Diffie-Hellman-Merkle key exchange. More...

Data Structures
struct	mbedtls_dhm_context
	The DHM context structure. More...
Functions
void	mbedtls_dhm_init (mbedtls_dhm_context *ctx)
	This function initializes the DHM context.
int	mbedtls_dhm_read_params (mbedtls_dhm_context ctx, unsigned char p, const unsigned char end)
	This function parses the ServerKeyExchange parameters.
int	mbedtls_dhm_make_params (mbedtls_dhm_context ctx, int x_size, unsigned char output, size_t olen, int(f_rng)(void , unsigned char , size_t), void *p_rng)
	This function sets up and writes the ServerKeyExchange parameters.
int	mbedtls_dhm_set_group (mbedtls_dhm_context ctx, const mbedtls_mpi P, const mbedtls_mpi *G)
	Set prime modulus and generator.
int	mbedtls_dhm_read_public (mbedtls_dhm_context ctx, const unsigned char input, size_t ilen)
	This function imports the public value G^Y of the peer.
int	mbedtls_dhm_make_public (mbedtls_dhm_context ctx, int x_size, unsigned char output, size_t olen, int(f_rng)(void , unsigned char , size_t), void p_rng)
	This function creates its own private value `X` and exports `G^X`.
int	mbedtls_dhm_calc_secret (mbedtls_dhm_context ctx, unsigned char output, size_t output_size, size_t olen, int(f_rng)(void , unsigned char , size_t), void *p_rng)
	This function derives and exports the shared secret (G^Y)^X mod `P`.
void	mbedtls_dhm_free (mbedtls_dhm_context *ctx)
	This function frees and clears the components of a DHM key.
int	mbedtls_dhm_parse_dhm (mbedtls_dhm_context dhm, const unsigned char dhmin, size_t dhminlen)
	This function parses DHM parameters in PEM or DER format.
int	mbedtls_dhm_parse_dhmfile (mbedtls_dhm_context dhm, const char path)
	This function loads and parses DHM parameters from a file.
int	mbedtls_dhm_self_test (int verbose)
	The DMH checkup routine.

Detailed Description

Diffie-Hellman-Merkle key exchange.

RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE) defines a number of standardized Diffie-Hellman groups for IKE.

RFC-5114: Additional Diffie-Hellman Groups for Use with IETF Standards defines a number of standardized Diffie-Hellman groups that can be used.

Warning:: The security of the DHM key exchange relies on the proper choice of prime modulus - optimally, it should be a safe prime. The usage of non-safe primes both decreases the difficulty of the underlying discrete logarithm problem and can lead to small subgroup attacks leaking private exponent bits when invalid public keys are used and not detected. This is especially relevant if the same DHM parameters are reused for multiple key exchanges as in static DHM, while the criticality of small-subgroup attacks is lower for ephemeral DHM.; For performance reasons, the code does neither perform primality nor safe primality tests, nor the expensive checks for invalid subgroups. Moreover, even if these were performed, non-standardized primes cannot be trusted because of the possibility of backdoors that can't be effectively checked for.; Diffie-Hellman-Merkle is therefore a security risk when not using standardized primes generated using a trustworthy ("nothing up my sleeve") method, such as the RFC 3526 / 7919 primes. In the TLS protocol, DH parameters need to be negotiated, so using the default primes systematically is not always an option. If possible, use Elliptic Curve Diffie-Hellman (ECDH), which has better performance, and for which the TLS protocol mandates the use of standard parameters.

Definition in file dhm.h.

Function Documentation

int mbedtls_dhm_calc_secret	(	mbedtls_dhm_context *	ctx,
		unsigned char *	output,
		size_t	output_size,
		size_t *	olen,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

This function derives and exports the shared secret (G^Y)^X mod P.

Parameters:

ctx	The DHM context.
output	The destination buffer.
output_size	The size of the destination buffer. Must be at least the size of ctx->len.
olen	On exit, holds the actual number of Bytes written.
f_rng	The RNG function, for blinding purposes.
p_rng	The RNG parameter.

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

Note:: If non-NULL, f_rng is used to blind the input as a countermeasure against timing attacks. Blinding is used only if our secret value X is re-used and omitted otherwise. Therefore, we recommend always passing a non-NULL f_rng argument.

Definition at line 379 of file dhm.c.

void mbedtls_dhm_free ( mbedtls_dhm_context * ctx )

This function frees and clears the components of a DHM key.

Parameters:

ctx	The DHM context to free and clear.

Definition at line 432 of file dhm.c.

void mbedtls_dhm_init ( mbedtls_dhm_context * ctx )

This function initializes the DHM context.

Parameters:

ctx	The DHM context to initialize.

Definition at line 125 of file dhm.c.

int mbedtls_dhm_make_params	(	mbedtls_dhm_context *	ctx,
		int	x_size,
		unsigned char *	output,
		size_t *	olen,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

This function sets up and writes the ServerKeyExchange parameters.

Parameters:

ctx	The DHM context.
x_size	The private value size in Bytes.
olen	The number of characters written.
output	The destination buffer.
f_rng	The RNG function.
p_rng	The RNG parameter.

Note:: The destination buffer must be large enough to hold the reduced binary presentation of the modulus, the generator and the public key, each wrapped with a 2-byte length field. It is the responsibility of the caller to ensure that enough space is available. Refer to mbedtls_mpi_size to computing the byte-size of an MPI.; This function assumes that ctx->P and ctx->G have already been properly set. For that, use mbedtls_dhm_set_group() below in conjunction with mbedtls_mpi_read_binary() and mbedtls_mpi_read_string().

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

Definition at line 155 of file dhm.c.

int mbedtls_dhm_make_public	(	mbedtls_dhm_context *	ctx,
		int	x_size,
		unsigned char *	output,
		size_t	olen,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

This function creates its own private value X and exports G^X.

Parameters:

ctx	The DHM context.
x_size	The private value size in Bytes.
output	The destination buffer.
olen	The length of the destination buffer. Must be at least equal to ctx->len (the size of `P`).
f_rng	The RNG function.
p_rng	The RNG parameter.

Note:: The destination buffer will always be fully written so as to contain a big-endian presentation of G^X mod P. If it is larger than ctx->len, it will accordingly be padded with zero-bytes in the beginning.

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

Definition at line 267 of file dhm.c.

int mbedtls_dhm_read_params	(	mbedtls_dhm_context *	ctx,
		unsigned char **	p,
		const unsigned char *	end
	)

This function parses the ServerKeyExchange parameters.

Parameters:

ctx	The DHM context.
p	On input, p must be the start of the input buffer. On output, p is updated to point to the end of the data that has been read. On success, this is the first byte past the end of the ServerKeyExchange parameters. On error, this is the point at which an error has been detected, which is usually not useful except to debug failures.
end	The end of the input buffer.

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

Definition at line 133 of file dhm.c.

int mbedtls_dhm_read_public	(	mbedtls_dhm_context *	ctx,
		const unsigned char *	input,
		size_t	ilen
	)

This function imports the public value G^Y of the peer.

Parameters:

ctx	The DHM context.
input	The input buffer.
ilen	The size of the input buffer.

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

Definition at line 250 of file dhm.c.

int mbedtls_dhm_self_test ( int verbose )

The DMH checkup routine.

Returns:: 0 on success, or 1 on failure.

Definition at line 631 of file dhm.c.

int mbedtls_dhm_set_group	(	mbedtls_dhm_context *	ctx,
		const mbedtls_mpi *	P,
		const mbedtls_mpi *	G
	)

Set prime modulus and generator.

Parameters:

ctx	The DHM context.
P	The MPI holding DHM prime modulus.
G	The MPI holding DHM generator.

Note:: This function can be used to set P, G in preparation for mbedtls_dhm_make_params.

Returns:: 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code on failure.

Definition at line 228 of file dhm.c.

Type:	Program
Mbed OS support:	Mbed OS
Created:	13 Apr 2018
Imports:	1
Forks:	0
Commits:	1
Dependents:	0
Dependencies:	1
Followers:	1

Important changes to repositories hosted on mbed.com

dhm.h File Reference

Data Structures

Functions

Detailed Description

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

dhm.h File Reference

Data Structures

Functions

Detailed Description

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning