Improve/fix documentation

Signed-off-by: Ronald Cron <ronald.cron@arm.com>

include/psa/crypto.h

@@ -36,16 +36,6 @@
  * @{
  */
 
-/** \brief Key handle.
- *
- * 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 handle. How other handle values are assigned is
- * implementation-dependent.
- */
-typedef _unsigned_integral_type_ psa_key_handle_t;
-
 /**@}*/
 #endif /* __DOXYGEN_ONLY__ */
 

include/psa/crypto_compat.h

@@ -35,7 +35,7 @@ extern "C" {
 #endif
 
 /*
- * To support temporary both openless APIs and psa_open_key(), define
+ * To support both openless APIs and psa_open_key() temporarily, define
  * psa_key_handle_t to be equal to mbedtls_svc_key_id_t. Do not mark the
  * type and its utility macros and functions deprecated yet. This will be done
  * in a subsequent phase.

library/psa_crypto_core.h

@@ -38,14 +38,14 @@ typedef struct
     psa_core_key_attributes_t attr;
 
     /*
-     * Number of locks, read and/or write, to the key slot by the library.
+     * Number of locks on the key slot held by the library.
      *
      * This counter is incremented by one each time a library function
      * retrieves through one of the dedicated internal API a pointer to the
      * key slot.
      *
      * This counter is decremented by one each time a library function stops
-     * accessing to the key slot and states it by calling the
+     * accessing the key slot and states it by calling the
      * psa_unlock_key_slot() API.
      *
      * This counter is used to prevent resetting the key slot while the library
@@ -102,7 +102,7 @@ static inline int psa_is_key_slot_occupied( const psa_key_slot_t *slot )
 
 /** Test whether a key slot is locked.
  *
- * A key slot is locked iff its lock counter is strickly greater than 0.
+ * A key slot is locked iff its lock counter is strictly greater than 0.
  *
  * \param[in] slot  The key slot to test.
  *

library/psa_crypto_slot_management.c

@@ -110,6 +110,15 @@ static psa_status_t psa_get_and_lock_key_slot_in_memory(
     if( psa_key_id_is_volatile( key_id ) )
     {
         slot = &global_data.key_slots[ key_id - PSA_KEY_ID_VOLATILE_MIN ];
+
+        /*
+         * Check if both the PSA key identifier key_id and the owner
+         * identifier of key match those of the key slot.
+         *
+         * Note that, if the key slot is not occupied, its PSA key identifier
+         * is equal to zero. This is an invalid value for a PSA key identifier
+         * and thus cannot be equal to the valid PSA key identifier key_id.
+         */
         status = mbedtls_svc_key_id_equal( key, slot->attr.id ) ?
                  PSA_SUCCESS : PSA_ERROR_DOES_NOT_EXIST;
     }
@@ -192,9 +201,9 @@ psa_status_t psa_get_empty_key_slot( psa_key_id_t *volatile_key_id,
 
     /*
      * If there is no unused key slot and there is at least one unlocked key
-     * slot containing the description of a permament key, recycle the first
-     * such key slot we encountered. If we need later on to operate on the
-     * persistent key we evict now, we will reload its description from
+     * slot containing the description of a persistent key, recycle the first
+     * such key slot we encountered. If we later need to operate on the
+     * persistent key we are evicting now, we will reload its description from
      * storage.
      */
     if( ( selected_slot == NULL ) &&

library/psa_crypto_slot_management.h

@@ -79,9 +79,9 @@ static inline int psa_key_id_is_volatile( psa_key_id_t key_id )
  *                      identified by \p key.
  *
  * \retval #PSA_SUCCESS
- *         The pointer to the key slot containing the description of the key
- *         identified by \p key was returned. The key slot counter was
- *         implemented.
+ *         \p *p_slot contains a pointer to the key slot containing the
+ *         description of the key identified by \p key.
+ *         The key slot counter has been incremented.
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been initialized.
  * \retval #PSA_ERROR_INVALID_HANDLE

tests/suites/test_suite_psa_crypto_slot_management.function

@@ -908,7 +908,7 @@ void key_slot_eviction_to_import_new_key( int lifetime_arg )
 
     /*
      * Create a new persistent or volatile key. When creating the key,
-     * one of the description of the previously created persistent key
+     * one of the descriptions of the previously created persistent keys
      * is removed from the RAM key slots. This makes room to store its
      * description in RAM.
      */