{"id":13600629,"url":"https://github.com/PQClean/PQClean","last_synced_at":"2025-04-11T00:31:43.476Z","repository":{"id":41148628,"uuid":"165149670","full_name":"PQClean/PQClean","owner":"PQClean","description":"Clean, portable, tested implementations of post-quantum cryptography","archived":false,"fork":false,"pushed_at":"2025-03-05T11:24:17.000Z","size":7209,"stargazers_count":669,"open_issues_count":35,"forks_count":126,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-04-07T00:10:38.860Z","etag":null,"topics":["c","cryptography","implementations","post-quantum","post-quantum-cryptography","pqc","pqcrypto"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PQClean.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-11T00:04:18.000Z","updated_at":"2025-04-05T12:19:47.000Z","dependencies_parsed_at":"2023-09-21T17:55:02.857Z","dependency_job_id":"f58d3c0e-e08f-4a3d-befe-4a255122a841","html_url":"https://github.com/PQClean/PQClean","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PQClean%2FPQClean","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PQClean%2FPQClean/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PQClean%2FPQClean/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PQClean%2FPQClean/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PQClean","download_url":"https://codeload.github.com/PQClean/PQClean/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248322376,"owners_count":21084334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","cryptography","implementations","post-quantum","post-quantum-cryptography","pqc","pqcrypto"],"created_at":"2024-08-01T18:00:45.396Z","updated_at":"2025-04-11T00:31:38.465Z","avatar_url":"https://github.com/PQClean.png","language":"C","funding_links":[],"categories":["Software Projects","18. Emerging Trends in Rust Security","Quantum and post-quantum cryptography"],"sub_categories":["18.3 Post-Quantum Cryptography"],"readme":"# PQClean\n\n_[See the build status for each component here](.github/workflows/BADGES.md)_\n\n**PQClean**, in short, is an effort to collect **clean** implementations of the post-quantum\nschemes that are in the\n[NIST post-quantum project](https://csrc.nist.gov/projects/post-quantum-cryptography).\nThe goal of PQClean is to provide *standalone implementations* that\n\n* can easily be integrated into libraries such as [liboqs](https://openquantumsafe.org/#liboqs).\n* can efficiently upstream into higher-level protocol integration efforts such as [Open Quantum Safe](https://openquantumsafe.org/#integrations);\n* can easily be integrated into benchmarking frameworks such as [SUPERCOP](https://bench.cr.yp.to/supercop.html);\n* can easily be integrated into frameworks targeting embedded platforms such as [pqm4](https://github.com/mupq/pqm4);\n* are suitable starting points for architecture-specific optimized implementations;\n* are suitable starting points for evaluation of implementation security; and\n* are suitable targets for formal verification.\n\nWhat PQClean is **not** aiming for is\n\n* a build system producing an integrated library of all schemes;\n* including benchmarking of implementations; and\n* including integration into higher-level applications or protocols.\n\nAs a first main target, we are collecting C implementations that fulfill the requirements\nlisted below. We also accept optimised implementations, but still requiring high-quality, tested code.\n\nPlease also review our [guidelines for contributors](CONTRIBUTING.md) if you are interested in adding a scheme to PQClean.\n\n## PQClean paper\n\nFor a summary of the lessons learnt while working on PQClean, please refer to:\n\n\u003e Matthias J. Kannwischer, Peter Schwabe, Douglas Stebila, and Thom Wiggers. “Improving Software Quality in Cryptography Standardization Projects.” In: Security Standardization Research – EuroS\u0026P Workshops 2022. 2022.\n\nFind the paper at https://eprint.iacr.org/2022/337\n\nPlease cite this work when referring to PQClean:\n\n```bibtex\n@inproceedings{SSR:KSSW22,\n  author    = {Matthias J. Kannwischer and\n               Peter Schwabe and\n               Douglas Stebila and\n               Thom Wiggers},\n  title     = {Improving Software Quality in Cryptography Standardization Projects},\n  booktitle = {{IEEE} European Symposium on Security and Privacy, EuroS{\\\u0026}P 2022 - Workshops, Genoa, Italy, June 6-10, 2022},\n  pages     = {19--30},\n  publisher = {IEEE Computer Society},\n  address   = {Los Alamitos, CA, USA},\n  year      = {2022},\n  url       = {https://eprint.iacr.org/2022/337},\n  doi       = {10.1109/EuroSPW55150.2022.00010},\n}\n```\n\n**Please note** that many of the implementations included in PQClean originate from original research projects themselves, and their authors will appreciate getting cited as well.\n\n## Requirements on C implementations that are automatically checked\n\n_The checking of items on this list is still being developed. Checked items should be working._\n\n* [x] Code is valid C99\n* [x] Passes functional tests\n* [x] API functions do not write outside provided buffers\n* [x] `api.h` cannot include external files\n* [x] Compiles with `-Wall -Wextra -Wpedantic -Werror -Wmissing-prototypes` with `gcc` and `clang`\n* [x] `#if`/`#ifdef`s only for header encapsulation\n* [x] Consistent test vectors across runs\n* [x] Consistent test vectors on big-endian and little-endian machines\n* [x] Consistent test vectors on 32-bit and 64-bit machines\n* [x] `const` arguments are labeled as `const`\n* [x] No errors/warnings reported by valgrind\n* [x] No errors/warnings reported by address sanitizer\n* [x] Only dependencies: `fips202.c`, `sha2.c`, `aes.c`, `randombytes.c`\n* [x] API functions return `0` on success\n* [x] No dynamic memory allocations (including variable-length arrays)\n* [ ] No branching on secret data (dynamically checked using valgrind)\n* [ ] No access to secret memory locations (dynamically checked using valgrind)\n* [x] Separate subdirectories (without symlinks) for each parameter set of each scheme\n* [x] Builds under Linux, MacOS, and Windows\n    * [x] Linux\n    * [x] MacOS\n    * [x] Windows\n* [x] Makefile-based build for each separate scheme\n* [x] Makefile-based build for Windows (`nmake`)\n* [x] All exported symbols are namespaced with `PQCLEAN_SCHEMENAME_`\n* [x] Each implementation comes with a `LICENSE` file (see below)\n* [x] Each scheme comes with a `META.yml` file giving details about version of the algorithm, designers\n    * [x] Each individual implementation is specified in `META.yml`.\n\n\n## Requirements on C implementations that are manually checked\n\n* Minimalist Makefiles\n* No stringification macros\n* Output-parameter pointers in functions are on the left\n* All exported symbols are namespaced in place\n* Integer types are of fixed size where relevant, using `stdint.h` types (optional, recommended)\n* Integers used for indexing memory are of size `size_t` (optional, recommended)\n* Variable declarations at the beginning (except in `for (size_t i=...`) (optional, recommended)\n\n## Schemes currently in PQClean\n\nFor the following schemes we have implementations of one or more of their parameter sets.\nFor all of these schemes we have clean C code, but for some we also have optimised code.\n\n### Key Encapsulation Mechanisms\n\n**Finalists:**\n* Kyber\n\n**Alternate candidates:**\n* HQC\n* Classic McEliece\n\n### Signature schemes\n\n**To-be standards:**\n* Dilithium\n* Falcon\n* SPHINCS+\n\n**Alternate candidates:**\n* No participants yet.\n\nImplementations previously available in PQClean and dropped in Round 3 of the NIST standardization effort are available in the [`round2` tag](https://github.com/PQClean/PQClean/releases/tag/round2). \n\nImplementations previously available in PQClean and dropped in Round 4 of the NIST standardization effort are available in the [`round3` tag](https://github.com/PQClean/PQClean/releases/tag/round3). \n\n## API used by PQClean\n\nPQClean is essentially using the same API as required for the NIST reference implementations,\nwhich is also used by SUPERCOP and by libpqcrypto. The only differences to that API are\nthe following:\n* All functions are namespaced;\n* All lengths are passed as type `size_t` instead of `unsigned long long`; and\n* Signatures offer two additional functions that follow the \"traditional\" approach used\nin most software stacks of computing and verifying signatures instead of producing and\nrecovering signed messages. Specifically, those functions have the following name and signature:\n\n```c\nint PQCLEAN_SCHEME_IMPL_crypto_sign_signature(\n    uint8_t *sig, size_t *siglen,\n    const uint8_t *m, size_t mlen,\n    const uint8_t *sk);\nint PQCLEAN_SCHEME_IMPL_crypto_sign_verify(\n    const uint8_t *sig, size_t siglen,\n    const uint8_t *m, size_t mlen,\n    const uint8_t *pk);\n```\n\n## Building PQClean\n\nAs 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.\n\nList of required dependencies: ``gcc or clang, make, python3, python-yaml library, valgrind, astyle (\u003e= 3.0)``.\n\n## Using source code from PQClean in your own project\n\nEach implementation directory in PQClean (e.g., crypto\\_kem/kyber768\\_clean) can be extracted for use in your own project.  You will need to:\n\n1. Copy the source code from the implementation's directory into your project.\n2. Add the files to your project's build system.\n3. Provide instantiations of any of the common cryptographic algorithms used by the implementation.  This likely includes `common/randombytes.h` (a cryptographic random number generator), and possibly `common/sha2.h` (the SHA-2 hash function family), `common/aes.h` (AES implementations), `common/fips202.h` (the SHA-3 hash function family) and `common/sp800-185.h` (the cSHAKE family).\n   It is possible to use the implementations from the `common/` folder, but note that they may not be the most performant implementations and may do unnecessary things (like heap allocations) for our testing purposes.\n\nRegarding #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:\n\n- The file `Makefile` which can be used with GNU Make, BSD Make, and possibly others.\n- The file `Makefile.Microsoft_nmake` which can be used with Visual Studio's nmake.\n\n## Projects integrating PQClean-distributed source code\n\nThe following projects consume implementations from PQClean and provide their own wrappers around the implementations.\nTheir integration strategies may serve as examples for your own projects.\n\n- **[QuantCrypt](https://github.com/aabmets/quantcrypt)**: Cross-platform Python library for Post-Quantum Cryptography using precompiled PQClean binaries\n- **[pqcrypto crate](https://github.com/rustpq/pqcrypto)**: Rust integration that automatically generates wrappers from PQClean source code.\n- **[mupq](https://github.com/mupq/)**: Runs the implementations from PQClean as reference implementations to compare with microcontroller-optimized code.\n- **[node-pqclean](https://github.com/tniessen/node-pqclean)**: JavaScript interface for PQClean that natively supports Node.js, as well as Deno and web platforms through WebAssembly.\n- **[Open Quantum Safe](https://github.com/open-quantum-safe/)**: The Open Quantum Safe project integrates implementations from PQClean into their [liboqs](https://github.com/open-quantum-safe/liboqs/) C library, which then exposes them via [C++](https://github.com/open-quantum-safe/liboqs-cpp), [C# / .NET](https://github.com/open-quantum-safe/liboqs-dotnet), and [Python](https://github.com/open-quantum-safe/liboqs-python) wrappers, as well as to forks of [OpenSSL](https://github.com/open-quantum-safe/openssl) and [OpenSSH](https://github.com/open-quantum-safe/openssh-portable).\n\n## License\n\nEach subdirectory containing implementations contains a `LICENSE` file stating under what license that specific implementation is released.\nThe files in `common` contain licensing information at the top of the file (and are currently either public domain or MIT).\nAll other code in this repository is released under the conditions of [CC0](http://creativecommons.org/publicdomain/zero/1.0/).\n\n## Running tests locally\n\nSee https://github.com/PQClean/PQClean/wiki/Test-framework for details about the PQClean test framework.\n\nWhile we run extensive automatic testing on Github Actions ((emulated) Linux builds, MacOS and Windows builds) and [Travis CI][travis-pqc] (Aarch64 builds), and most tests can also be run locally.\nTo do this, make sure the following is installed:\n\n* Python 3.6+\n* `pytest` for python 3.\n\nWe also recommend installing ``pytest-xdist`` to allow running tests in parallel.\n\nYou will also need to make sure the submodules are initialized by running:\n\n```\ngit submodule update --init\n```\n\nRun the Python-based tests by going into the `test` directory and running `pytest -v` or (recommended) `pytest -n=auto` for parallel testing.\n\nYou may also run `python3 \u003ctestmodule\u003e` where `\u003ctestmodule\u003e` is any of the files starting with `test_` in the `test/` folder.\n\n[travis-pqc]: https://travis-ci.com/PQClean/PQClean/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPQClean%2FPQClean","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPQClean%2FPQClean","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPQClean%2FPQClean/lists"}