必须用Paragonie的crypto_aead等封装函数而非仅random_bytes()，因其自动处理nonce生成、验证等易错环节；密钥须用sodium_crypto_pwhash派生或random_bytes(32)生成；解密失败静默返回false，需手动检查并双重判断。
为什么不能直接用 random_bytes() 就完事？
PHP 7.0+ 确实自带 random_bytes()，但它只是“安全随机字节生成器”，不等于“加密功能封装”。Paragonie 的 crypto<em>aead</em><em></em>、crypto<em>secretbox</em> 等函数才是开箱即用的 AEAD 加密原语——它们自动处理 nonce 生成、验证、填充、密钥派生等易出错环节。
常见错误现象：hash_hmac() + openssl_encrypt() 手动拼凑，结果 nonce 重用、验证缺失、密文被篡改后仍解密成功。
使用场景：需要端到端保密性 + 完整性（比如用户敏感配置、API token payload、数据库字段加密）。
- 必须用
ParagonIE_Sodium<em>Compat</em>或原生sodium*()，别自己实现 HKDF 或 CBC 模式 -
random_bytes(24)生成的 nonce 不能复用，每次加密必须新取 - 如果用
crypto_secretbox()，解密失败时返回false，不是抛异常，得手动检查
use ParagonIE\Sodium\Core\Compat; $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES); $ciphertext = sodium_crypto_secretbox($message, $nonce, $key);
sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() 怎么选参数？
这是目前最推荐的 AEAD 函数，比 crypto_secretbox() 更安全（XChaCha20 抗侧信道，Poly1305 验证强），且支持附加数据（AD）——比如你不想加密但要绑定验证的请求 ID、时间戳。
立即学习“PHP免费学习笔记（深入）”；
参数差异：
- 第 1 个参数是明文（
$message），必须是string，不能是null或数组 - 第 2 个参数是附加数据（
$ad），可为null或空字符串；若传入，解密时必须提供完全相同的值，否则验证失败 - 第 3 个参数是 nonce，长度必须严格为
SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES（24 字节） - 第 4 个参数是密钥，长度必须为
SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES（32 字节）
性能影响：比 AES-GCM 在 PHP 中略慢，但差距可忽略；兼容性上，ParagonIE_Sodium_Compat 能 fallback 到纯 PHP 实现，无需扩展启用。
密钥从哪来？别用 md5('password') 或 openssl_random_pseudo_bytes()
密钥不是密码。它必须是密码学安全的、固定长度的随机字节，且永远不暴露、不推导、不复用。
常见错误现象：用用户密码直接当密钥、用时间戳拼接后 hash、把密钥硬编码在 config.php 里。
- 密钥应由
random_bytes(32)生成，存于环境变量或密钥管理服务（如 HashiCorp Vault） - 若需从密码派生密钥，必须用
sodium_crypto_pwhash()（不是password_hash()），指定 opslimit/memorylimit - 不要用
openssl_random_pseudo_bytes()：它已废弃，且在某些系统上 fallback 不安全
$key = sodium_crypto_pwhash(
SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES,
$password,
$salt,
SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
);解密失败只返回 false，怎么定位是哪一步崩了？
sodium_crypto<em>aead</em>*_decrypt() 和 sodium_crypto_secretbox_open() 在验证失败、nonce 错、密钥错、密文损坏时，全部静默返回 false —— 这是设计使然，防止时序攻击和 oracle 攻击。
容易踩的坑：没检查返回值，直接 json_decode($decrypted)，结果传入 null 导致后续逻辑崩溃，错误日志里却只看到 “JSON decode error”，根本看不出是加密层问题。
- 解密后必须用
is_string($decrypted) && $decrypted !== false双重判断 - 如果业务允许，可在加密时附带版本号（如
"v1:".$ciphertext），解密后先验版本再处理，避免格式升级导致的静默失败 - 日志里记录「解密失败」即可，不要记录 nonce 或密文片段（哪怕截断），防止密钥材料泄露
事情说清了就结束。真正难的不是调哪个函数，而是记住：nonce 要唯一、密钥要隔离、验证失败不报错、所有输入输出都当不可信数据处理。
