From 67e1c7ac800dd08192393107afbd7bf05581b316 Mon Sep 17 00:00:00 2001 From: "Adrian L. Shaw" Date: Tue, 14 May 2019 15:24:21 +0100 Subject: [PATCH 1/4] Remove remaining mentions of slots --- include/psa/crypto.h | 36 +++++++++++++++++------------------ include/psa/crypto_extra.h | 38 ++++++++++++++++++------------------- include/psa/crypto_values.h | 6 +++--- 3 files changed, 39 insertions(+), 41 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 84026c91c..5f80b131b 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -334,6 +334,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 @@ -365,6 +366,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. @@ -537,22 +539,20 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes); * @{ */ -/** Open a handle to an existing persistent key. +/** Get a handle to an existing persistent key. * - * Open a handle to a key which was previously created with psa_create_key(). + * Get a handle to a key which was previously created with psa_create_key(). * * 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 - * the data and metadata loaded from the specified - * persistent location. + * \param[out] handle On success, a handle to the key. * * \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 @@ -568,13 +568,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, @@ -609,6 +610,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. @@ -665,23 +667,20 @@ 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 any previous content of the handle is * 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, - * the multipart operation is aborted. - * - * \param handle Handle to the key slot to erase. + * \param handle Handle to the key to erase. * * \retval #PSA_SUCCESS - * The slot's content, if any, has been erased. + * The handle's content, if any, has been erased. * \retval #PSA_ERROR_NOT_PERMITTED - * The slot holds content and cannot be erased because it is + * The handle holds content and 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 @@ -873,7 +872,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, + * In an implementation where handles have different ownerships, * this function may be used to share a key with a different party, * subject to implementation-defined restrictions on key sharing. * @@ -903,8 +902,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 - * occupied slot. + * \param source_handle The key to copy. It must be a valid key handle. * \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 @@ -3397,7 +3395,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 diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h index 45655ddfc..c8876178c 100644 --- a/include/psa/crypto_extra.h +++ b/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, - * generating or creating a key in the slot. Changing the policy of an + * This function must be called on a key handle before importing, + * 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. - * When key material is later created in this key slot, + * \param[out] handle On success, a handle to the newly created key. + * 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_TAMPERING_DETECTED diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index c54fc9a60..d5c62de90 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -105,8 +105,8 @@ * 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, - * but shall return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST + * that a key either exists or not, + * but shall instead return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST * as applicable. */ #define PSA_ERROR_BAD_STATE ((psa_status_t)-137) @@ -116,7 +116,7 @@ * combination of parameters are recognized as invalid. * * 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 * as applicable. * From d56456cbe8967c77aaed1cc5bdd96ecb8459d307 Mon Sep 17 00:00:00 2001 From: "Adrian L. Shaw" Date: Wed, 15 May 2019 11:36:13 +0100 Subject: [PATCH 2/4] Improve descriptions that mention handles and fix incorrect mention of psa_create_key --- include/psa/crypto.h | 10 +++++----- include/psa/crypto_values.h | 13 ++++++------- 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 5f80b131b..22dea8feb 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -539,9 +539,10 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes); * @{ */ -/** Get a handle to an existing persistent key. +/** Open a handle to an existing persistent key. * - * Get 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. * * Implementations may provide additional keys that can be opened with * psa_open_key(). Such keys have a key identifier in the vendor range, @@ -669,8 +670,7 @@ psa_status_t psa_import_key(const psa_key_attributes_t *attributes, * * 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 handle is - * unrecoverable. + * make a best effort to ensure that that the key material cannot be recovered. * * This function also erases any metadata such as policies and frees all * resources associated with the key. @@ -678,7 +678,7 @@ psa_status_t psa_import_key(const psa_key_attributes_t *attributes, * \param handle Handle to the key to erase. * * \retval #PSA_SUCCESS - * The handle's content, if any, has been erased. + * The key material has been erased. * \retval #PSA_ERROR_NOT_PERMITTED * The handle holds content and cannot be erased because it is * read-only, either due to a policy or due to physical restrictions. diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index d5c62de90..83a65053d 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -107,7 +107,11 @@ * Implementations shall not return this error code to indicate * that a key either exists or not, * 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 - * that a key either exists or not, - * 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 + * Implementations shall not return this error code to indicate that a * key handle is invalid, but shall return #PSA_ERROR_INVALID_HANDLE * instead. */ From 52d83dabd636fa4b97b1ee73d6bc1a6476d1406e Mon Sep 17 00:00:00 2001 From: "Adrian L. Shaw" Date: Wed, 15 May 2019 11:39:06 +0100 Subject: [PATCH 3/4] Mention psa_close_key in the description of psa_open_key --- include/psa/crypto.h | 2 ++ 1 file changed, 2 insertions(+) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 22dea8feb..fc5d8079c 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -543,6 +543,8 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes); * * 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, From 0a695bd13e6d00cb67f8e65d69e089a728940951 Mon Sep 17 00:00:00 2001 From: "Adrian L. Shaw" Date: Wed, 15 May 2019 13:28:41 +0100 Subject: [PATCH 4/4] Simplify description of psa_copy_key --- include/psa/crypto.h | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index fc5d8079c..ca0d57dd7 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -682,7 +682,7 @@ psa_status_t psa_import_key(const psa_key_attributes_t *attributes, * \retval #PSA_SUCCESS * The key material has been erased. * \retval #PSA_ERROR_NOT_PERMITTED - * The handle 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 @@ -874,8 +874,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 handles 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