mbed TLS v2.2.0
Data Structures | Macros | Functions
dhm.h File Reference

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.

#include "bignum.h"
Include dependency graph for dhm.h:

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_self_test (int verbose)
 Checkup routine. More...
 

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
ctxDHM context
outputdestination buffer
output_sizesize of the destination buffer
olenon exit, holds the actual number of bytes written
f_rngRNG function, for blinding purposes
p_rngRNG 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
ctxDHM context to free and clear
void mbedtls_dhm_init ( mbedtls_dhm_context ctx)

Initialize DHM context.

Parameters
ctxDHM 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
ctxDHM context
x_sizeprivate value size in bytes
outputdestination buffer
olennumber of chars written
f_rngRNG function
p_rngRNG 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
ctxDHM context
x_sizeprivate value size in bytes
outputdestination buffer
olenmust be equal to ctx->P.len
f_rngRNG function
p_rngRNG 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
ctxDHM context
p&(start of input buffer)
endend 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
ctxDHM context
inputinput buffer
ilensize 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