PQClean/PQClean
GitHub: PQClean/PQClean
提供后量子密码学的干净、可移植 C 语言实现，便于集成到各类安全项目和评估框架中。
Stars: 916 | Forks: 183
# PQClean 项目介绍
_[在此查看各组件的构建状态](.github/workflows/BADGES.md)_
**PQClean**，简而言之，是一项旨在收集 [NIST 后量子项目](https://csrc.nist.gov/projects/post-quantum-cryptography)中后量子方案的**干净**实现的工作。
PQClean 的目标是提供*独立的实现*，它们：
* 可以轻松集成到 [liboqs](https://openquantumsafe.org/#liboqs) 等库中。
* 可以高效地上游合并到 [Open Quantum Safe](https://openquantumsafe.org/#integrations) 等更高级别的协议集成工作中。
* 可以轻松集成到 [SUPERCOP](https://bench.cr.yp.to/supercop.html) 等基准测试框架中。
* 可以轻松集成到针对 [pqm4](https://github.com/mupq/pqm4) 等嵌入式平台的框架中。
* 适合作为架构特定优化实现的起点。
* 适合作为评估实现安全性的起点。
* 适合作为形式化验证的目标。
PQClean **不**致力于：
* 一个能生成包含所有方案的集成库的构建系统；
* 包含实现的基准测试；以及
* 包含集成到更高级别的应用程序或协议中。
作为首要目标，我们正在收集满足下列要求的 C 语言实现。我们也接受优化的实现，但仍要求高质量、经过测试的代码。
如果您有兴趣将方案添加到 PQClean，也请查阅我们的[贡献者指南](CONTRIBUTING.md)。
## PQClean 论文
关于在开发 PQClean 过程中所获经验教训的总结，请参考：
论文可在 https://eprint.iacr.org/2022/337 找到。
引用 PQClean 时，请引用此工作：
```
@inproceedings{SSR:KSSW22,
author = {Matthias J. Kannwischer and
Peter Schwabe and
Douglas Stebila and
Thom Wiggers},
title = {Improving Software Quality in Cryptography Standardization Projects},
booktitle = {{IEEE} European Symposium on Security and Privacy, EuroS{\&}P 2022 - Workshops, Genoa, Italy, June 6-10, 2022},
pages = {19--30},
publisher = {IEEE Computer Society},
address = {Los Alamitos, CA, USA},
year = {2022},
url = {https://eprint.iacr.org/2022/337},
doi = {10.1109/EuroSPW55150.2022.00010},
}
```
**请注意**，PQClean 中包含的许多实现本身源自原始研究项目，其作者也会感谢被引用。
## 自动检查的 C 语言实现要求
_此列表项目的检查仍在开发中。已勾选的项目应可正常工作。_
* [x] 代码是有效的 C99
* [x] 通过功能测试
* [x] API 函数不会写入提供的缓冲区之外
* [x] `api.h` 不能包含外部文件
* [x] 使用 `gcc` 和 `clang` 编译时，通过 `-Wall -Wextra -Wpedantic -Werror -Wmissing-prototypes` 选项
* [x] `#if`/`#ifdef` 仅用于头文件封装
* [x] 跨运行的测试向量一致
* [x] 在大端和小端机器上测试向量一致
* [x] 在 32 位和 64 位机器上测试向量一致
* [x] `const` 参数被标记为 `const`
* [x] valgrind 未报告错误/警告
* [x] address sanitizer 未报告错误/警告
* [x] 仅依赖项：`fips202.c`、`sha2.c`、`aes.c`、`randombytes.c`
* [x] API 函数成功时返回 `0`
* [x] 无动态内存分配（包括变长数组）
* [ ] 不基于秘密数据进行分支（使用 valgrind 动态检查）
* [ ] 不访问秘密内存位置（使用 valgrind 动态检查）
* [x] 每个方案的每个参数集都有单独的子目录（不使用符号链接）
* [x] 可在 Linux、MacOS 和 Windows 下构建
* [x] Linux
* [x] MacOS
* [x] Windows
* [x] 每个独立方案均有基于 Makefile 的构建
* [x] Windows (`nmake`) 的基于 Makefile 的构建
* [x] 所有导出符号都使用 `PQCLEAN_SCHEMENAME_` 命名空间
* [x] 每个实现都附带一个 `LICENSE` 文件（见下文）
* [x] 每个方案都附带一个 `META.yml` 文件，提供算法版本、设计者等详细信息
* [x] 每个独立实现都在 `META.yml` 中指定
## 手动检查的 C 语言实现要求
* 最简化的 Makefile
* 无字符串化宏
* 函数中的输出参数指针位于左侧
* 所有导出符号就地命名空间化
* 相关时使用 `stdint.h` 类型，确保整数类型大小固定（可选，推荐）
* 用于内存索引的整数类型为 `size_t`（可选，推荐）
* 变量声明位于开头（`for (size_t i=...` 除外）（可选，推荐）
## PQClean 中当前包含的方案
对于以下方案，我们拥有其一个或多个参数集的实现。
对于所有这些方案，我们都有干净的 C 代码，但对于某些方案，我们也有优化代码。
### 密钥封装机制
**最终候选：**
* Kyber
**备选候选：**
* HQC
* Classic McEliece
### 签名方案
**待定标准：**
* Dilithium
* Falcon
* SPHINCS+
**备选候选：**
* 目前尚无参与者。
在 NIST 标准化工作第 3 轮中被移除的、先前在 PQClean 中可用的实现，可在 [`round2` 标签](https://github.com/PQClean/PQClean/releases/tag/round2)中找到。
在 NIST 标准化工作第 4 轮中被移除的、先前在 PQClean 中可用的实现，可在 [`round3` 标签](https://github.com/PQClean/PQClean/releases/tag/round3)中找到。
## PQClean 使用的 API
PQClean 基本上使用与 NIST 参考实现要求相同的 API，该 API 也被 SUPERCOP 和 libpqcrypto 使用。与该 API 的唯一区别如下：
* 所有函数都有命名空间；
* 所有长度都作为 `size_t` 类型传递，而不是 `unsigned long long`；以及
* 签名方案提供了两个额外的函数，这些函数遵循大多数软件栈中计算和验证签名的传统方法，而不是生成和恢复签名消息。具体来说，这些函数具有以下名称和签名：
```
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);
```
## 构建 PQClean
如上所述，PQClean **并非**旨在构建为单一库：它是一个可以轻松集成到其他库中的源代码集合。PQClean 仓库包含各种测试程序，它们确实构建了各种文件，但您不应使用生成的二进制文件。
所需依赖项列表：`gcc 或 clang、make、python3、python-yaml 库、valgrind、astyle (>= 3.0)`。
## 在您自己的项目中使用 PQClean 的源代码
PQClean 中的每个实现目录（例如 `crypto\_kem/kyber768\_clean`）都可以提取出来用于您自己的项目。您需要：
1. 将源代码从实现目录复制到您的项目中。
2. 将文件添加到您项目的构建系统中。
3. 提供实现所使用的任何通用加密算法的实例化。这可能包括 `common/randombytes.h`（密码学随机数生成器），以及可能的 `common/sha2.h`（SHA-2 哈希函数家族）、`common/aes.h`（AES 实现）、`common/fips202.h`（SHA-3 哈希函数家族）和 `common/sp800-185.h`（cSHAKE 家族）。
可以使用 `common/` 文件夹中的实现，但请注意，它们可能不是性能最优的实现，并且可能为我们的测试目的执行了不必要的操作（如堆分配）。
关于第 2 步，将文件添加到您项目的构建系统中，PQClean 中的每个实现都附带两个示例 Makefile，展示如何为该实现构建文件：
- `Makefile` 文件，可用于 GNU Make、BSD Make，可能也适用于其他。
- `Makefile.Microsoft_nmake` 文件，可用于 Visual Studio 的 nmake。
## 集成 PQClean 分发源代码的项目
以下项目使用了 PQClean 的实现，并提供了自己的封装。
它们的集成策略可以作为您自己项目的示例。
- **[QuantCrypt](https://github.com/aabmets/quantcrypt)**：跨平台的 Python 后量子密码学库，使用预编译的 PQClean 二进制文件。
- **[pqcrypto crate](https://github.com/rustpq/pqcrypto)**：Rust 集成，从 PQClean 源代码自动生成封装。
- **[mupq](https://github.com/mupq/)**：运行 PQClean 中的实现作为参考实现，与微控制器优化代码进行比较。
- **[node-pqclean](https://github.com/tniessen/node-pqclean)**：PQClean 的 JavaScript 接口，原生支持 Node.js，并通过 WebAssembly 支持 Deno 和 Web 平台。
- **[Open Quantum Safe](https://github.com/open-quantum-safe/)**：Open Quantum Safe 项目将 PQClean 的实现集成到其 [liboqs](https://github.com/open-quantum-safe/liboqs/) C 库中，然后通过 [C++](https://github.com/open-quantum-safe/liboqs-cpp)、[C# / .NET](https://github.com/open-quantum-safe/liboqs-dotnet) 和 [Python](https://github.com/open-quantum-safe/liboqs-python) 封装暴露它们，以及暴露给 [OpenSSL](https://github.com/open-quantum-safe/openssl) 和 [OpenSSH](https://github.com/open-quantum-safe/openssh-portable) 的分支。
## 许可证
每个包含实现的子目录都包含一个 `LICENSE` 文件，说明该特定实现是在什么许可证下发布的。
`common` 中的文件在文件顶部包含许可信息（目前是公共领域或 MIT）。
此仓库中的所有其他代码均在 [CC0](http://creativecommons.org/publicdomain/zero/1.0/) 条件下发布。
## 本地运行测试
有关 PQClean 测试框架的详细信息，请参阅 https://github.com/PQClean/PQClean/wiki/Test-framework。
虽然我们在 Github Actions（模拟的 Linux 构建、MacOS 和 Windows 构建）和 [Travis CI][travis-pqc]（Aarch64 构建）上运行广泛的自动测试，但大多数测试也可以在本地运行。
为此，请确保已安装以下内容：
* Python 3.6+
* 用于 Python 3 的 `pytest`。
我们还推荐安装 `pytest-xdist` 以允许并行运行测试。
您还需要通过运行以下命令确保子模块已初始化：
```
git submodule update --init
```
进入 `test` 目录并运行 `pytest -v` 或（推荐）`pytest -n=auto` 进行并行测试，即可运行基于 Python 的测试。
您也可以运行 `python3 `，其中 `` 是 `test/` 文件夹中任何以 `test_` 开头的文件。
标签：C语言实现, DNS解析, meg, NIST标准, pocsuite3, 信息安全, 加密算法, 反取证, 可移植性, 后量子密码学, 安全评估, 客户端加密, 密码学, 密码方案, 嵌入式系统, 库集成, 开源项目, 形式验证, 手动系统调用, 数据管道, 架构优化, 独立实现, 软件工程, 软件测试, 逆向工具, 量子安全