Clean, portable, tested implementations of post-quantum cryptography
PQClean, in short, is an effort to collect clean implementations of the post-quantum schemes that are in the NIST post-quantum project. The goal of PQClean is to provide standalone implementations that
What PQClean is not aiming for is
As a first main target, we are collecting C implementations that fulfill the requirements listed below. We also accept optimised implementations, but still requiring high-quality, tested code.
Please also review our guidelines for contributors if you are interested in adding a scheme to PQClean.
The checking of items on this list is still being developed. Checked items should be working.
api.hcannot include external files
-Wall -Wextra -Wpedantic -Werror -Wmissing-prototypeswith
#ifdefs only for header encapsulation
constarguments are labeled as
LICENSEfile (see below)
META.ymlfile giving details about version of the algorithm, designers
stdint.htypes (optional, recommended)
for (size_t i=...) (optional, recommended)
For the following schemes we have implementations of one or more of their parameter sets. For all of these schemes we have clean C code, but for some we also have optimised code.
Finalists: * Classic McEliece * Kyber * NTRU * SABER
Alternate candidates: * FrodoKEM * HQC
Finalists: * Dilithium * Falcon * Rainbow
Alternate candidates: * SPHINCS+tag.
PQClean is essentially using the same API as required for the NIST reference implementations, which is also used by SUPERCOP and by libpqcrypto. The only differences to that API are the following: * All functions are namespaced; * All lengths are passed as type
unsigned long long; and * Signatures offer two additional functions that follow the "traditional" approach used in most software stacks of computing and verifying signatures instead of producing and recovering signed messages. Specifically, those functions have the following name and signature:
int PQCLEAN_SCHEME_IMPL_crypto_sign_signature( uint8_t *sig, size_t *siglen, const uint8_t *m, size_t mlen, const uint8_t *sk); int PQCLEAN_SCHEME_IMPL_crypto_sign_verify( const uint8_t *sig, size_t siglen, const uint8_t *m, size_t mlen, const uint8_t *pk);
As noted above, PQClean is not meant to be built as a single library: it is a collection of source code that can be easily integrated into other libraries. The PQClean repository includes various test programs which do build various files, but you should not use the resulting binaries.
List of required dependencies:
gcc or clang, make, python3, python-yaml library, valgrind, astyle (>= 3.0).
Each implementation directory in PQClean (e.g., crypto_kem/kyber768\clean) can be extracted for use in your own project. You will need to:
common/randombytes.h(a cryptographic random number generator), and possibly
common/sha2.h(the SHA-2 hash function family),
common/fips202.h(the SHA-3 hash function family) and
common/sp800-185.h(the cSHAKE family).
Regarding #2, adding the files to your project's build system, each implementation in PQClean is accompanied by example two makefiles that show how one could build the files for that implementation:
Makefilewhich can be used with GNU Make, BSD Make, and possibly others.
Makefile.Microsoft_nmakewhich can be used with Visual Studio's nmake.
The following projects consume implementations from PQClean and provide their own wrappers around the implementations. Their integration strategies may serve as examples for your own projects.
Each subdirectory containing implementations contains a
LICENSEfile stating under what license that specific implementation is released. The files in
commoncontain 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.
See https://github.com/PQClean/PQClean/wiki/Test-framework for details about the PQClean test framework.
While we run extensive automatic testing on Github Actions ((emulated) Linux builds, MacOS and Windows builds) and Travis CI (Aarch64 builds), and most tests can also be run locally. To do this, make sure the following is installed:
pytestfor python 3.
We also recommend installing
pytest-xdistto allow running tests in parallel.
You will also need to make sure the submodules are initialized by running:
git submodule update --init
Run the Python-based tests by going into the
testdirectory and running
pytest -vor (recommended)
pytest -n=autofor parallel testing.
You may also run
python3where is any of the files starting with