nRF5 SDK v17.1.0

ECDH - Elliptic Curve Diffie–Hellman

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).

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.

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

}

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 | | | | |

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

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