psa_aead_generate_nonce() function

Active AEAD operation.

Buffer where the generated nonce is to be written.

Size of the \p nonce buffer in bytes.

On success, the number of bytes of the generated nonce.

Abort an AEAD operation. Aborting an operation frees all associated resources except for the \p operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again. You may call this function any time after the operation object has been initialized as described in #psa_aead_operation_t. 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.

Set the key for a multipart authenticated encryption operation. The sequence of operations to encrypt a message with authentication is as follows: -# Allocate an operation object which will be passed to all the functions listed here. -# Initialize the operation object with one of the methods described in the documentation for #psa_aead_operation_t, e.g. #PSA_AEAD_OPERATION_INIT. -# Call psa_aead_encrypt_setup() to specify the algorithm and key. -# If needed, call psa_aead_set_lengths() to specify the length of the inputs to the subsequent calls to psa_aead_update_ad() and psa_aead_update(). See the documentation of psa_aead_set_lengths() for details. -# Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to generate or set the nonce. You should use psa_aead_generate_nonce() unless the protocol you are implementing requires a specific nonce value. -# Call psa_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time. -# Call psa_aead_update() zero, one or more times, passing a fragment of the message to encrypt each time. -# Call psa_aead_finish(). If an error occurs at any step after a call to psa_aead_encrypt_setup(), the operation will need to be reset by a call to psa_aead_abort(). The application may call psa_aead_abort() at any time after the operation has been initialized. After a successful call to psa_aead_encrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation: - A successful call to psa_aead_finish(). - A call to psa_aead_abort().

Set the key for a multipart authenticated decryption operation. The sequence of operations to decrypt a message with authentication is as follows: -# Allocate an operation object which will be passed to all the functions listed here. -# Initialize the operation object with one of the methods described in the documentation for #psa_aead_operation_t, e.g. #PSA_AEAD_OPERATION_INIT. -# Call psa_aead_decrypt_setup() to specify the algorithm and key. -# If needed, call psa_aead_set_lengths() to specify the length of the inputs to the subsequent calls to psa_aead_update_ad() and psa_aead_update(). See the documentation of psa_aead_set_lengths() for details. -# Call psa_aead_set_nonce() with the nonce for the decryption. -# Call psa_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time. -# Call psa_aead_update() zero, one or more times, passing a fragment of the ciphertext to decrypt each time. -# Call psa_aead_verify(). If an error occurs at any step after a call to psa_aead_decrypt_setup(), the operation will need to be reset by a call to psa_aead_abort(). The application may call psa_aead_abort() at any time after the operation has been initialized. After a successful call to psa_aead_decrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation: - A successful call to psa_aead_verify(). - A call to psa_aead_abort().

Set the nonce for an authenticated encryption or decryption operation. This function sets the nonce for the authenticated encryption or decryption operation. The application must call psa_aead_encrypt_setup() or psa_aead_decrypt_setup() before calling this function. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Declare the lengths of the message and additional data for AEAD. The application must call this function before calling psa_aead_update_ad() or psa_aead_update() if the algorithm for the operation requires it. If the algorithm does not require it, calling this function is optional, but if this function is called then the implementation must enforce the lengths. You may call this function before or after setting the nonce with psa_aead_set_nonce() or psa_aead_generate_nonce(). - For #PSA_ALG_CCM, calling this function is required. - For the other AEAD algorithms defined in this specification, calling this function is not required. - For vendor-defined algorithm, refer to the vendor documentation. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Pass additional data to an active AEAD operation. Additional data is authenticated, but not encrypted. You may call this function multiple times to pass successive fragments of the additional data. You may not call this function after passing data to encrypt or decrypt with psa_aead_update(). Before calling this function, you must: 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup(). 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce(). If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort(). \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS, there is no guarantee that the input is valid. Therefore, until you have called psa_aead_verify() and it has returned #PSA_SUCCESS, treat the input as untrusted and prepare to undo any action that depends on the input if psa_aead_verify() returns an error status.

Encrypt or decrypt a message fragment in an active AEAD operation. Before calling this function, you must: 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input. 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce(). 3. Call psa_aead_update_ad() to pass all the additional data. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort(). \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS, there is no guarantee that the input is valid. Therefore, until you have called psa_aead_verify() and it has returned #PSA_SUCCESS: - Do not use the output in any way other than storing it in a confidential location. If you take any action that depends on the tentative decrypted data, this action will need to be undone if the input turns out not to be valid. Furthermore, if an adversary can observe that this action took place (for example through timing), they may be able to use this fact as an oracle to decrypt any message encrypted with the same key. - In particular, do not copy the output anywhere but to a memory or storage space that you have exclusive access to. This function does not require the input to be aligned to any particular block boundary. If the implementation can only process a whole block at a time, it must consume all the input provided, but it may delay the end of the corresponding output until a subsequent call to psa_aead_update(), psa_aead_finish() or psa_aead_verify() provides sufficient input. The amount of data that can be delayed in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE.

Finish encrypting a message in an AEAD operation. The operation must have been set up with psa_aead_encrypt_setup(). This function finishes the authentication of the additional data formed by concatenating the inputs passed to preceding calls to psa_aead_update_ad() with the plaintext formed by concatenating the inputs passed to preceding calls to psa_aead_update(). This function has two output buffers: - \p ciphertext contains trailing ciphertext that was buffered from preceding calls to psa_aead_update(). - \p tag contains the authentication tag. When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Finish authenticating and decrypting a message in an AEAD operation. The operation must have been set up with psa_aead_decrypt_setup(). This function finishes the authenticated decryption of the message components: - The additional data consisting of the concatenation of the inputs passed to preceding calls to psa_aead_update_ad(). - The ciphertext consisting of the concatenation of the inputs passed to preceding calls to psa_aead_update(). - The tag passed to this function call. If the authentication tag is correct, this function outputs any remaining plaintext and reports success. If the authentication tag is not correct, this function returns #PSA_ERROR_INVALID_SIGNATURE. When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().