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)

#define	PSA_PAKE_STEP_CONFIRM ((psa_pake_step_t) 0x04)

Typedefs
typedef uint8_t	psa_pake_role_t
	Encoding of the application role of PAKE. More...

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

typedef uint32_t	psa_pake_primitive_t
	Encoding of the primitive associated with the PAKE. More...

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 uint32_t	psa_pake_cs_get_key_confirmation (const psa_pake_cipher_suite_t *cipher_suite)

static void	psa_pake_cs_set_key_confirmation (psa_pake_cipher_suite_t *cipher_suite, uint32_t key_confirmation)

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, mbedtls_svc_key_id_t password_key, const psa_pake_cipher_suite_t cipher_suite)

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_set_context (psa_pake_operation_t operation, const uint8_t context, size_t context_len)

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_shared_key (psa_pake_operation_t operation, const psa_key_attributes_t attributes, mbedtls_svc_key_id_t *key)

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

#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))))

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 787 of file crypto_extra.h.

Referenced by psa_pake_cs_get_primitive().

#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:

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().
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 766 of file crypto_extra.h.

#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:

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().
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 746 of file crypto_extra.h.

#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 720 of file crypto_extra.h.

#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 705 of file crypto_extra.h.

#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 696 of file crypto_extra.h.

#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 714 of file crypto_extra.h.

#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 726 of file crypto_extra.h.

#define PSA_PAKE_STEP_CONFIRM ((psa_pake_step_t) 0x04)

The key confirmation value.

This is only used with PAKE algorithms with an explicit key confirmation phase.

Refer to the documentation of the PAKE algorithm for information about the input format.

Definition at line 852 of file crypto_extra.h.

#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 804 of file crypto_extra.h.

#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 842 of file crypto_extra.h.

#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 821 of file crypto_extra.h.

Typedef Documentation

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 1216 of file crypto_extra.h.

typedef struct psa_jpake_computation_stage_s psa_jpake_computation_stage_t

The type of computation stage for J-PAKE operations.

Definition at line 1219 of file crypto_extra.h.

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 1087 of file crypto_extra.h.

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 684 of file crypto_extra.h.

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

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 1213 of file crypto_extra.h.

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 690 of file crypto_extra.h.

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 677 of file crypto_extra.h.

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 659 of file crypto_extra.h.

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 667 of file crypto_extra.h.

Function Documentation

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

static struct psa_pake_cipher_suite_s psa_pake_cipher_suite_init ( void )

static

Return an initial value for a PAKE cipher suite object.

Definition at line 1931 of file crypto_extra.h.

References PSA_PAKE_CIPHER_SUITE_INIT.

static psa_algorithm_t psa_pake_cs_get_algorithm ( const psa_pake_cipher_suite_t * cipher_suite )

inlinestatic

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 1874 of file crypto_extra.h.

References psa_pake_cipher_suite_s::algorithm.

static uint16_t psa_pake_cs_get_bits ( const psa_pake_cipher_suite_t * cipher_suite )

inlinestatic

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 1913 of file crypto_extra.h.

References psa_pake_cipher_suite_s::bits.

static psa_pake_family_t psa_pake_cs_get_family ( const psa_pake_cipher_suite_t * cipher_suite )

inlinestatic

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 1907 of file crypto_extra.h.

References psa_pake_cipher_suite_s::family.

static uint32_t psa_pake_cs_get_key_confirmation ( const psa_pake_cipher_suite_t * cipher_suite )

inlinestatic

Retrieve the key confirmation from a PAKE cipher suite.

Parameters

[in] cipher_suite The cipher suite structure to query.

Returns: A key confirmation value: either PSA_PAKE_CONFIRMED_KEY or PSA_PAKE_UNCONFIRMED_KEY.

Definition at line 1920 of file crypto_extra.h.

References psa_pake_cipher_suite_s::key_confirmation.

static psa_pake_primitive_t psa_pake_cs_get_primitive ( const psa_pake_cipher_suite_t * cipher_suite )

inlinestatic

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

static void psa_pake_cs_set_algorithm	(	psa_pake_cipher_suite_t *	cipher_suite,
		psa_algorithm_t	algorithm
	)

inlinestatic

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 1880 of file crypto_extra.h.

References psa_pake_cipher_suite_s::algorithm, and PSA_ALG_IS_PAKE.

static void psa_pake_cs_set_key_confirmation	(	psa_pake_cipher_suite_t *	cipher_suite,
		uint32_t	key_confirmation
	)

inlinestatic

Declare the key confirmation for a PAKE cipher suite.

This function overwrites any key confirmation previously set in cipher_suite.

The documentation of individual PAKE algorithms specifies which key confirmation values are valid for the algorithm.

Parameters

[out]	cipher_suite	The cipher suite structure to write to.
[in]	key_confirmation	The key confirmation value to write: either PSA_PAKE_CONFIRMED_KEY or PSA_PAKE_UNCONFIRMED_KEY.

Definition at line 1925 of file crypto_extra.h.

References psa_pake_cipher_suite_s::key_confirmation.

static void psa_pake_cs_set_primitive	(	psa_pake_cipher_suite_t *	cipher_suite,
		psa_pake_primitive_t	primitive
	)

inlinestatic

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 1898 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_status_t psa_pake_get_shared_key	(	psa_pake_operation_t *	operation,
		const psa_key_attributes_t *	attributes,
		mbedtls_svc_key_id_t *	key
	)

Extract the shared secret from the PAKE as a key.

This is the final call in a PAKE operation, which retrieves the shared secret as a key. It is recommended that this key is used as an input to a key derivation operation to produce additional cryptographic keys. For some PAKE algorithms, the shared secret is also suitable for use as a key in cryptographic operations such as encryption. Refer to the documentation of individual PAKE algorithms for more information, see PAKE algorithms.

Depending on the key confirmation requested in the cipher suite, psa_pake_get_shared_key() must be called either before or after the key-confirmation output and input steps for the PAKE algorithm. The key confirmation affects the guarantees that can be made about the shared key:

Unconfirmed key:

If the cipher suite used to set up the operation requested an unconfirmed key, the application must call psa_pake_get_shared_key() after the key-exchange output and input steps are completed. The PAKE algorithm provides a cryptographic guarantee that only a peer who used the same password and identity inputs is able to compute the same key. However, there is no guarantee that the peer is the participant it claims to be and was able to compute the same key.

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

Note: Some PAKE algorithms do not enable the output of the shared secret until it has been confirmed.

Confirmed key:

If the cipher suite used to set up the operation requested a confirmed key, the application must call psa_pake_get_shared_key() after the key-exchange and key-confirmation output and input steps are completed.

Following key confirmation, the PAKE algorithm provides a cryptographic guarantee that the peer used the same password and identity inputs, and has computed the identical shared secret key.

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

Note: Some PAKE algorithms do not include any key-confirmation steps.

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 algorithms for more information. See PAKE algorithms.

When this function returns successfully, the operation becomes inactive. 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.
[in]	attributes	The attributes for the new key. This function uses the attributes as follows: The key type is required. All PAKE algorithms can output a key of type PSA_KEY_TYPE_DERIVE or PSA_KEY_TYPE_HMAC. PAKE algorithms that produce a pseudo-random shared secret, can also output block-cipher key types, for example PSA_KEY_TYPE_AES. Refer to the documentation of individual PAKE algorithms for more information. See PAKE algorithms.

The key size in attributes must be zero. The returned key size is always determined from the PAKE shared secret.

The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation.

The key usage flags define what operations are permitted with the key.

The key lifetime and identifier are required for a persistent key.

Note: This is an input parameter: It is not updated with the final key attributes. The final attributes of the new key can be queried by calling psa_get_key_attributes() with the key’s identifier.

Parameters

[out] key On success, an identifier for the newly created key. PSA_KEY_ID_NULL on failure.

Return values

PSA_SUCCESS	Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.
PSA_ERROR_BAD_STATE	The following conditions can result in this error: The state of PAKE operation `operation` is not valid: It must be ready to return the shared secret. For an unconfirmed key, this will be when the key-exchange output and input steps are complete, but prior to any key-confirmation output and input steps. For a confirmed key, this will be when all key-exchange and key-confirmation output and input steps are complete. The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_NOT_PERMITTED	The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.
PSA_ERROR_ALREADY_EXISTS	This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_INVALID_ARGUMENT	The following conditions can result in this error: The `key` type is not valid for output from this `operation’s` algorithm. The `key` size is nonzero. The `key` lifetime is invalid. The `key` identifier is not valid for the key lifetime. The `key` usage flags include invalid values. The `key’s` permitted-usage algorithm is invalid. The `key` attributes, as a whole, are invalid.
PSA_ERROR_NOT_SUPPORTED	The `key` attributes, as a whole, are not supported for creation from a PAKE secret, either by the implementation in general or in the specified storage location.
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_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.

static struct psa_pake_operation_s psa_pake_operation_init ( void )

static

Return an initial value for a PAKE operation object.

Definition at line 1937 of file crypto_extra.h.

References PSA_PAKE_OPERATION_INIT.

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_status_t psa_pake_set_context	(	psa_pake_operation_t *	operation,
		const uint8_t *	context,
		size_t	context_len
	)

Set the context data for a password-authenticated key exchange.

Not all PAKE algorithms use context data. Only call this function for algorithms that need it.

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 an operation for which the context hasn't been specified (psa_pake_set_context() hasn't been called yet).
[in]	context	The context to set.
	context_len	The length of `context` in bytes.

Return values

PSA_SUCCESS	Success.
PSA_ERROR_INVALID_ARGUMENT	The algorithm in `operation` does not use a context.
PSA_ERROR_NOT_SUPPORTED	The library configuration does not support PAKE algorithms with a context, or this specific context value is not supported for the given `operation`.
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_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_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_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_status_t psa_pake_setup	(	psa_pake_operation_t *	operation,
		mbedtls_svc_key_id_t	password_key,
		const psa_pake_cipher_suite_t *	cipher_suite
	)

Setup a password-authenticated key exchange.

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

Allocate a PAKE operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_pake_operation_t. For example, using PSA_PAKE_OPERATION_INIT.
Call psa_pake_setup() to specify the cipher suite.
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.

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

Call psa_pake_output(operation, PSA_PAKE_STEP_KEY_SHARE, ...) to get the key share that needs to be sent to the peer.
Call psa_pake_input(operation, PSA_PAKE_STEP_KEY_SHARE, ...) to provide the key share that was received from the peer.
Depending on the algorithm additional calls to psa_pake_output() and psa_pake_input() might be necessary.
Call psa_pake_get_shared_key() to access the shared secret.

Refer to the documentation of individual PAKE algorithms for details on the required set up and operation for each algorithm, and for constraints on the format and content of valid passwords. See PAKE algorithms.

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

A successful call to psa_pake_get_shared_key().
A call to psa_pake_abort().

If psa_pake_setup() returns an error, the operation object is unchanged. If a subsequent function call with an active operation returns an error, the operation enters an error state.

To abandon an active operation, or reset an operation in an error state, call psa_pake_abort().

Parameters

[in,out]	operation	The operation object to set up. It must have been initialized as per the documentation for psa_pake_operation_t and not yet in use.
[in]	password_key	Identifier of the key holding the password or a value derived from the password. It must remain valid until the operation terminates.

The valid key types depend on the PAKE algorithm, and participant role. Refer to the documentation of individual PAKE algorithms for more information, see PAKE algorithms.

The key must permit the usage PSA_KEY_USAGE_DERIVE.

Parameters

[in] cipher_suite The cipher suite to use. A PAKE cipher suite fully characterizes a PAKE algorithm, including the PAKE algorithm.

The cipher suite must be compatible with the key type of password_key.

Return values

PSA_SUCCESS	Success. The operation is now active.
PSA_ERROR_BAD_STATE	The following conditions can result in this error: The operation state is not valid: it must be inactive. The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE	`password_key` is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED	`password_key` does not have the PSA_KEY_USAGE_DERIVE flag, or it does not permit the algorithm in `cipher_suite`.
PSA_ERROR_INVALID_ARGUMENT	The following conditions can result in this error: The algorithm in `cipher_suite` is not a PAKE algorithm, or encodes an invalid hash algorithm. The PAKE primitive in `cipher_suite` is not compatible with the PAKE algorithm. The key confirmation value in `cipher_suite` is not compatible with the PAKE algorithm and primitive. The key type or key size of `password_key` is not compatible with `cipher_suite`.
PSA_ERROR_NOT_SUPPORTED	The following conditions can result in this error: The algorithm in `cipher_suite` is not a supported PAKE algorithm, or encodes an unsupported hash algorithm. The PAKE primitive in `cipher_suite` is not supported or not compatible with the PAKE algorithm. The key confirmation value in `cipher_suite` is not supported, or not compatible, with the PAKE algorithm and primitive. The key type or key size of `password_key` is not supported with `cipher_suite`.
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation