Update PSA API specification to 1.0.0
Generated from the PSA Crypto API Dockerfile at tag psa-crypto-api-1.0.0
diff --git a/docs/html/_sources/overview/functionality.rst.txt b/docs/html/_sources/overview/functionality.rst.txt
new file mode 100644
index 0000000..004f8bc
--- /dev/null
+++ b/docs/html/_sources/overview/functionality.rst.txt
@@ -0,0 +1,647 @@
+.. _functionality-overview:
+
+Functionality overview
+----------------------
+
+This section provides a high-level overview of the functionality provided by the
+interface defined in this specification. Refer to the `API definition
+<api-reference>` for a detailed description.
+
+`future` describes features that might be included in future versions of this
+specification.
+
+Due to the modularity of the interface, almost every part of the library is
+optional. The only mandatory function is `psa_crypto_init()`.
+
+Library management
+~~~~~~~~~~~~~~~~~~
+
+Applications must call `psa_crypto_init()` to initialize the library before
+using any other function.
+
+Key management
+~~~~~~~~~~~~~~
+
+Applications always access keys indirectly via an identifier, and can perform
+operations using a key without accessing the key material. This allows keys to
+be *non-extractable*, where an application can use a key but is not permitted to
+obtain the key material. Non-extractable keys are bound to the device, can be
+rate-limited and can have their usage restricted by policies.
+
+Each key has a set of attributes that describe the key and the policy for using
+the key. A `psa_key_attributes_t` object contains all of the attributes, which
+is used when creating a key and when querying key attributes.
+
+Each key has a *lifetime* that determines when the key material is destroyed.
+There are two types of lifetimes: `volatile <volatile-keys>` and
+`persistent <persistent-keys>`.
+
+.. _volatile-keys:
+
+Volatile keys
+^^^^^^^^^^^^^
+
+A *volatile* key exists until it explicitly destroyed with `psa_destroy_key()`
+or until the application terminates, which conceptually destroys all of its
+volatile keys.
+
+Conceptually, a volatile key is stored in RAM. Volatile keys have the
+lifetime `PSA_KEY_LIFETIME_VOLATILE`.
+
+To create a volatile key:
+
+1. Populate a `psa_key_attributes_t` object with the required type, size, policy
+ and other key attributes.
+2. Create the key with `psa_import_key()`, `psa_generate_key()`,
+ `psa_key_derivation_output_key()` or `psa_copy_key()`. If successful, these
+ functions output a transient `key identifier <key-ids>`.
+
+To destroy a volatile key, call `psa_destroy_key()` with the key identifier.
+
+.. _persistent-keys:
+
+Persistent keys
+^^^^^^^^^^^^^^^
+
+A *persistent* key exists until it explicitly destroyed with `psa_destroy_key()`
+or until it is wiped by the reset or destruction of the device.
+
+Each persistent key has a permanent key identifier, which acts as a name for the key.
+Within an application, the key identifier corresponds to a single key. The
+application specifies the key identifier when the key is created and when
+using the key.
+
+Persistent keys can be stored in different storage areas; this is indicated
+through different lifetime values. This specification defines a single lifetime
+value `PSA_KEY_LIFETIME_PERSISTENT` which corresponds to a default storage
+area. Implementations can define alternative lifetime values corresponding to
+different storage areas with different retention policies, or to secure elements
+with different security characteristics.
+
+To create a persistent key:
+
+1. Populate a `psa_key_attributes_t` object with the key’s type, size, policy
+ and other attributes.
+2. In the attributes object, set the desired lifetime and persistent identifier
+ for the key.
+3. Create the key with one of the *key creation functions*:
+
+ * `psa_import_key()`
+ * `psa_generate_key()`
+ * `psa_key_derivation_output_key()`
+ * `psa_copy_key()`
+
+ If successful, these functions output the `key identifier <key-ids>`
+ that was specified by the application in step 2.
+
+To access an existing persistent key: use the key identifier in any API that
+requires a key.
+
+To remove cached copies of key material for persistent keys created with the
+`PSA_KEY_USAGE_CACHE` policy: call `psa_purge_key()` with the key identifier.
+
+To destroy a persistent key: call `psa_destroy_key()` with the key identifier.
+Destroying a persistent key permanently removes it from memory and storage.
+
+The key lifetime and identifier are set when the key is created and cannot be
+changed without destroying the key first. If the original key permits copying,
+then the application can specify a different lifetime for the copy of the key.
+
+.. _key-ids:
+
+Key identifiers
+^^^^^^^^^^^^^^^
+
+Key identifiers are integral values that act as permanent names for persistent
+keys, or as transient references to volatile keys. Key identifiers use the
+`psa_key_id_t` type, and the range of identifier values is divided as follows:
+
+:code:`PSA_KEY_ID_NULL = 0`
+ Reserved as an invalid key identifier.
+: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.
+
+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.
+
+Valid key identifiers must have distinct values within the same application. If
+the implementation provides `caller isolation <isolation>`, then key
+identifiers are local to each application. That is, the same key identifier in two
+applications corresponds to two different keys.
+
+If an invalid key identifier is provided as a parameter in any function, the
+function will return `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 `PSA_SUCCESS`.
+
+There must be a matching call to `psa_destroy_key()` for each successful call
+to a create a volatile key.
+
+A call to `psa_destroy_key()` destroys the key material, and will cause any active
+operations that are using the key to fail. Therefore an application must not
+destroy a key while an operation using that key is in progress, unless the
+application is prepared to handle a failure of the operation.
+
+Recommendations of minimum standards for key management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Most implementations provide the following functions:
+
+* `psa_import_key()`. The exceptions are implementations that only give access
+ to a key or keys that are provisioned by proprietary means, and do not allow
+ the main application to use its own cryptographic material.
+
+* `psa_get_key_attributes()` and the ``psa_get_key_xxx()`` accessor functions.
+ They are easy to implement, and it is difficult to write applications and to
+ diagnose issues without being able to check the metadata.
+
+* `psa_export_public_key()`. This function is usually provided if the
+ implementation supports any asymmetric algorithm, since public-key
+ cryptography often requires the delivery of a public key that is associated
+ with a protected private key.
+
+* `psa_export_key()`. However, highly constrained implementations that are
+ designed to work only with short-term keys, or only with long-term
+ non-extractable keys, do not need to provide this function.
+
+Usage policies
+~~~~~~~~~~~~~~
+
+All keys have an associated policy that regulates which operations are permitted
+on the key. Each key policy is a set of usage flags and a specific algorithm
+that is permitted with the key. The policy is part of the key attributes that
+are managed by a `psa_key_attributes_t` object.
+
+The usage flags are encoded in a bitmask, which has the type
+`psa_key_usage_t`. Four kinds of usage flag can be specified:
+
+* The extractable flag `PSA_KEY_USAGE_EXPORT` determines whether the key
+ material can be extracted.
+* The copyable flag `PSA_KEY_USAGE_COPY` determines whether the key material
+ can be copied into a new key, which can have a different lifetime or a more
+ restrictive policy.
+* The cacheable flag `PSA_KEY_USAGE_CACHE` determines whether the
+ implementation is permitted to retain non-essential copies of the
+ key material in RAM. This policy only applies to persistent keys. See also
+ :title:`key-material`.
+* The other usage flags, for example, `PSA_KEY_USAGE_ENCRYPT` and `PSA_KEY_USAGE_SIGN_MESSAGE`,
+ determine whether the corresponding operation is permitted on the key.
+
+In addition to the usage bitmask, a policy specifies which algorithm is
+permitted with the key. This specification only defines policies that restrict
+keys to a single algorithm, which is consistent with both common practice and
+security good practice.
+
+A highly constrained implementation might not be able to support all the policies
+that can be expressed through this interface. If an implementation cannot create
+a key with the required policy, it must return an appropriate error code when
+the key is created.
+
+Symmetric cryptography
+~~~~~~~~~~~~~~~~~~~~~~
+
+This specification defines interfaces for the following types of symmetric
+cryptographic operation:
+
+* Message digests, commonly known as hash functions.
+* Message authentication codes (MAC).
+* Symmetric ciphers.
+* Authenticated encryption with associated data (AEAD).
+
+For each type of symmetric cryptographic operation, the API includes:
+
+* A pair of *single-part* functions. For example, compute and verify, or
+ encrypt and decrypt.
+* A series of functions that permit *multi-part operations*.
+
+Single-part Functions
+^^^^^^^^^^^^^^^^^^^^^
+
+Single-part functions are APIs that implement the cryptographic operation in a
+single function call. This is the easiest API to use when all of the inputs and
+outputs fit into the application memory.
+
+Some use cases involve messages that are too large to be assembled in memory, or
+require non-default configuration of the algorithm. These use cases require the
+use of a :title:`multi-part operation <multi-part-operations>`.
+
+.. _multi-part-operations:
+
+Multi-part operations
+^^^^^^^^^^^^^^^^^^^^^
+
+Multi-part operations are APIs which split a single cryptographic operation into
+a sequence of separate steps. This enables fine control over the configuration
+of the cryptographic operation, and allows the message data to be processed in
+fragments instead of all at once. For example, the following situations require
+the use of a multi-part operation:
+
+- Processing messages that cannot be assembled in memory.
+- Using a deterministic IV for unauthenticated encryption.
+- Providing the IV separately for unauthenticated encryption or decryption.
+- Separating the AEAD authentication tag from the cipher text.
+
+Each multi-part operation defines a specific object type to maintain the state
+of the operation. These types are implementation-defined. All multi-part
+operations follow the same pattern of use:
+
+1. **Allocate:** Allocate memory for an operation object of the appropriate
+ type. The application can use any allocation strategy: stack, heap, static, etc.
+
+2. **Initialize:** Initialize or assign the operation object by one of the
+ following methods:
+
+ - Set it to logical zero. This is automatic for static and global
+ variables. Explicit initialization must use the associated
+ ``PSA_xxx_INIT`` macro as the type is implementation-defined.
+ - Set it to all-bits zero. This is automatic if the object was
+ allocated with ``calloc()``.
+ - Assign the value of the associated macro ``PSA_xxx_INIT``.
+ - Assign the result of calling the associated function
+ ``psa_xxx_init()``.
+
+ The resulting object is now *inactive*.
+
+ It is an error to initialize an operation object that is in *active* or
+ *error* states. This can leak memory or other resources.
+
+3. **Setup:** Start a new multi-part operation on an *inactive* operation
+ object. Each operation object will define one or more setup functions to
+ start a specific operation.
+
+ On success, a setup function will put an operation object into an *active*
+ state. On failure, the operation object will remain *inactive*.
+
+4. **Update:** Update an *active* operation object. The update function can
+ provide additional parameters, supply data for processing or generate
+ outputs.
+
+ On success, the operation object remains *active*. On failure, the
+ operation object will enter an *error* state.
+
+5. **Finish:** To end the operation, call the applicable finishing function.
+ This will take any final inputs, produce any final outputs, and then
+ release any resources associated with the operation.
+
+ On success, the operation object returns to the *inactive* state. On
+ failure, the operation object will enter an *error* state.
+
+An operation can be aborted at any stage during its use by calling the
+associated ``psa_xxx_abort()`` function. This will release any resources
+associated with the operation and return the operation object to the *inactive*
+state.
+
+Any error that occurs to an operation while it is in an *active* state will
+result in the operation entering an *error* state. The application must call the
+associated ``psa_xxx_abort()`` function to release the operation resources and
+return the object to the *inactive* state.
+
+Once an operation object is returned to the *inactive* state, it can be reused
+by calling one of the applicable setup functions again.
+
+If a multi-part operation object is not initialized before use, the behavior is
+undefined.
+
+If a multi-part operation function determines that the operation object is not in
+any valid state, it can return `PSA_ERROR_CORRUPTION_DETECTED`.
+
+If a multi-part operation function is called with an operation object in the
+wrong state, the function will return `PSA_ERROR_BAD_STATE` and the operation
+object will enter the *error* state.
+
+It is safe to move a multi-part operation object to a different memory location,
+for example, using a bitwise copy, and then to use the object in the new
+location. For example, an application can allocate an operation object on the
+stack and return it, or the operation object can be allocated within memory
+managed by a garbage collector. However, this does not permit the following
+behaviors:
+
+- Moving the object while a function is being called on the object. This is
+ not safe. See also `concurrency`.
+- Working with both the original and the copied operation objects. This
+ requires cloning the operation, which is only available for hash operations
+ using `psa_hash_clone()`.
+
+Each type of multi-part operation can have multiple *active* states.
+Documentation for the specific operation describes the configuration and update
+functions, and any requirements about their usage and ordering.
+
+Message digests (Hashes)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The single-part hash functions are:
+
+- `psa_hash_compute()` to calculate the hash of a message.
+- `psa_hash_compare()` to compare the hash of a message with a reference value.
+
+The `psa_hash_operation_t` `multi-part operation <multi-part-operations>`
+allows messages to be processed in fragments:
+
+1. Initialize the `psa_hash_operation_t` object to zero, or by assigning the
+ value of the associated macro `PSA_HASH_OPERATION_INIT`.
+2. Call `psa_hash_setup()` to specify the required hash algorithm, call
+ `psa_hash_clone()` to duplicate the state of *active* `psa_hash_operation_t`
+ object, or call `psa_hash_resume()` to restart a hash operation with the
+ output from a previously suspended hash operation.
+3. Call the `psa_hash_update()` function on successive chunks of the message.
+4. At the end of the message, call the required finishing function:
+
+ - To suspend the hash operation and extract a hash suspend state,
+ call `psa_hash_suspend()`. The output state can subsequently be used
+ to resume the hash operation.
+ - To calculate the digest of a message, call `psa_hash_finish()`.
+ - To verify the digest of a message against a reference value, call
+ `psa_hash_verify()`.
+
+To abort the operation or recover from an error, call `psa_hash_abort()`.
+
+Message authentication codes (MACs)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The single-part MAC functions are:
+
+- `psa_mac_compute()` to calculate the MAC of a message.
+- `psa_mac_verify()` to compare the MAC of a message with a reference value.
+
+The `psa_mac_operation_t` `multi-part operation <multi-part-operations>`
+allows messages to be processed in fragments:
+
+1. Initialize the `psa_mac_operation_t` object to zero, or by assigning the
+ value of the associated macro `PSA_MAC_OPERATION_INIT`.
+2. Call `psa_mac_sign_setup()` or `psa_mac_verify_setup()` to specify the
+ algorithm and key.
+3. Call the `psa_mac_update()` function on successive chunks of the message.
+4. At the end of the message, call the required finishing function:
+
+ - To calculate the MAC of the message, call `psa_mac_sign_finish()`.
+ - To verify the MAC of the message against a reference value, call
+ `psa_mac_verify_finish()`.
+
+To abort the operation or recover from an error, call `psa_mac_abort()`.
+
+Encryption and decryption
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+ The unauthenticated cipher API is provided to implement legacy protocols and
+ for use cases where the data integrity and authenticity is guaranteed by
+ non-cryptographic means. It is recommended that newer protocols use
+ :title:`func-aead`.
+
+The single-part functions for encrypting or decrypting a message using an
+unauthenticated symmetric cipher are:
+
+- `psa_cipher_encrypt()` to encrypt a message using an unauthenticated symmetric
+ cipher. The encryption function generates a random IV. Use the multi-part API
+ to provide a deterministic IV: this is not secure in general, but
+ can be secure in some conditions that depend on the algorithm.
+- `psa_cipher_decrypt()` to decrypt a message using an unauthenticated symmetric
+ cipher.
+
+The `psa_cipher_operation_t` `multi-part operation <multi-part-operations>`
+permits alternative initialization parameters and allows messages to be
+processed in fragments:
+
+1. Initialize the `psa_cipher_operation_t` object to zero, or by assigning the
+ value of the associated macro `PSA_CIPHER_OPERATION_INIT`.
+2. Call `psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()` to specify the
+ algorithm and key.
+3. Provide additional parameters:
+
+ - When encrypting data, generate or set an initialization vector (IV),
+ nonce, or similar initial value such as an initial counter value. To
+ generate a random IV, which is recommended in most protocols, call
+ `psa_cipher_generate_iv()`. To set the IV, call `psa_cipher_set_iv()`.
+ - When decrypting, set the IV or nonce. To set the IV, call
+ `psa_cipher_set_iv()`.
+4. Call the `psa_cipher_update()` function on successive chunks of the message.
+5. Call `psa_cipher_finish()` to complete the operation and return any final
+ output.
+
+To abort the operation or recover from an error, call `psa_cipher_abort()`.
+
+.. _func-aead:
+
+Authenticated encryption (AEAD)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The single-part AEAD functions are:
+
+- `psa_aead_encrypt()` to encrypt a message using an authenticated symmetric
+ cipher.
+- `psa_aead_decrypt()` to decrypt a message using an authenticated symmetric
+ cipher.
+
+These functions follow the interface recommended by :RFC:`5116`.
+
+The encryption function requires a nonce to be provided. To generate a random
+nonce, either call `psa_generate_random()` or use the AEAD multi-part API.
+
+The `psa_aead_operation_t` `multi-part operation <multi-part-operations>`
+permits alternative initialization parameters and allows messages to be
+processed in fragments:
+
+1. Initialize the `psa_aead_operation_t` object to zero, or by assigning the
+ value of the associated macro `PSA_AEAD_OPERATION_INIT`.
+2. Call `psa_aead_encrypt_setup()` or `psa_aead_decrypt_setup()` to specify the
+ algorithm and key.
+3. Provide additional parameters:
+
+ - If the algorithm requires it, call `psa_aead_set_lengths()` to specify the
+ length of the non-encrypted and encrypted inputs to the operation.
+ - When encrypting, call either `psa_aead_generate_nonce()` or
+ `psa_aead_set_nonce()` to generate or set the nonce.
+ - When decrypting, call `psa_aead_set_nonce()` to set the nonce.
+4. Call `psa_aead_update_ad()` zero or more times with fragments of the
+ non-encrypted additional data.
+5. Call `psa_aead_update()` zero or more times with fragments of the plaintext
+ or ciphertext to encrypt or decrypt.
+6. At the end of the message, call the required finishing function:
+
+ - To complete an encryption operation, call `psa_aead_finish()` to compute
+ and return authentication tag.
+ - To complete a decryption operation, call `psa_aead_verify()` to
+ compute the authentication tag and verify it against a reference value.
+
+To abort the operation or recover from an error, call `psa_aead_abort()`.
+
+Having a multi-part interface to authenticated encryption raises specific issues.
+
+Multi-part authenticated decryption produces partial results that are not
+authenticated. Applications must not use or expose partial results of
+authenticated decryption until `psa_aead_verify()` has returned a success
+status and must destroy all partial results without revealing them if
+`psa_aead_verify()` returns a failure status. Revealing partial results, either directly or indirectly through the application’s behavior, can compromise the
+confidentiality of all inputs that are encrypted with the same key.
+
+For encryption, some common algorithms cannot be processed in a streaming
+fashion. For SIV mode, the whole plaintext must be known before the encryption
+can start; the multi-part AEAD API is not meant to be usable with SIV mode. For
+CCM mode, the length of the plaintext must be known before the encryption can
+start; the application can call the function `psa_aead_set_lengths()` to provide
+these lengths before providing input.
+
+.. _key-derivation:
+
+Key derivation
+^^^^^^^^^^^^^^
+
+A key derivation encodes a deterministic method to generate a finite stream of
+bytes. This data stream is computed by the cryptoprocessor and extracted in
+chunks. If two key derivation operations are constructed with the same
+parameters, then they produce the same output.
+
+A key derivation consists of two phases:
+
+1. Input collection. This is sometimes known as *extraction*: the operation
+ “extracts” information from the inputs to generate a pseudorandom
+ intermediate secret value.
+2. Output generation. This is sometimes known as *expansion*: the operation
+ “expands” the intermediate secret value to the desired output length.
+
+The specification defines a `multi-part operation <multi-part-operations>`
+API for key derivation that allows for multiple key and non-key outputs to be
+extracted from a single derivation operation object.
+
+In an implementation with `isolation <isolation>`, the intermediate
+state of the key derivation is not visible to the caller, and if an output of
+the derivation is a non-exportable key, then this key cannot be recovered
+outside the isolation boundary.
+
+Applications use the `psa_key_derivation_operation_t` type to create key
+derivation operations. The operation object is used as follows:
+
+1. Initialize a `psa_key_derivation_operation_t` object to zero or to
+ `PSA_KEY_DERIVATION_OPERATION_INIT`.
+2. Call `psa_key_derivation_setup()` to select a key derivation algorithm.
+3. Call the functions `psa_key_derivation_input_bytes()` and
+ `psa_key_derivation_input_key()`, or `psa_key_derivation_key_agreement()` to
+ provide the inputs to the key derivation algorithm. Many key derivation
+ algorithms take multiple inputs; the ``step`` parameter to these functions
+ indicates which input is being provided. The documentation for each key
+ derivation algorithm describes the expected inputs for that algorithm and
+ in what order to pass them.
+4. Optionally, call `psa_key_derivation_set_capacity()` to set a limit on the
+ amount of data that can be output from the key derivation operation.
+5. Call `psa_key_derivation_output_key()` to create a derived key, or
+ `psa_key_derivation_output_bytes()` to export the derived data. These
+ functions can be called multiple times to read successive output from the key
+ derivation, until the stream is exhausted when its capacity has been reached.
+6. Key derivation does not finish in the same way as other multi-part
+ operations. Call `psa_key_derivation_abort()` to release the key derivation
+ operation memory when the object is no longer required.
+
+To recover from an error, call `psa_key_derivation_abort()` to release the key
+derivation operation memory.
+
+A key derivation operation cannot be rewound. Once a part of the stream has been
+output, it cannot be output again. This ensures that the same part of the output
+will not be used for different purposes.
+
+Example of the symmetric cryptography API
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here is an example of a use case where a master key is used to generate both a
+message encryption key and an IV for the encryption, and the derived key and IV
+are then used to encrypt a message.
+
+1. Derive the message encryption material from the master key.
+
+ 1. Initialize a `psa_key_derivation_operation_t` object to zero or to
+ `PSA_KEY_DERIVATION_OPERATION_INIT`.
+ 2. Call `psa_key_derivation_setup()` with `PSA_ALG_HKDF` as the algorithm.
+ 3. Call `psa_key_derivation_input_key()` with the step
+ `PSA_KEY_DERIVATION_INPUT_SECRET` and the master key.
+ 4. Call `psa_key_derivation_input_bytes()` with the step
+ `PSA_KEY_DERIVATION_INPUT_INFO` and a public value that uniquely
+ identifies the message.
+ 5. Populate a `psa_key_attributes_t` object with the derived message
+ encryption key’s attributes.
+ 6. Call `psa_key_derivation_output_key()` to create the derived message key.
+ 7. Call `psa_key_derivation_output_bytes()` to generate the derived IV.
+ 8. Call `psa_key_derivation_abort()` to release the key derivation operation
+ memory.
+
+2. Encrypt the message with the derived material.
+
+ 1. Initialize a `psa_cipher_operation_t` object to zero or to
+ `PSA_CIPHER_OPERATION_INIT`.
+ 2. Call `psa_cipher_encrypt_setup()` with the derived message encryption key.
+ 3. Call `psa_cipher_set_iv()` using the derived IV retrieved above.
+ 4. Call `psa_cipher_update()` one or more times to encrypt the message.
+ 5. Call `psa_cipher_finish()` at the end of the message.
+
+3. Call `psa_destroy_key()` to clear the generated key.
+
+Asymmetric cryptography
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This specification defines functions for asymmetric cryptography, including
+asymmetric encryption, asymmetric signature, and two-way key agreement.
+
+Asymmetric encryption
+^^^^^^^^^^^^^^^^^^^^^
+
+Asymmetric encryption is provided through the functions
+`psa_asymmetric_encrypt()` and `psa_asymmetric_decrypt()`.
+
+Hash-and-sign
+^^^^^^^^^^^^^
+
+The signature and verification functions `psa_sign_message()` and
+`psa_verify_message()` take a message as one of their inputs and perform a
+hash-and-sign algorithm.
+
+The functions `psa_sign_hash()` and `psa_verify_hash()` take a message hash as
+one of their inputs. This is useful for signing pre-computed hashes, or for
+implementing hash-and-sign using a :ref:`multi-part hash operation <hash-mp>`
+before signing the resulting hash. To determine which
+hash algorithm to use, call the macro `PSA_ALG_GET_HASH()` on the
+corresponding signature algorithm.
+
+Some hash-and-sign algorithms add padding to the message hash before completing
+the signing operation. The format of the padding that is used depends on the
+algorithm used to construct the signature.
+
+Key agreement
+^^^^^^^^^^^^^
+
+This specification defines two functions for a Diffie-Hellman-style key
+agreement where each party combines its own private key with the peer’s public
+key.
+
+The recommended approach is to use a `key derivation
+operation <key-derivation>` with the `psa_key_derivation_key_agreement()`
+input function, which calculates a shared secret for the key derivation
+function.
+
+Where an application needs direct access to the shared secret, it can call
+`psa_raw_key_agreement()` instead. Note that in general the shared secret is not
+directly suitable for use as a key because it is biased.
+
+Randomness and key generation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We strongly recommended that implementations include a random generator,
+consisting of a cryptographically secure pseudo-random generator (CSPRNG), which
+is adequately seeded with a cryptographic-quality hardware entropy source,
+commonly referred to as a true random number generator (TRNG). Constrained
+implementations can omit the random generation functionality if they do not
+implement any algorithm that requires randomness internally, and they do not
+provide a key generation functionality. For example, a special-purpose component
+for signature verification can omit this.
+
+It is recommended that applications use `psa_generate_key()`,
+`psa_cipher_generate_iv()` or `psa_aead_generate_nonce()` to generate
+suitably-formatted random data, as applicable. In addition, the API includes a
+function `psa_generate_random()` to generate and extract arbitrary random data.