XMSS wolfBoot support.

Author: philljj

config/examples/sim-xmss.config

@@ -0,0 +1,26 @@
+# XMSS/XMSS^MT/HSS signature example, based on sim.config example.
+#
+#
+
+ARCH=sim
+TARGET=sim
+SIGN?=XMSS
+HASH?=SHA256
+XMSS_PARAMS='XMSS-SHA2_10_256'
+WOLFBOOT_SMALL_STACK=0
+SPI_FLASH=0
+DEBUG=0
+DELTA_UPDATES=0
+IMAGE_SIGNATURE_SIZE=2500
+IMAGE_HEADER_SIZE?=5000
+
+# sizes should be multiple of system page size
+WOLFBOOT_PARTITION_SIZE=0x40000
+WOLFBOOT_SECTOR_SIZE=0x1000
+WOLFBOOT_PARTITION_BOOT_ADDRESS=0x20000
+# if on external flash, it should be multiple of system page size
+WOLFBOOT_PARTITION_UPDATE_ADDRESS=0x60000
+WOLFBOOT_PARTITION_SWAP_ADDRESS=0xA0000
+
+# required for keytools
+WOLFBOOT_FIXED_PARTITIONS=1

docs/PQ.md

@@ -1,17 +1,27 @@
 # Post-Quantum Signatures
 
 wolfBoot is adding support for post-quantum signatures. At present, support
-for LMS/HSS signatures has been added.
+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.
 
-## LMS/HSS
-
-LMS/HSS is a post-quantum stateful hash-based signature scheme (HBS). It
-is known for having small public and private keys, but larger signatures.
-The signature size is tunable via the different LMS parameters.
+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
+signing and verifying operations, but larger signatures. Their signature sizes
+however are tunable via their different parameters, which affords a space-time
+tradeoff.
 
 Stateful HBS schemes are based on the security of their underlying hash
 functions and Merkle trees, which are not expected to be broken by the advent
-of cryptographically relevant quantum computers.
+of cryptographically relevant quantum computers. For this reason they have
+been recommended by both NIST SP 800-208, and the NSA’s CNSA 2.0 suite.
+
+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
+
+
+## LMS/HSS
+
 
 ### Building with LMS Support
 
@@ -44,7 +54,7 @@ keygen, signing, and verifying functionality. However wolfBoot
 links directly with the subset of objects in the `hss_verify.a`
 build rule, as it only requires verify functionality.
 
-### Config
+### LMS Config
 
 A new LMS sim example has been added here:
 ```
@@ -69,17 +79,66 @@ In LMS the signature size is a function of the parameters. Use the added helper
 script `tools/lms/lms_siglen.sh` to calculate your signature length given your
 LMS parameters:
 ```
-$./tools/lms/lms_siglen.sh
-levels:      3
-height:      5
-winternitz:  8
-#
-total_len:   3992
+$ ./tools/lms/lms_siglen.sh  2 5 8
+levels:     2
+height:     5
+winternitz: 8
+signature length: 2644
 ```
 
-### More Info
+## XMSS/XMSS^MT
 
-See these links for more info on LMS 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
+### Building with XMSS Support
+
+XMSS/XMSS^MT support in wolfCrypt requires a patched version of the
+xmss-reference library ( https://github.com/XMSS/xmss-reference.git ).
+Use the following procedure to prepare xmss-reference for building with
+wolfBoot:
+
+```
+$ cd lib
+$ git clone https://github.com/XMSS/xmss-reference.git xmss
+$ ls
+CMakeLists.txt  wolfPKCS11  wolfTPM  wolfssl  xmss
+$ cd xmss
+$ git checkout 171ccbd26f098542a67eb5d2b128281c80bd71a6
+$ git apply ../../../tools/xmss/0001-Patch-to-support-wolfSSL-xmss-reference-integration.patch
+```
 
+The patch creates an addendum readme, `patch_readme.md`, with further comments.
+
+Nothing more is needed beyond the patch step, as wolfBoot will handle building
+the xmss build artifacts it requires.
+
+### XMSS Config
+A new XMSS sim example has been added here:
+```
+config/examples/sim-xmss.config
+```
+
+The `XMSS_PARAMS`, `IMAGE_SIGNATURE_SIZE`, and (optionally) `IMAGE_HEADER_SIZE`
+must be set:
+
+```
+SIGN?=XMSS
+...
+XMSS_PARAMS='XMSS-SHA2_10_256'
+...
+IMAGE_SIGNATURE_SIZE=2500
+IMAGE_HEADER_SIZE?=5000
+```
+
+The `XMSS_PARAMS` may be any SHA256 parameter set string from Tables 10 and 11
+from NIST SP 800-208.  Use the helper script `tools/xmss/xmss_siglen.sh` to
+calculate your signature length given your XMSS/XMSS^MT parameter string, e.g.:
+```
+$ ./tools/xmss/xmss_siglen.sh XMSS-SHA2_10_256
+parameter set:    XMSS-SHA2_10_256
+signature length: 2500
+```
+
+```
+$ ./tools/xmss/xmss_siglen.sh XMSSMT-SHA2_20/2_256
+parameter set:    XMSSMT-SHA2_20/2_256
+signature length: 4963
+```

include/loader.h

@@ -67,6 +67,9 @@ extern "C" {
      * options.mk from the .config file. */
     extern const unsigned char lms_pub_key[];
     extern unsigned int lms_pub_key_len;
+#elif defined(WOLFBOOT_SIGN_XMSS)
+    extern const unsigned char xmss_pub_key[];
+    extern unsigned int xmss_pub_key_len;
 #elif !defined(WOLFBOOT_NO_SIGN)
 #   error "No public key available for given signing algorithm."
 #endif /* Algorithm selection */

include/wolfboot/wolfboot.h

@@ -85,6 +85,7 @@ extern "C" {
 #define AUTH_KEY_ECC521  0x07
 #define AUTH_KEY_RSA3072 0x08
 #define AUTH_KEY_LMS     0x09
+#define AUTH_KEY_XMSS    0x10
 
 
 
@@ -105,6 +106,7 @@ extern "C" {
 #define HDR_IMG_TYPE_AUTH_ECC521  (AUTH_KEY_ECC521  << 8)
 #define HDR_IMG_TYPE_AUTH_RSA3072 (AUTH_KEY_RSA3072 << 8)
 #define HDR_IMG_TYPE_AUTH_LMS     (AUTH_KEY_LMS     << 8)
+#define HDR_IMG_TYPE_AUTH_XMSS    (AUTH_KEY_XMSS    << 8)
 
 #define HDR_IMG_TYPE_DIFF         0x00D0
 
@@ -122,6 +124,7 @@ extern "C" {
  #define KEYSTORE_PUBKEY_SIZE_RSA3072 448
  #define KEYSTORE_PUBKEY_SIZE_RSA4096 576
  #define KEYSTORE_PUBKEY_SIZE_LMS     60
+ #define KEYSTORE_PUBKEY_SIZE_XMSS    68
 
 /* Mask for key permissions */
  #define KEY_VERIFY_ALL         (0xFFFFFFFFU)
@@ -222,6 +225,11 @@ extern "C" {
  #   ifndef WOLFBOOT_UNIVERSAL_KEYSTORE
  #     define KEYSTORE_PUBKEY_SIZE KEYSTORE_PUBKEY_SIZE_LMS
  #   endif
+ #elif defined(WOLFBOOT_SIGN_XMSS)
+ #   define HDR_IMG_TYPE_AUTH HDR_IMG_TYPE_AUTH_XMSS
+ #   ifndef WOLFBOOT_UNIVERSAL_KEYSTORE
+ #     define KEYSTORE_PUBKEY_SIZE KEYSTORE_PUBKEY_SIZE_XMSS
+ #   endif
  #else
  #   error "No valid authentication mechanism selected. " \
            "Please select a valid SIGN= option."

options.mk

@@ -381,6 +381,46 @@ ifeq ($(SIGN),LMS)
   endif
 endif
 
+ifeq ($(SIGN),XMSS)
+  ifndef XMSS_PARAMS
+    $(error XMSS_PARAMS not set)
+  endif
+
+  ifndef IMAGE_SIGNATURE_SIZE
+    $(error IMAGE_SIGNATURE_SIZE not set)
+  endif
+
+  ifndef IMAGE_HEADER_SIZE
+    $(error IMAGE_HEADER_SIZE not set)
+  endif
+
+  XMSSDIR = lib/xmss
+  KEYGEN_OPTIONS+=--xmss
+  SIGN_OPTIONS+=--xmss
+  WOLFCRYPT_OBJS+= \
+    ./$(XMSSDIR)/params.o \
+    ./$(XMSSDIR)/thash.o \
+    ./$(XMSSDIR)/hash_address.o \
+    ./$(XMSSDIR)/wots.o \
+    ./$(XMSSDIR)/xmss.o \
+    ./$(XMSSDIR)/xmss_core_fast.o \
+    ./$(XMSSDIR)/xmss_commons.o \
+    ./$(XMSSDIR)/utils.o \
+    ./lib/wolfssl/wolfcrypt/src/ext_xmss.o \
+    ./lib/wolfssl/wolfcrypt/src/memory.o \
+    ./lib/wolfssl/wolfcrypt/src/wc_port.o \
+    ./lib/wolfssl/wolfcrypt/src/hash.o
+  CFLAGS+=-D"WOLFBOOT_SIGN_XMSS" -D"WOLFSSL_HAVE_XMSS" -D"HAVE_LIBXMSS" \
+    -DXMSS_PARAMS=\"$(XMSS_PARAMS)\" -I$(XMSSDIR) \
+    -D"IMAGE_SIGNATURE_SIZE"=$(IMAGE_SIGNATURE_SIZE) \
+    -D"WOLFSSL_XMSS_VERIFY_ONLY" -D"XMSS_VERIFY_ONLY"
+  ifeq ($(WOLFBOOT_SMALL_STACK),1)
+    $(error WOLFBOOT_SMALL_STACK with XMSS not supported)
+  else
+    STACK_USAGE=18064
+  endif
+endif
+
 ifeq ($(RAM_CODE),1)
   CFLAGS+= -D"RAM_CODE"
 endif

src/image.c

@@ -382,6 +382,71 @@ static void wolfBoot_verify_signature(uint8_t key_slot,
 }
 #endif /* WOLFBOOT_SIGN_LMS */
 
+#ifdef WOLFBOOT_SIGN_XMSS
+#include <wolfssl/wolfcrypt/xmss.h>
+#ifdef HAVE_LIBXMSS
+    #include <wolfssl/wolfcrypt/ext_xmss.h>
+#endif
+
+static void wolfBoot_verify_signature(uint8_t key_slot,
+        struct wolfBoot_image *img, uint8_t *sig)
+{
+    int       ret = 0;
+    XmssKey   xmss;
+    word32    pub_len = 0;
+    uint8_t * pubkey = NULL;
+
+    wolfBoot_printf("info: XMSS wolfBoot_verify_signature\n");
+
+    pubkey = keystore_get_buffer(key_slot);
+    if (pubkey == NULL) {
+        wolfBoot_printf("error: Xmss pubkey not found\n");
+        return;
+    }
+
+    ret = wc_XmssKey_Init(&xmss, NULL, INVALID_DEVID);
+    if (ret != 0) {
+        wolfBoot_printf("error: wc_XmssKey_Init returned %d\n", ret);
+        return;
+    }
+
+    wolfBoot_printf("info: using XMSS parameters: %s\n", XMSS_PARAMS);
+
+    /* Set the XMSS parameters. */
+    ret = wc_XmssKey_SetParamStr(&xmss, XMSS_PARAMS);
+    if (ret != 0) {
+        /* Something is wrong with the pub key or XMSS parameters. */
+        wolfBoot_printf("error: wc_XmssKey_SetParamStr(%s)" \
+                        " returned %d\n", XMSS_PARAMS, ret);
+        return;
+    }
+
+    wolfBoot_printf("info: using XMSS parameters: %s\n", XMSS_PARAMS);
+
+    /* Set the public key. */
+    ret = wc_XmssKey_ImportPubRaw(&xmss, pubkey, KEYSTORE_PUBKEY_SIZE);
+    if (ret != 0) {
+        /* Something is wrong with the pub key or LMS parameters. */
+        wolfBoot_printf("error: wc_XmssKey_ImportPubRaw" \
+                        " returned %d\n", ret);
+        return;
+    }
+
+    ret = wc_XmssKey_Verify(&xmss, sig, IMAGE_SIGNATURE_SIZE, img->sha_hash,
+                           WOLFBOOT_SHA_DIGEST_SIZE);
+
+    if (ret == 0) {
+        wolfBoot_printf("info: wc_XmssKey_Verify returned OK\n");
+        wolfBoot_image_confirm_signature_ok(img);
+    }
+    else {
+        wolfBoot_printf("error: wc_XmssKey_Verify returned %d\n", ret);
+    }
+
+    wc_XmssKey_Free(&xmss);
+}
+#endif /* WOLFBOOT_SIGN_XMSS */
+
 #endif /* WOLFBOOT_TPM && WOLFBOOT_TPM_VERIFY */
 
 

tools/config.mk

@@ -34,6 +34,7 @@ ifeq ($(ARCH),)
   LMS_LEVELS?=0
   LMS_HEIGHT?=0
   LMS_WINTERNITZ?=0
+  XMSS_PARAMS?=XMSS-SHA2_10_256
   NO_MPU?=0
   ENCRYPT?=0
   ENCRYPT_WITH_CHACHA?=0
@@ -93,4 +94,5 @@ CONFIG_VARS:= ARCH TARGET SIGN HASH MCUXSDK MCUXPRESSO MCUXPRESSO_CPU MCUXPRESSO
 	ENCRYPT_WITH_CHACHA ENCRYPT_WITH_AES128 ENCRYPT_WITH_AES256 ARMORED \
 	LMS_LEVELS LMS_HEIGHT LMS_WINTERNITZ \
 	WOLFBOOT_UNIVERSAL_KEYSTORE \
+	XMSS_PARAMS \
 	ELF

tools/keytools/Makefile

@@ -25,6 +25,15 @@ ifeq ($(SIGN),LMS)
             -D"LMS_WINTERNITZ=$(LMS_WINTERNITZ)"
 endif
 
+ifeq ($(SIGN),XMSS)
+  $(info xmss params: $(XMSS_PARAMS))
+  XMSSDIR = $(WOLFBOOTDIR)/lib/xmss
+  CFLAGS  +=-DWOLFBOOT_SIGN_XMSS -DWOLFSSL_HAVE_XMSS -DHAVE_LIBXMSS -I$(XMSSDIR) \
+            -D"IMAGE_SIGNATURE_SIZE"=$(IMAGE_SIGNATURE_SIZE) \
+            -DXMSS_PARAMS=\"$(XMSS_PARAMS)\"
+endif
+
+
 # option variables
 DEBUG_FLAGS     = -g -DDEBUG -DDEBUG_SIGNTOOL -DDEBUG_WOLFSSL -DDEBUG_WOLFSSL_VERBOSE
 SANITIZE_FLAGS  = -fsanitize=address
@@ -75,16 +84,33 @@ OBJS_REAL=\
 	$(WOLFDIR)/wolfcrypt/src/tfm.o \
 	$(WOLFDIR)/wolfcrypt/src/wc_port.o \
 	$(WOLFDIR)/wolfcrypt/src/wolfmath.o \
-	$(WOLFDIR)/wolfcrypt/src/ext_lms.o
+	$(WOLFDIR)/wolfcrypt/src/ext_lms.o \
+	$(WOLFDIR)/wolfcrypt/src/ext_xmss.o
 
 OBJS_REAL+=\
 	$(WOLFBOOTDIR)/src/delta.o
 
+ifeq ($(SIGN),XMSS)
+OBJS_REAL+=\
+	$(XMSSDIR)/params.o \
+	$(XMSSDIR)/thash.o \
+	$(XMSSDIR)/hash_address.o \
+	$(XMSSDIR)/wots.o \
+	$(XMSSDIR)/xmss.o \
+	$(XMSSDIR)/xmss_core_fast.o \
+	$(XMSSDIR)/xmss_commons.o \
+	$(XMSSDIR)/utils.o
+endif
+
 OBJS_VIRT=$(addprefix $(OBJDIR), $(notdir $(OBJS_REAL)))
 vpath %.c $(WOLFDIR)/wolfcrypt/src/
 vpath %.c $(WOLFBOOTDIR)/src/
 vpath %.c ./
 
+ifeq ($(SIGN),XMSS)
+    vpath %.c $(XMSSDIR)/
+endif
+
 .PHONY: clean all
 
 all: $(WOLFBOOTDIR)/include/target.h sign keygen
@@ -114,6 +140,9 @@ $(OBJDIR)/%.o: $(WOLFBOOTDIR)/src/%.c
 $(OBJDIR)/%.o: $(WOLFDIR)/wolfcrypt/src/%.c
 	$(Q)$(CC) $(CFLAGS) -c -o $@ $<
 
+$(XMSSDIR)/src/%.o: $(XMSSDIR)/src/%.c
+	$(Q)$(CC) $(CFLAGS) -c -o $@ $<
+
 # build templates
 sign: $(OBJS_VIRT) $(LIBS) sign.o
 	@echo "Building signing tool"