Function esp_idf_sys::psa_aead_encrypt_setup

pub unsafe extern "C" fn psa_aead_encrypt_setup(
    operation: *mut psa_aead_operation_t,
    key: mbedtls_svc_key_id_t,
    alg: psa_algorithm_t,
) -> psa_status_t

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().

\param[in,out] operation The operation object to set up. It must have been initialized as per the documentation for #psa_aead_operation_t and not yet in use. \param key Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage #PSA_KEY_USAGE_ENCRYPT. \param alg The AEAD algorithm to compute (\c PSA_ALG_XXX value such that #PSA_ALG_IS_AEAD(\p alg) is true).

\retval #PSA_SUCCESS Success. \retval #PSA_ERROR_BAD_STATE The operation state is not valid (it must be inactive), or the library has not been previously initialized by psa_crypto_init(). \retval #PSA_ERROR_INVALID_HANDLE \emptydescription \retval #PSA_ERROR_NOT_PERMITTED \emptydescription \retval #PSA_ERROR_INVALID_ARGUMENT \p key is not compatible with \p alg. \retval #PSA_ERROR_NOT_SUPPORTED \p alg is not supported or is not an AEAD algorithm. \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription \retval #PSA_ERROR_STORAGE_FAILURE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.