symmetric-encryption 0.4.0 → 0.5.0

data/README.md

@@ -50,27 +50,31 @@ names with encrypted_
 * More efficient replacement for attr_encrypted since only ActiveRecord Models
 are extended with encrypted_ behavior, rather than every object in the system
 * Custom validator for ActiveRecord Models
+* Stream based encryption and decryption so that large files can be read or
+  written with encryption
+* Stream based encryption and decryption also supports compression and decompression
+  on the fly
 
 ## Examples
 
 ### Encryption Example
 
-    Symmetric::Encryption.encrypt "Sensitive data"
+    SymmetricEncryption.encrypt "Sensitive data"
 
 ### Decryption Example
 
-    Symmetric::Encryption.decrypt "JqLJOi6dNjWI9kX9lSL1XQ==\n"
+    SymmetricEncryption.decrypt "JqLJOi6dNjWI9kX9lSL1XQ==\n"
 
 ### Validation Example
 
     class MyModel < ActiveRecord::Base
-      validates :encrypted_ssn, :symmetric_encrypted => true
+      validates :encrypted_ssn, :symmetric_encryption => true
     end
 
     m = MyModel.new
     m.valid?
     #  => false
-    m.encrypted_ssn = Symmetric::Encryption.encrypt('123456789')
+    m.encrypted_ssn = SymmetricEncryption.encrypt('123456789')
     m.valid?
     #  => true
 
@@ -85,9 +89,9 @@ For example config/database.yml
       host:     db1w
       database: myapp_production
       username: admin
-      password: <%= Symmetric::Encryption.try_decrypt "JqLJOi6dNjWI9kX9lSL1XQ==\n" %>
+      password: <%= SymmetricEncryption.try_decrypt "JqLJOi6dNjWI9kX9lSL1XQ==\n" %>
 
-Note: Use Symmetric::Encryption.try_decrypt method which will return nil if it
+Note: Use SymmetricEncryption.try_decrypt method which will return nil if it
   fails to decrypt the value, which is essential when the encryption keys differ
   between environments
 
@@ -100,6 +104,32 @@ Note: In order for the above technique to work in other YAML configuration files
     cfg = YAML.load(ERB.new(File.new(config_file).read).result)[Rails.env]
     raise("Environment #{Rails.env} not defined in redis.yml") unless cfg
 
+### Large File Encryption
+
+Example: Read and decrypt a line at a time from a file
+
+    SymmetricEncryption::Reader.open('encrypted_file') do |file|
+      file.each_line do |line|
+        puts line
+      end
+    end
+
+Example: Encrypt and write data to a file
+
+    SymmetricEncryption::Writer.open('encrypted_file') do |file|
+      file.write "Hello World\n"
+      file.write "Keep this secret"
+    end
+
+Example: Compress, Encrypt and write data to a file
+
+    SymmetricEncryption::Writer.open('encrypted_compressed.zip', :compress => true) do |file|
+      file.write "Hello World\n"
+      file.write "Compress this\n"
+      file.write "Keep this safe and secure\n"
+    end
+
+
 ### Generating encrypted passwords
 
 The following rake task can be used to generate encrypted passwords for the
@@ -236,7 +266,7 @@ startup, run the code below to initialize symmetric-encryption prior to
 attempting to encrypt or decrypt any data
 
     require 'symmetric-encryption'
-    Symmetric::Encryption.load!('config/symmetric-encryption.yml', 'production')
+    SymmetricEncryption.load!('config/symmetric-encryption.yml', 'production')
 
 Parameters:
 
@@ -246,7 +276,7 @@ Parameters:
 To manually generate the symmetric encryption keys, run the code below
 
     require 'symmetric-encryption'
-    Symmetric::Encryption.generate_symmetric_key_files('config/symmetric-encryption.yml', 'production')
+    SymmetricEncryption.generate_symmetric_key_files('config/symmetric-encryption.yml', 'production')
 
 Parameters:
 
@@ -358,8 +388,8 @@ Create a configuration file in config/symmetric-encryption.yml per the following
 Submit an issue ticket to request any of the following features:
 
 * Ability to entirely disable encryption for a specific environment.
-  Symmetric::Encryption.encrypt() would return the supplied data without encrypting it and
-  Symmetric::Encryption.decrypt() would return the supplied data without decrypting it
+  SymmetricEncryption.encrypt() would return the supplied data without encrypting it and
+  SymmetricEncryption.decrypt() would return the supplied data without decrypting it
 
 * Support for automatically compressing data prior to encrypting it when the
   data exceeds some predefined size. And automatically decompressing the data
@@ -371,7 +401,7 @@ Submit an issue ticket to request any of the following features:
 * Create rake task / generator to generate a sample configuration file
   with a new RSA Private key already in it
 
-* Ability to change Symmetric::Encryption configuration options from custom
+* Ability to change SymmetricEncryption configuration options from custom
   Rails initializers, rather than having everything in the config file.
   For example config.symmetric_encryption.cipher = 'aes-128-cbc'
 

data/Rakefile

@@ -4,20 +4,20 @@ $:.unshift lib unless $:.include?(lib)
 require 'rake/clean'
 require 'rake/testtask'
 require 'date'
-require 'symmetric/version'
+require 'symmetric_encryption/version'
 
 desc "Build gem"
 task :gem  do |t|
   gemspec = Gem::Specification.new do |s|
     s.name        = 'symmetric-encryption'
-    s.version     = Symmetric::VERSION
+    s.version     = SymmetricEncryption::VERSION
     s.platform    = Gem::Platform::RUBY
     s.authors     = ['Reid Morrison']
     s.email       = ['reidmo@gmail.com']
     s.homepage    = 'https://github.com/ClarityServices/symmetric-encryption'
     s.date        = Date.today.to_s
     s.summary     = "Symmetric Encryption for Ruby, and Ruby on Rails"
-    s.description = "Symmetric Encryption is a library to seamlessly enable symmetric encryption in a project, written in Ruby."
+    s.description = "SymmetricEncryption supports encrypting ActiveRecord data, Mongoid data, passwords in configuration files, encrypting and decrypting of large files through streaming"
     s.files       = FileList["./**/*"].exclude('*.gem', 'nbproject').map{|f| f.sub(/^\.\//, '')}
     s.has_rdoc    = true
   end

data/lib/symmetric-encryption.rb

@@ -1,16 +1,19 @@
-require 'symmetric/version'
-require 'symmetric/cipher'
-require 'symmetric/encryption'
+require 'symmetric_encryption/version'
+require 'symmetric_encryption/cipher'
+require 'symmetric_encryption/symmetric_encryption'
+require 'symmetric_encryption/reader'
+require 'symmetric_encryption/writer'
+require 'zlib'
 if defined?(Rails)
-  require 'symmetric/railtie'
+  require 'symmetric_encryption/railtie'
 end
 # attr_encrypted and Encrypted validator
 if defined?(ActiveRecord::Base)
-  require 'symmetric/extensions/active_record/base'
-  require 'symmetric/railties/symmetric_encrypted_validator'
+  require 'symmetric_encryption/extensions/active_record/base'
+  require 'symmetric_encryption/railties/symmetric_encryption_validator'
 end
 
 # field encryption for Mongoid
 if defined?(Mongoid)
-  require 'symmetric/extensions/mongoid/fields'
+  require 'symmetric_encryption/extensions/mongoid/fields'
 end

data/lib/symmetric_encryption/cipher.rb

@@ -0,0 +1,114 @@
+module SymmetricEncryption
+
+  # Hold all information related to encryption keys
+  # as well as encrypt and decrypt data using those keys
+  #
+  # Cipher is thread safe so that the same instance can be called by multiple
+  # threads at the same time without needing an instance of Cipher per thread
+  class Cipher
+    # Cipher to use for encryption and decryption
+    attr_reader :cipher, :version
+
+    # Future Use:
+    # attr_accessor :encoding, :version
+
+    # Generate a new Symmetric Key pair
+    #
+    # Returns a hash containing a new random symmetric_key pair
+    # consisting of a :key and :iv.
+    # The cipher is also included for compatibility with the Cipher initializer
+    def self.random_key_pair(cipher = 'aes-256-cbc', generate_iv = true)
+      openssl_cipher = OpenSSL::Cipher.new(cipher)
+      openssl_cipher.encrypt
+
+      {
+        :key    => openssl_cipher.random_key,
+        :iv     => generate_iv ? openssl_cipher.random_iv : nil,
+        :cipher => cipher
+      }
+    end
+
+    # Create a Symmetric::Key for encryption and decryption purposes
+    #
+    # Parameters:
+    #   :key
+    #     The Symmetric Key to use for encryption and decryption
+    #   :iv
+    #     Optional. The Initialization Vector to use with Symmetric Key
+    #   :cipher
+    #     Optional. Encryption Cipher to use
+    #     Default: aes-256-cbc
+    def initialize(parms={})
+      raise "Missing mandatory parameter :key" unless @key = parms[:key]
+      @iv = parms[:iv]
+      @cipher = parms[:cipher] || 'aes-256-cbc'
+      @version = parms[:version]
+    end
+
+    # AES Symmetric Encryption of supplied string
+    #  Returns result as a Base64 encoded string
+    #  Returns nil if the supplied str is nil
+    #  Returns "" if it is a string and it is empty
+    #
+    #  options:
+    #    :encoding
+    #       :base64 Return as a base64 encoded string
+    #       :binary Return as raw binary data string. Note: String can contain embedded nulls
+    #      Default: :base64
+    #    :compress
+    #      [true|false] Whether or not to compress the data _before_ encrypting
+    #      Default: false
+    def encrypt(str)
+      return if str.nil?
+      buf = str.to_s
+      return str if buf.empty?
+      crypt(:encrypt, buf)
+    end
+
+    # AES Symmetric Decryption of supplied string
+    #  Returns decrypted string
+    #  Returns nil if the supplied str is nil
+    #  Returns "" if it is a string and it is empty
+    def decrypt(str)
+      return if str.nil?
+      buf = str.to_s
+      return str if buf.empty?
+      crypt(:decrypt, buf)
+    end
+
+    # Return a new random key using the configured cipher
+    # Useful for generating new symmetric keys
+    def random_key
+      ::OpenSSL::Cipher::Cipher.new(@cipher).random_key
+    end
+
+    # Returns the block size for the configured cipher
+    def block_size
+      ::OpenSSL::Cipher::Cipher.new(@cipher).block_size
+    end
+
+    protected
+
+    # Only for use by Symmetric::EncryptedStream
+    def openssl_cipher(cipher_method)
+      openssl_cipher = ::OpenSSL::Cipher.new(self.cipher)
+      openssl_cipher.send(cipher_method)
+      openssl_cipher.key = @key
+      openssl_cipher.iv = @iv if @iv
+      openssl_cipher
+    end
+
+    # Creates a new OpenSSL::Cipher with every call so that this call
+    # is thread-safe
+    def crypt(cipher_method, string) #:nodoc:
+      openssl_cipher = ::OpenSSL::Cipher.new(self.cipher)
+      openssl_cipher.send(cipher_method)
+      openssl_cipher.key = @key
+      openssl_cipher.iv = @iv if @iv
+      result = openssl_cipher.update(string)
+      result << openssl_cipher.final
+    end
+
+  end
+
+end

data/lib/{symmetric → symmetric_encryption}/extensions/active_record/base.rb

@@ -3,7 +3,7 @@ module ActiveRecord #:nodoc:
 
     class << self # Class methods
       # Much lighter weight encryption for Rails attributes matching the
-      # attr_encrypted interface using Symmetry::Encryption
+      # attr_encrypted interface using SymmetricEncryption
       #
       # The regular attr_encrypted gem uses Encryptor that adds encryption to
       # every Ruby object which is a complete overkill for this simple use-case
@@ -31,7 +31,7 @@ module ActiveRecord #:nodoc:
             # If this method is not called, then the encrypted value is never decrypted
             def #{attribute}
               if @stored_encrypted_#{attribute} != self.encrypted_#{attribute}
-                @#{attribute} = ::Symmetric::Encryption.decrypt(self.encrypted_#{attribute})
+                @#{attribute} = ::SymmetricEncryption.decrypt(self.encrypted_#{attribute})
                 @stored_encrypted_#{attribute} = self.encrypted_#{attribute}
               end
               @#{attribute}
@@ -40,7 +40,7 @@ module ActiveRecord #:nodoc:
             # Set the un-encrypted attribute
             # Also updates the encrypted field with the encrypted value
             def #{attribute}=(value)
-              self.encrypted_#{attribute} = @stored_encrypted_#{attribute} = ::Symmetric::Encryption.encrypt(value#{".to_yaml" if options[:marshal]})
+              self.encrypted_#{attribute} = @stored_encrypted_#{attribute} = ::SymmetricEncryption.encrypt(value#{".to_yaml" if options[:marshal]})
               @#{attribute} = value
             end
           UNENCRYPTED
@@ -129,7 +129,7 @@ module ActiveRecord #:nodoc:
           attribute_names.each_with_index do |attribute, index|
             encrypted_name = "encrypted_#{attribute}"
             if instance_methods.include? encrypted_name #.to_sym in 1.9
-              args[index] = ::Symmetric::Encryption.encrypt(args[index])
+              args[index] = ::SymmetricEncryption.encrypt(args[index])
               attribute_names[index] = encrypted_name
             end
           end
@@ -139,9 +139,6 @@ module ActiveRecord #:nodoc:
       end
 
       alias_method_chain :method_missing, :attr_encrypted
-      #Equivalent to:
-      #  alias_method :method_missing_without_attr_encrypted, :attr_encrypted # new, old
-      #  alias_method :attr_encrypted, :method_missing_with_attr_encrypted
 
     end
   end

data/lib/{symmetric → symmetric_encryption}/extensions/mongoid/fields.rb

@@ -9,12 +9,21 @@ module Mongoid
     module ClassMethods
       # Example:
       #
+      #  require 'mongoid'
+      #  require 'symmetric-encryption'
+      #
+      #  # Initialize Mongoid in a standalone environment. In a Rails app this is not required
+      #  Mongoid.logger = Logger.new($stdout)
+      #  Mongoid.load!('config/mongoid.yml')
+      #
+      #  # Initialize SymmetricEncryption in a standalone environment. In a Rails app this is not required
+      #  SymmetricEncryption.load!('config/symmetric-encryption.yml', 'test')
+      #
       #  class Person
       #    include Mongoid::Document
-      #    include Symmetric::Encryption::Mongoid
       #
       #    field :name,                             :type => String
-      #    field :encrypted_social_security_number, :type => String, :encrypted => true, :decrypt_as => :social_security_number
+      #    field :encrypted_social_security_number, :type => String, :encrypted => true
       #    field :age,                              :type => Integer
       #
       #  end
@@ -35,13 +44,13 @@ module Mongoid
       #   puts "Decrypted Social Security Number is: #{person.social_security_number}"
       #
       #   # Or is the same as
-      #   puts "Decrypted Social Security Number is: #{Symmetric::Encryption.decrypt(person.encrypted_social_security_number)}"
+      #   puts "Decrypted Social Security Number is: #{SymmetricEncryption.decrypt(person.encrypted_social_security_number)}"
       #
       #   # Sets the encrypted_social_security_number to encrypted version
       #   person.social_security_number = "123456789"
       #
       #   # Or, is equivalent to:
-      #   person.social_security_number = Symmetric::Encryption.encrypt("123456789")
+      #   person.social_security_number = SymmetricEncryption.encrypt("123456789")
       #
       #
       # Note: Unlike attr_encrypted finders must use the encrypted field name
@@ -58,10 +67,10 @@ module Mongoid
       # @param [ Symbol ] name The name of the field.
       # @param [ Hash ] options The options to pass to the field.
       #
-      # @option options [ Class ] :type The type of the field.
-      # @option options [ String ] :label The label for the field.
       # @option options [ Boolean ] :encryption If the field contains encrypted data.
       # @option options [ Symbol ] :decrypt_as Name of the getters and setters to generate to access the decrypted value of this field.
+      # @option options [ Class ] :type The type of the field.
+      # @option options [ String ] :label The label for the field.
       # @option options [ Object, Proc ] :default The field's default
       #
       # @return [ Field ] The generated field
@@ -69,7 +78,7 @@ module Mongoid
         if options.delete(:encrypted) == true
           decrypt_as = options.delete(:decrypt_as)
           unless decrypt_as
-            raise "Symmetric::Encryption for Mongoid. When encryption is enabled for a field it must either start with 'encrypted_' or the option :decrypt must be supplied" unless field_name.to_s.start_with?('encrypted_')
+            raise "SymmetricEncryption for Mongoid. When encryption is enabled for a field it must either start with 'encrypted_' or the option :decrypt must be supplied" unless field_name.to_s.start_with?('encrypted_')
             decrypt_as = field_name.to_s['encrypted_'.length..-1]
           end
 
@@ -77,7 +86,7 @@ module Mongoid
           underlying_type = options[:type]
           options[:type] = String
 
-          raise "Symmetric::Encryption for Mongoid currently only supports :type => String" unless underlying_type == String
+          raise "SymmetricEncryption for Mongoid currently only supports :type => String" unless underlying_type == String
 
           # #TODO Need to do type conversions. Currently only support String
 
@@ -86,7 +95,7 @@ module Mongoid
             # Set the un-encrypted bank account number
             # Also updates the encrypted field with the encrypted value
             def #{decrypt_as}=(value)
-              @stored_#{field_name} = Symmetric::Encryption.encrypt(value)
+              @stored_#{field_name} = SymmetricEncryption.encrypt(value)
               self.#{field_name} = @stored_#{field_name}
               @#{decrypt_as} = value
             end
@@ -96,7 +105,7 @@ module Mongoid
             # If this method is not called, then the encrypted value is never decrypted
             def #{decrypt_as}
               if @stored_#{field_name} != self.#{field_name}
-                @#{decrypt_as} = Symmetric::Encryption.decrypt(self.#{field_name})
+                @#{decrypt_as} = SymmetricEncryption.decrypt(self.#{field_name})
                 @stored_#{field_name} = self.#{field_name}
               end
               @#{decrypt_as}

data/lib/{symmetric → symmetric_encryption}/railtie.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
-module Symmetric #:nodoc:
+module SymmetricEncryption #:nodoc:
   class Railtie < Rails::Railtie #:nodoc:
 
     # Exposes Symmetric Encryption's configuration to the Rails application configuration.
@@ -10,7 +10,7 @@ module Symmetric #:nodoc:
     #       config.symmetric_encryption.cipher = 'aes-256-cbc'
     #     end
     #   end
-    #config.symmetric_encryption = ::Symmetric::Config
+    #config.symmetric_encryption = ::SymmetricEncryption::Config
 
     rake_tasks do
       load "symmetric/railties/symmetric_encryption.rake"
@@ -28,10 +28,10 @@ module Symmetric #:nodoc:
     #
     # Loaded before Active Record initializes since database.yml can have encrypted
     # passwords in it
-    initializer "load symmetric encryption keys" , :before=>"active_record.initialize_database" do
+    initializer "symmetric-encryption.initialize" , :before=>"active_record.initialize_database" do
       config_file = Rails.root.join("config", "symmetric-encryption.yml")
       if config_file.file?
-        ::Symmetric::Encryption.load!(config_file, Rails.env)
+        ::SymmetricEncryption.load!(config_file, Rails.env)
       else
         puts "\nSymmetric Encryption config not found. Create a config file at: config/symmetric-encryption.yml"
         #           puts "to generate one run: rails generate symmetric-encryption:config\n\n"

data/lib/{symmetric → symmetric_encryption}/railties/symmetric_encryption.rake

@@ -3,7 +3,7 @@ namespace :symmetric_encryption do
   desc 'Decrypt the supplied string. Example: VALUE="_encrypted_string_" rake symmetric_encryption:decrypt'
   task :decrypt => :environment do
     puts "\nEncrypted: #{ENV['VALUE']}"
-    puts "Decrypted: #{Symmetric::Encryption.decrypt(ENV['VALUE'])}\n\n"
+    puts "Decrypted: #{SymmetricEncryption.decrypt(ENV['VALUE'])}\n\n"
   end
 
   desc 'Encrypt a value, such as a password. Example: rake symmetric_encryption:encrypt'
@@ -20,19 +20,19 @@ namespace :symmetric_encryption do
         puts "Passwords do not match, please try again"
       end
     end
-    puts "\nEncrypted: #{Symmetric::Encryption.encrypt(password1)}\n\n"
+    puts "\nEncrypted: #{SymmetricEncryption.encrypt(password1)}\n\n"
   end
 
   desc 'Generate new Symmetric key and initialization vector. Example: RAILS_ENV=production rake symmetric_encryption:generate_symmetric_keys'
   task :generate_symmetric_keys do
-    Symmetric::Encryption.generate_symmetric_key_files
+    SymmetricEncryption.generate_symmetric_key_files
   end
 
   desc 'Generate a random password and display its encrypted form. Example: rake symmetric_encryption:random_password'
   task :random_password => :environment do
-    p = Symmetric::Encryption.random_password
+    p = SymmetricEncryption.random_password
     puts "\nGenerated Password: #{p}"
-    puts "Encrypted: #{Symmetric::Encryption.encrypt(p)}\n\n"
+    puts "Encrypted: #{SymmetricEncryption.encrypt(p)}\n\n"
   end
 
 end