Add support for the Ascon family of algorithms

doc/crypto/api.db/psa/crypto.h

@@ -24,6 +24,7 @@ typedef uint32_t psa_pake_primitive_t;
 typedef uint8_t psa_pake_primitive_type_t;
 typedef uint8_t psa_pake_role_t;
 typedef uint8_t psa_pake_step_t;
+typedef /* implementation-defined type */ psa_xof_operation_t;
 typedef struct psa_custom_key_parameters_t {
     uint32_t flags;
 } psa_custom_key_parameters_t;
@@ -59,6 +60,10 @@ typedef struct psa_custom_key_parameters_t {
     /* specification-defined value */
 #define PSA_ALG_AES_MMO_ZIGBEE ((psa_algorithm_t)0x02000007)
 #define PSA_ALG_ANY_HASH ((psa_algorithm_t)0x020000ff)
+#define PSA_ALG_ASCON_AEAD128 ((psa_algorithm_t)0x05100700)
+#define PSA_ALG_ASCON_CXOF128 ((psa_algorithm_t)0x0D008300)
+#define PSA_ALG_ASCON_HASH256 ((psa_algorithm_t)0x02000020)
+#define PSA_ALG_ASCON_XOF128 ((psa_algorithm_t)0x0D000300)
 #define PSA_ALG_AT_LEAST_THIS_LENGTH_MAC(mac_alg, min_mac_length) \
     /* specification-defined value */
 #define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x03c00100)
@@ -134,6 +139,7 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_ALG_IS_TLS12_PRF(alg) /* specification-defined value */
 #define PSA_ALG_IS_TLS12_PSK_TO_MS(alg) /* specification-defined value */
 #define PSA_ALG_IS_WILDCARD(alg) /* specification-defined value */
+#define PSA_ALG_IS_XOF(alg) /* specification-defined value */
 #define PSA_ALG_JPAKE(hash_alg) /* specification-defined value */
 #define PSA_ALG_KEY_AGREEMENT(ka_alg, kdf_alg) \
     /* specification-defined value */
@@ -158,6 +164,8 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_ALG_SHA3_256 ((psa_algorithm_t)0x02000011)
 #define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x02000012)
 #define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x02000013)
+#define PSA_ALG_SHAKE128 ((psa_algorithm_t)0x0D000100)
+#define PSA_ALG_SHAKE256 ((psa_algorithm_t)0x0D000200)
 #define PSA_ALG_SHAKE256_512 ((psa_algorithm_t)0x02000015)
 #define PSA_ALG_SHA_1 ((psa_algorithm_t)0x02000005)
 #define PSA_ALG_SHA_224 ((psa_algorithm_t)0x02000008)
@@ -180,6 +188,7 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \
     /* specification-defined value */
 #define PSA_ALG_XCHACHA20_POLY1305 ((psa_algorithm_t)0x05100600)
+#define PSA_ALG_XOF_HAS_CONTEXT(alg) /* specification-defined value */
 #define PSA_ALG_XTS ((psa_algorithm_t)0x0440ff00)
 #define PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE \
     /* implementation-defined value */
@@ -283,6 +292,7 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_KEY_TYPE_AES ((psa_key_type_t)0x2400)
 #define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x2002)
 #define PSA_KEY_TYPE_ARIA ((psa_key_type_t)0x2406)
+#define PSA_KEY_TYPE_ASCON ((psa_key_type_t)0x2008)
 #define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x2403)
 #define PSA_KEY_TYPE_CHACHA20 ((psa_key_type_t)0x2004)
 #define PSA_KEY_TYPE_DERIVE ((psa_key_type_t)0x1200)
@@ -380,6 +390,7 @@ typedef struct psa_custom_key_parameters_t {
     /* implementation-defined value */
 #define PSA_TLS12_ECJPAKE_TO_PMS_OUTPUT_SIZE 32
 #define PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE /* implementation-defined value */
+#define PSA_XOF_OPERATION_INIT /* implementation-defined value */
 psa_status_t psa_aead_abort(psa_aead_operation_t * operation);
 psa_status_t psa_aead_decrypt(psa_key_id_t key,
                               psa_algorithm_t alg,
@@ -747,3 +758,16 @@ psa_status_t psa_verify_message(psa_key_id_t key,
                                 size_t input_length,
                                 const uint8_t * signature,
                                 size_t signature_length);
+psa_status_t psa_xof_abort(psa_xof_operation_t * operation);
+psa_xof_operation_t psa_xof_operation_init(void);
+psa_status_t psa_xof_output(psa_xof_operation_t * operation,
+                            uint8_t * output,
+                            size_t output_length);
+psa_status_t psa_xof_set_context(psa_xof_operation_t * operation,
+                                 const uint8_t * context,
+                                 size_t context_length);
+psa_status_t psa_xof_setup(psa_xof_operation_t * operation,
+                           psa_algorithm_t alg);
+psa_status_t psa_xof_update(psa_xof_operation_t * operation,
+                            const uint8_t * input,
+                            size_t input_length);

doc/crypto/api/keys/types.rst

@@ -593,6 +593,34 @@ Symmetric keys
 
         A call to `psa_key_derivation_output_key()` will draw 32 bytes of output and use these as the key data.
 
+.. macro:: PSA_KEY_TYPE_ASCON
+    :definition: ((psa_key_type_t)0x2008)
+
+    .. summary::
+        Key for the Ascon-AEAD128 AEAD algorithm.
+
+        .. versionadded:: 1.4
+
+    The standard Ascon-AEAD128 key size is 128 bits (16 bytes).
+
+    For the nonce-masking variant of Ascon-AEAD128, use a key size of 256 bits (32-bytes).
+
+    See `PSA_ALG_ASCON_AEAD128` for details of this algorithm.
+
+    .. subsection:: Compatible algorithms
+
+        .. hlist::
+
+            *   `PSA_ALG_ASCON_AEAD128`
+
+    .. subsection:: Key format
+
+        The data format for import and export of the key is the raw bytes of the key.
+
+    .. subsection:: Key derivation
+
+        A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
+
 .. _asymmetric-keys:
 
 Asymmetric keys

doc/crypto/api/ops/aead.rst

@@ -150,6 +150,33 @@ AEAD algorithms
 
         | `PSA_KEY_TYPE_XCHACHA20`
 
+.. macro:: PSA_ALG_ASCON_AEAD128
+    :definition: ((psa_algorithm_t)0x05100700)
+
+    .. summary::
+        The Ascon-AEAD128 AEAD algorithm.
+
+        .. versionadded:: 1.4
+
+    There are two variants of Ascon-AEAD128 defined in :cite-title:`SP800-232`:
+
+    *   An implementation that supports Ascon-AEAD128 must provide the standard variant, using a 128-bit key.
+        This is defined in `[SP800-232]` §4.1.
+    *   An implementation can optionally also provide the nonce-masking variant, using a 256-bit key.
+        This is defined in `[SP800-232]` §4.2.2.
+
+    The variant is selected based on the size of the key.
+
+    Both variants require a 128-bit (16 byte) nonce, which must not be reused with the same key.
+
+    Implementations must support 16-byte tags.
+    Truncated tags of at least 4 bytes are permitted, but it is recommended that truncated tag sizes are at least 8 bytes.
+    See `[SP800-232]` §4.2.1 and §4.3.R4.
+
+    .. subsection:: Compatible key types
+
+        | `PSA_KEY_TYPE_ASCON`
+
 .. macro:: PSA_ALG_AEAD_WITH_SHORTENED_TAG
     :definition: /* specification-defined value */
 

doc/crypto/api/ops/algorithms.rst

@@ -16,6 +16,7 @@ Algorithm identifiers are used for two purposes in the |API|:
 The specific algorithm identifiers are described alongside the cryptographic operation functions to which they apply:
 
 *   :secref:`hash-algorithms`
+*   :secref:`xof-algorithms`
 *   :secref:`mac-algorithms`
 *   :secref:`cipher-algorithms`
 *   :secref:`aead-algorithms`
@@ -83,6 +84,21 @@ Algorithm categories
 
     See :secref:`hash-algorithms` for a list of defined hash algorithms.
 
+.. macro:: PSA_ALG_IS_XOF
+    :definition: /* specification-defined value */
+
+    .. summary::
+        Whether the specified algorithm is an XOF algorithm.
+
+    .. param:: alg
+        An algorithm identifier: a value of type `psa_algorithm_t`.
+
+    .. return::
+        ``1`` if ``alg`` is an XOF algorithm, ``0`` otherwise.
+        This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.
+
+    See :secref:`xof-algorithms` for a list of defined XOF algorithms.
+
 .. macro:: PSA_ALG_IS_MAC
     :definition: /* specification-defined value */
 

doc/crypto/api/ops/hash.rst

@@ -184,13 +184,16 @@ Hash algorithms
     :definition: ((psa_algorithm_t)0x02000015)
 
     .. summary::
-        The first 512 bits (64 bytes) of the SHAKE256 output.
+        The first 512 bits (64 bytes) of the output from SHAKE256.
 
         .. versionadded:: 1.1
 
-    This is the pre-hashing for Ed448ph (see `PSA_ALG_ED448PH`).
+    This is used for pre-hashing in Ed448ph, see `PSA_ALG_ED448PH`.
 
-    SHAKE256 is defined in :cite:`FIPS202`.
+    The SHAKE256 XOF is defined in :cite:`FIPS202`.
+
+    .. note::
+        To use SHAKE256 as an XOF, see :secref:`xof` and `PSA_ALG_SHAKE256`.
 
     .. note::
         For other scenarios where a hash function based on SHA3 or SHAKE is required, SHA3-512 is recommended. SHA3-512 has the same output size, and a theoretically higher security strength.
@@ -203,6 +206,19 @@ Hash algorithms
 
     SM3 is defined in :cite-title:`ISO10118`, and also in :cite-title:`CSTC0004`.
 
+.. macro:: PSA_ALG_ASCON_HASH256
+    :definition: ((psa_algorithm_t)0x02000020)
+
+    .. summary::
+        The Ascon-Hash256 message-digest algorithm.
+
+        .. versionadded:: 1.4
+
+    Ascon-Hash256 is defined in :cite-title:`SP800-232` §5.1.
+
+    .. note::
+        To use the Ascon XOF algorithms, see `PSA_ALG_ASCON_XOF128` and `PSA_ALG_ASCON_CXOF128`.
+
 Single-part hashing functions
 -----------------------------
 

doc/crypto/api/ops/index.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2022, 2024 Arm Limited and/or its affiliates <[email protected]>
+.. SPDX-FileCopyrightText: Copyright 2018-2025 Arm Limited and/or its affiliates <[email protected]>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. _crypto-operations:
@@ -11,6 +11,7 @@ Cryptographic operation reference
 
     algorithms
     hash
+    xof
     mac
     cipher
     aead