takashi kadono / Mbed OS Nucleo446_SSD1331

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.

Dependencies:   ssd1331

Embed: (wiki syntax)

« Back to documentation index

dhm.h File Reference
Data Structures | Typedefs | Functions

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 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)
 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 public value of the peer, G^Y.
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 key, 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 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 not NULL, it is used to blind the input as a countermeasure against timing attacks. Blinding is used only if our private key X is re-used, and not used otherwise. We recommend always passing a non-NULL f_rng argument.
Parameters:
ctxThe DHM context.
outputThe destination buffer.
output_sizeThe size of the destination buffer. Must be at least the size of ctx->len (the size of P).
olenOn exit, holds the actual number of Bytes written.
f_rngThe RNG function, for blinding purposes.
p_rngThe RNG context.
Returns:
0 on success.
An MBEDTLS_ERR_DHM_XXX error code on failure.

Definition at line 376 of file dhm.c.

void mbedtls_dhm_free ( mbedtls_dhm_context *  ctx )

This function frees and clears the components of a DHM context.

Parameters:
ctxThe DHM context to free and clear.

Definition at line 429 of file dhm.c.

void mbedtls_dhm_init ( mbedtls_dhm_context *  ctx )

This function initializes the DHM context.

Parameters:
ctxThe DHM context to initialize.

Definition at line 122 of file dhm.c.

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.

Note:
The destination buffer must be large enough 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.
This function assumes that 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().
Parameters:
ctxThe DHM context.
x_sizeThe private key size in Bytes.
olenThe number of characters written.
outputThe destination buffer.
f_rngThe RNG function.
p_rngThe RNG context.
Returns:
0 on success.
An MBEDTLS_ERR_DHM_XXX error code on failure.

Definition at line 152 of file dhm.c.

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 key, X, and exports G^X.

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:
ctxThe DHM context.
x_sizeThe private key size in Bytes.
outputThe destination buffer.
olenThe length of the destination buffer. Must be at least equal to ctx->len (the size of P).
f_rngThe RNG function.
p_rngThe RNG context.
Returns:
0 on success.
An MBEDTLS_ERR_DHM_XXX error code on failure.

Definition at line 264 of file dhm.c.

int mbedtls_dhm_read_params ( mbedtls_dhm_context *  ctx,
unsigned char **  p,
const unsigned char *  end 
)

This function parses the ServerKeyExchange parameters.

Parameters:
ctxThe DHM context.
pOn 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.
endThe end of the input buffer.
Returns:
0 on success.
An MBEDTLS_ERR_DHM_XXX error code on failure.

Definition at line 130 of file dhm.c.

int mbedtls_dhm_read_public ( mbedtls_dhm_context *  ctx,
const unsigned char *  input,
size_t  ilen 
)

This function imports the public value of the peer, G^Y.

Parameters:
ctxThe DHM context.
inputThe input buffer containing the G^Y value of the peer.
ilenThe size of the input buffer.
Returns:
0 on success.
An MBEDTLS_ERR_DHM_XXX error code on failure.

Definition at line 247 of file dhm.c.

int mbedtls_dhm_self_test ( int  verbose )

The DMH checkup routine.

Returns:
0 on success.
1 on failure.

Definition at line 628 of file dhm.c.

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 P, G in preparation for mbedtls_dhm_make_params().
Parameters:
ctxThe DHM context.
PThe MPI holding the DHM prime modulus.
GThe MPI holding the DHM generator.
Returns:
0 if successful.
An MBEDTLS_ERR_DHM_XXX error code on failure.

Definition at line 225 of file dhm.c.

Generated on Tue Jul 12 2022 13:53:49 by  doxygen 1.7.2