File crypto_extra.h

PSA cryptography module: Mbed TLS vendor extensions.

This file is reserved for vendor-specific definitions.

Note

This file may not be included directly. Applications must include psa/crypto.h.

SECTION: Module configuration options

This section allows for the setting of module specific sizes and configuration options. The default values are already present in the relevant header files and should suffice for the regular use cases.

Our advice is to enable options and change their values here only if you have a good reason and know the consequences.

MBEDTLS_PSA_KEY_SLOT_COUNT

Use HMAC_DRBG with the specified hash algorithm for HMAC_DRBG for the PSA crypto subsystem.

If this option is unset:

If CTR_DRBG is available, the PSA subsystem uses it rather than HMAC_DRBG.
Otherwise, the PSA subsystem uses HMAC_DRBG with either MBEDTLS_MD_SHA512 or MBEDTLS_MD_SHA256 based on availability and on unspecified heuristics.

Restrict the PSA library to supporting a maximum amount of simultaneously loaded keys. A loaded key is a key stored by the PSA Crypto core as a volatile key, or a persistent key which is loaded temporarily by the library as part of a crypto operation in flight.

If this option is unset, the library will fall back to a default value of 32 keys.

Defines

PSA_CRYPTO_ITS_RANDOM_SEED_UID

PSA_KEY_TYPE_DSA_PUBLIC_KEY

DSA public key.

The import and export format is the representation of the public key y = g^x mod p as a big-endian byte string. The length of the byte string is the length of the base prime p in bytes.

PSA_KEY_TYPE_DSA_KEY_PAIR

DSA key pair (private and public key).

The import and export format is the representation of the private key x as a big-endian byte string. The length of the byte string is the private key size in bytes (leading zeroes are not stripped).

Deterministic DSA key derivation with psa_generate_derived_key follows FIPS 186-4 B.1.2: interpret the byte string as integer in big-endian order. Discard it if it is not in the range [0, N - 2] where N is the boundary of the private key domain (the prime p for Diffie-Hellman, the subprime q for DSA, or the order of the curve’s base point for ECC). Add 1 to the resulting integer and use this as the private key x.

PSA_KEY_TYPE_IS_DSA(type): Whether a key type is a DSA key (pair or public-only).

PSA_ALG_DSA_BASE

PSA_ALG_DSA(hash_alg)

DSA signature with hashing.

This is the signature scheme defined by FIPS 186-4, with a random per-message secret number (k).

Parameters

hash_alg – A hash algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_HASH(hash_alg) is true). This includes PSA_ALG_ANY_HASH when specifying the algorithm in a usage policy.

Returns

The corresponding DSA signature algorithm.

Returns

Unspecified if hash_alg is not a supported hash algorithm.

PSA_ALG_DETERMINISTIC_DSA_BASE

PSA_ALG_DSA_DETERMINISTIC_FLAG

PSA_ALG_DETERMINISTIC_DSA(hash_alg)

Deterministic DSA signature with hashing.

This is the deterministic variant defined by RFC 6979 of the signature scheme defined by FIPS 186-4.

Parameters

hash_alg – A hash algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_HASH(hash_alg) is true). This includes PSA_ALG_ANY_HASH when specifying the algorithm in a usage policy.

Returns

The corresponding DSA signature algorithm.

Returns

Unspecified if hash_alg is not a supported hash algorithm.

PSA_ALG_IS_DSA(alg)

PSA_ALG_DSA_IS_DETERMINISTIC(alg)

PSA_ALG_IS_DETERMINISTIC_DSA(alg)

PSA_ALG_IS_RANDOMIZED_DSA(alg)

PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg)

PSA_DH_FAMILY_CUSTOM

Custom Diffie-Hellman group.

For keys of type PSA_KEY_TYPE_DH_PUBLIC_KEY(PSA_DH_FAMILY_CUSTOM) or PSA_KEY_TYPE_DH_KEY_PAIR(PSA_DH_FAMILY_CUSTOM), the group data comes from domain parameters set by psa_set_key_domain_parameters().

PSA_PAKE_OPERATION_STAGE_SETUP: PAKE operation stages.

PSA_PAKE_OPERATION_STAGE_COLLECT_INPUTS

PSA_PAKE_OPERATION_STAGE_COMPUTATION

PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits)

Safe output buffer size for psa_get_key_domain_parameters().

This macro returns a compile-time constant if its arguments are compile-time constants.

Note

This is an experimental extension to the interface. It may change in future versions of the library.

Warning

This function may call its arguments multiple times or zero times, so you should not pass arguments that contain side effects.

Parameters

key_type – A supported key type.
key_bits – The size of the key in bits.

Returns

If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_get_key_domain_parameters() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are a valid combination that is not supported by the implementation, this macro shall return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.

PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits)

PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits)

MBEDTLS_PSA_KEY_ID_BUILTIN_MIN

The minimum value for a key identifier that is built into the implementation.

The range of key identifiers from MBEDTLS_PSA_KEY_ID_BUILTIN_MIN to MBEDTLS_PSA_KEY_ID_BUILTIN_MAX within the range from PSA_KEY_ID_VENDOR_MIN and PSA_KEY_ID_VENDOR_MAX and must not intersect with any other set of implementation-chosen key identifiers.

This value is part of the library’s ABI since changing it would invalidate the values of built-in key identifiers in applications.

MBEDTLS_PSA_KEY_ID_BUILTIN_MAX

The maximum value for a key identifier that is built into the implementation.

See MBEDTLS_PSA_KEY_ID_BUILTIN_MIN for more information.

PSA_ALG_CATEGORY_PAKE

PSA_ALG_IS_PAKE(alg)

Whether the specified algorithm is a password-authenticated key exchange.

Parameters

alg – An algorithm identifier (value of type psa_algorithm_t).

Returns

1 if alg is a password-authenticated key exchange (PAKE) algorithm, 0 otherwise. This macro may return either 0 or 1 if alg is not a supported algorithm identifier.

PSA_ALG_JPAKE

The Password-authenticated key exchange by juggling (J-PAKE) algorithm.

This is J-PAKE as defined by RFC 8236, instantiated with the following parameters:

The group can be either an elliptic curve or defined over a finite field.
Schnorr NIZK proof as defined by RFC 8235 and using the same group as the J-PAKE algorithm.
A cryptographic hash function.

To select these parameters and set up the cipher suite, call these functions in any order:

psa_pake_cs_set_algorithm(cipher_suite, PSA_ALG_JPAKE);
psa_pake_cs_set_primitive(cipher_suite,
                          PSA_PAKE_PRIMITIVE(type, family, bits));
psa_pake_cs_set_hash(cipher_suite, hash);

For more information on how to set a specific curve or field, refer to the documentation of the individual PSA_PAKE_PRIMITIVE_TYPE_XXX constants.

After initializing a J-PAKE operation, call

psa_pake_setup(operation, cipher_suite);
psa_pake_set_user(operation, ...);
psa_pake_set_peer(operation, ...);
psa_pake_set_password_key(operation, ...);

The password is provided as a key. This can be the password text itself, in an agreed character encoding, or some value derived from the password as required by a higher level protocol.

(The implementation converts the key material to a number as described in Section 2.3.8 of SEC 1: Elliptic Curve Cryptography (https://www.secg.org/sec1-v2.pdf), before reducing it modulo q. Here q is order of the group defined by the primitive set in the cipher suite. The psa_pake_set_password_key() function returns an error if the result of the reduction is 0.)

The key exchange flow for J-PAKE is as follows:

To get the first round data that needs to be sent to the peer, call

// Get g1
psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
// Get the ZKP public key for x1
psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
// Get the ZKP proof for x1
psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
// Get g2
psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
// Get the ZKP public key for x2
psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
// Get the ZKP proof for x2
psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);

To provide the first round data received from the peer to the operation, call

// Set g3
psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
// Set the ZKP public key for x3
psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
// Set the ZKP proof for x3
psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
// Set g4
psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
// Set the ZKP public key for x4
psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
// Set the ZKP proof for x4
psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);

To get the second round data that needs to be sent to the peer, call

// Get A
psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
// Get ZKP public key for x2*s
psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
// Get ZKP proof for x2*s
psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);

To provide the second round data received from the peer to the operation, call

// Set B
psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
// Set ZKP public key for x4*s
psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
// Set ZKP proof for x4*s
psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);

To access the shared secret call

// Get Ka=Kb=K
psa_pake_get_implicit_key()

For more information consult the documentation of the individual PSA_PAKE_STEP_XXX constants.

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 (the peer is not authenticated at this point, and no action should be taken that assume that they are - like for example accessing restricted files).

To make the authentication explicit there are various methods, see Section 5 of RFC 8236 for two examples.

PSA_PAKE_ROLE_NONE: 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.

PSA_PAKE_ROLE_FIRST

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.

PSA_PAKE_ROLE_SECOND

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.

PSA_PAKE_ROLE_CLIENT

The client in an augmented PAKE.

Augmented PAKE algorithms need to differentiate between client and server.

PSA_PAKE_ROLE_SERVER

The server in an augmented PAKE.

Augmented PAKE algorithms need to differentiate between client and server.

PSA_PAKE_PRIMITIVE_TYPE_ECC

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

PSA_PAKE_PRIMITIVE_TYPE_DH

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

PSA_PAKE_PRIMITIVE(pake_type, pake_family, 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.

PSA_PAKE_STEP_KEY_SHARE

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.

PSA_PAKE_STEP_ZK_PUBLIC

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.

PSA_PAKE_STEP_ZK_PROOF

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.

PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step)

A sufficient output buffer size for psa_pake_output().

If the size of the output buffer is at least this large, it is guaranteed that psa_pake_output() will not fail due to an insufficient output buffer size. The actual size of the output might be smaller in any given call.

See also PSA_PAKE_INPUT_MAX_SIZE

Parameters

alg – A PAKE algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_PAKE(alg) is true).
primitive – A primitive of type psa_pake_primitive_t that is compatible with algorithm alg.
input_step – A value of type psa_pake_step_t that is valid for the algorithm alg.

Returns

A sufficient input buffer size for the specified input, cipher suite and algorithm. If the cipher suite, the input type or PAKE algorithm is not recognized, or the parameters are incompatible, return 0.

PSA_PAKE_OUTPUT_MAX_SIZE

Output buffer size for psa_pake_output() for any of the supported PAKE algorithm and primitive suites and output step.

This macro must expand to a compile-time constant integer.

The value of this macro must be at least as large as the largest value returned by PSA_PAKE_OUTPUT_SIZE()

See also PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step).

PSA_PAKE_INPUT_MAX_SIZE

Input buffer size for psa_pake_input() for any of the supported PAKE algorithm and primitive suites and input step.

This macro must expand to a compile-time constant integer.

The value of this macro must be at least as large as the largest value returned by PSA_PAKE_INPUT_SIZE()

See also PSA_PAKE_INPUT_SIZE(alg, primitive, output_step).

PSA_PAKE_CIPHER_SUITE_INIT: Returns a suitable initializer for a PAKE cipher suite object of type psa_pake_cipher_suite_t.

PSA_PAKE_OPERATION_INIT: Returns a suitable initializer for a PAKE operation object of type psa_pake_operation_t.

PSA_JPAKE_EXPECTED_INPUTS(round)

PSA_JPAKE_EXPECTED_OUTPUTS(round)

Typedefs

typedef struct mbedtls_psa_stats_s mbedtls_psa_stats_t: Statistics about resource consumption related to the PSA keystore.

Note

The content of this structure is not part of the stable API and ABI of Mbed TLS and may change arbitrarily from version to version.

typedef uint64_t psa_drv_slot_number_t

A slot number identifying a key in a driver.

Values of this type are used to identify built-in keys.

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.

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.

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.

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.

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.

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.

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.

typedef struct psa_crypto_driver_pake_inputs_s psa_crypto_driver_pake_inputs_t: The type of input values for PAKE operations.

typedef struct psa_jpake_computation_stage_s psa_jpake_computation_stage_t: The type of computation stage for J-PAKE operations.

typedef enum psa_crypto_driver_pake_step psa_crypto_driver_pake_step_t

typedef enum psa_jpake_round psa_jpake_round_t

typedef enum psa_jpake_io_mode psa_jpake_io_mode_t

Enums

enum psa_crypto_driver_pake_step

Values:

enumerator PSA_JPAKE_STEP_INVALID

enumerator PSA_JPAKE_X1_STEP_KEY_SHARE

enumerator PSA_JPAKE_X1_STEP_ZK_PUBLIC

enumerator PSA_JPAKE_X1_STEP_ZK_PROOF

enumerator PSA_JPAKE_X2_STEP_KEY_SHARE

enumerator PSA_JPAKE_X2_STEP_ZK_PUBLIC

enumerator PSA_JPAKE_X2_STEP_ZK_PROOF

enumerator PSA_JPAKE_X2S_STEP_KEY_SHARE

enumerator PSA_JPAKE_X2S_STEP_ZK_PUBLIC

enumerator PSA_JPAKE_X2S_STEP_ZK_PROOF

enumerator PSA_JPAKE_X4S_STEP_KEY_SHARE

enumerator PSA_JPAKE_X4S_STEP_ZK_PUBLIC

enumerator PSA_JPAKE_X4S_STEP_ZK_PROOF

enum psa_jpake_round

Values:

enumerator PSA_JPAKE_FIRST

enumerator PSA_JPAKE_SECOND

enumerator PSA_JPAKE_FINISHED

enum psa_jpake_io_mode

Values:

enumerator PSA_JPAKE_INPUT

enumerator PSA_JPAKE_OUTPUT

Functions

static inline void psa_set_key_enrollment_algorithm(psa_key_attributes_t *attributes, psa_algorithm_t alg2)

Declare the enrollment algorithm for a key.

An operation on a key may indifferently use the algorithm set with psa_set_key_algorithm() or with this function.

Warning

Setting an enrollment algorithm is not recommended, because using the same key with different algorithms can allow some attacks based on arithmetic relations between different computations made with the same key, or can escalate harmless side channels into exploitable ones. Use this function only if it is necessary to support a protocol for which it has been verified that the usage of the key with multiple algorithms is safe.

Parameters

attributes – [out] The attribute structure to write to.
alg2 – A second algorithm that the key may be used for, in addition to the algorithm set with psa_set_key_algorithm().

static inline psa_algorithm_t psa_get_key_enrollment_algorithm(const psa_key_attributes_t *attributes)

Retrieve the enrollment algorithm policy from key attributes.

Parameters: attributes – [in] The key attribute structure to query.
Returns: The enrollment algorithm stored in the attribute structure.

psa_status_t psa_get_key_slot_number(const psa_key_attributes_t *attributes, psa_key_slot_number_t *slot_number)

Retrieve the slot number where a key is stored.

A slot number is only defined for keys that are stored in a secure element.

This information is only useful if the secure element is not entirely managed through the PSA Cryptography API. It is up to the secure element driver to decide how PSA slot numbers map to any other interface that the secure element may have.

Parameters

attributes – [in] The key attribute structure to query.
slot_number – [out] On success, the slot number containing the key.

Return values

PSA_SUCCESS – The key is located in a secure element, and *slot_number indicates the slot number that contains it.
PSA_ERROR_NOT_PERMITTED – The caller is not permitted to query the slot number. Mbed TLS currently does not return this error.
PSA_ERROR_INVALID_ARGUMENT – The key is not located in a secure element.

static inline void psa_set_key_slot_number(psa_key_attributes_t *attributes, psa_key_slot_number_t slot_number)

Choose the slot number where a key is stored.

This function declares a slot number in the specified attribute structure.

A slot number is only meaningful for keys that are stored in a secure element. It is up to the secure element driver to decide how PSA slot numbers map to any other interface that the secure element may have.

Note

Setting a slot number in key attributes for a key creation can cause the following errors when creating the key:

PSA_ERROR_NOT_SUPPORTED if the selected secure element does not support choosing a specific slot number.
PSA_ERROR_NOT_PERMITTED if the caller is not permitted to choose slot numbers in general or to choose this specific slot.
PSA_ERROR_INVALID_ARGUMENT if the chosen slot number is not valid in general or not valid for this specific key.
PSA_ERROR_ALREADY_EXISTS if there is already a key in the selected slot.

Parameters

attributes – [out] The attribute structure to write to.
slot_number – The slot number to set.

static inline void psa_clear_key_slot_number(psa_key_attributes_t *attributes)

Remove the slot number attribute from a key attribute structure.

This function undoes the action of psa_set_key_slot_number().

Parameters: attributes – [out] The attribute structure to write to.

psa_status_t mbedtls_psa_register_se_key(const psa_key_attributes_t *attributes)

Register a key that is already present in a secure element.

The key must be located in a secure element designated by the lifetime field in attributes, in the slot set with psa_set_key_slot_number() in the attribute structure. This function makes the key available through the key identifier specified in attributes.

Parameters

attributes – [in] The attributes of the existing key.

Return values

PSA_SUCCESS – The key was successfully registered. Note that depending on the design of the driver, this may or may not guarantee that a key actually exists in the designated slot and is compatible with the specified attributes.
PSA_ERROR_ALREADY_EXISTS – There is already a key with the identifier specified in attributes.
PSA_ERROR_NOT_SUPPORTED – The secure element driver for the specified lifetime does not support registering a key.
PSA_ERROR_INVALID_ARGUMENT – The identifier in attributes is invalid, namely the identifier is not in the user range, or attributes specifies a lifetime which is not located in a secure element, or no slot number is specified in attributes, or the specified slot number is not valid.
PSA_ERROR_NOT_PERMITTED – The caller is not authorized to register the specified key slot.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_INSUFFICIENT_STORAGE –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_DATA_CORRUPT –
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.

void mbedtls_psa_crypto_free(void)

Library deinitialization.

This function clears all data associated with the PSA layer, including the whole key store.

This is an Mbed TLS extension.

void mbedtls_psa_get_stats(mbedtls_psa_stats_t *stats): Get statistics about resource consumption related to the PSA keystore.

Note

When Mbed TLS is built as part of a service, with isolation between the application and the keystore, the service may or may not expose this function.

psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed, size_t seed_size)

Inject an initial entropy seed for the random generator into secure storage.

This function injects data to be used as a seed for the random generator used by the PSA Crypto implementation. On devices that lack a trusted entropy source (preferably a hardware random number generator), the Mbed PSA Crypto implementation uses this value to seed its random generator.

On devices without a trusted entropy source, this function must be called exactly once in the lifetime of the device. On devices with a trusted entropy source, calling this function is optional. In all cases, this function may only be called before calling any other function in the PSA Crypto API, including psa_crypto_init().

When this function returns successfully, it populates a file in persistent storage. Once the file has been created, this function can no longer succeed.

If any error occurs, this function does not change the system state. You can call this function again after correcting the reason for the error if possible.

This is an Mbed TLS extension.

Warning

This function can fail! Callers MUST check the return status.

Warning

If you use this function, you should use it as part of a factory provisioning process. The value of the injected seed is critical to the security of the device. It must be secret, unpredictable and (statistically) unique per device. You should be generate it randomly using a cryptographically secure random generator seeded from trusted entropy sources. You should transmit it securely to the device and ensure that its value is not leaked or stored anywhere beyond the needs of transmitting it from the point of generation to the call of this function, and erase all copies of the value once this function returns.

Note

This function is only available on the following platforms:

If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled. Note that you must provide compatible implementations of mbedtls_nv_seed_read and mbedtls_nv_seed_write.
In a client-server integration of PSA Cryptography, on the client side, if the server supports this feature.

Parameters

seed – [in] Buffer containing the seed value to inject.
seed_size – [in] Size of the seed buffer. The size of the seed in bytes must be greater or equal to both MBEDTLS_ENTROPY_BLOCK_SIZE and the value of MBEDTLS_ENTROPY_MIN_PLATFORM in library/entropy_poll.h in the Mbed TLS source code. It must be less or equal to MBEDTLS_ENTROPY_MAX_SEED_SIZE.

Return values

PSA_SUCCESS – The seed value was injected successfully. The random generator of the PSA Crypto implementation is now ready for use. You may now call psa_crypto_init() and use the PSA Crypto implementation.
PSA_ERROR_INVALID_ARGUMENT – seed_size is out of range.
PSA_ERROR_STORAGE_FAILURE – There was a failure reading or writing from storage.
PSA_ERROR_NOT_PERMITTED – The library has already been initialized. It is no longer possible to call this function.

psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes, psa_key_type_t type, const uint8_t *data, size_t data_length)

Set domain parameters for a key.

Some key types require additional domain parameters in addition to the key type identifier and the key size. Use this function instead of psa_set_key_type() when you need to specify domain parameters.

The format for the required domain parameters varies based on the key type.

For RSA keys (PSA_KEY_TYPE_RSA_PUBLIC_KEY or PSA_KEY_TYPE_RSA_KEY_PAIR), the domain parameter data consists of the public exponent, represented as a big-endian integer with no leading zeros. This information is used when generating an RSA key pair. When importing a key, the public exponent is read from the imported key data and the exponent recorded in the attribute structure is ignored. As an exception, the public exponent 65537 is represented by an empty byte string.

For DSA keys (PSA_KEY_TYPE_DSA_PUBLIC_KEY or PSA_KEY_TYPE_DSA_KEY_PAIR), the Dss-Params format as defined by RFC 3279 2.3.2.

Dss-Params ::= SEQUENCE  {
   p       INTEGER,
   q       INTEGER,
   g       INTEGER
}

For Diffie-Hellman key exchange keys (PSA_KEY_TYPE_DH_PUBLIC_KEY(PSA_DH_FAMILY_CUSTOM) or PSA_KEY_TYPE_DH_KEY_PAIR(PSA_DH_FAMILY_CUSTOM)), the DomainParameters format as defined by RFC 3279 2.3.3.

DomainParameters ::= SEQUENCE {
   p               INTEGER,                    -- odd prime, p=jq +1
   g               INTEGER,                    -- generator, g
   q               INTEGER,                    -- factor of p-1
   j               INTEGER OPTIONAL,           -- subgroup factor
   validationParams ValidationParams OPTIONAL
}
ValidationParams ::= SEQUENCE {
   seed            BIT STRING,
   pgenCounter     INTEGER
}

Note

This function may allocate memory or other resources. Once you have called this function on an attribute structure, you must call psa_reset_key_attributes() to free these resources.

Note

This is an experimental extension to the interface. It may change in future versions of the library.

Parameters

attributes – [inout] Attribute structure where the specified domain parameters will be stored. If this function fails, the content of attributes is not modified.
type – Key type (a PSA_KEY_TYPE_XXX value).
data – [in] Buffer containing the key domain parameters. The content of this buffer is interpreted according to type as described above.
data_length – Size of the data buffer in bytes.

Return values

PSA_SUCCESS –
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INSUFFICIENT_MEMORY –

psa_status_t psa_get_key_domain_parameters(const psa_key_attributes_t *attributes, uint8_t *data, size_t data_size, size_t *data_length)

Get domain parameters for a key.

Get the domain parameters for a key with this function, if any. The format of the domain parameters written to data is specified in the documentation for psa_set_key_domain_parameters().

Note

This is an experimental extension to the interface. It may change in future versions of the library.

Parameters

attributes – [in] The key attribute structure to query.
data – [out] On success, the key domain parameters.
data_size – Size of the data buffer in bytes. The buffer is guaranteed to be large enough if its size in bytes is at least the value given by PSA_KEY_DOMAIN_PARAMETERS_SIZE().
data_length – [out] On success, the number of bytes that make up the key domain parameters data.

Return values

PSA_SUCCESS –
PSA_ERROR_BUFFER_TOO_SMALL –

psa_ecc_family_t mbedtls_ecc_group_to_psa(mbedtls_ecp_group_id grpid, size_t *bits)

Convert an ECC curve identifier from the Mbed TLS encoding to PSA.

Note

This function is provided solely for the convenience of Mbed TLS and may be removed at any time without notice.

Parameters

grpid – An Mbed TLS elliptic curve identifier (MBEDTLS_ECP_DP_xxx).
bits – [out] On success, the bit size of the curve.

Returns

The corresponding PSA elliptic curve identifier (PSA_ECC_FAMILY_xxx).

Returns

0 on failure (grpid is not recognized).

mbedtls_ecp_group_id mbedtls_ecc_group_of_psa(psa_ecc_family_t curve, size_t bits, int bits_is_sloppy)

Convert an ECC curve identifier from the PSA encoding to Mbed TLS.

Note

This function is provided solely for the convenience of Mbed TLS and may be removed at any time without notice.

Parameters

curve – A PSA elliptic curve identifier (PSA_ECC_FAMILY_xxx).
bits – The bit-length of a private key on curve.
bits_is_sloppy – If true, bits may be the bit-length rounded up to the nearest multiple of 8. This allows the caller to infer the exact curve from the length of a key which is supplied as a byte string.

Returns

The corresponding Mbed TLS elliptic curve identifier (MBEDTLS_ECP_DP_xxx).

Returns

MBEDTLS_ECP_DP_NONE if curve is not recognized.

Returns

MBEDTLS_ECP_DP_NONE if bits is not correct for curve.

psa_status_t mbedtls_psa_external_get_random(mbedtls_psa_external_random_context_t *context, uint8_t *output, size_t output_size, size_t *output_length)

External random generator function, implemented by the platform.

When the compile-time option MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled, this function replaces Mbed TLS’s entropy and DRBG modules for all random generation triggered via PSA crypto interfaces.

Note

This random generator must deliver random numbers with cryptographic quality and high performance. It must supply unpredictable numbers with a uniform distribution. The implementation of this function is responsible for ensuring that the random generator is seeded with sufficient entropy. If you have a hardware TRNG which is slow or delivers non-uniform output, declare it as an entropy source with mbedtls_entropy_add_source() instead of enabling this option.

Parameters

context – [inout] Pointer to the random generator context. This is all-bits-zero on the first call and preserved between successive calls.
output – [out] Output buffer. On success, this buffer contains random data with a uniform distribution.
output_size – The size of the output buffer in bytes.
output_length – [out] On success, set this value to output_size.

Return values

PSA_SUCCESS – Success. The output buffer contains output_size bytes of cryptographic-quality random data, and *output_length is set to output_size.
PSA_ERROR_INSUFFICIENT_ENTROPY – The random generator requires extra entropy and there is no way to obtain entropy under current environment conditions. This error should not happen under normal circumstances since this function is responsible for obtaining as much entropy as it needs. However implementations of this function may return PSA_ERROR_INSUFFICIENT_ENTROPY if there is no way to obtain entropy without blocking indefinitely.
PSA_ERROR_HARDWARE_FAILURE – A failure of the random generator hardware that isn’t covered by PSA_ERROR_INSUFFICIENT_ENTROPY.

static inline int psa_key_id_is_builtin(psa_key_id_t key_id)

Test whether a key identifier belongs to the builtin key range.

Parameters

key_id – Key identifier to test.

Return values

1 – The key identifier is a builtin key identifier.
0 – The key identifier is not a builtin key identifier.

psa_status_t mbedtls_psa_platform_get_builtin_key(mbedtls_svc_key_id_t key_id, psa_key_lifetime_t *lifetime, psa_drv_slot_number_t *slot_number)

Platform function to obtain the location and slot number of a built-in key.

An application-specific implementation of this function must be provided if MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS is enabled. This would typically be provided as part of a platform’s system image.

MBEDTLS_SVC_KEY_ID_GET_KEY_ID(key_id) needs to be in the range from MBEDTLS_PSA_KEY_ID_BUILTIN_MIN to MBEDTLS_PSA_KEY_ID_BUILTIN_MAX.

In a multi-application configuration (MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER is defined), this function should check that MBEDTLS_SVC_KEY_ID_GET_OWNER_ID(key_id) is allowed to use the given key.

Parameters

key_id – The key ID for which to retrieve the location and slot attributes.
lifetime – [out] On success, the lifetime associated with the key corresponding to key_id. Lifetime is a combination of which driver contains the key, and with what persistence level the key is intended to be used. If the platform implementation does not contain specific information about the intended key persistence level, the persistence level may be reported as PSA_KEY_PERSISTENCE_DEFAULT.
slot_number – [out] On success, the slot number known to the driver registered at the lifetime location reported through lifetime which corresponds to the requested built-in key.

Return values

PSA_SUCCESS – The requested key identifier designates a built-in key. In a multi-application configuration, the requested owner is allowed to access it.
PSA_ERROR_DOES_NOT_EXIST – The requested key identifier is not a built-in key which is known to this function. If a key exists in the key storage with this identifier, the data from the storage will be used.

Returns

(any other error) Any other error is propagated to the function that requested the key. Common errors include:

PSA_ERROR_NOT_PERMITTED: the key exists but the requested owner is not allowed to access it.

static inline psa_pake_cipher_suite_t psa_pake_cipher_suite_init(void): Return an initial value for a PAKE cipher suite object.

static inline 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: cipher_suite – [in] The cipher suite structure to query.
Returns: The PAKE algorithm stored in the cipher suite structure.

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

This function overwrites any PAKE algorithm previously set in cipher_suite.

Parameters

cipher_suite – [out] 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.

static inline 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: cipher_suite – [in] The cipher suite structure to query.
Returns: The primitive stored in the cipher suite structure.

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

This function overwrites any primitive previously set in cipher_suite.

Parameters

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

static inline 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: cipher_suite – [in] The cipher suite structure to query.
Returns: The PAKE family stored in the cipher suite structure.

static inline 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: cipher_suite – [in] The cipher suite structure to query.
Returns: The PAKE primitive bit-size stored in the cipher suite structure.

static inline 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: cipher_suite – [in] 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.

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

This function overwrites any hash algorithm previously set in cipher_suite.

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

Parameters

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

static inline psa_pake_operation_t psa_pake_operation_init(void): Return an initial value for a PAKE operation object.

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

inputs – [in] Operation inputs.
password_len – [out] 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_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

inputs – [in] Operation inputs.
buffer – [out] Return buffer for password.
buffer_size – Size of the return buffer in bytes.
buffer_length – [out] 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_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

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

Return values

PSA_SUCCESS – Success.
PSA_ERROR_BAD_STATE – User id hasn’t been set yet.

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

inputs – [in] Operation inputs.
peer_len – [out] 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

inputs – [in] Operation inputs.
user_id – [out] User id.
user_id_size – Size of user_id in bytes.
user_id_len – [out] 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_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

inputs – [in] Operation inputs.
peer_id – [out] Peer id.
peer_id_size – Size of peer_id in bytes.
peer_id_length – [out] 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_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

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

Return values

PSA_SUCCESS – Success.
PSA_ERROR_BAD_STATE – Cipher_suite hasn’t been set yet.

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

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

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

Allocate an 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, e.g. 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.

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:

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

operation – [inout] The operation object to set up. It must have been initialized but not set up yet.
cipher_suite – [in] 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.

psa_status_t psa_pake_set_password_key(psa_pake_operation_t *operation, mbedtls_svc_key_id_t password)

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

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

Parameters

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

Return values

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

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

Parameters

operation – [inout] 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).
user_id – [in] 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_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.

Parameters

operation – [inout] 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).
peer_id – [in] 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

operation – [inout] 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_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

operation – [inout] Active PAKE operation.
step – The step of the algorithm for which the output is requested.
output – [out] 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.
output_length – [out] 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_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

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

Return values

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

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

Get implicitly confirmed shared secret from a PAKE.

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

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

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

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

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

Parameters

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

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_ARGUMENT – PSA_KEY_DERIVATION_INPUT_SECRET is not compatible with the algorithm in the output key derivation operation.
PSA_ERROR_NOT_SUPPORTED – Input from a PAKE is not supported by the algorithm in the output key derivation operation.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_BAD_STATE – The PAKE operation state is not valid (it must be active, but beyond that validity is specific to the algorithm), or the library has not been previously initialized by psa_crypto_init(), or the state of output is not valid for the PSA_KEY_DERIVATION_INPUT_SECRET step. This can happen if the step is out of order or the application has done this step already and it may not be repeated. It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_pake_abort(psa_pake_operation_t *operation)

Abort a PAKE operation.

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

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

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

Parameters

operation – [inout] 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.

struct mbedtls_psa_stats_s

#include <crypto_extra.h>

Statistics about resource consumption related to the PSA keystore.

Note

The content of this structure is not part of the stable API and ABI of Mbed TLS and may change arbitrarily from version to version.

Public Members

size_t private_volatile_slots: Number of slots containing key material for a volatile key.

size_t private_persistent_slots: Number of slots containing key material for a key which is in internal persistent storage.

size_t private_external_slots: Number of slots containing a reference to a key in a secure element.

size_t private_half_filled_slots: Number of slots which are occupied, but do not contain key material yet.

size_t private_cache_slots: Number of slots that contain cache data.

size_t private_empty_slots: Number of slots that are not used for anything.

size_t private_locked_slots: Number of slots that are locked.

psa_key_id_t private_max_open_internal_key_id: Largest key id value among open keys in internal persistent storage.

psa_key_id_t private_max_open_external_key_id: Largest key id value among open keys in secure elements.

struct psa_pake_cipher_suite_s

#include <crypto_extra.h>

Public Members

psa_algorithm_t algorithm

psa_pake_primitive_type_t type

psa_pake_family_t family

uint16_t bits

psa_algorithm_t hash

struct psa_crypto_driver_pake_inputs_s

#include <crypto_extra.h>

Public Members

uint8_t *private_password

size_t private_password_len

uint8_t *private_user

size_t private_user_len

uint8_t *private_peer

size_t private_peer_len

psa_key_attributes_t private_attributes

psa_pake_cipher_suite_t private_cipher_suite

struct psa_jpake_computation_stage_s

#include <crypto_extra.h>

Public Members

psa_jpake_round_t private_round

psa_jpake_io_mode_t private_io_mode

uint8_t private_inputs

uint8_t private_outputs

psa_pake_step_t private_step

struct psa_pake_operation_s

#include <crypto_extra.h>

Public Members

unsigned int private_id: Unique ID indicating which driver got assigned to do the operation. Since driver contexts are driver-specific, swapping drivers halfway through the operation is not supported. ID values are auto-generated in psa_crypto_driver_wrappers.h ID value zero means the context is not valid or not assigned to any driver (i.e. none of the driver contexts are active).

psa_algorithm_t private_alg

psa_pake_primitive_t private_primitive

uint8_t private_stage

uint8_t private_dummy

psa_jpake_computation_stage_t private_jpake

union psa_pake_operation_s::[anonymous] private_computation_stage

psa_driver_pake_context_t private_ctx

psa_crypto_driver_pake_inputs_t private_inputs

union psa_pake_operation_s::[anonymous] private_data