libsodium 是一个开源的现代密码学软件库,提供加密、解密、数字签名、口令哈希等基础密码学功能。它起源于 NaCl(读作「salt」),是可移植、可交叉编译、可打包的 NaCl 分支,并带有兼容且经过扩展的 API,目标是提供构建上层密码学工具所需的全部核心操作。库采用 ISC 许可证发布,支持 Windows、iOS、Android 等平台,并有 JavaScript 与 WebAssembly 版本以及数十种编程语言的绑定。
定义
libsodium 是一个用于加密、解密、签名和口令哈希等操作的现代软件库。它是 NaCl 的可移植、可交叉编译、可安装、可打包分支,提供与 NaCl 兼容的 API,并在此基础上扩展 API 以进一步提升易用性。库的目标是提供构建更高层次密码学工具所需的全部核心操作。
该库跨平台、跨语言,可在包括 Windows(配合 MinGW 或 Visual Studio,x86、x86_64 与 arm64)、iOS 和 Android 在内的多种编译器与操作系统上运行,同时提供 JavaScript 和 WebAssembly 版本,并为各种常见编程语言提供绑定。库由志愿者开发,采用 ISC 许可证发布。
原理
libsodium 通过高层 API 把常见的密码学操作封装成易于调用的函数,使用者在多数情况下不需要自行选择底层算法参数[1]。例如一次性加密数据时,先由 crypto_secretbox_keygen() 生成密钥,再用 randombytes_buf() 生成 nonce,然后用 crypto_secretbox_easy() 完成加密,密钥需要保密而 nonce 不必保密;解密则使用同一密钥和 nonce 调用 crypto_secretbox_open_easy()[1]。当数据无法一次性放入内存时,自 1.0.14 版本起可以使用 crypto_secretstream 接口[1]。
在认证加密方面,库提供 XChaCha20-Poly1305 与 AES-GCM 等不同算法变体[1]。采用共享密钥加密时,库会同时计算认证标签,解密过程中用该密钥校验标签是否对应该密文;若消息被改动,标签不再有效,解密函数会返回错误[1]。对于没有预共享密钥的双方,可各自用 crypto_kx_keypair() 生成密钥对并交换公钥,再通过 crypto_kx_client_session_keys() 与 crypto_kx_server_session_keys() 推算出两把相同的会话密钥,分别用于两个方向的消息加解密[1]。
库还提供安全内存分配等辅助能力。0.7.0 版本引入 sodium_malloc() 与 sodium_allocarray(),在被保护数据周围放置保护页,从而降低类似 Heartbleed 情形下敏感数据暴露的可能,并可用 sodium_mprotect_noaccess() 等函数调整内存区域的访问权限[2]。库中另提供 sodium_memzero() 用于擦除内存区域、sodium_memcmp() 用于在恒定时间内比较内存区域[3]。
发展历程
libsodium 的版本历史可追溯到 2013 年。0.3 版本于 2013 年 2 月 24 日发布,0.4 版本于 2013 年 4 月 25 日发布,0.4.2 于 2013 年 7 月 8 日发布,0.4.3 于 2013 年 9 月 9 日发布,0.4.5 于 2013 年 10 月 22 日发布[4]。
2014 年 0.5.0 版本引入 sodium_mlock() 与 sodium_munlock(),为 crypto_box 和 crypto_secretbox 增加高层封装,并加入 crypto_pwhash_scryptxsalsa208sha256 系列函数,CPU 特性改为在运行时检测[5]。同年 0.6.0 版本加入 ChaCha20 流密码与 ChaCha20Poly1305 认证加密结构[2]。0.7.0 版本支持 Ed25519 密钥与 Curve25519 密钥之间的相互转换,使同一对密钥既能用于签名又能用于加密[2]。1.0.0 版本于 2014 年 9 月 30 日发布,API 与 ABI 自此稳定,并在整个 1.x.y 系列中保持向后兼容[2]。
此后版本持续迭代。1.0.4 版本加入 AES256-GCM 支持与带 96 位 nonce 的 ChaCha20 实现[5]。1.0.9 版本加入 Argon2i 口令哈希函数与 crypto_pwhash 高层 API[5]。1.0.15 版本将默认口令哈希算法改为 Argon2id,pwhash_str_verify() 仍可校验 Argon2i 的哈希[6]。1.0.22 为当前的稳定版本。
应用
libsodium 以 C 语言库的形式分发,并带有与机器无关的头文件,便于第三方项目集成;构建上使用 autotools,方便各发行版打包[3]。Debian、Fedora 等发行版都提供对应的软件包,例如 Debian 中曾有 libsodium23、libsodium26 等包名[7][8]。
库被广泛用作其他语言和平台的密码学底座。围绕它出现了面向 Rust 等语言的封装,提供 X25519、Ed25519、Ristretto255 等公钥运算以及 Argon2、scrypt 口令哈希的调用接口[9]。也有把库编译为 WebAssembly 的用法,在浏览器与 Node.js 环境中执行 Curve25519 相关的密码学运算[10]。此外,库提供的受保护内存等函数可被上层组件用来保护私钥与机密数据[11]。
局限
库对所支持的曲线有明确的范围。其主要支持的曲线是 Curve25519,相当于 128 位安全强度;在一次安全审计报告写作时,库尚未提供 224 位与 256 位安全强度级别的曲线支持[12]。审计报告同时建议补充一条 256 位安全强度级别的曲线,以便开发者按不同安全级别选择曲线[12]。
部分原语在使用上存在条件限制。AES-GCM 可能因消息长度限制而失败,而 XChaCha20 的限制在实践上只是理论性的,因此检查返回值对后者并非严格必要,但审计建议在应用中无条件检查[1]。库中也有原语被移除或标记为废弃:1.0.15 版本删除了 aes128ctr 原语,理由是它速度慢、非标准、不提供认证且似无开源项目使用[6];crypto_sign_edwards25519sha512batch 系列函数在 1.0.6 版本被标记为弃用[5]。
此外,库并不提供 C++ 绑定,这部分可能属于另一个独立的软件包[13]。sodium_init() 自身不是线程安全的,在其成功返回之前不应调用其他函数;在多线程环境中需要自行加锁[3]。库的随机数辅助接口是 fork(2) 安全的,但不是线程安全的[3]。
参见
-
NaCl —— libsodium 即由这一密码学库分支发展而来,二者 API 兼容。
-
Curve25519 —— 库中公钥加密与密钥交换所依据的主要椭圆曲线。
-
Ed25519 —— 库默认用于 crypto_sign 系列签名操作的签名方案。
-
Argon2 —— 库中用于口令哈希的算法,1.0.15 起成为默认选择。
-
BLAKE2 —— 库中 crypto_generichash 所使用的哈希函数。
-
ChaCha20-Poly1305 —— 库提供的认证加密结构之一。
参考资料
- Quickstart and FAQ | Libsodium documentation [引用日期2026-10-14]
- Changelog for libsodium 1.0.0 [引用日期2026-10-14]
- README [引用日期2026-10-14]
- API/ABI changes review for libsodium [引用日期2026-10-14]
- libsodium [引用日期2026-10-14]
- ChangeLog [引用日期2026-10-14]
- 软件包：libsodium23（1.0.18-2 以及其他的） [引用日期2026-10-14]
- 软件包：libsodium26（1.0.22-2） [debports] [引用日期2026-10-14]
- crates.io: Rust Package Registry [引用日期2026-10-14]
- JSPM – @deliberative/crypto@0.5.4 [引用日期2026-10-14]
- arxiv.org 上的网页 [引用日期2026-10-14]
- Authenticated Encryption with Associated Data [引用日期2026-10-14]
- README [引用日期2026-10-14]