Using the key Command Set

The `key` command set contains commands that operate on cryptographic secrets and nonces.

Generating Secrets and Nonces

Secrets and nonces both consist of a randomly generated sequence of bits. The only distinction made between a secret and a nonce is the uses that may be made of them. For example, a secret value must not be passed in clear text in any circumstances. The visual distinction between these uses afforded by UDF presentation aids application debugging and audit.

The `key nonce` command is used to generate a new random nonce value:

Alice> key nonce

The Base32 presentation of a nonce value will always begin with the letter N.

By default, a 128 bit nonce is generated but nonces of any length may be generated using the `/bits` option:

Alice> key nonce /bits=256

Secrets are generated in the same way using the command `key secret`:

Alice> key secret

The Base32 presentation of a secret value will always begin with the letter E. Again, any output length can be requested up to the platform limit:

Alice> key secret /bits=256

Generating EARL values

An Encrypted Authenticated Resource locator is a form of URI that specifies a means of locating and decrypting content stored on a remote Web service.

The EARL itself specifies a domain name and a secret. The content is stored on the Web Service under a label that is the Content Digest of the secret.

EARLs may be generated using the `key earl` command to generate a new secret/digest pair which are then used to process the content data:

Alice> key earl

Alternatively, the `dare earl` command may be used to perform both operations:

Alice> dare earl TestFile1.txt
ERROR - Unspecified error

Sharing and recovering secrets

Secret sharing splits a secret into a set of shares such that the original secret can be recovered from a chosen number of shares called the quorum.

The `key share` command creates a secret and splits it into the specified number of shares with the specified quorum for recovery. By default, a 128 bit secret is created and three shares are created with a quorum of two:

Alice> key share

The first UDF output is the secret key, followed by the key identifier two shares. The different outputs are easily distinguished by their first letter. As with every meshman command, the `/json` option may be used to obtain the result as a JSON structure:

Alice> key share /json
  "ResultKey": {
    "Success": true,
    "Shares": ["SAQO-6O6Z-A6YD-PMHO-TPUZ-ZLPQ-VSA7-K",

The original secret may be recovered from a sufficient number of shares to meet the quorum using the `key recover`:


As with secret generation, larger or smaller secrets may be created but due to a limitation in the implementation of the key sharing algorithm, the secret must be of length 512 bits or less and the number of bits is rounded up to the nearest multiple of 32 bits.

For example, we can create a 192 bit secret and share it five ways with a quorum of three:

Alice> key share /quorum=3 /shares=5

It is also possible to share a specified secret. This allows a secret to be shared multiple times creating independent key sets. If we re-share the secret created earlier to create three shares with a quorum of two, the shares will be different:

ERROR - Attempted to divide by zero.