= merb_forgery_protection

  Merb plugin that provides forgery protection against css attacks.
  
  This plugin is a light-weight, port of Rails' request forgery protection. 
  
  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 your app 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
  add: dependency 'merb_forgery_protection' to init.rb

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

== Credits

  Ruby on Rails