@@ -1,5 +1,8 @@ == master +* Replace dynamic :salt option with :embed_salt option and utilizing the #encrypts block +* Allow a block to be used for dynamically defining encryption options +* Add :before / :after callbacks for hooking into the encryption process * Allow the callback when encryption occurs to be customized [Sergio Salvatore] * Define source attribute accessor if different than target and not defined [Sergio Salvatore] * Update tests to work with Rails 2.3 CHANGELOG.rdoc @@ -25,7 +25,7 @@ Source Encrypting attributes can be repetitive especially when doing so throughout various models and various projects. encrypted_attributes, in association -with the encrypted_strings plugin, helps make encrypting ActiveRecord +with the encrypted_strings library, helps make encrypting ActiveRecord attributes easier by automating the process. The options that +encrypts+ takes includes all of the encryption options for @@ -35,46 +35,46 @@ into the +encrypts+ method. Examples of this are show in the Usage section. == Usage -=== SHA Encryption +=== Encryption Modes -For SHA encryption, you can either use the default salt, a custom salt, or -generate one based on the attributes of the model. +SHA, symmetric, and asymmetric encryption modes are supported (default is SHA): -With the default salt: class User < ActiveRecord::Base - encrypts :password + encrypts :password, :salt => 'secret' + # encrypts :password, :mode => :symmetric, :password => 'secret' + # encrypts :password, :mode => :asymmetric, :public_key_file => '/keys/public', :private_key_file => '/keys/private' end -With a custom salt based on the record's values: - class User < ActiveRecord::Base - encrypts :password, :salt => :create_salt - - private - def create_salt - "#{login}_salt" - end - end +=== Dynamic Configuration -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. - -=== Symmetric Encryption +The encryption configuration can be dynamically set like so: class User < ActiveRecord::Base - encrypts :password, :mode => :symmetric, :password => 'secret' + encrypts :password, :mode => :sha do |user| + {:salt => "#{user.login}-#{Time.now}", :embed_salt => true} + end end -=== Asymmetric Encryption +In this case, 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. + +To store the dynamic salt in a separate column: class User < ActiveRecord::Base - encrypts :password, :mode => :asymmetric, :public_key_file => '/keys/public', :private_key_file => '/keys/private' + encrypts :password, :mode => :sha, :before => :create_salt do |user| + {:salt => user.salt} + end + + def create_salt + self.salt = "#{login}-#{Time.now}" + end end === Targeted Encryption If you want to store the encrypted value in a different attribute than the -attribute being encrypted, you can do so like so: +attribute being encrypted: class User < ActiveRecord::Base encrypts :password, :to => :crypted_password README.rdoc @@ -3,13 +3,17 @@ require 'encrypted_attributes/sha_cipher' module EncryptedAttributes module MacroMethods - # Encrypts the specified attribute. + # Encrypts the given attribute. # # Configuration options: - # * <tt>:mode</tt> - The mode of encryption to use. Default is sha. See - # EncryptedStrings for other possible modes. - # * <tt>:to</tt> - The attribute to write the encrypted value to. Default is - # the same attribute being encrypted. + # * <tt>:mode</tt> - The mode of encryption to use. Default is <tt>:sha</tt>. + # See EncryptedStrings for other possible modes. + # * <tt>:to</tt> - The attribute to write the encrypted value to. Default + # is the same attribute being encrypted. + # * <tt>:before</tt> - The callback to invoke every time *before* the + # attribute is encrypted + # * <tt>:after</tt> - The callback to invoke every time *after* the + # attribute is encrypted # * <tt>:on</tt> - The ActiveRecord callback to use when triggering the # encryption. By default, this will encrypt on <tt>before_validation</tt>. # See ActiveRecord::Callbacks for a list of possible callbacks. @@ -25,11 +29,11 @@ module EncryptedAttributes # # == 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, + # By default, 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 @@ -59,7 +63,7 @@ module EncryptedAttributes # # class User < ActiveRecord::Base # encrypts :password - # # encrypts :password, :salt => :create_salt + # # encrypts :password, :salt => 'secret' # end # # Symmetric encryption: @@ -75,7 +79,32 @@ module EncryptedAttributes # encrypts :password, :mode => :asymmetric # # encrypts :password, :mode => :asymmetric, :public_key_file => '/keys/public', :private_key_file => '/keys/private' # end - def encrypts(attr_name, options = {}) + # + # == Dynamic configuration + # + # For better security, the encryption options (such as the salt value) + # can be based on values in each individual record. In order to + # dynamically configure the encryption options so that individual records + # can be referenced, an optional block can be specified. + # + # For example, + # + # class User < ActiveRecord::Base + # encrypts :password, :mode => :sha, :before => :create_salt do |user| + # {:salt => user.salt} + # end + # + # private + # def create_salt + # self.salt = "#{login}-#{Time.now}" + # end + # end + # + # In the above example, the SHA encryption's <tt>salt</tt> is configured + # dynamically based on the user's login and the time at which it was + # encrypted. This helps improve the security of the user's password. + def encrypts(attr_name, options = {}, &config) + config ||= options attr_name = attr_name.to_s to_attr_name = (options.delete(:to) || attr_name).to_s @@ -88,10 +117,15 @@ module EncryptedAttributes cipher_class = EncryptedStrings.const_get(class_name) end + # Define encryption hooks + define_callbacks("before_encrypt_#{attr_name}", "after_encrypt_#{attr_name}") + send("before_encrypt_#{attr_name}", options.delete(:before)) if options.include?(:before) + send("after_encrypt_#{attr_name}", options.delete(:after)) if options.include?(:after) + # Set the encrypted value on the configured callback callback = options.delete(:on) || :before_validation send(callback, :if => options.delete(:if), :unless => options.delete(:unless)) do |record| - record.send(:write_encrypted_attribute, attr_name, to_attr_name, cipher_class, options) + record.send(:write_encrypted_attribute, attr_name, to_attr_name, cipher_class, config) true end @@ -103,7 +137,7 @@ module EncryptedAttributes # Define the reader when reading the encrypted attribute from the database define_method(to_attr_name) do - read_encrypted_attribute(to_attr_name, cipher_class, options) + read_encrypted_attribute(to_attr_name, cipher_class, config) end unless included_modules.include?(EncryptedAttributes::InstanceMethods) @@ -122,8 +156,10 @@ module EncryptedAttributes # Only encrypt values that actually have content and have not already # been encrypted unless value.blank? || value.encrypted? + callback("before_encrypt_#{attr_name}") + # Create the cipher configured for this attribute - cipher = create_cipher(cipher_class, options, :write, value) + cipher = create_cipher(cipher_class, options, value) # Encrypt the value value = cipher.encrypt(value) @@ -131,6 +167,8 @@ module EncryptedAttributes # Update the value based on the target attribute send("#{to_attr_name}=", value) + + callback("after_encrypt_#{attr_name}") end end @@ -148,21 +186,18 @@ module EncryptedAttributes # don't want to encrypt when a new value has been set) unless value.blank? || value.encrypted? || attribute_changed?(to_attr_name) # Create the cipher configured for this attribute - value.cipher = create_cipher(cipher_class, options, :read, value) + value.cipher = create_cipher(cipher_class, options, value) end value end - # Creates a new cipher with the given configuration options. The - # operator defines the context in which the cipher will be used. - def create_cipher(klass, options, operator, value) - if klass.parent == EncryptedAttributes - # Only use the contextual information for ciphers defined in this plugin - klass.new(self, value, operator, options.dup) - else - klass.new(options.dup) - end + # Creates a new cipher with the given configuration options + def create_cipher(klass, options, value) + options = options.is_a?(Proc) ? options.call(self) : options.dup + + # Only use the contextual information for this plugin's ciphers + klass.parent == EncryptedAttributes ? klass.new(value, options) : klass.new(options) end end end lib/encrypted_attributes.rb @@ -1,48 +1,29 @@ module EncryptedAttributes - # Adds support for dynamically generated salts + # Adds support for embedding salts in the encrypted value class ShaCipher < EncryptedStrings::ShaCipher # Encrypts a string using a Secure Hash Algorithm (SHA), specifically SHA-1. # - # The <tt>:salt</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 - object.send(salt) - when Proc - 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 at the end of the value if it's dynamic + # Configuration options: + # * <tt>:salt</tt> - Random bytes used as one of the inputs for generating + # the encrypted string + # * <tt>:embed_salt</tt> - Whether to embed the salt directly within the + # encrypted value. Default is false. This is useful for storing both + # the salt and the encrypted value in the same attribute. + def initialize(value, options = {}) #:nodoc: + if @embed_salt = options.delete(:embed_salt) + # The salt is at the end of the value salt = value[40..-1] - if @dynamic_salt = !salt.blank? - options[:salt] = salt - end - - super(options) + options[:salt] = salt unless salt.blank? end + + super(options) end - # Encrypts the data, appending the salt to the end of the string if it - # was created dynamically + # Encrypts the data, embedding the salt at the end of the string if + # configured to do so def encrypt(data) encrypted_data = super - encrypted_data << salt if @dynamic_salt + encrypted_data << salt if @embed_salt encrypted_data end end lib/encrypted_attributes/sha_cipher.rb @@ -1,7 +1,7 @@ class CreateUsers < ActiveRecord::Migration def self.up create_table :users do |t| - t.string :login, :password, :crypted_password + t.string :login, :password, :crypted_password, :salt end end test/app_root/db/migrate/001_create_users.rb @@ -177,9 +177,9 @@ class EncryptedAttributesWithConflictingVirtualAttributeSourceTest < ActiveSuppo end end -class EncryptedAttributesWithConditionalsTest < ActiveSupport::TestCase +class EncryptedAttributesWithCustomCallbackTest < ActiveSupport::TestCase def setup - User.encrypts :password, :on => :before_create + User.encrypts :password, :on => :before_save end def test_should_not_encrypt_on_validation @@ -201,12 +201,117 @@ class EncryptedAttributesWithConditionalsTest < ActiveSupport::TestCase end end -class EncryptedAttributesWithCustomCallbackTest < ActiveSupport::TestCase +class EncryptedAttributesWithConditionalsTest < ActiveSupport::TestCase def test_should_not_encrypt_if_if_conditional_is_false User.encrypts :password, :if => lambda {|user| false} user = create_user(:login => 'admin', :password => 'secret') assert_equal 'secret', user.password end + + def test_should_encrypt_if_if_conditional_is_true + User.encrypts :password, :if => lambda {|user| true} + user = create_user(:login => 'admin', :password => 'secret') + assert_equal '8152bc582f58c854f580cb101d3182813dec4afe', "#{user.password}" + end + + def test_should_not_encrypt_if_unless_conditional_is_true + User.encrypts :password, :unless => lambda {|user| true} + user = create_user(:login => 'admin', :password => 'secret') + assert_equal 'secret', user.password + end + + def test_should_encrypt_if_unless_conditional_is_false + User.encrypts :password, :unless => lambda {|user| false} + user = create_user(:login => 'admin', :password => 'secret') + assert_equal '8152bc582f58c854f580cb101d3182813dec4afe', "#{user.password}" + end + + def teardown + User.class_eval do + @before_validation_callbacks = nil + end + end +end + +class EncryptedAttributesWithBeforeCallbacksTest < ActiveSupport::TestCase + def setup + @password = nil + @ran_callback = false + User.encrypts :password, :before => lambda {|user| @ran_callback = true; @password = user.password.to_s} + + create_user(:login => 'admin', :password => 'secret') + end + + def test_should_run_callback + assert @ran_callback + end + + def test_should_not_have_encrypted_yet + assert_equal 'secret', @password + end + + def teardown + User.class_eval do + @before_validation_callbacks = nil + @before_encrypt_password_callbacks = nil + end + end +end + +class EncryptedAttributesWithAfterCallbacksTest < ActiveSupport::TestCase + def setup + @password = nil + @ran_callback = false + User.encrypts :password, :after => lambda {|user| @ran_callback = true; @password = user.password.to_s} + + create_user(:login => 'admin', :password => 'secret') + end + + def test_should_run_callback + assert @ran_callback + end + + def test_should_have_encrypted_already + assert_equal '8152bc582f58c854f580cb101d3182813dec4afe', @password + end + + def teardown + User.class_eval do + @before_validation_callbacks = nil + @after_encrypt_password_callbacks = nil + end + end +end + +class EncryptedAttributesWithDynamicConfigurationTest < ActiveSupport::TestCase + def setup + @salt = nil + User.encrypts :password, :before => lambda {|user| user.salt = user.login} do |user| + {:salt => @salt = user.salt} + end + + @user = create_user(:login => 'admin', :password => 'secret') + end + + def test_should_use_dynamic_configuration_during_write + assert_equal 'a55d037f385cad22efe7862e07b805938d150154', "#{@user[:password]}" + end + + def test_should_use_dynamic_configuration_during_read + user = User.find(@user.id) + assert_equal 'a55d037f385cad22efe7862e07b805938d150154', "#{user.password}" + end + + def test_should_build_configuration_after_before_callbacks_invoked + assert_equal 'admin', @salt + end + + def teardown + User.class_eval do + @before_validation_callbacks = nil + @before_encrypt_password_callbacks = nil + end + end end class ShaEncryptionTest < ActiveSupport::TestCase @@ -232,7 +337,7 @@ class ShaEncryptionTest < ActiveSupport::TestCase end def test_should_be_able_to_check_password - assert_equal 'secret', @user.password + assert_equal 'secret', @user. password end def teardown @@ -242,9 +347,9 @@ class ShaEncryptionTest < ActiveSupport::TestCase end end -class ShaWithCustomSaltEncryptionTest < ActiveSupport::TestCase +class ShaWithEmbeddedSaltEncryptionTest < ActiveSupport::TestCase def setup - User.encrypts :password, :mode => :sha, :salt => :login + User.encrypts :password, :mode => :sha, :salt => 'admin', :embed_salt => true @user = create_user(:login => 'admin', :password => 'secret') end test/unit/encrypted_attributes_test.rb @@ -1,56 +1,43 @@ require File.dirname(__FILE__) + '/../test_helper' -class ShaCipherOnWriteTest < Test::Unit::TestCase +class ShaCipherWithoutEmbeddingTest < Test::Unit::TestCase def setup - @user = create_user(:login => 'admin') + @cipher = EncryptedAttributes::ShaCipher.new('dc0fc7c07bba982a8d8f18fe138dbea912df5e0e', :salt => 'custom_salt') end - def test_should_allow_symbolic_salt - cipher = EncryptedAttributes::ShaCipher.new(@user, 'password', :write, :salt => :login) - assert_equal 'admin', cipher.salt - end - - def test_should_allow_stringified_salt - cipher = EncryptedAttributes::ShaCipher.new(@user, 'password', :write, :salt => 'custom_salt') - assert_equal 'custom_salt', cipher.salt + def test_should_use_configured_salt + assert_equal 'custom_salt', @cipher.salt end - def test_should_allow_block_salt - dynamic_salt = lambda {|user| user.login} - cipher = EncryptedAttributes::ShaCipher.new(@user, 'password', :write, :salt => dynamic_salt) - assert_equal 'admin', cipher.salt + def test_should_not_embed_salt_in_encrypted_string + assert_equal 'dc0fc7c07bba982a8d8f18fe138dbea912df5e0e', @cipher.encrypt('secret') end - - def test_should_allow_dynamic_nil_salt - dynamic_salt = lambda {|user| nil} - cipher = EncryptedAttributes::ShaCipher.new(@user, 'password', :write, :salt => dynamic_salt) - assert_equal '', cipher.salt +end + +class ShaCipherWithNoSaltEmbeddedTest < Test::Unit::TestCase + def setup + @cipher = EncryptedAttributes::ShaCipher.new('dc0fc7c07bba982a8d8f18fe138dbea912df5e0e', :embed_salt => true, :salt => 'custom_salt') end - def test_should_append_salt_to_encrypted_value_if_dynamic - cipher = EncryptedAttributes::ShaCipher.new(@user, 'password', :write, :salt => :login) - assert_equal 'a55d037f385cad22efe7862e07b805938d150154admin', cipher.encrypt('secret') + def test_should_use_configured_salt + assert_equal 'custom_salt', @cipher.salt end - def test_should_not_append_salt_to_encrypted_value_if_static - cipher = EncryptedAttributes::ShaCipher.new(@user, 'password', :write, :salt => 'custom_salt') - assert_equal 'dc0fc7c07bba982a8d8f18fe138dbea912df5e0e', cipher.encrypt('secret') + def test_should_embed_salt_in_encrypted_string + assert_equal 'dc0fc7c07bba982a8d8f18fe138dbea912df5e0ecustom_salt', @cipher.encrypt('secret') end end -class ShaCipherOnReadTest < Test::Unit::TestCase +class ShaCipherWithSaltEmbeddedTest < Test::Unit::TestCase def setup - @user = create_user(:login => 'admin') - @cipher = EncryptedAttributes::ShaCipher.new(@user, 'dc0fc7c07bba982a8d8f18fe138dbea912df5e0ecustom_salt', :read) + @cipher = EncryptedAttributes::ShaCipher.new('dc0fc7c07bba982a8d8f18fe138dbea912df5e0ecustom_salt', :embed_salt => true, :salt => 'ignored_salt') end - def test_should_should_use_remaining_characters_after_password_for_salt + def test_should_use_remaining_characters_after_password_for_salt assert_equal 'custom_salt', @cipher.salt end - def test_should_be_able_to_perform_equality_on_encrypted_strings - password = 'dc0fc7c07bba982a8d8f18fe138dbea912df5e0ecustom_salt' - password.cipher = @cipher - assert_equal 'secret', password + def test_should_embed_salt_in_encrypted_string + assert_equal 'dc0fc7c07bba982a8d8f18fe138dbea912df5e0ecustom_salt', @cipher.encrypt('secret') end end test/unit/sha_cipher_test.rb 52e093f7ff6aa3d9b1ce514d0817c936bc1c71e7 Aaron Pfeifer aaron.pfeifer@gmail.com http://github.com/pluginaweek/encrypted_attributes/commit/86423ed1b8090604270a243910f1c11264afd3da 86423ed1b8090604270a243910f1c11264afd3da 2009-05-02T10:49:51-07:00 2009-05-02T10:49:51-07:00 Allow a block to be used for dynamically defining encryption options Replace dynamic :salt option with :embed_salt option and utilizing the #encrypts block Add :before / :after callbacks for hooking into the encryption process 9eb47f4e664af833063d39e99ac357bf5b315eab Aaron Pfeifer aaron.pfeifer@gmail.com