diff --git a/doc/crypto/api/ops/aead.rst b/doc/crypto/api/ops/aead.rst index d59488d1..d2ee977b 100644 --- a/doc/crypto/api/ops/aead.rst +++ b/doc/crypto/api/ops/aead.rst @@ -21,7 +21,7 @@ The encryption function requires a nonce to be provided. To generate a random no The `psa_aead_operation_t` `multi-part operation ` permits alternative initialization parameters and allows messages to be processed in fragments. A multi-part AEAD operation is used as follows: 1. Initialize the `psa_aead_operation_t` object to zero, or by assigning the value of the associated macro `PSA_AEAD_OPERATION_INIT`. -#. Call `psa_aead_encrypt_setup()` or `psa_aead_decrypt_setup()` to specify the algorithm and key. +#. Call `psa_aead_encrypt_setup()` or `psa_aead_decrypt_setup()` to specify the algorithm and key, call `psa_aead_clone()` to duplicate the state of *active* .`psa_aead_operation_t` object #. 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. @@ -942,6 +942,32 @@ Multi-part AEAD operations In particular, calling `psa_aead_abort()` after the operation has been terminated by a call to `psa_aead_abort()`, `psa_aead_finish()` or `psa_aead_verify()` is safe and has no effect. +.. function:: psa_aead_clone + + .. summary:: + Clone a AEAD operation. + + .. param:: const psa_aead_operation_t * source_operation + The active aead operation to clone. + .. param:: psa_aead_operation_t * target_operation + The operation object to set up. It must be initialized but not active. + + .. return:: psa_status_t + .. retval:: PSA_SUCCESS + Success. + ``target_operation`` is ready to continue the same aead operation as ``source_operation``. + .. retval:: PSA_ERROR_BAD_STATE + The following conditions can result in this error: + + * 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()`. + .. retval:: PSA_ERROR_COMMUNICATION_FAILURE + .. retval:: PSA_ERROR_CORRUPTION_DETECTED + .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + + This function copies the state of an ongoing AEAD operation to a new operation object. In other words, this function is equivalent to calling `psa_aead_setup()` on ``target_operation`` with the same algorithm that ``source_operation`` was set up for, then `psa_aead_update()` on ``target_operation`` with the same input that that was passed to ``source_operation``. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object. + Support macros -------------- diff --git a/doc/crypto/api/ops/cipher.rst b/doc/crypto/api/ops/cipher.rst index e8d80721..f2712cb7 100644 --- a/doc/crypto/api/ops/cipher.rst +++ b/doc/crypto/api/ops/cipher.rst @@ -22,7 +22,7 @@ The single-part functions for encrypting or decrypting a message using an unauth The `psa_cipher_operation_t` `multi-part operation ` permits alternative initialization parameters and allows messages to be processed in fragments. A multi-part cipher operation is used as follows: -1. Initialize the `psa_cipher_operation_t` object to zero, or by assigning the value of the associated macro `PSA_CIPHER_OPERATION_INIT`. +1. Initialize the `psa_cipher_operation_t` object to zero, or by assigning the value of the associated macro `PSA_CIPHER_OPERATION_INIT`, call `psa_cipher_clone()` to duplicate the state of *active* .`psa_cipher_operation_t` object. #. Call `psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()` to specify the algorithm and key. #. Provide additional parameters: @@ -859,6 +859,34 @@ Multi-part cipher operations In particular, calling `psa_cipher_abort()` after the operation has been terminated by a call to `psa_cipher_abort()` or `psa_cipher_finish()` is safe and has no effect. +.. function:: psa_cipher_clone + + .. summary:: + Clone a cipher operation. + + .. param:: const psa_cipher_operation_t * source_operation + The active cipher operation to clone. + .. param:: psa_cipher_operation_t * target_operation + The operation object to set up. It must be initialized but not active. + + .. return:: psa_status_t + .. retval:: PSA_SUCCESS + Success. + ``target_operation`` is ready to continue the same cipher operation as ``source_operation``. + .. retval:: PSA_ERROR_BAD_STATE + The following conditions can result in this error: + + * 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()`. + .. retval:: PSA_ERROR_COMMUNICATION_FAILURE + .. retval:: PSA_ERROR_CORRUPTION_DETECTED + .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + + This function copies the state of an ongoing cipher operation to a new operation object. In other words, this function is equivalent to calling `psa_cipher_setup()` on ``target_operation`` with the same algorithm that ``source_operation`` was set up for, then `psa_cipher_update()` on ``target_operation`` with the same input that that was passed to ``source_operation``. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object. + + + Support macros -------------- diff --git a/doc/crypto/api/ops/key-derivation.rst b/doc/crypto/api/ops/key-derivation.rst index 5a1d1250..a5409932 100644 --- a/doc/crypto/api/ops/key-derivation.rst +++ b/doc/crypto/api/ops/key-derivation.rst @@ -31,7 +31,7 @@ An implementation with :term:`isolation` has the following properties: 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`. +1. Initialize a `psa_key_derivation_operation_t` object to zero or to `PSA_KEY_DERIVATION_OPERATION_INIT`, call `psa_key_derivation_clone()` to duplicate the state of *active* .`psa_key_derivation_operation_t` object. #. Call `psa_key_derivation_setup()` to select a key-derivation algorithm. #. Call the functions `psa_key_derivation_input_key()` or `psa_key_derivation_key_agreement()` to provide the secret inputs, and `psa_key_derivation_input_bytes()` or `psa_key_derivation_input_integer()` to provide the non-secret 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. #. 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. @@ -345,7 +345,7 @@ Key-derivation algorithms This KDF is defined in :cite-title:`TLS-ECJPAKE` ยง8.7. This specifies the use of a KDF to derive the TLS 1.2 session secrets from the output of EC J-PAKE over the secp256r1 Elliptic curve (the 256-bit curve in `PSA_ECC_FAMILY_SECP_R1`). EC J-PAKE operations can be performed using a PAKE operation, see :secref:`pake`. - This KDF takes the shared secret :math:`K`` (an uncompressed EC point in case of EC J-PAKE) and calculates :math:`\text{SHA256}(K.x)`. + This KDF takes the shared secret :math:``K`` (an uncompressed EC point in case of EC J-PAKE) and calculates :math:`\text{SHA256}(K.x)`. This function takes a single input: @@ -1208,6 +1208,32 @@ Key-derivation functions In particular, it is valid to call `psa_key_derivation_abort()` twice, or to call `psa_key_derivation_abort()` on an operation that has not been set up. +.. function:: psa_key_derivation_clone + + .. summary:: + Clone a key_derivation operation. + + .. param:: const psa_key_derivation_operation_t * source_operation + The active key_derivation operation to clone. + .. param:: psa_key_derivation_operation_t * target_operation + The operation object to set up. It must be initialized but not active. + + .. return:: psa_status_t + .. retval:: PSA_SUCCESS + Success. + ``target_operation`` is ready to continue the same key_derivation operation as ``source_operation``. + .. retval:: PSA_ERROR_BAD_STATE + The following conditions can result in this error: + + * 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()`. + .. retval:: PSA_ERROR_COMMUNICATION_FAILURE + .. retval:: PSA_ERROR_CORRUPTION_DETECTED + .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + + This function copies the state of an ongoing key_derivation operation to a new operation object. In other words, this function is equivalent to calling `psa_key_derivation_setup()` on ``target_operation`` with the same algorithm that ``source_operation`` was set up for, then `psa_key_derivation_update()` on ``target_operation`` with the same input that that was passed to ``source_operation``. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object. + Support macros -------------- diff --git a/doc/crypto/api/ops/mac.rst b/doc/crypto/api/ops/mac.rst index 18839c50..567f14bc 100644 --- a/doc/crypto/api/ops/mac.rst +++ b/doc/crypto/api/ops/mac.rst @@ -16,7 +16,7 @@ The single-part MAC functions are: The `psa_mac_operation_t` `multi-part operation ` allows messages to be processed in fragments. A multi-part MAC operation is used as follows: -1. Initialize the `psa_mac_operation_t` object to zero, or by assigning the value of the associated macro `PSA_MAC_OPERATION_INIT`. +1. Initialize the `psa_mac_operation_t` object to zero, or by assigning the value of the associated macro `PSA_MAC_OPERATION_INIT`, call `psa_mac_clone()` to duplicate the state of *active* .`psa_mac_operation_t` object. #. Call `psa_mac_sign_setup()` or `psa_mac_verify_setup()` to specify the algorithm and key. #. Call the `psa_mac_update()` function on successive chunks of the message. #. At the end of the message, call the required finishing function: @@ -604,6 +604,33 @@ Multi-part MAC operations In particular, calling `psa_mac_abort()` after the operation has been terminated by a call to `psa_mac_abort()`, `psa_mac_sign_finish()` or `psa_mac_verify_finish()` is safe and has no effect. +.. function:: psa_mac_clone + + .. summary:: + Clone a MAC operation. + + .. param:: const psa_mac_operation_t * source_operation + The active MAC operation to clone. + .. param:: psa_mac_operation_t * target_operation + The operation object to set up. It must be initialized but not active. + + .. return:: psa_status_t + .. retval:: PSA_SUCCESS + Success. + ``target_operation`` is ready to continue the same MAC operation as ``source_operation``. + .. retval:: PSA_ERROR_BAD_STATE + The following conditions can result in this error: + + * 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()`. + .. retval:: PSA_ERROR_COMMUNICATION_FAILURE + .. retval:: PSA_ERROR_CORRUPTION_DETECTED + .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + + This function copies the state of an ongoing MAC operation to a new operation object. In other words, this function is equivalent to calling `psa_mac_setup()` on ``target_operation`` with the same algorithm that ``source_operation`` was set up for, then `psa_mac_update()` on ``target_operation`` with the same input that that was passed to ``source_operation``. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object. + + Support macros -------------- diff --git a/doc/crypto/api/ops/pake.rst b/doc/crypto/api/ops/pake.rst index 6fa518b0..8ef24905 100644 --- a/doc/crypto/api/ops/pake.rst +++ b/doc/crypto/api/ops/pake.rst @@ -1178,6 +1178,31 @@ Multi-part PAKE operations In particular, calling `psa_pake_abort()` after the operation has been terminated by a call to `psa_pake_abort()` or `psa_pake_get_shared_key()` is safe and has no effect. +.. function:: psa_pake_clone + + .. summary:: + Clone a pake operation. + + .. param:: const psa_pake_operation_t * source_operation + The active pake operation to clone. + .. param:: psa_pake_operation_t * target_operation + The operation object to set up. It must be initialized but not active. + + .. return:: psa_status_t + .. retval:: PSA_SUCCESS + Success. + ``target_operation`` is ready to continue the same pake operation as ``source_operation``. + .. retval:: PSA_ERROR_BAD_STATE + The following conditions can result in this error: + + * 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()`. + .. retval:: PSA_ERROR_COMMUNICATION_FAILURE + .. retval:: PSA_ERROR_CORRUPTION_DETECTED + .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY + + This function copies the state of an ongoing pake operation to a new operation object. In other words, this function is equivalent to calling `psa_pake_setup()` on ``target_operation`` with the same algorithm that ``source_operation`` was set up for, then `psa_pake_update()` on ``target_operation`` with the same input that that was passed to ``source_operation``. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object. .. _pake-support: