Skip to content

Commit

Permalink
Merge pull request #110 from philljj/xmss_hooks_support
Browse files Browse the repository at this point in the history 
Add XMSS/XMSS^MT hooks documentation.
  • Loading branch information
@JacobBarthelmeh
JacobBarthelmeh authored Oct 16, 2023
2 parents f2bcd7a + aa97330 commit 181fcb6
Showing 1 changed file with 179 additions and 1 deletion.
180 changes: 179 additions & 1 deletion wolfSSL/src/appendix07.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -957,7 +957,7 @@ For more algorithm-specific benchmarking information, the OQS Project has benchm

## Post-Quantum Stateful Hash-Based Signatures

This section covers post-quantum stateful hash-based signature (HBS) schemes such as LMS/HSS, for which wolfSSL has recently added support.
This section covers post-quantum stateful hash-based signature (HBS) schemes such as LMS/HSS, and XMSS/XMSS^MT, for which wolfSSL has recently added support.

### Motivation

Expand Down Expand Up @@ -1116,3 +1116,181 @@ LMS/HSS L4_H5_W8 5340 sign 100 ops took 1.066 sec, avg 10.665 ms, 93.
LMS/HSS L4_H5_W8 5340 verify 200 ops took 1.478 sec, avg 7.388 ms, 135.358 ops/sec
Benchmark complete
```

### XMSS/XMSS^MT signatures

wolfSSL is adding support for XMSS/XMSS^MT stateful hash-based signatures. Similar to LMS, this
will be done by experimental integration with the xmss-reference repository
(https://github.com/XMSS/xmss-reference.git), from RFC 8391
(https://www.rfc-editor.org/rfc/rfc8391.html).

The xmss-reference supports `xmss_core_fast`, and `xmss_core` implementations. The `xmss_core_fast`
implementation was designed to prioritize performance with larger private key sizes as a tradeoff.
Our integration uses `xmss_core_fast`, with a patch applied so that the wolfCrypt SHA256 implementation
may be used instead.

The patch may be found here
```pq/stateful_hash_sig/0001-Patch-to-support-wolfSSL-xmss-reference-integration.patch```
in the wolfssl-examples repository: https://github.com/wolfSSL/wolfssl-examples.

Overall, XMSS/XMSS^MT is similar to LMS/HSS. For a more detailed comparison see
"LMS vs XMSS: Comparison of two Hash-Based Signature Standards" (https://eprint.iacr.org/2017/349.pdf).


XMSS^MT is the Multi-Tree generalization of XMSS,
analogous to HSS with LMS, with the distinction that the Winternitz value is fixed to `w=16` in
XMSS/XMSS^MT. The public key is slightly larger in XMSS/XMSS^MT (at 68 bytes in XMSS/XMSS^MT, vs 60 bytes in LMS/HSS), while signatures are slightly smaller.

#### Supported Parameters

wolfSSL supports the SHA256 XMSS/XMSS^MT parameter sets from Tables 10 and 11 from NIST SP 800-208 (https://csrc.nist.gov/pubs/sp/800/208/final).

parameter set name | Oid | n | w | h | d | h/d | Sig len
----------------------- | ----------- | --- | --- | --- | --- | --- | --
XMSS | | | | | | |
"XMSS-SHA2_10_256" | 0x00000001 | 32 | 16 | 10 | 1 | 10 | 2500
"XMSS-SHA2_16_256" | 0x00000002 | 32 | 16 | 16 | 1 | 16 | 2692
"XMSS-SHA2_20_256" | 0x00000003 | 32 | 16 | 20 | 1 | 20 | 2820
XMSS^MT | | | | | | |
"XMSSMT-SHA2_20/2_256" | 0x00000001 | 32 | 16 | 20 | 2 | 10 | 4963
"XMSSMT-SHA2_20/4_256" | 0x00000002 | 32 | 16 | 20 | 4 | 5 | 9251
"XMSSMT-SHA2_40/2_256" | 0x00000003 | 32 | 16 | 40 | 2 | 20 | 5605
"XMSSMT-SHA2_40/4_256" | 0x00000004 | 32 | 16 | 40 | 4 | 10 | 9893
"XMSSMT-SHA2_40/8_256" | 0x00000005 | 32 | 16 | 40 | 8 | 5 | 18469
"XMSSMT-SHA2_60/3_256" | 0x00000006 | 32 | 16 | 60 | 3 | 20 | 8392
"XMSSMT-SHA2_60/6_256" | 0x00000007 | 32 | 16 | 60 | 6 | 10 | 14824
"XMSSMT-SHA2_60/12_256" | 0x00000008 | 32 | 16 | 60 | 12 | 5 | 27688

In the table above, `n` is the number of bytes in the HASH function, `w` the Winternitz value, `h` the total height of the tree system, and `d` the number of levels of trees.

Key generation time is strongly determined by the height of the
first level tree (or `h/d`), while signature length grows primarily with `d` (the number of hyper
tree levels).

Similar to LMS/HSS, the number of available signatures grows as `2**h`, where h is the
total height of the tree system.

#### Benchmark Data

In the following, benchmark data is shown for several XMSS/XMSS^MT parameter sets,
for intel x86_64 and aarch64. The SHA256 performance on these systems is also listed for reference,
as computing the large number of required hash chains will constitute the bulk of the CPU
work for XMSS/XMSS^MT. Additionally, our patch to xmss-reference substitutes wolfCrypt's SHA256 implementation, and therefore benefits from the same ASM speedups.

As previously mentioned, our xmss integration is using the `xmss_core_fast` implementation from xmss-reference, which has faster performance at the tradeoff of larger private key sizes.

**x86_64**

The following x86_64 benchmark data were taken on an 8-core Intel i7-8700 CPU @ 3.20GHz, on Fedora 38 (`6.2.9-300.fc38.x86_64`). This CPU has `avx avx2` flags, which can accelerate hash operations and be utilized with `--enable-intelasm`.

With `--enable-intelasm`:

```text
$./wolfcrypt/benchmark/benchmark -xmss_xmssmt -sha256
------------------------------------------------------------------------------
wolfSSL version 5.6.3
------------------------------------------------------------------------------
Math: Multi-Precision: Wolf(SP) word-size=64 bits=4096 sp_int.c
wolfCrypt Benchmark (block bytes 1048576, min 1.0 sec each)
SHA-256 500 MiB took 1.009 seconds, 495.569 MiB/s Cycles per byte = 6.14
XMSS-SHA2_10_256 2500 sign 200 ops took 1.010 sec, avg 5.052 ms, 197.925 ops/sec
XMSS-SHA2_10_256 2500 verify 1600 ops took 1.011 sec, avg 0.632 ms, 1582.844 ops/sec
XMSSMT-SHA2_20/2_256 4963 sign 200 ops took 1.286 sec, avg 6.431 ms, 155.504 ops/sec
XMSSMT-SHA2_20/2_256 4963 verify 700 ops took 1.009 sec, avg 1.441 ms, 693.905 ops/sec
XMSSMT-SHA2_20/4_256 9251 sign 300 ops took 1.223 sec, avg 4.076 ms, 245.335 ops/sec
XMSSMT-SHA2_20/4_256 9251 verify 400 ops took 1.027 sec, avg 2.569 ms, 389.329 ops/sec
XMSSMT-SHA2_40/4_256 9893 sign 200 ops took 1.466 sec, avg 7.332 ms, 136.394 ops/sec
XMSSMT-SHA2_40/4_256 9893 verify 400 ops took 1.024 sec, avg 2.560 ms, 390.627 ops/sec
XMSSMT-SHA2_40/8_256 18469 sign 300 ops took 1.202 sec, avg 4.006 ms, 249.637 ops/sec
XMSSMT-SHA2_40/8_256 18469 verify 200 ops took 1.089 sec, avg 5.446 ms, 183.635 ops/sec
XMSSMT-SHA2_60/6_256 14824 sign 200 ops took 1.724 sec, avg 8.618 ms, 116.033 ops/sec
XMSSMT-SHA2_60/6_256 14824 verify 300 ops took 1.136 sec, avg 3.788 ms, 263.995 ops/sec
XMSSMT-SHA2_60/12_256 27688 sign 300 ops took 1.210 sec, avg 4.034 ms, 247.889 ops/sec
XMSSMT-SHA2_60/12_256 27688 verify 200 ops took 1.575 sec, avg 7.877 ms, 126.946 ops/sec
Benchmark complete
```

Without `--enable-intelasm`:

```text
$./wolfcrypt/benchmark/benchmark -xmss_xmssmt -sha256
------------------------------------------------------------------------------
wolfSSL version 5.6.3
------------------------------------------------------------------------------
Math: Multi-Precision: Wolf(SP) word-size=64 bits=4096 sp_int.c
wolfCrypt Benchmark (block bytes 1048576, min 1.0 sec each)
SHA-256 275 MiB took 1.005 seconds, 273.549 MiB/s Cycles per byte = 11.13
XMSS-SHA2_10_256 2500 sign 200 ops took 1.356 sec, avg 6.781 ms, 147.480 ops/sec
XMSS-SHA2_10_256 2500 verify 1200 ops took 1.025 sec, avg 0.854 ms, 1170.547 ops/sec
XMSSMT-SHA2_20/2_256 4963 sign 200 ops took 1.687 sec, avg 8.436 ms, 118.546 ops/sec
XMSSMT-SHA2_20/2_256 4963 verify 600 ops took 1.187 sec, avg 1.978 ms, 505.663 ops/sec
XMSSMT-SHA2_20/4_256 9251 sign 200 ops took 1.119 sec, avg 5.593 ms, 178.785 ops/sec
XMSSMT-SHA2_20/4_256 9251 verify 300 ops took 1.086 sec, avg 3.622 ms, 276.122 ops/sec
XMSSMT-SHA2_40/4_256 9893 sign 200 ops took 1.991 sec, avg 9.954 ms, 100.460 ops/sec
XMSSMT-SHA2_40/4_256 9893 verify 300 ops took 1.043 sec, avg 3.478 ms, 287.545 ops/sec
XMSSMT-SHA2_40/8_256 18469 sign 200 ops took 1.114 sec, avg 5.572 ms, 179.454 ops/sec
XMSSMT-SHA2_40/8_256 18469 verify 200 ops took 1.495 sec, avg 7.476 ms, 133.770 ops/sec
XMSSMT-SHA2_60/6_256 14824 sign 100 ops took 1.111 sec, avg 11.114 ms, 89.975 ops/sec
XMSSMT-SHA2_60/6_256 14824 verify 200 ops took 1.070 sec, avg 5.349 ms, 186.963 ops/sec
XMSSMT-SHA2_60/12_256 27688 sign 200 ops took 1.148 sec, avg 5.739 ms, 174.247 ops/sec
XMSSMT-SHA2_60/12_256 27688 verify 100 ops took 1.080 sec, avg 10.797 ms, 92.618 ops/sec
Benchmark complete
```

**aarch64**

The following aarch64 data were taken on Ubuntu linux (`5.15.0-71-generic`) running on an Apple M1, with cpu flags `sha1 sha2 sha3 sha512`, which will specifically significantly accelerate SHA hash operations when built with `--enable-armasm`.

With `--enable-armasm`:

```text
$ ./wolfcrypt/benchmark/benchmark -xmss_xmssmt -sha256
------------------------------------------------------------------------------
wolfSSL version 5.6.3
------------------------------------------------------------------------------
Math: Multi-Precision: Wolf(SP) word-size=64 bits=4096 sp_int.c
wolfCrypt Benchmark (block bytes 1048576, min 1.0 sec each)
SHA-256 2305 MiB took 1.001 seconds, 2303.346 MiB/s
XMSS-SHA2_10_256 2500 sign 800 ops took 1.079 sec, avg 1.349 ms, 741.447 ops/sec
XMSS-SHA2_10_256 2500 verify 6500 ops took 1.007 sec, avg 0.155 ms, 6455.445 ops/sec
XMSSMT-SHA2_20/2_256 4963 sign 700 ops took 1.155 sec, avg 1.650 ms, 606.154 ops/sec
XMSSMT-SHA2_20/2_256 4963 verify 3100 ops took 1.021 sec, avg 0.329 ms, 3037.051 ops/sec
XMSSMT-SHA2_20/4_256 9251 sign 1100 ops took 1.006 sec, avg 0.915 ms, 1093.191 ops/sec
XMSSMT-SHA2_20/4_256 9251 verify 1700 ops took 1.013 sec, avg 0.596 ms, 1677.399 ops/sec
XMSSMT-SHA2_40/4_256 9893 sign 600 ops took 1.096 sec, avg 1.827 ms, 547.226 ops/sec
XMSSMT-SHA2_40/4_256 9893 verify 1600 ops took 1.062 sec, avg 0.664 ms, 1506.946 ops/sec
XMSSMT-SHA2_40/8_256 18469 sign 1100 ops took 1.007 sec, avg 0.916 ms, 1092.214 ops/sec
XMSSMT-SHA2_40/8_256 18469 verify 900 ops took 1.088 sec, avg 1.209 ms, 827.090 ops/sec
XMSSMT-SHA2_60/6_256 14824 sign 600 ops took 1.179 sec, avg 1.966 ms, 508.728 ops/sec
XMSSMT-SHA2_60/6_256 14824 verify 1100 ops took 1.038 sec, avg 0.944 ms, 1059.590 ops/sec
XMSSMT-SHA2_60/12_256 27688 sign 1100 ops took 1.015 sec, avg 0.923 ms, 1083.767 ops/sec
XMSSMT-SHA2_60/12_256 27688 verify 600 ops took 1.149 sec, avg 1.914 ms, 522.367 ops/sec
Benchmark complete
```

Without `--enable-armasm`:

```text
$ ./wolfcrypt/benchmark/benchmark -xmss_xmssmt -sha256
------------------------------------------------------------------------------
wolfSSL version 5.6.3
------------------------------------------------------------------------------
Math: Multi-Precision: Wolf(SP) word-size=64 bits=4096 sp_int.c
wolfCrypt Benchmark (block bytes 1048576, min 1.0 sec each)
SHA-256 190 MiB took 1.020 seconds, 186.277 MiB/s
XMSS-SHA2_10_256 2500 sign 200 ops took 1.908 sec, avg 9.538 ms, 104.845 ops/sec
XMSS-SHA2_10_256 2500 verify 800 ops took 1.002 sec, avg 1.253 ms, 798.338 ops/sec
XMSSMT-SHA2_20/2_256 4963 sign 100 ops took 1.084 sec, avg 10.843 ms, 92.222 ops/sec
XMSSMT-SHA2_20/2_256 4963 verify 500 ops took 1.240 sec, avg 2.479 ms, 403.334 ops/sec
XMSSMT-SHA2_20/4_256 9251 sign 200 ops took 1.615 sec, avg 8.074 ms, 123.855 ops/sec
XMSSMT-SHA2_20/4_256 9251 verify 200 ops took 1.071 sec, avg 5.355 ms, 186.726 ops/sec
XMSSMT-SHA2_40/4_256 9893 sign 100 ops took 1.354 sec, avg 13.543 ms, 73.840 ops/sec
XMSSMT-SHA2_40/4_256 9893 verify 300 ops took 1.483 sec, avg 4.945 ms, 202.237 ops/sec
XMSSMT-SHA2_40/8_256 18469 sign 200 ops took 1.588 sec, avg 7.941 ms, 125.922 ops/sec
XMSSMT-SHA2_40/8_256 18469 verify 100 ops took 1.042 sec, avg 10.415 ms, 96.014 ops/sec
XMSSMT-SHA2_60/6_256 14824 sign 100 ops took 1.571 sec, avg 15.710 ms, 63.654 ops/sec
XMSSMT-SHA2_60/6_256 14824 verify 200 ops took 1.526 sec, avg 7.632 ms, 131.033 ops/sec
XMSSMT-SHA2_60/12_256 27688 sign 200 ops took 1.607 sec, avg 8.036 ms, 124.434 ops/sec
XMSSMT-SHA2_60/12_256 27688 verify 100 ops took 1.501 sec, avg 15.011 ms, 66.616 ops/sec
Benchmark complete
```

0 comments on commit 181fcb6

Please sign in to comment.