Merge pull request #6840 from philljj/xmss_hooks_support

Add XMSS/XMSSMT wolfCrypt hooks.

Author: JacobBarthelmeh

INSTALL

@@ -371,7 +371,7 @@ We also have vcpkg ports for wolftpm, wolfmqtt and curl.
     resulting packages are placed in the root directory of the
     project.
 
-18. Building for RHEL, Fedora, CentOS, SUSE, and openSUSE
+19. Building for RHEL, Fedora, CentOS, SUSE, and openSUSE
 
     To generate a .rpm package, configure wolfSSL with the desired
     configuration. Then run `make rpm` to generate a .rpm package
@@ -380,3 +380,51 @@ We also have vcpkg ports for wolftpm, wolfmqtt and curl.
     resulting packages are placed in the root directory of the
     project.
 
+20. Building with xmss-reference lib for XMSS/XMSS^MT support [EXPERIMENTAL]
+
+    Experimental support for XMSS/XMSS^MT has been achieved by integration
+    with the xmss-reference implementation from RFC 8391 (XMSS: eXtended
+    Merkle Signature Scheme). We support a patched version of xmss-reference
+    based on this git commit:
+      171ccbd26f098542a67eb5d2b128281c80bd71a6
+    At the time of writing this, this is the HEAD of the master branch of
+    the xmss-reference project.
+
+    How to get the xmss-reference library:
+      $ mkdir ~/xmss
+      $ cd ~/xmss
+      $ git clone https://github.com/XMSS/xmss-reference.git src
+      $ cd src
+      $ git checkout 171ccbd26f098542a67eb5d2b128281c80bd71a6
+      $ git apply <path to xmss reference patch>
+
+    The patch may be found in the wolfssl-examples repo here:
+      pq/stateful_hash_sig/0001-Patch-to-support-wolfSSL-xmss-reference-integration.patch
+
+    To build patched xmss-reference:
+      $ make xmss_lib.a
+
+    To build verify-only patched xmss-reference:
+      $ make xmss_verify_lib.a
+
+    Note that this patch changes xmss-reference to use wolfCrypt SHA256 hashing,
+    by registering a SHA callback function in xmss-reference. It
+    thus benefits from all the same asm speedups as wolfCrypt SHA hashing.
+    Depending on architecture you may build with --enable-intelasm, or
+    --enable-armasm, and see 30-40% speedups in XMSS/XMSS^MT.
+
+    For full keygen, signing, verifying, and benchmarking support, build
+    wolfSSL with:
+      $ ./configure \
+          --enable-xmss \
+          --with-libxmss=<path to xmss src dir>
+      $ make
+
+    Run the benchmark against XMSS/XMSS^MT with:
+      $ ./wolfcrypt/benchmark/benchmark -xmss_xmssmt
+
+    For a leaner xmss verify-only build, build with
+      $ ./configure \
+          --enable-xmss=verify-only \
+          --with-libxmss=<path to xmss src dir>
+      $ make

configure.ac

@@ -1143,6 +1143,100 @@ then
 fi
 
 
+# XMSS
+AC_ARG_ENABLE([xmss],
+    [AS_HELP_STRING([--enable-xmss],[Enable stateful XMSS/XMSS^MT signatures (default: disabled)])],
+    [ ENABLED_XMSS=$enableval ],
+    [ ENABLED_XMSS=no ]
+    )
+
+ENABLED_WC_XMSS=no
+for v in `echo $ENABLED_XMSS | tr "," " "`
+do
+  case $v in
+  yes)
+    ;;
+  no)
+    ;;
+  verify-only)
+    XMSS_VERIFY_ONLY=yes
+    AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_XMSS_VERIFY_ONLY -DXMSS_VERIFY_ONLY"
+    ;;
+  wolfssl)
+    ENABLED_WC_XMSS=yes
+    AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_WC_XMSS"
+    ;;
+  *)
+    AC_MSG_ERROR([Invalid choice for XMSS []: $ENABLED_XMSS.])
+    break;;
+  esac
+done
+
+if test "$ENABLED_XMSS" != "no"
+then
+    AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_HAVE_XMSS"
+
+    if test "$ENABLED_WC_XMSS" = "no";
+    then
+        # Default is to use hash-sigs XMSS lib. Make sure it's enabled.
+        if test "$ENABLED_LIBXMSS" = "no"; then
+            AC_MSG_ERROR([The default implementation for XMSS is the xmss-reference lib.
+            Please use --with-libxmss.])
+        fi
+    fi
+fi
+
+# libxmss
+# Get the path to xmss-reference.
+ENABLED_LIBXMSS="no"
+trylibxmssdir=""
+AC_ARG_WITH([libxmss],
+    [AS_HELP_STRING([--with-libxmss=PATH],[PATH to xmss-reference root dir. EXPERIMENTAL!])],
+    [
+        AC_MSG_CHECKING([for libxmss])
+
+        trylibxmssdir=$withval
+
+        if test -e $trylibxmssdir; then
+            libxmss_linked=yes
+        else
+            AC_MSG_ERROR([libxmss isn't found.
+            If it's already installed, specify its path using --with-libxmss=/dir/])
+        fi
+        if test "$XMSS_VERIFY_ONLY" = "yes"; then
+            if test -e $trylibxmssdir/xmss_verify_lib.a; then
+                CPPFLAGS="$AM_CPPFLAGS -DHAVE_LIBXMSS -I$trylibxmssdir"
+                LIB_STATIC_ADD="$LIB_STATIC_ADD $trylibxmssdir/xmss_verify_lib.a"
+                enable_shared=no
+                enable_static=yes
+                libxmss_linked=yes
+            else
+                AC_MSG_ERROR([xmss_verify_lib.a isn't found.
+                If it's already installed, specify its path using --with-libxmss=/dir/])
+            fi
+        elif test -e $trylibxmssdir/xmss_lib.a; then
+            CPPFLAGS="$AM_CPPFLAGS -DHAVE_LIBXMSS -I$trylibxmssdir"
+            LIB_STATIC_ADD="$LIB_STATIC_ADD $trylibxmssdir/xmss_lib.a"
+            enable_shared=no
+            enable_static=yes
+            libxmss_linked=yes
+        else
+            AC_MSG_ERROR([libxmss isn't found.
+            If it's already installed, specify its path using --with-libxmss=/dir/])
+        fi
+
+        XMSS_ROOT=$trylibxmssdir
+
+        AC_MSG_RESULT([yes])
+        AM_CPPFLAGS="$CPPFLAGS"
+
+        AM_CFLAGS="$AM_CFLAGS -DHAVE_LIBXMSS -I$trylibxmssdir"
+        ENABLED_LIBXMSS="yes"
+        AC_SUBST([XMSS_ROOT])
+    ],
+    [XMSS_ROOT=""]
+)
+
 # LMS
 AC_ARG_ENABLE([lms],
     [AS_HELP_STRING([--enable-lms],[Enable stateful LMS/HSS signatures (default: disabled)])],
@@ -9024,6 +9118,7 @@ AM_CONDITIONAL([BUILD_GE448], [test "x$ENABLED_GE448" = "xyes" || test "x$ENABLE
 AM_CONDITIONAL([BUILD_CURVE448],[test "x$ENABLED_CURVE448" = "xyes" || test "x$ENABLED_USERSETTINGS" = "xyes"])
 AM_CONDITIONAL([BUILD_CURVE448_SMALL],[test "x$ENABLED_CURVE448_SMALL" = "xyes" || test "x$ENABLED_USERSETTINGS" = "xyes"])
 AM_CONDITIONAL([BUILD_WC_LMS],[test "x$ENABLED_WC_LMS" != "xno" || test "x$ENABLED_USERSETTINGS" = "xyes"])
+AM_CONDITIONAL([BUILD_WC_XMSS],[test "x$ENABLED_WC_XMSS" != "xno" || test "x$ENABLED_USERSETTINGS" = "xyes"])
 AM_CONDITIONAL([BUILD_WC_KYBER],[test "x$ENABLED_WC_KYBER" != "xno" || test "x$ENABLED_USERSETTINGS" = "xyes"])
 AM_CONDITIONAL([BUILD_ECCSI],[test "x$ENABLED_ECCSI" = "xyes" || test "x$ENABLED_USERSETTINGS" = "xyes"])
 AM_CONDITIONAL([BUILD_SAKKE],[test "x$ENABLED_SAKKE" = "xyes" || test "x$ENABLED_USERSETTINGS" = "xyes"])
@@ -9064,6 +9159,7 @@ AM_CONDITIONAL([BUILD_CRL_MONITOR],[test "x$ENABLED_CRL_MONITOR" = "xyes"])
 AM_CONDITIONAL([BUILD_USER_RSA],[test "x$ENABLED_USER_RSA" = "xyes"] )
 AM_CONDITIONAL([BUILD_USER_CRYPTO],[test "x$ENABLED_USER_CRYPTO" = "xyes"])
 AM_CONDITIONAL([BUILD_LIBLMS],[test "x$ENABLED_LIBLMS" = "xyes"])
+AM_CONDITIONAL([BUILD_LIBXMSS],[test "x$ENABLED_LIBXMSS" = "xyes"])
 AM_CONDITIONAL([BUILD_LIBOQS],[test "x$ENABLED_LIBOQS" = "xyes"])
 AM_CONDITIONAL([BUILD_WNR],[test "x$ENABLED_WNR" = "xyes"])
 AM_CONDITIONAL([BUILD_SRP],[test "x$ENABLED_SRP" = "xyes" || test "x$ENABLED_USERSETTINGS" = "xyes"])
@@ -9497,6 +9593,11 @@ echo "   * ED448:                      $ENABLED_ED448"
 echo "   * ED448 streaming:            $ENABLED_ED448_STREAM"
 echo "   * LMS:                        $ENABLED_LMS"
 echo "   * LMS wolfSSL impl:           $ENABLED_WC_LMS"
+echo "   * XMSS:                       $ENABLED_XMSS"
+echo "   * XMSS wolfSSL impl:          $ENABLED_WC_XMSS"
+if test "$ENABLED_LIBXMSS" = "yes"; then
+echo "   * XMSS_ROOT:                  $XMSS_ROOT"
+fi
 echo "   * KYBER:                      $ENABLED_KYBER"
 echo "   * KYBER wolfSSL impl:         $ENABLED_WC_KYBER"
 echo "   * ECCSI                       $ENABLED_ECCSI"
@@ -9552,6 +9653,7 @@ echo "   * Persistent session cache:   $ENABLED_SAVESESSION"
 echo "   * Persistent cert    cache:   $ENABLED_SAVECERT"
 echo "   * Atomic User Record Layer:   $ENABLED_ATOMICUSER"
 echo "   * Public Key Callbacks:       $ENABLED_PKCALLBACKS"
+echo "   * libxmss:                    $ENABLED_LIBXMSS"
 echo "   * liblms:                     $ENABLED_LIBLMS"
 echo "   * liboqs:                     $ENABLED_LIBOQS"
 echo "   * Whitewood netRandom:        $ENABLED_WNR"

src/include.am

@@ -731,6 +731,10 @@ if BUILD_WC_LMS
 src_libwolfssl@LIBSUFFIX@_la_SOURCES += wolfcrypt/src/wc_lms.c
 endif
 
+if BUILD_WC_XMSS
+src_libwolfssl@LIBSUFFIX@_la_SOURCES += wolfcrypt/src/wc_xmss.c
+endif
+
 if BUILD_CURVE25519
 src_libwolfssl@LIBSUFFIX@_la_SOURCES += wolfcrypt/src/curve25519.c
 endif
@@ -836,6 +840,10 @@ if BUILD_LIBLMS
 src_libwolfssl@LIBSUFFIX@_la_SOURCES += wolfcrypt/src/ext_lms.c
 endif
 
+if BUILD_LIBXMSS
+src_libwolfssl@LIBSUFFIX@_la_SOURCES += wolfcrypt/src/ext_xmss.c
+endif
+
 if BUILD_LIBZ
 src_libwolfssl@LIBSUFFIX@_la_SOURCES += wolfcrypt/src/compress.c
 endif