Adding clone functions for all operation_t types

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 <multi-part-operations>` 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
 --------------
 

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 <multi-part-operations>` 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
 --------------
 

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

doc/crypto/api/ops/mac.rst

@@ -16,7 +16,7 @@ The single-part MAC functions are:
 
 The `psa_mac_operation_t` `multi-part operation <multi-part-operations>` 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
 --------------
 

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: