From 9741b114402b5552cdbeaf52352391d10bd3ddc7 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 21 Aug 2019 18:20:41 +0100 Subject: [PATCH] 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