= ActiveCrypto - Easy to use Crypto for Ruby on Rails

ActiveCrypto is based on EzCrypto and provides application oriented crypto support for Ruby on Rails applications.

== Features

* Transparent encryption/decryption
* Ruby on Rails like domain language

== Installation

Download it from here:

http://rubyforge.org/frs/?group_id=755&release_id=3321

or install it via Ruby Gems:

	gem install ezruby


== Simple examples

==== A simple encrypted class

You specify in your class which fields are encrypted:

	class Document < ActiveRecord::Base
		encrypt :title,:body
	end

Two encrypt it you need to enter a key. For ease of use there is a method called enter_password which sets the key based on a password of your choice.

	doc=Document.new
	doc.enter_password "This stuff is secret man!!!"
	doc.title="Plan to take over the world"
	doc.body="Write apps in Rails"
	doc.save
	
This needs to be done as well if you want to read your document:

	doc=Document.find 1
	doc.enter_password "This stuff is secret man!!!"
	puts doc.name
	
If you don't remember to set a key it will through a MissingKeyError.

==== More realistic example with KeyHolder

It probably isn't much use if each record needs its own key. The solution to this is the KeyHolder. A KeyHolder is an object that holds keys for use by other objects. A typical example would be a user.

	class User < ActiveRecord::Base
		has_many :documents
		keyholder
	end

We use standard ActiveRecord associations to associate the User with his documents. We also need to specify that he is a keyholder. We now modify our Document class as follows:

	class Document < ActiveRecord::Base
		belongs_to :user
		encrypt :title,:body,:key=>:user
	end

We have the standard associations going on here, but we have also added the option :key=>:user to the encrypt statement. Now we could do this:

	@user=User.new
	@user.enter_password "This stuff is secret man!!!"
	@user.save
	 
	@doc=Document.new
	@doc.user=@user 
	@doc.title="Plan to take over the world"
	@doc.body="Write apps in Rails"
	@doc.save
	
You could also do ordinary rails like stuf such as:

	@user.documents.each do |doc|
		puts doc.name
	end

Decryption is done transparently.

When doing this within a rails application, active_crypto automatically maintains a list of keys for each user session. Besides the 2 steps below you don't need to do anything special within your controller.

1. When a user logs on with a password enter his password like this:

	@user.enter_password @params['password']

2. When a user logs off call the following

	clear_session_keys
	
== Usage as a Rails plugin

Just unpack it into your $MY_RAILS_PROJECTS/vendor/plugins folder to use it as a self contained plugin. Otherwise you can install it as a gem using:

	$ gem install ezcrypto

Then make sure to require "active_crypto.rb" at the end of your environment.rb file.

== Database Schema issues

ActiveCrypto doesn't really care about the schema, but that said you do need a schema that will accept and not mangle it's output. On MySQL I normally use TINYBLOB instead of VARCHAR and BLOB instead of TEXT.

== License

EzCrypto and ActionCrypto is released under the MIT license.


== Support

To contact the author, send mail to pelleb@gmail.com

Also see my blogs at:
http://stakeventures.com and
http://neubia.com

This project was based on code used in my project StakeItOut, where you can securely share web services with your partners.
https://stakeitout.com

(C) 2005 Pelle Braendgaard