This file contains Diffie-Hellman-Merkle (DHM) key exchange definitions and functions.
More...
|
void | mbedtls_dhm_init (mbedtls_dhm_context *ctx) |
| This function initializes the DHM context. More...
|
|
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). More...
|
|
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. More...
|
|
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. More...
|
|
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. More...
|
|
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. More...
|
|
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 . More...
|
|
size_t | mbedtls_dhm_get_bitlen (const mbedtls_dhm_context *ctx) |
| This function returns the size of the prime modulus in bits. More...
|
|
size_t | mbedtls_dhm_get_len (const mbedtls_dhm_context *ctx) |
| This function returns the size of the prime modulus in bytes. More...
|
|
int | mbedtls_dhm_get_value (const mbedtls_dhm_context *ctx, mbedtls_dhm_parameter param, mbedtls_mpi *dest) |
| This function copies a parameter of a DHM key. More...
|
|
void | mbedtls_dhm_free (mbedtls_dhm_context *ctx) |
| This function frees and clears the components of a DHM context. More...
|
|
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. More...
|
|
int | mbedtls_dhm_parse_dhmfile (mbedtls_dhm_context *dhm, const char *path) |
| This function loads and parses DHM parameters from a file. More...
|
|
int | mbedtls_dhm_self_test (int verbose) |
| The DMH checkup routine. More...
|
|
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.
#define MBEDTLS_DHM_RFC3526_MODP_2048_P_BIN |
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
.
The following lists the source of the above groups in the standards:
- RFC 5114 section 2.2: 2048-bit MODP Group with 224-bit Prime Order Subgroup
- RFC 3526 section 3: 2048-bit MODP Group
- RFC 3526 section 4: 3072-bit MODP Group
- RFC 3526 section 5: 4096-bit MODP Group
- RFC 7919 section A.1: ffdhe2048
- RFC 7919 section A.2: ffdhe3072
- RFC 7919 section A.3: ffdhe4096
- RFC 7919 section A.4: ffdhe6144
- RFC 7919 section A.5: ffdhe8192
The constants with suffix "_p" denote the chosen prime moduli, while the constants with suffix "_g" denote the chosen generator of the associated prime field.
The constants further suffixed with "_bin" are provided in binary format, while all other constants represent null-terminated strings holding the hexadecimal presentation of the respective numbers.
The primes from RFC 3526 and RFC 7919 have been generating by the following trust-worthy procedure:
- Fix N in { 2048, 3072, 4096, 6144, 8192 } and consider the N-bit number the first and last 64 bits are all 1, and the remaining N - 128 bits of which are 0x7ff...ff.
- Add the smallest multiple of the first N - 129 bits of the binary expansion of pi (for RFC 5236) or e (for RFC 7919) to this intermediate bit-string such that the resulting integer is a safe-prime.
- The result is the respective RFC 3526 / 7919 prime, and the corresponding generator is always chosen to be 2 (which is a square for these prime, hence the corresponding subgroup has order (p-1)/2 and avoids leaking a bit in the private exponent).
Definition at line 442 of file dhm.h.