The specification is licensed under a Creative Commons Attribution 4.0
International License (CC-BY-4.0). For details, see the LICENSE
file. This covers the document sources in src/ and modules/ and everything
built from them.
The reference implementations and tests in zvknhk/ are software, not
specification text, and are licensed under the BSD 3-Clause License; see
zvknhk/LICENSE. That code is written to be copied into
QEMU (GPL-2.0-or-later), OpenSSL (Apache-2.0) and Spike (BSD-3-Clause), and
BSD-3-Clause is the license compatible with all three. Every file carries an
SPDX-License-Identifier tag stating which of the two applies to it.
The list of contributors to this specification is maintained in the contributors file.
For guidelines on how to contribute, refer to the CONTRIBUTING file.
The following directories are used to organize the contents of this repo:
-
dependencies/: software dependencies needed to build the specification -
docs-resources/: resources for all specifications sourced from git submodule -
modules/ROOT/: the specification content, laid out as an Antora component (pages/holds the chapters,resources/the bibliography); it is the single source for both the PDF and the web site -
src/riscv-pqc.adoc: the PDF assembler, which includes the chapters frommodules/ROOT/pages/ -
scripts/: release and site tooling from the RISC-V docs-spec-template -
build/: default directory where the build artifacts are generated -
zvknhk/: reference implementations and tests for theZvknhkVector Keccak extension — see zvknhk/README.md. The document includeszvknhk/sail/zvknhk_insts.saildirectly (through the symbolic linkmodules/ROOT/examples/zvknhk_insts.sail); building it does not require the Sail compiler or the reference-implementation submodules.
To build the document, you’ll need the following tools installed on your system:
-
Make
-
asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, asciidoctor-lists, and asciidoctor-mathematical
-
Docker
To start the build process, run:
cd ./riscv-pqc && make buildThe Makefile script will check the availability of Docker on your system:
-
If Docker is available, the documentation will be built inside a Docker container using the image
riscvintl/riscv-docs-base-container-image:latest. This ensures a consistent build environment across different systems. -
If Docker is not available, the documentation will be built directly on your system using the installed tools.
The PDF is named build/riscv-pqc-v<version>-<YYYYMMDD>.pdf, as the RISC-V
Architecture Review Committee requires (see ARC_SUBMISSION.md). The
version and the document state on the title page come from the v* git tags
through scripts/release-info.sh; an untagged build is labeled as a
development build. To build a specific version, run for example
make VERSION=v0.8.
The same content is published as an Antora site on GitHub Pages at
https://riscv.github.io/riscv-pqc/ by the publish-site.yml workflow. To
preview it locally (needs Node.js, and Docker for the diagram server):
npm install
docker compose up -d kroki
npm run preview # writes build/site/
docker compose downSee ANTORA.md for how the PDF and the site are built from one source.
Releases are v* tags. The milestone versions are v0.6, v0.8, v0.9,
v0.99 and v1.0; see ARC_SUBMISSION.md and SPEC_STATE.md. A
pushed tag builds the PDF, attaches it to a GitHub Release, and publishes the
site under /pqc/<version>/.
The repository has some basic commit checks set up with pre-commit that will be enforced by the GitHub CI. To ensure these checks are also run in the local repository while making changes the following command can be run:
pip3 install pre-commit && pre-commit installWhen enabling additional checks by editing .pre-commit-config.yaml, it is recommended to run to newly added check on all files in the repository. This can be done with the following command:
pre-commit run --all-files