column_cryptor 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 SCVNGR, 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,51 @@
+# column_cryptor
+
+`column_cryptor` is a gem that makes it easy to encrypt/decrypt ActiveRecord columns using a private key. If you need to store some sensitive information in your database, then this makes it easy to keep it encrypted.
+
+Note that `column_cryptor` is NOT a good solution for something like credit card information. Do everyone a favor and use a vault-like service. Instead, use `column_cryptor` to encrypt a user's phone number or other one-off bits of information you'd like to keep secret.
+
+## Getting Started
+
+Add to your Gemfile:
+
+    gem 'column_cryptor'
+
+then run `bundle install`.
+
+Next, use the generator to create an initializer with a random private key:
+
+    rails generate column_cryptor:install
+
+This will create a file called `config/initializers/column_cryptor.rb` that looks something like:
+
+    ColumnCryptor.private_key = "ssWII/MrFX8EmHMjG/5+un0mnYF5UeG2k7ajSjaKayU=\n"
+
+Those random characters represent a Base64-encoded private key suitable for encrypting and decrypting data using `column_cryptor`. It's recommended that you move that private key somewhere outside your code, such as to a yaml file or as an environment variable. Just be sure to set `ColumnCryptor.private_key` to your key.
+
+## Encrypting some data
+
+Once installed, you can then encrypt an ActiveRecord column like so:
+
+    class User < ActiveRecord::Base
+      encrypts :phone_number
+    end
+
+Getters and setters will be created for each column, automatically encrypting/decrypting `phone_number`.
+
+## Generating a new private key
+
+You can create a new private key using the `new_key` method:
+
+    ColumnCryptor.new_key
+
+This will return a Base64-encoded string representing a random private key. Be sure to leave it as-is (with the new-line at the end!) or ColumnCryptor won't know what do with it.
+
+Note that once you've started using a private key, if you ever lose it, all of your encrypted data will be lost with it. You also can't change your private key on the fly: you would need to first decrypt all of your data and then re-encrypt with your new private key.
+
+## Requirements
+
+`column_cryptor` requires Ruby 1.9+, and Rails 3.0 or later. The tests are written with Test::Unit and shoulda.
+
+## License
+
+`column_cryptor` is written by Ryan Twomey and Costa Walcott, and is Copyright 2012 SCVNGR, Inc. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.

data/Rakefile

@@ -0,0 +1,30 @@
+#!/usr/bin/env rake
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ColumnCryptor'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'rake/testtask'
+
+desc 'Test the paperclip plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib' << 'profile'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+task default: :test

data/lib/column_cryptor/core_ext.rb

@@ -0,0 +1 @@
+ActiveRecord::Base.send :include, ColumnCryptor

data/lib/column_cryptor/decryptor.rb

@@ -0,0 +1,48 @@
+module ColumnCryptor
+  # Given some ciphertext, attempts to decrypt it. Requires that ColumnCryptor.private_key be
+  # previously set to the same private key used to create the ciphertext.
+
+  class Decryptor
+    # Returns a new ColumnCryptor::Decryptor object initialized with the given ciphertext.
+    def initialize(encrypted_data)
+      @encrypted_data = encrypted_data
+    end
+
+    # Returns decrypted version of the Base64-encoded ciphertext.
+    def decrypt
+      unless @encrypted_data.blank?
+        plaintext_data
+      end
+    end
+
+    private
+
+    def decipher
+      @decipher ||= OpenSSL::Cipher::AES.new(256, :CBC).tap do |decipher|
+        decipher.decrypt
+        decipher.key = private_key
+      end
+    end
+
+    def deciphertext
+      decipher.update(decoded_data) + decipher.final
+    end
+
+    def decoded_data
+      @decoded_data ||= Base64.decode64(@encrypted_data)
+    end
+
+    def initialization_vector
+      decoded_data.slice! 0, decipher.block_size
+    end
+
+    def plaintext_data
+      decipher.iv = initialization_vector
+      deciphertext
+    end
+
+    def private_key
+      Base64.decode64 ColumnCryptor.private_key
+    end
+  end
+end

data/lib/column_cryptor/encryptor.rb

@@ -0,0 +1,43 @@
+module ColumnCryptor
+  # Given some plaintext, attempts to encrypt it. Requires that ColumnCryptor.private_key be set.
+
+  class Encryptor
+    # Returns a new ColumnCryptor::Encryptor object initialized with the given plaintext.
+    def initialize(plaintext)
+      @plaintext = plaintext
+    end
+
+    # Returns a Base64-encoded string of the encrypted (ciphertext) version of the plaintext.
+    def encrypt
+      unless @plaintext.blank?
+        Base64.encode64 encrypted_data
+      end
+    end
+
+    private
+
+    def cipher
+      @cipher ||= OpenSSL::Cipher::AES.new(256, :CBC).tap do |cipher|
+        cipher.encrypt
+        cipher.key = private_key
+      end
+    end
+
+    def ciphertext
+      cipher.update(@plaintext) + cipher.final
+    end
+
+    def encrypted_data
+      cipher.iv = initialization_vector
+      initialization_vector + ciphertext
+    end
+
+    def initialization_vector
+      @initial_vector ||= cipher.random_iv
+    end
+
+    def private_key
+      Base64.decode64 ColumnCryptor.private_key
+    end
+  end
+end

data/lib/column_cryptor/version.rb

@@ -0,0 +1,4 @@
+module ColumnCryptor
+  #:nodoc:
+  VERSION = '0.1.0'
+end

data/lib/column_cryptor.rb

@@ -0,0 +1,87 @@
+# This gem makes it easy to encrypt and decrypt sensitive application data using ActiveRecord. It
+# adds a getter and setter for each encryptable column, transparently encrypting before writing to
+# the database, and decrypting when reading.
+#
+# Author::    Ryan Twomey  (mailto:ryant@scvngr.com)
+# Copyright:: Copyright (c) 2012 SCVNGR, Inc.
+# License::   MIT
+
+# Sets up ColumnCryptor and includes it on all ActiveRecord::Base objects.
+
+require 'active_support/core_ext/string'
+require 'base64'
+require 'openssl'
+
+require 'column_cryptor/decryptor'
+require 'column_cryptor/encryptor'
+require 'column_cryptor/version'
+
+module ColumnCryptor
+  @@private_key = nil
+
+  #:nodoc:
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  # Returns a randomly generated key, Base64 encoded, suitable for sending to
+  # ColumnCryptor.private_key=
+  def self.new_key
+    Base64.encode64 cipher.random_key
+  end
+
+  # Sets the globally-used private key for all encryption/decryption operations.
+  def self.private_key=(private_key)
+    @@private_key = private_key
+  end
+
+  # Returns the currently set private_key, or nil.
+  def self.private_key
+    @@private_key
+  end
+
+  module ClassMethods
+    # Define which columns to mark as being encrypted. For example, if your ActiveRecord model has
+    # two columns you'd like to encrypt named "address" and "phone_number", you would call this as:
+    #
+    # encrypts :address, :phone_number
+    #
+    # This will define two methods for each attribute: a getter (i.e. "address") and a setter
+    # (i.e. "address="). The getter will automatically attempt to decrypt the data, while the
+    # setter will attempt to encrypt the data. When ActiveRecord writes your record to the database,
+    # the values of these columns will be the ciphertext.
+    #
+    # Note that you must set ColumnCryptor.private_key prior to using these setters/getters.
+    def encrypts(*args)
+      if args.respond_to?(:each)
+        args.each do |attribute|
+          define_encryption_methods attribute
+        end
+      else
+        define_encryption_methods args
+      end
+    end
+
+    private
+
+    def define_encryption_methods(attribute)
+      define_method attribute do
+        encrypted_data = send("#{attribute}_encrypted")
+        ColumnCryptor::Decryptor.new(encrypted_data).decrypt
+      end
+
+      define_method "#{attribute}=" do |new_value|
+        encrypted_data = ColumnCryptor::Encryptor.new(new_value).encrypt
+        send "#{attribute}_encrypted=", encrypted_data
+      end
+    end
+  end
+
+  private
+
+  def self.cipher
+    OpenSSL::Cipher::AES.new(256, :CBC)
+  end
+end
+
+require 'column_cryptor/core_ext'

data/lib/generators/column_cryptor/install/install_generator.rb

@@ -0,0 +1,18 @@
+require 'rails/generators/active_record'
+
+module ColumnCryptor
+  # Creates an initializer with a random private key
+  class InstallGenerator < Rails::Generators::Base
+    desc 'Add the column_cryptor initializer'
+
+    #:nodoc:
+    def self.source_root
+      @source_root ||= File.expand_path('../templates', __FILE__)
+    end
+
+    #:nodoc:
+    def install_initializer
+      template 'initializer.rb.erb', 'config/initializers/column_cryptor.rb'
+    end
+  end
+end

data/lib/generators/column_cryptor/install/templates/initializer.rb.erb

@@ -0,0 +1 @@
+ColumnCryptor.private_key = <%= ColumnCryptor.new_key.inspect %>

data/test/column_cryptor/decryptor_test.rb

@@ -0,0 +1,31 @@
+require './test/test_helper'
+require 'base64'
+
+class DecryptorTest < ActiveSupport::TestCase
+  context '#decrypt' do
+    setup do
+      ColumnCryptor.private_key = "dKY56fUpxMF2gmOxDzWoEm1z7bUJwe1jj9a2962T0GA=\n"
+    end
+
+    context 'with no data' do
+      setup do
+        @decryptor = ColumnCryptor::Decryptor.new(nil)
+      end
+
+      should 'return nil' do
+        assert_nil @decryptor.decrypt
+      end
+    end
+
+    context 'with encrypted data' do
+      setup do
+        decryptor = ColumnCryptor::Decryptor.new("xxl4Ny2fGdOKYaEXTDqdOWoNRNd4hT1xe9GlPQ7qWxE=\n")
+        @result = decryptor.decrypt
+      end
+
+      should 'decrypt to plaintext' do
+        assert_equal 'abc123', @result
+      end
+    end
+  end
+end

data/test/column_cryptor/encryptor_test.rb

@@ -0,0 +1,35 @@
+require './test/test_helper'
+require 'base64'
+
+class EncryptorTest < ActiveSupport::TestCase
+  context '#encrypt' do
+    setup do
+      ColumnCryptor.private_key = "dKY56fUpxMF2gmOxDzWoEm1z7bUJwe1jj9a2962T0GA=\n"
+    end
+
+    context 'with no data' do
+      setup do
+        @encryptor = ColumnCryptor::Encryptor.new(nil)
+      end
+
+      should 'return nil' do
+        assert_nil @encryptor.encrypt
+      end
+    end
+
+    context 'with plaintext data' do
+      setup do
+        cipher = OpenSSL::Cipher::AES.new(256, :CBC)
+        cipher.stubs random_iv: Base64.decode64('xxl4Ny2fGdOKYaEXTDqdOQ==\n')
+        OpenSSL::Cipher::AES.stubs new: cipher
+
+        @encryptor = ColumnCryptor::Encryptor.new('abc123')
+        @expected = "xxl4Ny2fGdOKYaEXTDqdOWoNRNd4hT1xe9GlPQ7qWxE=\n"
+      end
+
+      should 'encrypt data' do
+        assert_equal @expected, @encryptor.encrypt
+      end
+    end
+  end
+end

data/test/column_cryptor_test.rb

@@ -0,0 +1,57 @@
+require './test/test_helper'
+
+class ColumnCryptorTest < ActiveSupport::TestCase
+  context '.included' do
+    context 'on the class' do
+      setup do
+        @test_class = Class.new(ActiveRecord::Base)
+      end
+
+      should 'define encrypts method' do
+        assert @test_class.respond_to?(:encrypts)
+      end
+    end
+
+    context 'on the instance' do
+      setup do
+        test_class = Class.new(ActiveRecord::Base) do
+          encrypts :secret_data
+        end
+
+        klass = Object.const_set('Dummy', test_class)
+        create_table 'dummies'
+
+        @test_object = klass.new
+      end
+
+      should 'define getter and setter methods' do
+        assert @test_object.respond_to?(:secret_data)
+        assert @test_object.respond_to?(:secret_data=)
+      end
+    end
+  end
+
+  context '.new_key' do
+    setup do
+      key_str = 'abc123'
+      cipher = stub(random_key: key_str)
+      OpenSSL::Cipher::AES.stubs new: cipher
+
+      @expected = Base64.encode64(key_str)
+    end
+
+    should 'return expected key' do
+      assert_equal @expected, ColumnCryptor.new_key
+    end
+  end
+
+  context '.private_key' do
+    setup do
+      ColumnCryptor.private_key = 'abc123'
+    end
+
+    should 'return abc123' do
+      assert_equal 'abc123', ColumnCryptor.private_key
+    end
+  end
+end