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).
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index d3b7522..7291c3e 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -459,9 +459,12 @@
* 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 @@
* 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.