ReactOS  0.4.15-dev-2947-g59e1b78
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.

Classes

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

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

◆ 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
ctxThe ECDH context.
olenThe number of Bytes written.
bufThe destination buffer.
blenThe length of the destination buffer.
f_rngThe RNG function.
p_rngThe 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
grpThe ECP group.
zThe destination MPI (shared secret).
QThe public key from another party.
dOur secret exponent (private key).
f_rngThe RNG function.
p_rngThe 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
ctxThe 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
grpThe ECP group.
dThe destination MPI (private key).
QThe destination point (public key).
f_rngThe RNG function.
p_rngThe 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
ctxThe ECDH context to set up.
keyThe EC key to use.
sideDefines 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
ctxThe 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
ctxThe ECDH context.
olenThe number of characters written.
bufThe destination buffer.
blenThe length of the destination buffer.
f_rngThe RNG function.
p_rngThe 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
ctxThe ECDH context.
olenThe number of Bytes written.
bufThe destination buffer.
blenThe size of the destination buffer.
f_rngThe RNG function.
p_rngThe 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
ctxThe ECDH context.
bufThe pointer to the start of the input buffer.
endThe 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
ctxThe ECDH context.
bufThe start of the input buffer.
blenThe length of the input buffer.
Returns
0 on success, or an MBEDTLS_ERR_ECP_XXX error code on failure.
See also
ecp.h