attr_encrypted 1.1.2 → 1.2.0

data/README.rdoc

@@ -12,7 +12,6 @@ It works with ANY class, however, you get a few extra features when you're using
 
 == Usage
 
-
 === Basic
 
 Encrypting attributes has never been easier:
@@ -38,7 +37,7 @@ Encrypting attributes has never been easier:
   @user = User.load
   @user.ssn # decrypts :encrypted_ssn and returns '123-45-6789'
 
-The <tt>attr_encrypted</tt> method is also aliased as <tt>attr_encryptor</tt> to conform to Ruby's <tt>attr_</tt> naming conventions. I know that I should have called this project <tt>attr_encryptor</tt> but it was too late when I realized it ='(.
+The <tt>attr_encrypted</tt> method is also aliased as <tt>attr_encryptor</tt> to conform to Ruby's <tt>attr_</tt> naming conventions. I should have called this project <tt>attr_encryptor</tt> but it was too late when I realized it ='(.
 
 
 === Specifying the encrypted attribute name
@@ -246,6 +245,8 @@ You may want to encrypt objects other than strings (e.g. hashes, arrays, etc). I
     attr_encrypted :credentials, :key => 'some secret key', :marshal => true
   end
 
+You may also optionally specify <tt>:marshaler</tt>, <tt>:dump_method</tt>, and <tt>:load_method</tt> if you want to use something other than the default <tt>Marshal</tt> object.
+
 
 === Encrypt/decrypt attribute methods
 
@@ -297,12 +298,5 @@ Just like the default options for <tt>ActiveRecord</tt>, the <tt>:encode</tt> op
 * Make your feature addition or bug fix.
 * Add tests for it. This is important so I don't break it in a
   future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but
-   bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-
-== Contact
-
-Problems, comments, and suggestions all welcome: shuber@huberry.com
+* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.

data/lib/attr_encrypted.rb

@@ -1,26 +1,162 @@
-require 'eigenclass'
 require 'encryptor'
 
+# Adds attr_accessors that encrypt and decrypt an object's attributes
 module AttrEncrypted
-  def self.extended(base)
-    base.attr_encrypted_options = {}
-    base.instance_variable_set('@encrypted_attributes', {})
+  autoload :Version, 'attr_encrypted/version'
+
+  def self.extended(base) # :nodoc:
+    base.class_eval do
+      include InstanceMethods
+      attr_writer :attr_encrypted_options
+      @attr_encrypted_options, @encrypted_attributes = {}, {}
+    end
   end
-  
-  # Default options to use with calls to <tt>attr_encrypted</tt>.
+
+  # Generates attr_accessors that encrypt and decrypt attributes transparently
+  #
+  # Options (any other options you specify are passed to the encryptor's encrypt and decrypt methods)
+  #
+  #   :attribute        => The name of the referenced encrypted attribute. For example
+  #                        <tt>attr_accessor :email, :attribute => :ee</tt> would generate an
+  #                        attribute named 'ee' to store the encrypted email. This is useful when defining
+  #                        one attribute to encrypt at a time or when the :prefix and :suffix options
+  #                        aren't enough. Defaults to nil.
+  #
+  #   :prefix           => A prefix used to generate the name of the referenced encrypted attributes.
+  #                        For example <tt>attr_accessor :email, :password, :prefix => 'crypted_'</tt> would
+  #                        generate attributes named 'crypted_email' and 'crypted_password' to store the
+  #                        encrypted email and password. Defaults to 'encrypted_'.
+  #
+  #   :suffix           => A suffix used to generate the name of the referenced encrypted attributes.
+  #                        For example <tt>attr_accessor :email, :password, :prefix => '', :suffix => '_encrypted'</tt>
+  #                        would generate attributes named 'email_encrypted' and 'password_encrypted' to store the
+  #                        encrypted email. Defaults to ''.
+  #
+  #   :key              => The encryption key. This option may not be required if you're using a custom encryptor. If you pass
+  #                        a symbol representing an instance method then the :key option will be replaced with the result of the
+  #                        method before being passed to the encryptor. Objects that respond to :call are evaluated as well (including procs).
+  #                        Any other key types will be passed directly to the encryptor.
+  #
+  #   :encode           => If set to true, attributes will be encoded as well as encrypted. This is useful if you're
+  #                        planning on storing the encrypted attributes in a database. The default encoding is 'm' (base64),
+  #                        however this can be overwritten by setting the :encode option to some other encoding string instead of
+  #                        just 'true'. See http://www.ruby-doc.org/core/classes/Array.html#M002245 for more encoding directives.
+  #                        Defaults to false unless you're using it with ActiveRecord, DataMapper, or Sequel.
+  #
+  #   :default_encoding => Defaults to 'm' (base64).
+  #
+  #   :marshal          => If set to true, attributes will be marshaled as well as encrypted. This is useful if you're planning
+  #                        on encrypting something other than a string. Defaults to false unless you're using it with ActiveRecord
+  #                        or DataMapper.
+  #
+  #   :marshaler        => The object to use for marshaling. Defaults to Marshal.
+  #
+  #   :dump_method      => The dump method name to call on the <tt>:marshaler</tt> object to. Defaults to 'dump'.
+  #
+  #   :load_method      => The load method name to call on the <tt>:marshaler</tt> object. Defaults to 'load'.
   #
-  # It will inherit existing options from its parent class
+  #   :encryptor        => The object to use for encrypting. Defaults to Encryptor.
+  #
+  #   :encrypt_method   => The encrypt method name to call on the <tt>:encryptor</tt> object. Defaults to 'encrypt'.
+  #
+  #   :decrypt_method   => The decrypt method name to call on the <tt>:encryptor</tt> object. Defaults to 'decrypt'.
+  #
+  #   :if               => Attributes are only encrypted if this option evaluates to true. If you pass a symbol representing an instance
+  #                        method then the result of the method will be evaluated. Any objects that respond to <tt>:call</tt> are evaluated as well.
+  #                        Defaults to true.
+  #
+  #   :unless           => Attributes are only encrypted if this option evaluates to false. If you pass a symbol representing an instance
+  #                        method then the result of the method will be evaluated. Any objects that respond to <tt>:call</tt> are evaluated as well.
+  #                        Defaults to false.
+  #
+  # You can specify your own default options
+  #
+  #   class User
+  #     # now all attributes will be encoded and marshaled by default
+  #     attr_encrypted_options.merge!(:encode => true, :marshal => true, :some_other_option => true)
+  #     attr_encrypted :configuration, :key => 'my secret key'
+  #   end
+  #
+  #
+  # Example
+  #
+  #   class User
+  #     attr_encrypted :email, :credit_card, :key => 'some secret key'
+  #     attr_encrypted :configuration, :key => 'some other secret key', :marshal => true
+  #   end
+  #
+  #   @user = User.new
+  #   @user.encrypted_email # returns nil
+  #   @user.email = 'test@example.com'
+  #   @user.encrypted_email # returns the encrypted version of 'test@example.com'
+  #
+  #   @user.configuration = { :time_zone => 'UTC' }
+  #   @user.encrypted_configuration # returns the encrypted version of configuration
+  #
+  #   See README for more examples
+  def attr_encrypted(*attributes)
+    options = {
+      :prefix           => 'encrypted_',
+      :suffix           => '',
+      :if               => true,
+      :unless           => false,
+      :encode           => false,
+      :default_encoding => 'm',
+      :marshal          => false,
+      :marshaler        => Marshal,
+      :dump_method      => 'dump',
+      :load_method      => 'load',
+      :encryptor        => Encryptor,
+      :encrypt_method   => 'encrypt',
+      :decrypt_method   => 'decrypt'
+    }.merge!(attr_encrypted_options).merge!(attributes.last.is_a?(Hash) ? attributes.pop : {})
+
+    options[:encode] = options[:default_encoding] if options[:encode] == true
+
+    attributes.each do |attribute|
+      encrypted_attribute_name = (options[:attribute] ? options[:attribute] : [options[:prefix], attribute, options[:suffix]].join).to_sym
+
+      instance_methods_as_symbols = instance_methods.collect { |method| method.to_sym }
+      attr_reader encrypted_attribute_name unless instance_methods_as_symbols.include?(encrypted_attribute_name)
+      attr_writer encrypted_attribute_name unless instance_methods_as_symbols.include?(:"#{encrypted_attribute_name}=")
+
+      define_method(attribute) do
+        instance_variable_get("@#{attribute}") || instance_variable_set("@#{attribute}", decrypt(attribute, send(encrypted_attribute_name)))
+      end
+
+      define_method("#{attribute}=") do |value|
+        send("#{encrypted_attribute_name}=", encrypt(attribute, value))
+        instance_variable_set("@#{attribute}", value)
+      end
+
+      encrypted_attributes[attribute.to_sym] = options.merge!(:attribute => encrypted_attribute_name)
+    end
+  end
+  alias_method :attr_encryptor, :attr_encrypted
+
+  # Default options to use with calls to <tt>attr_encrypted</tt>
+  #
+  # It will inherit existing options from its superclass
   def attr_encrypted_options
-    @attr_encrypted_options ||= superclass.attr_encrypted_options.nil? ? {} : superclass.attr_encrypted_options.dup
+    @attr_encrypted_options ||= superclass.attr_encrypted_options.dup
   end
-  
-  # Sets default options to use with calls to <tt>attr_encrypted</tt>.
-  def attr_encrypted_options=(options)
-    @attr_encrypted_options = options
+
+  # Checks if an attribute is configured with <tt>attr_encrypted</tt>
+  #
+  # Example
+  #
+  #   class User
+  #     attr_accessor :name
+  #     attr_encrypted :email
+  #   end
+  #
+  #   User.attr_encrypted?(:name)  # false
+  #   User.attr_encrypted?(:email) # true
+  def attr_encrypted?(attribute)
+    encrypted_attributes.has_key?(attribute.to_sym)
   end
-  
-  # Contains a hash of encrypted attributes with virtual attribute names as keys and real attribute 
-  # names as values
+
+  # Decrypts a value for the attribute specified
   #
   # Example
   #
@@ -28,201 +164,133 @@ module AttrEncrypted
   #     attr_encrypted :email
   #   end
   #
-  #   User.encrypted_attributes # { 'email' => 'encrypted_email' }
-  def encrypted_attributes
-    @encrypted_attributes ||= superclass.encrypted_attributes.nil? ? {} : superclass.encrypted_attributes.dup
+  #   email = User.decrypt(:email, 'SOME_ENCRYPTED_EMAIL_STRING')
+  def decrypt(attribute, encrypted_value, options = {})
+    options = encrypted_attributes[attribute.to_sym].merge(options)
+    if options[:if] && !options[:unless] && !encrypted_value.nil? && !(encrypted_value.is_a?(String) && encrypted_value.empty?)
+      encrypted_value = encrypted_value.unpack(options[:encode]).first if options[:encode]
+      value = options[:encryptor].send(options[:decrypt_method], options.merge!(:value => encrypted_value))
+      value = options[:marshaler].send(options[:load_method], value) if options[:marshal]
+      value
+    else
+      encrypted_value
+    end
   end
-  
-  # Checks if an attribute has been configured to be encrypted
+
+  # Encrypts a value for the attribute specified
   #
   # Example
   #
   #   class User
-  #     attr_accessor :name
   #     attr_encrypted :email
   #   end
   #
-  #   User.attr_encrypted?(:name) # false
-  #   User.attr_encrypted?(:email) # true
-  def attr_encrypted?(attribute)
-    encrypted_attributes.keys.include?(attribute.to_s)
+  #   encrypted_email = User.encrypt(:email, 'test@example.com')
+  def encrypt(attribute, value, options = {})
+    options = encrypted_attributes[attribute.to_sym].merge(options)
+    if options[:if] && !options[:unless] && !value.nil? && !(value.is_a?(String) && value.empty?)
+      value = options[:marshaler].send(options[:dump_method], value) if options[:marshal]
+      encrypted_value = options[:encryptor].send(options[:encrypt_method], options.merge!(:value => value))
+      encrypted_value = [encrypted_value].pack(options[:encode]) if options[:encode]
+      encrypted_value
+    else
+      value
+    end
   end
-  
-  protected
-  
-    # Generates attr_accessors that encrypt and decrypt attributes transparently
-    #
-    # Options (any other options you specify are passed to the encryptor's encrypt and decrypt methods)
-    #
-    #   :attribute      => The name of the referenced encrypted attribute. For example 
-    #                      <tt>attr_accessor :email, :attribute => :ee</tt> would generate an 
-    #                      attribute named 'ee' to store the encrypted email. This is useful when defining
-    #                      one attribute to encrypt at a time or when the :prefix and :suffix options
-    #                      aren't enough. Defaults to nil.
-    #
-    #   :prefix         => A prefix used to generate the name of the referenced encrypted attributes.
-    #                      For example <tt>attr_accessor :email, :password, :prefix => 'crypted_'</tt> would 
-    #                      generate attributes named 'crypted_email' and 'crypted_password' to store the 
-    #                      encrypted email and password. Defaults to 'encrypted_'.
-    #
-    #   :suffix         => A suffix used to generate the name of the referenced encrypted attributes.
-    #                      For example <tt>attr_accessor :email, :password, :prefix => '', :suffix => '_encrypted'</tt>  
-    #                      would generate attributes named 'email_encrypted' and 'password_encrypted' to store the 
-    #                      encrypted email. Defaults to ''.
-    #
-    #   :key            => The encryption key. This option may not be required if you're using a custom encryptor. If you pass 
-    #                      a symbol representing an instance method then the :key option will be replaced with the result of the 
-    #                      method before being passed to the encryptor. Objects that respond to :call are evaluated as well (including procs). 
-    #                      Any other key types will be passed directly to the encryptor.
-    #
-    #   :encode         => If set to true, attributes will be encoded as well as encrypted. This is useful if you're
-    #                      planning on storing the encrypted attributes in a database. The default encoding is 'm*' (base64), 
-    #                      however this can be overwritten by setting the :encode option to some other encoding string instead of
-    #                      just 'true'. See http://www.ruby-doc.org/core/classes/Array.html#M002245 for more encoding directives. 
-    #                      Defaults to false unless you're using it with ActiveRecord or DataMapper.
-    #
-    #   :marshal        => If set to true, attributes will be marshaled as well as encrypted. This is useful if you're planning
-    #                      on encrypting something other than a string. Defaults to false unless you're using it with ActiveRecord 
-    #                      or DataMapper.
-    #
-    #   :encryptor      => The object to use for encrypting. Defaults to Encryptor.
-    #
-    #   :encrypt_method => The encrypt method name to call on the <tt>:encryptor</tt> object. Defaults to :encrypt.
-    #
-    #   :decrypt_method => The decrypt method name to call on the <tt>:encryptor</tt> object. Defaults to :decrypt.
-    #
-    #   :if             => Attributes are only encrypted if this option evaluates to true. If you pass a symbol representing an instance 
-    #                      method then the result of the method will be evaluated. Any objects that respond to :call are evaluated as well. 
-    #                      Defaults to true.
+
+  # Contains a hash of encrypted attributes with virtual attribute names as keys
+  # and their corresponding options as values
+  #
+  # Example
+  #
+  #   class User
+  #     attr_encrypted :email, :key => 'my secret key'
+  #   end
+  #
+  #   User.encrypted_attributes # { :email => { :attribute => 'encrypted_email', :key => 'my secret key' } }
+  def encrypted_attributes
+    @encrypted_attributes ||= superclass.encrypted_attributes.dup
+  end
+
+  # Forwards calls to :encrypt_#{attribute} or :decrypt_#{attribute} to the corresponding encrypt or decrypt method
+  # if attribute was configured with attr_encrypted
+  #
+  # Example
+  #
+  #   class User
+  #     attr_encrypted :email, :key => 'my secret key'
+  #   end
+  #
+  #   User.encrypt_email('SOME_ENCRYPTED_EMAIL_STRING')
+  def method_missing(method, *arguments, &block)
+    if method.to_s =~ /^((en|de)crypt)_(.+)$/ && attr_encrypted?($3)
+      send($1, $3, *arguments)
+    else
+      super
+    end
+  end
+
+  module InstanceMethods
+    # Decrypts a value for the attribute specified using options evaluated in the current object's scope
     #
-    #   :unless         => Attributes are only encrypted if this option evaluates to false. If you pass a symbol representing an instance 
-    #                      method then the result of the method will be evaluated. Any objects that respond to :call are evaluated as well. 
-    #                      Defaults to false.
+    # Example
     #
-    # You can specify your own default options
+    #  class User
+    #    attr_accessor :secret_key
+    #    attr_encrypted :email, :key => :secret_key
     #
-    #   class User
-    #     # now all attributes will be encoded and marshaled by default
-    #     attr_encrypted_options.merge!(:encode => true, :marshal => true, :some_other_option => true)
-    #     attr_encrypted :configuration
-    #   end
+    #    def initialize(secret_key)
+    #      self.secret_key = secret_key
+    #    end
+    #  end
     #
+    #  @user = User.new('some-secret-key')
+    #  @user.decrypt(:email, 'SOME_ENCRYPTED_EMAIL_STRING')
+    def decrypt(attribute, encrypted_value)
+      self.class.decrypt(attribute, encrypted_value, evaluated_attr_encrypted_options_for(attribute))
+    end
+
+    # Encrypts a value for the attribute specified using options evaluated in the current object's scope
     #
     # Example
     #
-    #   class User
-    #     attr_encrypted :email, :credit_card, :key => 'some secret key'
-    #     attr_encrypted :configuration, :key => 'some other secret key', :marshal => true
-    #   end
-    #
-    #   @user = User.new
-    #   @user.encrypted_email # returns nil
-    #   @user.email = 'test@example.com'
-    #   @user.encrypted_email # returns the encrypted version of 'test@example.com'
+    #  class User
+    #    attr_accessor :secret_key
+    #    attr_encrypted :email, :key => :secret_key
     #
-    #   @user.configuration = { :time_zone => 'UTC' }
-    #   @user.encrypted_configuration # returns the encrypted version of configuration
+    #    def initialize(secret_key)
+    #      self.secret_key = secret_key
+    #    end
+    #  end
     #
-    #   See README for more examples
-    def attr_encrypted(*attrs)
-      options = { 
-        :prefix => 'encrypted_', 
-        :suffix => '', 
-        :encryptor => Encryptor, 
-        :encrypt_method => :encrypt,
-        :decrypt_method => :decrypt,
-        :encode => false, 
-        :marshal => false, 
-        :if => true, 
-        :unless => false 
-      }.merge(attr_encrypted_options).merge(attrs.last.is_a?(Hash) ? attrs.pop : {})
-      options[:encode] = 'm*' if options[:encode] == true
-      
-      attrs.each do |attribute|
-        encrypted_attribute_name = options[:attribute].nil? ? options[:prefix].to_s + attribute.to_s + options[:suffix].to_s : options[:attribute].to_s
-        
-        encrypted_attributes[attribute.to_s] = encrypted_attribute_name
-        
-        attr_reader encrypted_attribute_name.to_sym unless instance_methods.include?(encrypted_attribute_name)
-        attr_writer encrypted_attribute_name.to_sym unless instance_methods.include?("#{encrypted_attribute_name}=")
-        
-        define_class_method "encrypt_#{attribute}" do |value|
-          if options[:if] && !options[:unless]
-            if value.nil? || (value.is_a?(String) && value.empty?)
-              encrypted_value = value
-            else
-              value = Marshal.dump(value) if options[:marshal]
-              encrypted_value = options[:encryptor].send options[:encrypt_method], options.merge(:value => value)
-              encrypted_value = [encrypted_value].pack(options[:encode]) if options[:encode]
-            end
-            encrypted_value
-          else
-            value
-          end
-        end
-        
-        define_class_method "decrypt_#{attribute}" do |encrypted_value|
-          if options[:if] && !options[:unless]
-            if encrypted_value.nil? || (encrypted_value.is_a?(String) && encrypted_value.empty?)
-              decrypted_value = encrypted_value
-            else
-              encrypted_value = encrypted_value.unpack(options[:encode]).to_s if options[:encode]
-              decrypted_value = options[:encryptor].send(options[:decrypt_method], options.merge(:value => encrypted_value))
-              decrypted_value = Marshal.load(decrypted_value) if options[:marshal]
-            end
-            decrypted_value
-          else
-            encrypted_value
-          end
-        end
-        
-        define_method "#{attribute}" do
-          begin
-            value = instance_variable_get("@#{attribute}")
-            encrypted_value = send(encrypted_attribute_name.to_sym)
-            original_options = [:key, :if, :unless].inject({}) do |hash, option|
-              hash[option] = options[option]
-              options[option] = self.class.send :evaluate_attr_encrypted_option, options[option], self
-              hash
-            end
-            value = instance_variable_set("@#{attribute}", self.class.send("decrypt_#{attribute}".to_sym, encrypted_value)) if value.nil? && !encrypted_value.nil?
-          ensure
-            options.merge!(original_options)
-          end
-          value
-        end
-        
-        define_method "#{attribute}=" do |value|
-          begin
-            original_options = [:key, :if, :unless].inject({}) do |hash, option|
-              hash[option] = options[option]
-              options[option] = self.class.send :evaluate_attr_encrypted_option, options[option], self
-              hash
-            end
-            send("#{encrypted_attribute_name}=".to_sym, self.class.send("encrypt_#{attribute}".to_sym, value))
-          ensure
-            options.merge!(original_options)
-          end
-          instance_variable_set("@#{attribute}", value)
-        end
-      end
+    #  @user = User.new('some-secret-key')
+    #  @user.encrypt(:email, 'test@example.com')
+    def encrypt(attribute, value)
+      self.class.encrypt(attribute, value, evaluated_attr_encrypted_options_for(attribute))
     end
-    alias_method :attr_encryptor, :attr_encrypted
-    
-    # Evaluates an option specified as a symbol representing an instance method or a proc
-    #
-    # If the option is not a symbol or proc then the original option is returned
-    def evaluate_attr_encrypted_option(option, object)
-      if option.is_a?(Symbol) && object.respond_to?(option)
-        object.send(option)
-      elsif option.respond_to?(:call)
-        option.call(object)
-      else
-        option
+
+    protected
+
+      # Returns attr_encrypted options evaluated in the current object's scope for the attribute specified
+      def evaluated_attr_encrypted_options_for(attribute)
+        self.class.encrypted_attributes[attribute.to_sym].inject({}) { |hash, (option, value)| hash.merge!(option => evaluate_attr_encrypted_option(value)) }
       end
-    end
+
+      # Evaluates symbol (method reference) or proc (responds to call) options
+      #
+      # If the option is not a symbol or proc then the original option is returned
+      def evaluate_attr_encrypted_option(option)
+        if option.is_a?(Symbol) && respond_to?(option)
+          send(option)
+        elsif option.respond_to?(:call)
+          option.call(self)
+        else
+          option
+        end
+      end
+  end
 end
 
 Object.extend AttrEncrypted
 
-Dir[File.join(File.dirname(__FILE__), 'attr_encrypted', 'adapters', '*.rb')].each { |file| require file }
+Dir[File.join(File.dirname(__FILE__), 'attr_encrypted', 'adapters', '*.rb')].each { |adapter| require adapter }