pluginaweek / encrypted_attributes

= encrypted_attributes

+encrypted_attributes+ adds support for automatically encrypting ActiveRecord
attributes.

== Resources

Wiki

* http://wiki.pluginaweek.org/Encrypted_attributes

API

* http://api.pluginaweek.org/encrypted_attributes

Development

* http://dev.pluginaweek.org/browser/trunk/encrypted_attributes

Source

* http://svn.pluginaweek.org/trunk/encrypted_attributes

== Description

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
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.
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.

== Usage

=== SHA Encryption

For SHA encryption, you can either use the default salt, a custom salt, or
generate one based on the attributes of the model.

With the default salt:
  class User < ActiveRecord::Base
    encrypts :password
  end

With a custom salt:
  class User < ActiveRecord::Base
    encrypts :password, :salt => :create_salt
    
    private
      def create_salt
        "#{login}_salt"
      end
  end

The salt and password values are combined and stored in the attributed being
encrypted.  Therefore, there's no need to add a second column for storing the
salt value.

=== Symmetric Encryption

With the default key:
  class User < ActiveRecord::Base
    encrypts :password, :mode => :symmetric
  end

With a custom key:
  class User < ActiveRecord::Base
    encrypts :password, :mode => :symmetric, :key => 'custom'
  end

=== Asymmetric Encryption

With default key files:
  class User < ActiveRecord::Base
    encrypts :password, :mode => :asymmetric
  end

With custom key files:
  class User < ActiveRecord::Base
    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
attribute being encrypted, you can do so like so:

  class User < ActiveRecord::Base
    encrypts :password, :to => :crypted_password
  end

=== Conditional Encryption

Like ActiveRecord validations, +encrypts+ can take <tt>:if</tt> and <tt>:unless</tt>
parameters that determine whether the encryption should occur.  For example,

  class User < ActiveRecord::Base
    encrypts :password, :if => Proc.new {Rails.env != 'development'}
  end

=== 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.

== Testing

Before you can run any tests, the following gem must be installed:
* plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper]

To run against a specific version of Rails:

  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails

== Dependencies

* Rails 2.1 or later
* encrypted_strings[http://wiki.pluginaweek.org/Encrypted_strings]