sys/psa_crypto: Split subsystem definitions into separate files

Currently PSA backends cannot use other backends because the necessary
definitions are defined in a single big header file. This prevents us
from creating a generic HMAC backend based on the available hash
backends, as the hash context struct is not available when defining the
HMAC context struct.

Fix this by spliting the headers into separate files. This makes it
possible us use the hash context definitions without pulling in the
remaining context definitions.

Signed-off-by: Armin Wolf <[email protected]>

Author: Wer-Wolf

examples/advanced/psa_crypto/custom_atca_params.h

@@ -20,7 +20,9 @@
  *
  */
 #include "cryptoauthlib.h"
-#include "psa/crypto.h"
+#include "psa/asymmetric_signature/algorithm.h"
+#include "psa/key/lifetime.h"
+#include "psa/key/type.h"
 
 #ifdef __cplusplus
 extern "C" {

sys/include/psa_crypto/psa/aead/sizes.h

@@ -0,0 +1,293 @@
+/*
+ * Copyright (C) 2025 TU Dresden
+ * Copyright (C) 2021 HAW Hamburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+#pragma once
+
+/**
+ * @ingroup     sys_psa_crypto
+ * @{
+ *
+ * @file
+ * @brief       AEAD size definitions for the PSA Crypto API
+ *
+ * @author      Armin Wolf <[email protected]>
+ * @author      Lena Boeckmann <[email protected]>
+ *
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "algorithm.h"
+
+/**
+ * @brief   A sufficient plaintext buffer size for @ref psa_aead_decrypt(),
+ *          for any of the supported key types and AEAD algorithms.
+ *
+ * @details If the size of the plaintext buffer is at least this large,
+ *          it is guaranteed that @ref psa_aead_decrypt() will not fail due
+ *          to an insufficient buffer size.
+ *
+ *          See also @ref PSA_AEAD_DECRYPT_OUTPUT_SIZE().
+ *
+ * @param   ciphertext_length Size of the ciphertext in bytes.
+ */
+#define PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(ciphertext_length) \
+/* implementation-defined value */
+
+/**
+ * @brief   The length of a tag for an AEAD algorithm, in bytes.
+ *
+ * @details This is the size of the tag output from @ref psa_aead_finish().
+ *          If the size of the tag buffer is at least this large, it is guaranteed that
+ *          @ref psa_aead_finish() will not fail due to an insufficient tag buffer size.
+ *
+ *          See also @ref PSA_AEAD_TAG_MAX_SIZE.
+ *
+ * @param   key_type    The type of the AEAD key.
+ * @param   key_bits    The size of the AEAD key in bits.
+ * @param   alg         An AEAD algorithm: a value of type @ref psa_algorithm_t such that
+ *                      @ref PSA_ALG_IS_AEAD(@p alg) is true.
+ *
+ * @return  The tag length for the specified algorithm and key.
+ *          0 if the AEAD algorithm does not have an identified tag that can be distinguished from
+ *          the rest of the ciphertext.
+ *          0 if the AEAD algorithm is not recognized or not supported.
+ */
+#define PSA_AEAD_TAG_LENGTH(key_type, key_bits, alg)     \
+    (PSA_ALG_IS_AEAD(alg) ?                              \
+    (((alg) & 0x003f0000) >> 16) :                       \
+    ((void) (key_type), (void) (key_bits), 0))
+
+/**
+ * @brief   A sufficient buffer size for storing the tag output by @ref psa_aead_finish(),
+ *          for any of the supported key types and AEAD algorithms.
+ *
+ * @details If the size of the tag buffer is at least this large, it is guaranteed that
+ *          @ref psa_aead_finish() will not fail due to an insufficient buffer size.
+ *
+ *          See also @ref PSA_AEAD_TAG_LENGTH().
+ */
+#define PSA_AEAD_TAG_MAX_SIZE (16)
+
+/**
+ * @brief   A sufficient buffer size for storing the tag output by @ref psa_aead_finish(),
+ *          for AES key types and CCM algorithms.
+ *
+ * @details If the size of the tag buffer is at least this large, it is guaranteed that
+ *          @ref psa_aead_finish() will not fail due to an insufficient buffer size.
+ *
+ *          See also @ref PSA_AEAD_TAG_LENGTH().
+ */
+#define PSA_AES_CCM_TAG_MAX_SIZE (16)
+
+/**
+ * @brief   A sufficient plaintext buffer size for @ref psa_aead_decrypt(), in bytes.
+ *
+ * @details If the size of the plaintext buffer is at least this large, it is guaranteed that
+ *          @ref psa_aead_decrypt() will not fail due to an insufficient buffer size. Depending on
+ *          the algorithm, the actual size of the plaintext might be smaller.
+ *
+ *          See also @ref PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE.
+ *
+ * @param   key_type            A symmetric key type that is compatible with algorithm alg.
+ * @param   alg                 An AEAD algorithm: a value of type @ref psa_algorithm_t
+ *                              such that @ref PSA_ALG_IS_AEAD(@p alg) is true.
+ * @param   ciphertext_length   Size of the ciphertext in bytes.
+ *
+ * @return  The AEAD plaintext size for the specified key type and algorithm.
+ *          0 if the key type or AEAD algorithm is not recognized, not supported or the parameters
+ *          are incompatible.
+ */
+#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) \
+        (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 &&                  \
+            ((ciphertext_length) > PSA_AEAD_TAG_LENGTH(key_type, 0, alg)) ?   \
+        (ciphertext_length) - PSA_AEAD_TAG_LENGTH(key_type, 0, alg) : 0)
+
+/**
+ * @brief   A sufficient ciphertext buffer size for @ref psa_aead_encrypt(),
+ *          for any of the supported key types and AEAD algorithms.
+ *
+ * @details If the size of the ciphertext buffer is at least this large,
+ *          it is guaranteed that @ref psa_aead_encrypt() will not fail due to an insufficient
+ *          buffer size.
+ *
+ *          See also @ref PSA_AEAD_ENCRYPT_OUTPUT_SIZE().
+ *
+ * @param   plaintext_length Size of the plaintext in bytes.
+ */
+#define PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(plaintext_length) \
+       ((plaintext_length) + PSA_AEAD_TAG_MAX_SIZE)
+
+/**
+ * @brief   A sufficient ciphertext buffer size for @ref psa_aead_encrypt(), in bytes.
+ *
+ * @details If the size of the ciphertext buffer is at least this large, it is guaranteed that
+ *          @ref psa_aead_encrypt() will not fail due to an insufficient buffer size. Depending on
+ *          the algorithm, the actual size of the ciphertext might be smaller.
+ *
+ *          See also @ref PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE.
+ *
+ * @param   key_type            A symmetric key type that is compatible with algorithm alg.
+ * @param   alg                 An AEAD algorithm: a value of type @ref psa_algorithm_t such
+ *                              that @ref PSA_ALG_IS_AEAD(alg) is true.
+ * @param   plaintext_length    Size of the plaintext in bytes.
+ *
+ * @return  The AEAD ciphertext size for the specified key type and algorithm.
+ *          0 if the key type or AEAD algorithm is not recognized, not supported or the parameters
+ *          are incompatible.
+ */
+#define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, plaintext_length) \
+        (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 ?                  \
+        (plaintext_length) + PSA_AEAD_TAG_LENGTH(key_type, 0, alg) : 0)
+
+/**
+ * @brief   A sufficient ciphertext buffer size for @ref psa_aead_finish(),
+ *          for any of the supported key types and AEAD algorithms.
+ *
+ * @details If the size of the ciphertext buffer is at least this large, it is guaranteed that
+ *          @ref psa_aead_finish() will not fail due to an insufficient ciphertext buffer size.
+ *
+ *          See also @ref PSA_AEAD_FINISH_OUTPUT_SIZE().
+ */
+#define PSA_AEAD_FINISH_OUTPUT_MAX_SIZE /* implementation-defined value */
+
+/**
+ * @brief   A sufficient ciphertext buffer size for @ref psa_aead_finish().
+ *
+ * @details If the size of the ciphertext buffer is at least this large, it is guaranteed that
+ *          @ref psa_aead_finish() will not fail due to an insufficient ciphertext buffer size. The
+ *          actual size of the output might be smaller in any given call.
+ *
+ *          See also @ref PSA_AEAD_FINISH_OUTPUT_MAX_SIZE.
+ *
+ * @param   key_type    A symmetric key type that is compatible with algorithm alg.
+ * @param   alg         An AEAD algorithm: a value of type @ref psa_algorithm_t such that
+ *                      @ref PSA_ALG_IS_AEAD(@p alg) is true.
+ *
+ * @return  A sufficient ciphertext buffer size for the specified key type and algorithm.
+ *          If the key type or AEAD algorithm is not recognized, or the parameters are incompatible,
+ *          return 0. An implementation can return either 0 or a correct size for a key type and
+ *          AEAD algorithm that it recognizes, but does not support.
+ */
+#define PSA_AEAD_FINISH_OUTPUT_SIZE(key_type, alg) \
+/* implementation-defined value */
+
+/**
+ * @brief   The default nonce size for an AEAD algorithm, in bytes.
+ *
+ * @details If the size of the nonce buffer is at least this large, it is guaranteed that
+ *          @ref psa_aead_generate_nonce() will not fail due to an insufficient buffer size.
+ *
+ *          For most AEAD algorithms, @ref PSA_AEAD_NONCE_LENGTH() evaluates to the exact size of
+ *          the nonce generated by @ref psa_aead_generate_nonce().
+ *
+ *          See also @ref PSA_AEAD_NONCE_MAX_SIZE.
+ *
+ * @param   key_type    A symmetric key type that is compatible with algorithm alg.
+ * @param   alg         An AEAD algorithm: a value of type @ref psa_algorithm_t such that
+ *                      @ref PSA_ALG_IS_AEAD(@p alg) is true.
+ *
+ * @return  The default nonce size for the specified key type and algorithm.
+ *          0 if the key type or AEAD algorithm is not recognized, not supported or the parameters
+ *          are incompatible.
+ */
+#define PSA_AEAD_NONCE_LENGTH(key_type, alg) \
+    ((PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) == 16 && \
+        ((PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG(alg) == PSA_ALG_CCM) || \
+        (PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG(alg) == PSA_ALG_CCM))) || \
+        (key_type == PSA_KEY_TYPE_CHACHA20 && \
+        PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG(alg) == PSA_ALG_CHACHA20_POLY1305) ? \
+        12 : 0)
+
+/**
+ * @brief   A sufficient buffer size for storing the nonce generated by
+ *          @ref psa_aead_generate_nonce(), for any of the supported key types and AEAD algorithms.
+ *
+ * @details If the size of the nonce buffer is at least this large, it is guaranteed that
+ *          @ref psa_aead_generate_nonce() will not fail due to an insufficient buffer size.
+ *
+ *          See also @ref PSA_AEAD_NONCE_LENGTH().
+ */
+#define PSA_AEAD_NONCE_MAX_SIZE (13)
+
+/**
+ * @brief   A sufficient output buffer size for @ref psa_aead_update(), for any of the supported key
+ *          types and AEAD algorithms.
+ *
+ * @details If the size of the output buffer is at least this large, it is guaranteed that
+ *          @ref psa_aead_update() will not fail due to an insufficient buffer size.
+ *
+ *          See also @ref PSA_AEAD_UPDATE_OUTPUT_SIZE().
+ *
+ * @param   input_length Size of the input in bytes.
+ */
+#define PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(input_length) \
+/* implementation-defined value */
+
+/**
+ * @brief   A sufficient output buffer size for @ref psa_aead_update().
+ *
+ * @details If the size of the output buffer is at least this large, it is guaranteed that
+ *          @ref psa_aead_update() will not fail due to an insufficient buffer size. The actual
+ *          size of the output might be smaller in any given call.
+ *
+ *          See also @ref PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE.
+ *
+ * @param   key_type        A symmetric key type that is compatible with algorithm alg.
+ * @param   alg             An AEAD algorithm: a value of type @ref psa_algorithm_t such that
+ *                          @ref PSA_ALG_IS_AEAD(@p alg) is true.
+ * @param   input_length    Size of the input in bytes.
+ *
+ * @return  A sufficient output buffer size for the specified key type and algorithm.
+ *          0 if the key type or AEAD algorithm is not recognized, not supported or the parameters
+ *          are incompatible.
+ */
+#define PSA_AEAD_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) \
+/* implementation-defined value */
+
+/**
+ * @brief   A sufficient output buffer size for @ref psa_aead_update(), for any of the supported key
+ *          types and AEAD algorithms.
+ *
+ * @details If the size of the output buffer is at least this large, it is guaranteed that
+ *          @ref psa_aead_update() will not fail due to an insufficient buffer size.
+ *
+ *          See also @ref PSA_AEAD_UPDATE_OUTPUT_SIZE().
+ *
+ * @param   input_length Size of the input in bytes.
+ */
+#define PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE /* implementation-defined value */
+
+/**
+ * @brief   A sufficient plaintext buffer size for @ref psa_aead_verify(), in bytes.
+ *
+ * @details If the size of the plaintext buffer is at least this large, it is guaranteed that
+ *          @ref psa_aead_verify() will not fail due to an insufficient plaintext buffer size. The
+ *          actual size of the output might be smaller in any given call.
+ *
+ *          See also @ref PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE.
+ *
+ * @param   key_type    A symmetric key type that is compatible with algorithm alg.
+ * @param   alg         An AEAD algorithm: a value of type @ref psa_algorithm_t such that
+ *                      @ref PSA_ALG_IS_AEAD(@p alg) is true.
+ *
+ * @return  A sufficient plaintext buffer size for the specified key type and algorithm.
+ *          0 if the key type or AEAD algorithm is not recognized, not supported or the parameters
+ *          are incompatible.
+ */
+#define PSA_AEAD_VERIFY_OUTPUT_SIZE(key_type, alg) \
+/* implementation-defined value */
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */

sys/include/psa_crypto/psa/aead/types.h

@@ -0,0 +1,92 @@
+/*
+ * Copyright (C) 2025 TU Dresden
+ * Copyright (C) 2021 HAW Hamburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+#pragma once
+
+/**
+ * @ingroup     sys_psa_crypto
+ * @{
+ *
+ * @file
+ * @brief       AEAD type definitions for the PSA Crypto API
+ *
+ * @author      Armin Wolf <[email protected]>
+ * @author      Lena Boeckmann <[email protected]>
+ *
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief   Structure storing an AEAD operation context
+ *
+ * @note    Not implemented, yet
+ */
+struct psa_aead_operation_s {
+    int dummy;  /**< Not implemented, yet */
+};
+
+/* These are all temporarily defined as some numeric type to prevent errors at compile time.*/
+/**
+ * @brief   The type of the state object for multi-part AEAD operations.
+ *
+ * @details Before calling any function on an AEAD operation object, the application must
+ *          initialize it by any of the following means:
+ *          - Set the object to all-bits-zero, for example:
+ *            @code
+ *            @ref psa_aead_operation_t operation;
+ *            memset(&operation, 0, sizeof(operation));
+ *            @endcode
+ *          - Initialize the object to logical zero values by declaring the object as static
+ *            or global without an explicit initializer, for example:
+ *            @code
+ *            static @ref psa_aead_operation_t operation;
+ *            @endcode
+ *          - Initialize the object to the initializer @ref PSA_AEAD_OPERATION_INIT, for example:
+ *            @code
+ *            @ref psa_aead_operation_t operation = @ref PSA_AEAD_OPERATION_INIT;
+ *            @endcode
+ *          - Assign the result of the function @ref psa_aead_operation_init() to the object,
+ *            for example:
+ *            @code
+ *            @ref psa_aead_operation_t operation;
+ *            operation = @ref psa_aead_operation_init();
+ *            @endcode
+ *
+ *          This is an implementation-defined type. Applications that make assumptions about the
+ *          content of this object will result in in implementation-specific behavior, and are
+ *          non-portable.
+ */
+typedef struct psa_aead_operation_s psa_aead_operation_t;
+
+/**
+ * @brief   This macro returns a suitable initializer for an AEAD operation object of type
+ *          @ref psa_aead_operation_t.
+ */
+#define PSA_AEAD_OPERATION_INIT { 0 }
+
+/**
+ * @brief   Return an initial value for an AEAD operation object.
+ *
+ * @return  psa_aead_operation_t
+ */
+static inline psa_aead_operation_t psa_aead_operation_init(void)
+{
+    const psa_aead_operation_t v = PSA_AEAD_OPERATION_INIT;
+
+    return v;
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */