mbed TLS  Version 2.9.0
SSL/TLS Library for the Embedded Space
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
ecjpake.h File Reference

Data Structures

struct  mbedtls_ecjpake_context
 EC J-PAKE context structure. More...
 

Enumerations

enum  mbedtls_ecjpake_role {
  MBEDTLS_ECJPAKE_CLIENT = 0,
  MBEDTLS_ECJPAKE_SERVER
}
 Roles in the EC J-PAKE exchange. More...
 

Functions

void mbedtls_ecjpake_init (mbedtls_ecjpake_context *ctx)
 Initialize a context (just makes it ready for setup() or free()). More...
 
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 a context for use. More...
 
int mbedtls_ecjpake_check (const mbedtls_ecjpake_context *ctx)
 Check if a context is ready for use. More...
 
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) More...
 
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) More...
 
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) More...
 
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) More...
 
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) More...
 
void mbedtls_ecjpake_free (mbedtls_ecjpake_context *ctx)
 Free a context's content. More...
 
int mbedtls_ecjpake_self_test (int verbose)
 Checkup routine. More...
 

Description

Elliptic curve J-PAKE.


Data Structure Documentation

struct 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 convetion from the Thread v1.0 spec. Correspondance is indicated in the description as a pair C: client name, S: server name

Data Fields
mbedtls_ecp_group grp Elliptic curve.
const mbedtls_md_info_t * md_info Hash to use.
int point_format Format for point export.
mbedtls_ecjpake_role role Are we client or server?
mbedtls_mpi s Pre-shared secret (passphrase)
mbedtls_ecp_point Xm1 My public key 1 C: X1, S: X3.
mbedtls_mpi xm1 My private key 1 C: x1, S: x3.
mbedtls_ecp_point Xm2 My public key 2 C: X2, S: X4.
mbedtls_mpi xm2 My private key 2 C: x2, S: x4.
mbedtls_ecp_point Xp Peer public key C: Xs, S: Xc.
mbedtls_ecp_point Xp1 Peer public key 1 C: X3, S: X1.
mbedtls_ecp_point Xp2 Peer public key 2 C: X4, S: X2.

Enumeration Type Documentation

Roles in the EC J-PAKE exchange.

Enumerator
MBEDTLS_ECJPAKE_CLIENT 

Client.

MBEDTLS_ECJPAKE_SERVER 

Server.

Function Documentation

int mbedtls_ecjpake_check ( const mbedtls_ecjpake_context ctx)

Check if a context is ready for use.

Parameters
ctxContext to check
Returns
0 if the context is ready for use, MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise
int 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)

Parameters
ctxContext to use
bufBuffer to write the contents to
lenBuffer size
olenWill be updated with the number of bytes written
f_rngRNG function
p_rngRNG parameter
Returns
0 if successfull, a negative error code otherwise
void mbedtls_ecjpake_free ( mbedtls_ecjpake_context ctx)

Free a context's content.

Parameters
ctxcontext to free
void mbedtls_ecjpake_init ( mbedtls_ecjpake_context ctx)

Initialize a context (just makes it ready for setup() or free()).

Parameters
ctxcontext to initialize
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
ctxContext to use
bufPointer to extension contents
lenExtension length
Returns
0 if successfull, a negative error code otherwise
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
ctxContext to use
bufPointer to the message
lenMessage length
Returns
0 if successfull, a negative error code otherwise
int mbedtls_ecjpake_self_test ( int  verbose)

Checkup routine.

Returns
0 if successful, or 1 if a test failed
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 a context for use.

Note
Currently the only values for hash/curve allowed by the standard are MBEDTLS_MD_SHA256/MBEDTLS_ECP_DP_SECP256R1.
Parameters
ctxcontext to set up
roleOur role: client or server
hashhash function to use (MBEDTLS_MD_XXX)
curveelliptic curve identifier (MBEDTLS_ECP_DP_XXX)
secretpre-shared secret (passphrase)
lenlength of the shared secret
Returns
0 if successfull, a negative error code otherwise
int 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)

Parameters
ctxContext to use
bufBuffer to write the contents to
lenBuffer size
olenWill be updated with the number of bytes written
f_rngRNG function
p_rngRNG parameter
Returns
0 if successfull, a negative error code otherwise
int 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)

Parameters
ctxContext to use
bufBuffer to write the contents to
lenBuffer size
olenWill be updated with the number of bytes written
f_rngRNG function
p_rngRNG parameter
Returns
0 if successfull, a negative error code otherwise