File ecjpake.h
Elliptic curve J-PAKE.
Enums
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
ctx – The ECJPAKE context to configure.
point_format – The point format to use: MBEDTLS_ECP_PF_UNCOMPRESSED (default) or MBEDTLS_ECP_PF_COMPRESSED.
- 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 beNULL
.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 beNULL
iff_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 beNULL
.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 beNULL
iff_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 beNULL
.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 beNULL
iff_rng
doesn’t use a context.
- Returns
0
if successful.- Returns
A negative error code on failure.
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 beNULL
.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 beNULL
iff_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 notNULL
, 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