encrypted_attributes 0.1.1 → 0.1.2

data/{CHANGELOG → CHANGELOG.rdoc}

@@ -1,29 +1,27 @@
-*SVN*
+== master
 
-*0.1.1* (June 22nd, 2008)
+== 0.1.2 / 2008-07-05
+
+* Leave salt stringification up to PluginAWeek::EncryptedString::ShaEncryptor
+
+== 0.1.1 / 2008-06-22
 
 * Remove log files from gems
 
-*0.1.0* (May 5th, 2008)
+== 0.1.0 / 2008-05-05
 
 * Don't extend encrypted_string's encryptors, instead creating subclasses
-
 * Don't assume anything about attribute confirmations
-
 * Support storing the salt for SHA encryption in the same string as the original value
-
 * Update documentation
 
-*0.0.2* (September 26th, 2007)
+== 0.0.2 / 2007-09-26
 
 * Move test fixtures out of the test application root directory
-
 * Convert dos newlines to unix newlines
 
-*0.0.1* (August 5th, 2007)
+== 0.0.1 / 2007-08-05
 
 * Official public release
-
 * Add documentation
-
 * Refactor unit test names

data/{README → README.rdoc}

@@ -5,21 +5,21 @@ attributes.
 
 == Resources
 
-Wiki
-
-* http://wiki.pluginaweek.org/Encrypted_attributes
-
 API
 
 * http://api.pluginaweek.org/encrypted_attributes
 
+Bugs
+
+* http://pluginaweek.lighthouseapp.com/projects/13269-encrypted_attributes
+
 Development
 
-* http://dev.pluginaweek.org/browser/trunk/encrypted_attributes
+* http://github.com/pluginaweek/encrypted_attributes
 
 Source
 
-* http://svn.pluginaweek.org/trunk/encrypted_attributes
+* git://github.com/pluginaweek/encrypted_attributes.git
 
 == Description
 
@@ -29,7 +29,7 @@ with the encrypted_strings plugin, helps make encrypting ActiveRecord
 attributes easier by automating the process.
 
 The options that +encrypts+ takes includes all of the encryption options for
-the specific type of encryptor being used in the encrypted_strings plugin.
+the specific type of encryptor being used from the encrypted_strings plugin.
 Therefore, if setting the key for asymmetric encryption, this would be passed
 into the +encrypts+ method.  Examples of this are show in the Usage section.
 
@@ -45,7 +45,7 @@ With the default salt:
     encrypts :password
   end
 
-With a custom salt:
+With a custom salt based on the record's values:
   class User < ActiveRecord::Base
     encrypts :password, :salt => :create_salt
     
@@ -55,7 +55,7 @@ With a custom salt:
       end
   end
 
-The salt and password values are combined and stored in the attributed being
+The salt and password values are combined and stored in the attribute being
 encrypted.  Therefore, there's no need to add a second column for storing the
 salt value.
 
@@ -83,7 +83,6 @@ With custom key files:
     encrypts :password, :mode => :asymmetric, :public_key_file => '/keys/public', :private_key_file => '/keys/private'
   end
 
-
 === Targeted Encryption
 
 If you want to store the encrypted value in a different attribute than the
@@ -105,13 +104,13 @@ parameters that determine whether the encryption should occur.  For example,
 === Additional information
 
 For more examples of actual migrations and models that encrypt attributes,
-see the unit tests.  Also, see encrypted_strings for more information about
-the various options that can be passed in.
+see the actual API and unit tests.  Also, see encrypted_strings for more
+information about the various options that can be passed in.
 
 == Testing
 
 Before you can run any tests, the following gem must be installed:
-* plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper]
+* plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]
 
 To run against a specific version of Rails:
 
@@ -120,4 +119,4 @@ To run against a specific version of Rails:
 == Dependencies
 
 * Rails 2.1 or later
-* encrypted_strings[http://wiki.pluginaweek.org/Encrypted_strings]
+* encrypted_strings[http://github.com/pluginaweek/encrypted_strings]

data/Rakefile

@@ -3,47 +3,55 @@ require 'rake/rdoctask'
 require 'rake/gempackagetask'
 require 'rake/contrib/sshpublisher'
 
-PKG_NAME           = 'encrypted_attributes'
-PKG_VERSION        = '0.1.1'
-PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
-RUBY_FORGE_PROJECT = 'pluginaweek'
-
-desc 'Default: run unit tests.'
+spec = Gem::Specification.new do |s|
+  s.name              = 'encrypted_attributes'
+  s.version           = '0.1.2'
+  s.platform          = Gem::Platform::RUBY
+  s.summary           = 'Adds support for automatically encrypting ActiveRecord attributes'
+  
+  s.files             = FileList['{lib,test}/**/*'].to_a - FileList['test/app_root/log/*'].to_a + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc)
+  s.require_path      = 'lib'
+  s.has_rdoc          = true
+  s.test_files        = Dir['test/**/*_test.rb']
+  s.add_dependency    'encrypted_strings', '>= 0.0.5'
+  
+  s.author            = 'Aaron Pfeifer'
+  s.email             = 'aaron@pluginaweek.org'
+  s.homepage          = 'http://www.pluginaweek.org'
+  s.rubyforge_project = 'pluginaweek'
+end
+  
+desc 'Default: run all tests.'
 task :default => :test
 
-desc 'Test the encrypted_attributes plugin.'
+desc "Test the #{spec.name} plugin."
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
-  t.pattern = 'test/**/*_test.rb'
+  t.test_files = spec.test_files
   t.verbose = true
 end
 
-desc 'Generate documentation for the encrypted_attributes plugin.'
+begin
+  require 'rcov/rcovtask'
+  namespace :test do
+    desc "Test the #{spec.name} plugin with Rcov."
+    Rcov::RcovTask.new(:rcov) do |t|
+      t.libs << 'lib'
+      t.test_files = spec.test_files
+      t.rcov_opts << '--exclude="^(?!lib/)"'
+      t.verbose = true
+    end
+  end
+rescue LoadError
+end
+
+desc "Generate documentation for the #{spec.name} plugin."
 Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'EncryptedAttributes'
+  rdoc.title    = spec.name
   rdoc.template = '../rdoc_template.rb'
-  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            = PKG_NAME
-  s.version         = PKG_VERSION
-  s.platform        = Gem::Platform::RUBY
-  s.summary         = 'Adds support for automatically encrypting ActiveRecord attributes'
-  
-  s.files           = FileList['{lib,test}/**/*'].to_a - FileList['test/app_root/log/*'].to_a + %w(CHANGELOG init.rb MIT-LICENSE Rakefile README)
-  s.require_path    = 'lib'
-  s.autorequire     = 'encrypted_attributes'
-  s.has_rdoc        = true
-  s.test_files      = Dir['test/**/*_test.rb']
-  s.add_dependency  'encrypted_strings', '>= 0.0.1'
-  
-  s.author          = 'Aaron Pfeifer'
-  s.email           = 'aaron@pluginaweek.org'
-  s.homepage        = 'http://www.pluginaweek.org'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'LICENSE', 'lib/**/*.rb')
 end
   
 Rake::GemPackageTask.new(spec) do |p|
@@ -52,14 +60,14 @@ Rake::GemPackageTask.new(spec) do |p|
   p.need_zip = true
 end
 
-desc 'Publish the beta gem'
+desc 'Publish the beta gem.'
 task :pgem => [:package] do
-  Rake::SshFilePublisher.new('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{PKG_FILE_NAME}.gem").upload
+  Rake::SshFilePublisher.new('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{spec.name}-#{spec.version}.gem").upload
 end
 
-desc 'Publish the API documentation'
+desc 'Publish the API documentation.'
 task :pdoc => [:rdoc] do
-  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{PKG_NAME}", 'rdoc').upload
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{spec.name}", 'rdoc').upload
 end
 
 desc 'Publish the API docs and gem'
@@ -72,10 +80,10 @@ task :release => [:gem, :package] do
   ruby_forge = RubyForge.new.configure
   ruby_forge.login
   
-  %w( gem tgz zip ).each do |ext|
-    file = "pkg/#{PKG_FILE_NAME}.#{ext}"
+  %w(gem tgz zip).each do |ext|
+    file = "pkg/#{spec.name}-#{spec.version}.#{ext}"
     puts "Releasing #{File.basename(file)}..."
     
-    ruby_forge.add_release(RUBY_FORGE_PROJECT, PKG_NAME, PKG_VERSION, file)
+    ruby_forge.add_release(spec.rubyforge_project, spec.name, spec.version, file)
   end
 end

data/lib/encrypted_attributes/sha_encryptor.rb

@@ -1,37 +1,45 @@
 module PluginAWeek #:nodoc:
   module EncryptedAttributes
-    # Supports encryption for ActiveRecord models by adding dynamically generated
-    # salts
+    # Adds support for dynamically generated salts
     class ShaEncryptor < PluginAWeek::EncryptedStrings::ShaEncryptor
-      def initialize(record, value, operation, options = {}) #:nodoc:
+      # Encrypts a string using a Secure Hash Algorithm (SHA), specifically SHA-1.
+      # 
+      # The <tt>:start</tt> configuration option can be any one of the following types:
+      # * +symbol+ - Calls the method on the object whose value is being encrypted
+      # * +proc+ - A block that will be invoked, providing it with the object whose value is being encrypted
+      # * +string+ - The actual salt value to use
+      def initialize(object, value, operation, options = {}) #:nodoc:
         if operation == :write
           # Figure out the actual salt value
           if salt = options[:salt]
             options[:salt] =
               case salt
               when Symbol
-                record.send(salt).to_s
+                object.send(salt)
               when Proc
-                salt.call(record).to_s
+                salt.call(object)
               else
                 salt
               end
           end
           
+          # Track whether or not the salt was generated dynamically
           @dynamic_salt = salt != options[:salt]
+          
           super(options)
         else
-          # The salt is in the value if it's dynamic
+          # The salt is at the end of the value if it's dynamic
           salt = value[40..-1]
           if @dynamic_salt = !salt.blank?
-            options.merge!(:salt => salt) 
+            options[:salt] = salt 
           end
           
           super(options)
         end
       end
       
-      # Encrypts the data, appending the salt to the end of the string
+      # Encrypts the data, appending the salt to the end of the string if it
+      # was created dynamically
       def encrypt(data)
         encrypted_data = Digest::SHA1.hexdigest(data + salt)
         encrypted_data << salt if @dynamic_salt

data/lib/encrypted_attributes.rb

@@ -11,65 +11,141 @@ module PluginAWeek #:nodoc:
       # Encrypts the specified attribute.
       # 
       # Configuration options:
-      # * +mode+ - The mode of encryption to use.  Default is sha.
-      # * +to+ - The attribute to write the encrypted value. Default is the same attribute being encryupted.
+      # * +mode+ - The mode of encryption to use.  Default is sha. See PluginAWeek::EncryptedStrings for other possible modes
+      # * +to+ - The attribute to write the encrypted value to. Default is the same attribute being encrypted.
       # * +if+ - Specifies a method, proc or string to call to determine if the encryption should occur. The method, proc or string should return or evaluate to a true or false value.
       # * +unless+ - Specifies a method, proc or string to call to determine if the encryption should not occur. The method, proc or string should return or evaluate to a true or false value. 
       # 
-      # For additional configuration options, see the individual encryptor class.
+      # For additional configuration options used during the actual encryption,
+      # see the individual encryptor class for the specified mode.
+      # 
+      # == Encryption timeline
+      # 
+      # Attributes are encrypted immediately before a record is validated.
+      # This means that you can still validate the presence of the encrypted
+      # attribute, but other things like password length cannot be validated
+      # without either (a) decrypting the value first or (b) using a different
+      # encryption target.  For example,
+      # 
+      #   class User < ActiveRecord::Base
+      #     encrypts :password, :to => :crypted_password
+      #     
+      #     validates_presence_of :password, :crypted_password
+      #     validates_length_of :password, :maximum => 16
+      #   end
+      # 
+      # In the above example, the actual encrypted password will be stored in
+      # the +crypted_password+ attribute.  This means that validations can
+      # still run against the model for the original password value.
+      # 
+      #   user = User.new(:password => 'secret')
+      #   user.password             # => "secret"
+      #   user.crypted_password     # => nil
+      #   user.valid?               # => true
+      #   user.crypted_password     # => "8152bc582f58c854f580cb101d3182813dec4afe"
+      #   
+      #   user = User.new(:password => 'longer_than_the_maximum_allowed')
+      #   user.valid?               # => false
+      #   user.crypted_password     # => "e80a709f25798f87d9ca8005a7f64a645964d7c2"
+      #   user.errors[:password]    # => "is too long (maximum is 16 characters)"
+      # 
+      # == Encryption mode examples
+      # 
+      # SHA encryption:
+      #   class User < ActiveRecord::Base
+      #     encrypts :password
+      #     # encrypts :password, :salt => :create_salt
+      #   end
+      # 
+      # Symmetric encryption:
+      #   class User < ActiveRecord::Base
+      #     encrypts :password, :mode => :symmetric
+      #     # encrypts :password, :mode => :symmetric, :key => 'custom'
+      #   end
+      # 
+      # Asymmetric encryption:
+      #   class User < ActiveRecord::Base
+      #     encrypts :password, :mode => :asymmetric
+      #     # encrypts :password, :mode => :asymmetric, :public_key_file => '/keys/public', :private_key_file => '/keys/private'
+      #   end
       def encrypts(attr_name, options = {})
         attr_name = attr_name.to_s
         to_attr_name = options.delete(:to) || attr_name
         
+        # Figure out what encryptor is being configured for the attribute
         mode = options.delete(:mode) || :sha
-        if mode == :sha
-          encryptor_class = "PluginAWeek::EncryptedAttributes::#{mode.to_s.classify}Encryptor".constantize
+        class_name = "#{mode.to_s.classify}Encryptor"
+        if PluginAWeek::EncryptedAttributes.const_defined?(class_name)
+          encryptor_class = PluginAWeek::EncryptedAttributes.const_get(class_name)
         else
-          encryptor_class = "PluginAWeek::EncryptedStrings::#{mode.to_s.classify}Encryptor".constantize
+          encryptor_class = PluginAWeek::EncryptedStrings.const_get(class_name)
         end
         
-        # Set the value immediately before validation takes place
+        # Set the encrypted value right before validation takes place
         before_validation(:if => options.delete(:if), :unless => options.delete(:unless)) do |record|
-          value = record.send(attr_name)
+          record.send(:write_encrypted_attribute, attr_name, to_attr_name, encryptor_class, options)
+          true
+        end
+        
+        # Define the reader when reading the encrypted attribute from the database
+        define_method(to_attr_name) do
+          read_encrypted_attribute(to_attr_name, encryptor_class, options)
+        end
+        
+        unless included_modules.include?(PluginAWeek::EncryptedAttributes::InstanceMethods)
+          include PluginAWeek::EncryptedAttributes::InstanceMethods
+        end
+      end
+    end
+    
+    module InstanceMethods #:nodoc:
+      private
+        # Encrypts the given attribute to a target location using the encryption
+        # options configured for that attribute
+        def write_encrypted_attribute(attr_name, to_attr_name, encryptor_class, options)
+          value = send(attr_name)
           
+          # Only encrypt values that actually have content and have not already
+          # been encrypted
           unless value.blank? || value.encrypted?
-            # Add contextual information for this plugin's encryptors
-            encryptor =
-              if encryptor_class.parent == PluginAWeek::EncryptedAttributes
-                encryptor_class.new(record, value, :write, options.dup)
-              else
-                encryptor_class.new(options.dup)
-              end
+            # Create the encryptor configured for this attribute
+            encryptor = create_encryptor(encryptor_class, options, :write, value)
             
-            # Encrypt the value and then track the encryptor used
+            # Encrypt the value
             value = encryptor.encrypt(value)
             value.encryptor = encryptor
             
-            record.send("#{to_attr_name}=", value)
+            # Update the value based on the target attribute
+            send("#{to_attr_name}=", value)
           end
-          
-          true
         end
         
-        # Define the reader when reading the crypted attribute from the db
-        define_method(to_attr_name) do
+        # Reads the given attribute from the database, adding contextual
+        # information about how it was encrypted so that equality comparisons
+        # can be used
+        def read_encrypted_attribute(to_attr_name, encryptor_class, options)
           value = read_attribute(to_attr_name)
           
           # Make sure we set the encryptor for equality comparison when reading
           # from the database
           unless value.blank? || value.encrypted? || attribute_changed?(to_attr_name)
-            # Add contextual information for this plugin's encryptors
-            value.encryptor =
-              if encryptor_class.parent == PluginAWeek::EncryptedAttributes
-                encryptor_class.new(self, value, :read, options.dup)
-              else
-                encryptor_class.new(options.dup)
-              end
+            # Create the encryptor configured for this attribute
+            value.encryptor = create_encryptor(encryptor_class, options, :read, value)
           end
           
           value
         end
-      end
+        
+        # Creates a new encryptor with the given configuration options. The
+        # operator defines the context in which the encryptor will be used.
+        def create_encryptor(klass, options, operator, value)
+          if klass.parent == PluginAWeek::EncryptedAttributes
+            # Only use the contextual information for encryptors defined in this plugin
+            klass.new(self, value, operator, options.dup)
+          else
+            klass.new(options.dup)
+          end
+        end
     end
   end
 end

data/test/app_root/script/console

@@ -0,0 +1,8 @@
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+libs =  " -r irb/completion"
+libs << " -r test/app_root/script/rails_framework_root"
+libs << " -r test/test_helper"
+libs << " -r plugin_test_helper/console_with_fixtures"
+libs << " -r console_app"
+libs << " -r console_with_helpers"
+exec "#{irb} #{libs} --simple-prompt"

data/test/app_root/script/rails_framework_root.rb

@@ -0,0 +1 @@
+RAILS_FRAMEWORK_ROOT = '/home/aaron/Projects/Vendor/rails'

data/test/factory.rb

@@ -1,26 +1,32 @@
 module Factory
-  # Build actions for the class
-  def self.build(klass, &block)
-    name = klass.to_s.underscore
-    define_method("#{name}_attributes", block)
+  # Build actions for the model
+  def self.build(model, &block)
+    name = model.to_s.underscore
     
-    module_eval <<-end_eval
-      def valid_#{name}_attributes(attributes = {})
-        #{name}_attributes(attributes)
-        attributes
-      end
-      
-      def new_#{name}(attributes = {})
-        #{klass}.new(valid_#{name}_attributes(attributes))
-      end
-      
-      def create_#{name}(*args)
-        record = new_#{name}(*args)
-        record.save!
-        record.reload
-        record
-      end
-    end_eval
+    define_method("#{name}_attributes", block)
+    define_method("valid_#{name}_attributes") {|*args| valid_attributes_for(model, *args)}
+    define_method("new_#{name}")              {|*args| new_record(model, *args)}
+    define_method("create_#{name}")           {|*args| create_record(model, *args)}
+  end
+  
+  # Get valid attributes for the model
+  def valid_attributes_for(model, attributes = {})
+    name = model.to_s.underscore
+    send("#{name}_attributes", attributes)
+    attributes
+  end
+  
+  # Build an unsaved record
+  def new_record(model, *args)
+    model.new(valid_attributes_for(model, *args))
+  end
+  
+  # Build and save/reload a record
+  def create_record(model, *args)
+    record = new_record(model, *args)
+    record.save!
+    record.reload
+    record
   end
   
   build User do |attributes|

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification 
 name: encrypted_attributes
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - Aaron Pfeifer
-autorequire: encrypted_attributes
+autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2008-06-22 00:00:00 -04:00
+date: 2008-07-05 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -19,7 +19,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.0.1
+        version: 0.0.5
     version: 
 description: 
 email: aaron@pluginaweek.org
@@ -37,6 +37,9 @@ files:
 - test/app_root/app
 - test/app_root/app/models
 - test/app_root/app/models/user.rb
+- test/app_root/script
+- test/app_root/script/rails_framework_root.rb
+- test/app_root/script/console
 - test/app_root/config
 - test/app_root/config/environment.rb
 - test/app_root/db
@@ -51,11 +54,11 @@ files:
 - test/unit
 - test/unit/sha_encryptor_test.rb
 - test/unit/encrypted_attributes_test.rb
-- CHANGELOG
+- CHANGELOG.rdoc
 - init.rb
-- MIT-LICENSE
+- LICENSE
 - Rakefile
-- README
+- README.rdoc
 has_rdoc: true
 homepage: http://www.pluginaweek.org
 post_install_message: 
@@ -77,7 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   version: 
 requirements: []
 
-rubyforge_project: 
+rubyforge_project: pluginaweek
 rubygems_version: 1.1.1
 signing_key: 
 specification_version: 2