diff --git a/source/mainnet/net/guides/company-identities.rst b/source/mainnet/net/guides/company-identities.rst index 453f15bf65..688e18f239 100644 --- a/source/mainnet/net/guides/company-identities.rst +++ b/source/mainnet/net/guides/company-identities.rst @@ -1,4 +1,6 @@ .. include:: ../../variables.rst +.. _IP address: https://en.wikipedia.org/wiki/IP_address +.. _port number: https://en.wikipedia.org/wiki/Port_(computer_networking) .. _company-identities: ============================ @@ -9,7 +11,10 @@ A company identity is for companies that need an identity and accounts on the Co You can't use the Desktop Wallet, |bw|, |mw-gen2|, or |mw-gen1| to create a company identity. You need to use a set of command-line tools, and you need to communicate directly with the identity provider (currently Notabene). `This page `_ describes Notabene's process, including recovery of company identities. -The information below describes how to create a company identity. Note that the process differs for testnet and mainnet. +The information below describes how to create a company identity, how to create accounts with a company identity, and how to recover a company identity. Note that the process differs for testnet and mainnet. + +Create an identity request +========================== .. dropdown:: Mainnet @@ -34,56 +39,218 @@ The information below describes how to create a company identity. Note that the - ``ip-info.json`` (public keys of the identity provider Notabene) + The ``user_cli`` tool supports three modes: the ``generate-request-v1`` mode, the ``create-credential-v1`` mode and ``recover-identity``. The ``generate-request-v1`` generates the request for the identity object that is to be sent to the identity provider. In the ``create-credential-v1`` mode the tool requires the identity object returned by the identity provider and generates a credential that can be sent to the chain to create an account. The ``recover-identity`` request generates an identity recovery request to be sent to the identity provider. + #. Download ``concordium-client`` for your platform. See :ref:`Downloads` to get the file and checksum. - #. To generate a request for an identity object, follow the `generate request instructions `__. Email the ``request.json`` output file to ania@notabene.id. Store the auxiliary output securely. + #. To generate a request for an identity object, use the following command: + + .. code-block:: console - #. To verify your identity towards Notabene, follow the `entity verification instructions `_. When the identity has been verified successfully, Notabene will notify you by email, and they will send you an identity object file named ``id-object.json``. + user_cli generate-request-v1 --cryptographic-parameters cryptographic-parameters.json --ars ars.json --ip-info ip-info.json --request-out request.json - #. To create additional accounts from the identity object returned by Notabene, follow the `create accounts instructions `__. You must deploy the credential.json output file to the chain exactly as described. If you don't, the account will not be created. You need access to a node to complete this step. Store the auxiliary output securely. + The above command will ask for some additional input. You have to choose anonymity revokers and revocation threshold. Use arrow keys to navigate through the lists and the space key to select and deselect list entries. Select whether the identity shall be used for Mainnet or Testnet. Afterwards, 24 BIP-39 will be generated and shown; write down the words and type them in again. This is your secret recovery phrase. - #. To recover your identity object (e.g. if you lost it), follow the `recovery of identity instructions `__. Email the ``recovery-request.json`` output file to ania@notabene.id. When the recovery request has been validated successfully, Notabene will notify you by email, and they will return the identity object named ``id-object.json`` that you lost. With the recovered identity object, you can then recreate your account keys, if needed. + The command outputs the ``request.json`` file which contains the request that should be sent to ania@notabene.id. Store the auxiliary output securely. - If you experience issues with steps 1, 2, 3, 4, 6 or 7, please contact Concordium’s technical support via support@concordium.software. If you experience issues with step 5, identity verification, please contact Notabene via ania@notabene.id. + #. To verify your identity towards Notabene, follow the `entity verification instructions `_. When the identity has been verified successfully, Notabene will notify you by email, and they will send you an identity object file named ``id-object.json``. If you experience any issues with this step, identity verification, please contact Notabene via ania@notabene.id. + + If you experience issues with steps 1, 2, 3, or 4 please contact Concordium’s technical support via support@concordium.software. .. dropdown:: Testnet #. Download the tools for your platform. - - `Tools for Linux `__ - - SHA256 checksum of the download: ``fd3620f3f3e2e9540b262ae68b8273c59816fbaa12d495629b07555c65bab4a2`` - - - `Tools for Windows `__ - - SHA256 checksum of the download: ``38433e51efa95121ee4e25a15552dd02905193e3de5d3976e4b067bd9cb46096`` + - `Tools for Linux `__ + - SHA256 checksum of the download: ``ad27147798583bc9c393af1ba554e005e3f0cb75137650ce3033452a20d32687`` - - `Tools for MacOS `__ - - SHA256 checksum of the download: ``6f457a05dc2f3345b48fd7d9d387e80b46d37ceaa6ebeadd759b6de4e634a4ca`` + - `Tools for Windows `__ + - SHA256 checksum of the download: ``45ee2d3a15fa44135ce43da2e8edd40b57b96a26c04d33e76498ac239a3afd1e`` - #. Download the testnet-specific `configuration files `__. + - `Tools for MacOS `__ + - SHA256 checksum of the download: ``917ea1889f1d758ecffa65c5abe138692bb4bf3f3d6f040031156b598d67cf3f`` #. Extract the files in the bundle to the same location on your computer. The bundle contains the following files: + - ``user_cli`` (tool) + - ``cryptographic-parameters-testnet.json`` - ``ars-testnet.json`` - ``ip-info-testnet.json`` (public keys of the identity provider) + The ``user_cli`` tool supports three modes: the ``generate-request-v1`` mode, the ``create-credential-v1`` mode and ``recover-identity``. The ``generate-request-v1`` generates the request for the identity object that is to be sent to the identity provider. In the ``create-credential-v1`` mode the tool requires the identity object returned by the identity provider and generates a credential that can be sent to the chain to create an account. The ``recover-identity`` request generates an identity recovery request to be sent to the identity provider. + #. Download ``concordium-client`` for your platform. See :ref:`Downloads` to get the file and checksum. - #. To generate a request for an identity object, follow the `generate request instructions `__. Email the ``request.json`` output file to support@concordium.software with the subject line "Test company identity". Store the auxiliary output securely. + #. To generate a request for an identity object, use the following command: + + .. code-block:: console + + user_cli generate-request-v1 --cryptographic-parameters cryptographic-parameters-testnet.json --ars ars-testnet.json --ip-info ip-info-testnet.json --request-out request.json + + The above command will ask for some additional input. You have to choose anonymity revokers and revocation threshold. Use arrow keys to navigate through the lists and the space key to select and deselect list entries. Select whether the identity shall be used for Mainnet or Testnet. Afterwards, 24 BIP-39 will be generated and shown; write down the words and type them in again. You need these when creating credentials. + + The command outputs the ``request.json`` file which contains the request that should be sent to the identity provider. + + #. Email the ``request.json`` output file to support@concordium.software with the subject line "Test company identity". The request should be sent to the identity provider through a trusted channel, together with any other required identity data. Store the auxiliary output securely. + + #. When the identity has been verified successfully, Concordium will notify you by email, and they will send you an identity object file named ``id-object.json``. Use this identity object file when creating accounts. + + If you experience issues, please contact Concordium’s technical support via support@concordium.software. + +Create accounts +=============== + +After obtaining the ``id-object.json`` identity object from the identity provider you can create additional accounts on the chain. Accounts are created by deploying credentials. The user_cli tool can only be used to create credentials. To deploy them to the chain, thus creating accounts, you need to use concordium-client and access to a node. + +.. dropdown:: Mainnet + + #. To create additional accounts from the identity object returned by Notabene, run the following command: + + .. code-block:: console + + user_cli create-credential-v1 --cryptographic-parameters cryptographic-parameters.json --ars ars.json --ip-info ip-info.json --id-object id-object.json --keys-out account-keys.json --credential-out credential.json + + You will have to select whether to reveal the LEI, which was optional when creating the identity object. Use the space key to select and deselect list entries. You will also be asked whether to create credential for Mainnet or Testnet. Afterwards you will be asked to type in the 24 BIP-39 words from earlier. + + The command outputs the following files: + + - ``account-keys.json`` which contains account keys of the account that will be created by the credential. + - ``credential.json`` which contains the payload of the account creation transaction. This must be sent to the chain, otherwise the account will not be created. By default this must be sent to the chain within 15 minutes. A larger or shorter message expiry may be set with --message-expiry flag to the command. Note that the credential number must be unique for each respective ``id-object.json``. Duplicate credential numbers for the same ``id-object.json`` will be rejected when submitting to chain. + + .. Note:: + + You must deploy the ``credential.json`` output file to the chain exactly as described below. If you don't, the account will not be created. You need access to a node to complete this step. Store the auxiliary output securely. + + 2. To create the account on the chain make sure you have access to a node, then run the following command with concordium-client: + + .. code-block:: console + + concordium-client transaction deploy-credential credential.json + + where ``credential.json`` is the file obtained in the previous step. If the node runs on a different machine or in a custom setup, the options ``--grpc-ip`` and ``--grpc-port`` can be used to set the `IP address`_ and `port number`_ where the node is accessible. + + If you experience issues, please contact Concordium’s technical support via support@concordium.software. + +.. dropdown:: Testnet + + #. To create additional accounts from the identity object returned by Concordium, run the following command: + + .. code-block:: console + + user_cli create-credential-v1 --cryptographic-parameters cryptographic-parameters-testnet.json --ars ars-testnet.json --ip-info ip-info-testnet.json --id-object id-object.json --keys-out account-keys.json --credential-out credential.json - #. When the identity has been verified successfully, Concordium will notify you by email, and they will send you an identity object file named ``id-object.json``. + You will have to select whether to reveal the LEI, which was optional when creating the identity object. Use the space key to select and deselect list entries. You will also be asked whether to create credential for Mainnet or Testnet. Afterwards you will be asked to type in the 24 BIP-39 words from earlier. - #. To create accounts from the identity object returned by Concordium, follow the `create accounts instructions `__. You must deploy the credential.json output file to the chain exactly as described. If you don't, the account will not be created. You need access to a node to complete this step. Store the auxiliary output securely. + The command outputs the following files: - #. To recover your identity object (e.g. if you lost it), follow the `recovery of identity instructions `__. Email the ``recovery-request.json`` output file to support@concordium.software with the subject line "Recover company identity". + - ``account-keys.json`` which contains account keys of the account that will be created by the credential. + - ``credential.json`` which contains the payload of the account creation transaction. This must be sent to the chain, otherwise the account will not be created. By default this must be sent to the chain within 15 minutes. A larger or shorter message expiry may be set with --message-expiry flag to the command. Note that the credential number must be unique for each respective ``id-object.json``. Duplicate credential numbers for the same ``id-object.json`` will be rejected when submitting to chain. - #. When the recovery request has been validated successfully, Concordium will notify you by email, and they will return the identity object named ``id-object.json`` that you lost. With the recovered identity object, you can then recreate your account keys, if needed. + .. Note:: + + You must deploy the ``credential.json`` output file to the chain exactly as described below. If you don't, the account will not be created. You need access to a node to complete this step. Store the auxiliary output securely. + + 2. To create the account on the chain make sure you have access to a node, then run the following command with ``concordium-client``: + + .. code-block:: console + + concordium-client transaction deploy-credential credential.json + + where ``credential.json`` is the file obtained in the previous step. If the node runs on a different machine or in a custom setup, the options ``--grpc-ip`` and ``--grpc-port`` can be used to set the `IP address`_ and `port number`_ where the node is accessible. Once you have created accounts, you can request CCDs for testing. To request CCDs for testing, run the following command: ``curl -X PUT https://wallet-proxy.testnet.concordium.com/v0/testnetGTUDrop/3GXM6cEuAwEA47EEtFpax9PLhMWchWmkaPmNZmW1kbDaWaKBxV`` where you replace 3GXM6cEuAwEA47EEtFpax9PLhMWchWmkaPmNZmW1kbDaWaKBxV with the account address that should receive the CCDs. If you experience issues, please contact Concordium’s technical support via support@concordium.software. + +Recovery +======== + +If the identity object used to create credentials is lost, it can be recovered from the identity provider by generating a recovery request using the 24 words used when the identity was originally created. Note that the process differs between mainnet and testnet. + +.. dropdown:: Mainnet + + #. To recover your identity object (e.g. if you lost it), run the following command: + + .. code-block:: console + + user_cli recover-identity --cryptographic-parameters cryptographic-parameters.json --ip-info ip-info.json --request-out recovery-request.json + + #. Email the ``recovery-request.json`` output file to ania@notabene.id. The request should be sent to the identity provider through a trusted channel, together with any other required identity data. When the recovery request has been validated successfully, Notabene will notify you by email, and they will return the identity object named ``id-object.json`` that you lost. With the recovered identity object, you can then recreate your account keys(account-keys.json) by running ``user_cli create-credential-v1``. + + If you experience issues, please contact Concordium’s technical support via support@concordium.software. + +.. dropdown:: Testnet + + #. To recover your identity object (e.g. if you lost it), run the following command: + + .. code-block:: console + + user_cli recover-identity --cryptographic-parameters cryptographic-parameters-testnet.json --ip-info ip-info-testnet.json --request-out recovery-request.json + + Email the ``recovery-request.json`` output file to support@concordium.software with the subject line "Recover company identity". + + #. When the recovery request has been validated successfully, Concordium will notify you by email, and they will return the identity object named ``id-object.json`` that you lost. With the recovered identity object, you can then recreate your account keys(account-keys.json) by running ``user_cli create-credential-v1``. + + If you experience issues, please contact Concordium’s technical support via support@concordium.software. + +Import created accounts into ``concordium-client`` +================================================== + +The account keys are primarily meant for clients to integrate into their key management solution and their software, e.g., an exchange integrating their trading platform with the Concordium chain. + +However if the ``account-keys.json`` file is not encrypted it can be imported into ``concordium-client`` with the command: + +.. code-block:: console + + concordium-client config account import account-keys.json --format=genesis --name my-account + +where the ``--name`` option is optional, and if given, will name the account according to the given value ("my-account" in the example above). + +If the account-keys.json file is encrypted then it must first be decrypted. This can be done with the :ref:`utils tool`. + +The initial account keys cannot be directly imported into ``concordium-client``. + +Format of the key files +----------------------- + +Both initial account keys and subsequent account keys are stored in JSON files. The unencrypted data is a JSON record with a number of fields. For sending transactions the fields that are relevant are: + +- ``accountKeys`` contains the account keys. It has the following format: + + .. code-block:: json + + "accountKeys": { + "keys": { + "0": { + "keys": { + "0": { + "signKey": "1e16c2e2302023fc5235c60734981a2427004f95b6ace50a1d8a205ee9e5f9e7", + "verifyKey": "7e9983b292cf5e5822b48dbed1c2d498aca97c097f7116511f7dcf6187d218c4" + } + }, + "threshold": 1 + } + }, + "threshold": 1 + } + + which contains the account keys. In this example the account has a single credential with index 0, and that credential has a single key with index 0. The private key is 1e16c2e2302023fc5235c60734981a2427004f95b6ace50a1d8a205ee9e5f9e7 and its public key is 7e9983b292cf5e5822b48dbed1c2d498aca97c097f7116511f7dcf6187d218c4. + +- ``address`` is the address of the account, e.g., + + .. code-block:: json + + "address": "2xe6cXEzBJZ8KXSYwb5uXJdHPZfAstbSZjfdAqsoF7VEq6q7AP" + +- keys for encrypted transfers. These are only needed for sending and receiving encrypted transfers. + + .. code-block:: json + + "encryptionPublicKey": "b14cbfe44a02c6b1f78711176d5f437295367aa4f2a8c2551ee10d25a03adc69d61a332a058971919dad7312e1fc94c58a2f44906bda77f42bc3503b53b604a851737829899ffd4895abc0184e2da448e673f5e87367991d4a453a7f562df974", + "encryptionSecretKey": "b14cbfe44a02c6b1f78711176d5f437295367aa4f2a8c2551ee10d25a03adc69d61a332a058971919dad7312e1fc94c557da780304fba3b831439243201396e8c83daa83da1acc385a7a28519011e6da" diff --git a/source/mainnet/net/references/concordium-client.rst b/source/mainnet/net/references/concordium-client.rst index f3424152a8..456a82afe0 100644 --- a/source/mainnet/net/references/concordium-client.rst +++ b/source/mainnet/net/references/concordium-client.rst @@ -17,7 +17,7 @@ The Concordium distribution ships with a CLI tool named ``concordium-client``. By default ``concordium-client`` performs its queries and sends transactions through a :ref:`local node`. If the node runs on a different machine or in a custom setup, the options ``--grpc-ip`` and ``--grpc-port`` can be used -to set the `IP address`_ and `port number`_ that the node is accessible at. These +to set the `IP address`_ and `port number`_ where the node is accessible. These flags are supported by all ``concordium-client`` commands. Note that as of version 5.1.1, the `port number`_ must be the port where the GRPC V2 interface is enabled, in contrast to previous versions which required the port number of the V1 API of the Concordium node.