Add support for stateful hash-based signatures to the PQC Extension

doc/crypto/api/ops/signature.rst

@@ -116,7 +116,7 @@ RSA signature algorithms
     .. summary::
         The raw RSA PKCS#1 v1.5 signature algorithm, without hashing.
 
-    This specialized signature algorithm can be only used with the `psa_sign_hash()` and `psa_verify_hash()` functions.
+    This specialized signature algorithm can only be used with the `psa_sign_hash()` and `psa_verify_hash()` functions.
 
     This signature scheme is defined by :RFC-title:`8017#8.2` under the name RSASSA-PKCS1-v1_5.
 
@@ -334,7 +334,7 @@ ECDSA signature algorithms
     .. summary::
         The randomized ECDSA signature scheme, without hashing.
 
-    This specialized signature algorithm can be only used with the `psa_sign_hash()` and `psa_verify_hash()` functions.
+    This specialized signature algorithm can only be used with the `psa_sign_hash()` and `psa_verify_hash()` functions.
 
     This algorithm is randomized: each invocation returns a different, equally valid signature.
 
@@ -457,7 +457,7 @@ EdDSA signature algorithms
 
         .. versionadded:: 1.1
 
-    This message signature algorithm can be only used with the `psa_sign_message()` and `psa_verify_message()` functions.
+    This message signature algorithm can only be used with the `psa_sign_message()` and `psa_verify_message()` functions.
 
     This is the PureEdDSA digital signature algorithm defined by :RFC-title:`8032`, using standard parameters.
 

doc/ext-pqc/api.db/psa/crypto-pqc.h

@@ -10,6 +10,7 @@ typedef uint8_t psa_slh_dsa_family_t;
 #define PSA_ALG_DETERMINISTIC_SLH_DSA ((psa_algorithm_t) 0x06004100)
 #define PSA_ALG_HASH_ML_DSA(hash_alg) /* specification-defined value */
 #define PSA_ALG_HASH_SLH_DSA(hash_alg) /* specification-defined value */
+#define PSA_ALG_HSS ((psa_algorithm_t) 0x06004900)
 #define PSA_ALG_IS_DETERMINISTIC_HASH_ML_DSA(alg) \
     /* specification-defined value */
 #define PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA(alg) \
@@ -20,24 +21,34 @@ typedef uint8_t psa_slh_dsa_family_t;
 #define PSA_ALG_IS_HEDGED_HASH_SLH_DSA(alg) /* specification-defined value */
 #define PSA_ALG_IS_ML_DSA(alg) /* specification-defined value */
 #define PSA_ALG_IS_SLH_DSA(alg) /* specification-defined value */
+#define PSA_ALG_LMS ((psa_algorithm_t) 0x06004800)
 #define PSA_ALG_ML_DSA ((psa_algorithm_t) 0x06004400)
-#define PSA_ALG_ML_KEM ((psa_algorithm_t)0x0b000200)
+#define PSA_ALG_ML_KEM ((psa_algorithm_t)0x0c000200)
 #define PSA_ALG_SHAKE128_256 ((psa_algorithm_t)0x02000016)
+#define PSA_ALG_SHAKE256_192 ((psa_algorithm_t)0x02000017)
+#define PSA_ALG_SHAKE256_256 ((psa_algorithm_t)0x02000018)
+#define PSA_ALG_SHA_256_192 ((psa_algorithm_t)0x0200000E)
 #define PSA_ALG_SLH_DSA ((psa_algorithm_t) 0x06004000)
+#define PSA_ALG_XMSS ((psa_algorithm_t) 0x06004A00)
+#define PSA_ALG_XMSS_MT ((psa_algorithm_t) 0x06004B00)
+#define PSA_KEY_TYPE_HSS_PUBLIC_KEY ((psa_key_type_t)0x4008)
 #define PSA_KEY_TYPE_IS_ML_DSA(type) /* specification-defined value */
 #define PSA_KEY_TYPE_IS_ML_KEM(type) /* specification-defined value */
 #define PSA_KEY_TYPE_IS_SLH_DSA(type) /* specification-defined value */
 #define PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR(type) \
     /* specification-defined value */
 #define PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY(type) \
     /* specification-defined value */
+#define PSA_KEY_TYPE_LMS_PUBLIC_KEY ((psa_key_type_t)0x4007)
 #define PSA_KEY_TYPE_ML_DSA_KEY_PAIR ((psa_key_type_t)0x7002)
 #define PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY ((psa_key_type_t)0x4002)
 #define PSA_KEY_TYPE_ML_KEM_KEY_PAIR ((psa_key_type_t)0x7004)
 #define PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY ((psa_key_type_t)0x4004)
 #define PSA_KEY_TYPE_SLH_DSA_GET_FAMILY(type) /* specification-defined value */
 #define PSA_KEY_TYPE_SLH_DSA_KEY_PAIR(set) /* specification-defined value */
 #define PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY(set) /* specification-defined value */
+#define PSA_KEY_TYPE_XMSS_MT_PUBLIC_KEY ((psa_key_type_t)0x400D)
+#define PSA_KEY_TYPE_XMSS_PUBLIC_KEY ((psa_key_type_t)0x400B)
 #define PSA_SLH_DSA_FAMILY_SHA2_F ((psa_slh_dsa_family_t) 0x04)
 #define PSA_SLH_DSA_FAMILY_SHA2_S ((psa_slh_dsa_family_t) 0x02)
 #define PSA_SLH_DSA_FAMILY_SHAKE_F ((psa_slh_dsa_family_t) 0x0d)

doc/ext-pqc/api/hash.rst

@@ -9,25 +9,63 @@
 Additional Hash algorithms
 ==========================
 
+SHA-256-based hash algorithms
+-----------------------------
+
+.. macro:: PSA_ALG_SHA_256_192
+    :definition: ((psa_algorithm_t)0x0200000E)
+
+    .. summary::
+        The SHA-256/192 message digest algorithm.
+
+        .. versionadded:: 1.3
+
+    SHA-256/192 is the first 192 bits (24 bytes) of the SHA-256 output.
+    SHA-256 is defined in :cite:`FIPS180-4`.
+
+
 SHAKE-based hash algorithms
 ---------------------------
 
 .. macro:: PSA_ALG_SHAKE128_256
     :definition: ((psa_algorithm_t)0x02000016)
 
     .. summary::
-        The first 256 bits (32 bytes) of the SHAKE128 output.
+        The SHAKE128/256 message digest algorithm.
 
-    This can be used as pre-hashing for SLH-DSA (see `PSA_ALG_HASH_SLH_DSA()`).
+        .. versionadded:: 1.3
 
+    SHAKE128/256 is the first 256 bits (32 bytes) of the SHAKE128 output.
     SHAKE128 is defined in :cite:`FIPS202`.
 
+    This can be used as pre-hashing for SLH-DSA (see `PSA_ALG_HASH_SLH_DSA()`).
+
     .. note::
         For other scenarios where a hash function based on SHA3 or SHAKE is required, SHA3-256 is recommended. SHA3-256 has the same output size, and a theoretically higher security strength.
 
-    .. versionadded:: 1.3
-
 .. comment
     Update the description of PSA_ALG_SHAKE256_512 to state:
 
     This is the pre-hashing for Ed448ph (see `PSA_ALG_ED448PH`), and can be used as pre-hashing for SLH-DSA (see `PSA_ALG_HASH_SLH_DSA()`).
+
+.. macro:: PSA_ALG_SHAKE256_192
+    :definition: ((psa_algorithm_t)0x02000017)
+
+    .. summary::
+        The SHAKE256/192 message digest algorithm.
+
+        .. versionadded:: 1.3
+
+    SHAKE256/192 is the first 192 bits (24 bytes) of the SHAKE256 output.
+    SHAKE256 is defined in :cite:`FIPS202`.
+
+.. macro:: PSA_ALG_SHAKE256_256
+    :definition: ((psa_algorithm_t)0x02000018)
+
+    .. summary::
+        The SHAKE256/256 message digest algorithm.
+
+        .. versionadded:: 1.3
+
+    SHAKE256/256 is the first 256 bits (32 bytes) of the SHAKE256 output.
+    SHAKE256 is defined in :cite:`FIPS202`.

doc/ext-pqc/api/lms.rst

@@ -0,0 +1,135 @@
+.. SPDX-FileCopyrightText: Copyright 2024-2025 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
+
+.. header:: psa/crypto-pqc
+    :seq: 5
+
+.. _lms:
+
+Leighton-Micali Signatures
+==========================
+
+The |API| supports Leighton-Micali Signatures (LMS), and the multi-level Hierarchical Signature Scheme (HSS).
+These schemes are defined in :rfc-title:`8554`.
+
+For the |API| to support signature verification, it is only necessary to define a public keys for these schemes, and the default public key formats for import and export.
+
+.. rationale::
+
+    At present, it is not expected that the |API| will be used to generate LMS or HSS private keys, or to carry out signing operations.
+    However, there is value in supporting verification of LMS and HSS signatures.
+    Therefore, the |API| does not support LMS or HSS key pairs, or the associated signing operations.
+
+.. note::
+    A full set of NIST-approved parameter sets for LMS and HSS is defined in :cite-title:`SP800-208` §4, with the additional IANA identifiers defined in :cite-title:`CFRG-LMS`.
+
+.. _lms-keys:
+
+Leighton-Micali Signature keys
+------------------------------
+
+.. macro:: PSA_KEY_TYPE_LMS_PUBLIC_KEY
+    :definition: ((psa_key_type_t)0x4007)
+
+    .. summary::
+        Leighton-Micali Signatures (LMS) public key.
+
+        .. versionadded:: 1.3
+
+    The parameterization of an LMS key is fully encoded in the key data.
+
+    The key attribute size of an LMS public key is output length, in bits, of the hash function identified by the LMS parameter set.
+
+    *   SHA-256/192, SHAKE256/192 : ``key_bits = 192``
+    *   SHA-256, SHAKE256/256 : ``key_bits = 256``
+
+    .. subsection:: Compatible algorithms
+
+        .. hlist::
+
+            *   `PSA_ALG_LMS`
+
+    .. subsection:: Key format
+
+        The data format for import or export of the public key is the encoded ``lms_public_key`` structure, defined in :rfc:`8554#3`.
+
+.. macro:: PSA_KEY_TYPE_HSS_PUBLIC_KEY
+    :definition: ((psa_key_type_t)0x4008)
+
+    .. summary::
+        Hierarchical Signature Scheme (HSS) public key.
+
+        .. versionadded:: 1.3
+
+    The parameterization of an HSS key is fully encoded in the key data.
+
+    The key attribute size of an HSS public key is output length, in bits, of the hash function identified by the HSS parameter set.
+
+    *   SHA-256/192, SHAKE256/192 : ``key_bits = 192``
+    *   SHA-256, SHAKE256/256 : ``key_bits = 256``
+
+    .. subsection:: Compatible algorithms
+
+        .. hlist::
+
+            *   `PSA_ALG_HSS`
+
+    .. subsection:: Key format
+
+        .. warning::
+
+            The key format may change in a final version of this API.
+            The standardization of exchange formats for HSS public keys is in progress, but final documents have not been published.
+            See :cite-title:`LAMPS-SHBS`.
+
+            The current proposed format is based on the expected outcome of that process.
+
+        The data format for import or export of the public key is the encoded ``hss_public_key`` structure, defined in :rfc:`8554#3`.
+
+
+.. _lms-algorithms:
+
+Leighton-Micali Signature algorithms
+------------------------------------
+
+.. macro:: PSA_ALG_LMS
+    :definition: ((psa_algorithm_t) 0x06004800)
+
+    .. summary::
+        Leighton-Micali Signatures (LMS) signature algorithm.
+
+        .. versionadded:: 1.3
+
+    This message-signature algorithm can only be used with the :code:`psa_verify_message()` function.
+
+    This is the LMS stateful hash-based signature algorithm, defined by :rfc-title:`8554`.
+    LMS requires an LMS key.
+    The key and the signature must both encode the same LMS parameter set, which is used for the verification procedure.
+
+    .. note::
+        LMS signature calculation is not supported.
+
+    .. subsection:: Compatible key types
+
+        | :code:`PSA_KEY_TYPE_LMS_PUBLIC_KEY` (signature verification only)
+
+.. macro:: PSA_ALG_HSS
+    :definition: ((psa_algorithm_t) 0x06004900)
+
+    .. summary::
+        Hierarchical Signature Scheme (HSS) signature algorithm.
+
+        .. versionadded:: 1.3
+
+    This message-signature algorithm can only be used with the :code:`psa_verify_message()` function.
+
+    This is the HSS stateful hash-based signature algorithm, defined by :rfc-title:`8554`.
+    HSS requires an HSS key.
+    The key and the signature must both encode the same HSS parameter set, which is used for the verification procedure.
+
+    .. note::
+        HSS signature calculation is not supported.
+
+    .. subsection:: Compatible key types
+
+        | :code:`PSA_KEY_TYPE_HSS_PUBLIC_KEY` (signature verification only)