Permalink
Browse files

Beefed up docs a bit

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7612 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
1 parent 7f9a6c0 commit 911ea2f26f0a8d240b8a76a41d7a4ce978c72b12 @dhh dhh committed Sep 24, 2007
Showing with 27 additions and 17 deletions.
  1. +27 −17 actionpack/lib/action_controller/request_forgery_protection.rb
@@ -1,22 +1,6 @@
module ActionController #:nodoc:
class InvalidToken < ActionControllerError; end
- # Protect a controller's actions with the #protect_from_forgery method. Failure to validate will result in a ActionController::InvalidToken
- # exception. Customize the error message through the use of rescue_templates and rescue_action_in_public.
- #
- # class FooController < ApplicationController
- # # uses the cookie session store
- # protect_from_forgery :except => :index
- #
- # # uses one of the other session stores that uses a session_id value.
- # protect_from_forgery :secret => 'my-little-pony', :except => :index
- # end
- #
- # Valid Options:
- #
- # * <tt>:only/:except</tt> - passed to the before_filter call. Set which actions are verified.
- # * <tt>:secret</tt> - Custom salt used to generate the form_authenticity_token. Leave this off if you are using the cookie session store.
- # * <tt>:digest</tt> - Message digest used for hashing. Defaults to 'SHA1'
module RequestForgeryProtection
def self.included(base)
base.class_eval do
@@ -28,6 +12,32 @@ def self.included(base)
end
module ClassMethods
+ # 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 Rails 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 an ActionController::InvalidToken if
+ # the token doesn't match what was expected. And it will add a _token parameter to all forms that are automatically generated
+ # by Rails. You can customize the error message given through public/422.html.
+ #
+ # Example:
+ #
+ # class FooController < ApplicationController
+ # # uses the cookie session store (then you don't need a separate :secret)
+ # protect_from_forgery :except => :index
+ #
+ # # uses one of the other session stores that uses a session_id value.
+ # protect_from_forgery :secret => 'my-little-pony', :except => :index
+ # end
+ #
+ # Valid Options:
+ #
+ # * <tt>:only/:except</tt> - passed to the before_filter call. Set which actions are verified.
+ # * <tt>:secret</tt> - Custom salt used to generate the form_authenticity_token.
+ # Leave this off if you are using the cookie session store.
+ # * <tt>:digest</tt> - Message digest used for hashing. Defaults to 'SHA1'
def protect_from_forgery(options = {})
self.request_forgery_protection_token ||= :authenticity_token
before_filter :verify_authenticity_token, :only => options.delete(:only), :except => options.delete(:except)
@@ -57,7 +67,7 @@ def verifiable_request_format?
request.format.html? || request.format.js?
end
- # Sets the token value for the current session. Pass a :secret option in #verify_token to add a custom salt to the hash.
+ # Sets the token value for the current session. Pass a :secret option in #protect_from_forgery to add a custom salt to the hash.
def form_authenticity_token
@form_authenticity_token ||= if request_forgery_protection_options[:secret]
authenticity_token_from_session_id

0 comments on commit 911ea2f

Please sign in to comment.