ecjpake.h
mbedtls/private_access.h
mbedtls/build_info.h
mbedtls/ecp.h
mbedtls/md.h
crypto_builtin_composites.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
ecjpake.h
mbedtls/ecp.h
mbedtls/mbedtls_config.h
mbedtls/md.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
ecjpake.h
net_sockets.h
oid.h
pk.h
pkcs7.h
psa_util.h
ssl.h
ssl_cache.h
ssl_ciphersuites.h
ssl_cookie.h
ssl_ticket.h
x509.h
x509_crl.h
x509_crt.h
x509_csr.h
crypto.h
crypto_builtin_composites.h
crypto_driver_contexts_composites.h
crypto_struct.h
mbedtls_ecjpake_context
mbedtls_ecjpake_role
MBEDTLS_ECJPAKE_CLIENT
= 0

Client

MBEDTLS_ECJPAKE_SERVER

Server

MBEDTLS_ECJPAKE_NONE

Undefined

Roles in the EC J-PAKE exchange

struct mbedtls_ecjpake_context typedef struct mbedtls_ecjpake_context mbedtls_ecjpake_context mbedtls_ecjpake_context

EC J-PAKE context structure.

J-PAKE is a symmetric protocol, except for the identifiers used in Zero-Knowledge Proofs, and the serialization of the second message (KeyExchange) as defined by the Thread spec.

In order to benefit from this symmetry, we choose a different naming convention from the Thread v1.0 spec. Correspondence is indicated in the description as a pair C: client name, S: server name

void void mbedtls_ecjpake_init (mbedtls_ecjpake_context *ctx) mbedtls_ecjpake_init mbedtls_ecjpake_context * ctx

Initialize an ECJPAKE context.

ctx

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

int int mbedtls_ecjpake_setup (mbedtls_ecjpake_context *ctx, mbedtls_ecjpake_role role, mbedtls_md_type_t hash, mbedtls_ecp_group_id curve, const unsigned char *secret, size_t len) mbedtls_ecjpake_setup mbedtls_ecjpake_context * ctx mbedtls_ecjpake_role role mbedtls_md_type_t hash mbedtls_ecp_group_id curve const unsigned char * secret size_t len

Set up an ECJPAKE context for use.

Currently the only values for hash/curve allowed by the standard are MBEDTLS_MD_SHA256/MBEDTLS_ECP_DP_SECP256R1.

ctx

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

role

The role of the caller. This must be either MBEDTLS_ECJPAKE_CLIENT or MBEDTLS_ECJPAKE_SERVER.

hash

The identifier of the hash function to use, for example MBEDTLS_MD_SHA256.

curve

The identifier of the elliptic curve to use, for example MBEDTLS_ECP_DP_SECP256R1.

secret

The pre-shared secret (passphrase). This must be a readable not empty buffer of length `len` Bytes. It need only be valid for the duration of this call.

len

The length of the pre-shared secret `secret`.

`0` if successful.

A negative error code on failure.

int int mbedtls_ecjpake_set_point_format (mbedtls_ecjpake_context *ctx, int point_format) mbedtls_ecjpake_set_point_format mbedtls_ecjpake_context * ctx int point_format

Set the point format for future reads and writes.

ctx

The ECJPAKE context to configure.

point_format

The point format to use: MBEDTLS_ECP_PF_UNCOMPRESSED (default) or MBEDTLS_ECP_PF_COMPRESSED.

`0` if successful.

MBEDTLS_ERR_ECP_BAD_INPUT_DATA if `point_format` is invalid.

int int mbedtls_ecjpake_check (const mbedtls_ecjpake_context *ctx) mbedtls_ecjpake_check const mbedtls_ecjpake_context * ctx

Check if an ECJPAKE context is ready for use.

ctx

The ECJPAKE context to check. This must be initialized.

`0` if the context is ready for use.

MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise.

int int mbedtls_ecjpake_write_round_one (mbedtls_ecjpake_context *ctx, unsigned char *buf, size_t len, size_t *olen, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng) mbedtls_ecjpake_write_round_one mbedtls_ecjpake_context * ctx unsigned char * buf size_t len size_t * olen int(*)(void *, unsigned char *, size_t) f_rng void * p_rng

Generate and write the first round message (TLS: contents of the Client/ServerHello extension, excluding extension type and length bytes).

ctx

The ECJPAKE context to use. This must be initialized and set up.

buf

The buffer to write the contents to. This must be a writable buffer of length `len` Bytes.

len

The length of `buf` in Bytes.

olen

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

f_rng

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

p_rng

The RNG parameter to be passed to `f_rng`. This may be `NULL` if `f_rng` doesn't use a context.

`0` if successful.

A negative error code on failure.

int int mbedtls_ecjpake_read_round_one (mbedtls_ecjpake_context *ctx, const unsigned char *buf, size_t len) mbedtls_ecjpake_read_round_one mbedtls_ecjpake_context * ctx const unsigned char * buf size_t len

Read and process the first round message (TLS: contents of the Client/ServerHello extension, excluding extension type and length bytes).

ctx

The ECJPAKE context to use. This must be initialized and set up.

buf

The buffer holding the first round message. This must be a readable buffer of length `len` Bytes.

len

The length in Bytes of `buf`.

`0` if successful.

A negative error code on failure.

int int mbedtls_ecjpake_write_round_two (mbedtls_ecjpake_context *ctx, unsigned char *buf, size_t len, size_t *olen, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng) mbedtls_ecjpake_write_round_two mbedtls_ecjpake_context * ctx unsigned char * buf size_t len size_t * olen int(*)(void *, unsigned char *, size_t) f_rng void * p_rng

Generate and write the second round message (TLS: contents of the Client/ServerKeyExchange).

ctx

The ECJPAKE context to use. This must be initialized, set up, and already have performed round one.

buf

The buffer to write the round two contents to. This must be a writable buffer of length `len` Bytes.

len

The size of `buf` in Bytes.

olen

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

f_rng

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

p_rng

The RNG parameter to be passed to `f_rng`. This may be `NULL` if `f_rng` doesn't use a context.

`0` if successful.

A negative error code on failure.

int int mbedtls_ecjpake_read_round_two (mbedtls_ecjpake_context *ctx, const unsigned char *buf, size_t len) mbedtls_ecjpake_read_round_two mbedtls_ecjpake_context * ctx const unsigned char * buf size_t len

Read and process the second round message (TLS: contents of the Client/ServerKeyExchange).

ctx

The ECJPAKE context to use. This must be initialized and set up and already have performed round one.

buf

The buffer holding the second round message. This must be a readable buffer of length `len` Bytes.

len

The length in Bytes of `buf`.

`0` if successful.

A negative error code on failure.

int int mbedtls_ecjpake_derive_secret (mbedtls_ecjpake_context *ctx, unsigned char *buf, size_t len, size_t *olen, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng) mbedtls_ecjpake_derive_secret mbedtls_ecjpake_context * ctx unsigned char * buf size_t len size_t * olen int(*)(void *, unsigned char *, size_t) f_rng void * p_rng

Derive the shared secret (TLS: Pre-Master Secret).

ctx

The ECJPAKE context to use. This must be initialized, set up and have performed both round one and two.

buf

The buffer to write the derived secret to. This must be a writable buffer of length `len` Bytes.

len

The length of `buf` in Bytes.

olen

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

f_rng

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

p_rng

The RNG parameter to be passed to `f_rng`. This may be `NULL` if `f_rng` doesn't use a context.

`0` if successful.

A negative error code on failure.

int int mbedtls_ecjpake_write_shared_key (mbedtls_ecjpake_context *ctx, unsigned char *buf, size_t len, size_t *olen, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng) mbedtls_ecjpake_write_shared_key mbedtls_ecjpake_context * ctx unsigned char * buf size_t len size_t * olen int(*)(void *, unsigned char *, size_t) f_rng void * p_rng

Write the shared key material to be passed to a Key Derivation Function as described in RFC8236.

ctx

The ECJPAKE context to use. This must be initialized, set up and have performed both round one and two.

buf

The buffer to write the derived secret to. This must be a writable buffer of length `len` Bytes.

len

The length of `buf` in Bytes.

olen

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

f_rng

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

p_rng

The RNG parameter to be passed to `f_rng`. This may be `NULL` if `f_rng` doesn't use a context.

`0` if successful.

A negative error code on failure.

void void mbedtls_ecjpake_free (mbedtls_ecjpake_context *ctx) mbedtls_ecjpake_free mbedtls_ecjpake_context * ctx

This clears an ECJPAKE context and frees any embedded data structure.

ctx

The ECJPAKE 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 ECJPAKE context.

int int mbedtls_ecjpake_self_test (int verbose) mbedtls_ecjpake_self_test int verbose

Checkup routine.

0 if successful, or 1 if a test failed

Elliptic curve J-PAKE.

    /*
    *CopyrightTheMbedTLSContributors
    *SPDX-License-Identifier:Apache-2.0ORGPL-2.0-or-later
    */
    #ifndefMBEDTLS_ECJPAKE_H
    #defineMBEDTLS_ECJPAKE_H
    #include"mbedtls/private_access.h"

    /*
    *J-PAKEisapassword-authenticatedkeyexchangethatallowsderivinga
    *strongsharedsecretfroma(potentiallylowentropy)pre-shared
    *passphrase,withforwardsecrecyandmutualauthentication.
    *https://en.wikipedia.org/wiki/Password_Authenticated_Key_Exchange_by_Juggling
    *
    *ThisfileimplementstheEllipticCurvevariantofJ-PAKE,
    *asdefinedinChapter7.4oftheThreadv1.0Specification,
    *availabletomembersoftheThreadGrouphttp://threadgroup.org/
    *
    *AstheJ-PAKEalgorithmisinherentlysymmetric,soisourAPI.
    *Eachpartyneedstosenditsfirstroundmessage,inanyorder,tothe
    *otherparty,theneachsendsitssecondroundmessage,inanyorder.
    *ThepayloadsareserializedinawaysuitableforuseinTLS,butcould
    *alsobeuseoutsideTLS.
    */
    #include"mbedtls/build_info.h"

    #include"mbedtls/ecp.h"
    #include"mbedtls/md.h"

    #ifdef__cplusplus
    extern"C"{
    #endif

    typedefenum{
    MBEDTLS_ECJPAKE_CLIENT=0,
    MBEDTLS_ECJPAKE_SERVER,
    MBEDTLS_ECJPAKE_NONE,
    }mbedtls_ecjpake_role;

    #if!defined(MBEDTLS_ECJPAKE_ALT)
    typedefstructmbedtls_ecjpake_context{
    mbedtls_md_type_tMBEDTLS_PRIVATE(md_type);
    mbedtls_ecp_groupMBEDTLS_PRIVATE(grp);
    mbedtls_ecjpake_roleMBEDTLS_PRIVATE(role);
    intMBEDTLS_PRIVATE(point_format);
    mbedtls_ecp_pointMBEDTLS_PRIVATE(Xm1);
    mbedtls_ecp_pointMBEDTLS_PRIVATE(Xm2);
    mbedtls_ecp_pointMBEDTLS_PRIVATE(Xp1);
    mbedtls_ecp_pointMBEDTLS_PRIVATE(Xp2);
    mbedtls_ecp_pointMBEDTLS_PRIVATE(Xp);
    mbedtls_mpiMBEDTLS_PRIVATE(xm1);
    mbedtls_mpiMBEDTLS_PRIVATE(xm2);
    mbedtls_mpiMBEDTLS_PRIVATE(s);
    }mbedtls_ecjpake_context;

    #else/*MBEDTLS_ECJPAKE_ALT*/
    #include"ecjpake_alt.h"
    #endif/*MBEDTLS_ECJPAKE_ALT*/

    voidmbedtls_ecjpake_init(mbedtls_ecjpake_context*ctx);

    intmbedtls_ecjpake_setup(mbedtls_ecjpake_context*ctx,
    mbedtls_ecjpake_rolerole,
    mbedtls_md_type_thash,
    mbedtls_ecp_group_idcurve,
    constunsignedchar*secret,
    size_tlen);

    intmbedtls_ecjpake_set_point_format(mbedtls_ecjpake_context*ctx,
    intpoint_format);

    intmbedtls_ecjpake_check(constmbedtls_ecjpake_context*ctx);

    intmbedtls_ecjpake_write_round_one(mbedtls_ecjpake_context*ctx,
    unsignedchar*buf,size_tlen,size_t*olen,
    int(*f_rng)(void*,unsignedchar*,size_t),
    void*p_rng);

    intmbedtls_ecjpake_read_round_one(mbedtls_ecjpake_context*ctx,
    constunsignedchar*buf,
    size_tlen);

    intmbedtls_ecjpake_write_round_two(mbedtls_ecjpake_context*ctx,
    unsignedchar*buf,size_tlen,size_t*olen,
    int(*f_rng)(void*,unsignedchar*,size_t),
    void*p_rng);

    intmbedtls_ecjpake_read_round_two(mbedtls_ecjpake_context*ctx,
    constunsignedchar*buf,
    size_tlen);

    intmbedtls_ecjpake_derive_secret(mbedtls_ecjpake_context*ctx,
    unsignedchar*buf,size_tlen,size_t*olen,
    int(*f_rng)(void*,unsignedchar*,size_t),
    void*p_rng);

    intmbedtls_ecjpake_write_shared_key(mbedtls_ecjpake_context*ctx,
    unsignedchar*buf,size_tlen,size_t*olen,
    int(*f_rng)(void*,unsignedchar*,size_t),
    void*p_rng);

    voidmbedtls_ecjpake_free(mbedtls_ecjpake_context*ctx);

    #ifdefined(MBEDTLS_SELF_TEST)

    intmbedtls_ecjpake_self_test(intverbose);

    #endif/*MBEDTLS_SELF_TEST*/

    #ifdef__cplusplus
    }
    #endif

    #endif/*ecjpake.h*/