746 lines
37 KiB
C
746 lines
37 KiB
C
/*
|
|
* PSA AEAD driver entry points
|
|
*/
|
|
/*
|
|
* Copyright The Mbed TLS Contributors
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
* not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
#ifndef PSA_CRYPTO_AEAD_H
|
|
#define PSA_CRYPTO_AEAD_H
|
|
|
|
#include <psa/crypto.h>
|
|
|
|
/**
|
|
* \brief Process an authenticated encryption operation.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* aead_encrypt entry point. This function behaves as an aead_encrypt
|
|
* entry point as defined in the PSA driver interface specification for
|
|
* transparent drivers.
|
|
*
|
|
* \param[in] attributes The attributes of the key to use for the
|
|
* operation.
|
|
* \param[in] key_buffer The buffer containing the key context.
|
|
* \param key_buffer_size Size of the \p key_buffer buffer in bytes.
|
|
* \param alg The AEAD algorithm to compute.
|
|
* \param[in] nonce Nonce or IV to use.
|
|
* \param nonce_length Size of the nonce buffer in bytes. This must
|
|
* be appropriate for the selected algorithm.
|
|
* The default nonce size is
|
|
* PSA_AEAD_NONCE_LENGTH(key_type, alg) where
|
|
* key_type is the type of key.
|
|
* \param[in] additional_data Additional data that will be authenticated
|
|
* but not encrypted.
|
|
* \param additional_data_length Size of additional_data in bytes.
|
|
* \param[in] plaintext Data that will be authenticated and encrypted.
|
|
* \param plaintext_length Size of plaintext in bytes.
|
|
* \param[out] ciphertext Output buffer for the authenticated and
|
|
* encrypted data. The additional data is not
|
|
* part of this output. For algorithms where the
|
|
* encrypted data and the authentication tag are
|
|
* defined as separate outputs, the
|
|
* authentication tag is appended to the
|
|
* encrypted data.
|
|
* \param ciphertext_size Size of the ciphertext buffer in bytes. This
|
|
* must be appropriate for the selected algorithm
|
|
* and key:
|
|
* - A sufficient output size is
|
|
* PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg,
|
|
* plaintext_length) where key_type is the type
|
|
* of key.
|
|
* - PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(
|
|
* plaintext_length) evaluates to the maximum
|
|
* ciphertext size of any supported AEAD
|
|
* encryption.
|
|
* \param[out] ciphertext_length On success, the size of the output in the
|
|
* ciphertext buffer.
|
|
*
|
|
* \retval #PSA_SUCCESS Success.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
|
* \p alg is not supported.
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
|
* ciphertext_size is too small.
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
|
*/
|
|
psa_status_t mbedtls_psa_aead_encrypt(
|
|
const psa_key_attributes_t *attributes,
|
|
const uint8_t *key_buffer, size_t key_buffer_size,
|
|
psa_algorithm_t alg,
|
|
const uint8_t *nonce, size_t nonce_length,
|
|
const uint8_t *additional_data, size_t additional_data_length,
|
|
const uint8_t *plaintext, size_t plaintext_length,
|
|
uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length );
|
|
|
|
/**
|
|
* \brief Process an authenticated decryption operation.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* aead_decrypt entry point. This function behaves as an aead_decrypt
|
|
* entry point as defined in the PSA driver interface specification for
|
|
* transparent drivers.
|
|
*
|
|
* \param[in] attributes The attributes of the key to use for the
|
|
* operation.
|
|
* \param[in] key_buffer The buffer containing the key context.
|
|
* \param key_buffer_size Size of the \p key_buffer buffer in bytes.
|
|
* \param alg The AEAD algorithm to compute.
|
|
* \param[in] nonce Nonce or IV to use.
|
|
* \param nonce_length Size of the nonce buffer in bytes. This must
|
|
* be appropriate for the selected algorithm.
|
|
* The default nonce size is
|
|
* PSA_AEAD_NONCE_LENGTH(key_type, alg) where
|
|
* key_type is the type of key.
|
|
* \param[in] additional_data Additional data that has been authenticated
|
|
* but not encrypted.
|
|
* \param additional_data_length Size of additional_data in bytes.
|
|
* \param[in] ciphertext Data that has been authenticated and
|
|
* encrypted. For algorithms where the encrypted
|
|
* data and the authentication tag are defined
|
|
* as separate inputs, the buffer contains
|
|
* encrypted data followed by the authentication
|
|
* tag.
|
|
* \param ciphertext_length Size of ciphertext in bytes.
|
|
* \param[out] plaintext Output buffer for the decrypted data.
|
|
* \param plaintext_size Size of the plaintext buffer in bytes. This
|
|
* must be appropriate for the selected algorithm
|
|
* and key:
|
|
* - A sufficient output size is
|
|
* PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg,
|
|
* ciphertext_length) where key_type is the
|
|
* type of key.
|
|
* - PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(
|
|
* ciphertext_length) evaluates to the maximum
|
|
* plaintext size of any supported AEAD
|
|
* decryption.
|
|
* \param[out] plaintext_length On success, the size of the output in the
|
|
* plaintext buffer.
|
|
*
|
|
* \retval #PSA_SUCCESS Success.
|
|
* \retval #PSA_ERROR_INVALID_SIGNATURE
|
|
* The cipher is not authentic.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
|
* \p alg is not supported.
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
|
* plaintext_size is too small.
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
|
*/
|
|
psa_status_t mbedtls_psa_aead_decrypt(
|
|
const psa_key_attributes_t *attributes,
|
|
const uint8_t *key_buffer, size_t key_buffer_size,
|
|
psa_algorithm_t alg,
|
|
const uint8_t *nonce, size_t nonce_length,
|
|
const uint8_t *additional_data, size_t additional_data_length,
|
|
const uint8_t *ciphertext, size_t ciphertext_length,
|
|
uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length );
|
|
|
|
/** Set the key for a multipart authenticated encryption operation.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* aead_encrypt_setup entry point. This function behaves as an
|
|
* aead_encrypt_setup entry point as defined in the PSA driver interface
|
|
* specification for transparent drivers.
|
|
*
|
|
* 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 mbedtls_psa_aead_encrypt_setup() to specify the algorithm and key.
|
|
* -# If needed, call mbedtls_psa_aead_set_lengths() to specify the length of
|
|
* the inputs to the subsequent calls to mbedtls_psa_aead_update_ad() and
|
|
* mbedtls_psa_aead_update(). See the documentation of mbedtls_psa_aead_set_lengths()
|
|
* for details.
|
|
* -# Call either psa_aead_generate_nonce() or
|
|
* mbedtls_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 mbedtls_psa_aead_update_ad() zero, one or more times, passing a fragment
|
|
* of the non-encrypted additional authenticated data each time.
|
|
* -# Call mbedtls_psa_aead_update() zero, one or more times, passing a fragment
|
|
* of the message to encrypt each time.
|
|
* -# Call mbedtls_psa_aead_finish().
|
|
*
|
|
* If an error occurs at any step after a call to mbedtls_psa_aead_encrypt_setup(),
|
|
* the operation will need to be reset by a call to mbedtls_psa_aead_abort(). The
|
|
* application may call mbedtls_psa_aead_abort() at any time after the operation
|
|
* has been initialized.
|
|
*
|
|
* After a successful call to mbedtls_psa_aead_encrypt_setup(), the application must
|
|
* eventually terminate the operation. The following events terminate an
|
|
* operation:
|
|
* - A successful call to mbedtls_psa_aead_finish().
|
|
* - A call to mbedtls_psa_aead_abort().
|
|
*
|
|
* \param[in,out] operation The operation object to set up. It must have
|
|
* been initialized as per the documentation for
|
|
* #mbedtls_psa_aead_operation_t and not yet in use.
|
|
* \param[in] attributes The attributes of the key to use for the
|
|
* operation.
|
|
* \param[in] key_buffer The buffer containing the key context.
|
|
* \param key_buffer_size Size of the \p key_buffer buffer in bytes.
|
|
* \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).
|
|
* \retval #PSA_ERROR_INVALID_HANDLE
|
|
* \retval #PSA_ERROR_NOT_PERMITTED
|
|
* \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
|
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
|
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
|
* \retval #PSA_ERROR_STORAGE_FAILURE
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* 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.
|
|
*/
|
|
psa_status_t mbedtls_psa_aead_encrypt_setup(psa_aead_operation_t *operation,
|
|
const psa_key_attributes_t *attributes,
|
|
const uint8_t *key_buffer, size_t key_buffer_size,
|
|
psa_algorithm_t alg);
|
|
|
|
/** Set the key for a multipart authenticated decryption operation.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* aead_decrypt_setup entry point. This function behaves as an
|
|
* aead_decrypt_setup entry point as defined in the PSA driver interface
|
|
* specification for transparent drivers.
|
|
*
|
|
* 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 mbedtls_psa_aead_decrypt_setup() to specify the algorithm and key.
|
|
* -# If needed, call mbedtls_psa_aead_set_lengths() to specify the length of the
|
|
* inputs to the subsequent calls to mbedtls_psa_aead_update_ad() and
|
|
* mbedtls_psa_aead_update(). See the documentation of mbedtls_psa_aead_set_lengths()
|
|
* for details.
|
|
* -# Call mbedtls_psa_aead_set_nonce() with the nonce for the decryption.
|
|
* -# Call mbedtls_psa_aead_update_ad() zero, one or more times, passing a fragment
|
|
* of the non-encrypted additional authenticated data each time.
|
|
* -# Call mbedtls_psa_aead_update() zero, one or more times, passing a fragment
|
|
* of the ciphertext to decrypt each time.
|
|
* -# Call mbedtls_psa_aead_verify().
|
|
*
|
|
* If an error occurs at any step after a call to mbedtls_psa_aead_decrypt_setup(),
|
|
* the operation will need to be reset by a call to mbedtls_psa_aead_abort(). The
|
|
* application may call mbedtls_psa_aead_abort() at any time after the operation
|
|
* has been initialized.
|
|
*
|
|
* After a successful call to mbedtls_psa_aead_decrypt_setup(), the application must
|
|
* eventually terminate the operation. The following events terminate an
|
|
* operation:
|
|
* - A successful call to mbedtls_psa_aead_verify().
|
|
* - A call to mbedtls_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[in] attributes The attributes of the key to use for the
|
|
* operation.
|
|
* \param[in] key_buffer The buffer containing the key context.
|
|
* \param key_buffer_size Size of the \p key_buffer buffer in bytes.
|
|
* \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).
|
|
* \retval #PSA_ERROR_INVALID_HANDLE
|
|
* \retval #PSA_ERROR_NOT_PERMITTED
|
|
* \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
|
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
|
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
|
* \retval #PSA_ERROR_STORAGE_FAILURE
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* 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.
|
|
*/
|
|
psa_status_t mbedtls_psa_aead_decrypt_setup(psa_aead_operation_t *operation,
|
|
const psa_key_attributes_t *attributes,
|
|
const uint8_t *key_buffer, size_t key_buffer_size,
|
|
psa_algorithm_t alg);
|
|
|
|
/** Set the nonce for an authenticated encryption or decryption operation.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* psa_aead_set_nonce entry point. This function behaves as an
|
|
* psa_aead_set_nonce entry point as defined in the PSA driver interface
|
|
* specification for transparent drivers.
|
|
*
|
|
* This function sets the nonce for the authenticated
|
|
* encryption or decryption operation.
|
|
*
|
|
* The application must call mbedtls_psa_aead_encrypt_setup() or
|
|
* mbedtls_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 mbedtls_psa_aead_abort().
|
|
*
|
|
* \note When encrypting, applications should use mbedtls_psa_aead_generate_nonce()
|
|
* instead of this function, unless implementing a protocol that requires
|
|
* a non-random IV.
|
|
*
|
|
* \param[in,out] operation Active AEAD operation.
|
|
* \param[in] nonce Buffer containing the nonce to use.
|
|
* \param nonce_length Size of the nonce in bytes.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* Success.
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* The operation state is not valid (it must be active, with no nonce
|
|
* set).
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* The size of \p nonce is not acceptable for the chosen algorithm.
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
|
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
|
* \retval #PSA_ERROR_STORAGE_FAILURE
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* 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.
|
|
*/
|
|
psa_status_t mbedtls_psa_aead_set_nonce(psa_aead_operation_t *operation,
|
|
const uint8_t *nonce,
|
|
size_t nonce_length);
|
|
|
|
/** Declare the lengths of the message and additional data for AEAD.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* psa_aead_set_lengths entry point. This function behaves as an
|
|
* psa_aead_set_lengths entry point as defined in the PSA driver interface
|
|
* specification for transparent drivers.
|
|
*
|
|
* The application must call 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.
|
|
*
|
|
* You may call this function before or after setting the nonce with
|
|
* mbedtls_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 mbedtls_psa_aead_abort().
|
|
*
|
|
* \param[in,out] operation Active AEAD operation.
|
|
* \param ad_length Size of the non-encrypted additional
|
|
* authenticated data in bytes.
|
|
* \param plaintext_length Size of the plaintext to encrypt in bytes.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* Success.
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* The operation state is not valid (it must be active, and
|
|
* mbedtls_psa_aead_update_ad() and mbedtls_psa_aead_update() must not have been
|
|
* called yet).
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* At least one of the lengths is not acceptable for the chosen
|
|
* algorithm.
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
|
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* 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.
|
|
*/
|
|
psa_status_t mbedtls_psa_aead_set_lengths(psa_aead_operation_t *operation,
|
|
size_t ad_length,
|
|
size_t plaintext_length);
|
|
|
|
/** Pass additional data to an active AEAD operation.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* aead_update_ad entry point. This function behaves as an aead_update_ad
|
|
* entry point as defined in the PSA driver interface specification for
|
|
* transparent drivers.
|
|
*
|
|
* 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 mbedtls_psa_aead_update().
|
|
*
|
|
* Before calling this function, you must:
|
|
* 1. Call either mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup().
|
|
* 2. Set the nonce with psa_aead_generate_nonce() or
|
|
* mbedtls_psa_aead_set_nonce().
|
|
*
|
|
* If this function returns an error status, the operation enters an error
|
|
* state and must be aborted by calling mbedtls_psa_aead_abort().
|
|
*
|
|
* \warning When decrypting, until mbedtls_psa_aead_verify() has returned #PSA_SUCCESS,
|
|
* there is no guarantee that the input is valid. Therefore, until
|
|
* you have called mbedtls_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 mbedtls_psa_aead_verify() returns an error status.
|
|
*
|
|
* \note For the time being #PSA_ALG_CCM and #PSA_ALG_GCM require the entire
|
|
* additional data to be passed in in one go, i.e. only call
|
|
* mbedtls_mbedtls_psa_aead_update_ad() once.
|
|
*
|
|
* \param[in,out] operation Active AEAD operation.
|
|
* \param[in] input Buffer containing the fragment of
|
|
* additional data.
|
|
* \param input_length Size of the \p input buffer in bytes.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* Success.
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* The operation state is not valid (it must be active, have a nonce
|
|
* set, have lengths set if required by the algorithm, and
|
|
* mbedtls_psa_aead_update() must not have been called yet).
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* The total input length overflows the additional data length that
|
|
* was previously specified with mbedtls_psa_aead_set_lengths().
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
|
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
|
* \retval #PSA_ERROR_STORAGE_FAILURE
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* 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.
|
|
*/
|
|
psa_status_t mbedtls_psa_aead_update_ad(psa_aead_operation_t *operation,
|
|
const uint8_t *input,
|
|
size_t input_length);
|
|
|
|
/** Encrypt or decrypt a message fragment in an active AEAD operation.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* aead_update entry point. This function behaves as an aead_update entry
|
|
* point as defined in the PSA driver interface specification for
|
|
* transparent drivers.
|
|
*
|
|
* Before calling this function, you must:
|
|
* 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 psa_aead_generate_nonce() or
|
|
* 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 operation enters an error
|
|
* state and must be aborted by calling mbedtls_psa_aead_abort().
|
|
*
|
|
* \warning When decrypting, until mbedtls_psa_aead_verify() has returned
|
|
* #PSA_SUCCESS, there is no guarantee that the input is valid.
|
|
* Therefore, until you have called mbedtls_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 mbedtls_psa_aead_update(), mbedtls_psa_aead_finish() or
|
|
* mbedtls_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.
|
|
*
|
|
* \note For the time being #PSA_ALG_CCM and #PSA_ALG_GCM require the entire
|
|
* data to be passed in in one go, i.e. only call
|
|
* mbedtls_mbedtls_psa_aead_update() once.
|
|
*
|
|
* \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 at least
|
|
* #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg,
|
|
* \p input_length) where \c alg is the
|
|
* algorithm that is being calculated.
|
|
* \param[out] output_length On success, the number of bytes
|
|
* that make up the returned output.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* Success.
|
|
* \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).
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
|
* The size of the \p output buffer is too small.
|
|
* You can determine a sufficient buffer size by calling
|
|
* #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg, \p input_length)
|
|
* where \c alg is the algorithm that is being calculated.
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* The total length of input to mbedtls_psa_aead_update_ad() so far is
|
|
* less than the additional data length that was previously
|
|
* specified with mbedtls_psa_aead_set_lengths().
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* The total input length overflows the plaintext length that
|
|
* was previously specified with mbedtls_psa_aead_set_lengths().
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
|
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
|
* \retval #PSA_ERROR_STORAGE_FAILURE
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* 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.
|
|
*/
|
|
psa_status_t mbedtls_psa_aead_update(psa_aead_operation_t *operation,
|
|
const uint8_t *input,
|
|
size_t input_length,
|
|
uint8_t *output,
|
|
size_t output_size,
|
|
size_t *output_length);
|
|
|
|
/** Finish encrypting a message in an AEAD operation.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* aead_finish entry point. This function behaves as an aead_finish entry
|
|
* point as defined in the PSA driver interface specification for
|
|
* transparent drivers.
|
|
*
|
|
* The operation must have been set up 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. Its length is always
|
|
* #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
|
|
* that the operation performs.
|
|
*
|
|
* When this function returns successfuly, the operation becomes inactive.
|
|
* If this function returns an error status, the operation enters an error
|
|
* state and must be aborted by calling mbedtls_psa_aead_abort().
|
|
*
|
|
* \param[in,out] operation Active AEAD operation.
|
|
* \param[out] ciphertext Buffer where the last part of the ciphertext
|
|
* is to be written.
|
|
* \param ciphertext_size Size of the \p ciphertext buffer in bytes.
|
|
* This must be at least
|
|
* #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg) where
|
|
* \c alg is the algorithm that is being
|
|
* calculated.
|
|
* \param[out] ciphertext_length On success, the number of bytes of
|
|
* returned ciphertext.
|
|
* \param[out] tag Buffer where the authentication tag is
|
|
* to be written.
|
|
* \param tag_size Size of the \p tag buffer in bytes.
|
|
* This must be at least
|
|
* #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is
|
|
* the algorithm that is being calculated.
|
|
* \param[out] tag_length On success, the number of bytes
|
|
* that make up the returned tag.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* Success.
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* The operation state is not valid (it must be an active encryption
|
|
* operation with a nonce set).
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
|
* The size of the \p ciphertext or \p tag buffer is too small.
|
|
* You can determine a sufficient buffer size for \p ciphertext by
|
|
* calling #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg)
|
|
* where \c alg is the algorithm that is being calculated.
|
|
* You can determine a sufficient buffer size for \p tag by
|
|
* calling #PSA_AEAD_TAG_LENGTH(\c alg).
|
|
* \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().
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* The total length of input to mbedtls_psa_aead_update() so far is
|
|
* less than the plaintext length that was previously
|
|
* specified with mbedtls_psa_aead_set_lengths().
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
|
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
|
* \retval #PSA_ERROR_STORAGE_FAILURE
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* 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.
|
|
*/
|
|
psa_status_t mbedtls_psa_aead_finish(psa_aead_operation_t *operation,
|
|
uint8_t *ciphertext,
|
|
size_t ciphertext_size,
|
|
size_t *ciphertext_length,
|
|
uint8_t *tag,
|
|
size_t tag_size,
|
|
size_t *tag_length);
|
|
|
|
/** Finish authenticating and decrypting a message in an AEAD operation.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* aead_verify entry point. This function behaves as an aead_verify entry
|
|
* point as defined in the PSA driver interface specification for
|
|
* transparent drivers.
|
|
*
|
|
* The operation must have been set up with mbedtls_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 mbedtls_psa_aead_update_ad().
|
|
* - The ciphertext consisting of the concatenation of the inputs passed to
|
|
* preceding calls to mbedtls_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 successfuly, the operation becomes inactive.
|
|
* If this function returns an error status, the operation enters an error
|
|
* state and must be aborted by calling mbedtls_psa_aead_abort().
|
|
*
|
|
* \note Implementations shall make the best effort to ensure that the
|
|
* comparison between the actual tag and the expected tag is performed
|
|
* in constant time.
|
|
*
|
|
* \param[in,out] operation Active AEAD operation.
|
|
* \param[out] plaintext Buffer where the last part of the plaintext
|
|
* is to be written. This is the remaining data
|
|
* from previous calls to mbedtls_psa_aead_update()
|
|
* that could not be processed until the end
|
|
* of the input.
|
|
* \param plaintext_size Size of the \p plaintext buffer in bytes.
|
|
* This must be at least
|
|
* #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg) where
|
|
* \c alg is the algorithm that is being
|
|
* calculated.
|
|
* \param[out] plaintext_length On success, the number of bytes of
|
|
* returned plaintext.
|
|
* \param[in] tag Buffer containing the authentication tag.
|
|
* \param tag_length Size of the \p tag buffer in bytes.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* Success.
|
|
* \retval #PSA_ERROR_INVALID_SIGNATURE
|
|
* The calculations were successful, but the authentication tag is
|
|
* not correct.
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* The operation state is not valid (it must be an active decryption
|
|
* operation with a nonce set).
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
|
* The size of the \p plaintext buffer is too small.
|
|
* You can determine a sufficient buffer size for \p plaintext by
|
|
* calling #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg)
|
|
* where \c alg is the algorithm that is being calculated.
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* The total length of input to mbedtls_psa_aead_update_ad() so far is
|
|
* less than the additional data length that was previously
|
|
* specified with mbedtls_psa_aead_set_lengths().
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* The total length of input to mbedtls_psa_aead_update() so far is
|
|
* less than the plaintext length that was previously
|
|
* specified with psa_aead_set_lengths().
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
|
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
|
* \retval #PSA_ERROR_STORAGE_FAILURE
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* 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.
|
|
*/
|
|
psa_status_t mbedtls_psa_aead_verify(psa_aead_operation_t *operation,
|
|
uint8_t *plaintext,
|
|
size_t plaintext_size,
|
|
size_t *plaintext_length,
|
|
const uint8_t *tag,
|
|
size_t tag_length);
|
|
|
|
/** Abort an AEAD operation.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* aead_abort entry point. This function behaves as an aead_abort entry
|
|
* point as defined in the PSA driver interface specification for
|
|
* transparent drivers.
|
|
*
|
|
* 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
|
|
* mbedtls_psa_aead_encrypt_setup() or mbedtls_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 mbedtls_psa_aead_abort() after the operation has been
|
|
* terminated by a call to mbedtls_psa_aead_abort(), mbedtls_psa_aead_finish() or
|
|
* mbedtls_psa_aead_verify() is safe and has no effect.
|
|
*
|
|
* \param[in,out] operation Initialized AEAD operation.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
|
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* 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.
|
|
*/
|
|
psa_status_t mbedtls_psa_aead_abort(psa_aead_operation_t *operation);
|
|
|
|
|
|
#endif /* PSA_CRYPTO_AEAD */
|