Function esp_idf_sys::psa_aead_update

source · 
pub unsafe extern "C" fn psa_aead_update(
    operation: *mut psa_aead_operation_t,
    input: *const u8,
    input_length: usize,
    output: *mut u8,
    output_size: usize,
    output_length: *mut usize
) -> psa_status_t
Expand description

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.

\param[in,out] operation Active AEAD operation. \param[in] input Buffer containing the message fragment to encrypt or decrypt. \param input_length Size of the \p input buffer in bytes. \param[out] output Buffer where the output is to be written. \param output_size Size of the \p output buffer in bytes. This must be appropriate for the selected algorithm and key: - A sufficient output size is #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c key_type, \c alg, \p input_length) where \c key_type is the type of key and \c alg is the algorithm that were used to set up the operation. - #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p input_length) evaluates to the maximum output size of any supported AEAD algorithm. \param[out] output_length On success, the number of bytes that make up the returned output.

\retval #PSA_SUCCESS Success. \retval #PSA_ERROR_BUFFER_TOO_SMALL The size of the \p output buffer is too small. #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c key_type, \c alg, \p input_length) or #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p input_length) can be used to determine the required buffer size. \retval #PSA_ERROR_INVALID_ARGUMENT The total length of input to psa_aead_update_ad() so far is less than the additional data length that was previously specified with psa_aead_set_lengths(), or the total input length overflows the plaintext length that was previously specified with psa_aead_set_lengths(). \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 \emptydescription \retval #PSA_ERROR_BAD_STATE The operation state is not valid (it must be active, have a nonce set, and have lengths set if required by the algorithm), or 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.