aabmets/quantcrypt
GitHub: aabmets/quantcrypt
一个跨平台的 Python 库，封装预编译的 PQClean 二进制，解决在 Python 中使用后量子密码的易用性与跨平台问题。
Stars: 55 | Forks: 9
# QuantCrypt
[](https://pypi.org/project/quantcrypt/)
[](https://github.com/aabmets/quantcrypt/blob/main/LICENSE)
[](https://codecov.io/gh/aabmets/quantcrypt)
[](https://github.com/aabmets/quantcrypt/actions/workflows/pytest-codecov.yml)
[](https://pypistats.org/packages/quantcrypt)
[](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt)
[](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt)
[](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt)
[](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt)
[](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt) [](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt) [](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt) [](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt) ## 注意：归档意图 本项目将于 2026 年 7 月与 PQClean 项目一同被标记为只读状态。 请将您的代码迁移到任何替代实现方案中（如果 Python 存在这些替代方案的话）。 有关更多信息，请参阅 issue [PQClean/PQClean#604](https://github.com/PQClean/PQClean/issues/604)。 ## 描述 QuantCrypt 是一个跨平台的 Python 库，使用预编译的 PQClean 二进制文件进行后量子密码学操作。 虽然 QuantCrypt 包含由 [NIST](https://csrc.nist.gov/projects/post-quantum-cryptography) 标准化的多种 PQC 算法变体， 但建议仅使用由 [NSA 的 CNSA 咨询](https://en.wikipedia.org/wiki/Commercial_National_Security_Algorithm_Suite)推荐的最强变体。 ## 动机 目前，尚不存在任何纯 Python 实现的后量子密码学算法， 这使得 Python 开发者必须首先寻找从哪里获取可靠的 PQC 算法 C 源代码， 接着在他们的系统上安装必要的 C 编译器，然后摸索如何使用 CFFI 来编译并在其 Python 源代码中 使用这些 C 代码。此外，这些二进制文件仅与编译它们的平台兼容， 这使得在开发和部署工作流中使用不同的平台变得非常困难，因为每次都必须重新编译 C 源代码。 本库通过在 GitHub Actions 中使用 CFFI 为 Windows、Linux 和 Darwin 平台预编译 PQC 算法的 C 源代码， 从而解决了这个问题，并且它还在 PQC 二进制文件的基础上提供了一个优雅的 Python 包装器。 因为我希望这个库能够包罗万象，所以它还包含许多在处理后量子密码学时可能需要的辅助类。 本库非常注重开发者体验，旨在提供强大的功能，同时又易于使用且令人愉悦，因此它能“直接为您所用”于您的项目中。 ## 快速开始 本库的完整文档可以在 [Wiki](https://github.com/aabmets/quantcrypt/wiki) 中找到。 因为该库拥有丰富的 docstring，能够提供对库行为的详细深入解析， 建议在使用本库时使用支持自动补全和代码洞察的 IDE。 最受欢迎的选择是 PyCharm 或带有 Python 专用插件的 VS Code。 ### 安装 要在安装 QuantCrypt 时包含默认依赖项（无编译器），请使用以下命令之一： 使用 [UV](https://docs.astral.sh/uv/) _(推荐)_： ``` uv add quantcrypt ``` 使用 [Poetry](https://python-poetry.org/docs/)： ``` poetry add quantcrypt ``` 使用 [pip](https://pip.pypa.io/en/stable/getting-started/)： ``` pip install quantcrypt ``` 如果您想在本地机器上重新编译 PQA 二进制文件，可以通过在上述任一安装命令后附加 `[compiler]` 来安装带可选依赖的 QuantCrypt。 QuantCrypt 会将带有预编译二进制文件的预构建 wheel 发布到 PyPI 仓库。 如果您的平台支持其中一种预构建的 wheel，那么您无需通过编译器选项安装 QuantCrypt 即可使用本库。 _**注意：**_ 如果您确实决定重新编译 PQA 二进制文件，您需要安装特定于平台的 `C/C++` 构建 工具，例如 [Visual Studio](https://visualstudio.microsoft.com/)、[Xcode](https://developer.apple.com/xcode/) 或 [GNU Make](https://www.gnu.org/software/make/) _(非详尽列表)_。 _**注意：**_ 如果您尝试在缺少可选依赖项的情况下通过编程方式导入 compiler 模块， 将会收到导入错误。 ### 脚本导入 ``` from quantcrypt import ( kem, # Key Encapsulation Mechanism algos - public-key cryptography dss, # Digital Signature Scheme algos - secret-key signatures cipher, # The Krypton Cipher - symmetric cipher based on AES-256 kdf, # Argon2 helpers + KMAC-KDF - key derivation functions errors, # All errors QuantCrypt may raise - also available from other modules utils, # Helper utilities from all modules - gathered into one module compiler # Tools for compiling PQA binaries - requires optional dependencies ) ``` ### CLI 命令 本库的通用功能也可以通过命令行访问，您可以使用 `qclib` 命令来调用。请记住，如果您将 QuantCrypt 安装到了 venv 中，您需要激活 venv 才能访问 CLI。QuantCrypt 内部使用 [Typer](https://typer.tiangolo.com/) 来提供 CLI 体验。 您可以使用 `--help` 选项来了解有关每个命令和子命令的更多信息。 ``` qclib --help qclib --version qclib info --help qclib keygen --help qclib encrypt --help qclib decrypt --help qclib sign --help qclib verify --help qclib remove --help qclib compile --help ``` _**注意：**_ 当带编译器可选依赖项成功安装 QuantCrypt 后， `compile` CLI 命令才可用。 ## 安全声明 本库中使用的 PQC 算法的安全性继承自 [PQClean](https://github.com/PQClean/PQClean) 项目。 您可以从他们的 [SECURITY.md](https://github.com/PQClean/PQClean/blob/master/SECURITY.md) 文件中阅读 PQClean 项目的安全声明。 要报告 PQC 算法的安全漏洞，请在 PQClean 仓库中创建一个 [issue](https://github.com/PQClean/PQClean/issues)。 ## 鸣谢 如果没有这些核心依赖项，这个库是不可能实现的： * [PQClean](https://github.com/PQClean/PQClean) - 后量子密码学算法的 C 源代码 * [Cryptodome](https://pypi.org/project/pycryptodome/) - AES-256 和 SHA3 实现 * [Argon2-CFFI](https://pypi.org/project/argon2-cffi/) - Argon2 KDF 实现 感谢这些库的创建者和维护者的辛勤工作。
[](https://pypi.org/project/quantcrypt/)
[](https://github.com/aabmets/quantcrypt/blob/main/LICENSE)
[](https://codecov.io/gh/aabmets/quantcrypt)
[](https://github.com/aabmets/quantcrypt/actions/workflows/pytest-codecov.yml)
[](https://pypistats.org/packages/quantcrypt)
[](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt)
[](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt)
[](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt)
[](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt)[](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt) [](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt) [](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt) [](https://sonarcloud.io/summary/new_code?id=aabmets_quantcrypt) ## 注意：归档意图 本项目将于 2026 年 7 月与 PQClean 项目一同被标记为只读状态。 请将您的代码迁移到任何替代实现方案中（如果 Python 存在这些替代方案的话）。 有关更多信息，请参阅 issue [PQClean/PQClean#604](https://github.com/PQClean/PQClean/issues/604)。 ## 描述 QuantCrypt 是一个跨平台的 Python 库，使用预编译的 PQClean 二进制文件进行后量子密码学操作。 虽然 QuantCrypt 包含由 [NIST](https://csrc.nist.gov/projects/post-quantum-cryptography) 标准化的多种 PQC 算法变体， 但建议仅使用由 [NSA 的 CNSA 咨询](https://en.wikipedia.org/wiki/Commercial_National_Security_Algorithm_Suite)推荐的最强变体。 ## 动机 目前，尚不存在任何纯 Python 实现的后量子密码学算法， 这使得 Python 开发者必须首先寻找从哪里获取可靠的 PQC 算法 C 源代码， 接着在他们的系统上安装必要的 C 编译器，然后摸索如何使用 CFFI 来编译并在其 Python 源代码中 使用这些 C 代码。此外，这些二进制文件仅与编译它们的平台兼容， 这使得在开发和部署工作流中使用不同的平台变得非常困难，因为每次都必须重新编译 C 源代码。 本库通过在 GitHub Actions 中使用 CFFI 为 Windows、Linux 和 Darwin 平台预编译 PQC 算法的 C 源代码， 从而解决了这个问题，并且它还在 PQC 二进制文件的基础上提供了一个优雅的 Python 包装器。 因为我希望这个库能够包罗万象，所以它还包含许多在处理后量子密码学时可能需要的辅助类。 本库非常注重开发者体验，旨在提供强大的功能，同时又易于使用且令人愉悦，因此它能“直接为您所用”于您的项目中。 ## 快速开始 本库的完整文档可以在 [Wiki](https://github.com/aabmets/quantcrypt/wiki) 中找到。 因为该库拥有丰富的 docstring，能够提供对库行为的详细深入解析， 建议在使用本库时使用支持自动补全和代码洞察的 IDE。 最受欢迎的选择是 PyCharm 或带有 Python 专用插件的 VS Code。 ### 安装 要在安装 QuantCrypt 时包含默认依赖项（无编译器），请使用以下命令之一： 使用 [UV](https://docs.astral.sh/uv/) _(推荐)_： ``` uv add quantcrypt ``` 使用 [Poetry](https://python-poetry.org/docs/)： ``` poetry add quantcrypt ``` 使用 [pip](https://pip.pypa.io/en/stable/getting-started/)： ``` pip install quantcrypt ``` 如果您想在本地机器上重新编译 PQA 二进制文件，可以通过在上述任一安装命令后附加 `[compiler]` 来安装带可选依赖的 QuantCrypt。 QuantCrypt 会将带有预编译二进制文件的预构建 wheel 发布到 PyPI 仓库。 如果您的平台支持其中一种预构建的 wheel，那么您无需通过编译器选项安装 QuantCrypt 即可使用本库。 _**注意：**_ 如果您确实决定重新编译 PQA 二进制文件，您需要安装特定于平台的 `C/C++` 构建 工具，例如 [Visual Studio](https://visualstudio.microsoft.com/)、[Xcode](https://developer.apple.com/xcode/) 或 [GNU Make](https://www.gnu.org/software/make/) _(非详尽列表)_。 _**注意：**_ 如果您尝试在缺少可选依赖项的情况下通过编程方式导入 compiler 模块， 将会收到导入错误。 ### 脚本导入 ``` from quantcrypt import ( kem, # Key Encapsulation Mechanism algos - public-key cryptography dss, # Digital Signature Scheme algos - secret-key signatures cipher, # The Krypton Cipher - symmetric cipher based on AES-256 kdf, # Argon2 helpers + KMAC-KDF - key derivation functions errors, # All errors QuantCrypt may raise - also available from other modules utils, # Helper utilities from all modules - gathered into one module compiler # Tools for compiling PQA binaries - requires optional dependencies ) ``` ### CLI 命令 本库的通用功能也可以通过命令行访问，您可以使用 `qclib` 命令来调用。请记住，如果您将 QuantCrypt 安装到了 venv 中，您需要激活 venv 才能访问 CLI。QuantCrypt 内部使用 [Typer](https://typer.tiangolo.com/) 来提供 CLI 体验。 您可以使用 `--help` 选项来了解有关每个命令和子命令的更多信息。 ``` qclib --help qclib --version qclib info --help qclib keygen --help qclib encrypt --help qclib decrypt --help qclib sign --help qclib verify --help qclib remove --help qclib compile --help ``` _**注意：**_ 当带编译器可选依赖项成功安装 QuantCrypt 后， `compile` CLI 命令才可用。 ## 安全声明 本库中使用的 PQC 算法的安全性继承自 [PQClean](https://github.com/PQClean/PQClean) 项目。 您可以从他们的 [SECURITY.md](https://github.com/PQClean/PQClean/blob/master/SECURITY.md) 文件中阅读 PQClean 项目的安全声明。 要报告 PQC 算法的安全漏洞，请在 PQClean 仓库中创建一个 [issue](https://github.com/PQClean/PQClean/issues)。 ## 鸣谢 如果没有这些核心依赖项，这个库是不可能实现的： * [PQClean](https://github.com/PQClean/PQClean) - 后量子密码学算法的 C 源代码 * [Cryptodome](https://pypi.org/project/pycryptodome/) - AES-256 和 SHA3 实现 * [Argon2-CFFI](https://pypi.org/project/argon2-cffi/) - Argon2 KDF 实现 感谢这些库的创建者和维护者的辛勤工作。
标签：PQClean, Python, 后量子密码学, 密码学, 手动系统调用, 无后门, 跨平台