aead 1.3.0

data/.gitignore

@@ -0,0 +1,8 @@
+/Gemfile.lock
+
+/.yardoc
+/bin
+/coverage
+/doc
+
+*.bundle

data/.travis.yml

@@ -0,0 +1,3 @@
+rvm:
+  - 1.9.2
+  - 1.9.3

data/.yardopts

@@ -0,0 +1,2 @@
+--markup-provider=redcarpet
+--markup=markdown

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem 'terminal-notifier-guard'
+gem 'pry'
+gem 'pry-doc'

data/Guardfile

@@ -0,0 +1,10 @@
+guard 'yard' do
+  watch(%r{lib/.+\.rb})
+  watch(%r{ext/.+\.c})
+end
+
+guard 'minitest' do
+  watch(%r|^spec/(.*)_spec\.rb|)
+  watch(%r|^lib/(.*)([^/]+)\.rb|)     { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  watch(%r|^spec/spec_helper\.rb|)    { "spec" }
+end

data/LICENSE.md

@@ -0,0 +1,22 @@
+The MIT License
+===============
+
+Copyright (c) 2012 OneLogin, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,57 @@
+# aead #
+
+Ruby library for generating AEAD (authenticated encryption with
+associated data) ciphertexts.
+
+## Description ##
+
+Modern encryption best practices encourage the use of authenticated
+encryption: ciphertext contents should be authenticated during the
+decryption process, preventing either malicious or unintentional
+silent corruption.
+
+This library provides an extension to the Ruby OpenSSL bindings that
+allows access to the GCM mode supported by OpenSSL (in versions higher
+than 1.0.0). For Rubies linked against older versions of OpenSSL, a
+mode is provided to perform AES-256-CTR with HMAC-SHA-256, as
+[encouraged by Colin Percival](http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html).
+
+## Getting Started ##
+
+```ruby
+require 'aead'
+
+# currently, AES-256-GCM and AES-256-CTR-HMAC-SHA-256 are supported
+mode   = AEAD::Cipher.new('AES-256-GCM')
+key    = cipher.generate_key
+nonce  = cipher.generate_nonce
+
+cipher    = mode.new(key)
+aead      = cipher.encrypt(nonce, 'authentication data', 'plaintext')
+plaintext = cipher.decrypt(nonce, 'authentication data', aead)
+```
+
+If any of the key, nonce, authentication data, or ciphertext has been
+altered, the ciphertext will fail to decrypt and an exception will be
+raised.
+
+```ruby
+cipher.decrypt(nonce, 'authentication data', aead.succ) # => ArgumentError
+```
+
+## Security Guidelines ##
+
+Nonces should *never* be used to encrypt more than one plaintext with
+the same key.
+
+Nonces generated through the API provided by this gem are guaranteed
+to be unique as long as the state file is not corrupted or
+removed. The state file is located in `/var/tmp/ruby-aead`. 
+
+Nonce generation is thread-safe and tolerates being performed
+simultaneously in separate processes.
+
+If you believe you have discovered a security vulnerability in this
+gem, please email `security@onelogin.com` with a description. We
+follow responsible disclosure guidelines, and will work with you to
+quickly find a resolution.

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rake/testtask'
+require 'rake/version_task'
+require 'yard'
+
+task :default => %w{ build test }
+
+task :build do
+  Dir.chdir('ext/openssl/cipher/aead') do
+    system %{ruby extconf.rb}
+    system %{make}
+    system %{cp aead.#{RbConfig::CONFIG['DLEXT']} ../../../../lib/openssl/cipher}
+  end
+end
+
+Rake::TestTask.new do |t|
+  t.libs.push 'lib'
+  t.libs.push 'spec'
+
+  t.test_files = FileList['spec/**/*_spec.rb']
+  t.verbose    = true
+end
+
+if defined?(RUBY_ENGINE) and RUBY_ENGINE == 'ruby'
+  require 'cane/rake_task'
+
+  task :default => :cane
+
+  Cane::RakeTask.new do |t|
+    t.add_threshold 'coverage/coverage.txt', :>=, 100
+  end
+end
+
+Rake::VersionTask.new do |t|
+  t.with_git_tag = true
+end
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  # --no-stats applies only to the `yard stats` command, so to include
+  # it we have to disable automatic stat generation and do it
+  # ourselves
+  t.options << '--no-stats'
+  t.after = lambda do
+    stats = YARD::CLI::Stats.new
+    stats.run '--list-undoc'
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+1.3.0

data/aead.gemspec

@@ -0,0 +1,34 @@
+require 'pathname'
+
+Gem::Specification.new do |gem|
+  gem.name    = 'aead'
+  gem.version = Pathname.new(__FILE__).join('../VERSION').read.chomp
+
+  gem.author = 'Stephen Touset'
+  gem.email  = 'stephen@touset.org'
+
+  gem.homepage    = 'https://github.com/onelogin/aead'
+  gem.summary     = %{Ruby library to generate AEADs}
+  gem.description = %{Ruby library to generate AEADs}
+
+  gem.bindir      = 'script'
+  gem.files       = `git ls-files`            .split("\n")
+  gem.extensions  = `git ls-files -- ext/*.rb`.split("\n")
+  gem.executables = `git ls-files -- script/*`.split("\n").map {|e| e[7..-1] }
+  gem.test_files  = `git ls-files -- spec/*`  .split("\n")
+
+  gem.add_dependency 'macaddr', '~> 1'
+
+  gem.add_development_dependency 'bundler'
+  gem.add_development_dependency 'cane'
+  gem.add_development_dependency 'guard'
+  gem.add_development_dependency 'guard-minitest'
+  gem.add_development_dependency 'guard-yard'
+  gem.add_development_dependency 'markdown'
+  gem.add_development_dependency 'minitest'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'redcarpet'
+  gem.add_development_dependency 'simplecov'
+  gem.add_development_dependency 'yard'
+  gem.add_development_dependency 'version'
+end

data/ext/openssl/cipher/aead/.gitignore

@@ -0,0 +1,4 @@
+/Makefile
+/*.bundle
+/*.log
+/*.o

data/ext/openssl/cipher/aead/aead.c

@@ -0,0 +1,156 @@
+#include <ruby.h>
+#include <openssl/ssl.h>
+#include <openssl/err.h>
+
+VALUE dOSSL;
+VALUE eCipherError;
+
+#define GetCipherInit(obj, ctx) do {                    \
+        Data_Get_Struct((obj), EVP_CIPHER_CTX, (ctx));  \
+    } while (0)
+
+#define GetCipher(obj, ctx) do {                                        \
+        GetCipherInit((obj), (ctx));                                    \
+        if (!(ctx)) {                                                   \
+            ossl_raise(rb_eRuntimeError, "Cipher not inititalized!");   \
+        }                                                               \
+    } while (0)
+
+static VALUE
+ossl_make_error(VALUE exc, const char *fmt, va_list args)
+{
+    char buf[BUFSIZ];
+    const char *msg;
+    long e;
+    int len = 0;
+
+#ifdef HAVE_ERR_PEEK_LAST_ERROR
+    e = ERR_peek_last_error();
+#else
+    e = ERR_peek_error();
+#endif
+    if (fmt) {
+        len = vsnprintf(buf, BUFSIZ, fmt, args);
+    }
+    if (len < BUFSIZ && e) {
+        if (dOSSL == Qtrue) /* FULL INFO */
+            msg = ERR_error_string(e, NULL);
+        else
+            msg = ERR_reason_error_string(e);
+        len += snprintf(buf+len, BUFSIZ-len, "%s%s", (len ? ": " : ""), msg);
+    }
+    if (dOSSL == Qtrue){ /* show all errors on the stack */
+        while ((e = ERR_get_error()) != 0){
+            rb_warn("error on stack: %s", ERR_error_string(e, NULL));
+        }
+    }
+    ERR_clear_error();
+
+    if(len > BUFSIZ) len = rb_long2int(strlen(buf));
+    return rb_exc_new(exc, buf, len);
+}
+
+void
+ossl_raise(VALUE exc, const char *fmt, ...)
+{
+    va_list args;
+    VALUE err;
+    va_start(args, fmt);
+    err = ossl_make_error(exc, fmt, args);
+    va_end(args);
+    rb_exc_raise(err);
+}
+
+static VALUE
+ossl_cipher_set_aad(VALUE self, VALUE data)
+{
+    EVP_CIPHER_CTX *ctx;
+    char           *in      = NULL;
+    int             in_len  = 0;
+    int             out_len = 0;
+
+    StringValue(data);
+
+    in     = (unsigned char *) RSTRING_PTR(data);
+    in_len = RSTRING_LENINT(data);
+
+    GetCipher(self, ctx);
+
+    if (!EVP_CipherUpdate(ctx, NULL, &out_len, in, in_len))
+        ossl_raise(eCipherError, NULL);
+
+    return self;
+}
+
+static VALUE
+ossl_cipher_get_tag(VALUE self)
+{
+    EVP_CIPHER_CTX *ctx;
+    VALUE           tag;
+
+    tag = rb_str_new(NULL, 16);
+
+    GetCipher(self, ctx);
+
+#ifndef EVP_CTRL_GCM_GET_TAG
+    ossl_raise(eCipherError, "your version of OpenSSL doesn't support GCM");
+#else
+    if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, 16, (unsigned char *)RSTRING_PTR(tag)))
+        ossl_raise(eCipherError, NULL);
+#endif
+
+    return tag;
+}
+
+static VALUE
+ossl_cipher_set_tag(VALUE self, VALUE data)
+{
+    EVP_CIPHER_CTX *ctx;
+    char           *in     = NULL;
+    int             in_len = 0;
+
+    StringValue(data);
+
+    in     = (unsigned char *) RSTRING_PTR(data);
+    in_len = RSTRING_LENINT(data);
+
+    GetCipher(self, ctx);
+
+#ifndef EVP_CTRL_GCM_SET_TAG
+    ossl_raise(eCipherError, "your version of OpenSSL doesn't support GCM");
+#else
+    if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, in_len, in))
+        ossl_raise(eCipherError, NULL);
+#endif
+
+    return data;
+}
+
+static VALUE
+ossl_cipher_verify(VALUE self)
+{
+    EVP_CIPHER_CTX *ctx;
+    int             out_len = 0;
+
+    GetCipher(self, ctx);
+
+    if (!EVP_CipherUpdate(ctx, NULL, &out_len, NULL, 0))
+        ossl_raise(eCipherError, "ciphertext failed authentication step");
+
+    return rb_str_new(0, 0);
+}
+
+void
+Init_aead(void)
+{
+    VALUE mOSSL       = rb_define_module("OpenSSL");
+    VALUE mOSSLCipher = rb_define_class_under(mOSSL, "Cipher", rb_cObject);
+    VALUE eOSSLError  = rb_define_class_under(mOSSL,"OpenSSLError",rb_eStandardError);
+
+    eCipherError = rb_define_class_under(mOSSLCipher, "CipherError", eOSSLError);
+
+    rb_define_method(mOSSLCipher, "aad=",     ossl_cipher_set_aad, 1);
+    rb_define_method(mOSSLCipher, "gcm_tag",  ossl_cipher_get_tag, 0);
+    rb_define_method(mOSSLCipher, "gcm_tag=", ossl_cipher_set_tag, 1);
+    rb_define_method(mOSSLCipher, "verify",   ossl_cipher_verify,  0);
+}

data/ext/openssl/cipher/aead/extconf.rb

@@ -0,0 +1,6 @@
+require 'mkmf'
+
+have_header("openssl/ssl.h")
+have_library("ssl", "SSLv23_method")
+
+create_makefile('openssl/cipher/aead')

data/lib/aead.rb

@@ -0,0 +1,4 @@
+module AEAD
+  autoload :Cipher, 'aead/cipher'
+  autoload :Nonce,  'aead/nonce'
+end

data/lib/aead/cipher.rb

@@ -0,0 +1,221 @@
+require 'aead'
+
+require 'openssl'
+require 'openssl/cipher/aead'
+require 'securerandom'
+
+#
+# Wraps AEAD ciphers in a simplified interface.
+#
+class AEAD::Cipher
+  autoload :AES_256_GCM,              'aead/cipher/aes_256_gcm'
+  autoload :AES_256_CBC_HMAC_SHA_256, 'aead/cipher/aes_256_cbc_hmac_sha_256'
+  autoload :AES_256_CTR_HMAC_SHA_256, 'aead/cipher/aes_256_ctr_hmac_sha_256'
+
+  #
+  # Returns a particular Cipher implementation.
+  #
+  # @param [String] algorithm the AEAD implementation to use
+  # @return [Class] the cipher implementation
+  #
+  def self.new(algorithm)
+    # run normal Class#new if we're being called from a subclass
+    return super unless self == AEAD::Cipher
+
+    # TODO: ciphers should register themselves, as opposed to using a
+    # potentiall-unsafe const_get
+    self.const_get algorithm.tr('-', '_').upcase
+  end
+
+  #
+  # Returns a securely-generated key of appropriate length for the
+  # current Cipher.
+  #
+  # @return [String] a random key
+  #
+  def self.generate_key
+    SecureRandom.random_bytes(self.key_len)
+  end
+
+  #
+  # Returns a unique nonce for the current Cipher.
+  #
+  # @return [String] a random key
+  #
+  def self.generate_nonce
+    AEAD::Nonce.generate
+  end
+
+  #
+  # Does a constant-time comparison between two strings. Useful to
+  # avoid timing attacks when comparing a generated signature against
+  # a user-provided signature.
+  #
+  # @param [String] left any string
+  # @param [String] right any string
+  # @return [Boolean] whether or not the strings are equal
+  #
+  def self.signature_compare(left, right)
+    # short-circuit if the lengths are inequal
+    return false if left.to_s.bytesize != right.bytesize
+
+    # Constant-time string comparison algorithm:
+    #   1. Break both strings into bytes
+    #   2. Subtract the strings from one-another, byte by byte
+    #      (any non-equal bytes will subtract to a nonzero value)
+    #   3. OR the XOR'd bytes together
+    #   4. If the result is nonzero, the strings differed.
+    left   = left.bytes.to_a
+    right  = right.bytes.to_a
+    result = 0
+
+    left.length.times do |i|
+      result |= left[i] - right[i]
+    end
+
+    result == 0
+  end
+
+  #
+  # The length of keys of encryption keys used by the current Cipher.
+  #
+  # @return [Integer] the length of keys in bytes
+  #
+  def key_len
+    self.class.key_len
+  end
+
+  #
+  # The length of nonces used by the current Cipher.
+  #
+  # @return [Integer] the length of nonces in bytes
+  #
+  def nonce_len
+    self.class.nonce_len
+  end
+
+  #
+  # Encrypts a plaintext using the current Cipher.
+  #
+  # IMPORTANT: Do not ever encrypt data using the same nonce more than
+  # once given a particular secret key. Doing so will violate the
+  # security guarantees of the AEAD cipher.
+  #
+  # @param [String] nonce a unique nonce, never before used with the
+  #   current encryption key
+  # @param [String, nil] aad arbitrary additional authentication data that
+  #   must later be provided to decrypt the aead
+  # @param [String] plaintext arbitrary plaintext
+  # @return [String] the generated AEAD
+  #
+  def encrypt(nonce, aad, plaintext)
+    _verify_nonce_bytesize(nonce, self.nonce_len)
+    _verify_plaintext_presence(plaintext)
+
+    self._encrypt(
+       _pad_nonce(nonce),
+       aad,
+       plaintext
+    )
+  end
+
+  #
+  # Decrypts a plaintext using the current Cipher.
+  #
+  # @param [String] nonce the nonce used when encrypting the AEAD
+  # @param [String] aad the additional authentication data used when
+  #   encrypting the AEAD
+  # @param [String] aead the encrypted AEAD
+  # @return [String] the original plaintext
+  #
+  def decrypt(nonce, aad, aead)
+    _verify_nonce_bytesize(nonce, self.nonce_len)
+
+    self._decrypt(
+      _pad_nonce(nonce),
+      aad,
+      _extract_ciphertext(aead, self.tag_len),
+      _extract_tag(aead, self.tag_len)
+    )
+  end
+
+  protected
+
+  # The OpenSSL algorithm to be used by the cipher.
+  attr_accessor :algorithm
+
+  # The secret key provided by the user.
+  attr_accessor :key
+
+  #
+  # Initializes the cipher.
+  #
+  # @param [String] algorithm the full encryption mode to be used in
+  #   calls to {#cipher}.
+  # @param [String] key the encryption key supplied by the user
+  # @return [Cipher] the initialized Cipher
+  #
+  def initialize(algorithm, key)
+    _verify_key_bytesize(key, self.key_len)
+
+    self.algorithm = algorithm.dup.freeze
+    self.key       = key.dup.freeze
+
+    self.freeze
+  end
+
+
+  #
+  # Yields the {OpenSSL::Cipher} for the current {#algorithm}
+  #
+  def cipher(direction)
+    yield OpenSSL::Cipher.new(algorithm).send(direction)
+  end
+
+  #
+  # The length of initialization vectors used by the current Cipher.
+  #
+  # @return [Integer] the length of initialization vectors in bytes
+  #
+  def iv_len
+    self.class.iv_len
+  end
+
+  #
+  # The length of authentication tags generated by the current Cipher.
+  #
+  # @return [Integer] the length of authentication tags in bytes
+  #
+  def tag_len
+    self.class.tag_len
+  end
+
+  private
+
+  def _verify_key_bytesize(key, key_len)
+    raise ArgumentError, "key must be at least #{key_len} bytes" unless
+      key.bytesize >= key_len
+  end
+
+  def _verify_nonce_bytesize(nonce, nonce_len)
+    raise ArgumentError, "nonce must be at least #{nonce_len} bytes" unless
+      nonce.bytesize == nonce_len
+  end
+
+  def _verify_plaintext_presence(plaintext)
+    raise ArgumentError, 'plaintext must not be empty' unless
+      not plaintext.nil? and not plaintext.empty?
+  end
+
+  def _pad_nonce(nonce)
+    nonce.rjust(self.iv_len, "\0")
+  end
+
+  def _extract_ciphertext(ciphertext, tag_len)
+    ciphertext[ 0 .. -tag_len - 1 ].to_s
+  end
+
+  def _extract_tag(ciphertext, tag_len)
+    ciphertext[ -tag_len .. -1 ].to_s
+  end
+end