mbed TLS v3.1.0
Data Structures | Macros | Typedefs | Enumerations | Functions
ecdh.h File Reference

This file contains ECDH definitions and functions. More...

#include "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include "mbedtls/ecp.h"
Include dependency graph for ecdh.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  mbedtls_ecdh_context
 The ECDH context structure. More...
 

Macros

#define MBEDTLS_ECDH_LEGACY_CONTEXT
 

Typedefs

typedef struct mbedtls_ecdh_context mbedtls_ecdh_context
 The ECDH context structure. More...
 

Enumerations

enum  mbedtls_ecdh_side { MBEDTLS_ECDH_OURS, MBEDTLS_ECDH_THEIRS }
 

Functions

int mbedtls_ecdh_can_do (mbedtls_ecp_group_id gid)
 Check whether a given group can be used for ECDH. More...
 
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)
 This function generates an ECDH keypair on an elliptic curve. 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)
 This function computes the shared secret. More...
 
void mbedtls_ecdh_init (mbedtls_ecdh_context *ctx)
 This function initializes an ECDH context. More...
 
int mbedtls_ecdh_setup (mbedtls_ecdh_context *ctx, mbedtls_ecp_group_id grp_id)
 This function sets up the ECDH context with the information given. More...
 
void mbedtls_ecdh_free (mbedtls_ecdh_context *ctx)
 This function frees a 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)
 This function generates an EC key pair and exports its in the format used in a TLS ServerKeyExchange handshake message. More...
 
int mbedtls_ecdh_read_params (mbedtls_ecdh_context *ctx, const unsigned char **buf, const unsigned char *end)
 This function parses the ECDHE parameters in a TLS ServerKeyExchange handshake message. More...
 
int mbedtls_ecdh_get_params (mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key, mbedtls_ecdh_side side)
 This function sets up 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)
 This function generates a public key and exports it as a TLS ClientKeyExchange payload. More...
 
int mbedtls_ecdh_read_public (mbedtls_ecdh_context *ctx, const unsigned char *buf, size_t blen)
 This function parses and processes the ECDHE payload of a TLS ClientKeyExchange message. 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)
 This function derives and exports the shared secret. More...
 
void mbedtls_ecdh_enable_restart (mbedtls_ecdh_context *ctx)
 This function enables restartable EC computations for this context. (Default: disabled.) More...
 

Detailed Description

This file contains ECDH definitions and functions.

The Elliptic Curve Diffie-Hellman (ECDH) protocol is an anonymous key agreement protocol allowing two parties to establish a shared secret over an insecure channel. Each party must have an elliptic-curve public–private key pair.

For more information, see NIST SP 800-56A Rev. 2: Recommendation for Pair-Wise Key Establishment Schemes Using Discrete Logarithm Cryptography.

Definition in file ecdh.h.

Macro Definition Documentation

#define MBEDTLS_ECDH_LEGACY_CONTEXT

Definition at line 54 of file ecdh.h.

Typedef Documentation

The ECDH context structure.

Warning
Performing multiple operations concurrently on the same ECDSA context is not supported; objects of this type should not be shared between multiple threads.

Enumeration Type Documentation

Defines the source of the imported EC key.

Enumerator
MBEDTLS_ECDH_OURS 

Our key.

MBEDTLS_ECDH_THEIRS 

The key of the peer.

Definition at line 71 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 
)

This function derives and exports the shared secret.

This is the last function used by both TLS client and servers.

Note
If f_rng is not NULL, it is used to implement countermeasures against side-channel attacks. For more information, see mbedtls_ecp_mul().
See Also
ecp.h
Parameters
ctxThe ECDH context to use. This must be initialized and have its own private key generated and the peer's public key imported.
olenThe address at which to store the total number of Bytes written on success. This must not be NULL.
bufThe buffer to write the generated shared key to. This must be a writable buffer of size blen Bytes.
blenThe length of the destination buffer buf in Bytes.
f_rngThe RNG function to use. This must not be NULL.
p_rngThe RNG context. This may be NULL if f_rng doesn't need a context argument.
Returns
0 on success.
MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see mbedtls_ecp_set_max_ops().
Another MBEDTLS_ERR_ECP_XXX error code on failure.
int mbedtls_ecdh_can_do ( mbedtls_ecp_group_id  gid)

Check whether a given group can be used for ECDH.

Parameters
gidThe ECP group ID to check.
Returns
1 if the group can be used, 0 otherwise
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 
)

This function computes the shared secret.

This function performs the second of two core computations implemented during the ECDH key exchange. The first core computation is performed by mbedtls_ecdh_gen_public().

See Also
ecp.h
Note
If f_rng is not NULL, it is used to implement countermeasures against side-channel attacks. For more information, see mbedtls_ecp_mul().
Parameters
grpThe ECP group to use. This must be initialized and have domain parameters loaded, for example through mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().
zThe destination MPI (shared secret). This must be initialized.
QThe public key from another party. This must be initialized.
dOur secret exponent (private key). This must be initialized.
f_rngThe RNG function to use. This must not be NULL.
p_rngThe RNG context to be passed to f_rng. This may be NULL if f_rng is NULL or doesn't need a context argument.
Returns
0 on success.
Another MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.
void mbedtls_ecdh_enable_restart ( mbedtls_ecdh_context ctx)

This function enables restartable EC computations for this context. (Default: disabled.)

See Also
mbedtls_ecp_set_max_ops()
Note
It is not possible to safely disable restartable computations once enabled, except by free-ing the context, which cancels possible in-progress operations.
Parameters
ctxThe ECDH context to use. This must be initialized.
void mbedtls_ecdh_free ( mbedtls_ecdh_context ctx)

This function frees a context.

Parameters
ctxThe context to free. This may be NULL, in which case this function does nothing. If it is not NULL, it must point to an initialized ECDH context.
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 
)

This function generates an ECDH keypair on an elliptic curve.

This function performs the first of two core computations implemented during the ECDH key exchange. The second core computation is performed by mbedtls_ecdh_compute_shared().

See Also
ecp.h
Parameters
grpThe ECP group to use. This must be initialized and have domain parameters loaded, for example through mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().
dThe destination MPI (private key). This must be initialized.
QThe destination point (public key). This must be initialized.
f_rngThe RNG function to use. This must not be NULL.
p_rngThe RNG context to be passed to f_rng. This may be NULL in case f_rng doesn't need a context argument.
Returns
0 on success.
Another MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.
int mbedtls_ecdh_get_params ( mbedtls_ecdh_context ctx,
const mbedtls_ecp_keypair key,
mbedtls_ecdh_side  side 
)

This function sets up an ECDH context from an EC key.

It is used by clients and servers in place of the ServerKeyEchange for static ECDH, and imports ECDH parameters from the EC key information of a certificate.

See Also
ecp.h
Parameters
ctxThe ECDH context to set up. This must be initialized.
keyThe EC key to use. This must be initialized.
sideDefines the source of the key. Possible values are:
Returns
0 on success.
Another MBEDTLS_ERR_ECP_XXX error code on failure.
void mbedtls_ecdh_init ( mbedtls_ecdh_context ctx)

This function initializes an ECDH context.

Parameters
ctxThe ECDH context to initialize. This must not be NULL.
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 
)

This function generates an EC key pair and exports its in the format used in a TLS ServerKeyExchange handshake message.

This is the second function used by a TLS server for ECDHE ciphersuites. (It is called after mbedtls_ecdh_setup().)

See Also
ecp.h
Parameters
ctxThe ECDH context to use. This must be initialized and bound to a group, for example via mbedtls_ecdh_setup().
olenThe address at which to store the number of Bytes written.
bufThe destination buffer. This must be a writable buffer of length blen Bytes.
blenThe length of the destination buffer buf in Bytes.
f_rngThe RNG function to use. This must not be NULL.
p_rngThe RNG context to be passed to f_rng. This may be NULL in case f_rng doesn't need a context argument.
Returns
0 on success.
MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see mbedtls_ecp_set_max_ops().
Another MBEDTLS_ERR_ECP_XXX error code on failure.
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 
)

This function generates a public key and exports it as a TLS ClientKeyExchange payload.

This is the second function used by a TLS client for ECDH(E) ciphersuites.

See Also
ecp.h
Parameters
ctxThe ECDH context to use. This must be initialized and bound to a group, the latter usually by mbedtls_ecdh_read_params().
olenThe address at which to store the number of Bytes written. This must not be NULL.
bufThe destination buffer. This must be a writable buffer of length blen Bytes.
blenThe size of the destination buffer buf in Bytes.
f_rngThe RNG function to use. This must not be NULL.
p_rngThe RNG context to be passed to f_rng. This may be NULL in case f_rng doesn't need a context argument.
Returns
0 on success.
MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see mbedtls_ecp_set_max_ops().
Another MBEDTLS_ERR_ECP_XXX error code on failure.
int mbedtls_ecdh_read_params ( mbedtls_ecdh_context ctx,
const unsigned char **  buf,
const unsigned char *  end 
)

This function parses the ECDHE parameters in a TLS ServerKeyExchange handshake message.

Note
In a TLS handshake, this is the how the client sets up its ECDHE context from the server's public ECDHE key material.
See Also
ecp.h
Parameters
ctxThe ECDHE context to use. This must be initialized.
bufOn input, *buf must be the start of the input buffer. On output, *buf 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.
endThe end of the input buffer.
Returns
0 on success.
An MBEDTLS_ERR_ECP_XXX error code on failure.
int mbedtls_ecdh_read_public ( mbedtls_ecdh_context ctx,
const unsigned char *  buf,
size_t  blen 
)

This function parses and processes the ECDHE payload of a TLS ClientKeyExchange message.

This is the third function used by a TLS server for ECDH(E) ciphersuites. (It is called after mbedtls_ecdh_setup() and mbedtls_ecdh_make_params().)

See Also
ecp.h
Parameters
ctxThe ECDH context to use. This must be initialized and bound to a group, for example via mbedtls_ecdh_setup().
bufThe pointer to the ClientKeyExchange payload. This must be a readable buffer of length blen Bytes.
blenThe length of the input buffer buf in Bytes.
Returns
0 on success.
An MBEDTLS_ERR_ECP_XXX error code on failure.
int mbedtls_ecdh_setup ( mbedtls_ecdh_context ctx,
mbedtls_ecp_group_id  grp_id 
)

This function sets up the ECDH context with the information given.

This function should be called after mbedtls_ecdh_init() but before mbedtls_ecdh_make_params(). There is no need to call this function before mbedtls_ecdh_read_params().

This is the first function used by a TLS server for ECDHE ciphersuites.

Parameters
ctxThe ECDH context to set up. This must be initialized.
grp_idThe group id of the group to set up the context for.
Returns
0 on success.