From 49c6143b17f61ce00c116d479349740507deede3 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Mon, 15 Jul 2024 16:20:03 +0100 Subject: [PATCH 01/10] crypto: provide incremental by-subsystem initialization for the library --- doc/crypto/api.db/psa/crypto.h | 10 ++ doc/crypto/api/keys/attributes.rst | 2 +- doc/crypto/api/keys/management.rst | 14 +- doc/crypto/api/library/library.rst | 183 ++++++++++++++++++++++++-- doc/crypto/api/ops/aead.rst | 24 ++-- doc/crypto/api/ops/cipher.rst | 18 +-- doc/crypto/api/ops/hash.rst | 20 +-- doc/crypto/api/ops/key-agreement.rst | 6 +- doc/crypto/api/ops/key-derivation.rst | 22 ++-- doc/crypto/api/ops/mac.rst | 16 +-- doc/crypto/api/ops/pk-encryption.rst | 4 +- doc/crypto/api/ops/rng.rst | 2 +- doc/crypto/api/ops/signature.rst | 8 +- doc/crypto/appendix/history.rst | 2 + 14 files changed, 253 insertions(+), 78 deletions(-) diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index bd6ba5e5..1dbe6d68 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/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, diff --git a/doc/crypto/api/keys/attributes.rst b/doc/crypto/api/keys/attributes.rst index 63691dc5..5745ffed 100644 --- a/doc/crypto/api/keys/attributes.rst +++ b/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. diff --git a/doc/crypto/api/keys/management.rst b/doc/crypto/api/keys/management.rst index 202230e7..b728ebf1 100644 --- a/doc/crypto/api/keys/management.rst +++ b/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``. @@ -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. diff --git a/doc/crypto/api/library/library.rst b/doc/crypto/api/library/library.rst index 2d734f67..4d403af4 100644 --- a/doc/crypto/api/library/library.rst +++ b/doc/crypto/api/library/library.rst @@ -40,6 +40,37 @@ API version Library initialization ---------------------- +It is recommended that applications initialize the |API| implementation, before calling any other function, except as otherwise indicated. +This is typically achieved by calling `psa_crypto_init()`. + +Some implementations provide the ability to selectively initialize a subset of the functionality, using calls to `psa_crypto_init_subsystem()`. +For example, this permits use cases such as early-stage bootloaders, that need to decrypt or authenticate firmware, where it is unnecessary to wait for an RNG to collect enough entropy. +In these implementations, calling `psa_crypto_init()` is equivalent to calling `psa_crypto_init_subsystem()` for all available subsystems. + +Applications are permitted to call these functions more than once. +Once a subsystem is successfully initialized, subsequent calls to initialize the same subsystem are guaranteed to succeed. + +If the application calls any function that returns a :code:`psa_status_t` result code before initializing the related subsystems, the following will occur: + +* If initialization of the library is essential for secure operation of the function, the implementation must return :code:`PSA_ERROR_BAD_STATE` or other appropriate error. + +* If failure to initialize the library does not compromise the security of the function, the implementation must either provide the expected result for the function, or return :code:`PSA_ERROR_BAD_STATE` or other appropriate error. + +.. note:: + + The following scenarios are examples where an implementation can require that the library has been initialized: + + * A client-server implementation, in which `psa_crypto_init()`, or :code:`psa_crypto_init_subsystem(PSA_CRYPTO_SUBSYSTEM_COMMUNICATION)`, establishes the communication with the server. + No key management or cryptographic operation can be performed until this is done. + + * An implementation in which `psa_crypto_init()`, or :code:`psa_crypto_init_subsystem(PSA_CRYPTO_SUBSYSTEM_RANDOM)`, initializes the random bit generator, and no operations that require the RNG can be performed until this is done. + For example, random data, key, IV, or nonce generation; randomized signature or encryption; and algorithms that are implemented with blinding. + +.. warning:: + + The set of functions that depend on successful initialization of specific subsystems, is :scterm:`IMPLEMENTATION DEFINED`. + Applications that rely on calling functions before initializing the library might not be portable to other implementations. + .. function:: psa_crypto_init .. summary:: @@ -52,24 +83,156 @@ Library initialization .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED .. retval:: PSA_ERROR_INSUFFICIENT_ENTROPY + .. retval:: PSA_ERROR_INSUFFICIENT_STORAGE + .. retval:: PSA_ERROR_HARDWARE_FAILURE + .. retval:: PSA_ERROR_STORAGE_FAILURE + .. retval:: PSA_ERROR_DATA_INVALID + .. retval:: PSA_ERROR_DATA_CORRUPT - It is recommended that applications call this function before calling any other function in this module. + It is recommended that applications call this function before calling any other function in this module, except as otherwise indicated. Applications are permitted to call this function more than once. Once a call succeeds, subsequent calls are guaranteed to succeed. - If the application calls any function that returns a :code:`psa_status_t` result code before calling `psa_crypto_init()`, the following will occur: + For finer control over initialization, see `psa_crypto_init_subsystem()`. - * If initialization of the library is essential for secure operation of the function, the implementation must return :code:`PSA_ERROR_BAD_STATE` or other appropriate error. + See also :secref:`library-init`. - * If failure to initialize the library does not compromise the security of the function, the implementation must either provide the expected result for the function, or return :code:`PSA_ERROR_BAD_STATE` or other appropriate error. +.. typedef:: uint32_t psa_crypto_subsystem_t - .. note:: + .. summary:: + Encoding of a subsystem of the |API| implementation. + + This type is used to specify implementation subsystems in a call to `psa_crypto_init_subsystem()`. + Values of this type are ``PSA_CRYPTO_SUBSYSTEM_xxx`` constants, or a bitwise-or of two or more of them. + + .. admonition:: Implementation note + + An implementation can define additional subsystem identifier values for use with `psa_crypto_init_subsystem()`. + +.. macro:: PSA_CRYPTO_SUBSYSTEM_COMMUNICATION + :definition: /* implementation-defined value */ + + .. summary:: + Crypto subsystem identifier for the 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, initializing 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 has no effect, and always succeeds. + +.. macro:: PSA_CRYPTO_SUBSYSTEM_KEYS + :definition: /* implementation-defined value */ + + .. summary:: + Crypto subsystem identifier for the key store in memory. + + Initializing this subsystem allows creating, accessing and destroying volatile keys in the default location, that is, 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`. - The following scenarios are examples where an implementation can require that the library has been initialized by calling `psa_crypto_init()`: - * A client-server implementation, in which `psa_crypto_init()` establishes the communication with the server. No key management or cryptographic operation can be performed until this is done. +.. macro:: PSA_CRYPTO_SUBSYSTEM_STORAGE + :definition: /* implementation-defined value */ + + .. summary:: + Crypto subsystem identifier for access to keys in storage. - * An implementation in which `psa_crypto_init()` initializes the random bit generator, and no operations that require the RNG can be performed until this is done. For example, random data, key, IV, or nonce generation; randomized signature or encryption; and algorithms that are implemented with blinding. + Initializing this subsystem and the `PSA_CRYPTO_SUBSYSTEM_KEYS` subsystem allows creating, accessing, and destroying persistent keys. + + Persistent keys in secure elements also require `PSA_CRYPTO_SUBSYSTEM_SECURE_ELEMENTS`. + +.. macro:: PSA_CRYPTO_SUBSYSTEM_ACCELERATORS + :definition: /* implementation-defined value */ + + .. summary:: + Crypto subsystem identifier for accelerator drivers. + + Initializing this subsystem results in initialization of all registered accelerator drivers. + + Initializing this subsystem allows cryptographic operations that are implemented via an accelerator driver. + +.. macro:: PSA_CRYPTO_SUBSYSTEM_SECURE_ELEMENTS + :definition: /* implementation-defined value */ + + .. summary:: + Crypto subsystem identifier for secure element drivers. + + Initializing this subsystem results in initialization 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. That is, keys whose location is not `PSA_KEY_LOCATION_LOCAL_STORAGE`. + +.. macro:: PSA_CRYPTO_SUBSYSTEM_RANDOM + :definition: /* implementation-defined value */ + + .. 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 is necessary for `psa_generate_random()`, `psa_generate_key()`, and some operations using private or secret keys. + + It is guaranteed that the following operations do not to require this subsystem: + + * Hash operations. + * Signature verification operations. + + Is it :scterm:`implementation defined` whether other operations require the initialization of this subsystem. + +.. macro:: PSA_CRYPTO_SUBSYSTEM_BUILTIN_KEYS + :definition: /* implementation-defined value */ + + .. summary:: + Crypto subsystem identifier for access to built-in keys. + + Initializing this subsystem as well as `PSA_CRYPTO_SUBSYSTEM_KEYS` allows access to built-in keys. + +.. macro:: PSA_CRYPTO_ALL_SUBSYSTEMS + :definition: /* implementation-defined value */ + + .. summary:: + Crypto subsystem identifier for all available subsystems. + + Using this value in a call to `psa_crypto_init_subsystem()` is equivalent to calling `psa_crypto_init()`. + +.. function:: psa_crypto_init_subsystem + + .. summary:: + Partial library initialization. + + .. param:: psa_crypto_subsystem_t subsystem + The subsystem, or set of subsystems, to initialize. + This must be one of the ``PSA_CRYPTO_SUBSYSTEM_xxx`` values, one of the implementation-specific subsystem values, or a bitwise-or of them. + + .. return:: psa_status_t + .. retval:: PSA_SUCCESS + Success. + .. retval:: PSA_ERROR_INVALID_ARGUMENT + ``subsystem`` is not a bitwise-or of one or more of the crypto subsystem identifier values. + These values can be defined in this specification or by the implementation. + .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + .. retval:: PSA_ERROR_COMMUNICATION_FAILURE + .. retval:: PSA_ERROR_CORRUPTION_DETECTED + .. retval:: PSA_ERROR_INSUFFICIENT_ENTROPY + .. retval:: PSA_ERROR_INSUFFICIENT_STORAGE + .. retval:: PSA_ERROR_HARDWARE_FAILURE + .. retval:: PSA_ERROR_STORAGE_FAILURE + .. retval:: PSA_ERROR_DATA_INVALID + .. retval:: PSA_ERROR_DATA_CORRUPT + + 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_subsystem()` with for a subsystem that is not used by the implementation must have no effect, and return :code:`PSA_SUCCESS`. + In effect, this is indicating that there is no further initialization required for this subsystem. + + Calling `psa_crypto_init()` is equivalent to calling :code:`psa_crypto_init_subsystem(PSA_CRYPTO_ALL_SUBSYSTEMS)`. + + See also :secref:`library-init`. + + .. note:: - .. warning:: - The set of functions that depend on successful initialization of the library is :scterm:`IMPLEMENTATION DEFINED`. Applications that rely on calling functions before initializing the library might not be portable to other implementations. + Multiple subsystems can be initialized in the same call by passing a bitwise-or of ``PSA_CRYPTO_SUBSYSTEM_xxx`` values. + If the initialization of one subsystem fails, it is unspecified whether other requested subsystems are initialized or not. diff --git a/doc/crypto/api/ops/aead.rst b/doc/crypto/api/ops/aead.rst index aad15a21..a6308295 100644 --- a/doc/crypto/api/ops/aead.rst +++ b/doc/crypto/api/ops/aead.rst @@ -289,7 +289,7 @@ Single-part AEAD functions .. 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`. .. function:: psa_aead_decrypt @@ -357,7 +357,7 @@ Single-part AEAD functions .. 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`. Multi-part AEAD operations -------------------------- @@ -448,7 +448,7 @@ Multi-part AEAD operations The following conditions can result in this error: * The operation state is not valid: it must be inactive. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_HANDLE ``key`` is not a valid key identifier. .. retval:: PSA_ERROR_NOT_PERMITTED @@ -512,7 +512,7 @@ Multi-part AEAD operations The following conditions can result in this error: * The operation state is not valid: it must be inactive. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_HANDLE ``key`` is not a valid key identifier. .. retval:: PSA_ERROR_NOT_PERMITTED @@ -575,7 +575,7 @@ Multi-part AEAD operations The following conditions can result in this error: * The operation state is not valid: it must be active, and `psa_aead_set_nonce()` and `psa_aead_generate_nonce()` must not have been called yet. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_ARGUMENT ``ad_length`` or ``plaintext_length`` are too large for the chosen algorithm. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -618,7 +618,7 @@ Multi-part AEAD operations * The operation state is not valid: it must be an active AEAD encryption operation, with no nonce set. * The operation state is not valid: this is an algorithm which requires `psa_aead_set_lengths()` to be called before setting the nonce. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_BUFFER_TOO_SMALL The size of the ``nonce`` buffer is too small. `PSA_AEAD_NONCE_LENGTH()` or `PSA_AEAD_NONCE_MAX_SIZE` can be used to determine a sufficient buffer size. .. retval:: PSA_ERROR_INSUFFICIENT_ENTROPY @@ -657,7 +657,7 @@ Multi-part AEAD operations * The operation state is not valid: it must be active, with no nonce set. * The operation state is not valid: this is an algorithm which requires `psa_aead_set_lengths()` to be called before setting the nonce. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_ARGUMENT ``nonce_length`` is not valid for the chosen algorithm. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -703,7 +703,7 @@ Multi-part AEAD operations The following conditions can result in this error: * The operation state is not valid: it must be active, have a nonce set, have lengths set if required by the algorithm, and `psa_aead_update()` must not have been called yet. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_ARGUMENT Excess additional data: the total input length to `psa_aead_update_ad()` is greater than the additional data length that was previously specified with `psa_aead_set_lengths()`, or is too large for the chosen AEAD algorithm. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -762,7 +762,7 @@ Multi-part AEAD operations The following conditions can result in this error: * The operation state is not valid: it must be active, have a nonce set, and have lengths set if required by the algorithm. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_BUFFER_TOO_SMALL The size of the ``output`` buffer is too small. `PSA_AEAD_UPDATE_OUTPUT_SIZE()` or `PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE()` can be used to determine a sufficient buffer size. .. retval:: PSA_ERROR_INVALID_ARGUMENT @@ -828,7 +828,7 @@ Multi-part AEAD operations The following conditions can result in this error: * The operation state is not valid: it must be an active encryption operation with a nonce set. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_BUFFER_TOO_SMALL The size of the ``ciphertext`` or ``tag`` buffer is too small. `PSA_AEAD_FINISH_OUTPUT_SIZE()` or `PSA_AEAD_FINISH_OUTPUT_MAX_SIZE` can be used to determine the required ``ciphertext`` buffer size. @@ -888,7 +888,7 @@ Multi-part AEAD operations The following conditions can result in this error: * The operation state is not valid: it must be an active decryption operation with a nonce set. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_BUFFER_TOO_SMALL The size of the ``plaintext`` buffer is too small. `PSA_AEAD_VERIFY_OUTPUT_SIZE()` or `PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE` can be used to determine a sufficient buffer size. .. retval:: PSA_ERROR_INVALID_ARGUMENT @@ -934,7 +934,7 @@ Multi-part AEAD operations .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. 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`. Aborting an operation frees all associated resources except for the ``operation`` object itself. Once aborted, the operation object can be reused for another operation by calling `psa_aead_encrypt_setup()` or `psa_aead_decrypt_setup()` again. diff --git a/doc/crypto/api/ops/cipher.rst b/doc/crypto/api/ops/cipher.rst index 32232473..1477ac4e 100644 --- a/doc/crypto/api/ops/cipher.rst +++ b/doc/crypto/api/ops/cipher.rst @@ -398,7 +398,7 @@ Single-part cipher functions .. 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 encrypts a message with a random initialization vector (IV). The length of the IV is :code:`PSA_CIPHER_IV_LENGTH(key_type, alg)` where ``key_type`` is the type of ``key``. @@ -462,7 +462,7 @@ Single-part cipher functions .. 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`. This function decrypts a message encrypted with a symmetric cipher. @@ -561,7 +561,7 @@ Multi-part cipher operations The following conditions can result in this error: * The operation state is not valid: it must be inactive. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing, see :secref:`library-init`. The sequence of operations to encrypt a message with a symmetric cipher is as follows: @@ -623,7 +623,7 @@ Multi-part cipher operations The following conditions can result in this error: * The operation state is not valid: it must be inactive. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing, see :secref:`library-init`. The sequence of operations to decrypt a message with a symmetric cipher is as follows: @@ -668,7 +668,7 @@ Multi-part cipher operations * The cipher algorithm does not use an IV. * The operation state is not valid: it must be active, with no IV set. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing, see :secref:`library-init`. .. retval:: PSA_ERROR_BUFFER_TOO_SMALL The size of the ``iv`` buffer is too small. `PSA_CIPHER_IV_LENGTH()` or `PSA_CIPHER_IV_MAX_SIZE` can be used to determine a sufficient buffer size. .. retval:: PSA_ERROR_INSUFFICIENT_ENTROPY @@ -709,7 +709,7 @@ Multi-part cipher operations * The cipher algorithm does not use an IV. * The operation state is not valid: it must be an active cipher encrypt operation, with no IV set. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing, see :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error: @@ -765,7 +765,7 @@ Multi-part cipher operations The following conditions can result in this error: * The operation state is not valid: it must be active, with an IV set if required for the algorithm. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing, see :secref:`library-init`. .. retval:: PSA_ERROR_BUFFER_TOO_SMALL The size of the ``output`` buffer is too small. `PSA_CIPHER_UPDATE_OUTPUT_SIZE()` or `PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE()` can be used to determine a sufficient buffer size. .. retval:: PSA_ERROR_INVALID_ARGUMENT @@ -820,7 +820,7 @@ Multi-part cipher operations The following conditions can result in this error: * The operation state is not valid: it must be active, with an IV set if required for the algorithm. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing, see :secref:`library-init`. .. retval:: PSA_ERROR_BUFFER_TOO_SMALL The size of the ``output`` buffer is too small. `PSA_CIPHER_FINISH_OUTPUT_SIZE()` or `PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE` can be used to determine a sufficient buffer size. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY @@ -851,7 +851,7 @@ Multi-part cipher operations .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. 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`. Aborting an operation frees all associated resources except for the ``operation`` object itself. Once aborted, the operation object can be reused for another operation by calling `psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()` again. diff --git a/doc/crypto/api/ops/hash.rst b/doc/crypto/api/ops/hash.rst index abd63d28..b8d82403 100644 --- a/doc/crypto/api/ops/hash.rst +++ b/doc/crypto/api/ops/hash.rst @@ -246,7 +246,7 @@ Single-part hashing functions .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. 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`. .. note:: To verify the hash of a message against an expected value, use `psa_hash_compare()` instead. @@ -287,7 +287,7 @@ Single-part hashing functions .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. 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`. .. _hash-mp: @@ -363,7 +363,7 @@ Multi-part hashing operations The following conditions can result in this error: * The operation state is not valid: it must be inactive. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED @@ -406,7 +406,7 @@ Multi-part hashing operations The following conditions can result in this error: * The operation state is not valid: it must be active. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_ARGUMENT The total input for the operation is too large for the hash algorithm. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -441,7 +441,7 @@ Multi-part hashing operations The following conditions can result in this error: * The operation state is not valid: it must be active. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_BUFFER_TOO_SMALL The size of the ``hash`` buffer is too small. `PSA_HASH_LENGTH()` can be used to determine a sufficient buffer size. @@ -480,7 +480,7 @@ Multi-part hashing operations The following conditions can result in this error: * The operation state is not valid: it must be active. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED @@ -507,7 +507,7 @@ Multi-part hashing operations .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. 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`. Aborting an operation frees all associated resources except for the ``operation`` object itself. Once aborted, the operation object can be reused for another operation by calling `psa_hash_setup()` again. @@ -542,7 +542,7 @@ Multi-part hashing operations The following conditions can result in this error: * The operation state is not valid: it must be active. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_BUFFER_TOO_SMALL The size of the ``hash_state`` buffer is too small. `PSA_HASH_SUSPEND_OUTPUT_SIZE()` or `PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE` can be used to determine a sufficient buffer size. @@ -608,7 +608,7 @@ Multi-part hashing operations The following conditions can result in this error: * The operation state is not valid: it must be inactive. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED @@ -639,7 +639,7 @@ Multi-part hashing operations * The ``source_operation`` state is not valid: it must be active. * The ``target_operation`` state is not valid: it must be inactive. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY diff --git a/doc/crypto/api/ops/key-agreement.rst b/doc/crypto/api/ops/key-agreement.rst index 9f9e2e95..01cb8b05 100644 --- a/doc/crypto/api/ops/key-agreement.rst +++ b/doc/crypto/api/ops/key-agreement.rst @@ -214,7 +214,7 @@ Standalone key agreement .. retval:: PSA_ERROR_DATA_INVALID .. retval:: PSA_ERROR_INSUFFICIENT_STORAGE .. retval:: PSA_ERROR_BAD_STATE - The library requires initializing by a call to `psa_crypto_init()`. + The library requires initializing. See :secref:`library-init`. A key-agreement algorithm takes two inputs: a private key ``private_key``, and a public key ``peer_key``. The result of this function is a shared secret, returned as a derivation key. @@ -283,7 +283,7 @@ Standalone key agreement .. 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`. A key-agreement algorithm takes two inputs: a private key ``private_key``, and a public key ``peer_key``. The result of this function is a shared secret, returned in the ``output`` buffer. @@ -321,7 +321,7 @@ Combining key agreement and key derivation The following conditions can result in this error: * The operation state is not valid for this key-agreement ``step``. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_HANDLE ``private_key`` is not a valid key identifier. .. retval:: PSA_ERROR_NOT_PERMITTED diff --git a/doc/crypto/api/ops/key-derivation.rst b/doc/crypto/api/ops/key-derivation.rst index 10ef1d45..abe00d2b 100644 --- a/doc/crypto/api/ops/key-derivation.rst +++ b/doc/crypto/api/ops/key-derivation.rst @@ -588,7 +588,7 @@ Key-derivation functions The following conditions can result in this error: * The operation state is not valid: it must be inactive. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. A key-derivation algorithm takes some inputs and uses them to generate a byte stream in a deterministic way. This byte stream can be used to produce keys and other cryptographic material. @@ -631,7 +631,7 @@ Key-derivation functions The following conditions can result in this error: * The operation state is not valid: it must be active. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_CORRUPTION_DETECTED The capacity of a key derivation is the maximum number of bytes that it can return. Reading :math:`N` bytes of output from a key-derivation operation reduces its capacity by at least :math:`N`. The capacity can be reduced by more than :math:`N` in the following situations: @@ -658,7 +658,7 @@ Key-derivation functions The following conditions can result in this error: * The operation state is not valid: it must be active. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED @@ -706,7 +706,7 @@ Key-derivation functions The following conditions can result in this error: * The operation state is not valid for this input ``step``. This can happen if the application provides a step out of order or repeats a step that may not be repeated. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key-derivation or key-agreement algorithm for information. @@ -752,7 +752,7 @@ Key-derivation functions The following conditions can result in this error: * The operation state is not valid for this input ``step``. This can happen if the application provides a step out of order or repeats a step that may not be repeated. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. Which inputs are required and in what order depends on the algorithm. However, when an algorithm requires a particular order, numeric inputs usually come first as they tend to be configuration parameters. @@ -804,7 +804,7 @@ Key-derivation functions The following conditions can result in this error: * The operation state is not valid for this input ``step``. This can happen if the application provides a step out of order or repeats a step that may not be repeated. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key-derivation or key-agreement algorithm for information. @@ -849,7 +849,7 @@ Key-derivation functions The following conditions can result in this error: * The operation state is not valid: it must be active, with all required input steps complete. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED @@ -935,7 +935,7 @@ Key-derivation functions The following conditions can result in this error: * The operation state is not valid: it must be active, with all required input steps complete. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY .. retval:: PSA_ERROR_INSUFFICIENT_STORAGE .. retval:: PSA_ERROR_COMMUNICATION_FAILURE @@ -1097,7 +1097,7 @@ Key-derivation functions The following conditions can result in this error: * The operation state is not valid: it must be active, with all required input steps complete. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. This function calculates output bytes from a key-derivation algorithm and compares those bytes to an expected value. If the key derivation's output is viewed as a stream of bytes, this function destructively reads ``output_length`` bytes from the stream before comparing them with ``expected_output``. @@ -1165,7 +1165,7 @@ Key-derivation functions The following conditions can result in this error: * The operation state is not valid: it must be active, with all required input steps complete. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. This function calculates output bytes from a key-derivation algorithm and compares those bytes to an expected value, provided as key of type `PSA_KEY_TYPE_PASSWORD_HASH`. If the key derivation's output is viewed as a stream of bytes, this function destructively reads the number of bytes corresponding to the length of the ``expected`` key from the stream before comparing them with the key value. @@ -1198,7 +1198,7 @@ Key-derivation functions .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. 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`. Aborting an operation frees all associated resources except for the ``operation`` object itself. Once aborted, the operation object can be reused for another operation by calling `psa_key_derivation_setup()` again. diff --git a/doc/crypto/api/ops/mac.rst b/doc/crypto/api/ops/mac.rst index dfce9285..91ee7d6f 100644 --- a/doc/crypto/api/ops/mac.rst +++ b/doc/crypto/api/ops/mac.rst @@ -229,7 +229,7 @@ Single-part MAC functions .. 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`. .. note:: To verify the MAC of a message against an expected value, use `psa_mac_verify()` instead. Beware that comparing integrity or authenticity data such as MAC values with a function such as ``memcmp()`` is risky because the time taken by the comparison might leak information about the MAC value which could allow an attacker to guess a valid MAC and thereby bypass security controls. @@ -282,7 +282,7 @@ Single-part MAC functions .. 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`. Multi-part MAC operations ------------------------- @@ -375,7 +375,7 @@ Multi-part MAC operations The following conditions can result in this error: * The operation state is not valid: it must be inactive. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. This function sets up the calculation of the message authentication code (MAC) of a byte string. To verify the MAC of a message against an expected value, use `psa_mac_verify_setup()` instead. @@ -438,7 +438,7 @@ Multi-part MAC operations The following conditions can result in this error: * The operation state is not valid: it must be inactive. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. This function sets up the verification of the message authentication code (MAC) of a byte string against an expected value. @@ -480,7 +480,7 @@ Multi-part MAC operations The following conditions can result in this error: * The operation state is not valid: it must be active. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_ARGUMENT The total input for the operation is too large for the MAC algorithm. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -524,7 +524,7 @@ Multi-part MAC operations The following conditions can result in this error: * The operation state is not valid: it must be an active mac sign operation. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_BUFFER_TOO_SMALL The size of the ``mac`` buffer is too small. `PSA_MAC_LENGTH()` or `PSA_MAC_MAX_SIZE` can be used to determine a sufficient buffer size. @@ -566,7 +566,7 @@ Multi-part MAC operations The following conditions can result in this error: * The operation state is not valid: it must be an active mac verify operation. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED @@ -596,7 +596,7 @@ Multi-part MAC operations .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. 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`. Aborting an operation frees all associated resources except for the ``operation`` object itself. Once aborted, the operation object can be reused for another operation by calling `psa_mac_sign_setup()` or `psa_mac_verify_setup()` again. diff --git a/doc/crypto/api/ops/pk-encryption.rst b/doc/crypto/api/ops/pk-encryption.rst index a2871213..1cb986c3 100644 --- a/doc/crypto/api/ops/pk-encryption.rst +++ b/doc/crypto/api/ops/pk-encryption.rst @@ -118,7 +118,7 @@ Asymmetric encryption functions .. retval:: PSA_ERROR_DATA_INVALID .. retval:: PSA_ERROR_INSUFFICIENT_ENTROPY .. 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 `PSA_ALG_RSA_PKCS1V15_CRYPT`, no salt is supported. @@ -186,7 +186,7 @@ Asymmetric encryption functions .. retval:: PSA_ERROR_INVALID_PADDING The algorithm uses padding, and the input does not contain valid padding. .. 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 `PSA_ALG_RSA_PKCS1V15_CRYPT`, no salt is supported. diff --git a/doc/crypto/api/ops/rng.rst b/doc/crypto/api/ops/rng.rst index c2f6dfe9..00c7d569 100644 --- a/doc/crypto/api/ops/rng.rst +++ b/doc/crypto/api/ops/rng.rst @@ -32,7 +32,7 @@ Random number generation .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. 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`. .. warning:: This function **can** fail! Callers MUST check the return status and MUST NOT use the content of the output buffer if the return status is not :code:`PSA_SUCCESS`. diff --git a/doc/crypto/api/ops/signature.rst b/doc/crypto/api/ops/signature.rst index 4a74d74d..ed5870b9 100644 --- a/doc/crypto/api/ops/signature.rst +++ b/doc/crypto/api/ops/signature.rst @@ -624,7 +624,7 @@ Asymmetric signature functions .. retval:: PSA_ERROR_DATA_INVALID .. retval:: PSA_ERROR_INSUFFICIENT_ENTROPY .. retval:: PSA_ERROR_BAD_STATE - The library requires initializing by a call to `psa_crypto_init()`. + The library requires initializing. See :secref:`library-init`. .. note:: To perform a multi-part hash-and-sign signature algorithm, first use a :ref:`multi-part hash operation ` and then pass the resulting hash to `psa_sign_hash()`. :code:`PSA_ALG_GET_HASH(alg)` can be used to determine the hash algorithm to use. @@ -676,7 +676,7 @@ Asymmetric signature functions .. 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`. .. note:: To perform a multi-part hash-and-sign signature verification algorithm, first use a :ref:`multi-part hash operation ` to hash the message and then pass the resulting hash to `psa_verify_hash()`. :code:`PSA_ALG_GET_HASH(alg)` can be used to determine the hash algorithm to use. @@ -739,7 +739,7 @@ Asymmetric signature functions .. retval:: PSA_ERROR_DATA_INVALID .. retval:: PSA_ERROR_INSUFFICIENT_ENTROPY .. 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 hash-and-sign signature algorithms, the ``hash`` input to this function is the hash of the message to sign. The algorithm used to calculate this hash is encoded in the signature algorithm. For such algorithms, ``hash_length`` must equal the length of the hash output: :code:`hash_length == PSA_HASH_LENGTH(PSA_ALG_GET_HASH(alg))`. @@ -794,7 +794,7 @@ Asymmetric signature functions .. 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`. For hash-and-sign signature algorithms, the ``hash`` input to this function is the hash of the message to verify. The algorithm used to calculate this hash is encoded in the signature algorithm. For such algorithms, ``hash_length`` must equal the length of the hash output: :code:`hash_length == PSA_HASH_LENGTH(PSA_ALG_GET_HASH(alg))`. diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index 187b0747..a5e8fd26 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -33,6 +33,8 @@ Changes to the API See :secref:`asymmetric-key-encoding` and :secref:`appendix-specdef-key-values`. +* Added support for partial initialization of the implementation. See :secref:`library-init`. + * Added key-encapsulation functions, `psa_encapsulate()` and `psa_decapsulate()`. - Added `PSA_ALG_ECIES_SEC1` as a key-encapsulation algorithm that implements the key agreement steps of ECIES. From 1c01959318173b284973b6c119b8d953be225f95 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Mon, 4 Nov 2024 19:24:53 +0000 Subject: [PATCH 02/10] Update description for BAD_STATE errors in additional APIs --- doc/crypto/api/keys/management.rst | 2 +- doc/crypto/api/ops/key-derivation.rst | 2 +- doc/crypto/api/ops/key-encapsulation.rst | 4 ++-- doc/crypto/api/ops/pake.rst | 18 +++++++++--------- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/doc/crypto/api/keys/management.rst b/doc/crypto/api/keys/management.rst index b728ebf1..6b2968ff 100644 --- a/doc/crypto/api/keys/management.rst +++ b/doc/crypto/api/keys/management.rst @@ -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. diff --git a/doc/crypto/api/ops/key-derivation.rst b/doc/crypto/api/ops/key-derivation.rst index abe00d2b..0098d380 100644 --- a/doc/crypto/api/ops/key-derivation.rst +++ b/doc/crypto/api/ops/key-derivation.rst @@ -1048,7 +1048,7 @@ Key-derivation functions The following conditions can result in this error: * The operation state is not valid: it must be active, with all required input steps complete. - * The library requires initializing by a call to `psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY .. retval:: PSA_ERROR_INSUFFICIENT_STORAGE .. retval:: PSA_ERROR_COMMUNICATION_FAILURE diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index 46bf821b..608a27d4 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -210,7 +210,7 @@ Key-encapsulation functions .. 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 ``output_key`` location, policy, and type are taken from ``attributes``. @@ -325,7 +325,7 @@ Key-encapsulation functions .. 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 ``output_key`` location, policy, and type are taken from ``attributes``. diff --git a/doc/crypto/api/ops/pake.rst b/doc/crypto/api/ops/pake.rst index 950ca9e5..89a4e550 100644 --- a/doc/crypto/api/ops/pake.rst +++ b/doc/crypto/api/ops/pake.rst @@ -716,7 +716,7 @@ Multi-part PAKE operations The following conditions can result in this error: * The operation state is not valid: it must be inactive. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_HANDLE ``password_key`` is not a valid key identifier. .. retval:: PSA_ERROR_NOT_PERMITTED @@ -793,7 +793,7 @@ Multi-part PAKE operations The following conditions can result in this error: * The operation state is not valid: it must be active, and `psa_pake_set_role()`, `psa_pake_input()`, and `psa_pake_output()` must not have been called yet. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error: @@ -836,7 +836,7 @@ Multi-part PAKE operations The following conditions can result in this error: * The operation state is not valid: it must be active, and `psa_pake_set_user()`, `psa_pake_input()`, and `psa_pake_output()` must not have been called yet. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_ARGUMENT ``user_id`` is not valid for the operation's algorithm and cipher suite. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -873,7 +873,7 @@ Multi-part PAKE operations * The operation state is not valid: it must be active, and `psa_pake_set_peer()`, `psa_pake_input()`, and `psa_pake_output()` must not have been called yet. * Calling `psa_pake_set_peer()` is invalid with the operation's algorithm. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_ARGUMENT ``peer_id`` is not valid for the operation's algorithm and cipher suite. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -910,7 +910,7 @@ Multi-part PAKE operations * The operation state is not valid: it must be active, and `psa_pake_set_context()`, `psa_pake_input()`, and `psa_pake_output()` must not have been called yet. * Calling `psa_pake_set_context()` is invalid with the operation's algorithm. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_ARGUMENT ``context`` is not valid for the operation's algorithm and cipher suite. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -955,7 +955,7 @@ Multi-part PAKE operations The following conditions can result in this error: * The operation state is not valid: it must be active and fully set up, and this call must conform to the algorithm's requirements for ordering of input and output steps. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_ARGUMENT ``step`` is not compatible with the operation's algorithm. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -1002,7 +1002,7 @@ Multi-part PAKE operations The following conditions can result in this error: * The operation state is not valid: it must be active and fully set up, and this call must conform to the algorithm's requirements for ordering of input and output steps. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error: @@ -1083,7 +1083,7 @@ Multi-part PAKE operations For an unconfirmed key, this will be when the key-exchange output and input steps are complete, but prior to any key-confirmation output and input steps. For a confirmed key, this will be when all key-exchange and key-confirmation output and input steps are complete. - * The library requires initializing by a call to :code:`psa_crypto_init()`. + * The library requires initializing. See :secref:`library-init`. .. retval:: PSA_ERROR_ALREADY_EXISTS This is an attempt to create a persistent key, and there is already a persistent key with the given identifier. .. retval:: PSA_ERROR_NOT_SUPPORTED @@ -1169,7 +1169,7 @@ Multi-part PAKE operations .. retval:: PSA_ERROR_COMMUNICATION_FAILURE .. retval:: PSA_ERROR_CORRUPTION_DETECTED .. retval:: PSA_ERROR_BAD_STATE - The library requires initializing by a call to :code:`psa_crypto_init()`. + The library requires initializing. See :secref:`library-init`. Aborting an operation frees all associated resources except for the ``operation`` object itself. Once aborted, the operation object can be reused for another operation by calling `psa_pake_setup()` again. From 3b97bd00cd665f391467a697ea648011b49cdc69 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Mon, 4 Nov 2024 19:58:15 +0000 Subject: [PATCH 03/10] Expand uses of RNG --- doc/crypto/api/library/library.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/crypto/api/library/library.rst b/doc/crypto/api/library/library.rst index 4d403af4..8c35b9c3 100644 --- a/doc/crypto/api/library/library.rst +++ b/doc/crypto/api/library/library.rst @@ -44,7 +44,7 @@ It is recommended that applications initialize the |API| implementation, before This is typically achieved by calling `psa_crypto_init()`. Some implementations provide the ability to selectively initialize a subset of the functionality, using calls to `psa_crypto_init_subsystem()`. -For example, this permits use cases such as early-stage bootloaders, that need to decrypt or authenticate firmware, where it is unnecessary to wait for an RNG to collect enough entropy. +For example, this permits use cases such as early-stage bootloaders, that need to decrypt or authenticate firmware, where it is unnecessary to wait for a random bit generator to collect enough entropy. In these implementations, calling `psa_crypto_init()` is equivalent to calling `psa_crypto_init_subsystem()` for all available subsystems. Applications are permitted to call these functions more than once. @@ -63,8 +63,9 @@ If the application calls any function that returns a :code:`psa_status_t` result * A client-server implementation, in which `psa_crypto_init()`, or :code:`psa_crypto_init_subsystem(PSA_CRYPTO_SUBSYSTEM_COMMUNICATION)`, establishes the communication with the server. No key management or cryptographic operation can be performed until this is done. - * An implementation in which `psa_crypto_init()`, or :code:`psa_crypto_init_subsystem(PSA_CRYPTO_SUBSYSTEM_RANDOM)`, initializes the random bit generator, and no operations that require the RNG can be performed until this is done. - For example, random data, key, IV, or nonce generation; randomized signature or encryption; and algorithms that are implemented with blinding. + * An implementation in which `psa_crypto_init()`, or :code:`psa_crypto_init_subsystem(PSA_CRYPTO_SUBSYSTEM_RANDOM)`, initializes the random bit generator. + No operations that require output from the random bit generator can be performed until this is done. + For example, random data, key, IV, or nonce generation; randomized signature or encryption; key encapsulation; password-authenticated key exchange; and algorithms that are implemented with blinding. .. warning:: From 0f2959c7255e07cd66c597f08b630a10a17a4cd9 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Mon, 4 Nov 2024 19:58:52 +0000 Subject: [PATCH 04/10] Deinitialization is not a thing for the specification --- doc/crypto/api/library/library.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/crypto/api/library/library.rst b/doc/crypto/api/library/library.rst index 8c35b9c3..3de7d872 100644 --- a/doc/crypto/api/library/library.rst +++ b/doc/crypto/api/library/library.rst @@ -116,7 +116,7 @@ If the application calls any function that returns a :code:`psa_status_t` result .. summary:: Crypto subsystem identifier for the 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, initializing 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 client-server implementation, initializing this subsystem is necessary before any API function other than library initialization and functions accessing local data structures such as key attributes. In a library implementation, initializing this subsystem has no effect, and always succeeds. From 9956271eee41d09949e878b9726a8b61e2690f7f Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 5 Nov 2024 09:58:05 +0000 Subject: [PATCH 05/10] Add more operations to the description for the RANDOM subsystem initialization --- doc/crypto/api/library/library.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/crypto/api/library/library.rst b/doc/crypto/api/library/library.rst index 3de7d872..f045fd89 100644 --- a/doc/crypto/api/library/library.rst +++ b/doc/crypto/api/library/library.rst @@ -170,12 +170,15 @@ If the application calls any function that returns a :code:`psa_status_t` result 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()`, and some operations using private or secret keys. + Initializing this subsystem is necessary for `psa_generate_random()`, `psa_generate_key()`, `psa_encapsulate_key()`, PAKE operations, and some operations using key pairs. It is guaranteed that the following operations do not to require this subsystem: + * Retrieving key attributes. * Hash operations. * Signature verification operations. + * Exporting symmetric keys. + * Exporting asymmetric public keys from public-key objects. Is it :scterm:`implementation defined` whether other operations require the initialization of this subsystem. From 96fa0568e8a2df7462e5315371487e97c8d4a503 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 5 Nov 2024 16:02:48 +0000 Subject: [PATCH 06/10] Provide additional examples of crypto subsystem dependencies. --- doc/crypto/api/library/library.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/doc/crypto/api/library/library.rst b/doc/crypto/api/library/library.rst index f045fd89..e5817fb8 100644 --- a/doc/crypto/api/library/library.rst +++ b/doc/crypto/api/library/library.rst @@ -226,8 +226,15 @@ If the application calls any function that returns a :code:`psa_status_t` result 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`. + Initializing a subsystem may initialize other subsystems if the implementation 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`. + * In a system where the random bit generator is provided by a secure element, initializing `PSA_CRYPTO_SUBSYSTEM_RANDOM` can also initialize `PSA_CRYPTO_SUBSYSTEM_SECURE_ELEMENTS`. + * In a system where protected communication with a secure element requires a per-session key, initializing `PSA_CRYPTO_SUBSYSTEM_SECURE_ELEMENTS` can also initialize `PSA_CRYPTO_SUBSYSTEM_RANDOM`. + + .. warning:: + Application code that depends on the initialization dependencies of a specific implementation or system, might not be directly portable to other implementations. Calling `psa_crypto_init_subsystem()` with for a subsystem that is not used by the implementation must have no effect, and return :code:`PSA_SUCCESS`. In effect, this is indicating that there is no further initialization required for this subsystem. From 755eb0dfeaa1892858163137e27bfbc6a39e1852 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 6 Nov 2024 14:23:10 +0000 Subject: [PATCH 07/10] fixup: spell psa_encapsulate() correctly --- doc/crypto/api/library/library.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/crypto/api/library/library.rst b/doc/crypto/api/library/library.rst index e5817fb8..63176018 100644 --- a/doc/crypto/api/library/library.rst +++ b/doc/crypto/api/library/library.rst @@ -170,7 +170,7 @@ If the application calls any function that returns a :code:`psa_status_t` result 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()`, `psa_encapsulate_key()`, PAKE operations, and some operations using key pairs. + Initializing this subsystem is necessary for `psa_generate_random()`, `psa_generate_key()`, `psa_encapsulate()`, PAKE operations, and some operations using key pairs. It is guaranteed that the following operations do not to require this subsystem: From 940d059d3aec85ab82e6810693fd82a80eb864d2 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 6 Nov 2024 14:24:52 +0000 Subject: [PATCH 08/10] 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. --- doc/crypto/api/keys/ids.rst | 4 ++-- doc/crypto/api/keys/lifetimes.rst | 2 +- doc/crypto/api/keys/management.rst | 2 +- doc/crypto/api/keys/policy.rst | 2 +- doc/crypto/api/library/library.rst | 14 +++++++------- doc/crypto/overview/sample-arch.rst | 6 +++--- doc/crypto/terms | 20 +++++++++++++++++++- 7 files changed, 34 insertions(+), 16 deletions(-) diff --git a/doc/crypto/api/keys/ids.rst b/doc/crypto/api/keys/ids.rst index e5a586fa..92a3b49a 100644 --- a/doc/crypto/api/keys/ids.rst +++ b/doc/crypto/api/keys/ids.rst @@ -13,7 +13,7 @@ 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. @@ -21,7 +21,7 @@ Key identifiers are output from a successful call to one of the key creation fun 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 diff --git a/doc/crypto/api/keys/lifetimes.rst b/doc/crypto/api/keys/lifetimes.rst index 21bc7656..cd0859c0 100644 --- a/doc/crypto/api/keys/lifetimes.rst +++ b/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: diff --git a/doc/crypto/api/keys/management.rst b/doc/crypto/api/keys/management.rst index 6b2968ff..503a22a3 100644 --- a/doc/crypto/api/keys/management.rst +++ b/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. diff --git a/doc/crypto/api/keys/policy.rst b/doc/crypto/api/keys/policy.rst index 274acf34..f581e21f 100644 --- a/doc/crypto/api/keys/policy.rst +++ b/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. diff --git a/doc/crypto/api/library/library.rst b/doc/crypto/api/library/library.rst index 63176018..01055c6e 100644 --- a/doc/crypto/api/library/library.rst +++ b/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. diff --git a/doc/crypto/overview/sample-arch.rst b/doc/crypto/overview/sample-arch.rst index b4e843b7..63c89b38 100644 --- a/doc/crypto/overview/sample-arch.rst +++ b/doc/crypto/overview/sample-arch.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2022 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2022, 2024 Arm Limited and/or its affiliates .. 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 diff --git a/doc/crypto/terms b/doc/crypto/terms index dea51b14..4c20fc58 100644 --- a/doc/crypto/terms +++ b/doc/crypto/terms @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2020-2022 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2020-2022, 2024 Arm Limited and/or its affiliates .. 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. From 0ad77a55f2e374c28e96fa60ef2a481705df205d Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 6 Nov 2024 14:32:47 +0000 Subject: [PATCH 09/10] Add a recommendation for implementation of ALL_SUBSYSTEMS initialization --- doc/crypto/api/library/library.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/crypto/api/library/library.rst b/doc/crypto/api/library/library.rst index 01055c6e..cc8c2b1d 100644 --- a/doc/crypto/api/library/library.rst +++ b/doc/crypto/api/library/library.rst @@ -198,6 +198,11 @@ If the application calls any function that returns a :code:`psa_status_t` result Using this value in a call to `psa_crypto_init_subsystem()` is equivalent to calling `psa_crypto_init()`. + .. admonition:: Implementation note + + It is recommended that :code:`psa_crypto_init_subsystem(PSA_CRYPTO_ALL_SUBSYSTEMS)` is implemented in a way that provides compatibility with future versions of the implementation. + That is, addition of a new subsystem to an implementation does not require recompilation of the application so that this call will still initialize all subsystems. + .. function:: psa_crypto_init_subsystem .. summary:: From 0fa957c7889953c4b1339895375671aca4b79b07 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Mon, 16 Dec 2024 14:17:43 +0000 Subject: [PATCH 10/10] Add version information to the new functions --- doc/crypto/api/library/library.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/doc/crypto/api/library/library.rst b/doc/crypto/api/library/library.rst index cc8c2b1d..6185be63 100644 --- a/doc/crypto/api/library/library.rst +++ b/doc/crypto/api/library/library.rst @@ -103,6 +103,8 @@ If the application calls any function that returns a :code:`psa_status_t` result .. summary:: Encoding of a subsystem of the |API| implementation. + .. versionadded:: 1.3 + This type is used to specify implementation subsystems in a call to `psa_crypto_init_subsystem()`. Values of this type are ``PSA_CRYPTO_SUBSYSTEM_xxx`` constants, or a bitwise-or of two or more of them. @@ -116,6 +118,8 @@ If the application calls any function that returns a :code:`psa_status_t` result .. summary:: Crypto subsystem identifier for the communication with the server, if this is a client that communicates with a server where the key store is located. + .. versionadded:: 1.3 + In a client-server implementation, initializing this subsystem is necessary before any API function other than library initialization and functions accessing local data structures such as key attributes. In a library implementation, initializing this subsystem has no effect, and always succeeds. @@ -126,6 +130,8 @@ If the application calls any function that returns a :code:`psa_status_t` result .. summary:: Crypto subsystem identifier for the key store in memory. + .. versionadded:: 1.3 + Initializing this subsystem allows creating, accessing and destroying volatile keys in the default location, that is, keys with the lifetime `PSA_KEY_LIFETIME_VOLATILE`. Persistent keys also require `PSA_CRYPTO_SUBSYSTEM_STORAGE`. @@ -138,6 +144,8 @@ If the application calls any function that returns a :code:`psa_status_t` result .. summary:: Crypto subsystem identifier for access to keys in storage. + .. versionadded:: 1.3 + Initializing this subsystem and the `PSA_CRYPTO_SUBSYSTEM_KEYS` subsystem allows creating, accessing, and destroying persistent keys. Persistent keys in secure elements also require `PSA_CRYPTO_SUBSYSTEM_SECURE_ELEMENTS`. @@ -148,6 +156,8 @@ If the application calls any function that returns a :code:`psa_status_t` result .. summary:: Crypto subsystem identifier for :term:`cryptographic accelerator`\ s. + .. versionadded:: 1.3 + Initializing this subsystem results in initialization of cryptographic hardware accelerator interfaces. Initializing this subsystem allows cryptographic operations that are implemented in an accelerator. @@ -158,6 +168,8 @@ If the application calls any function that returns a :code:`psa_status_t` result .. summary:: Crypto subsystem identifier for :term:`secure element`\ s. + .. versionadded:: 1.3 + 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,6 +180,8 @@ If the application calls any function that returns a :code:`psa_status_t` result .. summary:: Crypto subsystem identifier for the random generator. + .. versionadded:: 1.3 + 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. @@ -188,6 +202,8 @@ If the application calls any function that returns a :code:`psa_status_t` result .. summary:: Crypto subsystem identifier for access to :term:`built-in key`\ s. + .. versionadded:: 1.3 + Initializing this subsystem as well as `PSA_CRYPTO_SUBSYSTEM_KEYS` allows access to built-in keys. .. macro:: PSA_CRYPTO_ALL_SUBSYSTEMS @@ -196,6 +212,8 @@ If the application calls any function that returns a :code:`psa_status_t` result .. summary:: Crypto subsystem identifier for all available subsystems. + .. versionadded:: 1.3 + Using this value in a call to `psa_crypto_init_subsystem()` is equivalent to calling `psa_crypto_init()`. .. admonition:: Implementation note @@ -208,6 +226,8 @@ If the application calls any function that returns a :code:`psa_status_t` result .. summary:: Partial library initialization. + .. versionadded:: 1.3 + .. param:: psa_crypto_subsystem_t subsystem The subsystem, or set of subsystems, to initialize. This must be one of the ``PSA_CRYPTO_SUBSYSTEM_xxx`` values, one of the implementation-specific subsystem values, or a bitwise-or of them.