Password-authenticated key exchange (PAKE)#

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.

Typedefs#

typedef uint8_t

Encoding of the application role of PAKE.

typedef uint8_t

Encoding of input and output indicators for PAKE.

typedef uint8_t

Encoding of the type of the PAKE's primitive.

typedef uint8_t

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

typedef uint32_t

Encoding of the primitive associated with the PAKE.

typedef uint8_t

Encoding of the application role of PAKE.

typedef uint8_t

Encoding of input and output indicators for PAKE.

typedef uint8_t

Encoding of the type of the PAKE's primitive.

typedef uint8_t

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

typedef uint32_t

Encoding of the primitive associated with the PAKE.

Functions#

psa_pake_cipher_suite_t

Return an initial value for a PAKE cipher suite object.

psa_pake_cs_get_algorithm(const psa_pake_cipher_suite_t *cipher_suite)

Retrieve the PAKE algorithm from a PAKE cipher suite.

void
psa_pake_cs_set_algorithm(psa_pake_cipher_suite_t *cipher_suite, psa_algorithm_t algorithm)

Declare the PAKE algorithm for the cipher suite.

psa_pake_cs_get_primitive(const psa_pake_cipher_suite_t *cipher_suite)

Retrieve the primitive from a PAKE cipher suite.

void
psa_pake_cs_set_primitive(psa_pake_cipher_suite_t *cipher_suite, psa_pake_primitive_t primitive)

Declare the primitive for a PAKE cipher suite.

psa_pake_cs_get_family(const psa_pake_cipher_suite_t *cipher_suite)

Retrieve the PAKE family from a PAKE cipher suite.

uint16_t
psa_pake_cs_get_bits(const psa_pake_cipher_suite_t *cipher_suite)

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

psa_pake_cs_get_hash(const psa_pake_cipher_suite_t *cipher_suite)

Retrieve the hash algorithm from a PAKE cipher suite.

void
psa_pake_cs_set_hash(psa_pake_cipher_suite_t *cipher_suite, psa_algorithm_t hash)

Declare the hash algorithm for a PAKE cipher suite.

psa_pake_operation_t

Return an initial value for a PAKE operation object.

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.

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.

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.

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.

psa_pake_set_role(psa_pake_operation_t *operation, psa_pake_role_t role)

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

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.

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.

psa_pake_get_implicit_key(psa_pake_operation_t *operation, psa_key_derivation_operation_t *output)

Get implicitly confirmed shared secret from a PAKE.

psa_pake_derive_secret(psa_pake_operation_t *operation, uint8_t *key_buf, size_t key_length)
psa_pake_abort(psa_pake_operation_t *operation)

Abort a PAKE operation.

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.

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.

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.

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.

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.

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.

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.

Macros#

#define
PSA_PAKE_ROLE_NONE ((psa_pake_role_t) 0x00)

A value to indicate no role in a PAKE algorithm.

#define
PSA_PAKE_ROLE_FIRST ((psa_pake_role_t) 0x01)

The first peer in a balanced PAKE.

#define
PSA_PAKE_ROLE_SECOND ((psa_pake_role_t) 0x02)

The second peer in a balanced PAKE.

#define
PSA_PAKE_ROLE_CLIENT ((psa_pake_role_t) 0x11)

The client in an augmented PAKE.

#define
PSA_PAKE_ROLE_SERVER ((psa_pake_role_t) 0x12)

The server in an augmented PAKE.

#define
PSA_PAKE_PRIMITIVE_TYPE_ECC ((psa_pake_primitive_type_t) 0x01)

The PAKE primitive type indicating the use of elliptic curves.

#define
PSA_PAKE_PRIMITIVE_TYPE_DH ((psa_pake_primitive_type_t) 0x02)

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

#define
PSA_PAKE_PRIMITIVE (pake_type, pake_family, pake_bits)

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

#define
PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t) 0x01)

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

#define
PSA_PAKE_STEP_ZK_PUBLIC ((psa_pake_step_t) 0x02)

A Schnorr NIZKP public key.

#define
PSA_PAKE_STEP_ZK_PROOF ((psa_pake_step_t) 0x03)

A Schnorr NIZKP proof.

#define
PSA_PAKE_ROLE_NONE ((psa_pake_role_t) 0x00)

A value to indicate no role in a PAKE algorithm.

#define
PSA_PAKE_ROLE_FIRST ((psa_pake_role_t) 0x01)

The first peer in a balanced PAKE.

#define
PSA_PAKE_ROLE_SECOND ((psa_pake_role_t) 0x02)

The second peer in a balanced PAKE.

#define
PSA_PAKE_ROLE_CLIENT ((psa_pake_role_t) 0x11)

The client in an augmented PAKE.

#define
PSA_PAKE_ROLE_SERVER ((psa_pake_role_t) 0x12)

The server in an augmented PAKE.

#define
PSA_PAKE_PRIMITIVE_TYPE_ECC ((psa_pake_primitive_type_t) 0x01)

The PAKE primitive type indicating the use of elliptic curves.

#define
PSA_PAKE_PRIMITIVE_TYPE_DH ((psa_pake_primitive_type_t) 0x02)

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

#define
PSA_PAKE_PRIMITIVE (pake_type, pake_family, pake_bits)

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

#define
PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t) 0x01)

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

#define
PSA_PAKE_STEP_ZK_PUBLIC ((psa_pake_step_t) 0x02)

A Schnorr NIZKP public key.

#define
PSA_PAKE_STEP_ZK_PROOF ((psa_pake_step_t) 0x03)

A Schnorr NIZKP proof.

Typedef Documentation#

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.


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.


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.


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.


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.


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.


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.


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.


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.


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.


Function Documentation#

psa_pake_cipher_suite_init#

static struct psa_pake_cipher_suite_s psa_pake_cipher_suite_init (void )

Return an initial value for a PAKE cipher suite object.

Parameters
TypeDirectionArgument NameDescription
voidN/A

psa_pake_cs_get_algorithm#

static psa_algorithm_t psa_pake_cs_get_algorithm (const psa_pake_cipher_suite_t * cipher_suite)

Retrieve the PAKE algorithm from a PAKE cipher suite.

Parameters
TypeDirectionArgument NameDescription
const psa_pake_cipher_suite_t *[in]cipher_suite

The cipher suite structure to query.

Returns

  • The PAKE algorithm stored in the cipher suite structure.


psa_pake_cs_set_algorithm#

static void psa_pake_cs_set_algorithm (psa_pake_cipher_suite_t * cipher_suite, psa_algorithm_t algorithm)

Declare the PAKE algorithm for the cipher suite.

Parameters
TypeDirectionArgument NameDescription
psa_pake_cipher_suite_t *[out]cipher_suite

The cipher suite structure to write to.

psa_algorithm_tN/Aalgorithm

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.

This function overwrites any PAKE algorithm previously set in cipher_suite.


psa_pake_cs_get_primitive#

static psa_pake_primitive_t psa_pake_cs_get_primitive (const psa_pake_cipher_suite_t * cipher_suite)

Retrieve the primitive from a PAKE cipher suite.

Parameters
TypeDirectionArgument NameDescription
const psa_pake_cipher_suite_t *[in]cipher_suite

The cipher suite structure to query.

Returns

  • The primitive stored in the cipher suite structure.


psa_pake_cs_set_primitive#

static void psa_pake_cs_set_primitive (psa_pake_cipher_suite_t * cipher_suite, psa_pake_primitive_t primitive)

Declare the primitive for a PAKE cipher suite.

Parameters
TypeDirectionArgument NameDescription
psa_pake_cipher_suite_t *[out]cipher_suite

The cipher suite structure to write to.

psa_pake_primitive_tN/Aprimitive

The primitive to write. If this is 0, the primitive type in cipher_suite becomes unspecified.

This function overwrites any primitive previously set in cipher_suite.


psa_pake_cs_get_family#

static psa_pake_family_t psa_pake_cs_get_family (const psa_pake_cipher_suite_t * cipher_suite)

Retrieve the PAKE family from a PAKE cipher suite.

Parameters
TypeDirectionArgument NameDescription
const psa_pake_cipher_suite_t *[in]cipher_suite

The cipher suite structure to query.

Returns

  • The PAKE family stored in the cipher suite structure.


psa_pake_cs_get_bits#

static uint16_t psa_pake_cs_get_bits (const psa_pake_cipher_suite_t * cipher_suite)

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

Parameters
TypeDirectionArgument NameDescription
const psa_pake_cipher_suite_t *[in]cipher_suite

The cipher suite structure to query.

Returns

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


psa_pake_cs_get_hash#

static psa_algorithm_t psa_pake_cs_get_hash (const psa_pake_cipher_suite_t * cipher_suite)

Retrieve the hash algorithm from a PAKE cipher suite.

Parameters
TypeDirectionArgument NameDescription
const psa_pake_cipher_suite_t *[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.


psa_pake_cs_set_hash#

static void psa_pake_cs_set_hash (psa_pake_cipher_suite_t * cipher_suite, psa_algorithm_t hash)

Declare the hash algorithm for a PAKE cipher suite.

Parameters
TypeDirectionArgument NameDescription
psa_pake_cipher_suite_t *[out]cipher_suite

The cipher suite structure to write to.

psa_algorithm_tN/Ahash

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.

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.


psa_pake_operation_init#

static struct psa_pake_operation_s psa_pake_operation_init (void )

Return an initial value for a PAKE operation object.

Parameters
TypeDirectionArgument NameDescription
voidN/A

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.

Parameters
TypeDirectionArgument NameDescription
psa_pake_operation_t *[inout]operation

The operation object to set up. It must have been initialized but not set up yet.

const psa_pake_cipher_suite_t *[in]cipher_suite

The cipher suite to use. (A cipher suite fully characterizes a PAKE algorithm and determines the algorithm as well.)

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:


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.

Parameters
TypeDirectionArgument NameDescription
psa_pake_operation_t *[inout]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).

mbedtls_svc_key_id_tN/Apassword

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.

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


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.

Parameters
TypeDirectionArgument NameDescription
psa_pake_operation_t *[inout]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).

const uint8_t *[in]user_id

The user ID to authenticate with.

size_tN/Auser_id_len

Size of the user_id buffer in bytes.

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.


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.

Parameters
TypeDirectionArgument NameDescription
psa_pake_operation_t *[inout]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).

const uint8_t *[in]peer_id

The peer's ID to authenticate.

size_tN/Apeer_id_len

Size of the peer_id buffer in bytes.

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.


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.

Parameters
TypeDirectionArgument NameDescription
psa_pake_operation_t *[inout]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).

psa_pake_role_tN/Arole

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.

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.


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.

Parameters
TypeDirectionArgument NameDescription
psa_pake_operation_t *[inout]operation

Active PAKE operation.

psa_pake_step_tN/Astep

The step of the algorithm for which the output is requested.

uint8_t *[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.

size_tN/Aoutput_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.

size_t *[out]output_length

On success, the number of bytes of the returned output.

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


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.

Parameters
TypeDirectionArgument NameDescription
psa_pake_operation_t *[inout]operation

Active PAKE operation.

psa_pake_step_tN/Astep

The step for which the input is provided.

const uint8_t *[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.

size_tN/Ainput_length

Size of the input buffer in bytes.

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


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.

Parameters
TypeDirectionArgument NameDescription
psa_pake_operation_t *[inout]operation

Active PAKE operation.

psa_key_derivation_operation_t *[out]output

A key derivation operation that is ready for an input step of type PSA_KEY_DERIVATION_INPUT_SECRET.

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.


psa_pake_derive_secret#

psa_status_t psa_pake_derive_secret (psa_pake_operation_t * operation, uint8_t * key_buf, size_t key_length)
Parameters
TypeDirectionArgument NameDescription
psa_pake_operation_t *N/Aoperation
uint8_t *N/Akey_buf
size_tN/Akey_length

psa_pake_abort#

psa_status_t psa_pake_abort (psa_pake_operation_t * operation)

Abort a PAKE operation.

Parameters
TypeDirectionArgument NameDescription
psa_pake_operation_t *[inout]operation

The operation to abort.

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.


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
TypeDirectionArgument NameDescription
const psa_crypto_driver_pake_inputs_t *[in]inputs

Operation inputs.

size_t *[out]password_len

Password length.


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
TypeDirectionArgument NameDescription
const psa_crypto_driver_pake_inputs_t *[in]inputs

Operation inputs.

uint8_t *[out]buffer

Return buffer for password.

size_tN/Abuffer_size

Size of the return buffer in bytes.

size_t *[out]buffer_length

Actual size of the password in bytes.


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
TypeDirectionArgument NameDescription
const psa_crypto_driver_pake_inputs_t *[in]inputs

Operation inputs.

size_t *[out]user_len

User id length.


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
TypeDirectionArgument NameDescription
const psa_crypto_driver_pake_inputs_t *[in]inputs

Operation inputs.

size_t *[out]peer_len

Peer id length.


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
TypeDirectionArgument NameDescription
const psa_crypto_driver_pake_inputs_t *[in]inputs

Operation inputs.

uint8_t *[out]user_id

User id.

size_tN/Auser_id_size

Size of user_id in bytes.

size_t *[out]user_id_len

Size of the user id in bytes.


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
TypeDirectionArgument NameDescription
const psa_crypto_driver_pake_inputs_t *[in]inputs

Operation inputs.

uint8_t *[out]peer_id

Peer id.

size_tN/Apeer_id_size

Size of peer_id in bytes.

size_t *[out]peer_id_length

Size of the peer id in bytes.


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
TypeDirectionArgument NameDescription
const psa_crypto_driver_pake_inputs_t *[in]inputs

Operation inputs.

psa_pake_cipher_suite_t *[out]cipher_suite

Return buffer for role.