Merge remote-tracking branch 'pqm4/master'

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "gitsubmodule"
+    directory: '/'
+    schedule:
+      interval: "monthly"

.github/pull_request_template.md

@@ -0,0 +1,7 @@
+- [ ] PR changes testvectors
+- [ ] Tests pass in qemu
+- [ ] Testvectors pass in qemu
+- [ ] Tests pass on Nucleo-L4R5ZI 
+- [ ] Testvectors pass on Nucleo-L4R5ZI 
+- [ ] Updated Benchmarks
+- [ ] Updated Skiplist entries

.github/workflows/cw308t-stm32f3.yml

@@ -0,0 +1,21 @@
+name: cw308t-stm32f3 build
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches: [ "master" ]
+jobs:
+  build-all:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install Toolchain
+        uses: carlosperate/[email protected]
+        with:
+          release: 13.2.Rel1
+      - name: Build All (cw308t-stm32f3)
+        run: make PLATFORM=cw308t-stm32f3 -j2

.github/workflows/cw308t-stm32f415.yml

@@ -0,0 +1,21 @@
+name: cw308t-stm32f415 build
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches: [ "master" ]
+jobs:
+  build-all:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install Toolchain
+        uses: carlosperate/[email protected]
+        with:
+          release: 13.2.Rel1
+      - name: Build All (cw308t-stm32f415)
+        run: make PLATFORM=cw308t-stm32f415 -j2

.github/workflows/mps2-an386.yml

@@ -0,0 +1,21 @@
+name: mps2-an386 build
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches: [ "master" ]
+jobs:
+  build-all:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install Toolchain
+        uses: carlosperate/[email protected]
+        with:
+          release: 13.2.Rel1
+      - name: Build All (mps2-an386)
+        run: make PLATFORM=mps2-an386 -j2

.github/workflows/nucleo-l476rg.yml

@@ -0,0 +1,21 @@
+name: nucleo-l476rg build
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches: [ "master" ]
+jobs:
+  build-all:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install Toolchain
+        uses: carlosperate/[email protected]
+        with:
+          release: 13.2.Rel1
+      - name: Build All (nucleo-l476rg)
+        run: make PLATFORM=nucleo-l476rg -j2

.github/workflows/nucleo-l4r5zi.yml

@@ -0,0 +1,21 @@
+name: nucleo-l4r5zi build
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches: [ "master" ]
+jobs:
+  build-all:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install Toolchain
+        uses: carlosperate/[email protected]
+        with:
+          release: 13.2.Rel1
+      - name: Build All (nucleo-l4r5zi)
+        run: make PLATFORM=nucleo-l4r5zi -j2

.github/workflows/stm32f4discovery.yml

@@ -0,0 +1,21 @@
+name: stm32f4discovery build
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches: [ "master" ]
+jobs:
+  build-all:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install Toolchain
+        uses: carlosperate/[email protected]
+        with:
+          release: 13.2.Rel1
+      - name: Build All (stm32f4discovery)
+        run: make PLATFORM=stm32f4discovery -j2

Makefile

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0 or CC0-1.0
 .PHONY: all
 all: tests tests-bin
 

README.md

@@ -16,23 +16,39 @@ The design goals of the library are to offer
 * integration of clean implementations from [PQClean](https://github.com/PQClean/PQClean); and
 * easy integration of new schemes and implementations into the framework.
 
-## Previous NIST PQC
+## Scope of pqm4
 
-The master branch of **pqm4** contains schemes that either [selected for standardization by NIST](https://csrc.nist.gov/Projects/post-quantum-cryptography/selected-algorithms-2022) or part of the [4th round of the NIST PQC competition](https://csrc.nist.gov/Projects/post-quantum-cryptography/round-4-submissions).
+The master branch of **pqm4** contains schemes that either
+- standardized by NIST in [FIPS203](https://csrc.nist.gov/pubs/fips/203/final), [FIPS204](https://csrc.nist.gov/pubs/fips/203/final), or [FIPS205](https://csrc.nist.gov/pubs/fips/203/final),
+- [selected for standardization by NIST](https://csrc.nist.gov/Projects/post-quantum-cryptography/selected-algorithms-2022),
+- part of the [4th round of the NIST PQC standardization process](https://csrc.nist.gov/Projects/post-quantum-cryptography/round-4-submissions),
+- part or the [first round of additional signatures of the NIST PQC standardization process](https://csrc.nist.gov/projects/pqc-dig-sig/round-1-additional-signatures),
+- part of the [second round of the KpqC competition](https://www.kpqc.or.kr/competition.html).
 
 Implementations for previous NIST PQC rounds are available here:
+- Signature Round 1: https://github.com/mupq/pqm4/releases/tag/SignatureRound1
 - Round 3: https://github.com/mupq/pqm4/releases/tag/Round3
 - Round 2: https://github.com/mupq/pqm4/releases/tag/Round2
 - Round 1: https://github.com/mupq/pqm4/releases/tag/Round1
 
 ## Changes in Round 2
-For the second round of the NIST PQC, **pqm4** was extended (see [#78](https://github.com/mupq/pqm4/pull/78)) with the following features:
+For the second round of the NIST PQC process, **pqm4** was extended (see [#78](https://github.com/mupq/pqm4/pull/78)) with the following features:
 - common code was moved to [mupq](https://github.com/mupq/mupq) for reuse in [pqriscv](https://github.com/mupq/pqriscv),
 - much simpler build process,
 - automated profiling of cycles spent in symmetric primitives (SHA-2, SHA-3, AES),
 - reporting of code-size,
 - integration of clean implementations from [PQClean](https://github.com/PQClean/PQClean).
 
+## Changes in Round 3
+For the third round of the NIST PQC process, **pqm4** was extended with the following features:
+- overhaul of the build process to support multiple target boards, and
+- use of the QEMU simulator to measure stack usage of larger schemes.
+
+## Changes in Round 4 / Round 1 of Additional signatures
+For the fourth round of the NIST PQC process **pqm4** was extended with the following features:
+- Switch to the Nucleo-L4R5ZI board as the default board for measurements, and
+- an overhaul of the console output.
+
 ## Schemes included in pqm4
 
 For most of the schemes there are multiple implementations. 
@@ -47,7 +63,10 @@ The naming scheme for these implementations is as follows:
 The testing and benchmarking framework of **pqm4** targets several development
 boards, all featuring an ARM Cortex-M4 chip:
 
-* `stm32f4discovery` (default): The [STM32F4 Discovery board](https://www.st.com/en/evaluation-tools/stm32f4discovery.html)
+* `nucleo-l4r5zi` (default): The [NUCLEO-L4R5ZI board](https://www.st.com/en/evaluation-tools/nucleo-l4r5zi.html)
+  featuring 2MB of Flash and 640KB of RAM. This board does not require a
+  separate USB serial interface converter.
+* `stm32f4discovery`: The [STM32F4 Discovery board](https://www.st.com/en/evaluation-tools/stm32f4discovery.html)
   featuring 1MB of Flash, and 192KB of RAM. Connecting the
   development to the host computer requires a mini-USB cable and a USB-TTL
   converter together with a 2-pin dupont / jumper cable.
@@ -56,9 +75,6 @@ boards, all featuring an ARM Cortex-M4 chip:
   separate USB serial interface converter.
 * `cw308t-stm32f3`: The ChipWhisperer [CW308-STM32F3 target board](https://rtfm.newae.com/Targets/UFO%20Targets/CW308T-STM32F/)
   (in the F3 configuration) featuring 256KB of Flash and 40KB of RAM.
-* `nucleo-l4r5zi`: The [NUCLEO-L4R5ZI board](https://www.st.com/en/evaluation-tools/nucleo-l4r5zi.html)
-  featuring 2MB of Flash and 640KB of RAM. This board does not require a
-  separate USB serial interface converter.
 * `mps2-an386`: The ARM MPS2(+) FPGA prototyping board when used with the
   ARM-Cortex M4 bitstream (see [ARM AN386](https://developer.arm.com/documentation/dai0386/c))
   featuring two 4MB RAM blocks, one used in lieu of Flash one as RAM. This board
@@ -67,7 +83,7 @@ boards, all featuring an ARM Cortex-M4 chip:
 
 ### Installing the ARM toolchain
 The **pqm4** build system assumes that you have the [arm-none-eabi toolchain](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads)
-toolchain installed.
+toolchain installed. All benchmarks are performed using this toolchain.
 On most Linux systems, the correct toolchain gets installed when you install the `arm-none-eabi-gcc` (or `gcc-arm-none-eabi`) package.  
 On some Linux distributions, you will also have to explicitly install `libnewlib-arm-none-eabi` .
 
@@ -78,12 +94,12 @@ refer to the stlink Github page for instructions on how to [compile it from sour
 (in that case, be careful to use libusb-1.0.0-dev, not libusb-0.1).
 
 ### Installing OpenOCD
-For the `nucleo-l4r5zi` board [OpenOCD](http://openocd.org) (tested with version 0.11) is used for flashing binaries.
+For the `nucleo-l4r5zi` board [OpenOCD](http://openocd.org) (tested with version 0.12) is used for flashing binaries.
 Depending on your operating system, OpenOCD may be available in your package manager -- if not, please
 refer to the OpenOCD README for instructions on how to [compile it from source](http://openocd.org/doc-release/README).
 
 ### Python3
-The benchmarking scripts used in **pqm4** require Python >= 3.6.
+The benchmarking scripts used in **pqm4** require Python >= 3.8.
 
 ### Installing pyserial
 The host-side Python code for most platforms requires the [pyserial](https://github.com/pyserial/pyserial) module.
@@ -151,22 +167,22 @@ int crypto_sign_open(unsigned char *m, size_t *mlen,
 
 
 ## Running tests and benchmarks
-The build system compiles six binaries for each implemenation which can be used to test and benchmark the schemes. For example, for the reference implementation of [Kyber768](https://pq-crystals.org/kyber/) the following binaries are assembled: 
- - `bin/crypto_kem_kyber768_m4_test.bin` tests if the scheme works as expected. For KEMs this tests if Alice and Bob derive the same shared key and for signature schemes it tests if a generated signature can be verified correctly. Several failure cases are also checked, see [mupq/crypto_kem/test.c](https://github.com/mupq/mupq/blob/master/crypto_kem/test.c) and [mupq/crypto_sign/test.c](https://github.com/mupq/mupq/blob/master/crypto_sign/test.c) for details.
- - `bin/crypto_kem_kyber768_m4_speed.bin` measures the runtime of `crypto_kem_keypair`, `crypto_kem_enc`, and `crypto_kem_dec` for KEMs and `crypto_sign_keypair`, `crypto_sign`, and `crypto_sign_open` for signatures. See [mupq/crypto_kem/speed.c](https://github.com/mupq/mupq/blob/master/crypto_kem/speed.c) and [mupq/crypto_sign/speed.c](https://github.com/mupq/mupq/blob/master/crypto_sign/speed.c).
- - `bin/crypto_kem_kyber768_m4_hashing.bin` measures the cycles spent in SHA-2, SHA-3, and AES of `crypto_kem_keypair`, `crypto_kem_enc`, and `crypto_kem_dec` for KEMs and `crypto_sign_keypair`, `crypto_sign`, and `crypto_sign_open` for signatures. See [mupq/crypto_kem/hashing.c](https://github.com/mupq/mupq/blob/master/crypto_kem/speed.c) and [mupq/crypto_sign/speed.c](https://github.com/mupq/mupq/blob/master/crypto_sign/speed.c).
- - `bin/crypto_kem_kyber768_m4_stack.bin` measures the stack consumption of each of the procedures involved. The memory allocated outside of the procedures (e.g., public keys, private keys, ciphertexts, signatures) is not included. See [mupq/crypto_kem/stack.c](https://github.com/mupq/mupq/blob/master/crypto_kem/stack.c) and [mupq/crypto_sign/stack.c](https://github.com/mupq/mupq/blob/master/crypto_sign/stack.c).
- - `bin/crypto_kem_kyber768_m4_testvectors.bin` uses a deterministic random number generator to generate testvectors for the implementation. These can be used to cross-check different implemenatations of the same scheme. See [mupq/crypto_kem/testvectors.c](https://github.com/mupq/mupq/blob/master/crypto_kem/testvectors.c) and [mupq/crypto_sign/testvectors.c](https://github.com/mupq/mupq/blob/master/crypto_sign/testvectors.c).
-- `bin-host/crypto_kem_kyber768_m4_testvectors` uses the same deterministic random number generator to create the testvectors on your host. See [mupq/crypto_kem/testvectors-host.c](https://github.com/mupq/mupq/blob/master/crypto_kem/testvectors-host.c) and [mupq/crypto_sign/testvectors-host.c](https://github.com/mupq/mupq/blob/master/crypto_sign/testvectors-host.c).
+The build system compiles six binaries for each implemenation which can be used to test and benchmark the schemes. For example, for the reference implementation of [ML-KEM-768](https://pq-crystals.org/kyber/) the following binaries are assembled: 
+ - `bin/crypto_kem_ml-kem-768_m4_test.bin` tests if the scheme works as expected. For KEMs this tests if Alice and Bob derive the same shared key and for signature schemes it tests if a generated signature can be verified correctly. Several failure cases are also checked, see [mupq/crypto_kem/test.c](https://github.com/mupq/mupq/blob/master/crypto_kem/test.c) and [mupq/crypto_sign/test.c](https://github.com/mupq/mupq/blob/master/crypto_sign/test.c) for details.
+ - `bin/crypto_kem_ml-kem-768_m4_speed.bin` measures the runtime of `crypto_kem_keypair`, `crypto_kem_enc`, and `crypto_kem_dec` for KEMs and `crypto_sign_keypair`, `crypto_sign`, and `crypto_sign_open` for signatures. See [mupq/crypto_kem/speed.c](https://github.com/mupq/mupq/blob/master/crypto_kem/speed.c) and [mupq/crypto_sign/speed.c](https://github.com/mupq/mupq/blob/master/crypto_sign/speed.c).
+ - `bin/crypto_kem_ml-kem-768_m4_hashing.bin` measures the cycles spent in SHA-2, SHA-3, and AES of `crypto_kem_keypair`, `crypto_kem_enc`, and `crypto_kem_dec` for KEMs and `crypto_sign_keypair`, `crypto_sign`, and `crypto_sign_open` for signatures. See [mupq/crypto_kem/hashing.c](https://github.com/mupq/mupq/blob/master/crypto_kem/speed.c) and [mupq/crypto_sign/speed.c](https://github.com/mupq/mupq/blob/master/crypto_sign/speed.c).
+ - `bin/crypto_kem_ml-kem-768_m4_stack.bin` measures the stack consumption of each of the procedures involved. The memory allocated outside of the procedures (e.g., public keys, private keys, ciphertexts, signatures) is not included. See [mupq/crypto_kem/stack.c](https://github.com/mupq/mupq/blob/master/crypto_kem/stack.c) and [mupq/crypto_sign/stack.c](https://github.com/mupq/mupq/blob/master/crypto_sign/stack.c).
+ - `bin/crypto_kem_ml-kem-768_m4_testvectors.bin` uses a deterministic random number generator to generate testvectors for the implementation. These can be used to cross-check different implemenatations of the same scheme. See [mupq/crypto_kem/testvectors.c](https://github.com/mupq/mupq/blob/master/crypto_kem/testvectors.c) and [mupq/crypto_sign/testvectors.c](https://github.com/mupq/mupq/blob/master/crypto_sign/testvectors.c).
+- `bin-host/crypto_kem_ml-kem-768_m4_testvectors` uses the same deterministic random number generator to create the testvectors on your host. See [mupq/crypto_kem/testvectors-host.c](https://github.com/mupq/mupq/blob/master/crypto_kem/testvectors-host.c) and [mupq/crypto_sign/testvectors-host.c](https://github.com/mupq/mupq/blob/master/crypto_sign/testvectors-host.c).
 - An `elf` file for each binary is generated in the `elf/` folder if desired.
 
 The `elf` files or binaries can be flashed to your board using an appropriate
-tool. For example, the `stm32f4discovery` platform uses `st-flash`, e.g., `st-flash write bin/crypto_kem_kyber768_m4_test.bin 0x8000000`. To receive the output, run `python3 hostside/host_unidirectional.py`. 
+tool. For example, the `stm32f4discovery` platform uses `st-flash`, e.g., `st-flash write bin/crypto_kem_ml-kem-768_m4_test.bin 0x8000000`. To receive the output, run `python3 hostside/host_unidirectional.py`. 
 
 If you target the `mps2-an386` platform, you can also run the `elf` file using
 the QEMU ARM emulator:
 ```
-qemu-system-arm -M mps2-an386 -nographic -semihosting -kernel elf/crypto_kem_kyber512_m4_test.elf
+qemu-system-arm -M mps2-an386 -nographic -semihosting -kernel elf/crypto_kem_ml-kem-512_m4_test.elf
 ```
 The emulator should exit automatically when the test / benchmark completes. If
 you run into an error, you can exit QEMU pressing CTRL+A and then X.
@@ -185,7 +201,7 @@ The scripts take a number of command line arguments, which you'll need to adapt:
 If you change any of these values, you'll need to run `make clean` (the build
 system will remind you).
 
-In case you don't want to include all schemes, pass a list of schemes you want to include to any of the scripts, e.g., `python3 test.py kyber768 sphincs-shake256-128f-simple`. 
+In case you don't want to include all schemes, pass a list of schemes you want to include to any of the scripts, e.g., `python3 test.py ml-kem-768 sphincs-shake256-128f-simple`. 
 In case you want to exclude certain schemes pass `--exclude`, e.g., `python3 test.py --exclude saber`.
 
 The benchmark results (in `benchmarks/`) created by 
@@ -394,5 +410,6 @@ Each subdirectory containing implementations contains a LICENSE or COPYING file
 under what license that specific implementation is released. 
 The files in common contain licensing information at the top of the file (and 
 are currently either public domain or MIT). 
-All other code in this repository is released under the conditions of [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
+
+All other code in this repository is dual-licensed under [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) and under the conditions of [CC0](https://creativecommons.org/publicdomain/zero/1.0/).