diff --git a/source/mainnet/net/guides/company-identities.rst b/source/mainnet/net/guides/company-identities.rst index 6754add017..ab02ab69bd 100644 --- a/source/mainnet/net/guides/company-identities.rst +++ b/source/mainnet/net/guides/company-identities.rst @@ -9,202 +9,101 @@ Company identity creation A company identity is for companies that need an identity and accounts on the Concordium blockchain, but don't want that identity to belong to a specific person. Company identities are therefore issued with documents that identify the company and not an individual. Company identities are only relevant for a few companies, such as crypto exchanges. -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. +You can't use the Desktop Wallet, |bw|, |mw-gen2|, or |mw-gen1| to create a company identity. You need to use the Company identity management tool, 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, how to create accounts with a company identity, and how to recover 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. If you experience issues with the Concordium Company ID tool, please contact Concordium’s technical support via support@concordium.software. -Create an identity request -========================== +Using the company identity tool +=============================== -.. dropdown:: Mainnet +Once you have dowloaded the Concordium Company ID tool for your platform and installed it, you should choose your network, either Mainnet or Testnet. A default Concordium node URL is used, but you can enter your node URL, if desired. - #. Download the tools for your platform. +Request identity +---------------- - - `Tools for Linux `__ - - SHA256 checksum of the download: ``fd3620f3f3e2e9540b262ae68b8273c59816fbaa12d495629b07555c65bab4a2`` +#. Click **Request identity**. - - `Tools for Windows `__ - - SHA256 checksum of the download: ``38433e51efa95121ee4e25a15552dd02905193e3de5d3976e4b067bd9cb46096`` +#. Read the information and click **Proceed**. - - `Tools for MacOS `__ - - SHA256 checksum of the download: ``6f457a05dc2f3345b48fd7d9d387e80b46d37ceaa6ebeadd759b6de4e634a4ca`` +#. Write down or save your seedphrase by clicking the copy button to copy your seedphrase to the clipboard and remember to go to the clipboard and save the file. Keep your seedphrase secure as you will need it to create accounts or recover the identity. Click **Proceed**. - #. Extract the files in the bundle to the same location on your computer. The bundle contains the following files: +.. image:: ../images/company-id-request.png + :alt: company id tool screen showing identities related to seedphrase and option to select + :width: 50px - - ``user_cli`` (tool) +#. Enter your seedphrase to verify that you have recorded it correctly. Click **Proceed**. - - ``cryptographic-parameters.json`` +#. Click **Generate request.json**. The command outputs the ``request.json`` file. The request should be sent to the identity provider through a trusted channel. Store the auxiliary output securely. - - ``ars.json`` + - For **Mainnet** requests: Send the file to ania@notabene.id together with any other required identity data as described in the `entity verification instructions `_. - - ``ip-info.json`` (public keys of the identity provider Notabene) + - For **Testnet** requests: Send the file to support@concordium.software with the subject line "Test company identity". - 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. +When the identity has been verified successfully, you will receive an email with an identity object file named ``id-object.json``. Store this file securely as you need it to create accounts and regenerate account keys. - #. Download ``concordium-client`` for your platform. See :ref:`Downloads` to get the file and checksum. +Create account +-------------- - #. To generate a request for an identity object, use the following command: +After obtaining the ``id-object.json`` identity object from the identity provider you can create additional accounts on the chain. The Concordium Company ID 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. - .. code-block:: console +**Create account** can also be used to regenerate the keys for an old account. - user_cli generate-request-v1 --cryptographic-parameters cryptographic-parameters.json --ars ars.json --ip-info ip-info.json --request-out request.json +#. Click **Create Account**. - 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. +#. Enter your seedphrase in the Enter seedphrase field. In the Identity object file field click to navigate to the location of the stored ``id-object.json`` file. Click **Get Accounts**. - The command outputs the ``request.json`` file which contains the request that should be sent to ania@notabene.id. Store the auxiliary output securely. +.. image:: ../images/company-id-create-acct.png + :alt: company id tool screen showing seedphrase field and file selection box + :width: 50px - #. 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. +#. On the next screen, click **Create Account** to create an account with this company identity. When prompted, save the ``account-keys.json`` in a secure location as you will need them to interact with the accounts on-chain. You can click **Create account** again to create another account. - If you experience issues with steps 1, 2, 3, or 4 please contact Concordium’s technical support via support@concordium.software. +.. dropdown:: 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: -.. dropdown:: Testnet + - ``accountKeys`` contains the account keys. It has the following format: - #. Download the tools for your platform. + .. code-block:: json - - `Tools for Linux `__ - - SHA256 checksum of the download: ``2847d59ff2a0806f081b04a503644f16d8f799e6975f1c32e9e6ce4871c25c49`` - - - `Tools for Windows `__ - - SHA256 checksum of the download: ``208f2054b19fe8f90a2e2fbeb026e34a496e0353c596e2c422f082ca881e32dc`` - - - `Tools for MacOS `__ - - SHA256 checksum of the download: ``d2d514e85b495fc4a25dbe349174e94a933f0447986cd502e8f17d7e7426e263`` - - #. 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, 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 - - 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. - - 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. + "accountKeys": { + "keys": { + "0": { + "keys": { + "0": { + "signKey": "1e16c2e2302023fc5235c60734981a2427004f95b6ace50a1d8a205ee9e5f9e7", + "verifyKey": "7e9983b292cf5e5822b48dbed1c2d498aca97c097f7116511f7dcf6187d218c4" + } + }, + "threshold": 1 + } + }, + "threshold": 1 + } -.. dropdown:: Testnet + 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. - #. To recover your identity object (e.g. if you lost it), run the following command: + - ``address`` is the address of the account, e.g., - .. code-block:: console + .. code-block:: json - user_cli recover-identity --cryptographic-parameters cryptographic-parameters-testnet.json --ip-info ip-info-testnet.json --request-out recovery-request.json + "address": "2xe6cXEzBJZ8KXSYwb5uXJdHPZfAstbSZjfdAqsoF7VEq6q7AP" - Email the ``recovery-request.json`` output file to support@concordium.software with the subject line "Recover company identity". + - keys for encrypted transfers. These are only needed for sending and receiving encrypted transfers. - #. 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``. + .. code-block:: json - If you experience issues, please contact Concordium’s technical support via support@concordium.software. + "encryptionPublicKey": "b14cbfe44a02c6b1f78711176d5f437295367aa4f2a8c2551ee10d25a03adc69d61a332a058971919dad7312e1fc94c58a2f44906bda77f42bc3503b53b604a851737829899ffd4895abc0184e2da448e673f5e87367991d4a453a7f562df974", + "encryptionSecretKey": "b14cbfe44a02c6b1f78711176d5f437295367aa4f2a8c2551ee10d25a03adc69d61a332a058971919dad7312e1fc94c557da780304fba3b831439243201396e8c83daa83da1acc385a7a28519011e6da" Import created accounts into ``concordium-client`` -================================================== +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To use the accounts created in the Concordium Company ID tool, you must use Concordium Client. You can download it :ref:`here`. For information about how to use it, see :ref:`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: +However, if the ``account-keys.json`` file is not encrypted it can be imported into ``concordium-client`` with the command: .. code-block:: console @@ -216,41 +115,27 @@ If the account-keys.json file is encrypted then it must first be decrypted. This The initial account keys cannot be directly imported into ``concordium-client``. -Format of the key files ------------------------ +Once you have created accounts, you can request CCDs for testing. To request CCDs for testing, run the following command: -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: +``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. -- ``accountKeys`` contains the account keys. It has the following format: +Identity recovery +----------------- - .. code-block:: json - - "accountKeys": { - "keys": { - "0": { - "keys": { - "0": { - "signKey": "1e16c2e2302023fc5235c60734981a2427004f95b6ace50a1d8a205ee9e5f9e7", - "verifyKey": "7e9983b292cf5e5822b48dbed1c2d498aca97c097f7116511f7dcf6187d218c4" - } - }, - "threshold": 1 - } - }, - "threshold": 1 - } +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. Recover identity generates an identity recovery request to be sent to the identity provider. - 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. +#. Click **Identity Recovery**. -- ``address`` is the address of the account, e.g., +#. Enter your seedphrase in the Enter seedphrase field. And click **Find identities**. - .. code-block:: json +#. You see a list of identities associated with the seedphrase. In the Identities to recover drop-down, select the identity you want to recover. Click **Generate recovery request**. The command outputs the ``recovery-request.json`` file. The request should be sent to the identity provider through a trusted channel. Store the auxiliary output securely. - "address": "2xe6cXEzBJZ8KXSYwb5uXJdHPZfAstbSZjfdAqsoF7VEq6q7AP" +.. image:: ../images/company-id-recover.png + :alt: company id tool screen showing identities related to seedphrase and option to select + :width: 50px -- keys for encrypted transfers. These are only needed for sending and receiving encrypted transfers. +- For Mainnet requests: Send the file to ania@notabene.id together with any other required identity data as described in the `entity verification instructions `_. - .. code-block:: json +- For Testnet requests: Send the file to support@concordium.software with the subject line "Recover company identity". - "encryptionPublicKey": "b14cbfe44a02c6b1f78711176d5f437295367aa4f2a8c2551ee10d25a03adc69d61a332a058971919dad7312e1fc94c58a2f44906bda77f42bc3503b53b604a851737829899ffd4895abc0184e2da448e673f5e87367991d4a453a7f562df974", - "encryptionSecretKey": "b14cbfe44a02c6b1f78711176d5f437295367aa4f2a8c2551ee10d25a03adc69d61a332a058971919dad7312e1fc94c557da780304fba3b831439243201396e8c83daa83da1acc385a7a28519011e6da" +When the recovery request has been verified successfully, you will receive an email with the identity object file named ``id-object.json`` that you lost. Store this file securely as you need it to create accounts and regenerate account keys. diff --git a/source/mainnet/net/images/company-id-create-acct.png b/source/mainnet/net/images/company-id-create-acct.png new file mode 100644 index 0000000000..827ad6e635 Binary files /dev/null and b/source/mainnet/net/images/company-id-create-acct.png differ diff --git a/source/mainnet/net/images/company-id-recover.png b/source/mainnet/net/images/company-id-recover.png new file mode 100644 index 0000000000..1f3f478935 Binary files /dev/null and b/source/mainnet/net/images/company-id-recover.png differ diff --git a/source/mainnet/net/images/company-id-request.png b/source/mainnet/net/images/company-id-request.png new file mode 100644 index 0000000000..9441382c56 Binary files /dev/null and b/source/mainnet/net/images/company-id-request.png differ diff --git a/source/mainnet/net/installation/downloads.rst b/source/mainnet/net/installation/downloads.rst index b50c9aed2e..10154f7010 100644 --- a/source/mainnet/net/installation/downloads.rst +++ b/source/mainnet/net/installation/downloads.rst @@ -299,7 +299,7 @@ Download the block separately to inspect it or to run a node in a custom configu Auxiliary tools =============== -Auxiliary tools are a collection of tools that can be used by developers to perform actions as needed. +Auxiliary tools are a collection of tools that can be used to perform actions as needed. Encrypt/decrypt tool v1.0.0 --------------------------- @@ -312,6 +312,19 @@ Encrypt/decrypt tool v1.0.0 For information about how to use the encrypt/decrypt tool, see :ref:`Auxiliary tools `. +Company identity management tool v0.1.0 +--------------------------------------- + +Use this tool to create a company identity, request accounts using a company identity, and recover a company identity. + +- `Download the Company identity management tool for Linux `_ + +- `Download the Company identity management tool for Windows `_ + +- `Download the Company identity management tool for MacOS `_ + +For information about how to use the company identity management tool, see XXX. + .. toctree:: :hidden: :maxdepth: 1