ecdh.h File Reference

Elliptic curve Diffie-Hellman. 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
| 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...

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

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