From 2493401af48ba57a778e7e4e76795a7271f07960 Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Tue, 8 Oct 2019 15:43:13 +0200
Subject: [PATCH] Document that psa_close_key(0) and psa_destroy_key(0) succeed

Document that passing 0 to a close/destroy function does nothing and
returns PSA_SUCCESS.

Although this was not written explicitly, the specification strongly
suggested that this would return PSA_ERROR_INVALID_HANDLE. While
returning INVALID_HANDLE makes sense, it was awkward for a very common
programming style where applications can store 0 in a handle variable
to indicate that the handle has been closed or has never been open:
applications had to either check if (handle != 0) before calling
psa_close_key(handle) or psa_destroy_key(handle), or ignore errors
from the close/destroy function. Now applications following this style
can just call psa_close_key(handle) or psa_destroy_key(handle).
---
 include/psa/crypto.h | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index d3b7522ab..7291c3e57 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -459,9 +459,12 @@ psa_status_t psa_open_key(psa_key_id_t id,
  * maintain the key handle until after the multipart operation has finished.
  *
  * \param handle        The key handle to close.
+ *                      If this is \c 0, do nothing and return \c PSA_SUCCESS.
  *
  * \retval #PSA_SUCCESS
+ *         \p handle was a valid handle or \c 0. It is now closed.
  * \retval #PSA_ERROR_INVALID_HANDLE
+ *         \p handle is not a valid handle nor \c 0.
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
@@ -579,13 +582,17 @@ psa_status_t psa_copy_key(psa_key_handle_t source_handle,
  * key will cause the multipart operation to fail.
  *
  * \param handle        Handle to the key to erase.
+ *                      If this is \c 0, do nothing and return \c PSA_SUCCESS.
  *
  * \retval #PSA_SUCCESS
- *         The key material has been erased.
+ *         \p handle was a valid handle and the key material that it
+ *         referred to has been erased.
+ *         Alternatively, \p handle is \c 0.
  * \retval #PSA_ERROR_NOT_PERMITTED
  *         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
+ *         \p handle is not a valid handle nor \c 0.
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  *         There was an failure in communication with the cryptoprocessor.
  *         The key material may still be present in the cryptoprocessor.