strongbox 0.2.0

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2009 Joseph A. Ilacqua, Jr
+
+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.textile

@@ -0,0 +1,178 @@
+h1. Strongbox
+
+Strongbox provides Public Key Encryption for ActiveRecord. By using a public key
+sensitive information can be encrypted and stored automatically. Once stored a
+password is required to access the information.
+
+Because the largest amount of data that can practically be encrypted with a public
+key is 245 byte, by default Strongbox uses a two layer approach. First it encrypts
+the attribute using symmetric encryption with a randomly generated key and
+initialization vector (IV) (which can just be through to as a second key), then it
+encrypts those with the public key.
+
+Strongbox stores the encrypted attribute in a database column by the same name, i.e.
+if you tell Strongbox to encrypt "secret" then it will be store in "secret" in the
+database, just as the unencrypted attribute would be. If symmetric encryption is used
+(the default) two additional columns "secret_key" and "secret_iv" are needed as well.
+
+The attribute is automatically encrypted simply by setting it:
+
+  user.secret = "Shhhhhhh..."
+
+and decrypted by calling the "decrypt" method with the private key password.
+
+  plain_text = user.secret.decrypt 'letmein'
+
+h2. Quick Start
+
+In your model:
+
+  class User < ActiveRecord::Base
+    encrypt_with_public_key :secret,
+      :key_pair => File.join(RAILS_ROOT,'config','keypair.pem'),
+  end
+  
+In your migrations:
+
+  class AddSecretColumnsToUser < ActiveRecord::Migration
+    def self.up
+      add_column :users, :secret, binary
+      add_column :users, :secret_key, binary
+      add_column :users, :secret_iv, binary
+    end
+    def self.down
+      remove_column :users, :secret
+      remove_column :users, :secret_key
+      remove_column :users, :secret_iv
+    end  
+  end
+  
+Generate a key pair:
+
+(Choose a strong password.)
+
+  openssl genrsa -des3 -out config/private.pem 2048
+  openssl rsa -in config/private.pem -out config/public.pem -outform PEM -pubout
+  cat config/private.pem  config/public.pem >> config/keypair.pem
+
+In your views and forms you don't need to do anything special to encrypt data. To
+decrypt call:
+
+  user.secret.decrypt 'password'
+
+h2. Gem installation (Rails 2.1+)
+
+In config/environment.rb:
+
+    config.gem "spikex-strongbox", 
+      :lib     => 'strongbox', 
+      :source  => 'http://gems.github.com', 
+
+h2. Usage
+
+_encrypt_with_public_key_ sets up the attribute it's called on for automatic
+encryption.  It's simplest form is:
+
+  class User < ActiveRecord::Base
+    encrypt_with_public_key :secret,
+      :key_pair => File.join(RAILS_ROOT,'config','keypair.pem')
+    end
+  end
+
+Which will encrypt the attribute "secret". The attribute will be encrypted using
+symmetric encryption with an automatically generated key and IV encrypted using the
+public key. This requires three columns in the database "secret", "secret_key", and
+"secret_iv" (see below).
+
+Options to encrypt_with_public_key are:
+
+:public_key - Path to the public key file.  Overrides :keypair.
+
+:private_key - Path to the private key file.  Overrides :keypair.
+
+:keypair - Path to a file containing both the public and private keys.
+
+:symmetric :always/:never - Encrypt the date using symmetric encryption. The public
+key is used to encrypt an automatically generated key and IV. This allows for large
+amounts of data to be encrypted. The size of data that can be encrypted directly with
+the public is limit to key size (in bytes) - 11. So a 2048 key can encrypt *245 bytes*. Defaults to :always
+
+:symmetric_cipher - Cipher to use for symmetric encryption.  Defaults to *'aes-256-cbc'*.  Other ciphers support by OpenSSL may be used.
+
+:base64 true/false - Use Base64 encoding to convert encrypted data to text. Use when
+binary save data storage is not available.  Defaults to *false*
+
+:padding - Method used to pad data encrypted with the public key. Defaults to
+RSA_PKCS1_PADDING. The default should be fine unless you are dealing with legacy
+data.
+
+For example, encrypting a small attribute, providing only the public key for extra
+security, and Base64 encoding the encrypted data:
+
+  class User < ActiveRecord::Base
+    validates_length_of :pin_code, :is => 4
+    encrypt_with_public_key :pin_code, 
+      :symmetric => :never
+      :base64 => true
+      :public_key => File.join(RAILS_ROOT,'config','public.pem'),
+    end
+  end
+
+h2. Key Generation
+
+Generate a key pair:
+
+  openssl genrsa -des3 -out config/private.pem 2048
+  Generating RSA private key, 2048 bit long modulus
+  ......+++
+  .+++
+  e is 65537 (0x10001)
+  Enter pass phrase for config/private.pem:
+  Verifying - Enter pass phrase for config/private.pem:
+
+and extract the the public key:
+
+  openssl rsa -in config/private.pem -out config/public.pem -outform PEM -pubout
+  Enter pass phrase for config/private.pem:
+  writing RSA key
+
+If you are going to leave the private key installed it's easiest to create a single
+key pair file:
+
+  cat config/private.pem  config/public.pem >> config/keypair.pem
+
+Or, for added security, store the private key file else where, leaving only the public key.
+
+h2. Table Creation
+
+In it's default configuration Strongbox requires three columns, one the encrypted
+data, one for the encrypted symmetric key, and one for the encrypted symmetric IV. If
+symmetric encryption is disabled then only the columns for the data being encrypted
+is needed.
+
+If your underlying database allows, use the *binary* column type. If you must store
+your data in text format be sure to enable Base64 encoding and to use the *text*
+column type. The _string_ column type is likely to be too small to hold the encrypted
+string.
+
+h2. Security Caveats
+
+If you don't encrypt your data, then an attacker only needs to steal that data to get
+your secrets.
+
+If encrypt your data using symmetric encrypts and a stored key, then the attacker
+needs the data and the key stored on the server.
+
+If you use public key encryption, the attacker needs the data, the private key, and
+the password. This means the attacker has to sniff the password somehow, so that's
+what you need to protect against.
+
+h2. Authors
+
+Spike Ilacqua
+
+h2. Thanks
+
+Strongbox's implementation drew inspiration from Thoughtbot's Paperclip gem
+http://www.thoughtbot.com/projects/paperclip
+

data/Rakefile

@@ -0,0 +1,43 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+$LOAD_PATH << File.join(File.dirname(__FILE__), 'lib')
+require 'strongbox'
+
+desc 'Default: run tests.'
+task :default => :test
+
+desc 'Test the strongbox gem.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib' << 'profile'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the strongbox gem.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title = 'Strongbox'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s|
+  s.name = "strongbox"
+  s.version = Strongbox::VERSION
+  s.summary = "Secures ActiveRecord fields with public key encryption."
+  s.authors = ["Spike Ilacqua"]
+  s.email = "spike@stuff-things.net"
+  s.homepage = "http://stuff-things.net/strongbox"
+  s.files = FileList["[A-Z]*", "init.rb", "{lib,rails}/**/*"]
+  s.add_development_dependency 'thoughtbot-shoulda'
+end
+
+desc "Generate a gemspec file for GitHub"
+task :gemspec do
+  File.open("#{spec.name}.gemspec", 'w') do |f|
+    f.write spec.to_yaml
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'strongbox'

data/lib/strongbox.rb

@@ -0,0 +1,75 @@
+require 'openssl'
+require 'base64'
+
+require 'strongbox/lock'
+
+module Strongbox
+
+  VERSION = "0.2.0"
+
+  RSA_PKCS1_PADDING	= OpenSSL::PKey::RSA::PKCS1_PADDING
+  RSA_SSLV23_PADDING	= OpenSSL::PKey::RSA::SSLV23_PADDING
+  RSA_NO_PADDING		= OpenSSL::PKey::RSA::NO_PADDING
+  RSA_PKCS1_OAEP_PADDING	= OpenSSL::PKey::RSA::PKCS1_OAEP_PADDING
+  
+  class << self
+    # Provides for setting the default options for Strongbox
+    def options
+      @options ||= {
+        :base64 => false,
+        :symmetric => :always,
+        :padding => RSA_PKCS1_PADDING,
+        :symmetric_cipher => 'aes-256-cbc'
+      }
+    end
+    
+    def included base #:nodoc:
+      base.extend ClassMethods
+    end
+  end
+
+  class StrongboxError < StandardError #:nodoc:
+  end
+  
+  module ClassMethods
+    # +encrypt_with_public_key+ gives the class it is called on an attribute that
+    # when assigned is automatically encrypted using a public key.  This allows the
+    # unattended encryption of data, without exposing the information need to decrypt
+    # it (as would be the case when using symmetric key encryption alone).  Small
+    # amounts of data may be encrypted directly with the public key.  Larger data is
+    # encrypted using symmetric encryption. The encrypted data is stored in the
+    # database column of the same name as the attibute.  If symmetric encryption is
+    # used (the default) additional column are need to store the generated password
+    # and IV.
+    def encrypt_with_public_key(name, options = {})
+      include InstanceMethods
+
+      class_inheritable_reader :lock_options
+      write_inheritable_attribute(:lock_options, {}) if lock_options.nil?
+
+
+      lock_options[name] = options.symbolize_keys.reverse_merge Strongbox.options
+          
+      define_method name do
+        lock_for(name)
+      end
+      
+      define_method "#{name}=" do | plaintext |
+        lock_for(name).encrypt plaintext
+      end
+      
+    end
+  end
+  
+  module InstanceMethods
+    def lock_for name
+      @_locks ||= {}
+      @_locks[name] ||= Lock.new(name, self, self.class.lock_options[name])
+    end
+  end
+end
+
+if Object.const_defined?("ActiveRecord")
+  ActiveRecord::Base.send(:include, Strongbox)
+end
+

data/lib/strongbox/lock.rb

@@ -0,0 +1,115 @@
+module Strongbox
+  # The Lock class encrypts and decrypts the protected attribute.  It 
+  # automatically encrypts the data when set and decrypts it when the private
+  # key password is provided.
+  class Lock
+      
+    def initialize name, instance, options = {}
+      @name              = name
+      @instance          = instance
+      
+      @size = nil
+      
+      options = Strongbox.options.merge(options)
+      
+      @base64 = options[:base64]
+      @public_key = options[:public_key] || options[:key_pair]
+      @private_key = options[:private_key] || options[:key_pair]
+      @padding = options[:padding]
+      @symmetric = options[:symmetric]
+      @symmetric_cipher = options[:symmetric_cipher]
+      @symmetric_key = options[:symmetric_key] || "#{name}_key"
+      @symmetric_iv = options[:symmetric_iv] || "#{name}_iv"
+    end
+    
+    def encrypt plaintext
+      unless @public_key
+        raise StrongboxError.new("#{@instance.class} model does not have public key_file")
+      end
+      if !plaintext.blank?
+        @size = plaintext.size # For validations
+        # Using a blank password in OpenSSL::PKey::RSA.new prevents reading
+        # the private key if the file is a key pair
+        public_key = OpenSSL::PKey::RSA.new(File.read(@public_key),"")
+        if @symmetric == :always
+          cipher = OpenSSL::Cipher::Cipher.new(@symmetric_cipher)
+          cipher.encrypt
+          cipher.key = random_key = cipher.random_key
+          cipher.iv = random_iv = cipher.random_iv
+
+          ciphertext = cipher.update(plaintext)
+          ciphertext << cipher.final
+          encrypted_key = public_key.public_encrypt(random_key,@padding)
+          encrypted_iv = public_key.public_encrypt(random_iv,@padding)
+          if @base64
+            encrypted_key = Base64.encode64(encrypted_key)
+            encrypted_iv = Base64.encode64(encrypted_iv)
+          end
+          @instance.write_attribute(@symmetric_key,encrypted_key)
+          @instance.write_attribute(@symmetric_iv,encrypted_iv)
+        else
+          ciphertext = public_key.public_encrypt(plaintext,@padding)
+        end
+        ciphertext =  Base64.encode64(ciphertext) if @base64
+        @instance.write_attribute(@name,ciphertext)
+      end
+    end
+    
+    # Given the private key password decrypts the attribute.  Will raise
+    # OpenSSL::PKey::RSAError if the password is wrong.
+    
+    def decrypt password = ""
+      # Given a private key and a nil password OpenSSL::PKey::RSA.new() will
+      # *prompt* for a password, we default to an empty string to avoid that.
+      ciphertext = @instance.read_attribute(@name)
+      return nil if ciphertext.nil?
+      return "" if ciphertext.empty?
+      
+      return "*encrypted*" if password.blank?
+
+      unless @private_key
+        raise StrongboxError.new("#{@instance.class} model does not have private key_file")
+      end
+      
+      if ciphertext
+        ciphertext = Base64.decode64(ciphertext) if @base64
+        private_key = OpenSSL::PKey::RSA.new(File.read(@private_key),password)
+        if @symmetric == :always
+          random_key = @instance.read_attribute(@symmetric_key)
+          random_iv = @instance.read_attribute(@symmetric_iv)
+          if @base64
+            random_key = Base64.decode64(random_key)
+            random_iv = Base64.decode64(random_iv)
+          end
+          cipher = OpenSSL::Cipher::Cipher.new(@symmetric_cipher)
+          cipher.decrypt
+          cipher.key = private_key.private_decrypt(random_key,@padding)
+          cipher.iv = private_key.private_decrypt(random_iv,@padding)
+          plaintext = cipher.update(ciphertext)
+          plaintext << cipher.final
+        else
+          plaintext = private_key.private_decrypt(ciphertext,@padding)
+        end
+      else
+        nil
+      end
+    end
+    
+    def to_s
+      decrypt
+    end
+    
+    # Needed for validations
+    def blank?
+      @instance.read_attribute(@name).blank?
+    end
+    
+    def nil?
+      @instance.read_attribute(@name).nil?
+    end
+    
+    def size
+      @size
+    end
+  end
+end

data/rails/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__),'../init.rb')

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+name: strongbox
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Spike Ilacqua
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-28 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: spike@stuff-things.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- LICENSE
+- Rakefile
+- README.textile
+- init.rb
+- lib/strongbox/lock.rb
+- lib/strongbox.rb
+- rails/init.rb
+has_rdoc: true
+homepage: http://stuff-things.net/strongbox
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: Secures ActiveRecord fields with public key encryption.
+test_files: []
+