File ecjpake.h

Elliptic curve J-PAKE.

Typedefs

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

Enums

enum mbedtls_ecjpake_role

Roles in the EC J-PAKE exchange

Values:

enumerator MBEDTLS_ECJPAKE_CLIENT

Client

enumerator MBEDTLS_ECJPAKE_SERVER

Server

enumerator MBEDTLS_ECJPAKE_NONE

Undefined

Functions

void mbedtls_ecjpake_init(mbedtls_ecjpake_context *ctx)

Initialize an ECJPAKE context.

Parameters:

ctx – The ECJPAKE context to initialize. This must not be NULL.

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)

Set up an ECJPAKE context for use.

Note

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

Parameters:

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

Returns:

0 if successful.

Returns:

A negative error code on failure.

int mbedtls_ecjpake_set_point_format(mbedtls_ecjpake_context *ctx, int point_format)

Set the point format for future reads and writes.

Parameters:
Returns:

0 if successful.

Returns:

MBEDTLS_ERR_ECP_BAD_INPUT_DATA if point_format is invalid.

int mbedtls_ecjpake_check(const mbedtls_ecjpake_context *ctx)

Check if an ECJPAKE context is ready for use.

Parameters:

ctx – The ECJPAKE context to check. This must be initialized.

Returns:

0 if the context is ready for use.

Returns:

MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise.

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)

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

Parameters:

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

Returns:

0 if successful.

Returns:

A negative error code on failure.

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

Parameters:

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

Returns:

0 if successful.

Returns:

A negative error code on failure.

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)

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

Parameters:

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

Returns:

0 if successful.

Returns:

A negative error code on failure.

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

Parameters:

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

Returns:

0 if successful.

Returns:

A negative error code on failure.

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)

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

Parameters:

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

Returns:

0 if successful.

Returns:

A negative error code on failure.

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)

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

Parameters:

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

Returns:

0 if successful.

Returns:

A negative error code on failure.

void mbedtls_ecjpake_free(mbedtls_ecjpake_context *ctx)

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

Parameters:

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 mbedtls_ecjpake_self_test(int verbose)

Checkup routine.

Returns:

0 if successful, or 1 if a test failed

struct mbedtls_ecjpake_context
#include <ecjpake.h>

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

Public Members

mbedtls_md_type_t private_md_type

Hash to use

mbedtls_ecp_group private_grp

Elliptic curve

mbedtls_ecjpake_role private_role

Are we client or server?

int private_point_format

Format for point export

mbedtls_ecp_point private_Xm1

My public key 1 C: X1, S: X3

mbedtls_ecp_point private_Xm2

My public key 2 C: X2, S: X4

mbedtls_ecp_point private_Xp1

Peer public key 1 C: X3, S: X1

mbedtls_ecp_point private_Xp2

Peer public key 2 C: X4, S: X2

mbedtls_ecp_point private_Xp

Peer public key C: Xs, S: Xc

mbedtls_mpi private_xm1

My private key 1 C: x1, S: x3

mbedtls_mpi private_xm2

My private key 2 C: x2, S: x4

mbedtls_mpi private_s

Pre-shared secret (passphrase)