Clarify and expand the documentation of the allocate/create sequence
diff --git a/include/psa/crypto_se_driver.h b/include/psa/crypto_se_driver.h
index 127f17b..9a5d97d 100644
--- a/include/psa/crypto_se_driver.h
+++ b/include/psa/crypto_se_driver.h
@@ -812,6 +812,42 @@
/** \brief A function that allocates a slot for a key.
*
+ * To create a key in a specific slot in a secure element, the core
+ * first calls this function to determine a valid slot number,
+ * then calls a function to create the key material in that slot.
+ * For example, in nominal conditions (that is, if no error occurs),
+ * the effect of a call to psa_import_key() with a lifetime that places
+ * the key in a secure element is the following:
+ * -# The core calls psa_drv_se_key_management_t::p_allocate
+ * (or in some implementations
+ * psa_drv_se_key_management_t::p_validate_slot_number). The driver
+ * selects (or validates) a suitable slot number given the key attributes
+ * and the state of the secure element.
+ * -# The core calls psa_drv_se_key_management_t::p_import to import
+ * the key material in the selected slot.
+ *
+ * Other key creation methods lead to similar sequences. For example, the
+ * sequence for psa_generate_key() is the same except that the second step
+ * is a call to psa_drv_se_key_management_t::p_generate.
+ *
+ * In case of errors, other behaviors are possible.
+ * - If the PSA Cryptography subsystem dies after the first step,
+ * for example because the device has lost power abruptly,
+ * the second step may never happen, or may happen after a reset
+ * and re-initialization. Alternatively, after a reset and
+ * re-initialization, the core may call
+ * psa_drv_se_key_management_t::p_destroy on the slot number that
+ * was allocated (or validated) instead of calling a key creation function.
+ * - If an error occurs, the core may call
+ * psa_drv_se_key_management_t::p_destroy on the slot number that
+ * was allocated (or validated) instead of calling a key creation function.
+ *
+ * Errors and system resets also have an impact on the driver's persistent
+ * data. If a reset happens before the overall key creation process is
+ * completed (before or after the second step above), it is unspecified
+ * whether the persistent data after the reset is identical to what it
+ * was before or after the call to `p_allocate` (or `p_validate_slot_number`).
+ *
* \param[in,out] drv_context The driver context structure.
* \param[in,out] persistent_data A pointer to the persistent data
* that allows writing.
@@ -836,6 +872,18 @@
/** \brief A function that determines whether a slot number is valid
* for a key.
*
+ * To create a key in a specific slot in a secure element, the core
+ * first calls this function to validate the choice of slot number,
+ * then calls a function to create the key material in that slot.
+ * See the documentation of #psa_drv_se_allocate_key_t for more details.
+ *
+ * As of the PSA Cryptography API specification version 1.0, there is no way
+ * for applications to trigger a call to this function. However some
+ * implementations offer the capability to create or declare a key in
+ * a specific slot via implementation-specific means, generally for the
+ * sake of initial device provisioning or onboarding. Such a mechanism may
+ * be added to a future version of the PSA Cryptography API specification.
+ *
* \param[in,out] drv_context The driver context structure.
* \param[in] attributes Attributes of the key.
* \param[in] key_slot Slot where the key is to be stored.
@@ -1001,31 +1049,9 @@
* If one of the functions is not implemented, it should be set to NULL.
*/
typedef struct {
- /** Function that allocates a slot for a key.
- *
- * The core calls this function to determine a slot number, then
- * calls the actual creation function (such as
- * psa_drv_se_key_management_t::p_import or
- * psa_drv_se_key_management_t::p_generate).
- *
- * If this function succeeds, the next call that the core makes to the
- * driver is either the creation function or
- * psa_drv_se_key_management_t::p_destroy. Note that
- * if the platform is reset after this function returns, the core
- * may either subsequently call
- * psa_drv_se_key_management_t::p_destroy or may behave as if the
- * last call to this function had not taken place.
- */
+ /** Function that allocates a slot for a key. */
psa_drv_se_allocate_key_t p_allocate;
- /** Function that checks the validity of a slot for a key.
- *
- * The core calls this function instead of
- * psa_drv_se_key_management_t::p_allocate to create
- * a key in a specific slot. It then calls the actual creation function
- * (such as psa_drv_se_key_management_t::p_import or
- * psa_drv_se_key_management_t::p_generate) or
- * psa_drv_se_key_management_t::p_destroy.
- */
+ /** Function that checks the validity of a slot for a key. */
psa_drv_se_validate_slot_number_t p_validate_slot_number;
/** Function that performs a key import operation */
psa_drv_se_import_key_t p_import;