Merge pull request #6 from planetf1/initial

planetf1 · web-flow · commit 8bcb4b28d6e9 · 2024-05-09T11:12:49.000+01:00
diff --git a/README.md b/README.md
@@ -1,59 +1,38 @@
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
-# Welcome to the documentation template
+# Welcome to the documentation
 
-This repository serves as a template for creating documentation for projects. The template utilizes MkDocs (documentation at [mkdocs.org](https://www.mkdocs.org)) and the theme Material for MkDocs (documentation at [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)). Material adds a number of extra features to MkDocs, and repositories can take advantage of the theme's [Insiders](https://squidfunk.github.io/mkdocs-material/insiders/) capabilities.
-
-[Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/
-[Mike]: https://github.com/jimporter/mike
+This repository manages the documentation for the pq-code-package project.
 
 ## Prerequisites
 
-To test the documents and update the published site, the following tools are needed:
-
-- A Bash shell
-- git
-- Python 3
-- The [Material for Mkdocs] theme.
-- The [Mike] MkDocs plugin for publishing versions to gh-pages.
-  - Not used locally, but referenced in the `mkdocs.yml` file and needed for
-    deploying the site to gh-pages.
-
-### git
-`git` can be installed locally, as described in the [Install Git Guide from GitHub](https://github.com/git-guides/install-git).
-
-### Python 3
-`Python 3` can be installed locally, as described in the [Python Getting Started guide](https://www.python.org/about/gettingstarted/).
-
-### Mkdocs
+- [Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/
+- [Mike]: https://github.com/jimporter/mike
 
-The Mkdocs-related items can be installed locally, as described in the [Material
-for Mkdocs] installation instructions. The short, case-specific version of those
-instructions follow:
-
-```bash
+You can install these requirements via:
+```
 pip install -r requirements.txt
 ```
 
-### Verify Setup
+## Adding Content
 
-To verify your setup, check that you can run `mkdocs` by running the command `mkdocs --help` to see the help text.
+The basic process for adding content to the site is:
 
-## Useful MkDocs Commands
+- Create a new markdown file under the `docs` folder
+- Add the new file to the table of contents (`nav` section in the `mkdocs.yml` file)
 
-The commands you will usually use with `mkdocs` are:
+## Local testing
 
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
+Build the pages locally for testing using
+```
+mkdocs serve
+```
 
-## Adding Content
+## CI/Code
 
-The basic process for adding content to the site is:
+Github actions are used to build and publish the site to https://documentation.pqcodepackage.org
 
-- Create a new markdown file under the `docs` folder
-- Add the new file to the table of contents (`nav` section in the `mkdocs.yml` file)
+**NOTE** At this time there is NO PR verification, so please test locally to avoid a broken site.
 
-If you are using this as a template for creating your own documentation, please see [the instructions for customization](./docs/index.md).
 
 ## Repository layout
 
diff --git a/docs/contributing/asking-a-question.md b/docs/contributing/asking-a-question.md
@@ -11,8 +11,21 @@
 ## Chat
 [PQCA's Discord server](https://discord.com/invite/xyVnwzfg5R) is the place to go for real-time chat about everything from quick help to involved discussions.
 
-For general pq-code-package discussions, join the Discord server and visit #pqca-code-package.
+For general pq-code-package discussions, join the Discord server and visit the channels in the **PQ Code Package** section, for example:
+
+- pqcp-general : general discussions
+- pqcp-tsc : Technical steering committee
+
+Other channels will be added as individual projects opt to use discord to continue async discussions.
+
+## Github discussions
+
+[Discussions on pq-code-package](https://github.com/orgs/pq-code-package/discussions) can also be used for discussions that aren't appropriate to track in issues
 
 ## Mailing Lists
 The pq-code-package mailing lists are hosted by the pqca Foundation: https://pqca.org . 
 
+Currently there is one specific mailing list **pq-code-package-tsc** .
+
+If the lists are used extensively, additional lists can be added,
+
diff --git a/docs/contributing/charter.md b/docs/contributing/charter.md
diff --git a/docs/contributing/code-of-conduct.md b/docs/contributing/code-of-conduct.md
diff --git a/docs/contributing/reporting-a-bug.md b/docs/contributing/reporting-a-bug.md
@@ -1,12 +1,15 @@
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 # Reporting a Bug
 
-To report a bug, submit an issue in our public issue trackers on Github.
+To report a bug, submit an issue via github, directly against the appropriate [repository](repositories.md
+
+If the issue is security related, please follow the steps in [reporting a security issue](../security/reporting-a-security-issue.md) instead.
 
 When reporting an issue, please provide as much detail as possible about how to reproduce it. If possible, explain how to reproduce the issue. Details are very helpful. Please include the following information:
 
-* Operating system and version (if Mac, include the processor)
-* Project version
+* Operating system and version
+* Architecture (ie amd64, arm64 etc)
+* Code version
 * Environment details (virtual, physical, etc.)
 * Steps to reproduce the issue
 * Actual results
diff --git a/docs/contributing/reporting-a-security-issue.md b/docs/contributing/reporting-a-security-issue.md
diff --git a/docs/contributing/repositories.md b/docs/contributing/repositories.md
@@ -0,0 +1,15 @@
+| Repository | tags | Purpose |
+| --- | --- | --- |
+| [`.github` :material-github:](https://github.com/pq-code-package/.github){ target=gh } | None | PQCP GitHub organization profile |
+| [`documentation` :material-github:](https://github.com/pq-code-package/documentation){ target=gh } | [OrderedDict({'name': 'documentation'}), OrderedDict({'name': 'website'})] | Project documentation built using mkdocs |
+| [`mlkem-c-aarch64` :material-github:](https://github.com/pq-code-package/mlkem-c-aarch64){ target=gh } | None | ML-KEM implementation optimized for aarch64 |
+| [`mlkem-c-embedded` :material-github:](https://github.com/pq-code-package/mlkem-c-embedded){ target=gh } | None | MLKEM implementation optimized for embedded microcontrollers |
+| [`mlkem-c-generic` :material-github:](https://github.com/pq-code-package/mlkem-c-generic){ target=gh } | None | ML-KEM generic implementation in C from PQclean |
+| [`mlkem-libjade` :material-github:](https://github.com/pq-code-package/mlkem-libjade){ target=gh } | None | ML-KEM implementation in libjade with high assurance |
+| [`mlkem-rust-libcrux` :material-github:](https://github.com/pq-code-package/mlkem-rust-libcrux){ target=gh } | None | portable ML-KEM implementation with some optimizations for AVX2. Full AVX2 support will be added over the coming months. The code is formally verified for panic freedom, correctness, and secret independence in F* using the hax toolchain. |
+| [`pq-code-package-hackathon` :material-github:](https://github.com/pq-code-package/pq-code-package-hackathon){ target=gh } | [OrderedDict({'name': 'documentation'}), OrderedDict({'name': 'hackathon'}), OrderedDict({'name': 'website'})] | Hackathon planning and documentation |
+| [`template-code` :material-github:](https://github.com/pq-code-package/template-code){ target=gh } | None | Template for creating code repositories, with basic file setup included |
+| [`tsc` :material-github:](https://github.com/pq-code-package/tsc){ target=gh } | None | PQ Code Project Technical Steering Committee resources |
+
+
+**NOTE**: The above segment is created by the `scripts/catalog_repo.pl` script. 
diff --git a/docs/contributing/tsc.md b/docs/contributing/tsc.md
diff --git a/docs/faqs.md b/docs/faqs.md
@@ -1,23 +1,11 @@
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
-# Frequently Asked Questions
-
-## Topic 1
-
-### Question 1 for Topic 1
 
-Answer
-
-### Question 2 for Topic 1
-
-Answer
+# Frequently Asked Questions
 
-## Topic 2
 
-### Question 1 for Topic 2
 
-Answer
+## What is this section of the documentation for?
 
-### Question 2 for Topic 2
+This area will contain common FAQs in future
 
-Answer
 
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -1,8 +1,7 @@
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
-**term**
 
-: definition
+**glossary**
+
+: A list of definitions of terms used in this documentation.
 
-**term**
 
-: definition
diff --git a/docs/governance/charter.md b/docs/governance/charter.md
@@ -0,0 +1,5 @@
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+The charter under which pq-code-package is managed can be found in the TSC repository 
+
+* Read [pq-code-package charter](https://pq-code-package.github.io/tsc/charter/charter-2024-01-29.pdf)
diff --git a/docs/governance/code-of-conduct.md b/docs/governance/code-of-conduct.md
@@ -0,0 +1,7 @@
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+Whilst the community is organizing, we haven't yet formally adopted a specific code of conduct.
+
+The working assumption is that we follow the standard Linux Foundation code of conduct
+
+* [Linux Foundation COC](https://docs.linuxfoundation.org/lfx/mentorship/mentor-guide/code-of-conduct)
diff --git a/docs/governance/dco.md b/docs/governance/dco.md
@@ -0,0 +1,3 @@
+The DCO is a per-commit sign-off made by a contributor stating that they agree to the terms published at https://developercertificate.org/ for that particular contribution.
+
+* [Read more](https://wiki.linuxfoundation.org/dco)
diff --git a/docs/governance/tsc.md b/docs/governance/tsc.md
@@ -0,0 +1,30 @@
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+The Technical Steering Committee (TSC) is the leadership of the 
+pq-code-package project. It's role is to:
+
+- Set the overall strategy of the project ie across all our algorithm 
+implementations & supporting subprojects
+- Liase with the PQCA TAC providing feedback and raising issues and concerns
+- resolve any issues within the project community
+
+## Members
+
+The initial TSC was created based on the intial contributors during the project inception. 
+
+Subsequent members may be voted onto the TSC, the process for doing so will be clarified at a later stage.
+
+## Meetings
+
+Meetings are open to everyone, but only TSC members may vote. 
+
+Minutes and recordings will generally be made available. If you are concerned about recording or minutes this may be noted, and recording/minuting then suspended for the appropriate discussion.
+
+* [Link to agenda and minutes](https://github.com/pq-code-package/tsc/blob/main/meetings/index.md)
+
+* [PQCA calendar](https://pqca.org/calendar/) incorporates all scheduled TSC meetings
+  - note that times are currently displayed in US Central time
+
+## Issue Tracking
+
+The [tsc](https://github.com/pq-code-package/tsc/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) is used to track discussions and actions at the TSC.
diff --git a/docs/implementations/index.md b/docs/implementations/index.md
@@ -1 +1,16 @@
-<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+The PQ Code Package offers a variety of different implementations of ML-KEM.
+
+These vary in certain characteristics in terms of:
+
+* Code Audits
+* Formal verification
+* Platform specific optimizations (memory, cpu, ...)
+* Implementation Language
+
+Additionally as sub-projects onboard to pq-code-package they will go through a variety of stages before being ready to use 
+
+More guidance about how to choose an implementation will be added in future. 
+
+For now go to the [list of repositories](../contributing/repositories.md) & view the other pages in this section
diff --git a/docs/implementations/mlkem-c-aarch64.md b/docs/implementations/mlkem-c-aarch64.md
@@ -1 +1,4 @@
-<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+ML-KEM implementation optimized for aarch64
+
+??? not-started "NO implementation code as of 2024-05-09"
diff --git a/docs/implementations/mlkem-c-embedded.md b/docs/implementations/mlkem-c-embedded.md
@@ -1 +1,4 @@
-<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+MLKEM-C-EMBEDDED is a collection of MLKEM implementations optimized for embedded microcontrollers.
+
+* [Detailed information](https://github.com/pq-code-package/mlkem-c-embedded#)
diff --git a/docs/implementations/mlkem-c-generic.md b/docs/implementations/mlkem-c-generic.md
@@ -1 +1,5 @@
-<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+ML-KEM generic implementation in C from PQclean
+
+??? not-started "NO implementation code as of 2024-05-09"
diff --git a/docs/implementations/mlkem-libjade.md b/docs/implementations/mlkem-libjade.md
@@ -1 +1,4 @@
-<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+The code provided in this repository comes from the libjade cryptographic library. See https://formosa-crypto.org for more information.
+
+??? not-started "NO implementation code as of 2024-05-09"
diff --git a/docs/implementations/mlkem-rust-libcrux.md b/docs/implementations/mlkem-rust-libcrux.md
@@ -1 +1,4 @@
-<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+portable ML-KEM implementation with some optimizations for AVX2. Full AVX2 support will be added over the coming months. The code is formally verified for panic freedom, correctness, and secret independence in F* using the hax toolchain.
+
+??? not-started "NO implementation code as of 2024-05-09"
diff --git a/docs/index.md b/docs/index.md
@@ -3,6 +3,5 @@
 
 Welcome to the pq-code-package documentation.
 
-In this version, only the **Contributing** section has been
-customized.
+Please select one of the section using the nav-bar at the top, or top-left.
 
diff --git a/docs/overview/choosing-implementation.md b/docs/overview/choosing-implementation.md
@@ -1,7 +1,17 @@
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 # Choosing an ML-KEM implementation
 
-The implementations in this repository vary in terms of:
-- Implementation Language
-- Auditing
-- Formal Verification
+The PQ Code Package offers a variety of different implementations of ML-KEM.
+
+These vary in certain characteristics in terms of:
+
+* Code Audits
+* Formal verification
+* Platform specific optimizations (memory, cpu, ...)
+* Implementation Language
+
+Additionally as sub-projects onboard to pq-code-package they will go through a variety of stages before being ready to use 
+
+More guidance about how to choose an implementation will be added in future. 
+
+For now go to the [list of repositories](../contributing/repositories.md) & view the other pages in this section
diff --git a/docs/overview/mlkem.md b/docs/overview/mlkem.md
@@ -1 +1,12 @@
-<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+ML-KEM is an **M** odule **L** attice implementation of a **K** ey **E** xchange **M** echanism as
+specified in [FIPS 203 (draft)](https://csrc.nist.gov/pubs/fips/203/ipd). 
+
+This standard also specifies three parameter sets:
+
+- ML-KEM-512
+- ML-KEM-768
+- ML-KEM-1024
+
+ML-KEM is based on the original CRYSTALS-Kyber KEM and is IND-CCA2 secure. 
diff --git a/docs/overview/pqca.md b/docs/overview/pqca.md
@@ -1 +1,6 @@
-<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+_The alliance seeks to address cryptographic security challenges posed by quantum computing by producing high-assurance software implementations of standardized algorithms and supporting the continued development and standardization of new post-quantum algorithms with software for evaluation and prototyping._
+
+- https://pqca.org/
+
+The pq-code-package is a project under the PQCA
diff --git a/docs/overview/purpose.md b/docs/overview/purpose.md
@@ -1 +1,13 @@
-<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+The PQ Code Package project is a new open source project that aims to build high-assurance software implementations of standards-track post-quantum cryptography algorithms.  The PQCP is a project within the [Linux Foundation](https://linuxfoundation.org/) as part of the [Post-Quantum Cryptography Alliance](https://pqca.org/).
+
+Our initial focus in the first phase of the project will be on the [Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM) algorithm](https://csrc.nist.gov/pubs/fips/203/ipd).  As the project grows, we intend to also produce implementations for [ML-DSA](https://csrc.nist.gov/pubs/fips/204/ipd) and [SLH-DSA](https://csrc.nist.gov/pubs/fips/205/ipd), as well as other standards-track post-quantum algorithms.
+
+We aim for implementations produced by the project to have assurances given either as a result of external audits or as a result of formal verification methods (or both).
+
+We have interest from early participants to create or build on existing implementations for the following algorithms and platforms, and hope to expand this list as the project progresses:
+
+- a platform-independent implementation of ML-KEM in C
+- an AVX2-optimized assembly implementation of ML-KEM
+- a Rust implementation of ML-KEM
+- an aarch64-optimized implementation of ML-KEM
diff --git a/docs/security/reporting-a-security-issue.md b/docs/security/reporting-a-security-issue.md
@@ -0,0 +1,5 @@
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+Guidance on reporting security concerns will be added soon.
+
+For now, please contact one of the project maintainers directly if it's a security concern that's not yet appropriate to make public.
diff --git a/mkdocs.yml b/mkdocs.yml
diff --git a/scripts/catalog_repo.pl b/scripts/catalog_repo.pl

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+The DCO is a per-commit sign-off made by a contributor stating that they agree to the terms published at https://developercertificate.org/ for that particular contribution.`
	`2`	`+`
	`3`	`+* [Read more](https://wiki.linuxfoundation.org/dco)`