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.

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
+ * 0 is not a valid key handle. How other handle values are assigned is
- * implementation dependent.
+ * implementation-dependent.
  */
 typedef _unsigned_integral_type_ psa_key_handle_t;
 
@@ -129,17 +129,17 @@ typedef int32_t psa_status_t;
 /** 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
+ * If a handle is invalid, it does not designate an occupied slot.
- * not be performed even after erasing the slot's content),
+ * The error for an invalid handle is #PSA_ERROR_INVALID_HANDLE.
- * implementations shall return #PSA_ERROR_INVALID_ARGUMENT instead. */
+ */
 #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
+ * If a handle is invalid, it does not designate an empty slot.
- * not be performed even after creating appropriate content in the slot),
+ * The error for an invalid handle is #PSA_ERROR_INVALID_HANDLE.
- * implementations shall return #PSA_ERROR_INVALID_ARGUMENT instead. */
+ */
 #define PSA_ERROR_EMPTY_SLOT            ((psa_status_t)6)
 
 /** The requested action cannot be performed in the current state.
@@ -162,7 +162,12 @@ typedef int32_t psa_status_t;
  * 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_lifetime_t;
  */
 typedef uint32_t psa_key_id_t;
 
-/** A volatile key slot retains its content as long as the application is
+/** A volatile key only exists as long as the handle to it is not closed.
- * running. It is guaranteed to be erased on a power reset.
+ * 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
+/** The default storage area for persistent keys.
- * destroyed.
+ *
+ * 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 @@ psa_status_t psa_close_key(psa_key_handle_t handle);
  *
  * \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 @@ psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy);
  * \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 @@ psa_status_t psa_generator_read(psa_crypto_generator_t *generator,
  *
  * \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 @@ typedef struct {
  *                          \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.

library/psa_crypto_slot_management.c

@@ -100,7 +100,8 @@ void psa_wipe_all_key_slots( void )
 
 /** Find a free key slot and mark it as in use.
  *
- * \param[out] handle   On success, a slot number that is not in use.
+ * \param[out] handle   On success, a slot number that is not in use. This
+ *                      value can be used as a handle to the slot.
  *
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -123,7 +124,7 @@ static psa_status_t psa_internal_allocate_key_slot( psa_key_handle_t *handle )
  *
  * This does not affect persistent storage.
  *
- * \param handle        The key slot number to release.
+ * \param handle        The handle to the key slot to release.
  *
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INVALID_ARGUMENT