ecdh.h File Reference

Detailed Description

Elliptic curve Diffie-Hellman.

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 ecdh.h.

#include "ecp.h"

Include dependency graph for ecdh.h:

Go to the source code of this file.

Data Structures
struct	mbedtls_ecdh_context
	ECDH context structure. More...

Enumerations
enum	mbedtls_ecdh_side { MBEDTLS_ECDH_OURS, MBEDTLS_ECDH_THEIRS }
	When importing from an EC key, select if it is our key or the peer's key. More...

Functions
int	mbedtls_ecdh_gen_public (mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
	Generate a public key. More...
int	mbedtls_ecdh_compute_shared (mbedtls_ecp_group *grp, mbedtls_mpi *z, const mbedtls_ecp_point *Q, const mbedtls_mpi *d, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
	Compute shared secret Raw function that only does the core computation. More...
void	mbedtls_ecdh_init (mbedtls_ecdh_context *ctx)
	Initialize context. More...
void	mbedtls_ecdh_free (mbedtls_ecdh_context *ctx)
	Free context. More...
int	mbedtls_ecdh_make_params (mbedtls_ecdh_context *ctx, size_t *olen, unsigned char *buf, size_t blen, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
	Generate a public key and a TLS ServerKeyExchange payload. More...
int	mbedtls_ecdh_read_params (mbedtls_ecdh_context *ctx, const unsigned char **buf, const unsigned char *end)
	Parse and procress a TLS ServerKeyExhange payload. More...
int	mbedtls_ecdh_get_params (mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key, mbedtls_ecdh_side side)
	Setup an ECDH context from an EC key. More...
int	mbedtls_ecdh_make_public (mbedtls_ecdh_context *ctx, size_t *olen, unsigned char *buf, size_t blen, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
	Generate a public key and a TLS ClientKeyExchange payload. More...
int	mbedtls_ecdh_read_public (mbedtls_ecdh_context *ctx, const unsigned char *buf, size_t blen)
	Parse and process a TLS ClientKeyExchange payload. More...
int	mbedtls_ecdh_calc_secret (mbedtls_ecdh_context *ctx, size_t *olen, unsigned char *buf, size_t blen, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
	Derive and export the shared secret. More...

Enumeration Type Documentation

enum mbedtls_ecdh_side

When importing from an EC key, select if it is our key or the peer's key.

Enumerator
MBEDTLS_ECDH_OURS
MBEDTLS_ECDH_THEIRS

Definition at line 35 of file ecdh.h.

Function Documentation

int mbedtls_ecdh_calc_secret	(	mbedtls_ecdh_context *	ctx,
		size_t *	olen,
		unsigned char *	buf,
		size_t	blen,
		int(*)(void *, unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

Derive and export the shared secret.

(Last function used by both TLS client en servers.)

Parameters

ctx	ECDH context
olen	number of bytes written
buf	destination buffer
blen	buffer length
f_rng	RNG function, see notes for mbedtls_ecdh_compute_shared()
p_rng	RNG parameter

Returns

0 if successful, or an MBEDTLS_ERR_ECP_XXX error code

int mbedtls_ecdh_compute_shared	(	mbedtls_ecp_group *	grp,
		mbedtls_mpi *	z,
		const mbedtls_ecp_point *	Q,
		const mbedtls_mpi *	d,
		int(*)(void *, unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

Compute shared secret Raw function that only does the core computation.

Parameters

grp	ECP group
z	Destination MPI (shared secret)
Q	Public key from other party
d	Our secret exponent (private key)
f_rng	RNG function (see notes)
p_rng	RNG parameter

Returns

0 if successful, or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code

Note

If f_rng is not NULL, it is used to implement countermeasures against potential elaborate timing attacks, see mbedtls_ecp_mul() for details.

void mbedtls_ecdh_free

(

mbedtls_ecdh_context *

ctx

)

Free context.

Parameters

ctx	Context to free

int mbedtls_ecdh_gen_public	(	mbedtls_ecp_group *	grp,
		mbedtls_mpi *	d,
		mbedtls_ecp_point *	Q,
		int(*)(void *, unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

Generate a public key.

Raw function that only does the core computation.

Parameters

grp	ECP group
d	Destination MPI (secret exponent, aka private key)
Q	Destination point (public key)
f_rng	RNG function
p_rng	RNG parameter

Returns

0 if successful, or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code

int mbedtls_ecdh_get_params	(	mbedtls_ecdh_context *	ctx,
		const mbedtls_ecp_keypair *	key,
		mbedtls_ecdh_side	side
	)

Setup an ECDH context from an EC key.

(Used by clients and servers in place of the ServerKeyEchange for static ECDH: import ECDH parameters from a certificate's EC key information.)

Parameters

ctx	ECDH constext to set
key	EC key to use
side	Is it our key (1) or the peer's key (0) ?

Returns

0 if successful, or an MBEDTLS_ERR_ECP_XXX error code

void mbedtls_ecdh_init

(

mbedtls_ecdh_context *

ctx

)

Initialize context.

Parameters

ctx	Context to initialize

int mbedtls_ecdh_make_params	(	mbedtls_ecdh_context *	ctx,
		size_t *	olen,
		unsigned char *	buf,
		size_t	blen,
		int(*)(void *, unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

Generate a public key and a TLS ServerKeyExchange payload.

(First function used by a TLS server for ECDHE.)

Parameters

ctx	ECDH context
olen	number of chars written
buf	destination buffer
blen	length of buffer
f_rng	RNG function
p_rng	RNG parameter

Note

This function assumes that ctx->grp has already been properly set (for example using mbedtls_ecp_group_load).

Returns

0 if successful, or an MBEDTLS_ERR_ECP_XXX error code

int mbedtls_ecdh_make_public	(	mbedtls_ecdh_context *	ctx,
		size_t *	olen,
		unsigned char *	buf,
		size_t	blen,
		int(*)(void *, unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

Generate a public key and a TLS ClientKeyExchange payload.

(Second function used by a TLS client for ECDH(E).)

Parameters

ctx	ECDH context
olen	number of bytes actually written
buf	destination buffer
blen	size of destination buffer
f_rng	RNG function
p_rng	RNG parameter

Returns

0 if successful, or an MBEDTLS_ERR_ECP_XXX error code

int mbedtls_ecdh_read_params	(	mbedtls_ecdh_context *	ctx,
		const unsigned char **	buf,
		const unsigned char *	end
	)

Parse and procress a TLS ServerKeyExhange payload.

(First function used by a TLS client for ECDHE.)

Parameters

ctx	ECDH context
buf	pointer to start of input buffer
end	one past end of buffer

Returns

0 if successful, or an MBEDTLS_ERR_ECP_XXX error code

int mbedtls_ecdh_read_public	(	mbedtls_ecdh_context *	ctx,
		const unsigned char *	buf,
		size_t	blen
	)

Parse and process a TLS ClientKeyExchange payload.

(Second function used by a TLS server for ECDH(E).)

Parameters

ctx	ECDH context
buf	start of input buffer
blen	length of input buffer

Returns

0 if successful, or an MBEDTLS_ERR_ECP_XXX error code