一、问题现象与背景
在使用Python的pycryptodome库进行流加密时，开发者经常遇到如下错误提示：
ValueError: Key must be 16 or 32 bytes long这个错误发生在调用ChaCha20.new()方法时，表明传入的密钥参数不符合算法要求。ChaCha20作为现代流加密算法，对密钥长度有严格规定，必须为128位(16字节)或256位(32字节)。
二、问题根源分析
经过对源码的深入分析，我们发现该错误主要源于以下几个场景：
- 用户生成密钥时使用了不安全的随机方法（如
os.urandom(24)） - 从配置文件中读取的密钥被错误截断或编码转换
- 使用密码派生函数（如PBKDF2）时未设置正确的输出长度
- 跨平台传输密钥时发生了编码错误
三、解决方案与代码示例
1. 正确生成随机密钥
from Crypto.Random import get_random_bytes
# 生成32字节（256位）密钥
key = get_random_bytes(32)
cipher = ChaCha20.new(key=key)2. 处理已有密钥的规范化
对于已有但长度不符的密钥，建议使用HKDF进行规范化：
from Crypto.Protocol.KDF import HKDF
original_key = b"my_password" # 示例短密钥
key = HKDF(original_key, 32, salt=None, hashmod=SHA256)
3. 完整的加密解密示例
from Crypto.Cipher import ChaCha20
from Crypto.Random import get_random_bytes
# 加密流程
key = get_random_bytes(32)
nonce = get_random_bytes(12)
cipher = ChaCha20.new(key=key, nonce=nonce)
ciphertext = cipher.encrypt(b"Secret message")
# 解密流程
cipher = ChaCha20.new(key=key, nonce=nonce)
plaintext = cipher.decrypt(ciphertext)四、最佳实践建议
- 始终使用256位密钥以获得最高安全性
- 为每次加密生成唯一的nonce（12字节随机数）
- 考虑使用
ChaCha20_Poly1305实现认证加密 - 密钥存储应采用专门的密钥管理系统
- 在Web应用中通过环境变量传递密钥
五、性能优化技巧
当处理大文件时，建议采用分块处理模式：
chunk_size = 1024 * 1024 # 1MB
with open("large_file.bin", "rb") as f:
while chunk := f.read(chunk_size):
encrypted_chunk = cipher.encrypt(chunk)
# 处理加密块...六、安全注意事项
开发者需要特别注意：
- 绝对不要重复使用nonce+key组合
- 避免在客户端JavaScript中实现相同逻辑
- 定期轮换加密密钥
- 考虑使用硬件安全模块(HSM)保护主密钥