rbnacl：实践指南

作者：袖梨 2026-09-11

在项目中评估rbnacl，可以先看清用途边界：Ruby FFI 绑定到网络和加密 (NaCl) 库 (a.k.a.libsodium)。在日常自动化场景里，常见问题是输入边界、依赖和失败处理如果不清楚就很难稳定复用，这正是评估时需要盯住的地方。我的评估方法是用一项范围明确的真实任务完成最小试跑，然后检查配置时间、输出质量、异常信息和维护痕迹是否与文档一致。我会把它列入愿意先做小范围验证并复查原始文档的团队的候选清单，而不是仅凭项目介绍直接纳入生产。

======

libsodium 的 Ruby 绑定，网络和密码学的一个分支图书馆。

为什么是libsodium/NaCl？

NaCl 是一种不同类型的密码库。在过去的加密货币图书馆是厨房里的小碎片，就像密码， MACs、签名算法和哈希函数。为了完成任何事你必须就使用哪些特定的部分做出很多决定，如果你的任何决定是错误的，结果就是不安全的系统。选择也并不容易：EAX？ GCM？ CCM？ AES-CTR？ CMAC？ OMAC1? AEAD? NIST? CBC? CFB? CTR? ECB? OMGWTFBBQ!

NaCl 将密码学置于 Rails 之上！而不是让你选择哪个要使用的加密原语，NaCl 提供约定优于配置以专业组装的高级密码 APIs 的形式确保不仅可以保护您的数据的机密性，还可以检测篡改行为。这些高级、易于使用的 APIs 被设计为难以被攻击默认情况下，OpenSSL 等库公开的原语则不然。

这种方法使 NaCl 更接近像 GPG 这样的系统。到 OpenSSL 等库中的加密原语 APIs。此外， NaCl还使用最先进的加密，包括Curve25519椭圆曲线和 XSalsa20 流密码。这意味着使用 NaCl 您不仅可以获得一个被设计为默认安全的系统，您还可以获得一个使用相对较小的加密密钥速度非常快。

有什么好处吗？

是的。

支持的平台

您可以在支持 libsodium 的平台上使用 RbNaCl（见下文）。

该库旨在支持以下 Ruby 并对其进行测试版本：

红宝石2.6
红宝石2.7
红宝石3.0
红宝石3.1
红宝石3.2
红宝石3.3
红宝石3.4
JRuby 9.4
JRuby 10.0

如果某些功能在其中一个版本上不起作用，那就是一个错误。

安装

注意：Windows 安装说明可参见。

钠

要使用 RbNaCl，您需要安装 libsodium：

https://github.com/jedisct1/libsodium

至少需要版本 1.0.0。

对于 OS X 用户，libsodium 可通过自制程序获得，并可通过以下方式安装：

brew install libsodium

对于 FreeBSD 用户，libsodium 可以通过 pkgng 和 ports 获取。安装二进制包：

pkg install libsodium

要从 FreeBSD 上的 ports 安装，请使用您最喜欢的 ports 前端 (e.g. portmaster 或 portupgrade），或使用 make，如下所示：

cd /usr/ports/security/libsodium; make install clean

RbNaCl 宝石

安装 libsodium 后，将此行添加到应用程序的 Gemfile 中：

gem 'rbnacl'

然后执行：

$ bundle

或者自己安装：

$ gem install rbnacl

在你的 Ruby 程序中执行以下操作：

require 'rbnacl'

...将其作为依赖项拉入。

文档

RbNaCl的文档可以在wiki中找到。具有以下特点支持：

SimpleBox: easy-to-use 公钥或秘密密钥加密“on Rails”
秘钥加密: authenticated 使用对称加密各方共享单一密钥
公钥加密: securely 向给定的公众发送消息只能用秘密密钥解密的密钥
数字签名: sign 带有私钥的消息，可以由公众验证
Authenticators: create 代码，可用于检查消息的真实性
哈希函数: compute 消息中的安全、固定长度代码这不会泄露消息的内容

还提供其他高级用户功能。请参阅 Wiki 了解更多信息信息。

YARD API 文档也可用。

了解更多

虽然 NaCl 的设计比平常更容易用于加密货币图书馆，密码学是一门极其困难的学科，它在申请之前尽可能多地了解它总是有帮助的它适用于特定的用例。也就是说，NaCl 的创建者 Dan Bernstein，发表了多篇关于NaCl的论文。如果你是有兴趣了解更多有关 NaCl 工作原理的信息，推荐你读过它们：