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

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