Skip to content

Contributing guide

Jump to bottom
Michael Baentsch edited this page Feb 25, 2023 · 8 revisions

Contributing new quantum-safe algorithms

All submissions must meet acceptance criteria given below. Algorithms may be removed if they no longer meet the acceptance criteria.

  • Algorithmic requirements:
    • The algorithm must be submitted to the NIST Post-Quantum Cryptography project, or posted as update to an existing algorithm, and must be present in the current round
    • Algorithms whose security is considered effectively broken are not eligible for addition; see the Lifecycle section below for conditions on their removal.
    • KEMs can be IND-CPA or IND-CCA-secure, at any NIST security level.
    • Signature schemes can be EUF-CMA-secure, at any NIST security level.
  • Targets:
  • Source code requirements:
    • License: Source code licensed under the MIT License, the BSD license, or in the public domain can be directly incorporated into the repository. GPL code will not be included in the repository. All files (except those in external or pqclean directories) must include a machine-readable SPDX-License-Identifier header in a comment, as described by https://spdx.org/ids.
    • Code quality: The source code must meet the following quality checks, some of which are enforced by our continuous integration system:
      • Public API functions must be documented with appropriate Doxygen comments.
      • All secrets in memory must be zero'ed out before being deallocated/released using our OQS_MEM_* functions.
      • Exported symbols must be namespaced.
      • We will periodically run static analysis and other analysis tools to identify additional potential flaws. Authors of PRs are particularly encouraged to run all tests locally prior to submission of a PR.
      • See additional information on coding conventions.
      • Regarding constant time validation, see the test documentation.
    • Common function usage: The source code should make use of liboqs' random number generator, AES implementation, and SHA-3 implementation, rather than its own implementation.
  • Maintenance: We hope the contributor will intend to help update the implementation in liboqs as the algorithm evolves or as we make enhancements to the library. The goals and acceptance criteria for new algorithms on liboqs master branch are stated in the README.md. In particular, our goals are to include high quality implementations for which the contributor aims to help with ongoing maintenance.

To discuss the contribution of a new algorithm to liboqs master branch, please contact Douglas Stebila or post an issue on GitHub for discussion.

Additional information, including coding conventions, can be found on the wiki.

Automated inclusion

We have created a facility to automate the inclusion of upstream algorithms already following the guidelines laid out in this document. As the PQClean project has comparable goals, this automation is similar to the methods used there and encoded in the copy-from-upstream scripting. Code inclusion can be added by providing a suitable entry in the YML file specifying algorithm name and an upstream code location. Beyond the source code, a meta.yml file needs to be present at that location which then informs the actual import logic by specifying files to be imported, code version, algorithm KATs and entry points that have to be conformant to the OQS APIs for KEMs and signatures. The copy-from-upstream script has a patching mechanism that can be used in some rare cases when automated inclusion would otherwise fail.

Contributing common code

Various functions of common utility, e.g., for testing and code re-use, are provided in the src/common directory. Most notably these are different random number generators, AES implementation(s), SHA-3 implementation(s) and OpenSSL shims.

  • Targets:
    • Operating systems: Common code must build at least on Linux, Windows and macOS (x86_64).
    • Architecture: The code must build at least on x86 and x64. Build targets are available for various further processor-specific features.
  • Source code requirements:
    • License: Source code licensed under the MIT License, the BSD license, or in the public domain can be directly incorporated into the repository. GPL code will not be included in the repository. All files (except those in external or pqclean directories) must include a machine-readable SPDX-License-Identifier header in a comment, as described by https://spdx.org/ids.
    • Code quality: Source code contributed to OQS common code must be formatted in accordance with our formatting requirements. Non-OQS core code is any code not originally created in this repository but only imported manually or automatically, such as specific quantum-safe algorithms. Adherence to our formatting requirements is successfully tested by executing ./tests/run_astyle.sh in the liboqs project root folder without "Formatting" statements returned. Passing this test is a prerequisite for successful CI.
  • Maintenance: We hope the contributor will intend to help update the implementation in liboqs as the algorithm evolves or as we make enhancements to the library.

Contributing other enhancements

Bug reports can be filed as issues on GitHub. Please use the "bug" label and indicate which version of liboqs the issue relates to (by specifying the commit hash), and what platform was in use (CPU, operating system, compiler).

If you have some improvements to an algorithm, are interested in getting liboqs to build on a new platform, or want to explore integrating liboqs into a new application, feel free to open an issue or contribute a pull request.

Lifecycle

Release cycle: We aim to make releases 3 to 4 months. Plans for each individual release can be found on the Github projects board.

Versioning: We label our releases with a variant of semantic versioning, using the notation 0.Y.Z. Semantic versioning allows that anything may change between 0.whatever versions. We intend to use X.Y.Z labelling as follows, for X=0.

  • X=0 will be used while the library is considered experimental and while the NIST Post-Quantum Cryptography Standardization project has not completed.
  • Y will be incremented when backwards incompatible changes are introduced that either change the public API or change the input/output behaviour of a cryptographic algorithm. See explanation below.
  • Z will be incremented when backwards compatible bug fixes are introduced.

Algorithm deprecation: If an algorithm is found to be insecure or does not advance to the next round of the NIST competition, but is included in version 0.Y.Z, it will be marked as deprecated using a compile time warning in version 0.(Y+1).Z' and removed in version 0.(Y+2).Z''.

Algorithm compatibility: Unlike existing standardization cryptographic algorithms (SHA-2, SHA-3, PKCS#1v1.5, nistp256, ...), post-quantum algorithms are under active development, and the mathematical algorithm of a cryptographic scheme may change: a particular name (e.g., "FrodoKEM-AES-640") may refer to different mathematical algorithms over time. liboqs may update implementations as algorithms evolve. During the 0.Y.Z phase of liboqs, versions 0.Y.Z and version 0.(Y+1).Z' may not be interoperable. liboqs-reliant applications can check the alg_version member of the OQS_KEM data structure for each algorithm to obtain an identifier of the algorithm version used in a particular implementation; implementations returning the same alg_version for an algorithm will be interoperable.

API stability: The public API of liboqs master branch is currently considered to be the functions and macros in oqs/common.h, oqs/oqsconfig.h, oqs/kem.h, oqs/rand.h, oqs/sig.h, and includes all functions marked with OQS_API. During the 0.Y.Z phase of liboqs, incompatible changes to the public API will lead to incrementing Y.

License

liboqs is licensed primarily under the MIT License. Submissions to liboqs master branch must be under the MIT License, a compatible license, or in the public domain.

Continuous Integration (CI) Testing

Builds are tested using continuous integration systems as follows:

  • macOS 10.15.1 (Xcode 11.3) using CircleCI
  • Ubuntu 18.04 (Bionic), with gcc-7, gcc-8, and clang-9, on x86_64 using CircleCI
  • Debian 10 (Buster), with gcc-8.3.0, on amd64, ARMv8 (arm64), ARMv7 (armhf, armel) using CircleCI
  • Centos 8 with gcc on amd64 using CircleCI
  • Windows Server 2019, with Visual Studio 2019 and Msys2, on x86_64 using AppVeyor

Normal pull requests (PRs) must have all CI tests pass. Non-standard PRs must explain the reasons for breaking CI as well as a plan how to get CI to work again.

You can locally run most of the integration tests that CircleCI runs. First, you need to install CircleCI's local command line interface as indicated in the installation instructions. Then:

circleci local execute --job <jobname>

where <jobname> is one of the jobs in the CircleCI config file.

  • If the Checkout code stage fails with error xargs: tar: terminated by signal 13, you need to edit the .circleci/config.yml file to change checkout to *localCheckout as indicated.
  • You may receive an error "Failed uploading test results directory" when running CircleCI locally, that is expected behaviour.
  • You cannot run "machine" CircleCI builds locally, which are what we use for testing builds on emulated platforms, specifically the ARM debian-buster-aarch64, -armhf, and -armel jobs.
Clone this wiki locally