dhm.h File Reference

Diffie-Hellman-Merkle key exchange. More...

`#include "config.h"`
`#include "bignum.h"`
Include dependency graph for dhm.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures

struct | mbedtls_dhm_context
| The DHM context structure. More...

## Macros

#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 __attribute__((deprecated))
#define | MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL) ( (mbedtls_deprecated_constant_t) ( 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. More...
int | mbedtls_dhm_read_params (mbedtls_dhm_context *ctx, unsigned char **p, const unsigned char *end)
| This function parses the ServerKeyExchange parameters. 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 sets up and writes the ServerKeyExchange parameters. More...
int | mbedtls_dhm_set_group (mbedtls_dhm_context *ctx, const mbedtls_mpi *P, const mbedtls_mpi *G)
| Set 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 public value G^Y 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 its own private value `X` and exports `G^X`. 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...
void | mbedtls_dhm_free (mbedtls_dhm_context *ctx)
| This function frees and clears the components of a DHM key. 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...

## Variables

MBEDTLS_DEPRECATED typedef char const * | mbedtls_deprecated_constant_t

## Detailed Description

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.

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.

## Macro Definition Documentation

## MBEDTLS_DEPRECATED

#define MBEDTLS_DEPRECATED __attribute__((deprecated))

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 352 of file dhm.h.

## MBEDTLS_DEPRECATED_STRING_CONSTANT

#define MBEDTLS_DEPRECATED_STRING_CONSTANT | ( |  | VAL | ) | ( (mbedtls_deprecated_constant_t) ( VAL ) )

Definition at line 354 of file dhm.h.

## MBEDTLS_DHM_RFC3526_MODP_2048_G

#define MBEDTLS_DHM_RFC3526_MODP_2048_G MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )

The hexadecimal presentation of the chosen generator of the 2048-bit MODP Group, as defined in RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE).

Definition at line 438 of file dhm.h.

## MBEDTLS_DHM_RFC3526_MODP_2048_G_BIN

#define MBEDTLS_DHM_RFC3526_MODP_2048_G_BIN { 0x02 }

Definition at line 551 of file dhm.h.

## MBEDTLS_DHM_RFC3526_MODP_2048_P

#define MBEDTLS_DHM_RFC3526_MODP_2048_P

Value:
MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
"29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
"EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
"E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
"EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
"C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
"83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
"670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
"E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
"DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
"15728E5A8AACAA68FFFFFFFFFFFFFFFF" )
MBEDTLS_DEPRECATED_STRING_CONSTANT
#define MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL)
Definition: dhm.h:354

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).

Deprecated:
  The hex-encoded primes from RFC 3625 are deprecated and superseded by the corresponding macros providing them as binary constants. Their hex-encoded constants are likely to be removed in a future version of the library.

Definition at line 419 of file dhm.h.

## MBEDTLS_DHM_RFC3526_MODP_2048_P_BIN

#define MBEDTLS_DHM_RFC3526_MODP_2048_P_BIN

Definition at line 517 of file dhm.h.

## MBEDTLS_DHM_RFC3526_MODP_3072_G

#define MBEDTLS_DHM_RFC3526_MODP_3072_G MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )

The hexadecimal presentation of the chosen generator of the 3072-bit MODP Group, as defined in RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE).

Definition at line 470 of file dhm.h.

## MBEDTLS_DHM_RFC3526_MODP_3072_G_BIN

#define MBEDTLS_DHM_RFC3526_MODP_3072_G_BIN { 0x02 }

Definition at line 603 of file dhm.h.

## MBEDTLS_DHM_RFC3526_MODP_3072_P

#define MBEDTLS_DHM_RFC3526_MODP_3072_P

Value:
MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
"29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
"EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
"E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
"EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
"C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
"83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
"670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
"E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
"DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
"15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64" \
"ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7" \
"ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B" \
"F12FFA06D98A0864D87602733EC86A64521F2B18177B200C" \
"BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \
"43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF" )
MBEDTLS_DEPRECATED_STRING_CONSTANT
#define MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL)
Definition: dhm.h:354

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).

Definition at line 446 of file dhm.h.

## MBEDTLS_DHM_RFC3526_MODP_3072_P_BIN

#define MBEDTLS_DHM_RFC3526_MODP_3072_P_BIN

Definition at line 553 of file dhm.h.

## MBEDTLS_DHM_RFC3526_MODP_4096_G

#define MBEDTLS_DHM_RFC3526_MODP_4096_G MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )

The hexadecimal presentation of the chosen generator of the 4096-bit MODP Group, as defined in RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE).

Definition at line 508 of file dhm.h.

## MBEDTLS_DHM_RFC3526_MODP_4096_G_BIN

#define MBEDTLS_DHM_RFC3526_MODP_4096_G_BIN { 0x02 }

Definition at line 671 of file dhm.h.

## MBEDTLS_DHM_RFC3526_MODP_4096_P

#define MBEDTLS_DHM_RFC3526_MODP_4096_P

Value:
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" )
MBEDTLS_DEPRECATED_STRING_CONSTANT
#define MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL)
Definition: dhm.h:354

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).

Definition at line 478 of file dhm.h.

## MBEDTLS_DHM_RFC3526_MODP_4096_P_BIN

#define MBEDTLS_DHM_RFC3526_MODP_4096_P_BIN

Definition at line 605 of file dhm.h.

## MBEDTLS_DHM_RFC5114_MODP_2048_G

#define MBEDTLS_DHM_RFC5114_MODP_2048_G

Value:
MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"AC4032EF4F2D9AE39DF30B5C8FFDAC506CDEBE7B89998CAF" \
"74866A08CFE4FFE3A6824A4E10B9A6F0DD921F01A70C4AFA" \
"AB739D7700C29F52C57DB17C620A8652BE5E9001A8D66AD7" \
"C17669101999024AF4D027275AC1348BB8A762D0521BC98A" \
"E247150422EA1ED409939D54DA7460CDB5F6C6B250717CBE" \
"F180EB34118E98D119529A45D6F834566E3025E316A330EF" \
"BB77A86F0C1AB15B051AE3D428C8F8ACB70A8137150B8EEB" \
"10E183EDD19963DDD9E263E4770589EF6AA21E7F5F2FF381" \
"B539CCE3409D13CD566AFBB48D6C019181E1BCFE94B30269" \
"EDFE72FE9B6AA4BD7B5A0F1C71CFFF4C19C418E1F6EC0179" \
"81BC087F2A7065B384B890D3191F2BFA" )
MBEDTLS_DEPRECATED_STRING_CONSTANT
#define MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL)
Definition: dhm.h:354

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.

Definition at line 394 of file dhm.h.

## MBEDTLS_DHM_RFC5114_MODP_2048_P

#define MBEDTLS_DHM_RFC5114_MODP_2048_P

Value:
MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"AD107E1E9123A9D0D660FAA79559C51FA20D64E5683B9FD1" \
"B54B1597B61D0A75E6FA141DF95A56DBAF9A3C407BA1DF15" \
"EB3D688A309C180E1DE6B85A1274A0A66D3F8152AD6AC212" \
"9037C9EDEFDA4DF8D91E8FEF55B7394B7AD5B7D0B6C12207" \
"C9F98D11ED34DBF6C6BA0B2C8BBC27BE6A00E0A0B9C49708" \
"B3BF8A317091883681286130BC8985DB1602E714415D9330" \
"278273C7DE31EFDC7310F7121FD5A07415987D9ADC0A486D" \
"CDF93ACC44328387315D75E198C641A480CD86A1B9E587E8" \
"BE60E69CC928B2B9C52172E413042E9B23F10B0E16E79763" \
"C9B53DCF4BA80A29E3FB73C16B8E75B97EF363E2FFA31F71" \
"CF9DE5384E71B81C0AC4DFFE0C10E64F" )
MBEDTLS_DEPRECATED_STRING_CONSTANT
#define MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL)
Definition: dhm.h:354

Warning
  The origin of the primes in RFC 5114 is not documented and their use therefore constitutes a security risk!

Deprecated:
  The hex-encoded primes from RFC 5114 are deprecated and are likely to be removed in a future version of the library without replacement.

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.

Definition at line 375 of file dhm.h.

## MBEDTLS_DHM_RFC7919_FFDHE2048_G_BIN

#define MBEDTLS_DHM_RFC7919_FFDHE2048_G_BIN { 0x02 }

Definition at line 707 of file dhm.h.

## MBEDTLS_DHM_RFC7919_FFDHE2048_P_BIN

#define MBEDTLS_DHM_RFC7919_FFDHE2048_P_BIN

Definition at line 673 of file dhm.h.

## MBEDTLS_DHM_RFC7919_FFDHE3072_G_BIN

#define MBEDTLS_DHM_RFC7919_FFDHE3072_G_BIN { 0x02 }

Definition at line 759 of file dhm.h.

## MBEDTLS_DHM_RFC7919_FFDHE3072_P_BIN

#define MBEDTLS_DHM_RFC7919_FFDHE3072_P_BIN

Definition at line 709 of file dhm.h.

## MBEDTLS_DHM_RFC7919_FFDHE4096_G_BIN

#define MBEDTLS_DHM_RFC7919_FFDHE4096_G_BIN { 0x02 }

Definition at line 827 of file dhm.h.

## MBEDTLS_DHM_RFC7919_FFDHE4096_P_BIN

#define MBEDTLS_DHM_RFC7919_FFDHE4096_P_BIN

Definition at line 761 of file dhm.h.

## MBEDTLS_DHM_RFC7919_FFDHE6144_G_BIN

#define MBEDTLS_DHM_RFC7919_FFDHE6144_G_BIN { 0x02 }

Definition at line 927 of file dhm.h.

## MBEDTLS_DHM_RFC7919_FFDHE6144_P_BIN

#define MBEDTLS_DHM_RFC7919_FFDHE6144_P_BIN

Definition at line 829 of file dhm.h.

## MBEDTLS_DHM_RFC7919_FFDHE8192_G_BIN

#define MBEDTLS_DHM_RFC7919_FFDHE8192_G_BIN { 0x02 }

Definition at line 1059 of file dhm.h.

## MBEDTLS_DHM_RFC7919_FFDHE8192_P_BIN

#define MBEDTLS_DHM_RFC7919_FFDHE8192_P_BIN

Definition at line 929 of file dhm.h.

## MBEDTLS_ERR_DHM_ALLOC_FAILED

#define MBEDTLS_ERR_DHM_ALLOC_FAILED -0x3400

Allocation of memory failed.

Definition at line 80 of file dhm.h.

## MBEDTLS_ERR_DHM_BAD_INPUT_DATA

#define MBEDTLS_ERR_DHM_BAD_INPUT_DATA -0x3080

Bad input parameters.

Definition at line 73 of file dhm.h.

## MBEDTLS_ERR_DHM_CALC_SECRET_FAILED

#define MBEDTLS_ERR_DHM_CALC_SECRET_FAILED -0x3300

Calculation of the DHM secret failed.

Definition at line 78 of file dhm.h.

## MBEDTLS_ERR_DHM_FILE_IO_ERROR

#define MBEDTLS_ERR_DHM_FILE_IO_ERROR -0x3480

Read or write of file failed.

Definition at line 81 of file dhm.h.

## MBEDTLS_ERR_DHM_HW_ACCEL_FAILED

#define MBEDTLS_ERR_DHM_HW_ACCEL_FAILED -0x3500

DHM hardware accelerator failed.

Definition at line 82 of file dhm.h.

## MBEDTLS_ERR_DHM_INVALID_FORMAT

#define MBEDTLS_ERR_DHM_INVALID_FORMAT -0x3380

The ASN.1 data is not formatted correctly.

Definition at line 79 of file dhm.h.

## MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED

#define MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED -0x3180

Making of the DHM parameters failed.

Definition at line 75 of file dhm.h.

## MBEDTLS_ERR_DHM_MAKE_PUBLIC_FAILED

#define MBEDTLS_ERR_DHM_MAKE_PUBLIC_FAILED -0x3280

Making of the public value failed.

Definition at line 77 of file dhm.h.

## MBEDTLS_ERR_DHM_READ_PARAMS_FAILED

#define MBEDTLS_ERR_DHM_READ_PARAMS_FAILED -0x3100

Reading of the DHM parameters failed.

Definition at line 74 of file dhm.h.

## MBEDTLS_ERR_DHM_READ_PUBLIC_FAILED

#define MBEDTLS_ERR_DHM_READ_PUBLIC_FAILED -0x3200

Reading of the public values failed.

Definition at line 76 of file dhm.h.

## MBEDTLS_ERR_DHM_SET_GROUP_FAILED

#define MBEDTLS_ERR_DHM_SET_GROUP_FAILED -0x3580

Setting the modulus and generator failed.

Definition at line 83 of file dhm.h.

## Function Documentation

## mbedtls_dhm_calc_secret()

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`.

Parameters

  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.

Returns
  `0` on success, or an `MBEDTLS_ERR_DHM_XXX` error code on failure.

Note
  If non-NULL, `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.

## mbedtls_dhm_free()

void mbedtls_dhm_free | ( | mbedtls_dhm_context * | ctx | ) |

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

Parameters

  ctx | The DHM context to free and clear.

## mbedtls_dhm_init()

void mbedtls_dhm_init | ( | mbedtls_dhm_context * | ctx | ) |

This function initializes the DHM context.

Parameters

  ctx | The DHM context to initialize.

## mbedtls_dhm_make_params()

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.

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.

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().

Returns
  `0` on success, or an `MBEDTLS_ERR_DHM_XXX` error code on failure.

## mbedtls_dhm_make_public()

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`.

Parameters

  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.

Note
  The destination buffer will always be fully written so as to contain a big-endian presentation of G^X mod P. If it is larger than ctx->len, it will accordingly be padded with zero-bytes in the beginning.

Returns
  `0` on success, or an `MBEDTLS_ERR_DHM_XXX` error code on failure.

## mbedtls_dhm_read_params()

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

This function parses the ServerKeyExchange parameters.

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.

Returns
  `0` on success, or an `MBEDTLS_ERR_DHM_XXX` error code on failure.

## mbedtls_dhm_read_public()

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.

Parameters

  ctx | The DHM context.
  input | The input buffer.
  ilen | The size of the input buffer.

Returns
  `0` on success, or an `MBEDTLS_ERR_DHM_XXX` error code on failure.

## mbedtls_dhm_self_test()

int mbedtls_dhm_self_test | ( | int | verbose | ) |

The DMH checkup routine.

Returns
  `0` on success, or `1` on failure.

## mbedtls_dhm_set_group()

int mbedtls_dhm_set_group | ( | mbedtls_dhm_context * | ctx,
|  | const mbedtls_mpi * | P,
|  | const mbedtls_mpi * | G
| ) |  |

Set prime modulus and generator.

Parameters

  ctx | The DHM context.
  P | The MPI holding DHM prime modulus.
  G | The MPI holding DHM generator.

Note
  This function can be used to set P, G in preparation for `mbedtls_dhm_make_params`.

Returns
  `0` if successful, or an `MBEDTLS_ERR_DHM_XXX` error code on failure.

## Variable Documentation

## mbedtls_deprecated_constant_t

MBEDTLS_DEPRECATED typedef char const* mbedtls_deprecated_constant_t

Definition at line 353 of file dhm.h.