From 09829036ab8e2757c00848c72c724fa7bf728deb Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Mon, 10 Dec 2018 17:00:38 +0100
Subject: [PATCH] Document some functions in internal headers

---
 library/psa_crypto_core.h            | 34 ++++++++++++++++++++++++----
 library/psa_crypto_slot_management.h | 26 +++++++++++++++++----
 2 files changed, 52 insertions(+), 8 deletions(-)

diff --git a/library/psa_crypto_core.h b/library/psa_crypto_core.h
index 24140b517..c28968197 100644
--- a/library/psa_crypto_core.h
+++ b/library/psa_crypto_core.h
@@ -60,12 +60,38 @@ typedef struct
 } psa_key_slot_t;
 
 /** Completely wipe a slot in memory, including its policy.
- * Persistent storage is not affected. */
+ *
+ * Persistent storage is not affected.
+ *
+ * \param[in,out] slot  The key slot to wipe.
+ *
+ * \retval PSA_SUCCESS
+ *         Success. This includes the case of a key slot that was
+ *         already fully wiped.
+ * \retval PSA_ERROR_TAMPERING_DETECTED
+ */
 psa_status_t psa_wipe_key_slot( psa_key_slot_t *slot );
 
-/** Import key data into a slot. `slot->type` must have been set
- * previously. This function assumes that the slot does not contain
- * any key material yet. On failure, the slot content is unchanged. */
+/** Import key data into a slot.
+ *
+ * `slot->type` must have been set previously.
+ * This function assumes that the slot does not contain any key material yet.
+ * On failure, the slot content is unchanged.
+ *
+ * Persistent storage is not affected.
+ *
+ * \param[in,out] slot  The key slot to import data into.
+ *                      Its `type` field must have previously been set to
+ *                      the desired key type.
+ *                      It must not contain any key material yet.
+ * \param[in] data      Buffer containing the key material to parse and import.
+ * \param data_length   Size of \p data in bytes.
+ *
+ * \retval PSA_SUCCESS
+ * \retval PSA_ERROR_INVALID_ARGUMENT
+ * \retval PSA_ERROR_NOT_SUPPORTED
+ * \retval PSA_ERROR_INSUFFICIENT_MEMORY
+ */
 psa_status_t psa_import_key_into_slot( psa_key_slot_t *slot,
                                        const uint8_t *data,
                                        size_t data_length );
diff --git a/library/psa_crypto_slot_management.h b/library/psa_crypto_slot_management.h
index a2e52ba32..6746bad91 100644
--- a/library/psa_crypto_slot_management.h
+++ b/library/psa_crypto_slot_management.h
@@ -26,15 +26,33 @@
  * The value is a compile-time constant for now, for simplicity. */
 #define PSA_KEY_SLOT_COUNT 32
 
-/** Access a key slot at the given handle. */
+/** Access a key slot at the given handle.
+ *
+ * \param handle        Key handle to query.
+ * \param[out] p_slot   On success, `*p_slot` contains a pointer to the
+ *                      key slot in memory designated by \p handle.
+ *
+ * \retval PSA_SUCCESS
+ *         Success: \p handle is a handle to `*p_slot`. Note that `*p_slot`
+ *         may be empty or occupied.
+ * \retval PSA_ERROR_INVALID_HANDLE
+ *         \p handle is out of range or is not in use.
+ * \retval PSA_ERROR_BAD_STATE
+ *         The library has not been initialized.
+ */
 psa_status_t psa_get_key_slot( psa_key_handle_t handle,
                                psa_key_slot_t **p_slot );
 
-/** Initialize the key slot structures. */
+/** Initialize the key slot structures.
+ *
+ * \retval PSA_SUCCESS
+ *         Currently this function always succeeds.
+ */
 psa_status_t psa_initialize_key_slots( void );
 
-/** Delete all data from key slots in memory. This does not affect persistent
- * storage. */
+/** Delete all data from key slots in memory.
+ *
+ * This does not affect persistent storage. */
 void psa_wipe_all_key_slots( void );
 
 #endif /* PSA_CRYPTO_SLOT_MANAGEMENT_H */