The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs. More...

Data Structures
struct	mbedtls_ecdh_context
	The ECDH context structure. More...
Enumerations
enum	mbedtls_ecdh_side
	Defines the source of the imported EC key: More...
Functions
int	mbedtls_ecdh_gen_public (mbedtls_ecp_group grp, mbedtls_mpi d, mbedtls_ecp_point Q, int(f_rng)(void , unsigned char , size_t), void *p_rng)
	This function generates an ECDH keypair on an elliptic curve.
int	mbedtls_ecdh_compute_shared (mbedtls_ecp_group grp, mbedtls_mpi z, const mbedtls_ecp_point Q, const mbedtls_mpi d, int(f_rng)(void , unsigned char , size_t), void p_rng)
	This function computes the shared secret.
void	mbedtls_ecdh_init (mbedtls_ecdh_context *ctx)
	This function initializes an ECDH context.
void	mbedtls_ecdh_free (mbedtls_ecdh_context *ctx)
	This function frees a context.
int	mbedtls_ecdh_make_params (mbedtls_ecdh_context ctx, size_t olen, unsigned char buf, size_t blen, int(f_rng)(void , unsigned char , size_t), void *p_rng)
	This function generates a public key and a TLS ServerKeyExchange payload.
int	mbedtls_ecdh_read_params (mbedtls_ecdh_context ctx, const unsigned char buf, const unsigned char end)
	This function parses and processes a TLS ServerKeyExhange payload.
int	mbedtls_ecdh_get_params (mbedtls_ecdh_context ctx, const mbedtls_ecp_keypair key, mbedtls_ecdh_side side)
	This function sets up an ECDH context from an EC key.
int	mbedtls_ecdh_make_public (mbedtls_ecdh_context ctx, size_t olen, unsigned char buf, size_t blen, int(f_rng)(void , unsigned char , size_t), void *p_rng)
	This function generates a public key and a TLS ClientKeyExchange payload.
int	mbedtls_ecdh_read_public (mbedtls_ecdh_context ctx, const unsigned char buf, size_t blen)
	This function parses and processes a TLS ClientKeyExchange payload.
int	mbedtls_ecdh_calc_secret (mbedtls_ecdh_context ctx, size_t olen, unsigned char buf, size_t blen, int(f_rng)(void , unsigned char , size_t), void *p_rng)
	This function derives and exports the shared secret.

Detailed Description

The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs.

ECDH is an anonymous key agreement protocol allowing two parties to establish a shared secret over an insecure channel. Each party must have an elliptic-curve public–private key pair.

For more information, see NIST SP 800-56A Rev. 2: Recommendation for Pair-Wise Key Establishment Schemes Using Discrete Logarithm Cryptography.

Definition in file ecdh.h.

Enumeration Type Documentation

enum mbedtls_ecdh_side

Defines the source of the imported EC key:

Our key.
The key of the peer.

Definition at line 47 of file ecdh.h.

Function Documentation

int mbedtls_ecdh_calc_secret	(	mbedtls_ecdh_context *	ctx,
		size_t *	olen,
		unsigned char *	buf,
		size_t	blen,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

This function derives and exports the shared secret.

This is the last function used by both TLS client and servers.

Parameters:

ctx	The ECDH context.
olen	The number of Bytes written.
buf	The destination buffer.
blen	The length of the destination buffer.
f_rng	The RNG function.
p_rng	The RNG parameter.

Returns:: 0 on success, or an MBEDTLS_ERR_ECP_XXX error code on failure.

See also:: ecp.h

Note:: If f_rng is not NULL, it is used to implement countermeasures against potential elaborate timing attacks. For more information, see mbedtls_ecp_mul().

Definition at line 245 of file ecdh.c.

int mbedtls_ecdh_compute_shared	(	mbedtls_ecp_group *	grp,
		mbedtls_mpi *	z,
		const mbedtls_ecp_point *	Q,
		const mbedtls_mpi *	d,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

This function computes the shared secret.

This function performs the second of two core computations implemented during the ECDH key exchange. The first core computation is performed by mbedtls_ecdh_gen_public().

Parameters:

grp	The ECP group.
z	The destination MPI (shared secret).
Q	The public key from another party.
d	Our secret exponent (private key).
f_rng	The RNG function.
p_rng	The RNG parameter.

Returns:: 0 on success, or an MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.

See also:: ecp.h

Note:: If f_rng is not NULL, it is used to implement countermeasures against potential elaborate timing attacks. For more information, see mbedtls_ecp_mul().

Definition at line 57 of file ecdh.c.

void mbedtls_ecdh_free ( mbedtls_ecdh_context * ctx )

This function frees a context.

Parameters:

ctx	The context to free.

Definition at line 100 of file ecdh.c.

int mbedtls_ecdh_gen_public	(	mbedtls_ecp_group *	grp,
		mbedtls_mpi *	d,
		mbedtls_ecp_point *	Q,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

This function generates an ECDH keypair on an elliptic curve.

This function performs the first of two core computations implemented during the ECDH key exchange. The second core computation is performed by mbedtls_ecdh_compute_shared().

Parameters:

grp	The ECP group.
d	The destination MPI (private key).
Q	The destination point (public key).
f_rng	The RNG function.
p_rng	The RNG parameter.

Returns:: 0 on success, or an MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.

See also:: ecp.h

Definition at line 45 of file ecdh.c.

int mbedtls_ecdh_get_params	(	mbedtls_ecdh_context *	ctx,
		const mbedtls_ecp_keypair *	key,
		mbedtls_ecdh_side	side
	)

This function sets up an ECDH context from an EC key.

It is used by clients and servers in place of the ServerKeyEchange for static ECDH, and imports ECDH parameters from the EC key information of a certificate.

Parameters:

ctx The ECDH context to set up.

key The EC key to use.

side

Defines the source of the key:

1: Our key.
0: The key of the peer.

Returns:: 0 on success, or an MBEDTLS_ERR_ECP_XXX error code on failure.

See also:: ecp.h

Definition at line 177 of file ecdh.c.

void mbedtls_ecdh_init ( mbedtls_ecdh_context * ctx )

This function initializes an ECDH context.

Parameters:

ctx	The ECDH context to initialize.

Definition at line 92 of file ecdh.c.

int mbedtls_ecdh_make_params	(	mbedtls_ecdh_context *	ctx,
		size_t *	olen,
		unsigned char *	buf,
		size_t	blen,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

This function generates a public key and a TLS ServerKeyExchange payload.

This is the first function used by a TLS server for ECDHE ciphersuites.

Parameters:

ctx	The ECDH context.
olen	The number of characters written.
buf	The destination buffer.
blen	The length of the destination buffer.
f_rng	The RNG function.
p_rng	The RNG parameter.

Note:: This function assumes that the ECP group (grp) of the ctx context has already been properly set, for example, using mbedtls_ecp_group_load().

Returns:: 0 on success, or an MBEDTLS_ERR_ECP_XXX error code on failure.

See also:: ecp.h

Definition at line 122 of file ecdh.c.

int mbedtls_ecdh_make_public	(	mbedtls_ecdh_context *	ctx,
		size_t *	olen,
		unsigned char *	buf,
		size_t	blen,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

This function generates a public key and a TLS ClientKeyExchange payload.

This is the second function used by a TLS client for ECDH(E) ciphersuites.

Parameters:

ctx	The ECDH context.
olen	The number of Bytes written.
buf	The destination buffer.
blen	The size of the destination buffer.
f_rng	The RNG function.
p_rng	The RNG parameter.

Returns:: 0 on success, or an MBEDTLS_ERR_ECP_XXX error code on failure.

See also:: ecp.h

Definition at line 203 of file ecdh.c.

int mbedtls_ecdh_read_params	(	mbedtls_ecdh_context *	ctx,
		const unsigned char **	buf,
		const unsigned char *	end
	)

This function parses and processes a TLS ServerKeyExhange payload.

This is the first function used by a TLS client for ECDHE ciphersuites.

Parameters:

ctx	The ECDH context.
buf	The pointer to the start of the input buffer.
end	The address for one Byte past the end of the buffer.

Returns:: 0 on success, or an MBEDTLS_ERR_ECP_XXX error code on failure.

See also:: ecp.h

Definition at line 159 of file ecdh.c.

int mbedtls_ecdh_read_public	(	mbedtls_ecdh_context *	ctx,
		const unsigned char *	buf,
		size_t	blen
	)

This function parses and processes a TLS ClientKeyExchange payload.

This is the second function used by a TLS server for ECDH(E) ciphersuites.

Parameters:

ctx	The ECDH context.
buf	The start of the input buffer.
blen	The length of the input buffer.

Returns:: 0 on success, or an MBEDTLS_ERR_ECP_XXX error code on failure.

See also:: ecp.h

Definition at line 224 of file ecdh.c.

Type:	Program
Mbed OS support:	Mbed OS
Created:	29 Mar 2018
Imports:	22
Forks:	0
Commits:	5
Dependents:	0
Dependencies:	0
Followers:	6

Important changes to repositories hosted on mbed.com

ecdh.h File Reference

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

ecdh.h File Reference

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning