ecdh.h File Reference

The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs. 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...

## 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

The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs.

ECDH 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.

## Enumeration Type Documentation

## mbedtls_ecdh_side

enum mbedtls_ecdh_side

Defines the source of the imported EC key:

- Our key.
- The key of the peer.

Enumerator
MBEDTLS_ECDH_OURS |
MBEDTLS_ECDH_THEIRS |

Definition at line 47 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.

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 parameter.

Returns
  `0` on success, or an `MBEDTLS_ERR_ECP_XXX` error code on failure.

See also
  ecp.h

Note
  If `f_rng` is not NULL, it is used to implement countermeasures against potential elaborate timing attacks. For more information, see mbedtls_ecp_mul().

## 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().

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 parameter.

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

See also
  ecp.h

Note
  If `f_rng` is not NULL, it is used to implement countermeasures against potential elaborate timing attacks. For more information, see mbedtls_ecp_mul().

## 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().

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 parameter.

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

See also
  ecp.h

## 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.

Parameters

  ctx | The ECDH context to set up.
  key | The EC key to use.

  side

  Defines the source of the key:
  - 1: Our key.
  - 0: The key of the peer.

Returns
  `0` on success, or an `MBEDTLS_ERR_ECP_XXX` error code on failure.

See also
  ecp.h

## 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.

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 parameter.

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().

Returns
  `0` on success, or an `MBEDTLS_ERR_ECP_XXX` error code on failure.

See also
  ecp.h

## 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.

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 parameter.

Returns
  `0` on success, or an `MBEDTLS_ERR_ECP_XXX` error code on failure.

See also
  ecp.h

## 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.

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, or an `MBEDTLS_ERR_ECP_XXX` error code on failure.

See also
  ecp.h

## 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.

Parameters

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

Returns
  `0` on success, or an `MBEDTLS_ERR_ECP_XXX` error code on failure.

See also
  ecp.h