psa: Implement persistent keys
Allow use of persistent keys, including configuring them, importing and
exporting them, and destroying them.
When getting a slot using psa_get_key_slot, there are 3 scenarios that
can occur if the keys lifetime is persistent:
1. Key type is PSA_KEY_TYPE_NONE, no persistent storage entry:
- The key slot is treated as a standard empty key slot
2. Key type is PSA_KEY_TYPE_NONE, persistent storage entry exists:
- Attempt to load the key from persistent storage
3. Key type is not PSA_KEY_TYPE_NONE:
- As checking persistent storage on every use of the key could
be expensive, the persistent key is assumed to be saved in
persistent storage, the in-memory key is continued to be used.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index d1a3f0f..1ca6492 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1441,6 +1441,7 @@
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
@@ -1922,6 +1923,16 @@
* whether the lifetime of an occupied key slot can be changed, is
* implementation-dependent.
*
+ * When creating a persistent key, you must call this function before creating
+ * the key material with psa_import_key(), psa_generate_key() or
+ * psa_generator_import_key(). To open an existing persistent key, you must
+ * call this function with the correct lifetime value before using the slot
+ * for a cryptographic operation. Once a slot's lifetime has been set,
+ * the lifetime remains associated with the slot until a subsequent call to
+ * psa_set_key_lifetime(), until the key is wiped with psa_destroy_key or
+ * until the application terminates (or disconnects from the cryptography
+ * service, if the implementation offers such a possibility).
+ *
* \param key Slot whose lifetime is to be changed.
* \param lifetime The lifetime value to set for the given key slot.
*