#include "psa/crypto.h"
#include "psa_crypto_core.h"
#include "psa_crypto_se.h"

Include dependency graph for psa_crypto_slot_management.h:

Macros
#define	PSA_KEY_ID_VOLATILE_MIN PSA_KEY_ID_VENDOR_MIN

#define	PSA_KEY_ID_VOLATILE_MAX (PSA_KEY_ID_VOLATILE_MIN + MBEDTLS_PSA_KEY_SLOT_COUNT - 1)

Functions
psa_status_t	psa_get_and_lock_key_slot (mbedtls_svc_key_id_t key, psa_key_slot_t **p_slot)

psa_status_t	psa_initialize_key_slots (void)

void	psa_wipe_all_key_slots (void)

psa_status_t	psa_reserve_free_key_slot (psa_key_id_t volatile_key_id, psa_key_slot_t *p_slot)

psa_status_t	psa_unregister_read (psa_key_slot_t *slot)

psa_status_t	psa_unregister_read_under_mutex (psa_key_slot_t *slot)

psa_status_t	psa_validate_key_location (psa_key_lifetime_t lifetime, psa_se_drv_table_entry_t **p_drv)

psa_status_t	psa_validate_key_persistence (psa_key_lifetime_t lifetime)

int	psa_is_valid_key_id (mbedtls_svc_key_id_t key, int vendor_ok)

Macro Definition Documentation

◆ PSA_KEY_ID_VOLATILE_MAX

#define PSA_KEY_ID_VOLATILE_MAX (PSA_KEY_ID_VOLATILE_MIN + MBEDTLS_PSA_KEY_SLOT_COUNT - 1)

The maximum value for a volatile key identifier.

◆ PSA_KEY_ID_VOLATILE_MIN

#define PSA_KEY_ID_VOLATILE_MIN PSA_KEY_ID_VENDOR_MIN

Range of volatile key identifiers.

The first MBEDTLS_PSA_KEY_SLOT_COUNT identifiers of the implementation range of key identifiers are reserved for volatile key identifiers.

If id is a a volatile key identifier, PSA_KEY_ID_VOLATILE_MIN - id indicates the key slot containing the volatile key definition. See psa_crypto_slot_management.c for details. The minimum value for a volatile key identifier.

Function Documentation

◆ psa_get_and_lock_key_slot()

psa_status_t psa_get_and_lock_key_slot	(	mbedtls_svc_key_id_t	key,
		psa_key_slot_t **	p_slot
	)

Get the description of a key given its identifier and lock it.

The descriptions of volatile keys and loaded persistent keys are stored in key slots. This function returns a pointer to the key slot containing the description of a key given its identifier.

In case of a persistent key, the function loads the description of the key into a key slot if not already done.

On success, the returned key slot has been registered for reading. It is the responsibility of the caller to call psa_unregister_read(slot) when they have finished reading the contents of the slot.

On failure, *p_slot is set to NULL. This ensures that it is always valid to call psa_unregister_read on the returned slot.

Parameters

	key	Key identifier to query.
[out]	p_slot	On success, `*p_slot` contains a pointer to the key slot containing the description of the key identified by `key`.

Return values

PSA_SUCCESS	`*p_slot` contains a pointer to the key slot containing the description of the key identified by `key`. The key slot counter has been incremented.
PSA_ERROR_BAD_STATE	The library has not been initialized.
PSA_ERROR_INVALID_HANDLE	`key` is not a valid key identifier.
PSA_ERROR_INSUFFICIENT_MEMORY	`key` is a persistent key identifier. The implementation does not have sufficient resources to load the persistent key. This can be due to a lack of empty key slot, or available memory.
PSA_ERROR_DOES_NOT_EXIST	There is no key with key identifier `key`.
PSA_ERROR_CORRUPTION_DETECTED	\emptydescription
PSA_ERROR_STORAGE_FAILURE	\emptydescription
PSA_ERROR_DATA_CORRUPT	\emptydescription

◆ psa_initialize_key_slots()

psa_status_t psa_initialize_key_slots ( void )

Initialize the key slot structures.

Return values

PSA_SUCCESS Currently this function always succeeds.

◆ psa_is_valid_key_id()

int psa_is_valid_key_id	(	mbedtls_svc_key_id_t	key,
		int	vendor_ok
	)

Validate a key identifier.

Parameters

[in]	key	The key identifier.
[in]	vendor_ok	Non-zero to indicate that key identifiers in the vendor range are allowed, volatile key identifiers excepted `0` otherwise.

Return values

<>	0 if the key identifier is valid, 0 otherwise.

◆ psa_reserve_free_key_slot()

psa_status_t psa_reserve_free_key_slot	(	psa_key_id_t *	volatile_key_id,
		psa_key_slot_t **	p_slot
	)

Find a free key slot and reserve it to be filled with a key.

This function finds a key slot that is free, sets its state to PSA_SLOT_FILLING and then returns the slot.

On success, the key slot's state is PSA_SLOT_FILLING. It is the responsibility of the caller to change the slot's state to PSA_SLOT_EMPTY/FULL once key creation has finished.

If multi-threading is enabled, the caller must hold the global key slot mutex.

Parameters

[out]	volatile_key_id	- If null, reserve a cache slot for a persistent or built-in key. If non-null, allocate a slot for a volatile key. On success, `*volatile_key_id` is the identifier corresponding to the returned slot. It is the caller's responsibility to set this key identifier in the attributes.
[out]	p_slot	On success, a pointer to the slot.

Return values

PSA_SUCCESS	\emptydescription
PSA_ERROR_INSUFFICIENT_MEMORY	There were no free key slots. When MBEDTLS_PSA_KEY_STORE_DYNAMIC is enabled, there was not enough memory to allocate more slots.
PSA_ERROR_BAD_STATE	\emptydescription
PSA_ERROR_CORRUPTION_DETECTED	This function attempted to operate on a key slot which was in an unexpected state.

◆ psa_unregister_read()

psa_status_t psa_unregister_read ( psa_key_slot_t * slot )

Unregister from reading a key slot.

This function decrements the key slot registered reader counter by one. If the state of the slot is PSA_SLOT_PENDING_DELETION, and there is only one registered reader (the caller), this function will call psa_wipe_key_slot(). If multi-threading is enabled, the caller must hold the global key slot mutex.

Note: To ease the handling of errors in retrieving a key slot a NULL input pointer is valid, and the function returns successfully without doing anything in that case.

Parameters

[in] slot The key slot.

Return values

PSA_SUCCESS	`slot` is NULL or the key slot reader counter has been decremented (and potentially wiped) successfully.
PSA_ERROR_CORRUPTION_DETECTED	The slot's state was neither PSA_SLOT_FULL nor PSA_SLOT_PENDING_DELETION. Or a wipe was attempted and the slot's state was not PSA_SLOT_PENDING_DELETION. Or registered_readers was equal to 0.

◆ psa_unregister_read_under_mutex()

psa_status_t psa_unregister_read_under_mutex ( psa_key_slot_t * slot )

Wrap a call to psa_unregister_read in the global key slot mutex.

If threading is disabled, this simply calls psa_unregister_read.

Note: To ease the handling of errors in retrieving a key slot a NULL input pointer is valid, and the function returns successfully without doing anything in that case.

Parameters

[in] slot The key slot.

Return values

PSA_SUCCESS	`slot` is NULL or the key slot reader counter has been decremented (and potentially wiped) successfully.
PSA_ERROR_CORRUPTION_DETECTED	The slot's state was neither PSA_SLOT_FULL nor PSA_SLOT_PENDING_DELETION. Or a wipe was attempted and the slot's state was not PSA_SLOT_PENDING_DELETION. Or registered_readers was equal to 0.

◆ psa_validate_key_location()

psa_status_t psa_validate_key_location	(	psa_key_lifetime_t	lifetime,
		psa_se_drv_table_entry_t **	p_drv
	)

Validate a key's location.

This function checks whether the key's attributes point to a location that is known to the PSA Core, and returns the driver function table if the key is to be found in an external location.

Parameters

[in]	lifetime	The key lifetime attribute.
[out]	p_drv	On success, when a key is located in external storage, returns a pointer to the driver table associated with the key's storage location.

Return values

PSA_SUCCESS	\emptydescription
PSA_ERROR_INVALID_ARGUMENT	\emptydescription

◆ psa_validate_key_persistence()

psa_status_t psa_validate_key_persistence ( psa_key_lifetime_t lifetime )

Validate the persistence of a key.

Parameters

[in] lifetime The key lifetime attribute.

Return values

PSA_SUCCESS	\emptydescription
PSA_ERROR_NOT_SUPPORTED	The key is persistent but persistent keys are not supported.

◆ psa_wipe_all_key_slots()

void psa_wipe_all_key_slots ( void )

Delete all data from key slots in memory. This function is not thread safe, it wipes every key slot regardless of state and reader count. It should only be called when no slot is in use.

This does not affect persistent storage.

Macros

Functions

Macro Definition Documentation

◆ PSA_KEY_ID_VOLATILE_MAX

◆ PSA_KEY_ID_VOLATILE_MIN

Function Documentation

◆ psa_get_and_lock_key_slot()

◆ psa_initialize_key_slots()

◆ psa_is_valid_key_id()

◆ psa_reserve_free_key_slot()

◆ psa_unregister_read()

◆ psa_unregister_read_under_mutex()

◆ psa_validate_key_location()

◆ psa_validate_key_persistence()

◆ psa_wipe_all_key_slots()