Squashed 'lib/mbedtls/external/mbedtls/' content from commit 2ca6c285a0dd
git-subtree-dir: lib/mbedtls/external/mbedtls
git-subtree-split: 2ca6c285a0dd3f33982dd57299012dacab1ff206
diff --git a/library/psa_crypto_aead.h b/library/psa_crypto_aead.h
new file mode 100644
index 0000000..a339219
--- /dev/null
+++ b/library/psa_crypto_aead.h
@@ -0,0 +1,499 @@
+/*
+ * PSA AEAD driver entry points
+ */
+/*
+ * Copyright The Mbed TLS Contributors
+ * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
+ */
+
+#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 \emptydescription
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ * ciphertext_size is too small.
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
+ */
+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 \emptydescription
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ * plaintext_size is too small.
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
+ */
+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.
+ *
+ * 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.
+ *
+ * \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.
+ It must be consistent with the size in bits
+ recorded in \p attributes.
+ * \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_INVALID_ARGUMENT
+ * An invalid block length was supplied.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \p alg is not supported.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * Failed to allocate memory for key material
+ */
+psa_status_t mbedtls_psa_aead_encrypt_setup(
+ mbedtls_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.
+ *
+ * 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.
+ *
+ * \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.
+ It must be consistent with the size in bits
+ recorded in \p attributes.
+ * \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_INVALID_ARGUMENT
+ * An invalid block length was supplied.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \p alg is not supported.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * Failed to allocate memory for key material
+ */
+psa_status_t mbedtls_psa_aead_decrypt_setup(
+ mbedtls_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 aead_set_nonce
+ * entry point. This function behaves as an 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 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().
+ *
+ * \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_INVALID_ARGUMENT
+ * The size of \p nonce is not acceptable for the chosen algorithm.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * Algorithm previously set is not supported in this configuration of
+ * the library.
+ */
+psa_status_t mbedtls_psa_aead_set_nonce(
+ mbedtls_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 aead_set_lengths
+ * entry point. This function behaves as an aead_set_lengths entry point
+ * as defined in the PSA driver interface specification for transparent
+ * drivers.
+ *
+ * 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().
+ *
+ * \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_INVALID_ARGUMENT
+ * At least one of the lengths is not acceptable for the chosen
+ * algorithm.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * Algorithm previously set is not supported in this configuration of
+ * the library.
+ */
+psa_status_t mbedtls_psa_aead_set_lengths(
+ mbedtls_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.
+ *
+ * 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().
+ *
+ * \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_NOT_SUPPORTED
+ * Algorithm previously set is not supported in this configuration of
+ * the library.
+ */
+psa_status_t mbedtls_psa_aead_update_ad(
+ mbedtls_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, 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.
+ *
+ * \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.
+ */
+psa_status_t mbedtls_psa_aead_update(
+ mbedtls_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 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.
+ *
+ * \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 appropriate for the selected
+ * algorithm and key:
+ * - A sufficient output size is
+ * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c key_type,
+ * \c alg) 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_FINISH_OUTPUT_MAX_SIZE evaluates to
+ * the maximum output size of any supported AEAD
+ * algorithm.
+ * \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 appropriate for the selected
+ * algorithm and key:
+ * - The exact tag size is #PSA_AEAD_TAG_LENGTH(\c
+ * key_type, \c key_bits, \c alg) where
+ * \c key_type and \c key_bits are the type and
+ * bit-size of the key, and \c alg are the
+ * algorithm that were used in the call to
+ * mbedtls_psa_aead_encrypt_setup().
+ * - #PSA_AEAD_TAG_MAX_SIZE evaluates to the
+ * maximum tag size of any supported AEAD
+ * algorithm.
+ * \param[out] tag_length On success, the number of bytes
+ * that make up the returned tag.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ * The size of the \p tag buffer is too small.
+ * #PSA_AEAD_TAG_LENGTH(\c key_type, key_bits, \c alg) or
+ * #PSA_AEAD_TAG_MAX_SIZE can be used to determine the required \p tag
+ * buffer size.
+ */
+psa_status_t mbedtls_psa_aead_finish(
+ mbedtls_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);
+
+/** 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 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.
+ *
+ * \param[in,out] operation Initialized AEAD operation.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ */
+psa_status_t mbedtls_psa_aead_abort(
+ mbedtls_psa_aead_operation_t *operation);
+
+#endif /* PSA_CRYPTO_AEAD_H */