Skip to content

Commit 726cd28

Browse files
philljjdanielinux
philljj
authored and
danielinux
committed
Update PQ docs, and fix spelling errors.
1 parent 92e048a commit 726cd28

5 files changed

Lines changed: 81 additions & 61 deletions

File tree

‎config/examples/sim-xmss.config‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# XMSS/XMSS^MT/HSS signature example, based on sim.config example.
22
#
3+
# XMSS/XMSS^MT is a post-quantum, stateful, hash-based signature scheme.
4+
#
5+
# Use the helper script
6+
# tools/xmss/xmss_siglen.sh
7+
# to calculate your signature length given an xmss parameter string.
38
#
49

510
ARCH=sim

‎docs/PQ.md‎

Lines changed: 66 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -19,42 +19,18 @@ See these links for more info on stateful HBS support and wolfSSL/wolfCrypt:
1919
- https://www.wolfssl.com/documentation/manuals/wolfssl/appendix07.html#post-quantum-stateful-hash-based-signatures
2020
- https://github.com/wolfSSL/wolfssl-examples/tree/master/pq/stateful_hash_sig
2121

22+
## Supported PQ Signature Methods
2223

23-
## LMS/HSS
24+
These four PQ signature options are supported:
25+
- LMS: uses wolfcrypt implementation from `wc_lms.c`, and `wc_lms_impl.c`.
26+
- XMSS: uses wolfcrypt implementation from `wc_xmss.c`, and `wc_xmss_impl.c`.
27+
- ext_LMS: uses external integration from `ext_lms.c`.
28+
- ext_XMSS: uses external integration from `ext_xmss.c`.
2429

30+
The wolfcrypt implementations are more performant and are recommended.
31+
The external integrations are experimental and for testing interoperability.
2532

26-
### Building with LMS Support
27-
28-
LMS/HSS support in wolfCrypt requires the hash-sigs library ( https://github.com/cisco/hash-sigs ).
29-
Use the following procedure to prepare hash-sigs for building with wolfBoot:
30-
31-
```
32-
$ cd lib
33-
$ mkdir hash-sigs
34-
$ls
35-
CMakeLists.txt hash-sigs wolfssl wolfTPM
36-
$ cd hash-sigs
37-
$ mkdir lib
38-
$ git clone https://github.com/cisco/hash-sigs.git src
39-
$ cd src
40-
$ git checkout b0631b8891295bf2929e68761205337b7c031726
41-
$ git apply ../../../tools/lms/0001-Patch-to-support-wolfBoot-LMS-build.patch
42-
```
43-
44-
Nothing more is needed, as wolfBoot will automatically produce the required
45-
hash-sigs build artifacts.
46-
47-
Note: the hash-sigs project only builds static libraries:
48-
- hss_verify.a: a single-threaded verify-only static lib.
49-
- hss_lib.a: a single-threaded static lib.
50-
- hss_lib_thread.a: a multi-threaded static lib.
51-
52-
The keytools utility links against `hss_lib.a`, as it needs full
53-
keygen, signing, and verifying functionality. However wolfBoot
54-
links directly with the subset of objects in the `hss_verify.a`
55-
build rule, as it only requires verify functionality.
56-
57-
### LMS Config
33+
### LMS/HSS Config
5834

5935
A new LMS sim example has been added here:
6036
```
@@ -86,31 +62,8 @@ winternitz: 8
8662
signature length: 2644
8763
```
8864

89-
## XMSS/XMSS^MT
65+
### XMSS/XMSS^MT Config
9066

91-
### Building with XMSS Support
92-
93-
XMSS/XMSS^MT support in wolfCrypt requires a patched version of the
94-
xmss-reference library ( https://github.com/XMSS/xmss-reference.git ).
95-
Use the following procedure to prepare xmss-reference for building with
96-
wolfBoot:
97-
98-
```
99-
$ cd lib
100-
$ git clone https://github.com/XMSS/xmss-reference.git xmss
101-
$ ls
102-
CMakeLists.txt wolfPKCS11 wolfTPM wolfssl xmss
103-
$ cd xmss
104-
$ git checkout 171ccbd26f098542a67eb5d2b128281c80bd71a6
105-
$ git apply ../../tools/xmss/0001-Patch-to-support-wolfSSL-xmss-reference-integration.patch
106-
```
107-
108-
The patch creates an addendum readme, `patch_readme.md`, with further comments.
109-
110-
Nothing more is needed beyond the patch step, as wolfBoot will handle building
111-
the xmss build artifacts it requires.
112-
113-
### XMSS Config
11467
A new XMSS sim example has been added here:
11568
```
11669
config/examples/sim-xmss.config
@@ -142,3 +95,59 @@ $ ./tools/xmss/xmss_siglen.sh XMSSMT-SHA2_20/2_256
14295
parameter set: XMSSMT-SHA2_20/2_256
14396
signature length: 4963
14497
```
98+
99+
## Building the external PQ Integrations
100+
101+
### ext_LMS Support
102+
103+
The external LMS/HSS support in wolfCrypt requires the hash-sigs library ( https://github.com/cisco/hash-sigs ).
104+
Use the following procedure to prepare hash-sigs for building with wolfBoot:
105+
106+
```
107+
$ cd lib
108+
$ mkdir hash-sigs
109+
$ls
110+
CMakeLists.txt hash-sigs wolfssl wolfTPM
111+
$ cd hash-sigs
112+
$ mkdir lib
113+
$ git clone https://github.com/cisco/hash-sigs.git src
114+
$ cd src
115+
$ git checkout b0631b8891295bf2929e68761205337b7c031726
116+
$ git apply ../../../tools/lms/0001-Patch-to-support-wolfBoot-LMS-build.patch
117+
```
118+
119+
Nothing more is needed, as wolfBoot will automatically produce the required
120+
hash-sigs build artifacts.
121+
122+
Note: the hash-sigs project only builds static libraries:
123+
- hss_verify.a: a single-threaded verify-only static lib.
124+
- hss_lib.a: a single-threaded static lib.
125+
- hss_lib_thread.a: a multi-threaded static lib.
126+
127+
The keytools utility links against `hss_lib.a`, as it needs full
128+
keygen, signing, and verifying functionality. However wolfBoot
129+
links directly with the subset of objects in the `hss_verify.a`
130+
build rule, as it only requires verify functionality.
131+
132+
133+
### ext_XMSS Support
134+
135+
The external XMSS/XMSS^MT support in wolfCrypt requires a patched version of the
136+
xmss-reference library ( https://github.com/XMSS/xmss-reference.git ).
137+
Use the following procedure to prepare xmss-reference for building with
138+
wolfBoot:
139+
140+
```
141+
$ cd lib
142+
$ git clone https://github.com/XMSS/xmss-reference.git xmss
143+
$ ls
144+
CMakeLists.txt wolfPKCS11 wolfTPM wolfssl xmss
145+
$ cd xmss
146+
$ git checkout 171ccbd26f098542a67eb5d2b128281c80bd71a6
147+
$ git apply ../../tools/xmss/0001-Patch-to-support-wolfSSL-xmss-reference-integration.patch
148+
```
149+
150+
The patch creates an addendum readme, `patch_readme.md`, with further comments.
151+
152+
Nothing more is needed beyond the patch step, as wolfBoot will handle building
153+
the xmss build artifacts it requires.

‎docs/STM32-TZ.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ OPTION BYTES BANK: 0
5353
nRST_STOP : 0x1 (No reset generated when entering Stop mode)
5454
nRST_STDBY : 0x1 (No reset generated when entering Standby mode)
5555
nRST_SHDW : 0x1 (No reset generated when entering the Shutdown mode)
56-
IWDG_SW : 0x1 (Software independant watchdog)
56+
IWDG_SW : 0x1 (Software independent watchdog)
5757
IWDG_STOP : 0x1 (IWDG counter active in stop mode)
5858
IWDG_STDBY : 0x1 (IWDG counter active in standby mode)
5959
WWDG_SW : 0x1 (Software window watchdog)

‎docs/Signing.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,12 @@ file is in this format.
104104
* `--rsa4096` Use rsa4096 for signing the firmware. Assume that the given KEY.DER
105105
file is in this format.
106106

107+
* `--lms` Use LMS/HSS for signing the firmware. Assume that the given KEY.DER
108+
file is in this format.
109+
110+
* `--xmss` Use XMSS/XMSS^MT for signing the firmware. Assume that the given KEY.DER
111+
file is in this format.
112+
107113
* `--no-sign` Disable secure boot signature verification. No signature
108114
verification is performed in the bootloader, and the KEY.DER argument should
109115
not be supplied.

‎docs/Targets.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1766,7 +1766,7 @@ O.K.
17661766
17671767
Reset or power cycle board.
17681768
1769-
Once wolfBoot has performaed validation of the partition and booted the D15 Green LED on P3_13 will illuminate.
1769+
Once wolfBoot has performed validation of the partition and booted the D15 Green LED on P3_13 will illuminate.
17701770
17711771
### MCX A: Testing firmware update
17721772
@@ -1935,10 +1935,10 @@ Flash Allocation:
19351935
Detailed steps can be found at [Readme.md](../IDE/Renesas/e2studio/RA6M4/Readme.md).
19361936

19371937
## Renesas RZN2L
1938-
This example demonstrates simple secure firmware boot from extarnal flash by wolfBoot.
1938+
This example demonstrates simple secure firmware boot from external flash by wolfBoot.
19391939
A sample application v1 is securely loaded into internal RAM if there is not higher version in update region. A sample application v2 will be loaded when it is in update region.Both versions behave the same except blinking LED Red(v1) or Yellow(v2). They are compiled by e2Studio and running on the target board.
19401940

1941-
The exmaple uses SPI boot mode with external flash on the evaluation board. On this boot mode, the loader program, which is wolfBoot, is copied to the internal RAM(B-TCM). wolfBoot copies the application program from external flash memory to RAM(System RAM). As final step of wolfBoot the entry point of the copied applicatin program is called if its integrity and authenticity are OK.
1941+
The example uses SPI boot mode with external flash on the evaluation board. On this boot mode, the loader program, which is wolfBoot, is copied to the internal RAM(B-TCM). wolfBoot copies the application program from external flash memory to RAM(System RAM). As final step of wolfBoot the entry point of the copied application program is called if its integrity and authenticity are OK.
19421942

19431943
![Operation Overview](../IDE/Renesas/e2studio/RZN2L/doc/image1.png)
19441944

0 commit comments

Comments
 (0)