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

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.

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:

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

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

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 volatile_slots

Number of slots containing key material for a volatile key.

size_t persistent_slots

Number of slots containing key material for a key which is in internal persistent storage.

size_t external_slots

Number of slots containing a reference to a key in a secure element.

size_t half_filled_slots

Number of slots which are occupied, but do not contain key material yet.

size_t cache_slots

Number of slots that contain cache data.

size_t empty_slots

Number of slots that are not used for anything.

size_t locked_slots

Number of slots that are locked.

psa_key_id_t max_open_internal_key_id

Largest key id value among open keys in internal persistent storage.

psa_key_id_t max_open_external_key_id

Largest key id value among open keys in secure elements.