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.

Basic nrf_crypto CLI concepts

Get familiar with the following concepts before using nrf_crypto CLI.

Variables

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:

show $some_var

Arguments

The following table shows different types of command arguments.

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.

Types of IN arguments
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.	show @Hello hash_calculate sha256 "@Hello World!!!" $out_digest
(	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"

Note

The Tab key can be used for hints and autocompletion of the IN arguments.
All the OUT and IN/OUT arguments expect a variable name, so they must start with a "$" character.

Printing of arguments

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:

ecc_key_pair_generate secp256r1 >$private $public

The OUT argument can be printed without saving it to a variable. Use a single "$" character without variable name:

rng_vector_generate 32 $

Converters

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.

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.

Example of converter usage

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.

ecdsa_sign (private_secp160k1)BCF2FB6D3186C6DAF98ABFD76A6F549149BB23A3 "(sha256)@Hello World!!!" $sig

The final result is the same as the result of the following set of commands:

ecc_private_key_from_raw secp160k1 BCF2FB6D3186C6DAF98ABFD76A6F549149BB23A3 $pk
hash_calculate sha256 "@Hello World!!!" $digest
ecdsa_sign $pk $digest $sig

Command overview

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.

Command details

This section contains detailed information about all available commands from the Command overview table, ordered alphabetically.

aead_decrypt

Calculates AEAD in one step.

aead_decrypt mode key nonce adata data_in mac_size mac data_out

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.

aead_encrypt

Calculates AEAD in one step.

aead_encrypt mode key nonce adata data_in mac_size mac data_out

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.

aes_crypt

Calculates AES in one step.

aes_crypt mode operation [padding] key [iv] data_in data_out

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.

aes_finalize

Finalizes AES.

aes_finalize context data_in [data_out]

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.

aes_init

Initializes AES context.

aes_init mode operation [padding] key [iv] 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.

aes_update

Updates AES with new data.

aes_update context data_in [data_out]

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.

append

Appends raw data to a raw variable.

append [data1 [data2 ...]] variable

IN	dataN	Multiple raw data arguments that are concatenated.
IN/OUT	variable	Variable where data is appended.

converters

Lists all defined converters.

converters

n/a

This command does not take arguments.

ecc_byte_order_invert

Inverts byte order of the raw ECC data.

ecc_byte_order_invert [curve] input output

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.

ecc_curves

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.

ecc_curves

n/a

This command does not take arguments.

ecc_key_pair_generate

Generates the ECC key pair.

ecc_key_pair_generate curve private_key public_key

IN	curve	Curve to use.
IN	private_key	Source private key.
OUT	public_key	Generated public key.

ecc_private_key_from_raw

Creates the ECC private key from raw data.

ecc_private_key_from_raw curve raw_data private_key

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.

ecc_private_key_to_raw

Gets raw data from the ECC private key.

ecc_private_key_to_raw private_key raw_data

IN	private_key	Key to convert.
OUT	raw_data	Raw representation of the key.

ecc_public_key_calculate

Generates the ECC public key from a private key.

ecc_public_key_calculate private_key public_key

IN	private_key	Source private key.
OUT	public_key	Generated public key.

ecc_public_key_from_raw

Creates the ECC public key from raw data.

ecc_public_key_from_raw curve raw_data public_key

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.

ecc_public_key_to_raw

Gets raw data from the ECC public key.

ecc_public_key_to_raw public_key raw_data

IN	public_key	Key to convert.
OUT	raw_data	Raw representation of the key.

ecdh_compute

Computes Elliptic-curve Diffie-Hellman shared secret.

ecdh_compute private_key public_key shared_secret

IN	private_key	Local private key.
IN	public_key	Remote public key.
OUT	shared_secret	Created shared secret.

ecdsa_sign

Signs a message with the ECC private key.

ecdsa_sign private_key hash signature

IN	private_key	Private key.
IN	hash	Hash of the message to sign.
OUT	signature	Signature to create.

ecdsa_verify

Verifies a hash with the ECC public key.

ecdsa_verify public_key hash signature

IN	public_key	Public key.
IN	hash	Hash of the message to verify.
IN	signature	Signature to check.

eddsa_sign

Signs a message with the ECC private key by using EdDSA.

ecdsa_sign private_key message signature

IN	private_key	Private key.
IN	message	Message to sign.
OUT	signature	Signature to create.

eddsa_verify

Verifies a hash with the ECC public key by using EdDSA.

ecdsa_verify public_key message signature

IN	public_key	Public key.
IN	message	Message to verify.
IN	signature	Signature to check.

format

Changes printing format of raw data.

format type

IN

type

Source raw data to cut.
The following values are allowed:

hex - raw hex format (default),
c - C source code,
cli - string that can be copy-pasted back to CLI.

hash_calculate

Calculates hash in one step.

hash_calculate hash_type data digest

IN	hash_type	Algorithm used to calculate hash (sha256 or sha512).
IN	data	Data input.
OUT	digest	Calculated digest.

hash_finalize

Finalizes hash calculation.

hash_finalize context digest

IN	context	Hash context to finalize.
OUT	digest	Calculated digest.

hash_init

Initializes hash context.

hash_init hash_type context

IN	hash_type	Algorithm used to calculate hash (sha256 or sha512).
OUT	context	Newly initialized context.

hash_update

Updates hash function with new data.

hash_update context data

IN	context	Hash context to update.
IN	data	Data input.

hkdf_calculate

Calculates HKDF.

hkdf_calculate hash_type mode input_key salt ainfo output_key_size output_key

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.

hmac_calculate

Calculates HMAC in one step.

hmac_calculate hash_type key data digest

IN	hmac_type	Algorithm used to calculate hmac (sha256 or sha512).
IN	key	Key data.
IN	data	Data input.
OUT	digest	Calculated digest.

hmac_finalize

Finalizes HAMC calculation.

hmac_finalize context digest

IN	context	HMAC context to finalize.
OUT	digest	Calculated digest.

hmac_init

Initializes HMAC context.

hmac_init hash_type key context

IN	hmac_type	Algorithm used to calculate HMAC (sha256 or sha512).
IN	key	Key data.
OUT	context	Newly initialized context.

hmac_update

Updates HMAC calculation with a new data.

hmac_update context data

IN	context	HMAC context to update.
IN	data	Data input.

ls

Lists all defined variables.

ls

n/a

This command does not take arguments.

mv

Renames a variable.

mv old_name new_name

IN	old_name	Name of the variable to rename.
IN	new_name	New name of the variable.

prepend

Prepends raw data to a raw variable.

prepend [data1 [data2 ...]] variable

IN	dataN	Multiple raw data arguments that are to be concatenated.
IN/OUT	variable	Variable where data is to be prepended.

raw

Creates variable with raw data.

raw [data1 [data2 ...]] output

IN	dataN	Multiple raw data arguments that are to be concatenated.
OUT	output	Newly created raw data.

rm

Removes a variable.

rm variable_name

IN

variable_name

Name of the variable to remove or "*" to delete all.

rng_reseed

Reseeds the generator.

rng_reseed [data]

IN

data

Seed data used to reseed.

rng_vector_generate

Generates a random vector.

rng_vector_generate size vector

IN	size	Requested size of the vector in bytes.
OUT	vector	Resulting data.

rng_vector_generate_in_range

Generates a random vector in specific range.

rng_vector_generate_in_range min max vector

IN	min	Minimum value.
IN	max	Maximum value.
OUT	vector	Resulting data.

show

Displays the contents of a variable.

show variable_name

IN

variable_name

Name of the variable to display.

sub

Creates variable from part of a raw data.

sub source start_index bytes_count output

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.

varmap

Prints full contents of the variable memory.

varmap

n/a

This command does not take arguments.

Testing

Test the nrf_crypto CLI Example application by performing the following steps:

Start a terminal emulator (PuTTY is recommended) with the following Terminal settings to establish the connection:
- Serial: for UART,
- Telnet, port 19021: for RTT transport.
  Note
  For establishing an RTT session, use JLink.exe. Do not use J-Link Viewer, as it does not support inline input and output like a terminal emulator.
Compile and program the application.
Wait for prompt nrf_crypto$.
Press the Tab key to check the list of commands.
Type some commands and check the results. For example:

rng_vector_generate 16 $

hash_calculate sha256 "@Hello World!!!" $hash

show $hash