PSA partial initialization

include/psa/crypto.h

@@ -75,18 +75,12 @@ extern "C" {
  * \brief Library initialization.
  *
  * Applications must call this function before calling any other
- * function in this module.
+ * function in this module, except as otherwise indicated.
  *
  * Applications may call this function more than once. Once a call
  * succeeds, subsequent calls are guaranteed to succeed.
  *
- * If the application calls other functions before calling psa_crypto_init(),
- * the behavior is undefined. Implementations are encouraged to either perform
- * the operation as if the library had been initialized or to return
- * #PSA_ERROR_BAD_STATE or some other applicable error. In particular,
- * implementations should not return a success status if the lack of
- * initialization may have security implications, for example due to improper
- * seeding of the random number generator.
+ * For finer control over initialization, see psa_crypto_init_subsystem().
  *
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -101,6 +95,44 @@ extern "C" {
  */
 psa_status_t psa_crypto_init(void);
 
+/**
+ * \brief Partial library initialization.
+ *
+ * Applications may call this function on the same subsystem more than once.
+ * Once a call succeeds, subsequent calls with the same subsystem are
+ * guaranteed to succeed.
+ *
+ * Initializing a subsystem may initialize other subsystems if the
+ * implementations needs them internally. For example, in a typical
+ * client-server implementation, #PSA_CRYPTO_SUBSYSTEM_COMMUNICATION is
+ * required for all other subsystems, and therefore initializing any other
+ * subsystem also initializes #PSA_CRYPTO_SUBSYSTEM_COMMUNICATION.
+ *
+ * Calling psa_crypto_init() is equivalent to calling
+ * psa_crypto_init_subsystem() on all the available subsystems.
+ *
+ * \note This function is part of a draft API specification and may change
+ *       as the API evolves.
+ *
+ * \note You can initialize multiple subsystems in the same call by passing
+ *       a bitwise-or of \c PSA_CRYPTO_SUBSYSTEM_xxx values. This ability
+ *       is experimental and may change without notice. If the initialization
+ *       of one subsystem fails, it is unspecified whether other requested
+ *       subsystems are initialized or not.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_DATA_CORRUPT
+ */
+psa_status_t psa_crypto_init_subsystem(psa_crypto_subsystem_t subsystem);
+
 /**@}*/
 
 /** \addtogroup attributes

include/psa/crypto_extra.h

@@ -216,6 +216,26 @@ psa_status_t mbedtls_psa_register_se_key(
  */
 void mbedtls_psa_crypto_free( void );
 
+/**
+ * \brief Query the library initialization state.
+ *
+ * This is an Mbed TLS extension.
+ *
+ * \note This function is experimental and may change or be removed
+ *       without notice.
+ *
+ * \note You can pass a mask of subsystems as \p subsystem, and this
+ *       function returns 1 if and only if all the given subsystems are
+ *       initialized. This ability is experimental and may be removed
+ *       without notice.
+ *
+ * \param subsystem     The subsystem to query.
+ *
+ * \return 1 if the given subsysem is already initialized, otherwise 0.
+ */
+int mbedtls_psa_crypto_is_subsystem_initialized(
+    psa_crypto_subsystem_t subsystem );
+
 /** \brief Statistics about
  * resource consumption related to the PSA keystore.
  *

include/psa/crypto_types.h

@@ -462,4 +462,132 @@ typedef uint16_t psa_key_derivation_step_t;
 
 /**@}*/
 
+/** \addtogroup initialization
+ * @{
+ */
+
+/* Auxiliary type for values of type psa_crypto_subsystem_index_t */
+typedef enum {
+    MBEDTLS_PSA_CRYPTO_SUBSYSTEM_COMMUNICATION_INDEX,
+    MBEDTLS_PSA_CRYPTO_SUBSYSTEM_KEYS_INDEX,
+    MBEDTLS_PSA_CRYPTO_SUBSYSTEM_STORAGE_INDEX,
+    MBEDTLS_PSA_CRYPTO_SUBSYSTEM_ACCELERATORS_INDEX,
+    MBEDTLS_PSA_CRYPTO_SUBSYSTEM_SECURE_ELEMENTS_INDEX,
+    MBEDTLS_PSA_CRYPTO_SUBSYSTEM_RANDOM_INDEX,
+    MBEDTLS_PSA_CRYPTO_SUBSYSTEM_BUILTIN_KEYS_INDEX,
+    /* Must come last. Value equal to the number of preceding elements. */
+    MBEDTLS_PSA_CRYPTO_SUBSYSTEM_COUNT
+} mbedtls_psa_crypto_subsystem_index_t;
+
+/** \brief The designation of a subsystem of the PSA Crypto implementation.
+ *
+ * Value of this type are masks of \c PSA_CRYPTO_SUBSYSTEM_xxx constants.
+ *
+ * \note This type is experimental and may change without notice.
+ */
+typedef uint32_t psa_crypto_subsystem_t;
+
+/** Communication with the server, if this is a client that communicates
+ * with a server where the key store is located.
+ *
+ * In a client-server implementation, this subsystem is necessary
+ * before any API function other than library initialization,
+ * deinitialization and functions accessing local data structures
+ * such as key attributes.
+ *
+ * In a library implementation, initializing this subsystem does nothing
+ * and succeeds.
+ */
+#define PSA_CRYPTO_SUBSYSTEM_COMMUNICATION \
+    ((psa_crypto_subsystem_t)1 << MBEDTLS_PSA_CRYPTO_SUBSYSTEM_COMMUNICATION_INDEX)
+
+/** The key store in memory.
+ *
+ * Initializing this subsystem allows creating, accessing and destroying
+ * volatile keys in the default location, i.e.  keys with the lifetime
+ * #PSA_KEY_LIFETIME_VOLATILE.
+ *
+ * Persistent keys also require #PSA_CRYPTO_SUBSYSTEM_STORAGE.
+ * Keys in other locations also require
+ * #PSA_CRYPTO_SUBSYSTEM_SECURE_ELEMENTS.
+ */
+#define PSA_CRYPTO_SUBSYSTEM_KEYS \
+    ((psa_crypto_subsystem_t)1 << MBEDTLS_PSA_CRYPTO_SUBSYSTEM_KEYS_INDEX)
+
+/** Access to keys in storage.
+ *
+ * Initializing this subsystem as well as #PSA_CRYPTO_SUBSYSTEM_KEYS
+ * allows creating, accessing and destroying persistent keys.
+ *
+ * Oersistent keys in secure elements also require
+ * #PSA_CRYPTO_SUBSYSTEM_SECURE_ELEMENTS.
+ */
+#define PSA_CRYPTO_SUBSYSTEM_STORAGE \
+    ((psa_crypto_subsystem_t)1 << MBEDTLS_PSA_CRYPTO_SUBSYSTEM_STORAGE_INDEX)
+
+/** Accelerator drivers.
+ *
+ * Initializing this subsystem calls the initialization entry points
+ * of all registered accelerator drivers.
+ *
+ * Initializing this subsystem allows cryptographic operations that
+ * are implemented via an accelerator driver.
+ */
+#define PSA_CRYPTO_SUBSYSTEM_ACCELERATORS \
+    ((psa_crypto_subsystem_t)1 << MBEDTLS_PSA_CRYPTO_SUBSYSTEM_ACCELERATORS_INDEX)
+
+/** Secure element drivers.
+ *
+ * Initializing this subsystem calls the initialization entry points
+ * of all registered secure element drivers.
+ *
+ * Initializing this subsystem as well as #PSA_CRYPTO_SUBSYSTEM_KEYS
+ * allows creating, accessing and destroying keys in a secure element
+ * (i.e. keys whose location is not #PSA_KEY_LOCATION_LOCAL_STORAGE).
+ */
+#define PSA_CRYPTO_SUBSYSTEM_SECURE_ELEMENTS \
+    ((psa_crypto_subsystem_t)1 << MBEDTLS_PSA_CRYPTO_SUBSYSTEM_SECURE_ELEMENTS_INDEX)
+
+/** Initialize the random generator.
+ *
+ * Initializing this subsystem initializes all registered entropy drivers
+ * and accesses the registered entropy sources.
+ *
+ * Initializing this subsystem is necessary for psa_generate_random(),
+ * psa_generate_key(), as well as some operations using private or
+ * secret keys. Only the following operations are guaranteed not to
+ * require this subsystem:
+ *
+ * - hash operations;
+ * - signature verification operations.
+ *
+ * \note Currently, symmetric decryption (authenticated or not) and
+ *       MAC operations do not require the random generator.
+ *       This may change in future versions of the library
+ *       or when the operations are performed by a driver.
+ */
+#define PSA_CRYPTO_SUBSYSTEM_RANDOM \
+    ((psa_crypto_subsystem_t)1 << MBEDTLS_PSA_CRYPTO_SUBSYSTEM_RANDOM_INDEX)
+
+/** Access to built-in keys.
+ *
+ * Initializing this subsystem as well as #PSA_CRYPTO_SUBSYSTEM_KEYS
+ * allows access to built-in keys.
+ */
+#define PSA_CRYPTO_SUBSYSTEM_BUILTIN_KEYS \
+    ((psa_crypto_subsystem_t)1 << MBEDTLS_PSA_CRYPTO_SUBSYSTEM_BUILTIN_KEYS_INDEX)
+
+/* A mask of all the subsystems recognized by Mbed TLS. */
+#define MBEDTLS_PSA_CRYPTO_ALL_SUBSYSTEMS (     \
+        PSA_CRYPTO_SUBSYSTEM_COMMUNICATION |    \
+        PSA_CRYPTO_SUBSYSTEM_KEYS |             \
+        PSA_CRYPTO_SUBSYSTEM_STORAGE |          \
+        PSA_CRYPTO_SUBSYSTEM_ACCELERATORS |     \
+        PSA_CRYPTO_SUBSYSTEM_SECURE_ELEMENTS |  \
+        PSA_CRYPTO_SUBSYSTEM_RANDOM |           \
+        PSA_CRYPTO_SUBSYSTEM_BUILTIN_KEYS |     \
+        0 )
+
+/**@}*/
+
 #endif /* PSA_CRYPTO_TYPES_H */