Merge pull request #269 from ARMmbed/psa-slots_to_handles

Update API documentation to refer to handles and key ids, not slots

include/psa/crypto.h

@@ -332,6 +332,7 @@ static psa_key_usage_t psa_get_key_usage_flags(
 static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
                                   psa_algorithm_t alg);
 
+
 /** Retrieve the algorithm policy from key attributes.
  *
  * This function may be declared as `static` (i.e. without external
@@ -360,6 +361,7 @@ static psa_algorithm_t psa_get_key_algorithm(
 static void psa_set_key_type(psa_key_attributes_t *attributes,
                              psa_key_type_t type);
 
+
 /** Declare the size of a key.
  *
  * This function overwrites any key size previously set in \p attributes.
@@ -443,20 +445,21 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes);
 
 /** Open a handle to an existing persistent key.
  *
- * Open a handle to a key which was previously created with psa_create_key().
+ * Open a handle to a key which was previously created with
+ * psa_make_key_persistent() when setting its attributes.
+ * The handle should eventually be closed with psa_close_key()
+ * to release associated resources.
  *
  * Implementations may provide additional keys that can be opened with
  * psa_open_key(). Such keys have a key identifier in the vendor range,
  * as documented in the description of #psa_key_id_t.
  *
  * \param id            The persistent identifier of the key.
- * \param[out] handle   On success, a handle to a key slot which contains
+ * \param[out] handle   On success, a handle to the key.
- *                      the data and metadata loaded from the specified
- *                      persistent location.
  *
  * \retval #PSA_SUCCESS
  *         Success. The application can now use the value of `*handle`
- *         to access the newly allocated key slot.
+ *         to access the key.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_INVALID_ARGUMENT
@@ -472,13 +475,14 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes);
 psa_status_t psa_open_key(psa_key_id_t id,
                           psa_key_handle_t *handle);
 
+
 /** Close a key handle.
  *
  * If the handle designates a volatile key, destroy the key material and
  * free all associated resources, just like psa_destroy_key().
  *
  * If the handle designates a persistent key, free all resources associated
- * with the key in volatile memory. The key slot in persistent storage is
+ * with the key in volatile memory. The key in persistent storage is
  * not affected and can be opened again later with psa_open_key().
  *
  * If the key is currently in use in a multipart operation,
@@ -513,6 +517,7 @@ psa_status_t psa_close_key(psa_key_handle_t handle);
  * minimize the risk that an invalid input is accidentally interpreted
  * according to a different format.
  *
+
  * \param[in] attributes    The attributes for the new key.
  *                          The key size is always determined from the
  *                          \p data buffer.
@@ -568,23 +573,19 @@ psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
 /**
  * \brief Destroy a key.
  *
- * This function destroys the content of the key slot from both volatile
+ * This function destroys a key from both volatile
  * memory and, if applicable, non-volatile storage. Implementations shall
- * make a best effort to ensure that any previous content of the slot is
+ * make a best effort to ensure that that the key material cannot be recovered.
- * unrecoverable.
  *
  * This function also erases any metadata such as policies and frees all
  * resources associated with the key.
  *
- * If the key is currently in use in a multipart operation,
+ * \param handle        Handle to the key to erase.
- * the multipart operation is aborted.
- *
- * \param handle        Handle to the key slot to erase.
  *
  * \retval #PSA_SUCCESS
- *         The slot's content, if any, has been erased.
+ *         The key material has been erased.
  * \retval #PSA_ERROR_NOT_PERMITTED
- *         The slot holds content and cannot be erased because it is
+ *         The key cannot be erased because it is
  *         read-only, either due to a policy or due to physical restrictions.
  * \retval #PSA_ERROR_INVALID_HANDLE
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
@@ -770,8 +771,7 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
  * to another, since it populates a key using the material from
  * another key which may have a different lifetime.
  *
- * In an implementation where slots have different ownerships,
+ * This function may be used to share a key with a different party,
- * this function may be used to share a key with a different party,
  * subject to implementation-defined restrictions on key sharing.
  *
  * The policy on the source key must have the usage flag
@@ -800,8 +800,7 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
  * The effect of this function on implementation-defined attributes is
  * implementation-defined.
  *
- * \param source_handle     The key to copy. It must be a handle to an
+ * \param source_handle     The key to copy. It must be a valid key handle.
- *                          occupied slot.
  * \param[in] attributes    The attributes for the new key.
  *                          They are used as follows:
  *                          - The key type and size may be 0. If either is
@@ -3291,7 +3290,7 @@ psa_status_t psa_key_derivation_output_bytes(
  *         this function will not succeed, even with a smaller output buffer.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         The key type or key size is not supported, either by the
- *         implementation in general or in this particular slot.
+ *         implementation in general or in this particular location.
  * \retval #PSA_ERROR_BAD_STATE
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE

include/psa/crypto_extra.h

@@ -232,7 +232,7 @@ static psa_key_policy_t psa_key_policy_init(void);
  *
  * Note that this function does not make any consistency check of the
  * parameters. The values are only checked when applying the policy to
- * a key slot with psa_set_key_policy().
+ * a key with psa_set_key_policy().
  *
  * \param[in,out] policy The key policy to modify. It must have been
  *                       initialized as per the documentation for
@@ -260,14 +260,14 @@ psa_key_usage_t psa_key_policy_get_usage(const psa_key_policy_t *policy);
  */
 psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy);
 
-/** \brief Set the usage policy on a key slot.
+/** \brief Set the usage policy for a key.
  *
- * This function must be called on an empty key slot, before importing,
+ * This function must be called on a key handle before importing,
- * generating or creating a key in the slot. Changing the policy of an
+ * generating or creating a key. Changing the policy of an
  * existing key is not permitted.
  *
  * Implementations may set restrictions on supported key policies
- * depending on the key type and the key slot.
+ * depending on the key type.
  *
  * \param handle        Handle to the key whose policy is to be changed.
  * \param[in] policy    The policy object to query.
@@ -292,9 +292,9 @@ psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy);
 psa_status_t psa_set_key_policy(psa_key_handle_t handle,
                                 const psa_key_policy_t *policy);
 
-/** \brief Get the usage policy for a key slot.
+/** \brief Get the usage policy for a key.
  *
- * \param handle        Handle to the key slot whose policy is being queried.
+ * \param handle        Handle to the key whose policy is being queried.
  * \param[out] policy   On success, the key's policy.
  *
  * \retval #PSA_SUCCESS
@@ -321,9 +321,9 @@ psa_status_t psa_get_key_policy(psa_key_handle_t handle,
  * a structure that represents the properties.
  */
 
-/** Create a new persistent key slot.
+/** Create a new persistent key.
  *
- * Create a new persistent key slot and return a handle to it. The handle
+ * Create a new persistent key and return a handle to it. The handle
  * remains valid until the application calls psa_close_key() or terminates.
  * The application can open the key again with psa_open_key() until it
  * removes the key by calling psa_destroy_key().
@@ -332,13 +332,13 @@ psa_status_t psa_get_key_policy(psa_key_handle_t handle,
  *                      area where the key material is stored. This must not
  *                      be #PSA_KEY_LIFETIME_VOLATILE.
  * \param id            The persistent identifier of the key.
- * \param[out] handle   On success, a handle to the newly created key slot.
+ * \param[out] handle   On success, a handle to the newly created key.
- *                      When key material is later created in this key slot,
+ *                      When key material is later created in this key,
  *                      it will be saved to the specified persistent location.
  *
  * \retval #PSA_SUCCESS
  *         Success. The application can now use the value of `*handle`
- *         to access the newly allocated key slot.
+ *         for key operations.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
  * \retval #PSA_ERROR_ALREADY_EXISTS
@@ -358,20 +358,20 @@ psa_status_t psa_create_key(psa_key_lifetime_t lifetime,
                             psa_key_id_t id,
                             psa_key_handle_t *handle);
 
-/** Allocate a key slot for a transient key, i.e. a key which is only stored
+/** Allocate space for a transient key, i.e. a key which is only stored
  * in volatile memory.
  *
- * The allocated key slot and its handle remain valid until the
+ * The allocated key and its handle remain valid until the
  * application calls psa_close_key() or psa_destroy_key() or until the
  * application terminates.
  *
- * \param[out] handle   On success, a handle to a volatile key slot.
+ * \param[out] handle   On success, a handle to a volatile key.
  *
  * \retval #PSA_SUCCESS
  *         Success. The application can now use the value of `*handle`
- *         to access the newly allocated key slot.
+ *         to refer to the key.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
- *         There was not enough memory, or the maximum number of key slots
+ *         There was not enough memory, or the maximum number of transient keys
  *         has been reached.
  */
 psa_status_t psa_allocate_key(psa_key_handle_t *handle);
@@ -379,7 +379,7 @@ psa_status_t psa_allocate_key(psa_key_handle_t *handle);
 /**
  * \brief Get basic metadata about a key.
  *
- * \param handle        Handle to the key slot to query.
+ * \param handle        Handle to the key to query.
  * \param[out] type     On success, the key type (a \c PSA_KEY_TYPE_XXX value).
  *                      This may be a null pointer, in which case the key type
  *                      is not written.
@@ -390,7 +390,7 @@ psa_status_t psa_allocate_key(psa_key_handle_t *handle);
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INVALID_HANDLE
  * \retval #PSA_ERROR_DOES_NOT_EXIST
- *         The handle is to a key slot which does not contain key material yet.
+ *         The handle does not contain a key.
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED

include/psa/crypto_values.h

@@ -105,9 +105,13 @@
  * descriptions for permitted sequencing of functions.
  *
  * Implementations shall not return this error code to indicate
- * that a key slot is occupied when it needs to be free or vice versa,
+ * that a key either exists or not,
- * but shall return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST
+ * but shall instead return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST
- * as applicable. */
+ * as applicable.
+ *
+ * Implementations 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_BAD_STATE             ((psa_status_t)-137)
 
 /** The parameters passed to the function are invalid.
@@ -115,12 +119,7 @@
  * Implementations may return this error any time a parameter or
  * combination of parameters are recognized as invalid.
  *
- * Implementations shall not return this error code to indicate
+ * Implementations shall not return this error code to indicate that a
- * that a key slot is occupied when it needs to be free or vice versa,
- * but shall return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST
- * 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.
  */