From d339aefd917d4503ff068e88de853cb21c2a43e3 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 9 Aug 2024 14:04:46 +0200 Subject: [PATCH] Clarify some internal documentation Signed-off-by: Gilles Peskine --- tf-psa-crypto/core/psa_crypto_core.h | 10 +++++++++- tf-psa-crypto/core/psa_crypto_slot_management.h | 16 +++++++++------- 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/tf-psa-crypto/core/psa_crypto_core.h b/tf-psa-crypto/core/psa_crypto_core.h index 91ef0bfb78..21e7559f01 100644 --- a/tf-psa-crypto/core/psa_crypto_core.h +++ b/tf-psa-crypto/core/psa_crypto_core.h @@ -88,7 +88,15 @@ typedef struct { /* The index of the slice containing this slot. * This field must be filled if the slot contains a key * (including keys being created or destroyed), and can be either - * filled or 0 when the slot is free. */ + * filled or 0 when the slot is free. + * + * In most cases, the slice index can be deduced from the key identifer. + * We keep it in a separate field for robustness (it reduces the chance + * that a coding mistake in the key store will result in accessing the + * wrong slice), and also so that it's available even on code paths + * during creation or destruction where the key identifier might not be + * filled in. + * */ uint8_t slice_index; #endif /* MBEDTLS_PSA_KEY_STORE_DYNAMIC */ diff --git a/tf-psa-crypto/core/psa_crypto_slot_management.h b/tf-psa-crypto/core/psa_crypto_slot_management.h index 26b73969b4..af1208e3ae 100644 --- a/tf-psa-crypto/core/psa_crypto_slot_management.h +++ b/tf-psa-crypto/core/psa_crypto_slot_management.h @@ -137,13 +137,15 @@ void psa_wipe_all_key_slots(void); * If multi-threading is enabled, the caller must hold the * global key slot mutex. * - * \param[out] volatile_key_id If null, reserve a cache slot for - * a persistent or built-in key. - * If non-null, allocate a slot for - * a volatile key. - * If non-null, on success, the volatile key - * identifier corresponding with the - * returned slot. + * \param[out] volatile_key_id - If null, reserve a cache slot for + * a persistent or built-in key. + * - If non-null, allocate a slot for + * a volatile key. On success, + * \p *volatile_key_id is the + * identifier corresponding to the + * returned slot. It is the caller's + * responsibility to set this key identifier + * in the attributes. * \param[out] p_slot On success, a pointer to the slot. * * \retval #PSA_SUCCESS \emptydescription