When using ECDSA, a digital signature attests the authenticity of a set of data. It is calculated using a private key and a hash of the message. This process is called signing the message. The other party can check the signature using a hash of the message and a public key that corresponds to the private key used in the signing. This process is called verifying the message.

A valid signature indicates that:

the message comes from the owner of the private key,
the message was not altered after signing,
the owner of the private key cannot deny having sent the message.

From a technical point of view, a signature is a pair of big integers of size equal to the size of a private key used to generate the signature. Meaning of the integers depends on the selected digital signature scheme.

For information about public-private key management and general concepts regarding ECC, see ECC - Elliptic Curve Cryptography.

For detailed API documentation of this module, see Elliptic Curve Digital Signature (ECDSA).

API

The library provides two functions to perform ECDSA: nrf_crypto_ecdsa_sign and nrf_crypto_ecdsa_verify. Not all of these functions are implemented by the backends. See the table at Backends and nrf_crypto backend modules.

This library represents a signature as an array of bytes containing two big integers in big-endian order. Use nrf_crypto_ecc_byte_order_invert if little endian is required. Signature size depends on the curve type. Array type nrf_crypto_ecdsa_signature_t is big enough to hold a signature from any of the enabled curve types. There are also curve specific types, such as nrf_crypto_ecdsa_secp256r1_signature_t that can be used to reduce memory consumption. See Memory saving for more details.

Random number generator is required to perform signing in a secure way, see Dependencies.

Code examples

Signing a hash of the message:

nrf_crypto_ecdsa_sign_context_t sign_context;
nrf_crypto_ecc_private_key_t my_private_key;
nrf_crypto_ecdsa_signature_t signature;
size_t signature_size = sizeof(signature);
// ...
// Prepare my_private_key.
// ...
err_code = nrf_crypto_ecdsa_sign(&sign_context, // Context
 &my_private_key, // Private key
 p_hash, // Message hash
 hash_size, // Hash size
 signature, // signature
 &signature_size); // Signature size

Verifying a signature:

nrf_crypto_ecdsa_verify_context_t verify_context;
nrf_crypto_ecc_public_key_t some_public_key;
nrf_crypto_ecdsa_signature_t signature;
size_t signature_size = sizeof(signature);
// ...
// Prepare some_public_key.
// Receive signature and size_of_signature.
// ...
err_code = nrf_crypto_ecdsa_verify(&verify_context, // Context
 &some_public_key, // Public key
 p_hash, // Message hash
 hash_size, // Hash size
 signature, // Signature
 signature_size); // Signature size
if (err_code == NRF_SUCCESS)
{
 // Signature is valid
}
else if (err_code == NRF_ERROR_CRYPTO_ECDSA_INVALID_SIGNATURE)
{
 // Signature is invalid
}
else
{
 // Some error occurred during signature verification
}

Backends

ECDSA functionality depends on the selected backend. See Backends for more details about backends. Function availability is summarized in the table below:

API function	CC310 ¹	mbed TLS	Oberon ¹	µECC	CC310_BL
nrf_crypto_ecdsa_sign	✔	✔	✔	✔
nrf_crypto_ecdsa_verify	✔	✔	✔	✔	✔

¹ - Hash size can only be 160, 224, 256, 384, or 512-bit long.
² - Only hash of length 256 bit or longer.

Dependencies

RNG - Random Number Generator is required for nrf_crypto_ecdsa_sign. It must be correctly configured and initialized before calling the function.

RNG dependency does not apply to Experimental: Ed25519 – EdDSA using SHA-512 and Curve25519.

Experimental: Ed25519 – EdDSA using SHA-512 and Curve25519

Ed25519 is a version of EdDSA (Edwards-curve Digital Signature Algorithm) using SHA-512 and Curve25519. Curve25519 is not compatible with ECDSA, so a different digital signature scheme must be used for signing and verifying with Curve25519. Ed25519 is available using the same API as ECDSA, but it is not the same scheme.

Ed25519 is available in the API as a separate curve type. Variable g_nrf_crypto_ecc_ed25519_curve_info must be passed to key creation functions to use Ed25519.

Warning: You must provide a plain message as a parameter to Ed25519 sign and verify functions. Do not pass a hash of the message, as it is done in ECDSA.

Example of signing with Ed25519:

const uint8_t my_raw_private_key[32] = {
 0x23, 0x8F, 0x43, 0x88, ... // 32 bytes (256 bits) of raw private key
}
nrf_crypto_ecdsa_sign_context_t sign_context;
nrf_crypto_ecc_private_key_t my_private_key;
nrf_crypto_ecdsa_ed25519_signature_t signature;
size_t raw_key_size = sizeof(my_raw_private_key);
size_t signature_size = sizeof(signature);
// Convert raw key to backend type
err_code = nrf_crypto_ecc_private_key_from_raw(
 &g_nrf_crypto_ecc_ed25519_curve_info, // Info structure
 &my_private_key, // Private key
 my_raw_private_key, // Raw private key
 raw_key_size); // Raw key size
APP_ERROR_CHECK(err_code);
// Sign using Ed25519
err_code = nrf_crypto_ecdsa_sign(&sign_context, // Sign context
 &my_private_key, // Ed25519 private key
 "Hello World!", // String to sign
 strlen("Hello World!"),// Size of string to hash
 signature, // Signature
 &signature_size); // Signature hash

ECDH Example

See ECDSA Example for an example that shows the ECDSA procedure.

For an example showing the verification procedure of ECDSA, see Test Example.