psa_register_read() function

The key slot.

Wrap a call to psa_unregister_read in the global key slot mutex. If threading is disabled, this simply calls psa_unregister_read.

Get the description of a key given its identifier and policy constraints and lock it. The key must have allow all the usage flags set in \p usage. If \p alg is nonzero, the key must allow operations with this algorithm. If \p alg is zero, the algorithm is not checked. 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 then unregister once they have finished reading the contents of the slot. The caller unregisters by calling psa_unregister_read() or psa_unregister_read_under_mutex(). psa_unregister_read() must be called if and only if the caller already holds the global key slot mutex (when mutexes are enabled). psa_unregister_read_under_mutex() encapsulates the unregister with mutex lock and unlock operations.

Completely wipe a slot in memory, including its policy. Persistent storage is not affected. Sets the slot's state to PSA_SLOT_EMPTY. If multi-threading is enabled, the caller must hold the global key slot mutex.

Try to allocate a buffer to an empty key slot.

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.

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.

Prepare a key slot to receive key material. This function allocates a key slot and sets its metadata. If this function fails, call psa_fail_key_creation(). This function is intended to be used as follows: -# Call psa_start_key_creation() to allocate a key slot, prepare it with the specified attributes, and in case of a volatile key assign it a volatile key identifier. -# Populate the slot with the key material. -# Call psa_finish_key_creation() to finalize the creation of the slot. In case of failure at any step, stop the sequence and call psa_fail_key_creation(). 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.

Finalize the creation of a key once its key material has been set. This entails writing the key to persistent storage. If this function fails, call psa_fail_key_creation(). See the documentation of psa_start_key_creation() for the intended use of this function. If the finalization succeeds, the function sets the key slot's state to PSA_SLOT_FULL, and the key slot can no longer be accessed as part of the key creation process.

Abort the creation of a key. You may call this function after calling psa_start_key_creation(), or after psa_finish_key_creation() fails. In other circumstances, this function may not clean up persistent storage. See the documentation of psa_start_key_creation() for the intended use of this function. Sets the slot's state to PSA_SLOT_EMPTY.

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.

Test whether a key slot has any registered readers. If multi-threading is enabled, the caller must hold the global key slot mutex.

Get a key slot containing a transparent key and lock it. A transparent key is a key for which the key material is directly available, as opposed to a key in a secure element and/or to be used by a secure element. This is a temporary function that may be used instead of psa_get_and_lock_key_slot_with_policy() when there is no opaque key support for a cryptographic operation. On success, the returned key slot has been registered for reading. It is the responsibility of the caller to then unregister once they have finished reading the contents of the slot. The caller unregisters by calling psa_unregister_read() or psa_unregister_read_under_mutex(). psa_unregister_read() must be called if and only if the caller already holds the global key slot mutex (when mutexes are enabled). psa_unregister_read_under_mutex() encapsulates psa_unregister_read() with mutex lock and unlock operations.

Wipe key data from a slot. Preserves metadata such as the policy.

Copy key data (in export format) into an empty key slot. This function assumes that the slot does not contain any key material yet. On failure, the slot content is unchanged.

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.

Get the description in memory 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. The function searches the key slots containing the description of the key with \p key identifier. The function does only read accesses to the key slots. The function does not load any persistent key thus does not access any storage. For volatile key identifiers, only one key slot is queried as a volatile key with identifier key_id can only be stored in slot of index ( key_id - #PSA_KEY_ID_VOLATILE_MIN ). On success, the function locks the key slot. It is the responsibility of the caller to unlock the key slot when it does not access it anymore. If multi-threading is enabled, the caller must hold the global key slot mutex.

Validate optional attributes during key creation. Some key attributes are optional during key creation. If they are specified in the attributes structure, check that they are consistent with the data in the slot. This function should be called near the end of key creation, after the slot in memory is fully populated but before saving persistent data.

Internal function for raw key agreement Calls the driver wrapper which will hand off key agreement task to the driver's implementation if a driver is present. Fallback specified in the driver wrapper is built-in raw key agreement (psa_key_agreement_raw_builtin).

Return a key slot to the free list. Call this function when a slot obtained from psa_reserve_free_key_slot() is no longer in use. If multi-threading is enabled, the caller must hold the global key slot mutex.