Diffie-Hellman-Merkle key exchange. More...
#include "config.h"
#include "bignum.h"
Go to the source code of this file.
Data Structures | |
struct | mbedtls_dhm_context |
The DHM context structure. More... | |
Defines | |
#define | MBEDTLS_ERR_DHM_BAD_INPUT_DATA -0x3080 |
#define | MBEDTLS_ERR_DHM_READ_PARAMS_FAILED -0x3100 |
#define | MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED -0x3180 |
#define | MBEDTLS_ERR_DHM_READ_PUBLIC_FAILED -0x3200 |
#define | MBEDTLS_ERR_DHM_MAKE_PUBLIC_FAILED -0x3280 |
#define | MBEDTLS_ERR_DHM_CALC_SECRET_FAILED -0x3300 |
#define | MBEDTLS_ERR_DHM_INVALID_FORMAT -0x3380 |
#define | MBEDTLS_ERR_DHM_ALLOC_FAILED -0x3400 |
#define | MBEDTLS_ERR_DHM_FILE_IO_ERROR -0x3480 |
#define | MBEDTLS_ERR_DHM_HW_ACCEL_FAILED -0x3500 |
#define | MBEDTLS_ERR_DHM_SET_GROUP_FAILED -0x3580 |
#define | MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL) VAL |
#define | MBEDTLS_DHM_RFC5114_MODP_2048_P |
#define | MBEDTLS_DHM_RFC5114_MODP_2048_G |
#define | MBEDTLS_DHM_RFC3526_MODP_2048_P |
#define | MBEDTLS_DHM_RFC3526_MODP_2048_G MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" ) |
#define | MBEDTLS_DHM_RFC3526_MODP_3072_P |
#define | MBEDTLS_DHM_RFC3526_MODP_3072_G MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" ) |
#define | MBEDTLS_DHM_RFC3526_MODP_4096_P |
#define | MBEDTLS_DHM_RFC3526_MODP_4096_G MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" ) |
#define | MBEDTLS_DHM_RFC3526_MODP_2048_P_BIN |
#define | MBEDTLS_DHM_RFC3526_MODP_2048_G_BIN { 0x02 } |
#define | MBEDTLS_DHM_RFC3526_MODP_3072_P_BIN |
#define | MBEDTLS_DHM_RFC3526_MODP_3072_G_BIN { 0x02 } |
#define | MBEDTLS_DHM_RFC3526_MODP_4096_P_BIN |
#define | MBEDTLS_DHM_RFC3526_MODP_4096_G_BIN { 0x02 } |
#define | MBEDTLS_DHM_RFC7919_FFDHE2048_P_BIN |
#define | MBEDTLS_DHM_RFC7919_FFDHE2048_G_BIN { 0x02 } |
#define | MBEDTLS_DHM_RFC7919_FFDHE3072_P_BIN |
#define | MBEDTLS_DHM_RFC7919_FFDHE3072_G_BIN { 0x02 } |
#define | MBEDTLS_DHM_RFC7919_FFDHE4096_P_BIN |
#define | MBEDTLS_DHM_RFC7919_FFDHE4096_G_BIN { 0x02 } |
#define | MBEDTLS_DHM_RFC7919_FFDHE6144_P_BIN |
#define | MBEDTLS_DHM_RFC7919_FFDHE6144_G_BIN { 0x02 } |
#define | MBEDTLS_DHM_RFC7919_FFDHE8192_P_BIN |
#define | MBEDTLS_DHM_RFC7919_FFDHE8192_G_BIN { 0x02 } |
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. |
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.
Definition in file dhm.h.
#define MBEDTLS_DEPRECATED_STRING_CONSTANT | ( | VAL | ) | VAL |
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:
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:
#define MBEDTLS_DHM_RFC3526_MODP_2048_G MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" ) |
#define MBEDTLS_DHM_RFC3526_MODP_2048_P |
MBEDTLS_DEPRECATED_STRING_CONSTANT( \ "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \ "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \ "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \ "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \ "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \ "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \ "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \ "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \ "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \ "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \ "15728E5A8AACAA68FFFFFFFFFFFFFFFF" )
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_3072_G MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" ) |
#define MBEDTLS_DHM_RFC3526_MODP_3072_P |
MBEDTLS_DEPRECATED_STRING_CONSTANT( \ "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \ "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \ "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \ "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \ "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \ "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \ "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \ "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \ "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \ "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \ "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64" \ "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7" \ "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B" \ "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C" \ "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \ "43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF" )
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_4096_G MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" ) |
#define MBEDTLS_DHM_RFC3526_MODP_4096_P |
MBEDTLS_DEPRECATED_STRING_CONSTANT( \ "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \ "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \ "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \ "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \ "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \ "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \ "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \ "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \ "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \ "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \ "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64" \ "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7" \ "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B" \ "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C" \ "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \ "43DB5BFCE0FD108E4B82D120A92108011A723C12A787E6D7" \ "88719A10BDBA5B2699C327186AF4E23C1A946834B6150BDA" \ "2583E9CA2AD44CE8DBBBC2DB04DE8EF92E8EFC141FBECAA6" \ "287C59474E6BC05D99B2964FA090C3A2233BA186515BE7ED" \ "1F612970CEE2D7AFB81BDD762170481CD0069127D5B05AA9" \ "93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934063199" \ "FFFFFFFFFFFFFFFF" )
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_RFC5114_MODP_2048_G |
MBEDTLS_DEPRECATED_STRING_CONSTANT( \ "AC4032EF4F2D9AE39DF30B5C8FFDAC506CDEBE7B89998CAF" \ "74866A08CFE4FFE3A6824A4E10B9A6F0DD921F01A70C4AFA" \ "AB739D7700C29F52C57DB17C620A8652BE5E9001A8D66AD7" \ "C17669101999024AF4D027275AC1348BB8A762D0521BC98A" \ "E247150422EA1ED409939D54DA7460CDB5F6C6B250717CBE" \ "F180EB34118E98D119529A45D6F834566E3025E316A330EF" \ "BB77A86F0C1AB15B051AE3D428C8F8ACB70A8137150B8EEB" \ "10E183EDD19963DDD9E263E4770589EF6AA21E7F5F2FF381" \ "B539CCE3409D13CD566AFBB48D6C019181E1BCFE94B30269" \ "EDFE72FE9B6AA4BD7B5A0F1C71CFFF4C19C418E1F6EC0179" \ "81BC087F2A7065B384B890D3191F2BFA" )
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_RFC5114_MODP_2048_P |
MBEDTLS_DEPRECATED_STRING_CONSTANT( \ "AD107E1E9123A9D0D660FAA79559C51FA20D64E5683B9FD1" \ "B54B1597B61D0A75E6FA141DF95A56DBAF9A3C407BA1DF15" \ "EB3D688A309C180E1DE6B85A1274A0A66D3F8152AD6AC212" \ "9037C9EDEFDA4DF8D91E8FEF55B7394B7AD5B7D0B6C12207" \ "C9F98D11ED34DBF6C6BA0B2C8BBC27BE6A00E0A0B9C49708" \ "B3BF8A317091883681286130BC8985DB1602E714415D9330" \ "278273C7DE31EFDC7310F7121FD5A07415987D9ADC0A486D" \ "CDF93ACC44328387315D75E198C641A480CD86A1B9E587E8" \ "BE60E69CC928B2B9C52172E413042E9B23F10B0E16E79763" \ "C9B53DCF4BA80A29E3FB73C16B8E75B97EF363E2FFA31F71" \ "CF9DE5384E71B81C0AC4DFFE0C10E64F" )
The hexadecimal presentation of the prime underlying 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_ERR_DHM_ALLOC_FAILED -0x3400 |
#define MBEDTLS_ERR_DHM_BAD_INPUT_DATA -0x3080 |
#define MBEDTLS_ERR_DHM_CALC_SECRET_FAILED -0x3300 |
#define MBEDTLS_ERR_DHM_FILE_IO_ERROR -0x3480 |
#define MBEDTLS_ERR_DHM_HW_ACCEL_FAILED -0x3500 |
#define MBEDTLS_ERR_DHM_INVALID_FORMAT -0x3380 |
#define MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED -0x3180 |
#define MBEDTLS_ERR_DHM_MAKE_PUBLIC_FAILED -0x3280 |
#define MBEDTLS_ERR_DHM_READ_PARAMS_FAILED -0x3100 |
#define MBEDTLS_ERR_DHM_READ_PUBLIC_FAILED -0x3200 |
#define MBEDTLS_ERR_DHM_SET_GROUP_FAILED -0x3580 |
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
.
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. |
0
on success, or an MBEDTLS_ERR_DHM_XXX
error code on failure.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. void mbedtls_dhm_free | ( | mbedtls_dhm_context * | ctx | ) |
This function frees and clears the components of a DHM key.
ctx | The DHM context to free and clear. |
void mbedtls_dhm_init | ( | mbedtls_dhm_context * | ctx | ) |
This function initializes the DHM context.
ctx | The DHM context to initialize. |
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.
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. |
mbedtls_mpi_size
to computing the byte-size of an MPI.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().0
on success, or an MBEDTLS_ERR_DHM_XXX
error code on failure. 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
.
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. |
0
on success, or an MBEDTLS_ERR_DHM_XXX
error code on failure. int mbedtls_dhm_read_params | ( | mbedtls_dhm_context * | ctx, | |
unsigned char ** | p, | |||
const unsigned char * | end | |||
) |
This function parses the ServerKeyExchange 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. |
0
on success, or an MBEDTLS_ERR_DHM_XXX
error code on failure. 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.
ctx | The DHM context. | |
input | The input buffer. | |
ilen | The size of the input buffer. |
0
on success, or an MBEDTLS_ERR_DHM_XXX
error code on failure. int mbedtls_dhm_self_test | ( | int | verbose | ) |
The DMH checkup routine.
0
on success, or 1
on failure. int mbedtls_dhm_set_group | ( | mbedtls_dhm_context * | ctx, | |
const mbedtls_mpi * | P, | |||
const mbedtls_mpi * | G | |||
) |
Set prime modulus and generator.
ctx | The DHM context. | |
P | The MPI holding DHM prime modulus. | |
G | The MPI holding DHM generator. |
mbedtls_dhm_make_params
.0
if successful, or an MBEDTLS_ERR_DHM_XXX
error code on failure.