NCBI C++ ToolKit
Macros | Functions
psa_crypto_slot_management.h File Reference
#include "psa/crypto.h"
#include "psa_crypto_core.h"
#include "psa_crypto_se.h"
+ Include dependency graph for psa_crypto_slot_management.h:

Go to the source code of this file.

Go to the SVN repository for this file.

Macros

#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

static int psa_key_id_is_volatile (psa_key_id_t key_id)
 Test whether a key identifier is a volatile key identifier. More...
 
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_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. More...
 
static psa_status_t psa_key_slot_state_transition (psa_key_slot_t *slot, psa_key_slot_state_t expected_state, psa_key_slot_state_t new_state)
 Change the state of a key slot. More...
 
static psa_status_t psa_register_read (psa_key_slot_t *slot)
 Register as a reader of a key slot. More...
 
psa_status_t psa_unregister_read (psa_key_slot_t *slot)
 Unregister from reading a key slot. More...
 
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. More...
 
static int psa_key_lifetime_is_external (psa_key_lifetime_t lifetime)
 Test whether a lifetime designates a key in an external cryptoprocessor. 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...
 
int psa_is_valid_key_id (mbedtls_svc_key_id_t key, int vendor_ok)
 Validate a key identifier. More...
 

Macro Definition Documentation

◆ 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 31 of file psa_crypto_slot_management.h.

◆ PSA_KEY_ID_VOLATILE_MIN

#define PSA_KEY_ID_VOLATILE_MIN
Value:
MBEDTLS_PSA_KEY_SLOT_COUNT + 1)
#define PSA_KEY_ID_VENDOR_MAX
The maximum value for a key identifier chosen by the implementation.

Range of volatile key identifiers.

The last MBEDTLS_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 26 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 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.

Parameters
keyKey identifier to query.
[out]p_slotOn 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_STATEThe library has not been initialized.
PSA_ERROR_INVALID_HANDLEkey is not a valid key identifier.
PSA_ERROR_INSUFFICIENT_MEMORYkey 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_EXISTThere 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_SUCCESSCurrently 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]keyThe key identifier.
[in]vendor_okNon-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_key_id_is_volatile()

static int psa_key_id_is_volatile ( psa_key_id_t  key_id)
inlinestatic

Test whether a key identifier is a volatile key identifier.

Parameters
key_idKey identifier to test.
Return values
1The key identifier is a volatile key identifier.
0The key identifier is not a volatile key identifier.

Definition at line 42 of file psa_crypto_slot_management.h.

References PSA_KEY_ID_VOLATILE_MAX, and PSA_KEY_ID_VOLATILE_MIN.

◆ psa_key_lifetime_is_external()

static int psa_key_lifetime_is_external ( psa_key_lifetime_t  lifetime)
inlinestatic

Test whether a lifetime designates a key in an external cryptoprocessor.

Parameters
lifetimeThe lifetime to test.
Return values
1The lifetime designates an external key. There should be a registered driver for this lifetime, otherwise the key cannot be created or manipulated.
0The lifetime designates a key that is volatile or in internal storage.

Definition at line 241 of file psa_crypto_slot_management.h.

References PSA_KEY_LIFETIME_GET_LOCATION, and PSA_KEY_LOCATION_LOCAL_STORAGE.

◆ psa_key_slot_state_transition()

static psa_status_t psa_key_slot_state_transition ( psa_key_slot_t slot,
psa_key_slot_state_t  expected_state,
psa_key_slot_state_t  new_state 
)
inlinestatic

Change the state of a key slot.

This function changes the state of the key slot from expected_state to new state. If the state of the slot was not expected_state, the state is unchanged.

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

Parameters
[in]slotThe key slot.
[in]expected_stateThe current state of the slot.
[in]new_stateThe new state of the slot.
Return values
PSA_SUCCESSThe key slot's state variable is new_state.
PSA_ERROR_CORRUPTION_DETECTEDThe slot's state was not expected_state.

Definition at line 146 of file psa_crypto_slot_management.h.

References PSA_ERROR_CORRUPTION_DETECTED, PSA_SUCCESS, and psa_key_slot_t::state.

◆ psa_register_read()

static psa_status_t psa_register_read ( psa_key_slot_t slot)
inlinestatic

Register as a reader of a key slot.

This function increments the key slot registered reader counter by one. If multi-threading is enabled, the caller must hold the global key slot mutex.

Parameters
[in]slotThe key slot.
Return values
PSA_SUCCESSThe key slot registered reader counter was incremented.
PSA_ERROR_CORRUPTION_DETECTEDThe reader counter already reached its maximum value and was not increased, or the slot's state was not PSA_SLOT_FULL.

Definition at line 171 of file psa_crypto_slot_management.h.

References PSA_ERROR_CORRUPTION_DETECTED, PSA_SLOT_FULL, PSA_SUCCESS, psa_key_slot_t::registered_readers, SIZE_MAX, and psa_key_slot_t::state.

◆ 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_idOn success, volatile key identifier associated to the returned slot.
[out]p_slotOn success, a pointer to the slot.
Return values
PSA_SUCCESS\emptydescription
PSA_ERROR_INSUFFICIENT_MEMORYThere were no free key slots.
PSA_ERROR_BAD_STATE\emptydescription
PSA_ERROR_CORRUPTION_DETECTEDThis 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]slotThe key slot.
Return values
PSA_SUCCESSslot is NULL or the key slot reader counter has been decremented (and potentially wiped) successfully.
PSA_ERROR_CORRUPTION_DETECTEDThe 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]slotThe key slot.
Return values
PSA_SUCCESSslot is NULL or the key slot reader counter has been decremented (and potentially wiped) successfully.
PSA_ERROR_CORRUPTION_DETECTEDThe 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]lifetimeThe key lifetime attribute.
[out]p_drvOn 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]lifetimeThe key lifetime attribute.
Return values
PSA_SUCCESS\emptydescription
PSA_ERROR_NOT_SUPPORTEDThe 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.

Modified on Tue Jul 23 17:50:39 2024 by modify_doxy.py rev. 669887