dhm.h File Reference

This file contains Diffie-Hellman-Merkle (DHM) key exchange definitions and functions. More...

#include "mbedtls/config.h"
#include "mbedtls/bignum.h"

Go to the source code of this file.

Data Structures
struct	mbedtls_dhm_context
	The DHM context structure. More...

Macros
#define	MBEDTLS_ERR_DHM_BAD_INPUT_DATA   -0x3080
	Bad input parameters.
#define	MBEDTLS_ERR_DHM_READ_PARAMS_FAILED   -0x3100
	Reading of the DHM parameters failed.
#define	MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED   -0x3180
	Making of the DHM parameters failed.
#define	MBEDTLS_ERR_DHM_READ_PUBLIC_FAILED   -0x3200
	Reading of the public values failed.
#define	MBEDTLS_ERR_DHM_MAKE_PUBLIC_FAILED   -0x3280
	Making of the public value failed.
#define	MBEDTLS_ERR_DHM_CALC_SECRET_FAILED   -0x3300
	Calculation of the DHM secret failed.
#define	MBEDTLS_ERR_DHM_INVALID_FORMAT   -0x3380
	The ASN.1 data is not formatted correctly.
#define	MBEDTLS_ERR_DHM_ALLOC_FAILED   -0x3400
	Allocation of memory failed.
#define	MBEDTLS_ERR_DHM_FILE_IO_ERROR   -0x3480
	Read or write of file failed.
#define	MBEDTLS_ERR_DHM_HW_ACCEL_FAILED   -0x3500
	DHM hardware accelerator failed.
#define	MBEDTLS_ERR_DHM_SET_GROUP_FAILED   -0x3580
	Setting the modulus and generator failed.
#define	MBEDTLS_DHM_RFC5114_MODP_2048_P
	RFC 3526, RFC 5114 and RFC 7919 standardize a number of Diffie-Hellman groups, some of which are included here for use within the SSL/TLS module and the user's convenience when configuring the Diffie-Hellman parameters by hand through mbedtls_ssl_conf_dh_param.
#define	MBEDTLS_DHM_RFC5114_MODP_2048_G
	The hexadecimal presentation of the chosen generator of the 2048-bit MODP Group with 224-bit Prime Order Subgroup, as defined in RFC-5114: Additional Diffie-Hellman Groups for Use with IETF Standards.
#define	MBEDTLS_DHM_RFC3526_MODP_2048_P
	The hexadecimal presentation of the prime underlying the 2048-bit MODP Group, as defined in RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE).
#define	MBEDTLS_DHM_RFC3526_MODP_2048_G    MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )
	The hexadecimal presentation of the chosen generator of the 2048-bit MODP Group, as defined in RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE).
#define	MBEDTLS_DHM_RFC3526_MODP_3072_P
	The hexadecimal presentation of the prime underlying the 3072-bit MODP Group, as defined in RFC-3072: More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE).
#define	MBEDTLS_DHM_RFC3526_MODP_3072_G    MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )
	The hexadecimal presentation of the chosen generator of the 3072-bit MODP Group, as defined in RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE).
#define	MBEDTLS_DHM_RFC3526_MODP_4096_P
	The hexadecimal presentation of the prime underlying the 4096-bit MODP Group, as defined in RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE).
#define	MBEDTLS_DHM_RFC3526_MODP_4096_G    MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )
	The hexadecimal presentation of the chosen generator of the 4096-bit MODP Group, as defined in RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE).

Typedefs
typedef struct mbedtls_dhm_context	mbedtls_dhm_context
	The DHM context structure.

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 DHM parameters in a TLS ServerKeyExchange handshake message (DHM modulus, generator, and public key).
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 generates a DHM key pair and exports its public part together with the DHM parameters in the format used in a TLS ServerKeyExchange handshake message.
int	mbedtls_dhm_set_group (mbedtls_dhm_context *ctx, const mbedtls_mpi *P, const mbedtls_mpi *G)
	This function sets the prime modulus and generator.
int	mbedtls_dhm_read_public (mbedtls_dhm_context *ctx, const unsigned char *input, size_t ilen)
	This function imports the raw public value 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 a DHM key pair and exports the raw public key in big-endian format.
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 context.

Detailed Description

This file contains Diffie-Hellman-Merkle (DHM) key exchange definitions and functions.

Diffie-Hellman-Merkle (DHM) key exchange is defined in RFC-2631: Diffie-Hellman Key Agreement Method and Public-Key Cryptography Standards (PKCS) #3: Diffie Hellman Key Agreement Standard.

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.