sodium 0.0.0 → 0.5.0

data/.gitignore

@@ -0,0 +1,4 @@
+build/
+coverage/
+
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,27 @@
+script: bundle exec rake test
+
+env:
+  - >
+    LIBSODIUM_MIRROR="https://github.com/jedisct1/libsodium/tarball/%s"
+    LIBSODIUM_VERSION="master"
+# - >
+#   LIBSODIUM_MIRROR="http://download.dnscrypt.org/libsodium/releases/libsodium-%s.tar.gz"
+#   LIBSODIUM_VERSION=0.4.1
+#   LIBSODIUM_DIGEST=65756c7832950401cc0e6ee0e99b165974244e749f40f33d465f56447bae8ce3
+
+rvm:
+  - 1.8.7
+  - 1.9.3
+  - 2.0.0
+  - ruby-head
+  - ree
+  - jruby-18mode
+  - jruby-19mode
+  - jruby-head
+  - rbx-18mode
+  - rbx-19mode
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org/'
+
+gemspec
+
+gem 'pry'
+
+group :test do
+  gem 'coveralls', :require => false
+end

data/README.md

@@ -0,0 +1,111 @@
+[![Gem Version][gem-badge]][gem-url]
+[![Build Status][travis-badge]][travis-url]
+[![Dependency Status][gemnasium-badge]][gemnasium-url]
+[![Code Climate][codeclimate-badge]][codeclimate-url]
+[![Coverage Status][coveralls-badge]][coveralls-url]
+
+sodium
+======
+
+`sodium` is a Ruby binding to the easy-to-use high-speed crypto library [`libsodium`][libsodium] (which itself is based on [Daniel J. Bernstein][djb]'s [`NaCl`][nacl]). `NaCl`'s goal, and thus this project's, is to provide all the core operations necessary to build high-level cryptographic tools.
+
+`NaCl` improves upon existing libraries with improved security through tight coding standads, improved usability, and significantly boosted performance.
+
+Why Sodium?
+-----------
+
+`sodium` exports the functions provided by `libsodium` in an object-oriented, Rubylike manner using a very thin [FFI][ffi] wrapper. It thus provides all the benefits of using the `libsodium` C library directly: simplicity, performance, and security.
+
+This library is tightly focused on providing only modern primitives and operations, giving users as few ways as possible to shoot themselves in the foot. While *no* crypto library can prevent all classes of user error, this library at least attempts to minimize the possibility of known, easily-preventable types of user error such as the use of broken primitives, reliance on non-authenticated encryption modes, and composition of low-level primitives to perform tasks for which well-studied high-level operations already exist.
+
+Libraries like [OpenSSL][openssl] pack in support for every cryptographic primitive, protocol, and operation under the sun. Many of these supported features are cryptographically broken and preserved only so developers can maintain compatibility with older software. This is explicitly *not* a goal of `sodium`. While we will provide migration paths away from any primitives discovered to be weak or broken, we will never introduce known-bad primitives (e.g., MD5 or SHA-1) or easy-to-fuck-up operations (e.g., CBC mode) for the sake of interoperability.
+
+Security
+--------
+
+The underlying cryptographic functions and APIs have been designed, chosen, and implemented by professional cryptographers. `sodium` itself, however, has not. No guarantees are made about its security nor suitability for any particular purpose.
+
+If believe you have discovered a security vulnerability in the `sodium` wrapper, contact me at `sodium (at) touset (dot) org`. Please encrypt your message using the project's [GPG key][gpg-key] (fingerprint: `1E71 12A4 9424 2358 F6C8 727D C947 F58B FFCE E0D7`).
+
+Supported Platforms
+-------------------
+
+  * MRI 2.0
+  * MRI 1.9.3
+  * MRI 1.8.7 / REE
+  * Rubinius 1.8 / 1.9
+  * JRuby 1.8 / 1.9
+
+Support for these platforms is automatically tested using [Travis CI][travis-ci].
+
+Windows is also theoretically supported, but is as of yet completely untested. If `sodium` doesn't work for you on Windows (or any of the other supported platforms, for that matter), please submit a bug.
+
+Installation
+------------
+
+### Dependencies
+
+`sodium` depends on the [`libsodium`][libsodium] C library. It can be installed through [homebrew][homebrew] on OSX.
+
+```sh
+brew install libsodium
+```
+
+### Ruby Gem
+
+`sodium` is distributed as a gem of the same name. You can simply install it through the `gem` command
+
+```sh
+gem install sodium
+```
+
+or install it through [`bundler`][bundler] by adding it to your `Gemfile` and bundling.
+
+```ruby
+echo gem 'sodium' >> Gemfile
+bundle
+```
+
+Documentation
+-------------
+
+Full documentation can be found online at [RubyDoc][rubydoc-url]. Examples are provided for the following high-level operations:
+
+  * [Secret-Key Encryption][example-symmetric-encryption]
+  * [Secret-Key Message Authenticators][example-symmetric-authenticators]
+  * [Public-Key Encryption][example-asymmetric-encryption]
+  * [Public-Key Message Signatures][example-asymmetric-signatures]
+
+Contributing
+------------
+
+Fork, commit, push. Submit pull request. When possible, try and follow existing coding conventions for the file you're editing.
+
+[libsodium]: https://github.com/jedisct1/libsodium/
+[djb]:       http://cr.yp.to/djb.html
+[nacl]:      http://nacl.cr.yp.to/
+[ffi]:       http://github.com/ffi/ffi
+[openssl]:   http://ruby-doc.org/stdlib-2.0/libdoc/openssl/rdoc/OpenSSL.html
+[travis-ci]: https://travis-ci.org/stouset/sodium
+[homebrew]:  http://mxcl.github.io/homebrew/
+[bundler]:   http://gembundler.com/
+
+[gem-badge]:         https://badge.fury.io/rb/sodium.png
+[gem-url]:           https://badge.fury.io/rb/sodium
+[travis-badge]:      https://travis-ci.org/stouset/sodium.png
+[travis-url]:        https://travis-ci.org/stouset/sodium
+[gemnasium-badge]:   https://gemnasium.com/stouset/sodium.png
+[gemnasium-url]:     https://gemnasium.com/stouset/sodium
+[codeclimate-badge]: https://codeclimate.com/github/stouset/sodium.png
+[codeclimate-url]:   https://codeclimate.com/github/stouset/sodium
+[coveralls-badge]:   https://coveralls.io/repos/stouset/sodium/badge.png?branch=master
+[coveralls-url]:     https://coveralls.io/r/stouset/sodium
+[rubydoc-badge]:     :(
+[rubydoc-url]:       http://rubydoc.org/gems/sodium/frames
+
+[example-symmetric-encryption]:     examples/TODO
+[example-symmetric-authenticators]: examples/TODO
+[example-asymmetric-encryption]:    examples/TODO
+[example-asymmetric-signatures]:    examples/TODO
+
+[gpg-key]: sodium.pub.gpg

data/Rakefile

@@ -0,0 +1,3 @@
+Dir['tasks/**/*.rake'].each {|task| load task }
+
+task :default => :test

data/VERSION

@@ -0,0 +1 @@
+0.5.0

data/config/nacl_ffi.yml

@@ -0,0 +1,90 @@
+- :class    : Sodium::Auth
+  :family   : crypto_auth
+  :constants:
+    - BYTES
+    - KEYBYTES
+  
+  :functions: 
+    ~      : [ buffer_out, buffer_in, ulong_long, buffer_in, int ]
+    :verify: [ buffer_in , buffer_in, ulong_long, buffer_in, int ]
+
+  :primitives:
+    - :HMACSHA512256
+    - :HMACSHA256
+
+- :class    : Sodium::Box
+  :family   : crypto_box
+  :constants:
+    - PUBLICKEYBYTES
+    - SECRETKEYBYTES
+    - BEFORENMBYTES
+    - NONCEBYTES
+    - ZEROBYTES
+    - BOXZEROBYTES
+    - MACBYTES
+    
+  :functions:
+    ~            : [ buffer_out, buffer_in, ulong_long, buffer_in, buffer_in, buffer_in, int ]
+    :open        : [ buffer_out, buffer_in, ulong_long, buffer_in, buffer_in, buffer_in, int ]
+    :keypair     : [ buffer_out, buffer_out, int ]
+    :beforenm    : [ buffer_out, buffer_in, buffer_in, int ]
+    :afternm     : [ buffer_out, buffer_in, ulong_long, buffer_in, buffer_in, int ]
+    :open_afternm: [ buffer_out, buffer_in, ulong_long, buffer_in, buffer_in, int ]
+
+  :primitives:
+    - :Curve25519XSalsa20Poly1305
+
+- :class    : Sodium::Hash
+  :family   : crypto_hash
+  :constants:
+    - BYTES
+
+  :functions:
+    ~: [ buffer_out, buffer_in, ulong_long, int ]
+
+  :primitives:
+    - :SHA512
+    - :SHA256
+
+- :class    : Sodium::OneTimeAuth
+  :family   : crypto_onetimeauth
+  :constants: 
+    - BYTES
+    - KEYBYTES
+
+  :functions:
+    ~      : [ buffer_out, buffer_in, ulong_long, buffer_in, int ]
+    :verify: [ buffer_in , buffer_in, ulong_long, buffer_in, int ]
+
+  :primitives:
+    - :Poly1305
+
+- :class    : Sodium::SecretBox
+  :family   : crypto_secretbox
+  :constants:
+    - KEYBYTES
+    - NONCEBYTES
+    - ZEROBYTES
+    - BOXZEROBYTES
+
+  :functions:
+    ~    : [ buffer_out, buffer_in, ulong_long, buffer_in, buffer_in, int ]
+    :open: [ buffer_out, buffer_in, ulong_long, buffer_in, buffer_in, int ]
+
+  :primitives:
+    - :XSalsa20Poly1305
+
+- :class    : Sodium::Sign
+  :family   : crypto_sign
+  :constants:
+    - BYTES
+    - PUBLICKEYBYTES
+    - SECRETKEYBYTES
+
+  :functions:
+    ~      : [ buffer_out, buffer_out, buffer_in, ulong_long, buffer_in, int ]
+    open   : [ buffer_out, buffer_out, buffer_in, ulong_long, buffer_in, int ]
+    keypair: [ buffer_out, buffer_out, int ]
+
+  :primitives:
+    - :Ed25519

data/lib/sodium.rb

@@ -0,0 +1,24 @@
+module Sodium
+  class Error       < ::StandardError; end
+  class LengthError < Error;           end
+  class CryptoError < Error;           end
+  class MemoryError < Error;           end
+end
+
+# require 'sodium/version'
+
+# core classes used by other modules
+require 'sodium/delegate'
+require 'sodium/buffer'
+require 'sodium/random'
+
+# object-oriented bindings to FFI
+require 'sodium/auth'
+require 'sodium/box'
+require 'sodium/hash'
+require 'sodium/one_time_auth'
+require 'sodium/secret_box'
+require 'sodium/sign'
+
+# automagic FFI bindings to libsodium
+require 'sodium/ffi'

data/lib/sodium/auth.rb

@@ -0,0 +1,52 @@
+require 'sodium'
+
+class Sodium::Auth
+  include Sodium::Delegate
+
+  def self.key
+    Sodium::Buffer.key self.implementation[:KEYBYTES]
+  end
+
+  def initialize(key)
+    @key = self.class._key(key)
+  end
+
+  def auth(message)
+    message = self.class._message(message)
+
+    Sodium::Buffer.empty self.implementation[:BYTES] do |authenticator|
+      self.implementation.nacl(
+        authenticator.to_str,
+        message.to_str,
+        message.to_str.bytesize,
+        @key.to_str
+      ) or raise Sodium::CryptoError, 'failed to generate an authenticator'
+    end
+  end
+
+  def verify(message, authenticator)
+    message       = self.class._message(message)
+    authenticator = self.class._authenticator(authenticator)
+
+    self.implementation.nacl_verify(
+      authenticator.to_str,
+      message.to_str,
+      message.to_str.bytesize,
+      @key.to_str
+    )
+  end
+
+  private
+
+  def self._key(k)
+    Sodium::Buffer.new k, self.implementation[:KEYBYTES]
+  end
+
+  def self._authenticator(a)
+    Sodium::Buffer.new a, self.implementation[:BYTES]
+  end
+
+  def self._message(m)
+    Sodium::Buffer.new(m)
+  end
+end

data/lib/sodium/box.rb

@@ -0,0 +1,127 @@
+require 'sodium'
+
+class Sodium::Box
+  include Sodium::Delegate
+
+  def self.keypair
+    public_key = Sodium::Buffer.empty self.implementation[:PUBLICKEYBYTES]
+    secret_key = Sodium::Buffer.empty self.implementation[:SECRETKEYBYTES]
+
+    self.implementation.nacl_keypair(
+      public_key.to_str,
+      secret_key.to_str
+    ) or raise Sodium::CryptoError, 'failed to generate a keypair'
+
+    return secret_key, public_key
+  end
+
+  def self.afternm(shared_key, message, nonce)
+    shared_key = _shared_key(shared_key)
+    message    = _message(message)
+    nonce      = _nonce(nonce)
+
+    Sodium::Buffer.empty(message.bytesize) do |ciphertext|
+      self.implementation.nacl_afternm(
+        ciphertext.to_str,
+        message.to_str,
+        message.to_str.bytesize,
+        nonce.to_str,
+        shared_key.to_str
+      ) or raise Sodium::CryptoError, 'failed to close the box'
+    end.unpad self.implementation[:BOXZEROBYTES]
+  end
+
+  def self.open_afternm(shared_key, ciphertext, nonce)
+    shared_key = _shared_key(shared_key)
+    ciphertext = _ciphertext(ciphertext)
+    nonce      = _nonce(nonce)
+
+    Sodium::Buffer.empty(ciphertext.bytesize) do |message|
+      self.implementation.nacl_open_afternm(
+        message.to_str,
+        ciphertext.to_str,
+        ciphertext.to_str.bytesize,
+        nonce.to_str,
+        shared_key.to_str
+      ) or raise Sodium::CryptoError, 'failed to open the box'
+    end.unpad self.implementation[:ZEROBYTES]
+  end
+
+
+  def initialize(secret_key, public_key)
+    @secret_key = self.class._secret_key(secret_key)
+    @public_key = self.class._public_key(public_key)
+  end
+
+  def nonce
+    Sodium::Buffer.nonce self.implementation[:NONCEBYTES]
+  end
+
+  def box(message, nonce)
+    message = self.class._message(message)
+    nonce   = self.class._nonce(nonce)
+
+    Sodium::Buffer.empty(message.bytesize) do |ciphertext|
+      self.implementation.nacl(
+        ciphertext.to_str,
+        message.to_str,
+        message.to_str.bytesize,
+        nonce.to_str,
+        @public_key.to_str,
+        @secret_key.to_str
+      ) or raise Sodium::CryptoError, 'failed to close the box'
+    end.unpad self.implementation[:BOXZEROBYTES]
+  end
+
+  def open(ciphertext, nonce)
+    ciphertext = self.class._ciphertext(ciphertext)
+    nonce      = self.class._nonce(nonce)
+
+    Sodium::Buffer.empty(ciphertext.bytesize) do |message|
+      self.implementation.nacl_open(
+        message.to_str,
+        ciphertext.to_str,
+        ciphertext.to_str.bytesize,
+        nonce.to_str,
+        @public_key.to_str,
+        @secret_key.to_str
+      ) or raise Sodium::CryptoError, 'failed to open the box'
+    end.unpad self.implementation[:ZEROBYTES]
+  end
+
+  def beforenm
+    Sodium::Buffer.empty self.implementation[:BEFORENMBYTES] do |shared_key|
+      self.implementation.nacl_beforenm(
+        shared_key.to_str,
+        @public_key.to_str,
+        @secret_key.to_str
+      ) or raise Sodium::CryptoError, 'failed to create a shared key'
+    end
+  end
+
+  private
+
+  def self._public_key(k)
+    Sodium::Buffer.new k, self.implementation[:PUBLICKEYBYTES]
+  end
+
+  def self._secret_key(k)
+    Sodium::Buffer.new k, self.implementation[:SECRETKEYBYTES]
+  end
+
+  def self._shared_key(k)
+    Sodium::Buffer.new k, self.implementation[:BEFORENMBYTES]
+  end
+
+  def self._message(m)
+    Sodium::Buffer.new(m).pad self.implementation[:ZEROBYTES]
+  end
+
+  def self._ciphertext(c)
+    Sodium::Buffer.new(c).pad self.implementation[:BOXZEROBYTES]
+  end
+
+  def self._nonce(n)
+    Sodium::Buffer.new n, self.implementation[:NONCEBYTES]
+  end
+end