psa_aead_setup() function

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 the PSA core by it calling mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup() again. The PSA core may call this function any time after the operation object has been initialized as described in #mbedtls_psa_aead_operation_t. In particular, calling mbedtls_psa_aead_abort() after the operation has been terminated by a call to mbedtls_psa_aead_abort() or mbedtls_psa_aead_finish() is safe and has no effect.

Finish encrypting a message in an AEAD operation. The operation must have been set up by the PSA core with mbedtls_psa_aead_encrypt_setup(). This function finishes the authentication of the additional data formed by concatenating the inputs passed to preceding calls to mbedtls_psa_aead_update_ad() with the plaintext formed by concatenating the inputs passed to preceding calls to mbedtls_psa_aead_update(). This function has two output buffers: - \p ciphertext contains trailing ciphertext that was buffered from preceding calls to mbedtls_psa_aead_update(). - \p tag contains the authentication tag. Whether or not this function returns successfully, the PSA core subsequently calls mbedtls_psa_aead_abort() to deactivate the operation.

Set the key for a multipart authenticated encryption operation. If an error occurs at any step after a call to mbedtls_psa_aead_encrypt_setup(), the operation is reset by the PSA core by a call to mbedtls_psa_aead_abort(). The PSA core may call mbedtls_psa_aead_abort() at any time after the operation has been initialized, and is required to when the operation is no longer needed.

Set the key for a multipart authenticated decryption operation. If an error occurs at any step after a call to mbedtls_psa_aead_decrypt_setup(), the PSA core resets the operation by a call to mbedtls_psa_aead_abort(). The PSA core may call mbedtls_psa_aead_abort() at any time after the operation has been initialized, and is required to when the operation is no longer needed.

Set the nonce for an authenticated encryption or decryption operation. This function sets the nonce for the authenticated encryption or decryption operation. The PSA core calls mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup() before calling this function. If this function returns an error status, the PSA core will call mbedtls_psa_aead_abort().

Declare the lengths of the message and additional data for AEAD. The PSA core calls this function before calling mbedtls_psa_aead_update_ad() or mbedtls_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. The PSA core may call this function before or after setting the nonce with mbedtls_psa_aead_set_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. If this function returns an error status, the PSA core calls mbedtls_psa_aead_abort().

Pass additional data to an active AEAD operation. Additional data is authenticated, but not encrypted. The PSA core can call this function multiple times to pass successive fragments of the additional data. It will not call this function after passing data to encrypt or decrypt with mbedtls_psa_aead_update(). Before calling this function, the PSA core will: 1. Call either mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup(). 2. Set the nonce with mbedtls_psa_aead_set_nonce(). If this function returns an error status, the PSA core will call mbedtls_psa_aead_abort().

Encrypt or decrypt a message fragment in an active AEAD operation. Before calling this function, the PSA core will: 1. Call either mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input. 2. Set the nonce with mbedtls_psa_aead_set_nonce(). 3. Call mbedtls_psa_aead_update_ad() to pass all the additional data. If this function returns an error status, the PSA core will call mbedtls_psa_aead_abort(). 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 mbedtls_psa_aead_update(), mbedtls_psa_aead_finish() provides sufficient input. The amount of data that can be delayed in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE.