mbed TLS v2.14.1

Data Structures | Typedefs | Enumerations | Functions
ecdh.h File Reference

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

`#include "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...

## 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_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...
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 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)
| This function parses and processes a TLS ServerKeyExhange payload. 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 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 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)
| This function derives and exports the shared secret. 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.

## Typedef Documentation

## ◆ mbedtls_ecdh_context

typedef struct mbedtls_ecdh_context mbedtls_ecdh_context

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

## ◆ mbedtls_ecdh_side

enum mbedtls_ecdh_side

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 46 of file ecdh.h.

## Function Documentation

## ◆ mbedtls_ecdh_calc_secret()

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

  ctx | The ECDH context.
  olen | The number of Bytes written.
  buf | The destination buffer.
  blen | The length of the destination buffer.
  f_rng | The RNG function.
  p_rng | The RNG context.

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.

## ◆ mbedtls_ecdh_compute_shared()

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

  grp | The ECP group.
  z | The destination MPI (shared secret).
  Q | The public key from another party.
  d | Our secret exponent (private key).
  f_rng | The RNG function.
  p_rng | The RNG context.

Returns
  `0` on success.
  Another `MBEDTLS_ERR_ECP_XXX` or `MBEDTLS_MPI_XXX` error code on failure.

## ◆ mbedtls_ecdh_free()

void mbedtls_ecdh_free | ( | mbedtls_ecdh_context * | ctx | ) |

This function frees a context.

Parameters

  ctx | The context to free.

## ◆ mbedtls_ecdh_gen_public()

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

  grp | The ECP group.
  d | The destination MPI (private key).
  Q | The destination point (public key).
  f_rng | The RNG function.
  p_rng | The RNG context.

Returns
  `0` on success.
  Another `MBEDTLS_ERR_ECP_XXX` or `MBEDTLS_MPI_XXX` error code on failure.

## ◆ mbedtls_ecdh_get_params()

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

  ctx | The ECDH context to set up.
  key | The EC key to use.
  side | Defines the source of the key: 1: Our key, or 0: The key of the peer.

Returns
  `0` on success.
  Another `MBEDTLS_ERR_ECP_XXX` error code on failure.

## ◆ mbedtls_ecdh_init()

void mbedtls_ecdh_init | ( | mbedtls_ecdh_context * | ctx | ) |

This function initializes an ECDH context.

Parameters

  ctx | The ECDH context to initialize.

## ◆ mbedtls_ecdh_make_params()

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 a public key and a TLS ServerKeyExchange payload.

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

Note
  This function assumes that the ECP group (grp) of the `ctx` context has already been properly set, for example, using mbedtls_ecp_group_load().

See also
  ecp.h

Parameters

  ctx | The ECDH context.
  olen | The number of characters written.
  buf | The destination buffer.
  blen | The length of the destination buffer.
  f_rng | The RNG function.
  p_rng | The RNG context.

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.

## ◆ mbedtls_ecdh_make_public()

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 a TLS ClientKeyExchange payload.

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

See also
  ecp.h

Parameters

  ctx | The ECDH context.
  olen | The number of Bytes written.
  buf | The destination buffer.
  blen | The size of the destination buffer.
  f_rng | The RNG function.
  p_rng | The RNG context.

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.

## ◆ mbedtls_ecdh_read_params()

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

This function parses and processes a TLS ServerKeyExhange payload.

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

See also
  ecp.h

Parameters

  ctx | The ECDH context.
  buf | The pointer to the start of the input buffer.
  end | The address for one Byte past the end of the buffer.

Returns
  `0` on success.
  An `MBEDTLS_ERR_ECP_XXX` error code on failure.

## ◆ mbedtls_ecdh_read_public()

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

This function parses and processes a TLS ClientKeyExchange payload.

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

See also
  ecp.h

Parameters

  ctx | The ECDH context.
  buf | The start of the input buffer.
  blen | The length of the input buffer.

Returns
  `0` on success.
  An `MBEDTLS_ERR_ECP_XXX` error code on failure.