cryptography 常见问题完全指南：从安装排错到 PEM 解析的实战 FAQ

密码学【免费下载链接】cryptographycryptography is a package designed to expose cryptographic primitives and recipes to Python developers.项目地址https://gitcode.com/gh_mirrors/cr/cryptography点击查看免费下载cryptography是 Python 生态中最主流的密码学工具库之一为开发者提供加密原语primitives与开箱即用的配方recipes。本篇指南以官方 docs/faq.rst 为骨架系统梳理安装失败、警告抑制、OpenSSL 版本、Rust 构建、InternalError、PEM 导入等高频问题并结合仓库源码与测试给出可复现的排查路径与最佳实践。读完本文你将掌握如何快速解决pip install cryptography失败、如何正确抑制 import 时的弃用警告、如何应对 OpenSSL 版本过低与缺失 Rust 编译器、如何定位InternalError的根因、如何规范 PEM 文件使其可被顺利加载以及如何理解backend参数的历史演进与当前现状。问题追踪的原则先分清是不是 cryptography 的锅官方 FAQ 明确指出issue tracker 的首要目的是定位并修复cryptography自身的 bug 与功能请求。因此每当用户报障时项目组首先会问一个问题这是 cryptography 的 bug还是其他环节的 bug项目组会尽力帮助用户排查代码或环境层面的问题但也坦诚存在边界当问题与用户特定环境强相关、且无法复现时协助能力有限同时项目组不提供通用 Python 或 Python 打包packaging问题的支持。这一原则决定了你提 bug 时的预期管理尽量提供最小可复现示例并先排除自身代码与环境因素。无法抑制的 import 弃用警告为什么 filterwarnings 不生效警告类型不是 DeprecationWarning而是 UserWarningFAQ 特别用 hint 强调cryptography在 import 时发出的弃用警告并不继承DeprecationWarning而是继承UserWarning。这一设计在源码中有明确注释src/cryptography/utils.py# We use a UserWarning subclass, instead of DeprecationWarning, because CPython # decided deprecation warnings should be invisible by default. class CryptographyDeprecationWarning(UserWarning): passCPython 自 2.7 起默认隐藏DeprecationWarning仅开发者可见为了确保弃用提示真正被用户看到cryptography刻意选择继承UserWarning。pytest 场景下的抑制方法如果你的 pytest 遵循最佳实践、把警告视为错误filterwarnings errorimport 时弹出的弃用警告会导致测试直接失败。官方给出的解决方案是在filterwarnings列表末尾追加一条 ignore 规则ignore:Python 2 is no longer supported by the Python core team. Support for it is now deprecated in cryptography, and will be removed in a future release.:UserWarning为什么不能用 CryptographyDeprecationWarning 类名来过滤FAQ 特别强调了一个容易踩的坑不要试图用cryptography.utils.CryptographyDeprecationWarning作为 ignore 的类别参数。原因在于指定该类别时pytest/过滤器解析过程会内部触发import cryptography而这会在 ignore 规则生效之前就把警告发射出来规则形同虚设。同样的规则适用于 warnings.filterwarnings 与 -W 参数除了 pytestFAQ 指出同样的原理适用于代码内调用warnings.filterwarnings或者用 CPython 的-W命令行选项启动解释器。示例import warnings warnings.filterwarnings(ignore, messagerPython 2 is no longer supported.*)命令行方式$ python -W ignore:Python 2 is no longer supported.*:UserWarning your_script.py从源码看CryptographyDeprecationWarning同时是多个版本系列的弃用别名DeprecatedIn36~DeprecatedIn51见 src/cryptography/utils.py这意味着未来仍会有同类警告出现掌握上述匹配模式比记住某条具体消息更有价值。cryptography 安装失败的通用排错路径第一步升级 pip 再试安装失败的第一排查步骤永远是升级 pip 后重装。FAQ 给出的命令$ pip install -U pipWindows 平台则建议使用$ python -m pip install -U pip绝大多数安装问题尤其是旧 pip 无法识别新格式 wheel都能在这一步解决。升级后重新执行pip install cryptography若仍报错再参考完整的 docs/installation.rst 文档按平台逐项排查。第二步区分报错类型定位根因常见报错可归为三类对应 FAQ 中三个独立条目报错现象根因处理方向Can not find Rust compiler本地无 Rust 工具链需从源码构建升级 pip 获取预编译 wheel或安装 Rust见下文安装时因 OpenSSL 过旧失败系统 OpenSSL 低于 3.0.0升级到 OpenSSL 3.0.0可能需要升级操作系统构建时报错error: Can not find Rust compiler源码构建缺少 Rust参照 docs/installation.rst 的 Rust 章节安装为什么 cryptography 需要 Rust内存安全与性能的取舍FAQ 明确回答了为什么需要 Rust这一高频疑问cryptography的密码学运算依赖 OpenSSL详见 docs/openssl.rst——OpenSSL 是事实上的密码学标准实现性能高、附带多种对开发者有价值的认证。但它是 C 语言编写缺乏内存安全性。项目组的策略是保留 OpenSSL 的高性能优势同时把非密码学运算例如 ASN.1 解析重写为高性能、内存安全的 Rust。这一架构决策在仓库中清晰可见src/rust/下存在多个 Rust crate如负责 ASN.1 解析与编解码的src/rust/declarative_asn1/、负责密钥解析的 src/rust/cryptography-key-parsing/以及cryptography-openssl、cryptography-x509、cryptography-x509-verification等模块化 crate见 src/rust/Cargo.toml 及各 crate 的 Cargo.toml。Rust 只在构建期需要FAQ 特别澄清Rust 仅在 cryptography 的构建阶段需要构建完成后使用 cryptography 无需 Rust 环境。这与 C 编译器工具链的情况完全一致——都是构建需要、运行不需要。当前最低支持的 Rust 版本为 1.83.0见 docs/installation.rst 的 Rust 章节部分发行版如 Alpine 3.21、Debian 早于 Trixie 的版本、RHEL/CentOS 9.6 之前的版本自带的 Rust 过旧需要按官方指引安装较新版本。在 Docker 等部署场景中推荐多阶段构建构建阶段安装 Rust 和 C 工具链运行镜像中则不包含它们。遇到 InternalError 该怎么办InternalError 从哪来InternalError的定义位于 src/cryptography/exceptions.py其抛出点在 OpenSSL 绑定层。核心逻辑在 src/cryptography/hazmat/bindings/openssl/binding.pydef _openssl_assert(ok: bool) - None: if not ok: errors openssl.capture_error_stack() raise InternalError( Unknown OpenSSL error. This error is commonly encountered when another library is not cleaning up the OpenSSL error stack. ..., errors, )最常见的根因OpenSSL 错误栈被污染FAQ 明确指出InternalError最常见的原因是同一进程内其他也使用 OpenSSL 的库把错误留在了 OpenSSL 错误栈上。排查步骤逐个移除进程中的其他 OpenSSL 使用方如 PyOpenSSL、requests 的某些后端、其他加密库看问题是否消失若移除后仍有问题或确认其他库无责则可能是 cryptography 自身 bug请携带可复现步骤到项目 issue 区提交。OpenSSL 版本过低导致安装失败OpenSSL 项目已停止维护 0.9.8、1.0.0、1.0.1、1.0.2、1.1.0、1.1.1 这些发布系列这些版本不再获得上游安全补丁cryptography也随之放弃对它们的支持。因此安装或构建 cryptography 时遇到 OpenSSL 相关失败处理方式就是升级到 OpenSSL 3.0.0 或更高版本——这可能意味着需要升级到更新的操作系统发行版。从 docs/installation.rst 可以看到项目当前测试覆盖OpenSSL 3.0-latest、3.4-latest、3.5-latest、3.6-latest、4.0-latest以及 BoringSSL、aws-lc 与仍在安全支持期的 LibreSSL。多数主流平台通过manylinux/musllinux静态链接 wheel 即可获得最新 OpenSSL无需关心系统自带版本。构建报错 Can not find Rust compiler若从源码构建 cryptography 时出现该错误说明环境中没有 Rust 工具链。两条解决路径升级 pip新版 pip 会优先安装预编译的abi3wheel多数用户升级 pip 后即可跳过源码构建、不再需要 Rust安装 Rust按 docs/installation.rst 中的指引安装较新版本的 Rust推荐用 rustup最低 1.83.0并确保rustc/cargo在PATH中。同样强调Rust 只在构建阶段需要。Linux 下常见发行版安装命令取自 docs/installation.rst# Alpine $ sudo apk add gcc musl-dev python3-dev libffi-dev openssl-dev cargo pkgconfig # Debian/Ubuntu $ sudo apt-get install build-essential libssl-dev libffi-dev \ python3-dev cargo pkg-config # Fedora/RHEL/CentOS需 9.6 $ sudo dnf install redhat-rpm-config gcc libffi-devel python3-devel \ openssl-devel cargo pkg-config强制从源码构建不使用 manylinux wheel时可加--no-binary$ pip install cryptography --no-binary cryptographyAWS Lambda 上的安装/导入错误在 AWS Lambda 上遇到安装或导入错误时FAQ 建议严格遵循 AWS 官方文档来构建部署包构建 Lambda 的 .zip 归档时按 AWS 的 Python 打包文档操作使用容器镜像时按 AWS 的容器镜像构建文档操作。核心要点是Lambda 环境精简且架构可能非 x86-64依赖需随包带上或打进镜像且要注意为对应架构如 ARM64 Graviton获取正确的 wheel。abi3 wheel为什么你的 Python 版本没有专属 wheelFAQ 解释了一个常见疑惑为什么没有针对我的 Python 3.x 版本的 wheel答案在于 cryptography 的 Python 3 wheel 是abi3wheel即 CPython ABI 稳定 ABI。这类 wheel 标注了一个最低 Python 版本并可在大于或等于该版本的任何 Python 版本上使用。新版 pip 会自动选择并安装 abi3 wheel因此不需要为每个 Python 3 小版本单独发布 wheel。这意味着即使 PyPI 页面上没有与你 Python 3.x 精确匹配的 wheel 文件只要你的 Python 版本不低于 abi3 wheel 声明的基线例如 cp39安装也能正常进行。PEM 文件无法导入格式校验清单PEM 是什么PEM 是一种将密钥、证书等密码学数据编码为普通文本的格式最初定义于 RFC 1421后被多个 RFC 沿用。数据先做 base64 编码再用头尾行包裹。可导入的 PEM 必须满足三条规则FAQ 给出明确校验清单头行必须为单行形如-----BEGIN [FILE TYPE]-----其中[FILE TYPE]为CERTIFICATE、PUBLIC KEY、PRIVATE KEY等尾行必须为单行形如-----END [FILE TYPE]-----除最后一行外所有行必须恰好为 64 个字符base64 编码的 64 字符折行标准。合法 PEM 示例RSA 公钥-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7CsKFSzq20NLb2VQDXma 9DsDXtKADv0ziI5hT1KG6Bex5seE9pUoEcUxNv4uXo2jzAUgyRweRl/DLU8SoN8 WWd6YWik4GZvNv7j0z28h9Q5jRySxy4dmElFtIRHGiKhqd1Z06z4AzrmKEzgxkOk LJjY9cvwDiXjpK2oJwNNyavvjb5YZq6V60RhpyNtKpMh2zRLgIk9sROEPQeYfK 22zj2CnGBMg5Gm2uPOsGDltl/I/Fdh1aO3X4i1GXwCuPf1kSAg6lPJD0batftkSG v0X0heUaV0j1HSNlBWamT4IR9iJfKJHekOqvHQBcaCu7Ja4kXzx6GZ3M2j/Ja3A 2QIDAQAB -----END PUBLIC KEY-----若你的 PEM 导入失败对照上述三条规则逐一检查头尾行是否有额外空格或换行、中间行长度是否严格 64 字符、文件是否混入了不可见字符或非 base64 字符。对应加载 APIPEM 加载入口集中在 src/cryptography/hazmat/primitives/serialization/base.py例如from cryptography.hazmat.primitives import serialization private_key serialization.load_pem_private_key(data, passwordNone) public_key serialization.load_pem_public_key(data)其中load_pem_private_key、load_pem_public_key直接映射到 Rust 侧的密钥解析实现rust_openssl.keys.load_pem_private_key等而load_pem_parametersDH 参数映射到rust_openssl.dh.from_pem_parameters。这正是 FAQ为什么需要 Rust一节所述架构的具体体现PEM/ASN.1 解析已由 Rust 实现。backend 参数去哪了一个历史演进问题FAQ 记录了一次重要的 API 演进版本 3.1 起cryptography不再要求提供backend参数版本 36.0 起正式弃用backend参数如果你仍在使用旧版本且依赖该参数请查看对应版本的文档或直接升级到最新版。FAQ 特别说明出于向前兼容考虑backend仍会被静默接受——传了也不会报错但会被忽略且不再出现在文档中。因此在新代码中无需也不应再传递backend。非 x86 非 ARM64 架构为什么没有你的 CPU 的 wheelFAQ 坦诚回应了为什么不为我的 CPU 架构上传 wheel的问题上传到 PyPI 的 wheel 必须经过该架构上的完整 CI 测试每个 commit 都跑因为 cryptography 大量使用按架构优化的汇编代码将某架构纳入 CI 需要满足有能提供该架构构建、能集成进现有 workflow、容量足够且性能不拖累贡献者体验的 CI 提供方。FAQ 认为这不是不可逾越的门槛但也不轻松。若你希望支持新 CPU 架构欢迎联系项目组讨论并贡献支持——项目组会尽量配合但无法承诺亲自完成这项工作。总结FAQ 中的通用排错方法论纵观 docs/faq.rst可以提炼出一条通用的排错方法论先升级 pip 再重装——解决大多数 wheel 识别与源码构建误判问题区分项目 bug与环境问题——InternalError优先排查 OpenSSL 错误栈是否被其他库污染理解构建期依赖Rust、C 工具链、OpenSSL与运行期依赖的区别——构建时缺什么补什么运行时不需要 Rust校验输入格式——PEM 导入失败按 64 字符折行与头尾行规则逐条核对跟紧 API 演进——backend参数已弃用但可静默兼容新代码不要传遵循官方文档——Lambda、各发行版、Windows 编译等场景均有对应章节指引详见 docs/installation.rst。这套方法论配合仓库内的源码绑定层、Rust 解析器、序列化 API与测试如 tests/test_warnings.py 中对deprecated机制的验证足以应对绝大多数 cryptography 的日常使用与排障场景。赞分享密码学【免费下载链接】cryptographycryptography is a package designed to expose cryptographic primitives and recipes to Python developers.项目地址https://gitcode.com/gh_mirrors/cr/cryptography点击查看免费下载相关推荐Umi FAQ 实战指南从 polyfill、ESLint 到部署排错的常见问题全解Umi FAQ 实战指南从 polyfill、ESLint 到部署排错的常见问题全解 本文基于 docs/guide/faq.md https://link.前端开发工具Codex-X的自动故障转移是如何实现的本地127.0.0.1监听服务解析Codex X的自动故障转移是如何实现的本地127.0.0.1监听服务解析 Codex X 是 OpenAI Codex 桌面端/CLI 的可视化管理工桌面应用开发者工具AI 应用xLua 常见问题FAQ实战指南从安装部署、代码生成到热更新排错的全方位解答xLua 常见问题FAQ实战指南从安装部署、代码生成到热更新排错的全方位解答 xLua 是腾讯开源的一套基于 C Unity、.Net、Mono的 L游戏开发脚本语言集成上一篇终极ffmpeg-python视频增强指南AI超分辨率技术应用下一篇android-async-http容器化部署Docker集成测试创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考