open-quantum-safe/oqs-provider

[](https://github.com/open-quantum-safe/oqs-provider/actions/workflows/linux.yml) [](https://github.com/open-quantum-safe/oqs-provider/actions/workflows/windows.yml) [](https://github.com/open-quantum-safe/oqs-provider/actions/workflows/macos.yml) # oqsprovider - 面向 OpenSSL (>=v3) 的 Open Quantum Safe provider ## 目的 本代码库包含用于启用抗量子密码（QSC）的代码，其实现方式是在标准的 OpenSSL (>v1.1) 发行版中通过实现一个单一的共享库，即 OQS [provider](https://www.openssl.org/docs/manmaster/man7/provider.html)。 ## 状态 目前，该 provider 全面支持 TLS1.3 中的 KEM 密钥建立机制进行抗量子密码，包括通过 OpenSSL (3.0) provider 接口和混合 KEM 方案管理此类密钥。此外，还可以通过 OpenSSL EVP 接口使用包括 CMS 和 CMP 功能在内的 QSC 签名。密钥持久化通过 encode/decode 机制、X.509 数据结构以及用于将私钥与相应 X.509 证书捆绑在一起的 PKCS#12 提供。从 OpenSSL 3.2 开始，支持 TLS1.3 签名功能，并且 CMS 相关的最终问题也已得到解决。 已实现的标准记录在单独的文件 [STANDARDS.md](STANDARDS.md) 中。 ## 算法 此实现提供了以下抗量子算法： ### KEM 算法 - **BIKE**:`bikel1`\*, `p256_bikel1`\*, `x25519_bikel1`\*, `bikel3`, `p384_bikel3`, `x448_bikel3`, `bikel5`, `p521_bikel5` - **FrodoKEM**:`efrodo640aes`, `p256_efrodo640aes`, `x25519_efrodo640aes`, `efrodo640shake`, `p256_efrodo640shake`, `x25519_efrodo640shake`, `efrodo976aes`, `p384_efrodo976aes`, `x448_efrodo976aes`, `efrodo976shake`, `p384_efrodo976shake`, `x448_efrodo976shake`, `efrodo1344aes`, `p521_efrodo1344aes`, `efrodo1344shake`, `p521_efrodo1344shake`, `frodo640aes`, `p256_frodo640aes`, `x25519_frodo640aes`, `frodo640shake`, `p256_frodo640shake`, `x25519_frodo640shake`, `frodo976aes`, `p384_frodo976aes`, `x448_frodo976aes`, `frodo976shake`, `p384_frodo976shake`, `x448_frodo976shake`, `frodo1344aes`, `p521_frodo1344aes`, `frodo1344shake`, `p521_frodo1344shake` - **HQC**:`hqc1`, `p256_hqc1`, `x25519_hqc1`, `hqc3`, `p384_hqc3`, `x448_hqc3`, `hqc5`, `p521_hqc5` - **ML-KEM**:`mlkem512`, `p256_mlkem512`, `x25519_mlkem512`, `bp256_mlkem512`, `mlkem768`, `p384_mlkem768`, `x448_mlkem768`, `bp384_mlkem768`, `X25519MLKEM768`, `SecP256r1MLKEM768`, `mlkem1024`, `p521_mlkem1024`, `SecP384r1MLKEM1024`, `bp512_mlkem1024` ### 签名算法 - **ML-DSA**:`mldsa44`, `p256_mldsa44`, `rsa3072_mldsa44`, `mldsa65`, `p384_mldsa65`, `mldsa87`, `p521_mldsa87` - **Falcon**:`falcon512`, `p256_falcon512`, `rsa3072_falcon512`, `falconpadded512`, `p256_falconpadded512`, `rsa3072_falconpadded512`, `falcon1024`, `p521_falcon1024`, `falconpadded1024`, `p521_falconpadded1024` - **MAYO**:`mayo1`, `p256_mayo1`, `mayo2`, `p256_mayo2`, `mayo3`, `p384_mayo3`, `mayo5`, `p521_mayo5` - **CROSS**:`CROSSrsdp128balanced`, `CROSSrsdp128fast`\*, `CROSSrsdp128small`\*, `CROSSrsdp192balanced`\*, `CROSSrsdp192fast`\*, `CROSSrsdp192small`\*, `CROSSrsdp256small`\*\*, `CROSSrsdpg128balanced`\*, `CROSSrsdpg128fast`\*, `CROSSrsdpg128small`\*, `CROSSrsdpg192balanced`\*, `CROSSrsdpg192fast`\*, `CROSSrsdpg192small`\*, `CROSSrsdpg256balanced`\*, `CROSSrsdpg256fast`\*, `CROSSrsdpg256small`\* - **UOV**:`OV_Is`\*\*, `p256_OV_Is`\*\*, `OV_Ip`\*\*, `p256_OV_Ip`\*\*, `OV_III`\*\*, `p384_OV_III`\*\*, `OV_V`\*\*, `p521_OV_V`\*\*, `OV_Is_pkc`\*\*, `p256_OV_Is_pkc`\*\*, `OV_Ip_pkc`, `p256_OV_Ip_pkc`, `OV_III_pkc`\*\*, `p384_OV_III_pkc`\*\*, `OV_V_pkc`\*\*, `p521_OV_V_pkc`\*\*, `OV_Is_pkc_skc`\*\*, `p256_OV_Is_pkc_skc`\*\*, `OV_Ip_pkc_skc`, `p256_OV_Ip_pkc_skc`, `OV_III_pkc_skc`\*\*, `p384_OV_III_pkc_skc`\*\*, `OV_V_pkc_skc`\*\*, `p521_OV_V_pkc_skc`\*\* - **SNOVA**:`snova2454`, `p256_snova2454`, `snova2454shake`\*\*, `p256_snova2454shake`\*\*, `snova2454esk`, `p256_snova2454esk`, `snova2454shakeesk`\*\*, `p256_snova2454shakeesk`\*\*, `snova37172`, `p256_snova37172`, `snova2583`\*\*, `p256_snova2583`\*\*, `snova56252`\*\*, `p384_snova56252`\*\*, `snova49113`\*\*, `p384_snova49113`\*\*, `snova3784`\*\*, `p384_snova3784`\*\*, `snova2455`, `p384_snova2455`, `snova60104`\*\*, `p521_snova60104`\*\*, `snova2965`, `p521_snova2965` - **SLH-DSA**:`slhdsasha2128s`, `slhdsasha2128f`, `slhdsasha2192s`, `slhdsasha2192f`, `slhdsasha2256s`, `slhdsasha2256f`, `slhdsashake128s`, `slhdsashake128f`, `slhdsashake192s`, `slhdsashake192f`, `slhdsashake256s`, `slhdsashake256f` - **MQOM**:`mqom2cat1gf16fastr5`, `p256_mqom2cat1gf16fastr5`, `mqom2cat1gf16fastr3`\*, `p256_mqom2cat1gf16fastr3`\*, `mqom2cat1gf16shortr5`\*, `p256_mqom2cat1gf16shortr5`\*, `mqom2cat1gf16shortr3`\*, `p256_mqom2cat1gf16shortr3`\*, `mqom2cat3gf16fastr5`, `p384_mqom2cat3gf16fastr5`, `mqom2cat3gf16fastr3`\*, `p384_mqom2cat3gf16fastr3`\*, `mqom2cat3gf16shortr5`\*, `p384_mqom2cat3gf16shortr5`\*, `mqom2cat3gf16shortr3`\*, `p384_mqom2cat3gf16shortr3`\*, `mqom2cat5gf16fastr5`, `p521_mqom2cat5gf16fastr5`, `mqom2cat5gf16fastr3`\*, `p521_mqom2cat5gf16fastr3`\*, `mqom2cat5gf16shortr5`\*, `p521_mqom2cat5gf16shortr5`\*, `mqom2cat5gf16shortr3`\*, `p521_mqom2cat5gf16shortr3`\* 由于底层的 [liboqs](https://github.com/open-quantum-safe/liboqs) 在构建时可以配置为不启用所有算法，并且运行时底层的 `openssl` 安装可能已经提供了某些算法，因此建议通过标准命令检查实际启用的算法子集，即： `openssl list -signature-algorithms -provider oqsprovider` 和 `openssl list -kem-algorithms -provider oqsprovider`。 此外，上述未标有“*”或“**”的算法已针对 TLS 操作启用。 上述标有“*”的算法**未**针对 TLS 操作启用；这[可以通过修改主算法配置文件中的“enabled”标志来更改](CONFIGURE.md#pre-build-configuration)。上述标有“**”的算法**未**启用；这无法更改，因为这些算法与 [RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446) 不兼容。 为了支持经典密码和抗量子密码的并行使用，该 provider 还提供了不同的混合算法，将经典方法和抗量子方法结合在一起。 共有两种类型的组合： 上面列出的混合算法带有表示经典算法的前缀，例如，用于椭圆曲线的："p256_"。 算法的完整列表、它们的互操作性代码点 (code points) 和 OID，以及动态调整它们的方法（例如，用于互操作性测试）记录在 [ALGORITHMS.md](ALGORITHMS.md) 中。 ## 与 OpenSSL >= 3.5 配合使用 从 3.5 版本开始，OpenSSL 在其默认 provider 中原生实现了一系列不断增长的标准 PQ 算法（例如 ML-KEM、ML-DSA 和 SLH-DSA）。由于这些实现比 `oqsprovider` 中的等效功能更先进且维护得更好，因此适用以下规则： 该规则以算法整体为关键点，而不是其组件。它适用于标准化纯算法（ML-KEM、ML-DSA 和 SLH-DSA）以及 OpenSSL 原生提供的任何标准化混合算法（目前是混合 KEM `X25519MLKEM768`、`SecP256r1MLKEM768` 和 `SecP384r1MLKEM1024`）。 只要 OpenSSL 没有实现特定的组合，即使该组合的一个组件已经被标准化，该混合算法仍可以通过 `oqsprovider` 使用：例如，尽管 OpenSSL 提供了它们的 `ML-KEM-512` 组件，`x25519_mlkem512` 和 `p256_mlkem512` 仍然可用。 因此，任何希望通过 `oqsprovider` 测试任何已禁用的标准化 PQ 算法（无论是纯算法还是混合算法）的人，都必须在 OpenSSL 版本 `>= 3.2` 且 `< 3.5` 中进行测试。 ## 与 LibOQS 0.16.0 配合使用 LibOQS 0.16.0 版本包含对两种 FrodoKEM 变体的支持，如其在 [ISO](https://frodokem.org/files/FrodoKEM_standard_proposal_20250929.pdf) 标准化提案中所规定。在上述规范中，名称 `frodokem` 现在指的是一种标记为salted** 的新变体，而原始规范重命名为 `efrodokem`，即 **ephemeral** 变体。因此，用户必须意识到，根据所采用的 `liboqs` 版本不同，字符串 `frodokem*` 将指代不同的 FrodoKEM 变体。 ## 构建和测试 -- 快速入门 下面详细描述的所有组件构建和测试都可以通过分别运行脚本 `scripts/fullbuild.sh` 和 `scripts/runtests.sh` 来执行（已在 Linux Ubuntu 和 Mint 以及 MacOS 上测试）。 默认情况下，这些脚本始终针对当前的 OpenSSL `master` 分支进行构建和测试。 这些脚本可以[通过设置各种变量来配置](CONFIGURE.md#convenience-build-script-options)。请注意，这些脚本_不会_安装 `oqsprovider`。这可以通过运行 `cmake --install _build` 来实现（并遵循[激活说明](USAGE.md#activation))。 ## 构建和测试 下文描述了使用标准 `cmake` 工具进行的基本的“构建-测试-安装”周期。有关针对特定平台的说明，请参阅 [UNIX](NOTES-UNIX.md)（包括 MacOS 和 `cygwin`）和 [Windows](NOTES-Windows.md)。 ## 配置选项 在构建或运行时配置 `oqs-provider` 的所有选项均记录在 [CONFIGURE.md](CONFIGURE.md) 中。 ## 前置条件 要构建 `oqsprovider`，需要安装 OpenSSL 3.0 和 liboqs。它们安装在何处并不重要，只要安装了即可。如果安装在非标准位置，则在运行 `cmake` 时必须通过变量 "OPENSSL_ROOT_DIR" 和 "liboqs_DIR" 提供这些位置。详情请参阅 [CONFIGURE.md](CONFIGURE.md)。 ## 基本步骤 ``` cmake -S . -B _build && cmake --build _build && ctest --test-dir _build && cmake --install _build ``` ## 使用 `oqsprovider` 的使用方法记录在单独的 [USAGE.md](USAGE.md) 文件中。 ## 关于 OpenSSL 版本的说明 编写 `oqsprovider` 是为了确保在支持 provider 概念的所有 OpenSSL 版本上进行构建。然而，对于通过 provider 接口支持的功能，OpenSSL 仍处于活跃开发中。因此，上面记录的某些功能仅在特定的 OpenSSL 版本中受支持： ## 3.0/3.1 在这些版本中，不支持在 provider 中实现的 CMS 功能：https://github.com/openssl/openssl/issues/17717 的解决方案尚未向后移植到 OpenSSL3.0。 此版本也不支持在 TLS1.3 操作期间使用的基于 provider 的签名算法，如 https://github.com/openssl/openssl/issues/10512 中所述。 在 3.0.2 中也没有完全支持根据 openssl `speed` 命令进行性能测试，如 #385 中所述。 ## 3.2 及更高版本 这些版本在部署 `oqsprovider` 时完全支持使用 PQ 算法的所有 TLS1.3 操作，特别是在签名算法的使用方面。这还包括对以前不支持的 "OSSL_SIGNATURE_PARAM_CONTEXT_STRING" 参数的支持，并且自 `liboqs` 0.12 版本起，对单一 PQ 算法提供了有限的支持。 ## 3.4 及更高版本 预期这些版本支持 `openssl pkeyutl -encap/-decap` 语法，用于测试密钥封装和解封装以进行测试。要使用此选项，构建 OQS provider 时应包含 [KEM 编码/解码支持](CONFIGURE.md#oqs_kem_encoders)。 此版本中的新功能还包括能够通过新的 `openssl list` 选项检索当前所有处于活动状态的 TLS 签名算法： `openssl list -tls-signature-algorithms`。 这些版本还提供了对新 `sign/verify message` 接口的支持，该接口旨在对任意大的数据进行签名。包含此功能修改了混合签名组件的行为：不再进行无条件哈希，仅针对 `EVP_PKEY_OP_SIGNMSG/EVP_PKEY_OP_VERIFYMSG` 操作进行。这意味着 `EVP_PKEY_sign_init` 接口的行为已被修改，因为预期需要为混合签名方案提供适当的消息长度。 ## 3.5 及更高版本 这些版本包含对数量不断增加的标准化 PQC 算法（例如 ML-KEM、ML-DSA 和 SLH-DSA）的支持。因此，`oqsprovider` 无法再成功为这些算法注册 (O)ID，因为它们已经存在。 此外，`oqsprovider` 在功能性（例如，对多种密钥格式的支持）和非功能性（例如，代码质量）方面与这些算法的实现并不齐平。因此，如[与 OpenSSL >= 3.5 配合使用](#using-with-openssl--35)中所述，在 `openssl` 中检测到可用的任何组件已被标准化并在 OpenSSL 中实现的算法，在运行时会被禁用。即使使用相同的 `oqsprovider` 二进制文件，在版本低于 3.5 的 OpenSSL 安装中，这些算法仍将继续工作。 如果有足够的兴趣，通过实现 https://github.com/open-quantum-safe/oqs-provider/discussions/625 可能会解决此限制。非常欢迎贡献。 ## 所有版本 较旧 OpenSSL 版本中存在的一个限制是支持的默认组 (default groups) 的数量：[最多可以指定 44 个默认组](https://github.com/openssl/openssl/issues/23624)，例如，传递给 [SSL_CTX_set1_groups](https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set1_groups.html)。 因此，建议谨慎通过[预构建配置工具](CONFIGURE.md#pre-build-configuration) 激活 `oqsprovider` 支持的所有 KEM： 这可能导致 `openssl` 崩溃，具体取决于所使用的 OpenSSL 版本： 该问题在 OpenSSL "master" 分支以及自 3.3.0、3.2.2.、3.1.6 和 3.0.14 版本以来的相应分支中已不复存在。 有关 [OpenSSL 实现的普遍限制（例如，关于 provider 功能的使用和支持），请参见此处](https://www.openssl.org/docs/man3.0/man7/migration_guide.html)。 基本上与任何 TLS 服务器安装相关的一个问题是，观察到某些 TLS 服务器实现存在 [64 个 TLS 签名算法的限制](https://github.com/open-quantum-safe/oqs-provider/issues/399)。因此，再次建议谨慎[通过预构建配置工具激活超过 64 个 PQ 签名算法](CONFIGURE.md#pre-build-configuration)。 ## 一般免责声明 通常，强烈建议不要在任何版本的 `openssl` 中通过 `oqsprovider` 使用标准化算法系列，因为自 2024 年以来，密钥表现形式和密钥生成逻辑方面已出现差异。 `oqsprovider` 主要作为一种工具，旨在启用实验性 PQ 密码的测试，无意也无义务复制为 `openssl` 默认 provider 中生产级 PQ 密码开发所投入的努力。 ## 历史 有关当前和过去版本（“代码历史”）的文档记录在单独的文件 [RELEASE.md](RELEASE.md) 中。 # 免责声明 ## 标准软件免责声明 本软件按“原样”提供，不附带任何明示或暗示的保证，并且拒绝承担所有暗示的保证，包括任何关于适销性和特定用途适用性的保证。 ## 标准合规性 本项目遵循 [NIST PQC 标准化流程](https://csrc.nist.gov/projects/post-quantum-cryptography)，旨在支持对 NIST 正在评估和处于不同标准化阶段的各种 PQC 算法进行实验。目前，`oqsprovider` 无法声称或证明其遵守了已发布的任何标准文件。有关更多详细信息，请仔细查阅文件 [STANDARDS.md](STANDARDS.md)。最值得注意的是，仅在 `oqsprovider` 中实现的混合实现仍处于标准前/草案阶段。随着时间的推移，该项目旨在提供标准合规性，并征求通过贡献的意见来实现这一目标。 ## 组件免责声明 用于实现所有纯 PQC 功能的 `oqsprovider` 完全依赖于 [liboqs](https://github.com/open-quantum-safe/liboqs)，因此不建议将其用于实验目的之外的任何用途： 我们目前不建议在生产环境中依赖此软件或使用它来保护任何敏感数据。本软件旨在协助研究和原型设计。虽然我们尽最大努力避免安全漏洞，但该库尚未达到高安全性应用所需的审计和分析水平，因此不能作为高安全性用途的可靠依据。 更多详细信息和背景请参见： [liboqs 免责声明](https://github.com/open-quantum-safe/liboqs#limitations-and-security)

标签：Bash脚本, C/C++, OpenSSL, TLS, 事务性I/O, 加密库, 后量子密码学, 客户端加密, 密码学, 手动系统调用, 防御工具