ML-DSA: update PQ docs, refactor define bloat.

docs/PQ.md

@@ -1,8 +1,78 @@
 # Post-Quantum Signatures
 
-wolfBoot is adding support for post-quantum signatures. At present, support
-for LMS/HSS (https://www.rfc-editor.org/rfc/rfc8554.html), and XMSS/XMSS^MT
-(https://www.rfc-editor.org/rfc/rfc8391.html) has been added.
+wolfBoot is continuously adding support for post-quantum (PQ) signature
+algorithms as they mature. At present, support has been added for three NIST
+approved PQ signature algorithms:
+
+- ML-DSA: https://csrc.nist.gov/pubs/fips/204/final
+- LMS/HSS: https://csrc.nist.gov/projects/stateful-hash-based-signatures
+- XMSS/XMSS^MT: https://csrc.nist.gov/projects/stateful-hash-based-signatures
+
+ML-DSA is a post-quantum lattice-based algorithm, derived from
+CRYSTALS-DILITHIUM (a round three NIST finalist).
+
+LMS/HSS and XMSS/XMSS^MT are both post-quantum stateful
+hash-based signature (HBS) schemes, recommended in NIST SP 800-208.
+
+In terms of relative tradeoffs:
+- All three methods have fast verifying operations.
+- All three methods have variable length signature sizes.
+- ML-DSA key generation is much faster than LMS/HSS and XMSS/XMSS^MT.
+- ML-DSA public keys are larger than LMS/HSS and XMSS/XMSS^MT.
+- LMS/HSS and XMSS/XMSS^MT have stateful private keys, which requires
+  more care with key generation and signing operations.
+
+See these config files for simulated target examples:
+
+- `config/examples/sim-ml-dsa.config`
+- `config/examples/sim-lms.config`
+- `config/examples/sim-xmss.config`
+
+## Lattice Based Signature Methods
+
+### ML-DSA
+
+ML-DSA (Module-Lattice Digital Signature Algorithm) was standardized in
+FIPS 204 (https://csrc.nist.gov/pubs/fips/204/final), based on its
+round 3 predecessor CRYSTALS-DILITHIUM.
+
+ML-DSA has three standardized parameter sets:
+
+- `ML-DSA-44`
+- `ML-DSA-65`
+- `ML-DSA-87`
+
+The numerical suffix (44, 65, 87) denotes the dimension of the matrix used
+in the underlying lattice construction.
+
+The private key, public key, signature size, and overall security strength
+all depend on the parameter set:
+
+```
+#
+#               Private Key   Public Key   Signature Size   Security Strength
+#   ML-DSA-44      2560          1312         2420            Category 2
+#   ML-DSA-65      4032          1952         3309            Category 3
+#   ML-DSA-87      4896          2592         4627            Category 5
+#
+```
+
+This is configured in wolfBoot with `ML_DSA_LEVEL=<num>`. Here is an example
+from the `sim-ml-dsa.config`:
+
+```
+# ML-DSA config examples:
+#
+# Category 2:
+ML_DSA_LEVEL=2
+IMAGE_SIGNATURE_SIZE=2420
+IMAGE_HEADER_SIZE?=4840
+```
+
+Note: The wolfcrypt implementation of dilithium is built with
+`WOLFSSL_DILITHIUM_FIPS204_DRAFT` to conform to this standard.
+
+## Stateful Hash-Based Signature Methods
 
 LMS/HSS and XMSS/XMSS^MT are both post-quantum stateful hash-based signature
 (HBS) schemes. They are known for having small public keys, relatively fast
@@ -19,7 +89,7 @@ See these links for more info on stateful HBS support and wolfSSL/wolfCrypt:
 - https://www.wolfssl.com/documentation/manuals/wolfssl/appendix07.html#post-quantum-stateful-hash-based-signatures
 - https://github.com/wolfSSL/wolfssl-examples/tree/master/pq/stateful_hash_sig
 
-## Supported PQ Signature Methods
+### Supported PQ HBS Options
 
 These four PQ signature options are supported:
 - LMS: uses wolfcrypt implementation from `wc_lms.c`, and `wc_lms_impl.c`.

include/user_settings.h

@@ -227,6 +227,24 @@ extern int tolower(int c);
 #   define NO_RSA
 #endif /* RSA */
 
+/* ML-DSA (dilithium) */
+#if defined(WOLFBOOT_SIGN_ML_DSA)
+#   define HAVE_DILITHIUM
+#   define WOLFSSL_WC_DILITHIUM
+#   define WOLFSSL_EXPERIMENTAL_SETTINGS
+#   define WOLFSSL_DILITHIUM_FIPS204_DRAFT
+#   define WOLFSSL_DILITHIUM_VERIFY_ONLY
+#   define WOLFSSL_DILITHIUM_NO_LARGE_CODE
+#   define WOLFSSL_DILITHIUM_SMALL
+#   define WOLFSSL_DILITHIUM_VERIFY_SMALL_MEM
+#   define WOLFSSL_DILITHIUM_VERIFY_NO_MALLOC
+#   define WOLFSSL_DILITHIUM_NO_ASN1
+    /* dilithium needs these sha functions. */
+#   define WOLFSSL_SHA3
+#   define WOLFSSL_SHAKE256
+#   define WOLFSSL_SHAKE128
+#endif /* WOLFBOOT_SIGN_ML_DSA */
+
 #ifdef WOLFBOOT_HASH_SHA3_384
 #   define WOLFSSL_SHA3
 #   if defined(NO_RSA) && !defined(WOLFBOOT_TPM) && \

options.mk

@@ -486,7 +486,6 @@ ifneq (,$(filter $(SIGN), ext_LMS ext_XMSS))
   CFLAGS  +=-DWOLFSSL_EXPERIMENTAL_SETTINGS
 endif
 
-
 ifeq ($(SIGN),ML_DSA)
   # Use wolfcrypt ML-DSA dilithium implementation.
   KEYGEN_OPTIONS+=--ml_dsa
@@ -497,24 +496,14 @@ ifeq ($(SIGN),ML_DSA)
     ./lib/wolfssl/wolfcrypt/src/sha3.o \
     ./lib/wolfssl/wolfcrypt/src/wc_port.o \
     ./lib/wolfssl/wolfcrypt/src/hash.o
-  CFLAGS+=-D"WOLFSSL_DILITHIUM_FIPS204_DRAFT" \
-          -D"WOLFBOOT_SIGN_ML_DSA" -D"HAVE_DILITHIUM" \
-          -D"WOLFSSL_DILITHIUM_VERIFY_ONLY" \
-          -D"WOLFSSL_DILITHIUM_SMALL" \
-          -D"WOLFSSL_DILITHIUM_VERIFY_SMALL_MEM" \
-          -D"WOLFSSL_DILITHIUM_VERIFY_NO_MALLOC" \
-          -D"WOLFSSL_WC_DILITHIUM" -D"WOLFSSL_EXPERIMENTAL_SETTINGS" \
-          -D"WOLFSSL_DILITHIUM_NO_ASN1" \
-          -D"WC_DILITHIUM_FIXED_ARRAY" \
+  CFLAGS+=-D"WOLFBOOT_SIGN_ML_DSA" \
           -D"IMAGE_SIGNATURE_SIZE"=$(IMAGE_SIGNATURE_SIZE) \
-          -D"WOLFSSL_SHA3" -D"WOLFSSL_SHAKE128" -D"WOLFSSL_SHAKE256" \
           -D"ML_DSA_LEVEL"=$(ML_DSA_LEVEL)
   ifeq ($(WOLFBOOT_SMALL_STACK),1)
     $(error WOLFBOOT_SMALL_STACK with ML-DSA not supported yet)
   else
-    STACK_USAGE=19544
+    STACK_USAGE=19536
   endif
-
 endif
 
 ifeq ($(RAM_CODE),1)

tools/keytools/Makefile

@@ -166,11 +166,8 @@ endif
 ifeq ($(SIGN),ML_DSA)
   OBJS_REAL+=$(WOLFDIR)/wolfcrypt/src/dilithium.o
 
-  CFLAGS += -D"WOLFSSL_DILITHIUM_FIPS204_DRAFT" \
-            -D"WOLFBOOT_SIGN_ML_DSA" -D"HAVE_DILITHIUM" \
-            -D"WOLFSSL_WC_DILITHIUM" -D"WOLFSSL_EXPERIMENTAL_SETTINGS" \
+  CFLAGS += -D"WOLFBOOT_SIGN_ML_DSA" \
             -D"IMAGE_SIGNATURE_SIZE"=$(IMAGE_SIGNATURE_SIZE) \
-            -D"WOLFSSL_SHAKE128" \
             -D"ML_DSA_LEVEL"=$(ML_DSA_LEVEL)
 endif
 

tools/keytools/user_settings.h

@@ -73,6 +73,16 @@
 #define WOLFSSL_SHA3
 #undef  NO_SHA256
 
+/* ML-DSA (dilithium) */
+#if defined(WOLFBOOT_SIGN_ML_DSA)
+#   define HAVE_DILITHIUM
+#   define WOLFSSL_WC_DILITHIUM
+#   define WOLFSSL_EXPERIMENTAL_SETTINGS
+#   define WOLFSSL_DILITHIUM_FIPS204_DRAFT
+    /* dilithium needs these sha functions. */
+#   define WOLFSSL_SHAKE128
+#endif /* WOLFBOOT_SIGN_ML_DSA */
+
 /* ASN */
 #define WOLFSSL_ASN_TEMPLATE