crypto_laser 0.0.4 → 0.0.5

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    crypto_laser (0.0.4)
+    crypto_laser (0.0.5)
 
 GEM
   remote: http://rubygems.org/

data/README.md

@@ -1,23 +1,18 @@
 Crypto Laser
 ============
 
-Simple library for symmetric authenticated encryption.  
+Simple, cross-platform library for symmetric authenticated encryption.
 
     key = SecureRandom.random_bytes(64)
     cipher_text = CryptoLaser.encrypt(key, "my secret message")
     plain_text = CryptoLaser.decrypt(key, cipher_text)
 
-Most of the work is done by the aead gem, which itself relies 
-on OpenSSL.  Since many users, ourselves included, are on 
-OS X, this library uses AES-256-CBC-HMAC-SHA-256 as the cipher
-and MAC.
+Note that the key must be a raw byte array exactly 64 bytes long.
+The cipher texts returned by encrypt are Base64-encoded.
 
-Additional features provided by this library are:
+The heavy lifting is done by Ruby's OpenSSL, so we use AES-256-CBC as
+the cipher and HMAC-SHA-256 as the MAC.  These algorithms should be
+available on all Ruby 1.9 installations (including those on OS X,
+Windows, and Linux).
 
-- Nonce management.  No one knows what a nonce is, so this
-   library just takes care of that for you.
-- Base64 encoding of ciphertexts for easy portability.
-- The value returned by encrypt includes the nonce and
-   the algorithm used to create the ciphertext.  The
-   algorithm is authenticated, allowing for later cipher
-   suite negotiation should AES-256-CBC prove unreliable.
+![alt text](https://github.com/goodsearch/crypto_laser/raw/master/crypto_laser.jpeg "pew pew pew")

data/crypto_laser.gemspec

@@ -3,7 +3,7 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "crypto_laser"
-  s.version     = "0.0.4"
+  s.version     = "0.0.5"
   s.authors     = %w(Goodsearch)
   s.email       = %w(dev@goodsearch.com)
   s.homepage    = "http://www.goodsearch.com"

data/lib/crypto_laser.rb

@@ -1,67 +1,86 @@
 require 'openssl'
 require 'base64'
 
-# Simple library for authenticated encryption.  Most of the work
-# is done by the aead gem, which itself punts to OpenSSL.
+# Simple, cross-platform library for symmetric
+# authenticated encryption.
 #
-# Additional features provided by this library are:
+#    key = SecureRandom.random_bytes(64)
+#    cipher_text = CryptoLaser.encrypt(key, "my secret message")
+#    plain_text = CryptoLaser.decrypt(key, cipher_text)
 #
-# - Nonce management.  No one knows what a nonce is, so this
-#    library just takes of that for you.
-# - Base64 encoding of ciphertexts (since we want to use the
-#    encrypted values in config files)
-# - The value returned by encrypt includes the nonce and
-#    the algorithm used to create the ciphertext (so we can
-#    upgrade to a stronger algorithm later if need be)
+# Note that the key must be a raw byte array exactly 64 bytes long.
+# The cipher texts returned by encrypt are Base64-encoded.
 
+# The heavy lifting is done by Ruby's OpenSSL, so we use AES-256-CBC as
+# the cipher and HMAC-SHA-256 as the MAC.  These algorithms should be
+# available on all Ruby 1.9 installations (including those on OS X,
+# Windows, and Linux).
 class CryptoLaser
 
-  def self.encrypt(key, plain_text)
-    enc_key = key[0...32]
-    mac_key = key[32...64]
+  def initialize(key)
+    @enc_key = key[0...32]
+    @mac_key = key[32...64]
+  end
 
-    code = CryptoLaser.default_algorithm_code
+  def encrypt(plain_text)
+    code = default_algorithm_code
 
-    cipher = OpenSSL::Cipher.new(CryptoLaser.algorithms[code])
+    cipher = OpenSSL::Cipher.new(cipher_algorithms[code])
     cipher.encrypt
-    cipher.key = enc_key
-    nonce = cipher.random_iv
-    cipher.iv = nonce
+    cipher.key = @enc_key
+    iv = cipher.random_iv
+    cipher.iv = iv
     cipher_text = cipher.update(plain_text) + cipher.final
 
-    text_to_mac = code + nonce + cipher_text
-    mac = OpenSSL::HMAC.digest(OpenSSL::Digest::Digest.new('sha256'), mac_key, text_to_mac)
+    text_to_mac = code + iv + cipher_text
+    mac = mac(text_to_mac)
 
     Base64.strict_encode64(text_to_mac + mac).chomp
   end
 
-  def self.decrypt(key, base64_cipher_text)
-    enc_key = key[0...32]
-    mac_key = key[32...64]
+  def decrypt(base64_cipher_text)
     cipher_text = Base64.decode64(base64_cipher_text)
 
-    code = cipher_text[0,2]
-    algorithm = CryptoLaser.algorithms[code]
+    algorithm = cipher_algorithms[cipher_text[0,2]]
     raise "Invalid algorithm code." unless algorithm
 
-    text_to_mac = cipher_text[0...-32]
-    mac = OpenSSL::HMAC.digest(OpenSSL::Digest::Digest.new('sha256'), mac_key, text_to_mac)
-    raise "MAC check failed" unless mac == cipher_text[-32..-1]
+    mac = mac(cipher_text[0...-32])
+    raise "MAC check failed" unless equal_macs(mac, cipher_text[-32..-1])
 
-    decipher = OpenSSL::Cipher.new(CryptoLaser.algorithms[code])
-    decipher.decrypt
-    decipher.key = enc_key
-    decipher.iv = cipher_text[2...18]
+    cipher = OpenSSL::Cipher.new(algorithm)
+    cipher.decrypt
+    cipher.key = @enc_key
+    cipher.iv = cipher_text[2...18]
 
-    decipher.update(cipher_text[18...-32]) +  decipher.final
+    cipher.update(cipher_text[18...-32]) +  cipher.final
   end
 
-  def self.algorithms
+  private
+
+  def cipher_algorithms
     { "V1" => 'AES-256-CBC' }
   end
 
-  def self.default_algorithm_code
+  def mac_algorithms
+    { "V1" => 'SHA256' }
+  end
+
+  def default_algorithm_code
     "V1"
   end
 
+  def mac(text)
+    algorithm = mac_algorithms[text[0...2]]
+    OpenSSL::HMAC.digest(OpenSSL::Digest::Digest.new(algorithm), @mac_key, text)
+  end
+
+  def sha256(x)
+    OpenSSL::Digest::SHA256.digest(x)
+  end
+
+  # Guards against timing attacks, just in case.
+  def equal_macs(mac1, mac2)
+    sha256(mac1) == sha256(mac2)
+  end
+
 end

data/spec/lib/crypto_laser_spec.rb

@@ -1,28 +1,50 @@
 require 'spec_helper'
 require 'crypto_laser'
+require 'securerandom'
 
 describe CryptoLaser do
 
+  raw_cipher_text = "V1\x97\x88\xF3\x0Ei\x84\x99\xC7 OZ2\xCA\v\x873\x10\xD5jf\xDD\x84\xCA?~\x87\xEE|\x92\xD7\xB8r\x8D*\x02\xB5\x82\xE9\xFD>\xB5\x80Fh.kuO\x91\xE5\xF7&\xCC\xB9E\xB4?c\xE1\xE2b%fM"
+
+  let(:instance) { described_class.new(key) }
+
   let(:key) { "\"/\\xE0x5\\x9A\\xE9\\x82\\xB8p \\xED^\\xFFX\\xF6\\xB3}\\xB9bR\\xCF\\xDAdH\\xE4\\x9D\\xB5\\xC2r\\x98\\xD3\\xFC\"" }
   let(:nonce) { "\x97\x88\xF3\x0Ei\x84\x99\xC7 OZ2\xCA\v\x873" }
-  let(:cipher_text) { "VjGXiPMOaYSZxyBPWjLKC4czENVqZt2Eyj9+h+58kte4co0qArWC6f0+tYBGaC5rdU+R5fcmzLlFtD9j4eJiJWZN" }
+
+  let(:cipher_text) { Base64.strict_encode64(raw_cipher_text).chomp }
   let(:plain_text) { "ZOMG PONIES" }
 
   describe "#encrypt" do
 
-    before { OpenSSL::Cipher.any_instance.stub(:random_iv).and_return nonce }
+    subject { instance.encrypt(plain_text) }
 
-    subject { described_class.encrypt(key, plain_text) }
+    context "simple encryption" do
+      before { OpenSSL::Cipher.any_instance.stub(:random_iv).and_return nonce }
+      it "encrypts plain text" do
+        subject.should == cipher_text
+      end
+    end
 
-    it "encrypts plain text" do
-      subject.should == cipher_text
+    context "multiple encryptions of the same plaintext" do
+      it "results in different ciphertexts" do
+        cipher1 = instance.encrypt(plain_text)
+        cipher2 = instance.encrypt(plain_text)
+        cipher1.should_not == cipher2
+      end
+    end
+
+    context "empty plaintext" do
+      subject { instance.encrypt("") }
+      it "fails fast" do
+        expect { subject }.to raise_error /data must not be empty/i
+      end
     end
 
   end
 
   describe "#decrypt" do
 
-    subject { described_class.decrypt(key, cipher_text) }
+    subject { instance.decrypt(cipher_text) }
 
     it "decrypts cipher text" do
       subject.should == plain_text
@@ -34,6 +56,12 @@ describe CryptoLaser do
       end
     end
 
+    shared_examples_for "raises because the MAC check fails" do
+      specify do
+        expect { subject }.to raise_error /mac check failed/i
+      end
+    end
+
     context "when the algorithm code is invalid" do
       let(:cipher_text) { Base64.encode64("V2").chomp }
       it_should_behave_like "raises because the code is invalid"
@@ -44,6 +72,31 @@ describe CryptoLaser do
       it_should_behave_like "raises because the code is invalid"
     end
 
+    context "when an adversary alters the ciphertext" do
+      (2...raw_cipher_text.size).each do |i|
+        context "when an adversary alters byte #{i - 2} of the cipher text" do
+          let(:cipher_text) do
+            raw_cipher_text[i] = (raw_cipher_text[i].ord ^ 1).chr
+            Base64.strict_encode64(raw_cipher_text)
+          end
+          it_should_behave_like "raises because the MAC check fails"
+        end
+      end
+    end
+
+  end
+
+  context "random large string round-trips" do
+
+    it "correctly decrypts" do
+      1000.times do
+        len = SecureRandom.random_number(8192) + 1
+        plain_text = SecureRandom.random_bytes(len)
+        cipher_text = instance.encrypt(plain_text)
+        instance.decrypt(cipher_text).should == plain_text
+      end
+    end
+
   end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: crypto_laser
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -65,6 +65,7 @@ files:
 - README.md
 - Rakefile
 - crypto_laser.gemspec
+- crypto_laser.jpeg
 - lib/crypto_laser.rb
 - lib/tasks/decrypt.rake
 - lib/tasks/encrypt.rake