4. PyCryptodome 库核心模块调用方法

PyCryptodome 是 Python 生态中最成熟、维护最活跃的密码学库之一，提供了从底层原语到高层协议的全栈支持。本章聚焦其四大核心模块——Cipher、Hash、Signature、Protocol，通过调用示例与调试要点，帮助你在安全通信场景中正确组合这些模块。

4.1 模块架构总览

PyCryptodome 的模块设计遵循分层原则：底层原语（Cipher、Hash）为上层协议（Signature、Protocol）提供基础运算，而 Protocol 模块则封装了常见的通信安全模式。下图展示了四个模块之间的依赖与调用关系：

4.2 Cipher 模块：对称与非对称加密

Cipher 模块是 PyCryptodome 的加密核心，支持对称加密（AES、ChaCha20）和非对称加密（RSA、ECC）。所有加密操作遵循统一的 三步调用模式：创建密码对象 → 设置模式与参数 → 执行加密/解密。

4.2.1 对称加密：AES-GCM 示例

AES-GCM 是当前最推荐的身份认证加密模式，同时提供机密性、完整性和真实性。以下代码演示了加密与解密的完整流程：

from Cryptodome.Cipher import AES
from Cryptodome.Random import get_random_bytes

# 加密方
key = get_random_bytes(32)          # AES-256 密钥
nonce = get_random_bytes(12)        # GCM 推荐 12 字节 nonce
cipher = AES.new(key, AES.MODE_GCM, nonce=nonce)
plaintext = b"Hello, secure world!"
ciphertext, tag = cipher.encrypt_and_digest(plaintext)

# 解密方
cipher_dec = AES.new(key, AES.MODE_GCM, nonce=nonce)
try:
    decrypted = cipher_dec.decrypt_and_verify(ciphertext, tag)
    print("解密成功:", decrypted.decode())
except (ValueError, KeyError) as e:
    print("认证失败，数据被篡改:", e)

4.2.2 非对称加密：RSA-OAEP 示例

RSA-OAEP 是 RSA 加密的标准填充方案，可有效防止选择密文攻击。调用时需注意密钥格式与填充参数：

from Cryptodome.PublicKey import RSA
from Cryptodome.Cipher import PKCS1_OAEP

# 生成密钥对
key = RSA.generate(2048)
private_key = key.export_key()
public_key = key.publickey().export_key()

# 加密（使用公钥）
recipient_key = RSA.import_key(public_key)
cipher_rsa = PKCS1_OAEP.new(recipient_key)
ciphertext = cipher_rsa.encrypt(b"Short secret message")

# 解密（使用私钥）
private_key_import = RSA.import_key(private_key)
cipher_rsa_dec = PKCS1_OAEP.new(private_key_import)
plaintext = cipher_rsa_dec.decrypt(ciphertext)

4.3 Hash 模块：消息摘要与扩展

Hash 模块提供标准哈希函数（SHA-2、SHA-3、BLAKE2）以及消息认证码（HMAC）。所有哈希对象遵循 更新-摘要 模式，支持增量计算。

4.3.1 标准哈希调用

from Cryptodome.Hash import SHA256

h = SHA256.new()
h.update(b"First part of data")
h.update(b"Second part of data")
digest = h.digest()       # 32 字节二进制摘要
hex_digest = h.hexdigest()  # 64 字符十六进制字符串

4.3.2 HMAC 消息认证码

from Cryptodome.Hash import HMAC, SHA256

secret = b"shared-secret-key"
message = b"authenticate this"
hmac_obj = HMAC.new(secret, digestmod=SHA256)
hmac_obj.update(message)
mac = hmac_obj.digest()

# 验证端
try:
    hmac_obj.verify(mac)
    print("HMAC 验证通过")
except ValueError:
    print("HMAC 不匹配")

4.4 Signature 模块：数字签名与验证

Signature 模块封装了数字签名算法（DSA、RSA-PSS、ECDSA）。签名操作需要私钥，验证操作使用公钥。核心流程为：哈希消息 → 签名/验证。

4.4.1 RSA-PSS 签名与验证

from Cryptodome.PublicKey import RSA
from Cryptodome.Signature import pss
from Cryptodome.Hash import SHA256

# 签名方
key = RSA.generate(2048)
h = SHA256.new(b"Message to sign")
signer = pss.new(key)
signature = signer.sign(h)

# 验证方
h_verify = SHA256.new(b"Message to sign")
verifier = pss.new(key.publickey())
try:
    verifier.verify(h_verify, signature)
    print("签名验证成功")
except (ValueError, TypeError):
    print("签名无效")

4.5 Protocol 模块：密钥派生与安全协议

Protocol 模块提供高级密码协议，包括密钥派生函数（KDF）、密钥协商、秘密共享等。这些函数封装了复杂的底层运算，是构建安全通信系统的关键。

4.5.1 KDF：PBKDF2 与 scrypt

PBKDF2 和 scrypt 用于从密码派生加密密钥，增加暴力破解成本：

from Cryptodome.Protocol.KDF import PBKDF2, scrypt

password = b"user_password"
salt = b"unique_salt_value"

# PBKDF2（推荐用于兼容性）
key1 = PBKDF2(password, salt, dkLen=32, count=100000)

# scrypt（抗硬件加速，更安全）
key2 = scrypt(password, salt, key_len=32, N=2**14, r=8, p=1)

4.5.2 秘密共享：Shamir 算法

Shamir 秘密共享将密钥拆分为多个份额，只有达到阈值数量的份额才能恢复原密钥：

from Cryptodome.Protocol.SecretSharing import Shamir

# 拆分：5 个份额，任意 3 个可恢复
shares = Shamir.split(3, 5, b"my-secret-key-32bytes!")
for idx, share in shares:
    print(f"份额 {idx}: {share.hex()}")

# 恢复：使用前 3 个份额
recovered = Shamir.combine(shares[:3])
print("恢复密钥:", recovered)

4.6 模块组合调用：数字信封示例

数字信封是安全通信的经典模式，结合了非对称加密（保护对称密钥）和对称加密（保护数据）。下图展示了完整的调用流程：

# 数字信封完整实现（伪代码结构）
from Cryptodome.Cipher import AES, PKCS1_OAEP
from Cryptodome.PublicKey import RSA
from Cryptodome.Signature import pss
from Cryptodome.Hash import SHA256
from Cryptodome.Random import get_random_bytes

# 发送方
sym_key = get_random_bytes(32)
cipher_aes = AES.new(sym_key, AES.MODE_GCM)
ciphertext, tag = cipher_aes.encrypt_and_digest(data)

cipher_rsa = PKCS1_OAEP.new(recipient_pubkey)
encrypted_key = cipher_rsa.encrypt(sym_key)

h = SHA256.new(ciphertext + tag)
signature = pss.new(sender_privkey).sign(h)

# 接收方
sym_key_dec = PKCS1_OAEP.new(recipient_privkey).decrypt(encrypted_key)
cipher_aes_dec = AES.new(sym_key_dec, AES.MODE_GCM, nonce=cipher_aes.nonce)
plaintext = cipher_aes_dec.decrypt_and_verify(ciphertext, tag)

h_verify = SHA256.new(ciphertext + tag)
pss.new(sender_pubkey).verify(h_verify, signature)

4.7 调试常见问题速查表