dhm.h File Reference

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

`#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
| DHM context structure. More...

## Macros

#define | MBEDTLS_ERR_DHM_BAD_INPUT_DATA -0x3080
| Bad input parameters to function. More...
#define | MBEDTLS_ERR_DHM_READ_PARAMS_FAILED -0x3100
| Reading of the DHM parameters failed. More...
#define | MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED -0x3180
| Making of the DHM parameters failed. More...
#define | MBEDTLS_ERR_DHM_READ_PUBLIC_FAILED -0x3200
| Reading of the public values failed. More...
#define | MBEDTLS_ERR_DHM_MAKE_PUBLIC_FAILED -0x3280
| Making of the public value failed. More...
#define | MBEDTLS_ERR_DHM_CALC_SECRET_FAILED -0x3300
| Calculation of the DHM secret failed. More...
#define | MBEDTLS_ERR_DHM_INVALID_FORMAT -0x3380
| The ASN.1 data is not formatted correctly. More...
#define | MBEDTLS_ERR_DHM_ALLOC_FAILED -0x3400
| Allocation of memory failed. More...
#define | MBEDTLS_ERR_DHM_FILE_IO_ERROR -0x3480
| Read/write of file failed. More...
#define | MBEDTLS_DHM_RFC3526_MODP_2048_P
| RFC 3526 defines a number of standardized Diffie-Hellman groups for IKE. More...
#define | MBEDTLS_DHM_RFC3526_MODP_2048_G "02"
#define | MBEDTLS_DHM_RFC3526_MODP_3072_P
#define | MBEDTLS_DHM_RFC3526_MODP_3072_G "02"
#define | MBEDTLS_DHM_RFC3526_MODP_4096_P
#define | MBEDTLS_DHM_RFC3526_MODP_4096_G "02"
#define | MBEDTLS_DHM_RFC5114_MODP_2048_P
#define | MBEDTLS_DHM_RFC5114_MODP_2048_G

## Functions

void | mbedtls_dhm_init (mbedtls_dhm_context *ctx)
| Initialize DHM context. More...
int | mbedtls_dhm_read_params (mbedtls_dhm_context *ctx, unsigned char **p, const unsigned char *end)
| Parse 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)
| Setup and write the ServerKeyExchange parameters. More...
int | mbedtls_dhm_read_public (mbedtls_dhm_context *ctx, const unsigned char *input, size_t ilen)
| Import the peer's public value G^Y. 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)
| Create own private value X and export 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)
| Derive and export the shared secret (G^Y)^X mod P. More...
void | mbedtls_dhm_free (mbedtls_dhm_context *ctx)
| Free and clear the components of a DHM key. More...
int | mbedtls_dhm_parse_dhm (mbedtls_dhm_context *dhm, const unsigned char *dhmin, size_t dhminlen)
| Parse DHM parameters in PEM or DER format. More...
int | mbedtls_dhm_parse_dhmfile (mbedtls_dhm_context *dhm, const char *path)
| Load and parse DHM parameters. More...
int | mbedtls_dhm_self_test (int verbose)
| Checkup routine. More...

## Detailed Description

Diffie-Hellman-Merkle key exchange.

Copyright (C) 2006-2015, ARM Limited, All Rights Reserved SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file is part of mbed TLS (https://tls.mbed.org)

Definition in file dhm.h.

## Macro Definition Documentation

#define MBEDTLS_DHM_RFC3526_MODP_2048_G "02"

Definition at line 68 of file dhm.h.

#define MBEDTLS_DHM_RFC3526_MODP_2048_P

Value:
"FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
"29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
"EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
"E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
"EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
"C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
"83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
"670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
"E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
"DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
"15728E5A8AACAA68FFFFFFFFFFFFFFFF"

RFC 3526 defines a number of standardized Diffie-Hellman groups for IKE.

RFC 5114 defines a number of standardized Diffie-Hellman groups that can be used.

Some are included here for convenience.

Included are: RFC 3526 3. 2048-bit MODP Group RFC 3526 4. 3072-bit MODP Group RFC 3526 5. 4096-bit MODP Group RFC 5114 2.2. 2048-bit MODP Group with 224-bit Prime Order Subgroup

Definition at line 55 of file dhm.h.

#define MBEDTLS_DHM_RFC3526_MODP_3072_G "02"

Definition at line 88 of file dhm.h.

#define MBEDTLS_DHM_RFC3526_MODP_3072_P

Value:
"FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
"29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
"EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
"E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
"EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
"C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
"83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
"670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
"E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
"DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
"15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64" \
"ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7" \
"ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B" \
"F12FFA06D98A0864D87602733EC86A64521F2B18177B200C" \
"BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \
"43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF"

Definition at line 70 of file dhm.h.

#define MBEDTLS_DHM_RFC3526_MODP_4096_G "02"

Definition at line 114 of file dhm.h.

#define MBEDTLS_DHM_RFC3526_MODP_4096_P

Value:
"FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
"29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
"EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
"E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
"EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
"C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
"83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
"670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
"E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
"DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
"15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64" \
"ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7" \
"ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B" \
"F12FFA06D98A0864D87602733EC86A64521F2B18177B200C" \
"BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \
"43DB5BFCE0FD108E4B82D120A92108011A723C12A787E6D7" \
"88719A10BDBA5B2699C327186AF4E23C1A946834B6150BDA" \
"2583E9CA2AD44CE8DBBBC2DB04DE8EF92E8EFC141FBECAA6" \
"287C59474E6BC05D99B2964FA090C3A2233BA186515BE7ED" \
"1F612970CEE2D7AFB81BDD762170481CD0069127D5B05AA9" \
"93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934063199" \
"FFFFFFFFFFFFFFFF"

Definition at line 90 of file dhm.h.

#define MBEDTLS_DHM_RFC5114_MODP_2048_G

Value:
"AC4032EF4F2D9AE39DF30B5C8FFDAC506CDEBE7B89998CAF"\
"74866A08CFE4FFE3A6824A4E10B9A6F0DD921F01A70C4AFA"\
"AB739D7700C29F52C57DB17C620A8652BE5E9001A8D66AD7"\
"C17669101999024AF4D027275AC1348BB8A762D0521BC98A"\
"E247150422EA1ED409939D54DA7460CDB5F6C6B250717CBE"\
"F180EB34118E98D119529A45D6F834566E3025E316A330EF"\
"BB77A86F0C1AB15B051AE3D428C8F8ACB70A8137150B8EEB"\
"10E183EDD19963DDD9E263E4770589EF6AA21E7F5F2FF381"\
"B539CCE3409D13CD566AFBB48D6C019181E1BCFE94B30269"\
"EDFE72FE9B6AA4BD7B5A0F1C71CFFF4C19C418E1F6EC0179"\
"81BC087F2A7065B384B890D3191F2BFA"

Definition at line 129 of file dhm.h.

#define MBEDTLS_DHM_RFC5114_MODP_2048_P

Value:
"AD107E1E9123A9D0D660FAA79559C51FA20D64E5683B9FD1" \
"B54B1597B61D0A75E6FA141DF95A56DBAF9A3C407BA1DF15" \
"EB3D688A309C180E1DE6B85A1274A0A66D3F8152AD6AC212" \
"9037C9EDEFDA4DF8D91E8FEF55B7394B7AD5B7D0B6C12207" \
"C9F98D11ED34DBF6C6BA0B2C8BBC27BE6A00E0A0B9C49708" \
"B3BF8A317091883681286130BC8985DB1602E714415D9330" \
"278273C7DE31EFDC7310F7121FD5A07415987D9ADC0A486D" \
"CDF93ACC44328387315D75E198C641A480CD86A1B9E587E8" \
"BE60E69CC928B2B9C52172E413042E9B23F10B0E16E79763" \
"C9B53DCF4BA80A29E3FB73C16B8E75B97EF363E2FFA31F71" \
"CF9DE5384E71B81C0AC4DFFE0C10E64F"

Definition at line 116 of file dhm.h.

#define MBEDTLS_ERR_DHM_ALLOC_FAILED -0x3400

Allocation of memory failed.

Definition at line 38 of file dhm.h.

#define MBEDTLS_ERR_DHM_BAD_INPUT_DATA -0x3080

Bad input parameters to function.

Definition at line 31 of file dhm.h.

#define MBEDTLS_ERR_DHM_CALC_SECRET_FAILED -0x3300

Calculation of the DHM secret failed.

Definition at line 36 of file dhm.h.

#define MBEDTLS_ERR_DHM_FILE_IO_ERROR -0x3480

Read/write of file failed.

Definition at line 39 of file dhm.h.

#define MBEDTLS_ERR_DHM_INVALID_FORMAT -0x3380

The ASN.1 data is not formatted correctly.

Definition at line 37 of file dhm.h.

#define MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED -0x3180

Making of the DHM parameters failed.

Definition at line 33 of file dhm.h.

#define MBEDTLS_ERR_DHM_MAKE_PUBLIC_FAILED -0x3280

Making of the public value failed.

Definition at line 35 of file dhm.h.

#define MBEDTLS_ERR_DHM_READ_PARAMS_FAILED -0x3100

Reading of the DHM parameters failed.

Definition at line 32 of file dhm.h.

#define MBEDTLS_ERR_DHM_READ_PUBLIC_FAILED -0x3200

Reading of the public values failed.

Definition at line 34 of file dhm.h.

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

Derive and export the shared secret (G^Y)^X mod P.

Parameters

  ctx | DHM context
  output | destination buffer
  output_size | size of the destination buffer
  olen | on exit, holds the actual number of bytes written
  f_rng | RNG function, for blinding purposes
  p_rng | RNG parameter

Returns
  0 if successful, or an MBEDTLS_ERR_DHM_XXX error code

Note
  If non-NULL, f_rng is used to blind the input as countermeasure against timing attacks. Blinding is automatically used if and only if our secret value X is re-used and costs nothing otherwise, so it is recommended to always pass a non-NULL f_rng argument.

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

Free and clear the components of a DHM key.

Parameters

  ctx | DHM context to free and clear

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

Initialize DHM context.

Parameters

  ctx | DHM context to be initialized

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

Setup and write the ServerKeyExchange parameters.

Parameters

  ctx | DHM context
  x_size | private value size in bytes
  output | destination buffer
  olen | number of chars written
  f_rng | RNG function
  p_rng | RNG parameter

Note
  This function assumes that ctx->P and ctx->G have already been properly set (for example using mbedtls_mpi_read_string or mbedtls_mpi_read_binary).

Returns
  0 if successful, or an MBEDTLS_ERR_DHM_XXX error code

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

Create own private value X and export G^X.

Parameters

  ctx | DHM context
  x_size | private value size in bytes
  output | destination buffer
  olen | must be equal to ctx->P.len
  f_rng | RNG function
  p_rng | RNG parameter

Returns
  0 if successful, or an MBEDTLS_ERR_DHM_XXX error code

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

Parse the ServerKeyExchange parameters.

Parameters

  ctx | DHM context
  p | &(start of input buffer)
  end | end of buffer

Returns
  0 if successful, or an MBEDTLS_ERR_DHM_XXX error code

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

Import the peer's public value G^Y.

Parameters

  ctx | DHM context
  input | input buffer
  ilen | size of buffer

Returns
  0 if successful, or an MBEDTLS_ERR_DHM_XXX error code

int mbedtls_dhm_self_test | ( | int | verbose | ) |

Checkup routine.

Returns
  0 if successful, or 1 if the test failed