bchiu-merb_forgery_protection

= merb_forgery_protection

Merb plugin that provides forgery protection against css attacks.

Protect a controller's actions from CSRF attacks by ensuring that all forms are coming from the current web application, not a forged link from another site. This is done by embedding a token based on the session (which an attacker wouldn't know) in all forms and Ajax requests generated by Merb and then verifying the authenticity of that token in the controller. Only HTML/JavaScript requests are checked, so this will not protect your XML API (presumably you'll have a different authentication scheme there anyway). Also, GET requests are not protected as these should be indempotent anyway.

You turn this on with the #protect_from_forgery method, which will perform the check and raise a InvalidAuthenticityToken exception if the token doesn't match what was expected. And it will add an authenticity_token parameter to all forms that are automatically generated by Merb. You can customize the error message given through public/422.html.

Learn more about CSRF (Cross-Site Request Forgery) attacks:

• http://isc.sans.org/diary.html?storyid=1750
• http://en.wikipedia.org/wiki/Cross-site_request_forgery

Keep in mind, this is NOT a silver-bullet, plug 'n' play, warm security blanket for your merb app. There are a few guidelines you should follow:

• Keep your GET requests safe and idempotent. More reading material:
  • http://www.xml.com/pub/a/2002/04/24/deviant.html
  • http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
• Make sure the session cookies that Rails creates are non-persistent.
  Check in Firefox and look for "Expires: at end of session"

If you need to construct a request yourself, but still want to take advantage of forgery protection, you can grab the authenticity_token using the authenticity_token helper method and make it part of the parameters yourself.

== Installation

git clone git://github.com/bchiu/merb_forgery_protection.git cd merb_forgery_protection rake install

== Example

class Foo < Application # uses the cookie session store (then you don't need a separate :secret) protect_from_forgery :exclude => :index

# uses one of the other session stores that uses a session_id value.
protect_from_forgery :secret => 'my-little-pony', :exclude => :index

# you can disable csrf protection on controller-by-controller basis:
protect_from_forgery :enable => false

end

== Configuration

To disable forgery protection globally put this in your init.rb: Merb::Plugins.config[:forgery_protection] = { :enable => false }

=== Global Options: :secret - salt used to generate the token (default :session_secret_key) :enable - enable/disable protection for all controllers (default true) :digest - message digest used for hashing (default 'SHA1') :token_name - form field name for token (default :authenticity_token)

=== Controller Options: :only/:exclude - set which controller actions are protected from forgery :enable - enable/disable protection for this controller (default true) :secret - salt used to generate the token (default :session_secret_key)