密码学【免费下载链接】cryptographycryptography is a package designed to expose cryptographic primitives and recipes to Python developers.项目地址https://gitcode.com/gh_mirrors/cr/cryptography点击查看免费下载cryptography 是面向 Python 开发者的密码学工具包在其 docs/exceptions.rst 中系统定义了 6 个核心异常类型。本文将逐一讲解这些异常的触发场景、正确的捕获与处理方式并结合 src/cryptography/exceptions.py 的源码实现与仓库测试用例如 test_cmac.py、test_argon2.py深入剖析其底层原理帮助你在实际项目中写出健壮的密码学错误处理代码。异常模块总览cryptography.exceptions 的定位所有密码学相关异常统一收敛在cryptography.exceptions模块中由文档docs/exceptions.rst正式定义。在源码层面这些类定义于 src/cryptography/exceptions.py全部直接或间接继承自 Python 内置的Exception异常类继承关系一句话语义UnsupportedAlgorithmException请求的算法或算法组合不受支持AlreadyFinalizedException上下文context在 finalize 之后仍被继续使用InvalidSignatureException签名/消息认证码校验失败NotYetFinalizedException在 finalize 之前就访问了 AEAD 的 tag 属性AlreadyUpdatedException已调用过 update 之后又向上下文追加附加数据InvalidKeyExceptionKDF 验证方法计算出的密钥与期望密钥不匹配除了文档列出的这 6 类exceptions.py 还定义了InvalidTagAEAD 解密时 tag 校验失败与InternalError携带 OpenSSL 错误码的底层错误两个补充类型它们在文档未列出的场景中同样会从密码学操作中抛出。值得关注的是UnsupportedAlgorithm与InternalError是仅有的两个携带额外属性的异常UnsupportedAlgorithm构造函数接受message与可选的reason_Reasons | None并在实例上保存self._reasonInternalError保存err_code属性其中包含来自 Rust 侧 OpenSSL 绑定的错误列表list[rust_openssl.OpenSSLError]。理解UnsupportedAlgorithm算法与运行环境不匹配的信号UnsupportedAlgorithm是所有异常中出现频率最高、覆盖范围最广的一类它表示当前请求的算法或算法组合不受支持。需要强调的是它不代表你的代码写错了这类问题通常抛TypeError/ValueError而是代表运行时环境尤其是底层 OpenSSL 后端无法满足算法需求。从 Rust 侧看 reason 枚举在 src/cryptography/exceptions.py 中_Reasons直接复用自 Rust 侧实现_Reasons rust_exceptions._Reasons该枚举定义在 src/rust/src/exceptions.rs共包含 12 个成员可据此精确诊断哪种能力缺失reason 值含义BACKEND_MISSING_INTERFACE后端缺少所需接口UNSUPPORTED_HASH哈希算法不受支持UNSUPPORTED_CIPHER分组密码算法不受支持UNSUPPORTED_PADDING填充方案不受支持UNSUPPORTED_MGFMGF掩码生成函数不受支持UNSUPPORTED_PUBLIC_KEY_ALGORITHM公钥算法不受支持UNSUPPORTED_ELLIPTIC_CURVE椭圆曲线不受支持UNSUPPORTED_SERIALIZATION序列化格式不受支持UNSUPPORTED_X509X.509 功能不受支持UNSUPPORTED_EXCHANGE_ALGORITHM密钥交换算法不受支持UNSUPPORTED_DIFFIE_HELLMANDiffie-Hellman 参数不受支持UNSUPPORTED_MACMAC 算法不受支持从 src/rust/src/exceptions.rs 可以看到Rust 绑定通过pyo3::import_exception!直接引用 Python 侧的异常类确保底层 Rust 实现抛出的错误能原样映射回cryptography.exceptions保持异常类型的统一。典型触发路径模式与算法类型不匹配以分组密码模式校验为例src/cryptography/hazmat/primitives/_modes.py 中的_check_nonce_length明确展示了触发逻辑def _check_nonce_length(nonce, name, algorithm): if not isinstance(algorithm, BlockCipherAlgorithm): raise UnsupportedAlgorithm( f{name} requires a block cipher algorithm, _Reasons.UNSUPPORTED_CIPHER, ) if len(nonce) * 8 ! algorithm.block_size: raise ValueError(fInvalid nonce size ({len(nonce)}) for {name}.)同理modes.py 以及椭圆曲线、Ed448、ML-DSA、ML-KEM、X25519/X448 等模块参见 ec.py、mldsa.py、mlkem.py都会在算法不受后端支持时抛出UnsupportedAlgorithm。实战捕获建议由于该异常可能在任何初始化算法对象、或调用涉及后端能力的方法时抛出官方推荐在代码中显式捕获并降级处理from cryptography.exceptions import UnsupportedAlgorithm from cryptography.hazmat.primitives import hashes try: digest hashes.Hash(hashes.SHA3_512()) except UnsupportedAlgorithm: print(当前 OpenSSL 后端不支持 SHA3-512请升级或更换后端。)测试中同样如此——test_cmac.py 通过raises_unsupported_algorithm(_Reasons.UNSUPPORTED_CIPHER)精确断言了使用非分组密码算法构造 CMAC应抛出的异常与 reason。掌握两个状态机异常AlreadyFinalized 与 AlreadyUpdated密码学上下文对象如哈希、CMAC、HMAC、AEAD 加解密器普遍遵循可更新 → 终结 → 只读的状态机。AlreadyFinalized与AlreadyUpdated正是状态机违反时的哨兵。AlreadyFinalizedfinalize 之后的任何使用都是非法操作文档定义当上下文在终结finalized之后仍被使用时抛出。例如对已经finalize()的对象再次调用update()、finalize()、verify()或copy()。测试 test_cmac.py 完整展示了这一场景def test_raises_after_finalize(self): key b2b7e151628aed2a6abf7158809cf4f3c cmac CMAC(AES(key)) cmac.finalize() with pytest.raises(AlreadyFinalized): cmac.update(bfoo) with pytest.raises(AlreadyFinalized): cmac.copy() with pytest.raises(AlreadyFinalized): cmac.finalize() with pytest.raises(AlreadyFinalized): cmac.verify(b)同样的断言也遍布 test_aes.py、test_chacha20.py、test_block.py 等测试文件说明这是所有上下文型原语的统一约定。在 Rust 侧src/rust/src/exceptions.rs 提供了便捷的构造辅助pub(crate) fn already_finalized_error() - CryptographyError { CryptographyError::from(AlreadyFinalized::new_err(Context was already finalized.)) }实战要点捕获AlreadyFinalized通常意味着程序设计缺陷对已终结对象重复操作。合理做法是在业务层避免复用上下文对象如确有需要重新创建一个新对象。AlreadyUpdatedupdate 之后的二次数据追加文档定义**在已调用过 update 之后又向上下文添加附加数据additional data**时抛出。它保护的是那些只允许一次 update 之后不可再追加的上下文类型。其触发场景相对集中在特定的原语实现中属于较罕见的错误通常意味着调用方对接口语义理解有误——应当将全部数据一次性传入或改用支持流式多次 update 的接口。签名与密钥验证的失败信号InvalidSignature 与 InvalidKey这两个异常分别守护验证类操作的两条链路MAC/签名校验链路与 KDF 密钥校验链路。InvalidSignatureHMAC 或非对称签名验证失败文档定义签名验证失败时抛出可发生于 HMAC 或非对称密钥签名校验。它不携带任何附加信息源码中为空的pass类见 exceptions.py仅作为布尔判定的异常化表达。典型用法是CMAC.verify()from cryptography.hazmat.primitives.cmac import CMAC from cryptography.hazmat.primitives.ciphers.algorithms import AES from cryptography.exceptions import InvalidSignature cmac CMAC(AES(b2b7e151628aed2a6abf7158809cf4f3c)) cmac.update(b6bc1bee22e409f96e93d7e117393172a) try: cmac.verify(bfoobar) # 标签不匹配 except InvalidSignature: print(MAC 校验失败数据可能被篡改。)test_cmac.py 中的test_invalid_verify正是用pytest.raises(InvalidSignature)断言这一行为。HMACHMAC.verify()与 RSA/ECDSA/Ed25519 等非对称签名verify()在验证失败时同样抛出该异常。实战要点校验失败是预期内可恢复的错误可能源于篡改或传输损坏通常捕获后走重试、告警或拒绝流程而TypeError/ValueError才代表调用方自身的参数错误。InvalidKeyKDF 验证方法计算的密钥不匹配文档定义密钥派生函数KDF的 verify 方法计算出的密钥与期望密钥不匹配时抛出。其触发场景典型见于 Argon2 等密码哈希 KDF 的verify()调用。test_argon2.py 展示了相关断言且 test_argon2.py 中还存在matchdid you mean to use的提示性消息说明InvalidKey在部分实现中会携带帮助用户修正 API 用法的友好提示例如误把verify当hash使用时的引导信息。实战要点密码验证场景中InvalidKey表示口令错误应据此返回用户名或密码错误之类的统一响应避免向攻击者泄露账户存在性。容易被忽略的 NotYetFinalizedAEAD tag 的时序保护文档定义在上下文尚未终结finalized时就访问 AEAD 的 tag 属性时抛出。这是 AEAD如 AES-GCM、ChaCha20-Poly1305特有的时序约束——tag 只有在finalize()之后才存在提前读取是非法操作。这一设计的正确用法是先终结、再取 tagfrom cryptography.hazmat.primitives.ciphers.aead import AESGCM aesgcm AESGCM(key) ct aesgcm.encrypt(nonce, data, None) # 直接返回密文tag一步完成 # 若使用分步 API如 Cipher 上下文则必须先 finalize 再读取 tag捕获NotYetFinalized通常意味着流程编排错误忘记调用finalize()属于编程缺陷而非外部攻击信号。完整实践一段涵盖多类异常的错误处理模板综合上述语义给出一个可落地的统一错误处理范式from cryptography.exceptions import ( AlreadyFinalized, AlreadyUpdated, InvalidKey, InvalidSignature, NotYetFinalized, UnsupportedAlgorithm, ) def safe_verify(data, tag, cmac): try: cmac.update(data) cmac.verify(tag) return True except InvalidSignature: return False # 校验失败可恢复 except AlreadyFinalized: cmac new_cmac() # 编程缺陷重建上下文后重试 return safe_verify(data, tag, cmac) except AlreadyUpdated: raise ValueError(数据必须一次性传入) from None except UnsupportedAlgorithm as e: print(f后端不支持该算法: {e._reason}) return None总结与最佳实践清单按语义分类处理UnsupportedAlgorithm反映环境能力缺失可升级 OpenSSL 或换后端InvalidSignature/InvalidKey是验证失败可恢复的业务结果AlreadyFinalized/AlreadyUpdated/NotYetFinalized是状态机违规编程缺陷应修复调用逻辑。善用 reason 属性捕获UnsupportedAlgorithm后读取_reason_Reasons枚举的 12 个成员见 exceptions.rs可向用户给出精确的缺失能力提示。统一从cryptography.exceptions导入所有异常类型均在该模块中定义exceptions.pyRust 侧实现也通过pyo3::import_exception!回指该模块保证类型一致。用测试固化行为仓库测试如 test_cmac.py、test_argon2.py、test_aes.py对每个异常都有精确断言可作为自己代码中pytest.raises断言的参照模板。赞分享密码学【免费下载链接】cryptographycryptography is a package designed to expose cryptographic primitives and recipes to Python developers.项目地址https://gitcode.com/gh_mirrors/cr/cryptography点击查看免费下载相关推荐Scrapy 异常体系全解CloseSpider、DropItem、IgnoreRequest 等核心异常的用法与源码级原理Scrapy 异常体系全解CloseSpider、DropItem、IgnoreRequest 等核心异常的用法与源码级原理 导读 本文以 docs/topi网页爬虫后端Streamlink 异常体系全解从 StreamlinkError 到 CDPError 的源码级剖析Streamlink 异常体系全解从 StreamlinkError 到 CDPError 的源码级剖析 Streamlink 的异常体系是整个项目错误处理的音视频Salt 异常体系全解析读懂 salt.exceptions 源码与异常处理实践Salt 异常体系全解析读懂 salt.exceptions 源码与异常处理实践 SaltSaltStack把全部自定义异常集中定义在 salt/exce运维配置管理后端上一篇react-dates性能优化useCallback与事件处理下一篇GitHub项目创新指标Badges4-README.md-Profile技术创新徽章创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
cryptography 异常体系详解：UnsupportedAlgorithm、AlreadyFinalized 等内置异常的使用与源码剖析
密码学【免费下载链接】cryptographycryptography is a package designed to expose cryptographic primitives and recipes to Python developers.项目地址https://gitcode.com/gh_mirrors/cr/cryptography点击查看免费下载cryptography 是面向 Python 开发者的密码学工具包在其 docs/exceptions.rst 中系统定义了 6 个核心异常类型。本文将逐一讲解这些异常的触发场景、正确的捕获与处理方式并结合 src/cryptography/exceptions.py 的源码实现与仓库测试用例如 test_cmac.py、test_argon2.py深入剖析其底层原理帮助你在实际项目中写出健壮的密码学错误处理代码。异常模块总览cryptography.exceptions 的定位所有密码学相关异常统一收敛在cryptography.exceptions模块中由文档docs/exceptions.rst正式定义。在源码层面这些类定义于 src/cryptography/exceptions.py全部直接或间接继承自 Python 内置的Exception异常类继承关系一句话语义UnsupportedAlgorithmException请求的算法或算法组合不受支持AlreadyFinalizedException上下文context在 finalize 之后仍被继续使用InvalidSignatureException签名/消息认证码校验失败NotYetFinalizedException在 finalize 之前就访问了 AEAD 的 tag 属性AlreadyUpdatedException已调用过 update 之后又向上下文追加附加数据InvalidKeyExceptionKDF 验证方法计算出的密钥与期望密钥不匹配除了文档列出的这 6 类exceptions.py 还定义了InvalidTagAEAD 解密时 tag 校验失败与InternalError携带 OpenSSL 错误码的底层错误两个补充类型它们在文档未列出的场景中同样会从密码学操作中抛出。值得关注的是UnsupportedAlgorithm与InternalError是仅有的两个携带额外属性的异常UnsupportedAlgorithm构造函数接受message与可选的reason_Reasons | None并在实例上保存self._reasonInternalError保存err_code属性其中包含来自 Rust 侧 OpenSSL 绑定的错误列表list[rust_openssl.OpenSSLError]。理解UnsupportedAlgorithm算法与运行环境不匹配的信号UnsupportedAlgorithm是所有异常中出现频率最高、覆盖范围最广的一类它表示当前请求的算法或算法组合不受支持。需要强调的是它不代表你的代码写错了这类问题通常抛TypeError/ValueError而是代表运行时环境尤其是底层 OpenSSL 后端无法满足算法需求。从 Rust 侧看 reason 枚举在 src/cryptography/exceptions.py 中_Reasons直接复用自 Rust 侧实现_Reasons rust_exceptions._Reasons该枚举定义在 src/rust/src/exceptions.rs共包含 12 个成员可据此精确诊断哪种能力缺失reason 值含义BACKEND_MISSING_INTERFACE后端缺少所需接口UNSUPPORTED_HASH哈希算法不受支持UNSUPPORTED_CIPHER分组密码算法不受支持UNSUPPORTED_PADDING填充方案不受支持UNSUPPORTED_MGFMGF掩码生成函数不受支持UNSUPPORTED_PUBLIC_KEY_ALGORITHM公钥算法不受支持UNSUPPORTED_ELLIPTIC_CURVE椭圆曲线不受支持UNSUPPORTED_SERIALIZATION序列化格式不受支持UNSUPPORTED_X509X.509 功能不受支持UNSUPPORTED_EXCHANGE_ALGORITHM密钥交换算法不受支持UNSUPPORTED_DIFFIE_HELLMANDiffie-Hellman 参数不受支持UNSUPPORTED_MACMAC 算法不受支持从 src/rust/src/exceptions.rs 可以看到Rust 绑定通过pyo3::import_exception!直接引用 Python 侧的异常类确保底层 Rust 实现抛出的错误能原样映射回cryptography.exceptions保持异常类型的统一。典型触发路径模式与算法类型不匹配以分组密码模式校验为例src/cryptography/hazmat/primitives/_modes.py 中的_check_nonce_length明确展示了触发逻辑def _check_nonce_length(nonce, name, algorithm): if not isinstance(algorithm, BlockCipherAlgorithm): raise UnsupportedAlgorithm( f{name} requires a block cipher algorithm, _Reasons.UNSUPPORTED_CIPHER, ) if len(nonce) * 8 ! algorithm.block_size: raise ValueError(fInvalid nonce size ({len(nonce)}) for {name}.)同理modes.py 以及椭圆曲线、Ed448、ML-DSA、ML-KEM、X25519/X448 等模块参见 ec.py、mldsa.py、mlkem.py都会在算法不受后端支持时抛出UnsupportedAlgorithm。实战捕获建议由于该异常可能在任何初始化算法对象、或调用涉及后端能力的方法时抛出官方推荐在代码中显式捕获并降级处理from cryptography.exceptions import UnsupportedAlgorithm from cryptography.hazmat.primitives import hashes try: digest hashes.Hash(hashes.SHA3_512()) except UnsupportedAlgorithm: print(当前 OpenSSL 后端不支持 SHA3-512请升级或更换后端。)测试中同样如此——test_cmac.py 通过raises_unsupported_algorithm(_Reasons.UNSUPPORTED_CIPHER)精确断言了使用非分组密码算法构造 CMAC应抛出的异常与 reason。掌握两个状态机异常AlreadyFinalized 与 AlreadyUpdated密码学上下文对象如哈希、CMAC、HMAC、AEAD 加解密器普遍遵循可更新 → 终结 → 只读的状态机。AlreadyFinalized与AlreadyUpdated正是状态机违反时的哨兵。AlreadyFinalizedfinalize 之后的任何使用都是非法操作文档定义当上下文在终结finalized之后仍被使用时抛出。例如对已经finalize()的对象再次调用update()、finalize()、verify()或copy()。测试 test_cmac.py 完整展示了这一场景def test_raises_after_finalize(self): key b2b7e151628aed2a6abf7158809cf4f3c cmac CMAC(AES(key)) cmac.finalize() with pytest.raises(AlreadyFinalized): cmac.update(bfoo) with pytest.raises(AlreadyFinalized): cmac.copy() with pytest.raises(AlreadyFinalized): cmac.finalize() with pytest.raises(AlreadyFinalized): cmac.verify(b)同样的断言也遍布 test_aes.py、test_chacha20.py、test_block.py 等测试文件说明这是所有上下文型原语的统一约定。在 Rust 侧src/rust/src/exceptions.rs 提供了便捷的构造辅助pub(crate) fn already_finalized_error() - CryptographyError { CryptographyError::from(AlreadyFinalized::new_err(Context was already finalized.)) }实战要点捕获AlreadyFinalized通常意味着程序设计缺陷对已终结对象重复操作。合理做法是在业务层避免复用上下文对象如确有需要重新创建一个新对象。AlreadyUpdatedupdate 之后的二次数据追加文档定义**在已调用过 update 之后又向上下文添加附加数据additional data**时抛出。它保护的是那些只允许一次 update 之后不可再追加的上下文类型。其触发场景相对集中在特定的原语实现中属于较罕见的错误通常意味着调用方对接口语义理解有误——应当将全部数据一次性传入或改用支持流式多次 update 的接口。签名与密钥验证的失败信号InvalidSignature 与 InvalidKey这两个异常分别守护验证类操作的两条链路MAC/签名校验链路与 KDF 密钥校验链路。InvalidSignatureHMAC 或非对称签名验证失败文档定义签名验证失败时抛出可发生于 HMAC 或非对称密钥签名校验。它不携带任何附加信息源码中为空的pass类见 exceptions.py仅作为布尔判定的异常化表达。典型用法是CMAC.verify()from cryptography.hazmat.primitives.cmac import CMAC from cryptography.hazmat.primitives.ciphers.algorithms import AES from cryptography.exceptions import InvalidSignature cmac CMAC(AES(b2b7e151628aed2a6abf7158809cf4f3c)) cmac.update(b6bc1bee22e409f96e93d7e117393172a) try: cmac.verify(bfoobar) # 标签不匹配 except InvalidSignature: print(MAC 校验失败数据可能被篡改。)test_cmac.py 中的test_invalid_verify正是用pytest.raises(InvalidSignature)断言这一行为。HMACHMAC.verify()与 RSA/ECDSA/Ed25519 等非对称签名verify()在验证失败时同样抛出该异常。实战要点校验失败是预期内可恢复的错误可能源于篡改或传输损坏通常捕获后走重试、告警或拒绝流程而TypeError/ValueError才代表调用方自身的参数错误。InvalidKeyKDF 验证方法计算的密钥不匹配文档定义密钥派生函数KDF的 verify 方法计算出的密钥与期望密钥不匹配时抛出。其触发场景典型见于 Argon2 等密码哈希 KDF 的verify()调用。test_argon2.py 展示了相关断言且 test_argon2.py 中还存在matchdid you mean to use的提示性消息说明InvalidKey在部分实现中会携带帮助用户修正 API 用法的友好提示例如误把verify当hash使用时的引导信息。实战要点密码验证场景中InvalidKey表示口令错误应据此返回用户名或密码错误之类的统一响应避免向攻击者泄露账户存在性。容易被忽略的 NotYetFinalizedAEAD tag 的时序保护文档定义在上下文尚未终结finalized时就访问 AEAD 的 tag 属性时抛出。这是 AEAD如 AES-GCM、ChaCha20-Poly1305特有的时序约束——tag 只有在finalize()之后才存在提前读取是非法操作。这一设计的正确用法是先终结、再取 tagfrom cryptography.hazmat.primitives.ciphers.aead import AESGCM aesgcm AESGCM(key) ct aesgcm.encrypt(nonce, data, None) # 直接返回密文tag一步完成 # 若使用分步 API如 Cipher 上下文则必须先 finalize 再读取 tag捕获NotYetFinalized通常意味着流程编排错误忘记调用finalize()属于编程缺陷而非外部攻击信号。完整实践一段涵盖多类异常的错误处理模板综合上述语义给出一个可落地的统一错误处理范式from cryptography.exceptions import ( AlreadyFinalized, AlreadyUpdated, InvalidKey, InvalidSignature, NotYetFinalized, UnsupportedAlgorithm, ) def safe_verify(data, tag, cmac): try: cmac.update(data) cmac.verify(tag) return True except InvalidSignature: return False # 校验失败可恢复 except AlreadyFinalized: cmac new_cmac() # 编程缺陷重建上下文后重试 return safe_verify(data, tag, cmac) except AlreadyUpdated: raise ValueError(数据必须一次性传入) from None except UnsupportedAlgorithm as e: print(f后端不支持该算法: {e._reason}) return None总结与最佳实践清单按语义分类处理UnsupportedAlgorithm反映环境能力缺失可升级 OpenSSL 或换后端InvalidSignature/InvalidKey是验证失败可恢复的业务结果AlreadyFinalized/AlreadyUpdated/NotYetFinalized是状态机违规编程缺陷应修复调用逻辑。善用 reason 属性捕获UnsupportedAlgorithm后读取_reason_Reasons枚举的 12 个成员见 exceptions.rs可向用户给出精确的缺失能力提示。统一从cryptography.exceptions导入所有异常类型均在该模块中定义exceptions.pyRust 侧实现也通过pyo3::import_exception!回指该模块保证类型一致。用测试固化行为仓库测试如 test_cmac.py、test_argon2.py、test_aes.py对每个异常都有精确断言可作为自己代码中pytest.raises断言的参照模板。赞分享密码学【免费下载链接】cryptographycryptography is a package designed to expose cryptographic primitives and recipes to Python developers.项目地址https://gitcode.com/gh_mirrors/cr/cryptography点击查看免费下载相关推荐Scrapy 异常体系全解CloseSpider、DropItem、IgnoreRequest 等核心异常的用法与源码级原理Scrapy 异常体系全解CloseSpider、DropItem、IgnoreRequest 等核心异常的用法与源码级原理 导读 本文以 docs/topi网页爬虫后端Streamlink 异常体系全解从 StreamlinkError 到 CDPError 的源码级剖析Streamlink 异常体系全解从 StreamlinkError 到 CDPError 的源码级剖析 Streamlink 的异常体系是整个项目错误处理的音视频Salt 异常体系全解析读懂 salt.exceptions 源码与异常处理实践Salt 异常体系全解析读懂 salt.exceptions 源码与异常处理实践 SaltSaltStack把全部自定义异常集中定义在 salt/exce运维配置管理后端上一篇react-dates性能优化useCallback与事件处理下一篇GitHub项目创新指标Badges4-README.md-Profile技术创新徽章创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
