ECDH is a protocol that allows two parties to establish a shared secret over an insecure channel. Each party has a public-private key pair. The public key is sent from each party to the other one. The private key must be kept secret. A shared secret is data that is known only to the involved parties.

After the shared secret is calculated on both sides, it can be used to establish secure (encrypted) communication between the parties. See HKDF - HMAC-based Extract-and-Expand Key Derivation Function for more details on how to generate an encryption key from an ECDH shared secret.

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 Diffie-Hellman (ECDH).

API

The library provides one function nrf_crypto_ecdh_compute to perform ECDH. It computes the shared secret based on a local private key and a remote public key. See ECC - Elliptic Curve Cryptography for details on how to prepare those keys.

Shared secret output is a raw byte array containing big integer in big-endian byte order. One exception is Curve25519, which generates shared secret in little-endian byte order. NRF_CRYPTO_CURVE25519_BIG_ENDIAN_ENABLED option can be set 1 to change the endiannes of Curve25519. If you need to convert the shared secret to different endian format, use nrf_crypto_ecc_byte_order_invert.

The size of the output shared secret depends on used curve type. Array type nrf_crypto_ecdh_shared_secret_t is big enough to hold a shared secret from any of the enabled curve types. There are also curve-specific types, such as nrf_crypto_ecdh_secp256r1_shared_secret_t that can be used to reduce memory consumption. See Memory saving for more details.

Code example

nrf_crypto_ecdh_context_t ecdh_context;
nrf_crypto_ecc_private_key_t my_private_key;
nrf_crypto_ecc_public_key_t others_public_key;
nrf_crypto_ecdh_shared_secret_t shared_secret;
size_t shared_secret_size = sizeof(shared_secret);
// Not done here: Convert private/public keys from raw
// Calculates the ECDH shared secret
err_code = nrf_crypto_ecdh_compute(&ecdh_context, // Context
 &my_private_key, // Private key
 &others_public_key, // Public key
 shared_secret, // Shared secret
 &shared_secret_size); // Shared secret size
if (err_code == NRF_SUCCESS)
{
 // Do something with shared_secret array of size shared_secret_size
}

Backends

ECDH 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_ecdh_compute	✔	✔	✔	✔

ECDH Example

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

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