Clarify some internal documentation
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/library/psa_crypto_core.h b/library/psa_crypto_core.h
index 91ef0bf..21e7559 100644
--- a/library/psa_crypto_core.h
+++ b/library/psa_crypto_core.h
@@ -88,7 +88,15 @@
/* 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/library/psa_crypto_slot_management.h b/library/psa_crypto_slot_management.h
index 26b7396..af1208e 100644
--- a/library/psa_crypto_slot_management.h
+++ b/library/psa_crypto_slot_management.h
@@ -137,13 +137,15 @@
* 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