sys/psa_crypto: Rework Headers

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
+
+/** @} */