ecjpake.h File Reference

Elliptic curve J-PAKE. More...

`#include "mbedtls/config.h"`
`#include "mbedtls/ecp.h"`
`#include "mbedtls/md.h"`
Include dependency graph for ecjpake.h:

Go to the source code of this file.

## Data Structures

struct | mbedtls_ecjpake_context

## Typedefs

typedef struct mbedtls_ecjpake_context | mbedtls_ecjpake_context

## Enumerations

enum | mbedtls_ecjpake_role { MBEDTLS_ECJPAKE_CLIENT = 0 , MBEDTLS_ECJPAKE_SERVER }

## Functions

void | mbedtls_ecjpake_init (mbedtls_ecjpake_context *ctx)
| Initialize an ECJPAKE context. 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 an ECJPAKE context for use. More...
int | mbedtls_ecjpake_check (const mbedtls_ecjpake_context *ctx)
| Check if an ECJPAKE 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)
| This clears an ECJPAKE context and frees any embedded data structure. More...
int | mbedtls_ecjpake_self_test (int verbose)
| Checkup routine. More...

## Detailed Description

Elliptic curve J-PAKE.

Definition in file ecjpake.h.

## Typedef Documentation

## mbedtls_ecjpake_context

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

## Enumeration Type Documentation

## mbedtls_ecjpake_role

enum mbedtls_ecjpake_role

Roles in the EC J-PAKE exchange

Enumerator
MBEDTLS_ECJPAKE_CLIENT | Client
MBEDTLS_ECJPAKE_SERVER | Server

Definition at line 57 of file ecjpake.h.

## Function Documentation

## mbedtls_ecjpake_check()

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.
  MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise.

## mbedtls_ecjpake_derive_secret()

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

  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.
  A negative error code on failure.

## mbedtls_ecjpake_free()

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.

## mbedtls_ecjpake_init()

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

Initialize an ECJPAKE context.

Parameters

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

## mbedtls_ecjpake_read_round_one()

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.
  A negative error code on failure.

## mbedtls_ecjpake_read_round_two()

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.
  A negative error code on failure.

## mbedtls_ecjpake_self_test()

int mbedtls_ecjpake_self_test | ( | int | verbose | ) |

Checkup routine.

Returns
  0 if successful, or 1 if a test failed

## mbedtls_ecjpake_setup()

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 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.
  A negative error code on failure.

## mbedtls_ecjpake_write_round_one()

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

  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.
  A negative error code on failure.

## mbedtls_ecjpake_write_round_two()

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

  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.
  A negative error code on failure.