From 203491c65d143631688fd306ecaf81e5b27e16e1 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 21 Aug 2019 17:55:30 +0100 Subject: [PATCH 1/6] Remove duplicated information in psa_open_key The information about implmementation keys is duplicated. --- include/psa/crypto.h | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 2b5bb97fc..81739bcdc 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -358,18 +358,14 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes); * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key * always has a nonzero key identifier, set with psa_set_key_id() when * creating the key. Implementations may provide additional pre-provisioned - * keys with identifiers in the range - * #PSA_KEY_ID_VENDOR_MIN–#PSA_KEY_ID_VENDOR_MAX. + * 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. * * The application must eventually close the handle with psa_close_key() * to release associated resources. If the application dies without calling * psa_close_key(), the implementation should perform the equivalent of a * call to psa_close_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 the key. * From 9741b114402b5552cdbeaf52352391d10bd3ddc7 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 21 Aug 2019 18:20:41 +0100 Subject: [PATCH 2/6] Update psa_open_key documentation - Describe the implementation defined behavior for opening multiple keys, and provide a reference to the relevant section. - Describe the use of INSUFFICENT_MEMORY error to indicate additional implementation resource constaints. - Clarify the distinction between DOES_NOT_EXIST and INVALID_HANDLE error conditions. --- include/psa/crypto.h | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 81739bcdc..e067cbdd1 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -366,6 +366,11 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes); * psa_close_key(), the implementation should perform the equivalent of a * call to psa_close_key(). * + * Some implementations permit an application to open the same key multiple + * times. Applications that rely on this behavior will not be portable to + * implementations that only permit a single key handle to be opened. See + * also :ref:\`key-handles\`. + * * \param id The persistent identifier of the key. * \param[out] handle On success, a handle to the key. * @@ -373,9 +378,14 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes); * Success. The application can now use the value of `*handle` * to access the key. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * The implementation does not have sufficient resources to open the + * key. This can be due to reaching an implementation limit on the + * number of open keys, the number of open key handles, or available + * memory. * \retval #PSA_ERROR_DOES_NOT_EXIST + * There is no persistent key with key identifier \p id. * \retval #PSA_ERROR_INVALID_ARGUMENT - * \p id is invalid. + * \p id is not a valid persistent key identifier. * \retval #PSA_ERROR_NOT_PERMITTED * The specified key exists, but the application does not have the * permission to access it. Note that this specification does not From 3daba812d7640274f40069aedb0a943c0e61f799 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 21 Aug 2019 22:46:56 +0100 Subject: [PATCH 3/6] Update documentation for psa_close_key Adjust the wording to permit multiple handles to a single key - closing a handle does not necessarily release volatile memory associated with the key, that only occurs when the last handle is closed. --- include/psa/crypto.h | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index e067cbdd1..8aa11ce94 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -400,15 +400,19 @@ psa_status_t psa_open_key(psa_key_id_t id, /** 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 volatile key, this will 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 in persistent storage is - * not affected and can be opened again later with psa_open_key(). + * If this is the last open handle to a persistent key, then closing the handle + * will free all resources associated with the key in volatile memory. The key + * data in persistent storage is not affected and can be opened again later + * with a call to psa_open_key(). * - * If the key is currently in use in a multipart operation, - * the multipart operation is aborted. + * Closing the key handle makes the handle invalid, and the key handle + * must not be used again by the application.. + * + * If the key is currently in use in a multipart operation, then closing the + * last handle to the key will abort the multipart operation. * * \param handle The key handle to close. * From 07f16b78ffc90a0d1a735289c5eee33f40ec3fe8 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 21 Aug 2019 22:48:47 +0100 Subject: [PATCH 4/6] Update documentation for psa_destroy_key Define the affect on handles to the key and on active multipart operations. --- include/psa/crypto.h | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 8aa11ce94..eac0ff2bf 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -506,6 +506,11 @@ psa_status_t psa_import_key(const psa_key_attributes_t *attributes, * This function also erases any metadata such as policies and frees all * resources associated with the key. * + * Destroying a key will invalidate all existing handles to the key. + * + * If the key is currently in use in a multipart operation, then destroying the + * key will abort the multipart operation. + * * \param handle Handle to the key to erase. * * \retval #PSA_SUCCESS From 3c2b80377b208ee1ffd4e04ff9646c47fe4255a6 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 22 Aug 2019 12:20:12 +0100 Subject: [PATCH 5/6] Cross reference 'key handles' from INVALID_HANDLE --- include/psa/crypto_values.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index e0600a189..0781fa441 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -268,7 +268,7 @@ * to read from a resource. */ #define PSA_ERROR_INSUFFICIENT_DATA ((psa_status_t)-143) -/** The key handle is not valid. +/** The key handle is not valid. See also :ref:\`key-handles\`. */ #define PSA_ERROR_INVALID_HANDLE ((psa_status_t)-136) From 8824daec6ff61a513c23331e0990a9e9c44daf5b Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 22 Aug 2019 15:04:48 +0100 Subject: [PATCH 6/6] Editorial fixes. --- include/psa/crypto.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index eac0ff2bf..c3f8b6ea7 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -409,10 +409,10 @@ psa_status_t psa_open_key(psa_key_id_t id, * with a call to psa_open_key(). * * Closing the key handle makes the handle invalid, and the key handle - * must not be used again by the application.. + * must not be used again by the application. * * If the key is currently in use in a multipart operation, then closing the - * last handle to the key will abort the multipart operation. + * last remaining handle to the key will abort the multipart operation. * * \param handle The key handle to close. *