Ruby binding to the Networking and Cryptography (NaCl) library
Latest commit 699e329 Sep 2, 2017 @tarcieri tarcieri committed on GitHub Merge pull request #160 from EdwardBetts/spelling
correct spelling mistake


Gem Version Build Status Code Climate Coverage Status MIT licensed

NOTE: This is the 5.x stable branch of RbNaCl. For the 4.x legacy branch, please see:

A Ruby binding to the state-of-the-art Networking and Cryptography library by Daniel J. Bernstein. This is NOT Google Native Client. This is a crypto library.

On a completely unrelated topic, RbNaCl is also the empirical formula for Rubidium Sodium Chloride.

Need help with RbNaCl? Join the RbNaCl Google Group. We're also on IRC at #cryptosphere on

Why NaCl?

NaCl is a different kind of cryptographic library. In the past crypto libraries were kitchen sinks of little bits and pieces, like ciphers, MACs, signature algorithms, and hash functions. To accomplish anything you had to make a lot of decisions about which specific pieces to use, and if any of your decisions were wrong, the result was an insecure system. The choices are also not easy: EAX? GCM? CCM? AES-CTR? CMAC? OMAC1? AEAD? NIST? CBC? CFB? CTR? ECB? OMGWTFBBQ!

NaCl puts cryptography on Rails! Instead of making you choose which cryptographic primitives to use, NaCl provides convention over configuration in the form of expertly-assembled high-level cryptographic APIs that ensure not only the confidentiality of your data, but also detect tampering. These high-level, easy-to-use APIs are designed to be hard to attack by default in ways primitives exposed by libraries like OpenSSL are not.

This approach makes NaCl a lot closer to a system like GPG than it is to the cryptographic primitive APIs in a library like OpenSSL. In addition, NaCl also uses state-of-the-art encryption, including Curve25519 elliptic curves and the XSalsa20 stream cipher. This means with NaCl you not only get a system which is designed to be secure-by-default, you also get one which is extremely fast with comparatively small cryptographic keys.

For more information on NaCl's goals, see Dan Bernstein's presentation Blaming the Cryptographic User

Is it any good?


Supported platforms

You can use RbNaCl on platforms libsodium is supported (see below).

This library aims to support and is tested against the following Ruby versions:

  • Ruby 2.2.6+
  • Ruby 2.3.0+
  • JRuby

If something doesn't work on one of these versions, it's a bug.

This library may inadvertently work (or seem to work) on other Ruby versions, however support will only be provided for the versions listed above.

If you would like this library to support another Ruby version or implementation, you may volunteer to be a maintainer. Being a maintainer entails making sure all tests run and pass on that implementation. When something breaks on your implementation, you will be responsible for providing patches in a timely fashion. If critical issues for a particular implementation exist at the time of a major release, support for that Ruby version may be dropped.


Note: Windows installation instructions are available.


NOTE: Want to avoid the hassle of installing libsodium? Use the rbnacl-libsodium gem

To use RbNaCl, you will need to install libsodium:

At least version 1.0.0 is required.

For OS X users, libsodium is available via homebrew and can be installed with:

brew install libsodium

For FreeBSD users, libsodium is available both via pkgng and ports. To install a binary package:

pkg install libsodium

To install from ports on FreeBSD, use your favorite ports front end (e.g. portmaster or portupgrade), or use make as follows:

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

RbNaCl gem

Once you have libsodium installed, add this line to your application's Gemfile:

gem 'rbnacl'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rbnacl

Inside of your Ruby program do:

require 'rbnacl' pull it in as a dependency.


RbNaCl's documentation can be found in the Wiki. The following features are supported:

  • SimpleBox: easy-to-use public-key or secret-key encryption "on Rails"
  • Secret-key Encryption: authenticated symmetric encryption using a single key shared among parties
  • Public-key Encryption: securely send messages to a given public key which can only be decrypted by a secret key
  • Digital Signatures: sign messages with a private key which can be verified by a public one
  • Authenticators: create codes which can be used to check the authenticity of messages
  • Hash Functions: compute a secure, fixed-length code from a message which does not reveal the contents of the message

Additional power-user features are available. Please see the Wiki for further information.

YARD API documentation is also available.

Learn More

While NaCl has designed to be easier-than-usual to use for a crypto library, cryptography is an incredibly difficult subject and it's always helpful to know as much as you can about it before applying it to a particular use case. That said, the creator of NaCl, Dan Bernstein, has published a number of papers about NaCl. If you are interested in learning more about how NaCl works, it's recommended that you read them:

For more information on libsodium, please check out the Introducing Sodium blog post

Have a general interest in cryptography? Check out the free course Coursera offers from Stanford University Professor Dan Boneh:

Important Questions

Is it "Military Grade™"?

Only if your military understands twisted Edwards curves

Is it "Bank Grade™"?

No, that means 3DES, which this library doesn't support, sorry

Does it have a lock with a checkmark?

Sure, here you go:

Checkmarked Lock


  • Fork this repository on Github
  • Make your changes and send a pull request
  • If your changes look good, we'll merge 'em


Copyright (c) 2012-2017 Tony Arcieri, Jonathan Stott. Distributed under the MIT License. See LICENSE.txt for further details.