Loading...
Searching...
No Matches
Password-authenticated key exchange (PAKE)

## Macros

#define | PSA_PAKE_ROLE_NONE ((psa_pake_role_t) 0x00)
#define | PSA_PAKE_ROLE_FIRST ((psa_pake_role_t) 0x01)
#define | PSA_PAKE_ROLE_SECOND ((psa_pake_role_t) 0x02)
#define | PSA_PAKE_ROLE_CLIENT ((psa_pake_role_t) 0x11)
#define | PSA_PAKE_ROLE_SERVER ((psa_pake_role_t) 0x12)
#define | PSA_PAKE_PRIMITIVE_TYPE_ECC ((psa_pake_primitive_type_t) 0x01)
#define | PSA_PAKE_PRIMITIVE_TYPE_DH ((psa_pake_primitive_type_t) 0x02)
#define | PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits)
#define | PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t) 0x01)
#define | PSA_PAKE_STEP_ZK_PUBLIC ((psa_pake_step_t) 0x02)
#define | PSA_PAKE_STEP_ZK_PROOF ((psa_pake_step_t) 0x03)

## Typedefs

typedef uint8_t | psa_pake_role_t
| Encoding of the application role of PAKE.
typedef uint8_t | psa_pake_step_t
typedef uint8_t | psa_pake_primitive_type_t
typedef uint8_t | psa_pake_family_t
| Encoding of the family of the primitive associated with the PAKE.
typedef uint32_t | psa_pake_primitive_t
| Encoding of the primitive associated with the PAKE.
typedef struct psa_pake_cipher_suite_s | psa_pake_cipher_suite_t
typedef struct psa_pake_operation_s | psa_pake_operation_t
typedef struct psa_crypto_driver_pake_inputs_s | psa_crypto_driver_pake_inputs_t
typedef struct psa_jpake_computation_stage_s | psa_jpake_computation_stage_t

## Functions

static psa_pake_cipher_suite_t | psa_pake_cipher_suite_init (void)
static psa_algorithm_t | psa_pake_cs_get_algorithm (const psa_pake_cipher_suite_t *cipher_suite)
static void | psa_pake_cs_set_algorithm (psa_pake_cipher_suite_t *cipher_suite, psa_algorithm_t algorithm)
static psa_pake_primitive_t | psa_pake_cs_get_primitive (const psa_pake_cipher_suite_t *cipher_suite)
static void | psa_pake_cs_set_primitive (psa_pake_cipher_suite_t *cipher_suite, psa_pake_primitive_t primitive)
static psa_pake_family_t | psa_pake_cs_get_family (const psa_pake_cipher_suite_t *cipher_suite)
static uint16_t | psa_pake_cs_get_bits (const psa_pake_cipher_suite_t *cipher_suite)
static psa_algorithm_t | psa_pake_cs_get_hash (const psa_pake_cipher_suite_t *cipher_suite)
static void | psa_pake_cs_set_hash (psa_pake_cipher_suite_t *cipher_suite, psa_algorithm_t hash)
static psa_pake_operation_t | psa_pake_operation_init (void)
psa_status_t | psa_crypto_driver_pake_get_password_len (const psa_crypto_driver_pake_inputs_t *inputs, size_t *password_len)
psa_status_t | psa_crypto_driver_pake_get_password (const psa_crypto_driver_pake_inputs_t *inputs, uint8_t *buffer, size_t buffer_size, size_t *buffer_length)
psa_status_t | psa_crypto_driver_pake_get_user_len (const psa_crypto_driver_pake_inputs_t *inputs, size_t *user_len)
psa_status_t | psa_crypto_driver_pake_get_peer_len (const psa_crypto_driver_pake_inputs_t *inputs, size_t *peer_len)
psa_status_t | psa_crypto_driver_pake_get_user (const psa_crypto_driver_pake_inputs_t *inputs, uint8_t *user_id, size_t user_id_size, size_t *user_id_len)
psa_status_t | psa_crypto_driver_pake_get_peer (const psa_crypto_driver_pake_inputs_t *inputs, uint8_t *peer_id, size_t peer_id_size, size_t *peer_id_length)
psa_status_t | psa_crypto_driver_pake_get_cipher_suite (const psa_crypto_driver_pake_inputs_t *inputs, psa_pake_cipher_suite_t *cipher_suite)
psa_status_t | psa_pake_setup (psa_pake_operation_t *operation, const psa_pake_cipher_suite_t *cipher_suite)
psa_status_t | psa_pake_set_password_key (psa_pake_operation_t *operation, mbedtls_svc_key_id_t password)
psa_status_t | psa_pake_set_user (psa_pake_operation_t *operation, const uint8_t *user_id, size_t user_id_len)
psa_status_t | psa_pake_set_peer (psa_pake_operation_t *operation, const uint8_t *peer_id, size_t peer_id_len)
psa_status_t | psa_pake_set_role (psa_pake_operation_t *operation, psa_pake_role_t role)
psa_status_t | psa_pake_output (psa_pake_operation_t *operation, psa_pake_step_t step, uint8_t *output, size_t output_size, size_t *output_length)
psa_status_t | psa_pake_input (psa_pake_operation_t *operation, psa_pake_step_t step, const uint8_t *input, size_t input_length)
psa_status_t | psa_pake_get_implicit_key (psa_pake_operation_t *operation, psa_key_derivation_operation_t *output)
psa_status_t | psa_pake_abort (psa_pake_operation_t *operation)

## Detailed Description

This is a proposed PAKE interface for the PSA Crypto API. It is not part of the official PSA Crypto API yet.

Note
  The content of this section is not part of the stable API and ABI of Mbed TLS and may change arbitrarily from version to version. Same holds for the corresponding macros PSA_ALG_CATEGORY_PAKE and PSA_ALG_JPAKE.

## Macro Definition Documentation

## PSA_PAKE_PRIMITIVE

#define PSA_PAKE_PRIMITIVE | ( |  | pake_type,
|  |  | pake_family,
|  |  | pake_bits )

Value:
((pake_bits & 0xFFFF) != pake_bits) ? 0 : \
((psa_pake_primitive_t) (((pake_type) << 24 | \
(pake_family) << 16) | (pake_bits)))
psa_pake_primitive_t
uint32_t psa_pake_primitive_t
Encoding of the primitive associated with the PAKE.
Definition crypto_extra.h:828

Construct a PAKE primitive from type, family and bit-size.

Parameters

  pake_type | The type of the primitive (value of type psa_pake_primitive_type_t).
  pake_family | The family of the primitive (the type and interpretation of this parameter depends on `pake_type`, for more information consult the documentation of individual psa_pake_primitive_type_t constants).
  pake_bits | The bit-size of the primitive (Value of type `size_t`. The interpretation of this parameter depends on `pake_family`, for more information consult the documentation of individual psa_pake_primitive_type_t constants).

Returns
  The constructed primitive value of type psa_pake_primitive_t. Return 0 if the requested primitive can't be encoded as psa_pake_primitive_t.

Definition at line 925 of file crypto_extra.h.

Referenced by psa_pake_cs_get_primitive().

## PSA_PAKE_PRIMITIVE_TYPE_DH

#define PSA_PAKE_PRIMITIVE_TYPE_DH ((psa_pake_primitive_type_t) 0x02)

The PAKE primitive type indicating the use of Diffie-Hellman groups.

The values of the `family` and `bits` fields of the cipher suite identify a specific Diffie-Hellman group, using the same mapping that is used for Diffie-Hellman (psa_dh_family_t) keys.

(Here `family` means the value returned by psa_pake_cs_get_family() and `bits` means the value returned by psa_pake_cs_get_bits().)

Input and output during the operation can involve group elements and scalar values:

1. The format for group elements is the same as for public keys on the specific group would be. For more information, consult the documentation of psa_export_public_key().
2. The format for scalars is the same as for private keys on the specific group would be. For more information, consult the documentation of psa_export_key().

Definition at line 904 of file crypto_extra.h.

## PSA_PAKE_PRIMITIVE_TYPE_ECC

#define PSA_PAKE_PRIMITIVE_TYPE_ECC ((psa_pake_primitive_type_t) 0x01)

The PAKE primitive type indicating the use of elliptic curves.

The values of the `family` and `bits` fields of the cipher suite identify a specific elliptic curve, using the same mapping that is used for ECC (psa_ecc_family_t) keys.

(Here `family` means the value returned by psa_pake_cs_get_family() and `bits` means the value returned by psa_pake_cs_get_bits().)

Input and output during the operation can involve group elements and scalar values:

1. The format for group elements is the same as for public keys on the specific curve would be. For more information, consult the documentation of psa_export_public_key().
2. The format for scalars is the same as for private keys on the specific curve would be. For more information, consult the documentation of psa_export_key().

Definition at line 884 of file crypto_extra.h.

## PSA_PAKE_ROLE_CLIENT

#define PSA_PAKE_ROLE_CLIENT ((psa_pake_role_t) 0x11)

The client in an augmented PAKE.

Augmented PAKE algorithms need to differentiate between client and server.

Definition at line 858 of file crypto_extra.h.

## PSA_PAKE_ROLE_FIRST

#define PSA_PAKE_ROLE_FIRST ((psa_pake_role_t) 0x01)

The first peer in a balanced PAKE.

Although balanced PAKE algorithms are symmetric, some of them needs an ordering of peers for the transcript calculations. If the algorithm does not need this, both PSA_PAKE_ROLE_FIRST and PSA_PAKE_ROLE_SECOND are accepted.

Definition at line 843 of file crypto_extra.h.

## PSA_PAKE_ROLE_NONE

#define PSA_PAKE_ROLE_NONE ((psa_pake_role_t) 0x00)

A value to indicate no role in a PAKE algorithm. This value can be used in a call to psa_pake_set_role() for symmetric PAKE algorithms which do not assign roles.

Definition at line 834 of file crypto_extra.h.

## PSA_PAKE_ROLE_SECOND

#define PSA_PAKE_ROLE_SECOND ((psa_pake_role_t) 0x02)

The second peer in a balanced PAKE.

Although balanced PAKE algorithms are symmetric, some of them needs an ordering of peers for the transcript calculations. If the algorithm does not need this, either PSA_PAKE_ROLE_FIRST or PSA_PAKE_ROLE_SECOND are accepted.

Definition at line 852 of file crypto_extra.h.

## PSA_PAKE_ROLE_SERVER

#define PSA_PAKE_ROLE_SERVER ((psa_pake_role_t) 0x12)

The server in an augmented PAKE.

Augmented PAKE algorithms need to differentiate between client and server.

Definition at line 864 of file crypto_extra.h.

## PSA_PAKE_STEP_KEY_SHARE

#define PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t) 0x01)

The key share being sent to or received from the peer.

The format for both input and output at this step is the same as for public keys on the group determined by the primitive (psa_pake_primitive_t) would be.

For more information on the format, consult the documentation of psa_export_public_key().

For information regarding how the group is determined, consult the documentation PSA_PAKE_PRIMITIVE.

Definition at line 942 of file crypto_extra.h.

## PSA_PAKE_STEP_ZK_PROOF

#define PSA_PAKE_STEP_ZK_PROOF ((psa_pake_step_t) 0x03)

A Schnorr NIZKP proof.

This is the proof in the Schnorr Non-Interactive Zero-Knowledge Proof (the value denoted by the letter 'r' in RFC 8235).

Both for input and output, the value at this step is an integer less than the order of the group selected in the cipher suite. The format depends on the group as well:

- For Montgomery curves, the encoding is little endian.
- For everything else the encoding is big endian (see Section 2.3.8 of SEC 1: Elliptic Curve Cryptography at https://www.secg.org/sec1-v2.pdf).

In both cases leading zeroes are allowed as long as the length in bytes does not exceed the byte length of the group order.

For information regarding how the group is determined, consult the documentation PSA_PAKE_PRIMITIVE.

Definition at line 980 of file crypto_extra.h.

## PSA_PAKE_STEP_ZK_PUBLIC

#define PSA_PAKE_STEP_ZK_PUBLIC ((psa_pake_step_t) 0x02)

A Schnorr NIZKP public key.

This is the ephemeral public key in the Schnorr Non-Interactive Zero-Knowledge Proof (the value denoted by the letter 'V' in RFC 8235).

The format for both input and output at this step is the same as for public keys on the group determined by the primitive (psa_pake_primitive_t) would be.

For more information on the format, consult the documentation of psa_export_public_key().

For information regarding how the group is determined, consult the documentation PSA_PAKE_PRIMITIVE.

Definition at line 959 of file crypto_extra.h.

## Typedef Documentation

## psa_crypto_driver_pake_inputs_t

typedef struct psa_crypto_driver_pake_inputs_s psa_crypto_driver_pake_inputs_t

The type of input values for PAKE operations.

Definition at line 1326 of file crypto_extra.h.

## psa_jpake_computation_stage_t

typedef struct psa_jpake_computation_stage_s psa_jpake_computation_stage_t

The type of computation stage for J-PAKE operations.

Definition at line 1329 of file crypto_extra.h.

## psa_pake_cipher_suite_t

typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t

The type of the data structure for PAKE cipher suites.

This is an implementation-defined `struct`. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice.

Definition at line 1190 of file crypto_extra.h.

## psa_pake_family_t

typedef uint8_t psa_pake_family_t

Encoding of the family of the primitive associated with the PAKE.

For more information see the documentation of individual `PSA_PAKE_PRIMITIVE_TYPE_XXX` constants.

Definition at line 822 of file crypto_extra.h.

## psa_pake_operation_t

typedef struct psa_pake_operation_s psa_pake_operation_t

The type of the state data structure for PAKE operations.

Before calling any function on a PAKE operation object, the application must initialize it by any of the following means:

- Set the structure to all-bits-zero, for example:
  psa_pake_operation_t operation;
  memset(&operation, 0, sizeof(operation));
  psa_pake_operation_t
  struct psa_pake_operation_s psa_pake_operation_t
  Definition crypto_extra.h:1323
- Initialize the structure to logical zero values, for example:
  psa_pake_operation_t operation = {0};
- Initialize the structure to the initializer PSA_PAKE_OPERATION_INIT, for example:
  psa_pake_operation_t operation = PSA_PAKE_OPERATION_INIT;
  PSA_PAKE_OPERATION_INIT
  #define PSA_PAKE_OPERATION_INIT
  Definition crypto_extra.h:1080
- Assign the result of the function psa_pake_operation_init() to the structure, for example:
  psa_pake_operation_t operation;
  operation = psa_pake_operation_init();
  psa_pake_operation_init
  static psa_pake_operation_t psa_pake_operation_init(void)
  Definition crypto_extra.h:1967

This is an implementation-defined `struct`. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice.

Definition at line 1323 of file crypto_extra.h.

## psa_pake_primitive_t

typedef uint32_t psa_pake_primitive_t

Encoding of the primitive associated with the PAKE.

For more information see the documentation of the PSA_PAKE_PRIMITIVE macro.

Definition at line 828 of file crypto_extra.h.

## psa_pake_primitive_type_t

typedef uint8_t psa_pake_primitive_type_t

Encoding of the type of the PAKE's primitive.

Values defined by this standard will never be in the range 0x80-0xff. Vendors who define additional types must use an encoding in this range.

For more information see the documentation of individual `PSA_PAKE_PRIMITIVE_TYPE_XXX` constants.

Definition at line 815 of file crypto_extra.h.

## psa_pake_role_t

typedef uint8_t psa_pake_role_t

Encoding of the application role of PAKE.

Encodes the application's role in the algorithm is being executed. For more information see the documentation of individual `PSA_PAKE_ROLE_XXX` constants.

Definition at line 797 of file crypto_extra.h.

## psa_pake_step_t

typedef uint8_t psa_pake_step_t

Encoding of input and output indicators for PAKE.

Some PAKE algorithms need to exchange more data than just a single key share. This type is for encoding additional input and output data for such algorithms.

Definition at line 805 of file crypto_extra.h.

## Function Documentation

## psa_crypto_driver_pake_get_cipher_suite()

psa_status_t psa_crypto_driver_pake_get_cipher_suite | ( | const psa_crypto_driver_pake_inputs_t * | inputs,
|  | psa_pake_cipher_suite_t * | cipher_suite )

Get the cipher suite from given inputs.

Parameters

  [in] | inputs | Operation inputs.
  [out] | cipher_suite | Return buffer for role.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_BAD_STATE | Cipher_suite hasn't been set yet.

## psa_crypto_driver_pake_get_password()

psa_status_t psa_crypto_driver_pake_get_password | ( | const psa_crypto_driver_pake_inputs_t * | inputs,
|  | uint8_t * | buffer,
|  | size_t | buffer_size,
|  | size_t * | buffer_length )

Get the password from given inputs.

Parameters

  [in] | inputs | Operation inputs.
  [out] | buffer | Return buffer for password.
  | buffer_size | Size of the return buffer in bytes.
  [out] | buffer_length | Actual size of the password in bytes.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_BAD_STATE | Password hasn't been set yet.

## psa_crypto_driver_pake_get_password_len()

psa_status_t psa_crypto_driver_pake_get_password_len | ( | const psa_crypto_driver_pake_inputs_t * | inputs,
|  | size_t * | password_len )

Get the length of the password in bytes from given inputs.

Parameters

  [in] | inputs | Operation inputs.
  [out] | password_len | Password length.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_BAD_STATE | Password hasn't been set yet.

## psa_crypto_driver_pake_get_peer()

psa_status_t psa_crypto_driver_pake_get_peer | ( | const psa_crypto_driver_pake_inputs_t * | inputs,
|  | uint8_t * | peer_id,
|  | size_t | peer_id_size,
|  | size_t * | peer_id_length )

Get the peer id from given inputs.

Parameters

  [in] | inputs | Operation inputs.
  [out] | peer_id | Peer id.
  | peer_id_size | Size of `peer_id` in bytes.
  [out] | peer_id_length | Size of the peer id in bytes.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_BAD_STATE | Peer id hasn't been set yet.
  PSA_ERROR_BUFFER_TOO_SMALL | The size of the `peer_id` is too small.

## psa_crypto_driver_pake_get_peer_len()

psa_status_t psa_crypto_driver_pake_get_peer_len | ( | const psa_crypto_driver_pake_inputs_t * | inputs,
|  | size_t * | peer_len )

Get the length of the peer id in bytes from given inputs.

Parameters

  [in] | inputs | Operation inputs.
  [out] | peer_len | Peer id length.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_BAD_STATE | Peer id hasn't been set yet.

## psa_crypto_driver_pake_get_user()

psa_status_t psa_crypto_driver_pake_get_user | ( | const psa_crypto_driver_pake_inputs_t * | inputs,
|  | uint8_t * | user_id,
|  | size_t | user_id_size,
|  | size_t * | user_id_len )

Get the user id from given inputs.

Parameters

  [in] | inputs | Operation inputs.
  [out] | user_id | User id.
  | user_id_size | Size of `user_id` in bytes.
  [out] | user_id_len | Size of the user id in bytes.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_BAD_STATE | User id hasn't been set yet.
  PSA_ERROR_BUFFER_TOO_SMALL | The size of the `user_id` is too small.

## psa_crypto_driver_pake_get_user_len()

psa_status_t psa_crypto_driver_pake_get_user_len | ( | const psa_crypto_driver_pake_inputs_t * | inputs,
|  | size_t * | user_len )

Get the length of the user id in bytes from given inputs.

Parameters

  [in] | inputs | Operation inputs.
  [out] | user_len | User id length.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_BAD_STATE | User id hasn't been set yet.

## psa_pake_abort()

psa_status_t psa_pake_abort | ( | psa_pake_operation_t * | operation | ) |

Abort a PAKE operation.

Aborting an operation frees all associated resources except for the `operation` structure itself. Once aborted, the operation object can be reused for another operation by calling psa_pake_setup() again.

This function may be called at any time after the operation object has been initialized as described in psa_pake_operation_t.

In particular, calling psa_pake_abort() after the operation has been terminated by a call to psa_pake_abort() or psa_pake_get_implicit_key() is safe and has no effect.

Parameters

  [in,out] | operation | The operation to abort.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_COMMUNICATION_FAILURE |
  PSA_ERROR_CORRUPTION_DETECTED |
  PSA_ERROR_BAD_STATE | The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

## psa_pake_cipher_suite_init()

struct psa_pake_cipher_suite_s psa_pake_cipher_suite_init | ( | void |  | ) |

inline static

Return an initial value for a PAKE cipher suite object.

Definition at line 1961 of file crypto_extra.h.

References PSA_PAKE_CIPHER_SUITE_INIT, and psa_pake_cipher_suite_init().

Referenced by psa_pake_cipher_suite_init().

## psa_pake_cs_get_algorithm()

psa_algorithm_t psa_pake_cs_get_algorithm | ( | const psa_pake_cipher_suite_t * | cipher_suite | ) |

inline static

Retrieve the PAKE algorithm from a PAKE cipher suite.

Parameters

  [in] | cipher_suite | The cipher suite structure to query.

Returns
  The PAKE algorithm stored in the cipher suite structure.

Definition at line 1900 of file crypto_extra.h.

References psa_pake_cipher_suite_s::algorithm.

## psa_pake_cs_get_bits()

uint16_t psa_pake_cs_get_bits | ( | const psa_pake_cipher_suite_t * | cipher_suite | ) |

inline static

Retrieve the PAKE primitive bit-size from a PAKE cipher suite.

Parameters

  [in] | cipher_suite | The cipher suite structure to query.

Returns
  The PAKE primitive bit-size stored in the cipher suite structure.

Definition at line 1939 of file crypto_extra.h.

References psa_pake_cipher_suite_s::bits.

## psa_pake_cs_get_family()

psa_pake_family_t psa_pake_cs_get_family | ( | const psa_pake_cipher_suite_t * | cipher_suite | ) |

inline static

Retrieve the PAKE family from a PAKE cipher suite.

Parameters

  [in] | cipher_suite | The cipher suite structure to query.

Returns
  The PAKE family stored in the cipher suite structure.

Definition at line 1933 of file crypto_extra.h.

References psa_pake_cipher_suite_s::family.

## psa_pake_cs_get_hash()

psa_algorithm_t psa_pake_cs_get_hash | ( | const psa_pake_cipher_suite_t * | cipher_suite | ) |

inline static

Retrieve the hash algorithm from a PAKE cipher suite.

Parameters

  [in] | cipher_suite | The cipher suite structure to query.

Returns
  The hash algorithm stored in the cipher suite structure. The return value is 0 if the PAKE is not parametrised by a hash algorithm or if the hash algorithm is not set.

Definition at line 1945 of file crypto_extra.h.

References psa_pake_cipher_suite_s::hash.

## psa_pake_cs_get_primitive()

psa_pake_primitive_t psa_pake_cs_get_primitive | ( | const psa_pake_cipher_suite_t * | cipher_suite | ) |

inline static

Retrieve the primitive from a PAKE cipher suite.

Parameters

  [in] | cipher_suite | The cipher suite structure to query.

Returns
  The primitive stored in the cipher suite structure.

Definition at line 1917 of file crypto_extra.h.

References psa_pake_cipher_suite_s::bits, psa_pake_cipher_suite_s::family, PSA_PAKE_PRIMITIVE, and psa_pake_cipher_suite_s::type.

## psa_pake_cs_set_algorithm()

void psa_pake_cs_set_algorithm | ( | psa_pake_cipher_suite_t * | cipher_suite,
|  | psa_algorithm_t | algorithm )

inline static

Declare the PAKE algorithm for the cipher suite.

This function overwrites any PAKE algorithm previously set in `cipher_suite`.

Note
  For PSA_ALG_JPAKE, the only supported hash algorithm is SHA-256.

Parameters

  [out] | cipher_suite | The cipher suite structure to write to.
  | algorithm | The PAKE algorithm to write. (PSA_ALG_XXX values of type psa_algorithm_t such that PSA_ALG_IS_PAKE(`alg`) is true.) If this is 0, the PAKE algorithm in `cipher_suite` becomes unspecified.

Definition at line 1906 of file crypto_extra.h.

References psa_pake_cipher_suite_s::algorithm, and PSA_ALG_IS_PAKE.

## psa_pake_cs_set_hash()

void psa_pake_cs_set_hash | ( | psa_pake_cipher_suite_t * | cipher_suite,
|  | psa_algorithm_t | hash )

inline static

Declare the hash algorithm for a PAKE cipher suite.

This function overwrites any hash algorithm previously set in `cipher_suite`.

Refer to the documentation of individual PAKE algorithm types (PSA_ALG_XXX values of type psa_algorithm_t such that PSA_ALG_IS_PAKE(`alg`) is true) for more information.

Parameters

  [out] | cipher_suite | The cipher suite structure to write to.
  | hash | The hash involved in the cipher suite. (PSA_ALG_XXX values of type psa_algorithm_t such that PSA_ALG_IS_HASH(`alg`) is true.) If this is 0, the hash algorithm in `cipher_suite` becomes unspecified.

Definition at line 1951 of file crypto_extra.h.

References psa_pake_cipher_suite_s::hash, and PSA_ALG_IS_HASH.

## psa_pake_cs_set_primitive()

void psa_pake_cs_set_primitive | ( | psa_pake_cipher_suite_t * | cipher_suite,
|  | psa_pake_primitive_t | primitive )

inline static

Declare the primitive for a PAKE cipher suite.

This function overwrites any primitive previously set in `cipher_suite`.

Note
  For PSA_ALG_JPAKE, the only supported primitive is ECC on the curve secp256r1, i.e. PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC, PSA_ECC_FAMILY_SECP_R1, 256).

Parameters

  [out] | cipher_suite | The cipher suite structure to write to.
  | primitive | The primitive to write. If this is 0, the primitive type in `cipher_suite` becomes unspecified.

Definition at line 1924 of file crypto_extra.h.

References psa_pake_cipher_suite_s::bits, psa_pake_cipher_suite_s::family, and psa_pake_cipher_suite_s::type.

## psa_pake_get_implicit_key()

psa_status_t psa_pake_get_implicit_key | ( | psa_pake_operation_t * | operation,
|  | psa_key_derivation_operation_t * | output )

Get implicitly confirmed shared secret from a PAKE.

At this point there is a cryptographic guarantee that only the authenticated party who used the same password is able to compute the key. But there is no guarantee that the peer is the party it claims to be and was able to do so.

That is, the authentication is only implicit. Since the peer is not authenticated yet, no action should be taken yet that assumes that the peer is who it claims to be. For example, do not access restricted files on the peer's behalf until an explicit authentication has succeeded.

This function can be called after the key exchange phase of the operation has completed. It imports the shared secret output of the PAKE into the provided derivation operation. The input step PSA_KEY_DERIVATION_INPUT_SECRET is used when placing the shared key material in the key derivation operation.

The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. Refer to the documentation of individual PAKE algorithm types (PSA_ALG_XXX values of type psa_algorithm_t such that PSA_ALG_IS_PAKE(`alg`) is true) for more information.

When this function returns successfully, `operation` becomes inactive. If this function returns an error status, both `operation` and `key_derivation` operations enter an error state and must be aborted by calling psa_pake_abort() and psa_key_derivation_abort() respectively.

Parameters

  [in,out] | operation | Active PAKE operation.
  [out] | output | A key derivation operation that is ready for an input step of type PSA_KEY_DERIVATION_INPUT_SECRET.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_INVALID_ARGUMENT | PSA_KEY_DERIVATION_INPUT_SECRET is not compatible with the algorithm in the `output` key derivation operation.
  PSA_ERROR_NOT_SUPPORTED | Input from a PAKE is not supported by the algorithm in the `output` key derivation operation.
  PSA_ERROR_INSUFFICIENT_MEMORY |
  PSA_ERROR_COMMUNICATION_FAILURE |
  PSA_ERROR_CORRUPTION_DETECTED |
  PSA_ERROR_STORAGE_FAILURE |
  PSA_ERROR_DATA_CORRUPT |
  PSA_ERROR_DATA_INVALID |

  PSA_ERROR_BAD_STATE

  The PAKE operation state is not valid (it must be active, but beyond that validity is specific to the algorithm), or the library has not been previously initialized by psa_crypto_init(), or the state of `output` is not valid for the PSA_KEY_DERIVATION_INPUT_SECRET step. This can happen if the step is out of order or the application has done this step already and it may not be repeated. It is implementation-dependent whether a failure to initialize results in this error code.

## psa_pake_input()

psa_status_t psa_pake_input | ( | psa_pake_operation_t * | operation,
|  | psa_pake_step_t | step,
|  | const uint8_t * | input,
|  | size_t | input_length )

Provide input for a step of a password-authenticated key exchange.

Depending on the algorithm being executed, you might need to call this function several times or you might not need to call this at all.

The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. Refer to the documentation of individual PAKE algorithm types (PSA_ALG_XXX values of type psa_algorithm_t such that PSA_ALG_IS_PAKE(`alg`) is true) for more information.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_pake_abort().

Parameters

  [in,out] | operation | Active PAKE operation.
  | step | The step for which the input is provided.
  [in] | input | Buffer containing the input in the format appropriate for this `step`. Refer to the documentation of the individual `PSA_PAKE_STEP_XXX` constants for more information.
  | input_length | Size of the `input` buffer in bytes.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_INVALID_SIGNATURE | The verification fails for a PSA_PAKE_STEP_ZK_PROOF input step.
  PSA_ERROR_INVALID_ARGUMENT | `input_length` is not compatible with the `operation’s` algorithm, or the `input` is not valid for the `operation's` algorithm, cipher suite or `step`.
  PSA_ERROR_NOT_SUPPORTED | `step` p is not supported with the `operation's` algorithm, or the `input` is not supported for the `operation's` algorithm, cipher suite or `step`.
  PSA_ERROR_INSUFFICIENT_MEMORY |
  PSA_ERROR_COMMUNICATION_FAILURE |
  PSA_ERROR_CORRUPTION_DETECTED |
  PSA_ERROR_STORAGE_FAILURE |
  PSA_ERROR_DATA_CORRUPT |
  PSA_ERROR_DATA_INVALID |
  PSA_ERROR_BAD_STATE | The operation state is not valid (it must be active, and fully set up, and this call must conform to the algorithm's requirements for ordering of input and output steps), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

## psa_pake_operation_init()

struct psa_pake_operation_s psa_pake_operation_init | ( | void |  | ) |

inline static

Return an initial value for a PAKE operation object.

Definition at line 1967 of file crypto_extra.h.

References PSA_PAKE_OPERATION_INIT, and psa_pake_operation_init().

Referenced by psa_pake_operation_init().

## psa_pake_output()

psa_status_t psa_pake_output | ( | psa_pake_operation_t * | operation,
|  | psa_pake_step_t | step,
|  | uint8_t * | output,
|  | size_t | output_size,
|  | size_t * | output_length )

Get output for a step of a password-authenticated key exchange.

Depending on the algorithm being executed, you might need to call this function several times or you might not need to call this at all.

The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. Refer to the documentation of individual PAKE algorithm types (PSA_ALG_XXX values of type psa_algorithm_t such that PSA_ALG_IS_PAKE(`alg`) is true) for more information.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_pake_abort().

Parameters

  [in,out] | operation | Active PAKE operation.
  | step | The step of the algorithm for which the output is requested.
  [out] | output | Buffer where the output is to be written in the format appropriate for this `step`. Refer to the documentation of the individual `PSA_PAKE_STEP_XXX` constants for more information.
  | output_size | Size of the `output` buffer in bytes. This must be at least PSA_PAKE_OUTPUT_SIZE(`alg`, `primitive`, `output_step`) where `alg` and `primitive` are the PAKE algorithm and primitive in the operation's cipher suite, and `step` is the output step.
  [out] | output_length | On success, the number of bytes of the returned output.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_BUFFER_TOO_SMALL | The size of the `output` buffer is too small.
  PSA_ERROR_INVALID_ARGUMENT | `step` is not compatible with the operation's algorithm.
  PSA_ERROR_NOT_SUPPORTED | `step` is not supported with the operation's algorithm.
  PSA_ERROR_INSUFFICIENT_ENTROPY |
  PSA_ERROR_INSUFFICIENT_MEMORY |
  PSA_ERROR_COMMUNICATION_FAILURE |
  PSA_ERROR_CORRUPTION_DETECTED |
  PSA_ERROR_STORAGE_FAILURE |
  PSA_ERROR_DATA_CORRUPT |
  PSA_ERROR_DATA_INVALID |
  PSA_ERROR_BAD_STATE | The operation state is not valid (it must be active, and fully set up, and this call must conform to the algorithm's requirements for ordering of input and output steps), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

## psa_pake_set_password_key()

psa_status_t psa_pake_set_password_key | ( | psa_pake_operation_t * | operation,
|  | mbedtls_svc_key_id_t | password )

Set the password for a password-authenticated key exchange from key ID.

Call this function when the password, or a value derived from the password, is already present in the key store.

Parameters

  [in,out] | operation | The operation object to set the password for. It must have been set up by psa_pake_setup() and not yet in use (neither psa_pake_output() nor psa_pake_input() has been called yet). It must be on operation for which the password hasn't been set yet (psa_pake_set_password_key() hasn't been called yet).
  | password | Identifier of the key holding the password or a value derived from the password (eg. by a memory-hard function). It must remain valid until the operation terminates. It must be of type PSA_KEY_TYPE_PASSWORD or PSA_KEY_TYPE_PASSWORD_HASH. It has to allow the usage PSA_KEY_USAGE_DERIVE.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_INVALID_HANDLE | `password` is not a valid key identifier.
  PSA_ERROR_NOT_PERMITTED | The key does not have the PSA_KEY_USAGE_DERIVE flag, or it does not permit the `operation's` algorithm.
  PSA_ERROR_INVALID_ARGUMENT | The key type for `password` is not PSA_KEY_TYPE_PASSWORD or PSA_KEY_TYPE_PASSWORD_HASH, or `password` is not compatible with the `operation's` cipher suite.
  PSA_ERROR_NOT_SUPPORTED | The key type or key size of `password` is not supported with the `operation's` cipher suite.
  PSA_ERROR_COMMUNICATION_FAILURE |
  PSA_ERROR_CORRUPTION_DETECTED |
  PSA_ERROR_STORAGE_FAILURE |
  PSA_ERROR_DATA_CORRUPT |
  PSA_ERROR_DATA_INVALID |
  PSA_ERROR_BAD_STATE | The operation state is not valid (it must have been set up.), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

## psa_pake_set_peer()

psa_status_t psa_pake_set_peer | ( | psa_pake_operation_t * | operation,
|  | const uint8_t * | peer_id,
|  | size_t | peer_id_len )

Set the peer ID for a password-authenticated key exchange.

Call this function in addition to psa_pake_set_user() for PAKE algorithms that associate a user identifier with each side of the session. For PAKE algorithms that associate a single user identifier with the session, call psa_pake_set_user() only.

Refer to the documentation of individual PAKE algorithm types (PSA_ALG_XXX values of type psa_algorithm_t such that PSA_ALG_IS_PAKE(`alg`) is true) for more information.

Note
  When using the built-in implementation of PSA_ALG_JPAKE, the peer ID must be "client" (6-byte string) or "server" (6-byte string). Third-party drivers may or may not have this limitation.

Parameters

  [in,out] | operation | The operation object to set the peer ID for. It must have been set up by psa_pake_setup() and not yet in use (neither psa_pake_output() nor psa_pake_input() has been called yet). It must be on operation for which the peer ID hasn't been set (psa_pake_set_peer() hasn't been called yet).
  [in] | peer_id | The peer's ID to authenticate.
  | peer_id_len | Size of the `peer_id` buffer in bytes.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_INVALID_ARGUMENT | `peer_id` is not valid for the `operation's` algorithm and cipher suite.
  PSA_ERROR_NOT_SUPPORTED | The algorithm doesn't associate a second identity with the session.
  PSA_ERROR_INSUFFICIENT_MEMORY |
  PSA_ERROR_COMMUNICATION_FAILURE |
  PSA_ERROR_CORRUPTION_DETECTED |
  PSA_ERROR_BAD_STATE | Calling psa_pake_set_peer() is invalid with the `operation's` algorithm, the operation state is not valid, or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

## psa_pake_set_role()

psa_status_t psa_pake_set_role | ( | psa_pake_operation_t * | operation,
|  | psa_pake_role_t | role )

Set the application role for a password-authenticated key exchange.

Not all PAKE algorithms need to differentiate the communicating entities. It is optional to call this function for PAKEs that don't require a role to be specified. For such PAKEs the application role parameter is ignored, or PSA_PAKE_ROLE_NONE can be passed as `role`.

Refer to the documentation of individual PAKE algorithm types (PSA_ALG_XXX values of type psa_algorithm_t such that PSA_ALG_IS_PAKE(`alg`) is true) for more information.

Parameters

  [in,out] | operation | The operation object to specify the application's role for. It must have been set up by psa_pake_setup() and not yet in use (neither psa_pake_output() nor psa_pake_input() has been called yet). It must be on operation for which the application's role hasn't been specified (psa_pake_set_role() hasn't been called yet).
  | role | A value of type psa_pake_role_t indicating the application's role in the PAKE the algorithm that is being set up. For more information see the documentation of `PSA_PAKE_ROLE_XXX` constants.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_INVALID_ARGUMENT | The `role` is not a valid PAKE role in the `operation’s` algorithm.
  PSA_ERROR_NOT_SUPPORTED | The `role` for this algorithm is not supported or is not valid.
  PSA_ERROR_COMMUNICATION_FAILURE |
  PSA_ERROR_CORRUPTION_DETECTED |
  PSA_ERROR_BAD_STATE | The operation state is not valid, or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

## psa_pake_set_user()

psa_status_t psa_pake_set_user | ( | psa_pake_operation_t * | operation,
|  | const uint8_t * | user_id,
|  | size_t | user_id_len )

Set the user ID for a password-authenticated key exchange.

Call this function to set the user ID. For PAKE algorithms that associate a user identifier with each side of the session you need to call psa_pake_set_peer() as well. For PAKE algorithms that associate a single user identifier with the session, call psa_pake_set_user() only.

Refer to the documentation of individual PAKE algorithm types (PSA_ALG_XXX values of type psa_algorithm_t such that PSA_ALG_IS_PAKE(`alg`) is true) for more information.

Note
  When using the built-in implementation of PSA_ALG_JPAKE, the user ID must be "client" (6-byte string) or "server" (6-byte string). Third-party drivers may or may not have this limitation.

Parameters

  [in,out] | operation | The operation object to set the user ID for. It must have been set up by psa_pake_setup() and not yet in use (neither psa_pake_output() nor psa_pake_input() has been called yet). It must be on operation for which the user ID hasn't been set (psa_pake_set_user() hasn't been called yet).
  [in] | user_id | The user ID to authenticate with.
  | user_id_len | Size of the `user_id` buffer in bytes.

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_INVALID_ARGUMENT | `user_id` is not valid for the `operation's` algorithm and cipher suite.
  PSA_ERROR_NOT_SUPPORTED | The value of `user_id` is not supported by the implementation.
  PSA_ERROR_INSUFFICIENT_MEMORY |
  PSA_ERROR_COMMUNICATION_FAILURE |
  PSA_ERROR_CORRUPTION_DETECTED |
  PSA_ERROR_BAD_STATE | The operation state is not valid, or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

## psa_pake_setup()

psa_status_t psa_pake_setup | ( | psa_pake_operation_t * | operation,
|  | const psa_pake_cipher_suite_t * | cipher_suite )

Set the session information for a password-authenticated key exchange.

The sequence of operations to set up a password-authenticated key exchange is as follows:

1. Allocate an operation object which will be passed to all the functions listed here.
2. Initialize the operation object with one of the methods described in the documentation for psa_pake_operation_t, e.g. PSA_PAKE_OPERATION_INIT.
3. Call psa_pake_setup() to specify the cipher suite.
4. Call `psa_pake_set_xxx()` functions on the operation to complete the setup. The exact sequence of `psa_pake_set_xxx()` functions that needs to be called depends on the algorithm in use.

Refer to the documentation of individual PAKE algorithm types (PSA_ALG_XXX values of type psa_algorithm_t such that PSA_ALG_IS_PAKE(`alg`) is true) for more information.

A typical sequence of calls to perform a password-authenticated key exchange:

1. Call psa_pake_output(operation, PSA_PAKE_STEP_KEY_SHARE, ...) to get the key share that needs to be sent to the peer.
2. Call psa_pake_input(operation, PSA_PAKE_STEP_KEY_SHARE, ...) to provide the key share that was received from the peer.
3. Depending on the algorithm additional calls to psa_pake_output() and psa_pake_input() might be necessary.
4. Call psa_pake_get_implicit_key() for accessing the shared secret.

Refer to the documentation of individual PAKE algorithm types (PSA_ALG_XXX values of type psa_algorithm_t such that PSA_ALG_IS_PAKE(`alg`) is true) for more information.

If an error occurs at any step after a call to psa_pake_setup(), the operation will need to be reset by a call to psa_pake_abort(). The application may call psa_pake_abort() at any time after the operation has been initialized.

After a successful call to psa_pake_setup(), the application must eventually terminate the operation. The following events terminate an operation:

- A call to psa_pake_abort().
- A successful call to psa_pake_get_implicit_key().

Parameters

  [in,out] | operation | The operation object to set up. It must have been initialized but not set up yet.
  [in] | cipher_suite | The cipher suite to use. (A cipher suite fully characterizes a PAKE algorithm and determines the algorithm as well.)

Return values

  PSA_SUCCESS | Success.
  PSA_ERROR_INVALID_ARGUMENT | The algorithm in `cipher_suite` is not a PAKE algorithm, or the PAKE primitive in `cipher_suite` is not compatible with the PAKE algorithm, or the hash algorithm in `cipher_suite` is invalid or not compatible with the PAKE algorithm and primitive.
  PSA_ERROR_NOT_SUPPORTED | The algorithm in `cipher_suite` is not a supported PAKE algorithm, or the PAKE primitive in `cipher_suite` is not supported or not compatible with the PAKE algorithm, or the hash algorithm in `cipher_suite` is not supported or not compatible with the PAKE algorithm and primitive.
  PSA_ERROR_COMMUNICATION_FAILURE |
  PSA_ERROR_CORRUPTION_DETECTED |
  PSA_ERROR_BAD_STATE | The operation state is not valid, or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.