Password-authenticated key exchange (PAKE)

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.

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.

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.

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.

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.

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	user_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.

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.

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 , 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.

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

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.

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.

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.

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.

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.

The client in an augmented PAKE.

Augmented PAKE algorithms need to differentiate between client and server.

The server in an augmented PAKE.

Augmented PAKE algorithms need to differentiate between client and server.

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

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

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

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 .

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 .

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 .

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.

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.

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.

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.

Encoding of the primitive associated with the PAKE.

For more information see the documentation of the PSA_PAKE_PRIMITIVE macro.