Provide definitions for 'secure elemtn', 'accelerator', and 'built-in key'

* Xref the terms in suitable places
* Remove 'registration of drivers' from the description of crypto subsystem initialization.

Author: athoelke

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

@@ -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.
 

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.
 

doc/crypto/api/library/library.rst

@@ -146,19 +146,19 @@ If the application calls any function that returns a :code:`psa_status_t` result
     :definition: /* implementation-defined value */
 
     .. summary::
-        Crypto subsystem identifier for accelerator drivers.
+        Crypto subsystem identifier for :term:`cryptographic accelerator`\ s.
 
-    Initializing this subsystem results in initialization of all registered accelerator drivers.
+    Initializing this subsystem results in initialization of cryptographic hardware accelerator interfaces.
 
-    Initializing this subsystem allows cryptographic operations that are implemented via an accelerator driver.
+    Initializing this subsystem allows cryptographic operations that are implemented in an accelerator.
 
 .. macro:: PSA_CRYPTO_SUBSYSTEM_SECURE_ELEMENTS
     :definition: /* implementation-defined value */
 
     .. summary::
-        Crypto subsystem identifier for secure element drivers.
+        Crypto subsystem identifier for :term:`secure element`\ s.
 
-    Initializing this subsystem results in initialization of all registered secure element drivers.
+    Initializing this subsystem results in initialization of all cryptographic secure elements.
 
     Initializing this subsystem as well as `PSA_CRYPTO_SUBSYSTEM_KEYS` allows creating, accessing, and destroying keys in a secure element. That is, keys whose location is not `PSA_KEY_LOCATION_LOCAL_STORAGE`.
 
@@ -168,7 +168,7 @@ If the application calls any function that returns a :code:`psa_status_t` result
     .. summary::
         Crypto subsystem identifier for the random generator.
 
-    Initializing this subsystem initializes all registered entropy drivers, and accesses the registered entropy sources.
+    Initializing this subsystem initializes all entropy providers, and access to entropy sources.
 
     Initializing this subsystem is necessary for `psa_generate_random()`, `psa_generate_key()`, `psa_encapsulate()`, PAKE operations, and some operations using key pairs.
 
@@ -186,7 +186,7 @@ If the application calls any function that returns a :code:`psa_status_t` result
     :definition: /* implementation-defined value */
 
     .. summary::
-        Crypto subsystem identifier for access to built-in keys.
+        Crypto subsystem identifier for access to :term:`built-in key`\ s.
 
     Initializing this subsystem as well as `PSA_CRYPTO_SUBSYSTEM_KEYS` allows access to built-in keys.
 

doc/crypto/overview/sample-arch.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2022 Arm Limited and/or its affiliates <[email protected]>
+.. SPDX-FileCopyrightText: Copyright 2018-2022, 2024 Arm Limited and/or its affiliates <[email protected]>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. _architectures:
@@ -44,7 +44,7 @@ other partition runs an application. There is a security boundary between the
 two partitions, so that the application cannot access the cryptoprocessor,
 except through its public interface. Thus, the architecture provides
 :term:`cryptoprocessor isolation`. The cryptoprocessor has
-some non-volatile storage, a TRNG, and possibly, some cryptographic accelerators.
+some non-volatile storage, a true random number generator, and possibly, some :term:`cryptographic accelerator`\ s.
 
 There are a number of potential physical realizations: the cryptoprocessor might
 be a separate chip, a separate processor on the same chip, or a logical
@@ -103,7 +103,7 @@ have multiple cryptoprocessors:
 
 *   Different compromises between security and performance for different keys.
     Typically, this means a cryptoprocessor that runs on the same hardware as the
-    main application and processes short-term secrets, a secure element or a
+    main application and processes short-term secrets, a :term:`secure element` or a
     similar separate chip that retains long-term secrets.
 *   Independent provisioning of certain secrets.
 *   A combination of a non-removable cryptoprocessor and removable ones, for

doc/crypto/terms

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2020-2022 Arm Limited and/or its affiliates <[email protected]>
+.. SPDX-FileCopyrightText: Copyright 2020-2022, 2024 Arm Limited and/or its affiliates <[email protected]>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. term:: Algorithm
@@ -191,3 +191,21 @@
     :abbr: PQC
 
     A cryptographic scheme that relies on mathematical problems that do not have efficient algorithms for either classical or quantum computing.
+
+.. term:: Secure element
+    :abbr: SE
+
+    A hardware component or subsystem that is protected by design from unauthorized access, used to run a limited set of security services, and securely store confidential and cryptographic data.
+
+.. term:: Cryptographic accelerator
+
+    A hardware component or subsystem that provides accelerated implementation of cryptographic functionality.
+
+.. term:: Built-in key
+
+    A cryptographic key that is present in the implementation, which was not created by the application.
+    For example:
+
+    *   An immutable system or platform key.
+    *   A key derived from from a system secret.
+    *   A key provisioned by another component in the system for use by the application.