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.
  *