psa_crypto_slot_management.h File Reference

PSA crypto layer on top of Mbed TLS crypto. More...

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

Go to the source code of this file.

Macros
#define	PSA_KEY_SLOT_COUNT   32
	Number of key slots (plus one because 0 is not used). More...
#define	PSA_KEY_ID_VOLATILE_MIN
	Range of volatile key identifiers. More...
#define	PSA_KEY_ID_VOLATILE_MAX   PSA_KEY_ID_VENDOR_MAX
	The maximum value for a volatile key identifier. More...

Functions
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. More...
psa_status_t	psa_initialize_key_slots (void)
	Initialize the key slot structures. More...
void	psa_wipe_all_key_slots (void)
	Delete all data from key slots in memory. More...
psa_status_t	psa_get_empty_key_slot (psa_key_id_t *volatile_key_id, psa_key_slot_t **p_slot)
	Find a free key slot. More...
psa_status_t	psa_unlock_key_slot (psa_key_slot_t *slot)
	Unlock a key slot. More...
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. More...
psa_status_t	psa_validate_key_persistence (psa_key_lifetime_t lifetime)
	Validate the persistence of a key. More...
psa_status_t	psa_validate_key_id (mbedtls_svc_key_id_t key, int vendor_ok)
	Validate a key identifier. More...

Detailed Description

PSA crypto layer on top of Mbed TLS crypto.

Definition in file psa_crypto_slot_management.h.

Macro Definition Documentation

PSA_KEY_SLOT_COUNT

#define PSA_KEY_SLOT_COUNT   32

Number of key slots (plus one because 0 is not used).

The value is a compile-time constant for now, for simplicity.

Definition at line 32 of file psa_crypto_slot_management.h.

PSA_KEY_ID_VOLATILE_MIN

#define PSA_KEY_ID_VOLATILE_MIN

Value:

                                   ( PSA_KEY_ID_VENDOR_MAX - \
                                   PSA_KEY_SLOT_COUNT + 1 )

Range of volatile key identifiers.

The last PSA_KEY_SLOT_COUNT identifiers of the implementation range of key identifiers are reserved for volatile key identifiers. A volatile key identifier is equal to PSA_KEY_ID_VOLATILE_MIN plus the index of the key slot containing the volatile key definition. The minimum value for a volatile key identifier.

Definition at line 44 of file psa_crypto_slot_management.h.

PSA_KEY_ID_VOLATILE_MAX

#define PSA_KEY_ID_VOLATILE_MAX   PSA_KEY_ID_VENDOR_MAX

The maximum value for a volatile key identifier.

Definition at line 49 of file psa_crypto_slot_management.h.

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 is locked. It is the responsibility of the caller to unlock the key slot when it does not access it anymore.

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
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT

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

void psa_wipe_all_key_slots

(

void

)

Delete all data from key slots in memory.

This does not affect persistent storage.

psa_get_empty_key_slot()

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

Find a free key slot.

This function returns a key slot that is available for use and is in its ground state (all-bits-zero). On success, the key slot is locked. It is the responsibility of the caller to unlock the key slot when it does not access it anymore.

Parameters

[out]	volatile_key_id	On success, volatile key identifier associated to the returned slot.
[out]	p_slot	On success, a pointer to the slot.

Return values

PSA_SUCCESS
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_BAD_STATE

psa_unlock_key_slot()

psa_status_t psa_unlock_key_slot

(

psa_key_slot_t *

slot

)

Unlock a key slot.

This function decrements the key slot lock counter by one.

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 lock counter has been decremented successfully.
PSA_ERROR_CORRUPTION_DETECTED	The lock counter 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
PSA_ERROR_INVALID_ARGUMENT

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
PSA_ERROR_INVALID_ARGUMENT	The key is persistent but persistent keys are not supported.

psa_validate_key_id()

psa_status_t psa_validate_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

PSA_SUCCESS	The identifier is valid.
PSA_ERROR_INVALID_ARGUMENT	The key identifier is not valid.