PyCryptodome的AES-CBC加密必须用Crypto.Util.Padding.pad/unpad做PKCS#7填充，IV须随机且与密文拼接传输，密钥长度须严格校验，解密失败需按错误类型精准处理。
PyCryptodome 的 AES 加密必须用 PKCS7 填充，别手写 padding
很多接口文档只写“AES-128-CBC”，但没说填充方式，直接用 encrypt() 会报 ValueError: Data must be padded to block boundary。PyCryptodome 不自动填充，你得自己补 —— 但千万别用 while 循环手动加 \x04 这种土法。
正确做法是用 pad() 和 unpad()（来自 Crypto.Util.Padding），它们严格遵循 PKCS#7 标准，且能处理边界情况（比如明文长度刚好是块长整数倍）：
from Crypto.Cipher import AES
from Crypto.Util.Padding import pad, unpad
from Crypto.Random import get_random_bytes
<p>key = b'16bytekey12345678'
iv = get_random_bytes(16)
cipher = AES.new(key, AES.MODE_CBC, iv)</p><p>data = b'{"id":123,"ts":1712345678}'
padded = pad(data, AES.block_size) # 自动补到 16 字节对齐
ciphertext = cipher.encrypt(padded)
</p>
- 填充必须在加密前做，解密后立刻
unpad()，顺序错一步就会解出乱码 - 如果接口要求“不填充”，那大概率是用了 ZeroPadding 或 NoPadding —— 此时得确认对方是否真没填充，还是只是没写清楚
- 别用
PKCS5模块：PyCryptodome 里没有独立的 PKCS5，pad(..., style='pkcs7')是唯一标准接口
IV 必须随密文一起传，但不能固定或硬编码
常见错误是把 iv = b'1234567890123456' 写死，导致相同明文每次加密结果一样，攻击者可重放、可字典比对。接口加解密要求 IV 随机且每次不同，但接收方又必须知道它 —— 所以常规做法是把 IV 拼在密文前面（比如前 16 字节），再 base64 编码整个结果。
解密时先切出前 16 字节当 IV，剩下的是密文：
import base64 <h1>加密端</h1><p>iv = get_random_bytes(16) cipher = AES.new(key, AES.MODE_CBC, iv) ciphertext = cipher.encrypt(pad(data, AES.block_size))</p><h1>拼接 IV + 密文，再编码</h1><p>encoded = base64.b64encode(iv + ciphertext).decode()</p><h1>解密端</h1><p>raw = base64.b64decode(encoded) iv = raw[:16] ciphertext = raw[16:] cipher = AES.new(key, AES.MODE_CBC, iv) plaintext = unpad(cipher.decrypt(ciphertext), AES.block_size) </p>
- IV 不需要保密，但必须不可预测；
get_random_bytes()是安全的，os.urandom()也可，但别用random.randint() - 有些接口要求 IV 单独传字段（如
iv参数），那就按字段传，别塞进密文里 - 如果发现解密后开头几个字节是乱码，八成是 IV 没对上 —— 检查是不是少取了字节，或 base64 解码失败
密钥长度不对会静默失败，必须严格校验
PyCryptodome 对 AES 密钥长度很敏感：AES-128 要 16 字节，AES-192 要 24 字节，AES-256 要 32 字节。传入 17 字节的 key 不会报错，而是截断或报 ValueError: Invalid key size，取决于底层实现和版本。
更隐蔽的问题是：接口给的密钥可能是 hex 字符串或 base64，你直接 .encode() 就错了：
- 接口给
"abcd1234ef567890"（32 位 hex）→ 要用bytes.fromhex()转成 16 字节 - 接口给
"YWJjZDEyMzRlZjU2Nzg5MA=="→ 用base64.b64decode() - 绝不能对字符串直接
key.encode()，除非明确文档说“用 UTF-8 字节当密钥”
建议加一层校验：
def validate_aes_key(key: bytes, bits: int = 128) -> None:
expected_len = bits // 8
if len(key) != expected_len:
raise ValueError(f"AES-{bits} key must be {expected_len} bytes, got {len(key)}")
<h1>使用前调用</h1><p>validate_aes_key(key, 128)
</p>
解密失败时别只捕获 Exception，要区分具体错误类型
解密出错常被笼统 catch 住，然后返回空或默认值，掩盖了真实问题。实际可能有三类典型错误：
-
ValueError: Padding is incorrect→ 明文被篡改、IV 错、或 padding 方式不匹配（比如对方用 ZeroPadding，你用 PKCS7） -
ValueError: MAC check failed→ 如果用了 AES-GCM 模式，认证失败说明密文被改过 -
UnicodeDecodeError→unpad()成功，但解码 JSON 失败，说明原始数据不是 UTF-8，或加解密过程某步损坏了字节
建议按错误类型分路径处理：
try:
plaintext = unpad(cipher.decrypt(ciphertext), AES.block_size)
return json.loads(plaintext.decode('utf-8'))
except ValueError as e:
if "Padding" in str(e):
raise DecryptionError("Invalid padding — IV or key mismatch") from e
raise
except json.JSONDecodeError:
raise DecryptionError("Decrypted data is not valid JSON") from e
真正难调试的是 padding 错误 —— 它不告诉你哪一步错了，只能靠对比 IV、key、mode、padding 四要素逐个排除。别跳过这一步。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
