libsodium 必须在所有加密操作前调用 sodium_init()，否则多数情况崩溃或静默失败；推荐程序启动时 main() 开头调用一次，它线程安全且仅首次生效。
libsodium 初始化必须在所有加密操作前调用
不初始化就直接用 sodium_init() 以外的函数（比如 crypto_secretbox_easy()），多数情况下会崩溃或返回错误，但不是总报错——有些平台静默失败，导致密文解不开却查不出原因。
-
sodium_init()是线程安全的，可以多次调用，但只首次真正初始化；建议在程序启动时尽早调用一次，比如main()开头 - 不要在每次加解密前重复调用，它内部有开销（如检测 CPU 指令集、初始化随机数生成器）
- 如果使用静态链接的 libsodium，某些旧版 macOS 或嵌入式环境可能因缺少
/dev/urandom而卡住，此时需提前设置sodium_set_misuse_handler()捕获异常
对称加密选 crypto_secretbox 还是 crypto_aead_aes256gcm
别默认选 AES-GCM：libsodium 默认推荐 crypto_secretbox（XSalsa20-Poly1305），它更轻量、常数时间、无硬件依赖，且在绝大多数场景下足够安全。
-
crypto_secretbox_easy()适合大多数应用：传入密钥（crypto_secretbox_KEYBYTES字节）、nonce（crypto_secretbox_NONCEBYTES字节）、明文，输出带认证标签的密文 -
crypto_aead_aes256gcm_encrypt()仅当你需要与外部系统（如 TLS、Java Bouncy Castle）互操作，且明确要求 AES-GCM 时才用；它依赖 OpenSSL 或硬件 AES 指令，可移植性差 - nonce 绝对不能重用：对同一密钥，每个 nonce 必须唯一；建议用
randombytes_buf()生成，别手写递增计数器（容易溢出或跨进程冲突）
密钥管理不能靠硬编码或字符串字面量
把密钥写成 "my-super-secret-key-123" 这种字符串，等于没加密。libsodium 不负责密钥派生，你得自己处理。
C++ Code Review Master
下载
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
- 用户口令 → 密钥：必须用
crypto_pwhash()（如crypto_pwhash_str()+crypto_pwhash_str_verify()），而不是 MD5/SHA 简单哈希 - 主密钥派生子密钥：用
crypto_kdf_derive_from_key()，别用 XOR 或截断；它基于 HMAC-SHA512，支持上下文隔离 - 密钥存储：避免内存泄露——用完立即调用
sodium_memzero()清零密钥缓冲区；别用std::string存密钥，改用std::vector<unsigned char>或unsigned char[]
编译链接时 -lsodium 顺序和运行时找不到符号
链接时报 undefined reference to 'crypto_secretbox_easy'，大概率不是没装库，而是链接顺序或符号可见性问题。
立即学习“C++免费学习笔记（深入）”；
- 确保
-lsodium放在源文件或目标文件之后：例如g++ main.cpp -o app -lsodium，而不是g++ -lsodium main.cpp -o app - macOS 上若用 Homebrew 安装，头文件路径通常没问题，但动态库可能在
/opt/homebrew/lib，需加-L/opt/homebrew/lib - Linux 下静态链接要小心：如果同时链接了其他也用 libsodium 的第三方库（如 ZeroMQ），可能因 ABI 版本不一致导致运行时
symbol lookup error；建议统一用系统包管理器安装的版本，或全静态编译并确认ldd app不显示 libsodium
最常被跳过的一步是 nonce 生命周期管理——它和密钥一样关键，但没人记得存哪、怎么传、过期怎么处理。别把它当“随便填的参数”。
