From d56456cbe8967c77aaed1cc5bdd96ecb8459d307 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrian.shaw@arm.com>
Date: Wed, 15 May 2019 11:36:13 +0100
Subject: [PATCH] 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.
  */