File dhm.h
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.
Warning
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.
Warning
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.
Defines
-
MBEDTLS_ERR_DHM_BAD_INPUT_DATA
Bad input parameters.
-
MBEDTLS_ERR_DHM_READ_PARAMS_FAILED
Reading of the DHM parameters failed.
-
MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED
Making of the DHM parameters failed.
-
MBEDTLS_ERR_DHM_READ_PUBLIC_FAILED
Reading of the public values failed.
-
MBEDTLS_ERR_DHM_MAKE_PUBLIC_FAILED
Making of the public value failed.
-
MBEDTLS_ERR_DHM_CALC_SECRET_FAILED
Calculation of the DHM secret failed.
-
MBEDTLS_ERR_DHM_INVALID_FORMAT
The ASN.1 data is not formatted correctly.
-
MBEDTLS_ERR_DHM_ALLOC_FAILED
Allocation of memory failed.
-
MBEDTLS_ERR_DHM_FILE_IO_ERROR
Read or write of file failed.
-
MBEDTLS_ERR_DHM_SET_GROUP_FAILED
Setting the modulus and generator failed.
-
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).
-
MBEDTLS_DHM_RFC3526_MODP_2048_G_BIN
-
MBEDTLS_DHM_RFC3526_MODP_3072_P_BIN
-
MBEDTLS_DHM_RFC3526_MODP_3072_G_BIN
-
MBEDTLS_DHM_RFC3526_MODP_4096_P_BIN
-
MBEDTLS_DHM_RFC3526_MODP_4096_G_BIN
-
MBEDTLS_DHM_RFC7919_FFDHE2048_P_BIN
-
MBEDTLS_DHM_RFC7919_FFDHE2048_G_BIN
-
MBEDTLS_DHM_RFC7919_FFDHE3072_P_BIN
-
MBEDTLS_DHM_RFC7919_FFDHE3072_G_BIN
-
MBEDTLS_DHM_RFC7919_FFDHE4096_P_BIN
-
MBEDTLS_DHM_RFC7919_FFDHE4096_G_BIN
-
MBEDTLS_DHM_RFC7919_FFDHE6144_P_BIN
-
MBEDTLS_DHM_RFC7919_FFDHE6144_G_BIN
-
MBEDTLS_DHM_RFC7919_FFDHE8192_P_BIN
-
MBEDTLS_DHM_RFC7919_FFDHE8192_G_BIN
Enums
-
enum mbedtls_dhm_parameter
Which parameter to access in mbedtls_dhm_get_value().
Values:
-
enumerator MBEDTLS_DHM_PARAM_P
The prime modulus.
-
enumerator MBEDTLS_DHM_PARAM_G
The generator.
-
enumerator MBEDTLS_DHM_PARAM_X
Our secret value.
-
enumerator MBEDTLS_DHM_PARAM_GX
Our public key =
G^X
modP
.
-
enumerator MBEDTLS_DHM_PARAM_GY
The public key of the peer =
G^Y
modP
.
-
enumerator MBEDTLS_DHM_PARAM_K
The shared secret =
G^
(XY) modP
.
-
enumerator MBEDTLS_DHM_PARAM_P
Functions
-
void mbedtls_dhm_init(mbedtls_dhm_context *ctx)
This function initializes the DHM context.
- Parameters
ctx – The DHM context to initialize.
-
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).
Note
In a TLS handshake, this is the how the client sets up its DHM context from the server’s public DHM key material.
- Parameters
ctx – The DHM context to use. This must be initialized.
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.- Returns
An
MBEDTLS_ERR_DHM_XXX
error code on failure.
-
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.
Note
This function assumes that the DHM parameters
ctx->P
andctx->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().Note
In a TLS handshake, this is the how the server generates and exports its DHM key material.
- Parameters
ctx – The DHM context to use. This must be initialized and have the DHM parameters set. It may or may not already have imported the peer’s public key.
x_size – The private key size in Bytes.
olen – The address at which to store the number of Bytes written on success. This must not be
NULL
.output – The destination buffer. This must be a writable buffer of sufficient size 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.
f_rng – The RNG function. Must not be
NULL
.p_rng – The RNG context to be passed to
f_rng
. This may beNULL
iff_rng
doesn’t need a context parameter.
- Returns
0
on success.- Returns
An
MBEDTLS_ERR_DHM_XXX
error code on failure.
-
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.
Note
This function can be used to set
ctx->P
,ctx->G
in preparation for mbedtls_dhm_make_params().- Parameters
ctx – The DHM context to configure. This must be initialized.
P – The MPI holding the DHM prime modulus. This must be an initialized MPI.
G – The MPI holding the DHM generator. This must be an initialized MPI.
- Returns
0
if successful.- Returns
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 raw public value of the peer.
Note
In a TLS handshake, this is the how the server imports the Client’s public DHM key.
- Parameters
ctx – The DHM context to use. This must be initialized and have its DHM parameters set, e.g. via mbedtls_dhm_set_group(). It may or may not already have generated its own private key.
input – The input buffer containing the
G^Y
value of the peer. This must be a readable buffer of sizeilen
Bytes.ilen – The size of the input buffer
input
in Bytes.
- Returns
0
on success.- Returns
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 (*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.
Note
The destination buffer is always fully written so as to contain a big-endian representation of G^X mod P. If it is larger than
ctx->len
, it is padded accordingly with zero-bytes at the beginning.- Parameters
ctx – The DHM context to use. This must be initialized and have the DHM parameters set. It may or may not already have imported the peer’s public key.
x_size – The private key size in Bytes.
output – The destination buffer. This must be a writable buffer of size
olen
Bytes.olen – The length of the destination buffer. This must be at least equal to
ctx->len
(the size ofP
).f_rng – The RNG function. This must not be
NULL
.p_rng – The RNG context to be passed to
f_rng
. This may beNULL
iff_rng
doesn’t need a context argument.
- Returns
0
on success.- Returns
An
MBEDTLS_ERR_DHM_XXX
error code on failure.
-
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
.Note
If
f_rng
is notNULL
, it is used to blind the input as a countermeasure against timing attacks. Blinding is used only if our private keyX
is re-used, and not used otherwise. We recommend always passing a non-NULLf_rng
argument.- Parameters
ctx – The DHM context to use. This must be initialized and have its own private key generated and the peer’s public key imported.
output – The buffer to write the generated shared key to. This must be a writable buffer of size
output_size
Bytes.output_size – The size of the destination buffer. This must be at least the size of
ctx->len
(the size ofP
).olen – On exit, holds the actual number of Bytes written.
f_rng – The RNG function. Must not be
NULL
. Used for blinding.p_rng – The RNG context to be passed to
f_rng
. This may beNULL
iff_rng
doesn’t need a context parameter.
- Returns
0
on success.- Returns
An
MBEDTLS_ERR_DHM_XXX
error code on failure.
-
size_t mbedtls_dhm_get_bitlen(const mbedtls_dhm_context *ctx)
This function returns the size of the prime modulus in bits.
- Parameters
ctx – The DHM context to query.
- Returns
The size of the prime modulus in bits, i.e. the number n such that 2^(n-1) <= P < 2^n.
-
size_t mbedtls_dhm_get_len(const mbedtls_dhm_context *ctx)
This function returns the size of the prime modulus in bytes.
- Parameters
ctx – The DHM context to query.
- Returns
The size of the prime modulus in bytes, i.e. the number n such that 2^(8*(n-1)) <= P < 2^(8*n).
-
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.
- Parameters
ctx – The DHM context to query.
param – The parameter to copy.
dest – The MPI object to copy the value into. It must be initialized.
- Returns
0
on success.- Returns
MBEDTLS_ERR_DHM_BAD_INPUT_DATA if
param
is invalid.- Returns
An
MBEDTLS_ERR_MPI_XXX
error code if the copy fails.
-
void mbedtls_dhm_free(mbedtls_dhm_context *ctx)
This function frees and clears the components of a DHM context.
- Parameters
ctx – The DHM context to free and clear. This may be
NULL
, in which case this function is a no-op. If it is notNULL
, it must point to an initialized DHM context.
-
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.
- Parameters
dhm – The DHM context to import the DHM parameters into. This must be initialized.
dhmin – The input buffer. This must be a readable buffer of length
dhminlen
Bytes.dhminlen – The size of the input buffer
dhmin
, including the terminatingNULL
Byte for PEM data.
- Returns
0
on success.- Returns
An
MBEDTLS_ERR_DHM_XXX
orMBEDTLS_ERR_PEM_XXX
error code on failure.
-
int mbedtls_dhm_parse_dhmfile(mbedtls_dhm_context *dhm, const char *path)
This function loads and parses DHM parameters from a file.
- Parameters
dhm – The DHM context to load the parameters to. This must be initialized.
path – The filename to read the DHM parameters from. This must not be
NULL
.
- Returns
0
on success.- Returns
An
MBEDTLS_ERR_DHM_XXX
orMBEDTLS_ERR_PEM_XXX
error code on failure.
-
int mbedtls_dhm_self_test(int verbose)
The DMH checkup routine.
- Returns
0
on success.- Returns
1
on failure.