Merge pull request #437 from pq-code-package/update-docs

Update documentation in preparation of the alpha release
pq-code-package · Dec 3, 2024 · 112dbd3 · 112dbd3 · oqs-bot · Dec 3, 2024
2 parents b5f9627 + 61d5e18
commit 112dbd3
Show file tree

Hide file tree

Showing 16 changed files with 243 additions and 165 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,38 +1,33 @@
 ---
 name: Bug report
 about: Create a report to help us improve
-title: ''
 labels: bug
-assignees: ''
-
 ---
 
+
+<!-- 
+
+Security reports
+
+DO NOT report security issues through Github issues - instead use Github's [private vulnerability reporting](https://github.com/pq-code-package/mlkem-native/security). 
+-->
+
+
 **Describe the bug**
 A clear and concise description of what the bug is.
 
-**To Reproduce**
-Steps to reproduce the behavior:
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
+**Platform**: e.g., x86_64 Linux
 
-**Expected behavior**
-A clear and concise description of what you expected to happen.
+**Compiler**: e.g., gcc 13.2.0 (installed through nix)
 
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
+**How to reproduce**
+Steps to reproduce the behavior:
+```
 
-**Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
+```
 
-**Smartphone (please complete the following information):**
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser [e.g. stock browser, safari]
- - Version [e.g. 22]
+**Expected behavior**
+A clear and concise description of what you expected to happen.
 
 **Additional context**
 Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -1,20 +1,31 @@
 ---
 name: Feature request
 about: Suggest an idea for this project
-title: ''
 labels: enhancement
-assignees: ''
-
 ---
 
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+**Platform**: 
+Which platform does this concern?
+- [ ] platform independent
+- [ ] aarch64
+- [ ] x86_64
+- [ ] rv64
+- [ ] other
+
+**Issue category**:
+
+Which part(s) of mlkem-native does this issue concern:
+
+- [ ] core crypto: ML-KEM
+- [ ] core crypto: FIPS202
+- [ ] documentation
+- [ ] integration
+- [ ] CBMC
+- [ ] CI
+- [ ] Testing
 
 **Describe the solution you'd like**
 A clear and concise description of what you want to happen.
 
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
-
 **Additional context**
 Add any other context or screenshots about the feature request here.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,8 +1,21 @@
-[//]: # (SPDX-License-Identifier: CC-BY-4.0)
-<!-- Please give a brief explanation of the purpose of this pull request. -->
+<!-- 
+Security reports
 
-<!-- Does this PR resolve any issue?  If so, please reference it using automatic-closing keywords like "Fixes #123." -->
+DO NOT submit pull requests related to security issues directly - instead use Github's [private vulnerability reporting](https://github.com/pq-code-package/mlkem-native/security). 
+-->
 
-<!-- Any PR adding a new feature is expected to contain a test; the test should be part of CI testing, preferably within the ".github/workflows" directory tree. Please add an explanation to the PR if/when (why) this cannot be done. -->
+**Summary**:
+Provide a brief summary of your changes.
 
-<!-- Once your pull request is ready for review and passing continuous integration tests, please convert from a draft PR to a normal PR, and request a review. -->
+**Steps**:
+If your pull request consists of multiple sequential changes, please describe them here:
+
+**Performed local tests**:
+ - [ ] `lint` passing
+ - [ ] `tests all` passing
+ - [ ] `tests bench` passing
+ - [ ] `tests cbmc` passing
+
+**Do you expect this change to impact performance**: Yes/No
+
+If yes, please provide local benchmarking results.
diff --git a/.github/settings.yml b/.github/settings.yml
diff --git a/BUILDING.md b/BUILDING.md
@@ -0,0 +1,66 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+# Building mlkem-native
+
+### Prerequisites
+
+To build **mlkem-native**, you need `make` and a C90 compiler. To use the test scripts, you need Python3 with
+dependencies as specified in [requirements.txt](requirements.txt). We recommend using a virtual environment, e.g.:
+
+```bash
+python3 -m venv venv
+./venv/bin/python3 -m pip install -r requirements.txt
+source venv/bin/activate
+```
+
+### Using `make`
+
+You can build and test **mlkem-native** as follows:
+
+```bash
+make quickcheck       # With native code backend (if available)
+make OPT=0 quickcheck # With C backend
+```
+
+To merely build test and benchmarking components, use the following `make` targets:
+
+```bash
+make mlkem
+make bench
+make bench_components
+make nistkat
+make kat
+```
+
+The resulting binaries can then be found in [test/build](test/build).
+
+### Using `tests` script
+
+We recommend compiling and running tests and benchmarks using the [`./scripts/tests`](scripts/tests) script. For
+example,
+
+```bash
+./scripts/tests func
+```
+
+will compile and run functionality tests. For detailed information on how to use the script, please refer to the
+`--help` option.
+
+### Nix setup
+
+All the development and build dependencies are also specified in [flake.nix](flake.nix). We recommend installing them
+using
+[nix](https://nixos.org/download/). To execute a bash shell with the development environment specified in
+[flake.nix](flake.nix), run
+```bash
+nix develop --experimental-features 'nix-command flakes'
+```
+
+### Windows
+
+You can also build **mlkem-native** on Windows using `nmake` and an MSVC compiler.
+
+To build and run the tests (only support functional testing for non-opt implementation for now), use the following `nmake` targets:
+```powershell
+nmke /f .\Makefile.Microsoft_nmake quickcheck
+```
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -1,4 +1,4 @@
 # SPDX-License-Identifier: Apache-2.0
 # Last matching pattern has precedence
 
-* @pq-code-package/pqcp-embedded-maintainers-aarch64
+* @pq-code-package/pqcp-native-maintainers
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,6 +1,19 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
-[//]: # (TODO Add contributing guide)
 
 # Contributing
 
-to be completed
+We welcome proposals to improve **mlkem-native**.
+In particular, we are interested to hear how you plan to use **mlkem-native** or what should be improved about **mlkem-native** allowing other projects to rely on it.
+If you have specific feature requests, please open an issue. 
+
+You can contact the **mlkem-native** team through the [PQCA Discord](https://discord.com/invite/xyVnwzfg5R).
+
+## Call for contributors
+
+We are actively seeking contributors who can help us build **mlkem-native**. If you are interested, please contact us,
+or volunteer for any of the open issues.
+
+## Call for potential consumers
+
+If you are a potential consumer of **mlkem-native**, please reach out: We're interested in hearing the way you want to
+use **mlkem-native**. If you have specific feature requests, please open an issue.
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
Benchmark suite	Current: `112dbd3`	Previous: `b5f9627`	Ratio
`ML-KEM-512 keypair`	`29175` cycles	`29175` cycles	`1`
`ML-KEM-512 encaps`	`35851` cycles	`35852` cycles	`1.00`
`ML-KEM-512 decaps`	`46654` cycles	`46655` cycles	`1.00`
`ML-KEM-768 keypair`	`49175` cycles	`49173` cycles	`1.00`
`ML-KEM-768 encaps`	`55842` cycles	`55842` cycles	`1`
`ML-KEM-768 decaps`	`71008` cycles	`71009` cycles	`1.00`
`ML-KEM-1024 keypair`	`72213` cycles	`72211` cycles	`1.00`
`ML-KEM-1024 encaps`	`81522` cycles	`81518` cycles	`1.00`
`ML-KEM-1024 decaps`	`102032` cycles	`102031` cycles	`1.00`
Benchmark suite	Current: `112dbd3`	Previous: `b5f9627`	Ratio
`ML-KEM-512 keypair`	`13826` cycles	`13867` cycles	`1.00`
`ML-KEM-512 encaps`	`18206` cycles	`18209` cycles	`1.00`
`ML-KEM-512 decaps`	`24136` cycles	`24114` cycles	`1.00`
`ML-KEM-768 keypair`	`22449` cycles	`22529` cycles	`1.00`
`ML-KEM-768 encaps`	`24530` cycles	`24606` cycles	`1.00`
`ML-KEM-768 decaps`	`32562` cycles	`32992` cycles	`0.99`
`ML-KEM-1024 keypair`	`32068` cycles	`32044` cycles	`1.00`
`ML-KEM-1024 encaps`	`35768` cycles	`35669` cycles	`1.00`
`ML-KEM-1024 decaps`	`47196` cycles	`47172` cycles	`1.00`
Benchmark suite	Current: `112dbd3`	Previous: `b5f9627`	Ratio
`ML-KEM-512 keypair`	`18105` cycles	`18125` cycles	`1.00`
`ML-KEM-512 encaps`	`23049` cycles	`23108` cycles	`1.00`
`ML-KEM-512 decaps`	`30365` cycles	`30437` cycles	`1.00`
`ML-KEM-768 keypair`	`31040` cycles	`31062` cycles	`1.00`
`ML-KEM-768 encaps`	`33992` cycles	`33988` cycles	`1.00`
`ML-KEM-768 decaps`	`44795` cycles	`44793` cycles	`1.00`
`ML-KEM-1024 keypair`	`44475` cycles	`44464` cycles	`1.00`
`ML-KEM-1024 encaps`	`49934` cycles	`49925` cycles	`1.00`
`ML-KEM-1024 decaps`	`64410` cycles	`64360` cycles	`1.00`
Benchmark suite	Current: `112dbd3`	Previous: `b5f9627`	Ratio
`ML-KEM-512 keypair`	`20333` cycles	`20406` cycles	`1.00`
`ML-KEM-512 encaps`	`27122` cycles	`27162` cycles	`1.00`
`ML-KEM-512 decaps`	`36246` cycles	`36252` cycles	`1.00`
`ML-KEM-768 keypair`	`34874` cycles	`34879` cycles	`1.00`
`ML-KEM-768 encaps`	`38228` cycles	`38211` cycles	`1.00`
`ML-KEM-768 decaps`	`51442` cycles	`51431` cycles	`1.00`
`ML-KEM-1024 keypair`	`48095` cycles	`47922` cycles	`1.00`
`ML-KEM-1024 encaps`	`54307` cycles	`54120` cycles	`1.00`
`ML-KEM-1024 decaps`	`72272` cycles	`72069` cycles	`1.00`
Benchmark suite	Current: `112dbd3`	Previous: `b5f9627`	Ratio
`ML-KEM-512 keypair`	`36274` cycles	`36267` cycles	`1.00`
`ML-KEM-512 encaps`	`46425` cycles	`46461` cycles	`1.00`
`ML-KEM-512 decaps`	`61794` cycles	`61881` cycles	`1.00`
`ML-KEM-768 keypair`	`59022` cycles	`58961` cycles	`1.00`
`ML-KEM-768 encaps`	`73136` cycles	`73061` cycles	`1.00`
`ML-KEM-768 decaps`	`91674` cycles	`91662` cycles	`1.00`
`ML-KEM-1024 keypair`	`88422` cycles	`88471` cycles	`1.00`
`ML-KEM-1024 encaps`	`109490` cycles	`109327` cycles	`1.00`
`ML-KEM-1024 decaps`	`133800` cycles	`133709` cycles	`1.00`
Benchmark suite	Current: `112dbd3`	Previous: `b5f9627`	Ratio
`ML-KEM-512 keypair`	`52283` cycles	`52311` cycles	`1.00`
`ML-KEM-512 encaps`	`67755` cycles	`67788` cycles	`1.00`
`ML-KEM-512 decaps`	`92689` cycles	`92638` cycles	`1.00`
`ML-KEM-768 keypair`	`84632` cycles	`84658` cycles	`1.00`
`ML-KEM-768 encaps`	`104807` cycles	`104851` cycles	`1.00`
`ML-KEM-768 decaps`	`137726` cycles	`137784` cycles	`1.00`
`ML-KEM-1024 keypair`	`125447` cycles	`125478` cycles	`1.00`
`ML-KEM-1024 encaps`	`149691` cycles	`150020` cycles	`1.00`
`ML-KEM-1024 decaps`	`192820` cycles	`192389` cycles	`1.00`
Benchmark suite	Current: `112dbd3`	Previous: `b5f9627`	Ratio
`ML-KEM-512 keypair`	`56794` cycles	`56697` cycles	`1.00`
`ML-KEM-512 encaps`	`71874` cycles	`71820` cycles	`1.00`
`ML-KEM-512 decaps`	`96458` cycles	`96361` cycles	`1.00`
`ML-KEM-768 keypair`	`91852` cycles	`91823` cycles	`1.00`
`ML-KEM-768 encaps`	`111509` cycles	`111402` cycles	`1.00`
`ML-KEM-768 decaps`	`144573` cycles	`144449` cycles	`1.00`
`ML-KEM-1024 keypair`	`134776` cycles	`134612` cycles	`1.00`
`ML-KEM-1024 encaps`	`160403` cycles	`160084` cycles	`1.00`
`ML-KEM-1024 decaps`	`201536` cycles	`201685` cycles	`1.00`
Benchmark suite	Current: `112dbd3`	Previous: `b5f9627`	Ratio
`ML-KEM-512 keypair`	`29225` cycles	`29176` cycles	`1.00`
`ML-KEM-512 encaps`	`35945` cycles	`35859` cycles	`1.00`
`ML-KEM-512 decaps`	`46769` cycles	`46664` cycles	`1.00`
`ML-KEM-768 keypair`	`49356` cycles	`49198` cycles	`1.00`
`ML-KEM-768 encaps`	`56083` cycles	`55870` cycles	`1.00`
`ML-KEM-768 decaps`	`71255` cycles	`70985` cycles	`1.00`
`ML-KEM-1024 keypair`	`72196` cycles	`72174` cycles	`1.00`
`ML-KEM-1024 encaps`	`81636` cycles	`81621` cycles	`1.00`
`ML-KEM-1024 decaps`	`102095` cycles	`102067` cycles	`1.00`
Benchmark suite	Current: `112dbd3`	Previous: `b5f9627`	Ratio
`ML-KEM-512 keypair`	`15095` cycles	`15094` cycles	`1.00`
`ML-KEM-512 encaps`	`19759` cycles	`19754` cycles	`1.00`
`ML-KEM-512 decaps`	`26399` cycles	`26388` cycles	`1.00`
`ML-KEM-768 keypair`	`25602` cycles	`25558` cycles	`1.00`
`ML-KEM-768 encaps`	`28206` cycles	`28162` cycles	`1.00`
`ML-KEM-768 decaps`	`38237` cycles	`37988` cycles	`1.01`
`ML-KEM-1024 keypair`	`34906` cycles	`35553` cycles	`0.98`
`ML-KEM-1024 encaps`	`39691` cycles	`40680` cycles	`0.98`
`ML-KEM-1024 decaps`	`53117` cycles	`54473` cycles	`0.98`
Benchmark suite	Current: `112dbd3`	Previous: `b5f9627`	Ratio
`ML-KEM-512 keypair`	`19030` cycles	`19031` cycles	`1.00`
`ML-KEM-512 encaps`	`23843` cycles	`23843` cycles	`1`
`ML-KEM-512 decaps`	`31229` cycles	`31230` cycles	`1.00`
`ML-KEM-768 keypair`	`32329` cycles	`32332` cycles	`1.00`
`ML-KEM-768 encaps`	`36085` cycles	`36086` cycles	`1.00`
`ML-KEM-768 decaps`	`46487` cycles	`46491` cycles	`1.00`
`ML-KEM-1024 keypair`	`46970` cycles	`46964` cycles	`1.00`
`ML-KEM-1024 encaps`	`53087` cycles	`53086` cycles	`1.00`
`ML-KEM-1024 decaps`	`67406` cycles	`67401` cycles	`1.00`