The command line interface (CLI) example for nrf_crypto exposes the nrf_crypto library API as simple CLI commands. Use it to get familiar with the nrf_crypto functionality, and to do some one-time tasks like key generation or testing nrf_crypto functions.
Get familiar with the following concepts before using nrf_crypto CLI.
Variables are used to share data between commands. Variable is a memory block that contains some data. Its name starts with the "$" character, followed by the variable type.
There is one basic variable type called raw that is a simple byte buffer. There are also types intended for specific tasks, for example the AES context.
Variable can be used as parameter. For example, the following command shows information about variable $some_var
:
The following table shows different types of command arguments.
Argument | Description |
---|---|
IN | Data passed by this argument is read-only and does not change. Some IN arguments expect a literal value, such as key size or cipher mode. Others can use variables. |
OUT | Command creates a new variable and puts some content into it. If a variable with the same name already exists, it is overridden. |
IN/OUT | Variable passed by this argument will be changed. |
You can pass different types of IN arguments depending on the first character.
First character | Description | Example |
---|---|---|
$ | Variable from which the command is to take data. | rng_reseed $random_data |
@ | This is an ASCII string. All characters following "@" are converted into a temporary raw-type variable that contains the string. A string argument that contains spaces must be enclosed within quotes. |
|
( | Argument is converted before it is passed to the command. For details, see Converters. | See Example of converter usage. |
Any other | Arguments are treated as hex data. Hex string is converted into a temporary raw-type variable. Conversion is flexible and allows different formats of input. You can use both lower-case and upper-case hex characters. Hex characters can be grouped with any non-alphanumeric separator (such as spaces, commas, colons, dashes). You can add an optional "0x" prefix to the group. | ecc_private_key_from_raw secp160k1 BCF2FB6D3186C6DAF98ABFD76A6F549149BB23A3 $pk aes_init ecb encrypt 4a:44:22:4c:df:97:79:38:a0:cd:d0:5a:da:89:5c:db $ctx show "0x48 0x65 0x6C 0x6C 0x6F 0x57 0x6F 0x72 0x6C 0x64" |
The OUT and IN/OUT arguments are printed after the execution of command. You can disable printing of specific output with a ">" character prefix. For example, the following command only prints a public key, and not a private one:
The OUT argument can be printed without saving it to a variable. Use a single "$" character without variable name:
Before passing data to a command, the data can be converted. Converters allow to perform some operations in a single step instead of using multiple commands.
The IN argument can be prefixed by "(converter_name)", where converter_name is the name of a specific converter. The converter takes the data after this prefix and creates a new temporary variable with the converted data.
The following table shows the defined converters.
Converter | Description |
---|---|
raw | Converts ECC public or private key to raw representation. |
sha256 | Calculates hash digest from the input. |
sha512 | Calculates hash digest from the input. |
public_curve_name | Creates public key for a specific curve_name. |
private_curve_name | Creates private key for a specific curve_name. |
For the list of all available converters, use the converters
command or see the converters section.
The following command does the ECDSA signing in one step. The first argument is converted from a raw hex representation into a secp160k1 private key. The second argument is hashed using SHA-256. After both conversions are done, the ecdsa_sign command is executed with the converted values.
The final result is the same as the result of the following set of commands:
The following table lists all available commands, starting from the general ones. For detailed information about each command, see Command details.
Commands for handling variables | |
ls | Lists all defined variables. |
rm | Removes a variable. |
mv | Renames a variable. |
show | Shows the contents of a variable. |
varmap | Prints full contents of the variable memory. |
converters | Lists all defined converters. |
Commands for raw-type variables | |
raw | Creates a variable with raw data. |
prepend | Prepends raw data to a raw variable. |
append | Appends raw data to a raw variable. |
sub | Creates a variable from a part of the raw data. |
format | Changes printing format of the raw data. |
Commands for RNG | |
rng_vector_generate | Generates a random vector. |
rng_vector_generate_in_range | Generates a random vector in specific range. |
rng_reseed | Reseeds the generator. |
Commands for HASH | |
hash_init | Initializes the hash context. |
hash_update | Updates a hash function with new data. |
hash_finalize | Finalizes the hash calculation. |
hash_calculate | Calculates the hash in one step. |
Commands for HMAC | |
hmac_init | Initializes the HMAC context. |
hmac_update | Updates the HMAC calculation with new data. |
hmac_finalize | Finalizes the HAMC calculation. |
hmac_calculate | Calculates HMAC in one step. |
Commands for HKDF | |
hkdf_calculate | Calculates HKDF. |
Commands for AES | |
aes_init | Initializes the AES context. |
aes_update | Updates AES with new data. |
aes_finalize | Finalizes AES. |
aes_crypt | Calculates AES in one step. |
Commands for AEAD | |
aead_encrypt | Calculates AEAD in one step. |
aead_decrypt | Calculates AEAD in one step. |
Commands for all ECC | |
ecc_key_pair_generate | Generates an ECC key pair. |
ecc_public_key_calculate | Generates an ECC public key from private key. |
ecc_public_key_from_raw | Creates an ECC public key from raw data. |
ecc_public_key_to_raw | Gets raw data from the ECC public key. |
ecc_private_key_to_raw | Gets raw data from the ECC private key. |
ecc_private_key_from_raw | Creates an ECC private key from raw data. |
ecc_curves | Shows all available ECC curve types. |
ecc_byte_order_invert | Inverts byte order of raw ECC data. |
Commands for ECDH | |
ecdh_compute | Computes Elliptic-curve Diffie-Hellman shared secret. |
Commands for ECDSA | |
ecdsa_sign | Signs a message with the ECC private key. |
ecdsa_verify | Verifies a hash with the ECC public key. |
Commands for EdDSA | |
eddsa_sign | Signs a message with the ECC private key by using EdDSA. |
eddsa_verify | Verifies a hash with the ECC public key by using EdDSA. |
This section contains detailed information about all available commands from the Command overview table, ordered alphabetically.
Calculates AEAD in one step.
IN | mode | AES block cipher mode (ccm, ccm*, eax, gcm, chacha-poly). |
IN | key | AES key (must be 128, 192, or 256 bit long). |
IN | nonce | Nonce. |
IN | adata | Additional authenticated data. |
IN | data_in | Data to process. |
IN | mac | MAC to check. |
OUT | data_out | Resulting data. |
Calculates AEAD in one step.
IN | mode | AES block cipher mode (ccm, ccm*, eax, gcm, chacha-poly). |
IN | key | AES key (must be 128, 192, or 256 bit long). |
IN | nonce | Nonce. |
IN | adata | Additional authenticated data. |
IN | data_in | Data to process. |
IN | mac_size | Expected size of the MAC. |
OUT | mac | Resulting MAC. |
OUT | data_out | Resulting data. |
Calculates AES in one step.
IN | mode | AES block cipher mode (cbc, cbc-mac, cfb, cmac, ctr, ecb). |
IN | operation | Operation to perform (encrypt, decrypt, mac). |
IN | padding | Optional padding algorithm (pkcs7 or none). |
IN | key | AES key (must be 128, 192, or 256 bit long). |
IN | iv | Optional initialization vector. |
IN | data_in | Data to process. |
OUT | data_out | Resulting data. |
Finalizes AES.
IN | context | AES context. |
IN | data_in | Last part of input data. |
IN/OUT | data_out | Optional result data of the finalization. If it is not present, the data is discarded. If it is an existing raw variable, the data is appended. If it is a non-existing variable, it is created. |
Initializes AES context.
IN | mode | AES block cipher mode (cbc, cbc-mac, cfb, cmac, ctr, ecb). |
IN | operation | Operation to perform (encrypt, decrypt, mac). |
IN | padding | Optional padding algorithm (pkcs7 or none). |
IN | key | AES key (must be 128, 192, or 256 bit long). |
IN | iv | Optional initialization vector. |
OUT | context | Newly initialized context. |
Updates AES with new data.
IN | context | AES context. |
IN | data_in | Input data. For all modes except CFB, it must be a multiple of 16 bytes. |
IN/OUT | data_out | Optional result data of the finalization. If it is not present, the data is discarded. If it is an existing raw variable, the data is appended. If it is a non-existing variable, it is created. |
Appends raw data to a raw variable.
IN | dataN | Multiple raw data arguments that are concatenated. |
IN/OUT | variable | Variable where data is appended. |
Lists all defined converters.
n/a | This command does not take arguments. |
Inverts byte order of the raw ECC data.
IN | curve | Optional curve that defines how to invert fields. If it is skipped, all bytes are inverted. |
IN | input | Source raw data. |
OUT | output | Raw data containing inverted byte order. |
Lists all available ECC curve types. The content of the list are the aliases for the specific curve types. The most common alias is secp256r1.
n/a | This command does not take arguments. |
Generates the ECC key pair.
IN | curve | Curve to use. |
IN | private_key | Source private key. |
OUT | public_key | Generated public key. |
Creates the ECC private key from raw data.
IN | curve | Curve name. Use the ecc_curves command to list all supported curves. |
IN | raw_data | Raw representation of the key. |
OUT | private_key | Converted key. |
Gets raw data from the ECC private key.
IN | private_key | Key to convert. |
OUT | raw_data | Raw representation of the key. |
Generates the ECC public key from a private key.
IN | private_key | Source private key. |
OUT | public_key | Generated public key. |
Creates the ECC public key from raw data.
IN | curve | Curve name. Use the ecc_curves command to list all supported curves. |
IN | raw_data | Raw representation of the key. |
OUT | public_key | Converted key. |
Gets raw data from the ECC public key.
IN | public_key | Key to convert. |
OUT | raw_data | Raw representation of the key. |
Computes Elliptic-curve Diffie-Hellman shared secret.
IN | private_key | Local private key. |
IN | public_key | Remote public key. |
OUT | shared_secret | Created shared secret. |
Signs a message with the ECC private key.
IN | private_key | Private key. |
IN | hash | Hash of the message to sign. |
OUT | signature | Signature to create. |
Verifies a hash with the ECC public key.
IN | public_key | Public key. |
IN | hash | Hash of the message to verify. |
IN | signature | Signature to check. |
Signs a message with the ECC private key by using EdDSA.
IN | private_key | Private key. |
IN | message | Message to sign. |
OUT | signature | Signature to create. |
Verifies a hash with the ECC public key by using EdDSA.
IN | public_key | Public key. |
IN | message | Message to verify. |
IN | signature | Signature to check. |
Changes printing format of raw data.
IN | type | Source raw data to cut. The following values are allowed:
|
Calculates hash in one step.
IN | hash_type | Algorithm used to calculate hash (sha256 or sha512). |
IN | data | Data input. |
OUT | digest | Calculated digest. |
Finalizes hash calculation.
IN | context | Hash context to finalize. |
OUT | digest | Calculated digest. |
Initializes hash context.
IN | hash_type | Algorithm used to calculate hash (sha256 or sha512). |
OUT | context | Newly initialized context. |
Updates hash function with new data.
IN | context | Hash context to update. |
IN | data | Data input. |
Calculates HKDF.
IN | hmac_type | Algorithm used to calculate HKDF (sha256 or sha512). |
IN | mode | HKDF mode (normal or expand_only). |
IN | input_key | Key. |
IN | salt | Salt data or "-". |
IN | ainfo | Application specific information or "-". |
IN | key_size | Output key size in bytes, or bits, if a "bit" postfix is added. |
OUT | key | Calculated key. |
Calculates HMAC in one step.
IN | hmac_type | Algorithm used to calculate hmac (sha256 or sha512). |
IN | key | Key data. |
IN | data | Data input. |
OUT | digest | Calculated digest. |
Finalizes HAMC calculation.
IN | context | HMAC context to finalize. |
OUT | digest | Calculated digest. |
Initializes HMAC context.
IN | hmac_type | Algorithm used to calculate HMAC (sha256 or sha512). |
IN | key | Key data. |
OUT | context | Newly initialized context. |
Updates HMAC calculation with a new data.
IN | context | HMAC context to update. |
IN | data | Data input. |
Lists all defined variables.
n/a | This command does not take arguments. |
Renames a variable.
IN | old_name | Name of the variable to rename. |
IN | new_name | New name of the variable. |
Prepends raw data to a raw variable.
IN | dataN | Multiple raw data arguments that are to be concatenated. |
IN/OUT | variable | Variable where data is to be prepended. |
Creates variable with raw data.
IN | dataN | Multiple raw data arguments that are to be concatenated. |
OUT | output | Newly created raw data. |
Removes a variable.
IN | variable_name | Name of the variable to remove or "*" to delete all. |
Reseeds the generator.
IN | data | Seed data used to reseed. |
Generates a random vector.
IN | size | Requested size of the vector in bytes. |
OUT | vector | Resulting data. |
Generates a random vector in specific range.
IN | min | Minimum value. |
IN | max | Maximum value. |
OUT | vector | Resulting data. |
Displays the contents of a variable.
IN | variable_name | Name of the variable to display. |
Creates variable from part of a raw data.
IN | source | Source raw data to cut. |
IN | start_index | Index of byte in the source where cutting starts. Negative value starts the count from the end of data. |
IN | bytes_count | Number of bytes to cut. Negative value indicate where cutting ends, counting from the end of data. Value "-" cuts to the end. |
OUT | output | Variable where portion of the source is to be placed. |
Prints full contents of the variable memory.
n/a | This command does not take arguments. |
Test the nrf_crypto CLI Example application by performing the following steps:
JLink.exe
. Do not use J-Link Viewer, as it does not support inline input and output like a terminal emulator.nrf_crypto$
.