Update some documentation related to key slots
Some of the documentation is obsolete in its reference to key slots
when it should discuss key handles. This may require a further pass,
possibly with some reorganization of error codes.
Update the documentation of functions that modify key slots (key
material creation and psa_set_key_policy()) to discuss how they affect
storage.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 4aea990..c58d22a 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -41,8 +41,8 @@
* This type represents open handles to keys. It must be an unsigned integral
* type. The choice of type is implementation-dependent.
*
- * 0 is not a valid key slot number. The meaning of other values is
- * implementation dependent.
+ * 0 is not a valid key handle. How other handle values are assigned is
+ * implementation-dependent.
*/
typedef _unsigned_integral_type_ psa_key_handle_t;
@@ -129,17 +129,17 @@
/** A slot is occupied, but must be empty to carry out the
* requested action.
*
- * If the slot number is invalid (i.e. the requested action could
- * not be performed even after erasing the slot's content),
- * implementations shall return #PSA_ERROR_INVALID_ARGUMENT instead. */
+ * If a handle is invalid, it does not designate an occupied slot.
+ * The error for an invalid handle is #PSA_ERROR_INVALID_HANDLE.
+ */
#define PSA_ERROR_OCCUPIED_SLOT ((psa_status_t)5)
/** A slot is empty, but must be occupied to carry out the
* requested action.
*
- * If the slot number is invalid (i.e. the requested action could
- * not be performed even after creating appropriate content in the slot),
- * implementations shall return #PSA_ERROR_INVALID_ARGUMENT instead. */
+ * If a handle is invalid, it does not designate an empty slot.
+ * The error for an invalid handle is #PSA_ERROR_INVALID_HANDLE.
+ */
#define PSA_ERROR_EMPTY_SLOT ((psa_status_t)6)
/** The requested action cannot be performed in the current state.
@@ -162,7 +162,12 @@
* Implementations shall not return this error code to indicate
* that a key slot is occupied when it needs to be free or vice versa,
* but shall return #PSA_ERROR_OCCUPIED_SLOT or #PSA_ERROR_EMPTY_SLOT
- * as applicable. */
+ * as applicable.
+ *
+ * Implementation shall not return this error code to indicate that a
+ * key handle is invalid, but shall return #PSA_ERROR_INVALID_HANDLE
+ * instead.
+ */
#define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)8)
/** There is not enough runtime memory.
@@ -1409,13 +1414,22 @@
*/
typedef uint32_t psa_key_id_t;
-/** A volatile key slot retains its content as long as the application is
- * running. It is guaranteed to be erased on a power reset.
+/** A volatile key only exists as long as the handle to it is not closed.
+ * The key material is guaranteed to be erased on a power reset.
*/
#define PSA_KEY_LIFETIME_VOLATILE ((psa_key_lifetime_t)0x00000000)
-/** A persistent key slot retains its content as long as it is not explicitly
- * destroyed.
+/** The default storage area for persistent keys.
+ *
+ * A persistent key remains in storage until it is explicitly destroyed or
+ * until the corresponding storage area is wiped. This specification does
+ * not define any mechanism to wipe a storage area, but implementations may
+ * provide their own mechanism (for example to perform a factory reset,
+ * to prepare for device refurbishment, or to uninstall an application).
+ *
+ * This lifetime value is the default storage area for the calling
+ * application. Implementations may offer other storage areas designated
+ * by other lifetime values as implementation-specific extensions.
*/
#define PSA_KEY_LIFETIME_PERSISTENT ((psa_key_lifetime_t)0x00000001)
@@ -1599,6 +1613,8 @@
*
* \retval #PSA_SUCCESS
* Success.
+ * If the key is persistent, the key material and the key's metadata
+ * have been saved to persistent storage.
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_SUPPORTED
* The key type or key size is not supported, either by the
@@ -2009,6 +2025,10 @@
* \param[in] policy The policy object to query.
*
* \retval #PSA_SUCCESS
+ * Success.
+ * If the key is persistent, it is implementation-defined whether
+ * the policy has been saved to persistent storage. Implementations
+ * may defer saving the policy until the key material is created.
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_OCCUPIED_SLOT
* \retval #PSA_ERROR_NOT_SUPPORTED
@@ -3292,6 +3312,8 @@
*
* \retval #PSA_SUCCESS
* Success.
+ * If the key is persistent, the key material and the key's metadata
+ * have been saved to persistent storage.
* \retval #PSA_ERROR_INSUFFICIENT_CAPACITY
* There were fewer than \p output_length bytes
* in the generator. Note that in this case, no
@@ -3542,6 +3564,9 @@
* \c NULL then \p extra_size must be zero.
*
* \retval #PSA_SUCCESS
+ * Success.
+ * If the key is persistent, the key material and the key's metadata
+ * have been saved to persistent storage.
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_OCCUPIED_SLOT
* There is already a key in the specified slot.