Provide incremental by-subsystem initialization for the crypto library

doc/crypto/api.db/psa/crypto.h

@@ -4,6 +4,7 @@
 typedef /* implementation-defined type */ psa_aead_operation_t;
 typedef uint32_t psa_algorithm_t;
 typedef /* implementation-defined type */ psa_cipher_operation_t;
+typedef uint32_t psa_crypto_subsystem_t;
 typedef uint8_t psa_dh_family_t;
 typedef uint8_t psa_ecc_family_t;
 typedef /* implementation-defined type */ psa_hash_operation_t;
@@ -209,8 +210,16 @@ typedef struct psa_custom_key_parameters_t {
     /* implementation-defined value */
 #define PSA_CIPHER_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) \
     /* implementation-defined value */
+#define PSA_CRYPTO_ALL_SUBSYSTEMS /* implementation-defined value */
 #define PSA_CRYPTO_API_VERSION_MAJOR 1
 #define PSA_CRYPTO_API_VERSION_MINOR 3
+#define PSA_CRYPTO_SUBSYSTEM_ACCELERATORS /* implementation-defined value */
+#define PSA_CRYPTO_SUBSYSTEM_BUILTIN_KEYS /* implementation-defined value */
+#define PSA_CRYPTO_SUBSYSTEM_COMMUNICATION /* implementation-defined value */
+#define PSA_CRYPTO_SUBSYSTEM_KEYS /* implementation-defined value */
+#define PSA_CRYPTO_SUBSYSTEM_RANDOM /* implementation-defined value */
+#define PSA_CRYPTO_SUBSYSTEM_SECURE_ELEMENTS /* implementation-defined value */
+#define PSA_CRYPTO_SUBSYSTEM_STORAGE /* implementation-defined value */
 #define PSA_CUSTOM_KEY_PARAMETERS_INIT { 0 }
 #define PSA_DH_FAMILY_RFC7919 ((psa_dh_family_t) 0x03)
 #define PSA_ECC_FAMILY_BRAINPOOL_P_R1 ((psa_ecc_family_t) 0x30)
@@ -503,6 +512,7 @@ psa_status_t psa_copy_key(psa_key_id_t source_key,
                           const psa_key_attributes_t * attributes,
                           psa_key_id_t * target_key);
 psa_status_t psa_crypto_init(void);
+psa_status_t psa_crypto_init_subsystem(psa_crypto_subsystem_t subsystem);
 psa_status_t psa_decapsulate(psa_key_id_t key,
                              psa_algorithm_t alg,
                              const uint8_t * ciphertext,

doc/crypto/api/keys/attributes.rst

@@ -159,7 +159,7 @@ Managing key attributes
     .. retval:: PSA_ERROR_DATA_CORRUPT
     .. retval:: PSA_ERROR_DATA_INVALID
     .. retval:: PSA_ERROR_BAD_STATE
-        The library requires initializing by a call to `psa_crypto_init()`.
+        The library requires initializing. See :secref:`library-init`.
 
     This function first resets the attribute object as with `psa_reset_key_attributes()`. It then copies the attributes of the given key into the given attribute object.
 

doc/crypto/api/keys/ids.rst

@@ -13,15 +13,15 @@ Key identifiers are integral values that act as permanent names for persistent k
 :code:`PSA_KEY_ID_USER_MIN - PSA_KEY_ID_USER_MAX`
     Applications can freely choose persistent key identifiers in this range.
 :code:`PSA_KEY_ID_VENDOR_MIN - PSA_KEY_ID_VENDOR_MAX`
-    Implementations can define additional persistent key identifiers in this range, and must allocate any volatile key identifiers from this range.
+    Implementations can define additional persistent key identifiers in this range for :term:`built-in key`\ s, and must allocate any volatile key identifiers from this range.
 
 Key identifiers outside these ranges are reserved for future use.
 
 Key identifiers are output from a successful call to one of the key creation functions. For persistent keys, this is the same identifier as the one specified in the key attributes used to create the key. The key identifier remains valid until it is invalidated by passing it to `psa_destroy_key()`. A volatile key identifier must not be used after it has been invalidated.
 
 If an invalid key identifier is provided as a parameter in any function, the function will return :code:`PSA_ERROR_INVALID_HANDLE`; except for the special case of calling :code:`psa_destroy_key(PSA_KEY_ID_NULL)`, which has no effect and always returns :code:`PSA_SUCCESS`.
 
-Valid key identifiers must have distinct values within the same application. If the implementation provides :term:`caller isolation`, then key identifiers are local to each application. That is, the same key identifier in two applications corresponds to two different keys.
+Valid key identifiers must have distinct values within the same application. If the implementation provides :term:`caller isolation`, then key identifiers are local to each application. That is, keys that are created by two applications with the same key identifier are two separate keys.
 
 
 Key identifier type

doc/crypto/api/keys/lifetimes.rst

@@ -44,7 +44,7 @@ application specifies the key identifier when the key is created and when
 using the key.
 
 The lifetime attribute of a persistent key indicates how and where it is stored. The default lifetime value for a persistent key is `PSA_KEY_LIFETIME_PERSISTENT`, which corresponds to a default storage area. This specification defines how implementations can provide other lifetime values corresponding to
-different storage areas with different retention policies, or to secure elements
+different storage areas with different retention policies, or to :term:`secure element`\ s
 with different security characteristics.
 
 To create a persistent key:

doc/crypto/api/keys/management.rst

@@ -100,7 +100,7 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
     .. retval:: PSA_ERROR_DATA_INVALID
     .. retval:: PSA_ERROR_CORRUPTION_DETECTED
     .. retval:: PSA_ERROR_BAD_STATE
-        The library requires initializing by a call to `psa_crypto_init()`.
+        The library requires initializing, see :secref:`library-init`.
 
     The key is extracted from the provided ``data`` buffer. Its location, policy, and type are taken from ``attributes``.
 
@@ -224,7 +224,7 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
     .. retval:: PSA_ERROR_DATA_CORRUPT
     .. retval:: PSA_ERROR_DATA_INVALID
     .. retval:: PSA_ERROR_BAD_STATE
-        The library requires initializing by a call to `psa_crypto_init()`.
+        The library requires initializing, see :secref:`library-init`.
 
     The key is generated randomly. Its location, policy, type and size are taken from ``attributes``.
 
@@ -311,7 +311,7 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
     .. retval:: PSA_ERROR_DATA_CORRUPT
     .. retval:: PSA_ERROR_DATA_INVALID
     .. retval:: PSA_ERROR_BAD_STATE
-        The library requires initializing by a call to `psa_crypto_init()`.
+        The library requires initializing. See :secref:`library-init`.
 
     Use this function to provide explicit production parameters when generating a key.
     See the description of `psa_generate_key()` for the operation of this function with the default production parameters.
@@ -330,7 +330,7 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
     .. param:: psa_key_id_t source_key
         The key to copy.
         It must permit the usage `PSA_KEY_USAGE_COPY`.
-        If a private or secret key is being copied outside of a secure element it must also permit `PSA_KEY_USAGE_EXPORT`.
+        If a private or secret key is being copied outside of a :term:`secure element` it must also permit `PSA_KEY_USAGE_EXPORT`.
     .. param:: const psa_key_attributes_t * attributes
         The attributes for the new key.
 
@@ -391,7 +391,7 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
     .. retval:: PSA_ERROR_DATA_INVALID
     .. retval:: PSA_ERROR_CORRUPTION_DETECTED
     .. retval:: PSA_ERROR_BAD_STATE
-        The library requires initializing by a call to `psa_crypto_init()`.
+        The library requires initializing, see :secref:`library-init`.
 
     Copy key material from one location to another. Its location is taken from ``attributes``, its policy is the intersection of the policy in ``attributes`` and the source key policy, and its type and size are taken from the source key.
 
@@ -445,7 +445,7 @@ Key destruction
     .. retval:: PSA_ERROR_CORRUPTION_DETECTED
         An unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor might have been compromised.
     .. retval:: PSA_ERROR_BAD_STATE
-        The library requires initializing by a call to `psa_crypto_init()`.
+        The library requires initializing, see :secref:`library-init`.
 
     This function destroys a key from both volatile memory and, if applicable, non-volatile storage. Implementations must make a best effort to ensure that that the key material cannot be recovered.
 
@@ -475,7 +475,7 @@ Key destruction
     .. retval:: PSA_ERROR_DATA_INVALID
     .. retval:: PSA_ERROR_CORRUPTION_DETECTED
     .. retval:: PSA_ERROR_BAD_STATE
-        The library requires initializing by a call to `psa_crypto_init()`.
+        The library requires initializing, see :secref:`library-init`.
 
     For keys that have been created with the `PSA_KEY_USAGE_CACHE` usage flag, an implementation is permitted to make additional copies of the key material that are not in storage and not for the purpose of ongoing operations.
 
@@ -540,7 +540,7 @@ Key export
     .. retval:: PSA_ERROR_DATA_INVALID
     .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY
     .. retval:: PSA_ERROR_BAD_STATE
-        The library requires initializing by a call to `psa_crypto_init()`.
+        The library requires initializing, see :secref:`library-init`.
 
     The output of this function can be passed to `psa_import_key()` to create an equivalent object.
 
@@ -592,7 +592,7 @@ Key export
     .. retval:: PSA_ERROR_DATA_INVALID
     .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY
     .. retval:: PSA_ERROR_BAD_STATE
-        The library requires initializing by a call to `psa_crypto_init()`.
+        The library requires initializing, see :secref:`library-init`.
 
     The output of this function can be passed to `psa_import_key()` to create an object that is equivalent to the public key.
 

doc/crypto/api/keys/policy.rst

@@ -112,7 +112,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`.
 
     *   This flag is required to export a key from the cryptoprocessor using `psa_export_key()`. A public key or the public part of a key pair can always be exported regardless of the value of this permission flag.
 
-    *   This flag can also be required to make a copy of a key outside of a secure element using `psa_copy_key()`. See also `PSA_KEY_USAGE_COPY`.
+    *   This flag can also be required to make a copy of a key outside of a :term:`secure element` using `psa_copy_key()`. See also `PSA_KEY_USAGE_COPY`.
 
     If a key does not have export permission, implementations must not permit the key to be exported in plain form from the cryptoprocessor, whether through `psa_export_key()` or through a proprietary interface. The key might still be exportable in a wrapped form, i.e. in a form where it is encrypted by another key.