rjharmon-strongbox 0.3.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,271 @@
+h1. Strongbox
+
+Strongbox provides Public Key Encryption for ActiveRecord. By using a public key
+sensitive information can be encrypted and stored automatically. Once stored, the
+private key and password are required to access the information.
+
+Because the largest amount of data that can practically be encrypted with a 2048-bit 
+public key is 245 bytes, 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 thought of 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 have been.  If symmetric encryption 
+is used (the default) two additional columns "secret_key" and "secret_iv" are needed 
+as well.
+
+The attribute is automatically and immediately 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'
+
+The password for the private key can be empty if you are protecting the key through a 
+different method.  In that case, provide the empty string '' to decrypt() in order to 
+decrypt the data.
+
+This fork of Strongbox is also able to perform symmetric-only encryption.  If you 
+do this, be sure that you're protecting the symmetric key.  One application of this is
+for encrypting data to a private password known by the user.  See below for more options.
+
+h2. Quick Start
+
+In your model:
+
+bc. class User < ActiveRecord::Base
+  encrypt_with_public_key :secret,
+    :key_pair => File.join(RAILS_ROOT,'config','keypair.pem')
+end
+  
+In your migrations:
+
+bc. 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.)
+
+bc. 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:
+
+bc. user.secret.decrypt 'password'
+
+h2. Gem installation (Rails 2.1+)
+
+In config/environment.rb:
+
+bc. config.gem "strongbox"
+
+h2. Usage
+
+_encrypt_with_public_key_ sets up the attribute it's called on for automatic
+encryption.  It's simplest form is:
+
+bc. class User < ActiveRecord::Base
+  encrypt_with_public_key :secret,
+    :key_pair => File.join(RAILS_ROOT,'config','keypair.pem')
+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.
+
+:encrypt_iv true/false - Default is true for backward compatibility, but it is not 
+necessary to encrypt the initialization vector to maintain security.  For first-time
+installations, you might choose to set this to false, which cuts the encryption and
+decryption overhead approximately in half.  There is currently no method for 
+migrating encrypted iv's to clear-text iv's, but you could add a second set of columns 
+with a different configuration and write a script that decrypts values from one encrypted 
+column and stores them into to the second decrypted column.
+
+
+For example, encrypting a small attribute, providing only the public key for extra
+security, and Base64 encoding the encrypted data:
+
+bc. 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
+
+h2. Key Generation
+
+Generate a key pair:
+
+bc. 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:
+
+bc. 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:
+
+bc. 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. If you use a _string_ column and encrypt anything greater than 186 
+bytes (245 bytes if you don't enable Base64 encoding) *your data will be lost*.
+
+h2. Validation
+
+Because Strongbox immediately encrypts the data as you assign it into the model, 
+the amount of validation that can be done is minimal, being limited to 
+validates_size_of and validates_presence_of.  
+
+If you require additional validation for your encrypted columns, this should be done 
+before assigning into encrypted attributes.  That, or you might want to contribute a 
+patch that delays the encryption step until right before save.
+
+h2. Symmetric Encryption
+
+h3. Background
+
+Asymmetric encryption is generally far preferred over symmetric-only encryption.  
+Being able to physically separate and protect the private decryption key from the 
+public encryption key creates a level of potential security unmatchable with 
+symmetric encryption, which is reversible using the single encryption key.  
+
+However, symmetric keys can be useful in certain circumstances - for example the 
+combined symmetric/asymmetric encryption provided by default with 
+_encrypt_with_public_key_.  Other advanced examples include:
+
+* Encrypt data to a PIN code known only to the user (retrieve it only when they re-type their PIN)
+
+* Encrypt a PIN code with public key, then use the PIN to symmetrically encrypt other data, so 
+that it can be retrieved directly by the user but not by an attacker.  Combined with pubkey 
+encryption for the same data, much flexibility is gained with a minimum of risk exposure - though
+it comes with a tradeoff: increased code complexity.
+
+h3. Implementing Symmetric Encryption
+
+If you don't understand the caveats above, please re-read them.  Then, if you are 
+prepared to do symmetric encryption, use _encrypt_with_symmetric_key_:
+
+bc. class User < ActiveRecord::Base
+  validates_length_of :pin_code, :is => 4
+  encrypt_with_symmetric_key :some_data, :encrypt_iv => false, :key_proc => :pin_key
+  attr_accessor :pin_key
+end
+
+All options are the same as for pubkey encryption, except that no keys may be specified.  
+Additionally, :encrypt_iv must be set to false, and the :key_proc must be specified as a 
+symbol referring to a function which will return the symmetric key.
+
+h3. Implementing the symmetric-key function
+
+Two examples should demonstrate the use of a function that returns symmetric keys.  They 
+correspond to the two use cases mentioned above.  
+
+Encrypting with a key not stored on the server:  This is easily implemented by creating 
+an attr_accessor on the model having the encrypted field.  
+
+bc. class User < ActiveRecord::Base
+  encrypt_with_symmetric_key :some_data, :encrypt_iv => false, :key_proc => :pin_key
+  attr_accessor :pin_key
+end
+
+In your controller, put the key into the model prior to storing or retrieving encrypted data.
+
+In the second example, we store the user's PIN, encrypted asymmetrically.  To encrypt 
+data to the PIN code, we go inside the security perimeter where we have the private key; 
+decrypt the PIN, then set it, possibly using the attr_accessor method, prior to encrypting 
+the symmetric data.
+
+Decryption for user-facing content is done the same way as in the first example.  
+
+Another method of implementing the :key_proc is as follows:
+
+bc. attr_writer :pin_key
+def pin_key
+  @pin_key || self.pin.decrypt('password')
+end
+
+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. Contributors
+
+Randy Harmon
+
+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/lock.rb

@@ -0,0 +1,190 @@
+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)
+      
+      @is_empty = true if @instance[@name].blank?
+      
+      @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"
+      @key_proc = options[:key_proc]
+      @encrypt_iv = options[:encrypt_iv]
+      if @symmetric == :only
+        if @encrypt_iv
+          raise ArgumentError, ":encrypt_iv should be set to false for :symmetric => :only encryption, since encrypting the iv requires a pubkey"
+        end
+        if @public_key
+          raise ArgumentError, ":public_key, :private_key and :key_pair are not used with :symmetric => :only"
+        end
+        unless @key_proc
+          raise ArgumentError, ":key_proc option is required.  This option specifies a proc or a symbol of a method on the instance, which will return a key used for the symmetric cypher."
+        end
+      else
+        if @key_proc
+          raise ArgumentError, ":key_proc is valid only when :symmetric => :only is specified, or when using encrypt_with_symmetric_key()"
+        end
+      end
+    end
+    
+    def encrypt plaintext
+      
+      unless @public_key or @symmetric == :only
+        raise StrongboxError.new("#{@instance.class} model does not have public key_file")
+      end
+      if !plaintext.blank?
+        @is_empty = false
+        @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 = get_rsa_key(@public_key,"")
+        if @symmetric == :always or @symmetric == :only
+          cipher = OpenSSL::Cipher::Cipher.new(@symmetric_cipher)
+          cipher.encrypt
+          
+          cipher.key = symmetric_key = case @key_proc
+          when Proc
+            @key_proc.call( @instance )
+          when Symbol
+            @instance.send( @key_proc )
+          else
+            cipher.random_key
+          end
+          cipher.iv = symmetric_iv = cipher.random_iv
+
+          ciphertext = cipher.update(plaintext)
+          ciphertext << cipher.final
+          unless @symmetric == :only
+            encrypted_key = public_key.public_encrypt(symmetric_key,@padding)
+          end
+          if @encrypt_iv
+            encrypted_iv = public_key.public_encrypt(symmetric_iv,@padding)
+          end
+          if @base64
+            unless @symmetric == :only
+              encrypted_key = Base64.encode64(encrypted_key)
+            end
+            encrypted_iv = Base64.encode64(encrypted_iv)
+          end
+          unless @symmetric == :only
+            @instance[@symmetric_key] = encrypted_key
+          end
+          if @encrypt_iv
+            @instance[@symmetric_iv] = encrypted_iv
+          else
+            @instance[@symmetric_iv] = symmetric_iv
+          end
+        else
+          ciphertext = public_key.public_encrypt(plaintext,@padding)
+        end
+        ciphertext =  Base64.encode64(ciphertext) if @base64
+        @instance[@name] = ciphertext
+      else
+        @size = 0
+        @instance[@name] = ""
+        @is_empty = true
+      end
+    end
+    
+    # Given the private key password decrypts the attribute.  Will raise
+    # OpenSSL::PKey::RSAError if the password is wrong.
+    
+    def decrypt password = nil
+      return "" if @is_empty
+      # 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[@name]
+      return nil if ciphertext.nil?
+      return "" if ciphertext.empty?
+      
+      return "*encrypted*" if password.nil? and ! @key_proc
+      unless @private_key or @symmetric == :only
+        raise StrongboxError.new("#{@instance.class} model does not have private key_file")
+      end
+      
+      if ciphertext
+        ciphertext = Base64.decode64(ciphertext) if @base64
+        private_key = get_rsa_key(@private_key,password)
+        
+        if @symmetric == :always || @symmetric == :only
+          symmetric_key = case @key_proc
+          when Proc
+            @key_proc.call( @instance )
+          when Symbol
+            @instance.send( @key_proc )
+          else
+            @instance[@symmetric_key]
+          end
+          symmetric_iv = @instance[@symmetric_iv]
+          
+          if @base64
+            if @symmetric == :always
+              symmetric_key = Base64.decode64(symmetric_key)
+            end
+            symmetric_iv = Base64.decode64(symmetric_iv)
+          end
+          cipher = OpenSSL::Cipher::Cipher.new(@symmetric_cipher)
+          cipher.decrypt
+          cipher.key = if @symmetric == :only
+            symmetric_key
+          else
+            private_key.private_decrypt(symmetric_key,@padding)
+          end
+          if @encrypt_iv
+            cipher.iv = private_key.private_decrypt(symmetric_iv,@padding)
+          else
+            cipher.iv = symmetric_iv
+          end
+          
+          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[@name].blank?
+    end
+    
+    def nil?
+      @instance[@name].nil?
+    end
+    
+    def size
+      @size
+    end
+
+private
+    def get_rsa_key(key,password = '')
+      return nil unless key
+      return key if key.is_a?(OpenSSL::PKey::RSA)
+      if key !~ /^-----BEGIN RSA/
+        key = File.read(key)
+      end
+      return OpenSSL::PKey::RSA.new(key,password)
+    end
+  end
+end

data/lib/strongbox.rb

@@ -0,0 +1,85 @@
+require 'openssl'
+require 'base64'
+
+require 'strongbox/lock'
+
+module Strongbox
+
+  VERSION = "0.3.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,
+        :encrypt_iv => true,
+        :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 = {})
+      strongbox_encryption( name, options )
+    end
+
+    def encrypt_with_symmetric_key( name, options = {})
+      options.merge!( :symmetric => :only )
+      strongbox_encryption( name, options )
+    end
+
+    def strongbox_encryption( 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/rails/init.rb

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

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: rjharmon-strongbox
+version: !ruby/object:Gem::Version 
+  version: 0.3.0
+platform: ruby
+authors: 
+- Spike Ilacqua
+- Randy Harmon
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-13 23:00:00 -08: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: r_j_h_box-sf@yahoo.com
+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.5
+signing_key: 
+specification_version: 3
+summary: Secures ActiveRecord fields with public key encryption.
+test_files: []
+