ecdh.h File Reference

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

#include "config.h"
#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.
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.
void mbedtls_ecdh_init (mbedtls_ecdh_context *ctx)
 This function initializes an ECDH context.
void mbedtls_ecdh_free (mbedtls_ecdh_context *ctx)
 This function frees a context.
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.
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.
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.
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.
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.
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.

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

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

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().
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().
void mbedtls_ecdh_free ( mbedtls_ecdh_context ctx  ) 

This function frees a context.

Parameters:
ctx The 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 
)

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
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
void mbedtls_ecdh_init ( mbedtls_ecdh_context ctx  ) 

This function initializes an ECDH context.

Parameters:
ctx The ECDH 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 
)

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

Generated on 10 Aug 2020 for mbed TLS v2.7.16 by  doxygen 1.6.1