ECDH

Elliptic Curve Diffie-Hellman key agreement protocol. More...

Files
file	crypto_ecdh.h
	ECDH API.

Data Structures
struct	crypto_ecdh_context_t
	ECDH context. More...

Macros
#define	CRYPTO_ECDH_INIT_CTX(curve_init)   { {0}, {{0}, {0}}, {{0}, {0}}, {0}, curve_init, 0 }
	Initialize ECDH context. More...

Enumerations
enum	CRYPTO_ECDH_RET {   CRYPTO_ECDH_RET_OK = 0, CRYPTO_ECDH_RET_TO = 1, CRYPTO_ECDH_RET_EE = 2, CRYPTO_ECDH_RET_MP = 3,   CRYPTO_ECDH_RET_IP = 4, CRYPTO_ECDH_RET_ER = 5 }
	ECDH API return codes. More...
enum	crypto_ecdh_context_flags { CRYPTO_ECDH_CTX_d = 0x1, CRYPTO_ECDH_CTX_Ql = 0x2, CRYPTO_ECDH_CTX_Qp = 0x4, CRYPTO_ECDH_CTX_s = 0x8 }
	ECDH context flags type. More...

Functions
CRYPTO_ECDH_RET	crypto_ecdh_compute (crypto_ecdh_context_t *ctx, OS_TICK_TIME timeout)
	Generate Elliptic Curve Diffie-Hellman (ECDH) key pair. More...
CRYPTO_ECDH_RET	crypto_ecdh_init_context (crypto_ecdh_context_t *ctx, CRYPTO_ECC_CURVE curve_type)
	Initialize context for use with crypto_ecdh_compute. More...

Detailed Description

Elliptic Curve Diffie-Hellman key agreement protocol.

Macro Definition Documentation

CRYPTO_ECDH_INIT_CTX

#define CRYPTO_ECDH_INIT_CTX

(

curve_init

)

{ {0}, {{0}, {0}}, {{0}, {0}}, {0}, curve_init, 0 }

Initialize ECDH context.

Parameters

[in]

curve_init

The curve initilization macro. Details can be found in crypto curves documentation.

Enumeration Type Documentation

crypto_ecdh_context_flags

enum crypto_ecdh_context_flags

ECDH context flags type.

Enumerator
CRYPTO_ECDH_CTX_d	Private key is present in the context.
CRYPTO_ECDH_CTX_Ql	The local public key is present in the context.
CRYPTO_ECDH_CTX_Qp	The peer's public key is present in the context.
CRYPTO_ECDH_CTX_s	The shared secret is present in the context.

CRYPTO_ECDH_RET

enum CRYPTO_ECDH_RET

ECDH API return codes.

Enumerator
CRYPTO_ECDH_RET_OK	No error.
CRYPTO_ECDH_RET_TO	Operation timed out.
CRYPTO_ECDH_RET_EE	ECC operation error.
CRYPTO_ECDH_RET_MP	Missing peer public key.
CRYPTO_ECDH_RET_IP	Invalid peer public key.
CRYPTO_ECDH_RET_ER	Other error.

Function Documentation

crypto_ecdh_compute()

CRYPTO_ECDH_RET crypto_ecdh_compute	(	crypto_ecdh_context_t *	ctx,
		OS_TICK_TIME	timeout
	)

Generate Elliptic Curve Diffie-Hellman (ECDH) key pair.

This function implements the steps defined by the ECDH algorithm, depending on the input context contents. In more detail the steps are:

1. If the CRYPTO_ECDH_CTX_d flag is not set, the function will compute a private key, store it in the context and update the flag. This step invalidates any existing public key in the context.
2. If the CRYPTO_ECDH_CTX_Ql flag is not set or if a private key has been computed in the previous step, the function will compute a public key and update the flag.
3. If the CRYPTO_ECDH_CTX_Qp flag (peer's public key) is not set the function will return CRYPTO_ECDH_RET_MP. Otherwise it will check the peer's public key validity and if found valid it will calculate the shared secret and update the flag.

The resulting shared secret may be passed through a key-derivation function (KDF) to derive a symmetric key.

The following example shows how this function can be used to generate a public key and a shared secret based on the secp256r1 curve (NIST P-256).

// Create and initialize the ECDH context
crypto_ecdh_context_t c = CRYPTO_ECDH_INIT_CTX(CRYPTO_EC_PARAMS_SECP256R1);
 
// Generate public key
if (crypto_ecdh_compute(&c, 100) != CRYPTO_ECDH_RET_MP) {
     // handle error
}
 
// Exchange public keys (details of the exchange are out of scope for the example)
exchange_public_keys(c.Ql, c.Qp);
c.flags |= CRYPTO_ECDH_CTX_Qp;
 
// Generate shared secret
if (crypto_ecdh_compute(&c, 100) != CRYPTO_ECDH_RET_OK) {
     // handle error
}
 
// At this point c.s contains the shared secret and relevant flags are set

The next example shows how to generate a public key and a shared secret, if the peer's public key is available before calling this function. The example is based on Curve25519.

crypto_ecdh_context_t c = CRYPTO_ECDH_INIT_CTX(CRYPTO_EC_PARAMS_CURVE25519);
 
// Get peer's public key (details are out of scope for the example)
get_peer_public_key(c.Qp);
c.flags |= CRYPTO_ECDH_CTX_Qp;
 
// Generate public key and shared secret
if (crypto_ecdh_compute(&c, 100) != CRYPTO_ECDH_RET_OK) {
     // handle error
}
 
// At this point c.s contains the shared secret and Ql the local public key (relevant
// flags are also set). The public key can be sent to the peer (details are out of scope for the example)
send_public_key(c.Ql);

Parameters

[in,out]	ctx	The ECDH context where the result will be stored. It must be properly initialized with INIT_ECDH_CTX() and one of the supported curves .
[in]	timeout	Time in ticks to wait while trying to acquire hardware resources.

Returns

The function returns one of the return codes defined in CRYPTO_ECDH_RET.

crypto_ecdh_init_context()

CRYPTO_ECDH_RET crypto_ecdh_init_context	(	crypto_ecdh_context_t *	ctx,
		CRYPTO_ECC_CURVE	curve_type
	)

Initialize context for use with crypto_ecdh_compute.

Parameters

[in,out]	ctx	The ECDH context where the result will be stored. It must be properly initialized with INIT_ECDH_CTX() and one of the supported curves .
[in]	curve_type	Curve type to be used with the created ecdh context.

Returns

The function returns one of the return codes defined in CRYPTO_ECDH_RET.