Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
dhm.h File Reference
This file contains Diffie-Hellman-Merkle (DHM) key exchange definitions and functions. More...
Go to the source code of this file.
Data Structures | |
struct | mbedtls_dhm_context |
The DHM context structure. More... | |
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. | |
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
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.
Typedef Documentation
typedef struct mbedtls_dhm_context mbedtls_dhm_context |
The DHM context structure.
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
.
- 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, for blinding purposes. This may b NULL
if blinding isn't needed.p_rng The RNG context. This may be NULL
iff_rng
doesn't need a context argument.
- Returns:
0
on success.-
An
MBEDTLS_ERR_DHM_XXX
error code on failure.
void mbedtls_dhm_free | ( | mbedtls_dhm_context * | ctx ) |
void mbedtls_dhm_init | ( | mbedtls_dhm_context * | ctx ) |
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 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(). - 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.-
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 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 of P
).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.-
An
MBEDTLS_ERR_DHM_XXX
error code on failure.
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.-
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.-
An
MBEDTLS_ERR_DHM_XXX
orMBEDTLS_ERR_PEM_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 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.-
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.-
An
MBEDTLS_ERR_DHM_XXX
error code on failure.
int mbedtls_dhm_self_test | ( | int | verbose ) |
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.-
An
MBEDTLS_ERR_DHM_XXX
error code on failure.
Generated on Tue Jul 12 2022 13:55:07 by
