ecdh.h
mbedtls/private_access.h
mbedtls/build_info.h
mbedtls/ecp.h
ssl.h
mbedtls/bignum.h
mbedtls/build_info.h
mbedtls/check_config.h
mbedtls/config_adjust_legacy_crypto.h
mbedtls/config_adjust_psa_from_legacy.h
mbedtls/config_adjust_psa_superset_legacy.h
mbedtls/config_adjust_ssl.h
mbedtls/config_adjust_x509.h
mbedtls/config_psa.h
ecdh.h
mbedtls/ecp.h
mbedtls/mbedtls_config.h
mbedtls/platform_time.h
mbedtls/platform_util.h
mbedtls/private_access.h
psa/crypto_adjust_auto_enabled.h
psa/crypto_adjust_config_dependencies.h
psa/crypto_adjust_config_key_pair_types.h
psa/crypto_adjust_config_synonyms.h
psa/crypto_legacy.h
inttypes.h
limits.h
stddef.h
stdint.h
stdio.h
time.h
debug.h
ecdh.h
net_sockets.h
ssl.h
ssl_cache.h
ssl_cookie.h
ssl_ticket.h
mbedtls_ecdh_context_mbed
mbedtls_ecdh_context
mbedtls_ecdh_side
MBEDTLS_ECDH_OURS

Our key.

MBEDTLS_ECDH_THEIRS

The key of the peer.

Defines the source of the imported EC key.

mbedtls_ecdh_variant
MBEDTLS_ECDH_VARIANT_NONE
= 0

Implementation not defined.

MBEDTLS_ECDH_VARIANT_MBEDTLS_2_0

The default Mbed TLS implementation

Defines the ECDH implementation used.

Later versions of the library may add new variants, therefore users should not make any assumptions about them.

struct mbedtls_ecdh_context_mbed typedef struct mbedtls_ecdh_context_mbed mbedtls_ecdh_context_mbed mbedtls_ecdh_context_mbed

The context used by the default ECDH implementation.

Later versions might change the structure of this context, therefore users should not make any assumptions about the structure of mbedtls_ecdh_context_mbed.

struct mbedtls_ecdh_context typedef struct mbedtls_ecdh_context mbedtls_ecdh_context mbedtls_ecdh_context

The ECDH context structure.

Performing multiple operations concurrently on the same ECDSA context is not supported; objects of this type should not be shared between multiple threads.

mbedtls_ecp_group_id mbedtls_ecp_group_id mbedtls_ecdh_get_grp_id (mbedtls_ecdh_context *ctx) mbedtls_ecdh_get_grp_id mbedtls_ecdh_context * ctx

Return the ECP group for provided context.

To access group specific fields, users should use `mbedtls_ecp_curve_info_from_grp_id` or `mbedtls_ecp_group_load` on the extracted `group_id`.

ctx

The ECDH context to parse. This must not be `NULL`.

The `mbedtls_ecp_group_id` of the context.

int int mbedtls_ecdh_can_do (mbedtls_ecp_group_id gid) mbedtls_ecdh_can_do mbedtls_ecp_group_id gid

Check whether a given group can be used for ECDH.

gid

The ECP group ID to check.

`1` if the group can be used, `0` otherwise

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

ecp.h

grp

The ECP group to use. This must be initialized and have domain parameters loaded, for example through mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().

d

The destination MPI (private key). This must be initialized.

Q

The destination point (public key). This must be initialized.

f_rng

The RNG function to use. This must not be `NULL`.

p_rng

The RNG context to be passed to `f_rng`. This may be `NULL` in case `f_rng` doesn't need a context argument.

`0` on success.

Another `MBEDTLS_ERR_ECP_XXX` or `MBEDTLS_MPI_XXX` error code on failure.

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

ecp.h

If `f_rng` is not NULL, it is used to implement countermeasures against side-channel attacks. For more information, see mbedtls_ecp_mul().

grp

The ECP group to use. This must be initialized and have domain parameters loaded, for example through mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().

z

The destination MPI (shared secret). This must be initialized.

Q

The public key from another party. This must be initialized.

d

Our secret exponent (private key). This must be initialized.

f_rng

The RNG function to use. This must not be `NULL`.

p_rng

The RNG context to be passed to `f_rng`. This may be `NULL` if `f_rng` is `NULL` or doesn't need a context argument.

`0` on success.

Another `MBEDTLS_ERR_ECP_XXX` or `MBEDTLS_MPI_XXX` error code on failure.

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

This function initializes an ECDH context.

ctx

The ECDH context to initialize. This must not be `NULL`.

int int mbedtls_ecdh_setup (mbedtls_ecdh_context *ctx, mbedtls_ecp_group_id grp_id) mbedtls_ecdh_setup mbedtls_ecdh_context * ctx mbedtls_ecp_group_id grp_id

This function sets up the ECDH context with the information given.

This function should be called after mbedtls_ecdh_init() but before mbedtls_ecdh_make_params(). There is no need to call this function before mbedtls_ecdh_read_params().

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

ctx

The ECDH context to set up. This must be initialized.

grp_id

The group id of the group to set up the context for.

`0` on success.

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

This function frees a context.

ctx

The context to free. This may be `NULL`, in which case this function does nothing. If it is not `NULL`, it must point to an initialized ECDH context.

int 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) 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 an EC key pair and exports its in the format used in a TLS ServerKeyExchange handshake message.

This is the second function used by a TLS server for ECDHE ciphersuites. (It is called after mbedtls_ecdh_setup().)

ecp.h

ctx

The ECDH context to use. This must be initialized and bound to a group, for example via mbedtls_ecdh_setup().

olen

The address at which to store the number of Bytes written.

buf

The destination buffer. This must be a writable buffer of length `blen` Bytes.

blen

The length of the destination buffer `buf` in Bytes.

f_rng

The RNG function to use. This must not be `NULL`.

p_rng

The RNG context to be passed to `f_rng`. This may be `NULL` in case `f_rng` doesn't need a context argument.

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

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

This function parses the ECDHE parameters in a TLS ServerKeyExchange handshake message.

In a TLS handshake, this is the how the client sets up its ECDHE context from the server's public ECDHE key material.

ecp.h

ctx

The ECDHE context to use. This must be initialized.

buf

On input, `*buf` must be the start of the input buffer. On output, `*buf` is updated to point to the end of the data that has been read. On success, this is the first byte past the end of the ServerKeyExchange parameters. On error, this is the point at which an error has been detected, which is usually not useful except to debug failures.

end

The end of the input buffer.

`0` on success.

An `MBEDTLS_ERR_ECP_XXX` error code on failure.

int int mbedtls_ecdh_get_params (mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key, mbedtls_ecdh_side side) 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 ServerKeyExchange for static ECDH, and imports ECDH parameters from the EC key information of a certificate.

ecp.h

ctx

The ECDH context to set up. This must be initialized.

key

The EC key to use. This must be initialized.

side

Defines the source of the key. Possible values are:

- MBEDTLS_ECDH_OURS: The key is ours.

- MBEDTLS_ECDH_THEIRS: The key is that of the peer.

`0` on success.

Another `MBEDTLS_ERR_ECP_XXX` error code on failure.

int 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) 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 exports it as a TLS ClientKeyExchange payload.

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

ecp.h

ctx

The ECDH context to use. This must be initialized and bound to a group, the latter usually by mbedtls_ecdh_read_params().

olen

The address at which to store the number of Bytes written. This must not be `NULL`.

buf

The destination buffer. This must be a writable buffer of length `blen` Bytes.

blen

The size of the destination buffer `buf` in Bytes.

f_rng

The RNG function to use. This must not be `NULL`.

p_rng

The RNG context to be passed to `f_rng`. This may be `NULL` in case `f_rng` doesn't need a context argument.

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

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

This function parses and processes the ECDHE payload of a TLS ClientKeyExchange message.

This is the third function used by a TLS server for ECDH(E) ciphersuites. (It is called after mbedtls_ecdh_setup() and mbedtls_ecdh_make_params().)

ecp.h

ctx

The ECDH context to use. This must be initialized and bound to a group, for example via mbedtls_ecdh_setup().

buf

The pointer to the ClientKeyExchange payload. This must be a readable buffer of length `blen` Bytes.

blen

The length of the input buffer `buf` in Bytes.

`0` on success.

An `MBEDTLS_ERR_ECP_XXX` error code on failure.

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

If `f_rng` is not NULL, it is used to implement countermeasures against side-channel attacks. For more information, see mbedtls_ecp_mul().

ecp.h

ctx

The ECDH context to use. This must be initialized and have its own private key generated and the peer's public key imported.

olen

The address at which to store the total number of Bytes written on success. This must not be `NULL`.

buf

The buffer to write the generated shared key to. This must be a writable buffer of size `blen` Bytes.

blen

The length of the destination buffer `buf` in Bytes.

f_rng

The RNG function to use. This must not be `NULL`.

p_rng

The RNG context. This may be `NULL` if `f_rng` doesn't need a context argument.

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

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.

    /*
    *CopyrightTheMbedTLSContributors
    *SPDX-License-Identifier:Apache-2.0ORGPL-2.0-or-later
    */

    #ifndefMBEDTLS_ECDH_H
    #defineMBEDTLS_ECDH_H
    #include"mbedtls/private_access.h"

    #include"mbedtls/build_info.h"

    #include"mbedtls/ecp.h"

    /*
    *MbedTLSsupportstwoformatsforECDHcontexts(#mbedtls_ecdh_context
    *definedin`ecdh.h`).Formostapplications,thechoiceofformatmakes
    *nodifference,sincealllibraryfunctionscanworkwitheitherformat,
    *exceptthatthenewformatisincompatiblewithMBEDTLS_ECP_RESTARTABLE.

    *Thenewformatusedwhenthisoptionisdisabledissmaller
    *(56bytesona32-bitplatform).Infutureversionsofthelibrary,it
    *willsupportalternativeimplementationsofECDHoperations.
    *Thenewformatisincompatiblewithapplicationsthataccess
    *contextfieldsdirectlyandwithrestartableECPoperations.
    */

    #ifdefined(MBEDTLS_ECP_RESTARTABLE)
    #defineMBEDTLS_ECDH_LEGACY_CONTEXT
    #else
    #undefMBEDTLS_ECDH_LEGACY_CONTEXT
    #endif

    #ifdefined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED)
    #undefMBEDTLS_ECDH_LEGACY_CONTEXT
    #include"everest/everest.h"
    #endif

    #ifdef__cplusplus
    extern"C"{
    #endif

    typedefenum{
    MBEDTLS_ECDH_OURS,
    MBEDTLS_ECDH_THEIRS,
    }mbedtls_ecdh_side;

    #if!defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
    typedefenum{
    MBEDTLS_ECDH_VARIANT_NONE=0,
    MBEDTLS_ECDH_VARIANT_MBEDTLS_2_0,
    #ifdefined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED)
    MBEDTLS_ECDH_VARIANT_EVEREST
    #endif
    }mbedtls_ecdh_variant;

    typedefstructmbedtls_ecdh_context_mbed{
    mbedtls_ecp_groupMBEDTLS_PRIVATE(grp);
    mbedtls_mpiMBEDTLS_PRIVATE(d);
    mbedtls_ecp_pointMBEDTLS_PRIVATE(Q);
    mbedtls_ecp_pointMBEDTLS_PRIVATE(Qp);
    mbedtls_mpiMBEDTLS_PRIVATE(z);
    #ifdefined(MBEDTLS_ECP_RESTARTABLE)
    mbedtls_ecp_restart_ctxMBEDTLS_PRIVATE(rs);
    #endif
    }mbedtls_ecdh_context_mbed;
    #endif

    typedefstructmbedtls_ecdh_context{
    #ifdefined(MBEDTLS_ECDH_LEGACY_CONTEXT)
    mbedtls_ecp_groupMBEDTLS_PRIVATE(grp);
    mbedtls_mpiMBEDTLS_PRIVATE(d);
    mbedtls_ecp_pointMBEDTLS_PRIVATE(Q);
    mbedtls_ecp_pointMBEDTLS_PRIVATE(Qp);
    mbedtls_mpiMBEDTLS_PRIVATE(z);
    intMBEDTLS_PRIVATE(point_format);
    mbedtls_ecp_pointMBEDTLS_PRIVATE(Vi);
    mbedtls_ecp_pointMBEDTLS_PRIVATE(Vf);
    mbedtls_mpiMBEDTLS_PRIVATE(_d);
    #ifdefined(MBEDTLS_ECP_RESTARTABLE)
    intMBEDTLS_PRIVATE(restart_enabled);
    mbedtls_ecp_restart_ctxMBEDTLS_PRIVATE(rs);
    #endif/*MBEDTLS_ECP_RESTARTABLE*/
    #else
    uint8_tMBEDTLS_PRIVATE(point_format);
    mbedtls_ecp_group_idMBEDTLS_PRIVATE(grp_id);
    mbedtls_ecdh_variantMBEDTLS_PRIVATE(var);
    union{
    mbedtls_ecdh_context_mbedMBEDTLS_PRIVATE(mbed_ecdh);
    #ifdefined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED)
    mbedtls_ecdh_context_everestMBEDTLS_PRIVATE(everest_ecdh);
    #endif
    }MBEDTLS_PRIVATE(ctx);
    #ifdefined(MBEDTLS_ECP_RESTARTABLE)
    uint8_tMBEDTLS_PRIVATE(restart_enabled);
    #endif/*MBEDTLS_ECP_RESTARTABLE*/
    #endif/*MBEDTLS_ECDH_LEGACY_CONTEXT*/
    }
    mbedtls_ecdh_context;

    mbedtls_ecp_group_idmbedtls_ecdh_get_grp_id(mbedtls_ecdh_context*ctx);

    intmbedtls_ecdh_can_do(mbedtls_ecp_group_idgid);

    intmbedtls_ecdh_gen_public(mbedtls_ecp_group*grp,mbedtls_mpi*d,mbedtls_ecp_point*Q,
    int(*f_rng)(void*,unsignedchar*,size_t),
    void*p_rng);

    intmbedtls_ecdh_compute_shared(mbedtls_ecp_group*grp,mbedtls_mpi*z,
    constmbedtls_ecp_point*Q,constmbedtls_mpi*d,
    int(*f_rng)(void*,unsignedchar*,size_t),
    void*p_rng);

    voidmbedtls_ecdh_init(mbedtls_ecdh_context*ctx);

    intmbedtls_ecdh_setup(mbedtls_ecdh_context*ctx,
    mbedtls_ecp_group_idgrp_id);

    voidmbedtls_ecdh_free(mbedtls_ecdh_context*ctx);

    intmbedtls_ecdh_make_params(mbedtls_ecdh_context*ctx,size_t*olen,
    unsignedchar*buf,size_tblen,
    int(*f_rng)(void*,unsignedchar*,size_t),
    void*p_rng);

    intmbedtls_ecdh_read_params(mbedtls_ecdh_context*ctx,
    constunsignedchar**buf,
    constunsignedchar*end);

    intmbedtls_ecdh_get_params(mbedtls_ecdh_context*ctx,
    constmbedtls_ecp_keypair*key,
    mbedtls_ecdh_sideside);

    intmbedtls_ecdh_make_public(mbedtls_ecdh_context*ctx,size_t*olen,
    unsignedchar*buf,size_tblen,
    int(*f_rng)(void*,unsignedchar*,size_t),
    void*p_rng);

    intmbedtls_ecdh_read_public(mbedtls_ecdh_context*ctx,
    constunsignedchar*buf,size_tblen);

    intmbedtls_ecdh_calc_secret(mbedtls_ecdh_context*ctx,size_t*olen,
    unsignedchar*buf,size_tblen,
    int(*f_rng)(void*,unsignedchar*,size_t),
    void*p_rng);

    #ifdefined(MBEDTLS_ECP_RESTARTABLE)
    voidmbedtls_ecdh_enable_restart(mbedtls_ecdh_context*ctx);
    #endif/*MBEDTLS_ECP_RESTARTABLE*/

    #ifdef__cplusplus
    }
    #endif

    #endif/*ecdh.h*/