diff options
| -rw-r--r-- | actionpack/CHANGELOG | 2 | ||||
| -rw-r--r-- | actionpack/lib/action_controller/request_forgery_protection.rb | 75 |
2 files changed, 43 insertions, 34 deletions
diff --git a/actionpack/CHANGELOG b/actionpack/CHANGELOG index 53b32591c0..a3b0d6cfb7 100644 --- a/actionpack/CHANGELOG +++ b/actionpack/CHANGELOG @@ -1,5 +1,7 @@ *SVN* +* Correct inconsistencies in RequestForgeryProtection docs. #11032 [mislav] + * Introduce a Template class to ActionView. #11024 [lifofifo] * Introduce the :index option for form_for and fields_for to simplify multi-model forms (see http://railscasts.com/episodes/75). #9883 [rmm5t] diff --git a/actionpack/lib/action_controller/request_forgery_protection.rb b/actionpack/lib/action_controller/request_forgery_protection.rb index 75f9c0b284..beb987f7ca 100644 --- a/actionpack/lib/action_controller/request_forgery_protection.rb +++ b/actionpack/lib/action_controller/request_forgery_protection.rb @@ -13,33 +13,46 @@ module ActionController #:nodoc: base.extend(ClassMethods) end + # Protecting controller actions from CSRF attacks by ensuring that all forms are coming from the current web application, not a + # forged link from another site, 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. + # + # This is turned on with the <tt>protect_from_forgery</tt> method, which will check the token and raise an + # ActionController::InvalidAuthenticityToken if it doesn't match what was expected. You can customize the error message in + # production by editing public/422.html. A call to this method in ApplicationController is generated by default in post-Rails 2.0 + # applications. + # + # The token parameter is named <tt>authenticity_token</tt> by default. If you are generating an HTML form manually (without the + # use of Rails' <tt>form_for</tt>, <tt>form_tag</tt> or other helpers), you have to include a hidden field named like that and + # set its value to what is returned by <tt>form_authenticity_token</tt>. Same applies to manually constructed Ajax requests. To + # make the token available through a global variable to scripts on a certain page, you could add something like this to a view: + # + # <%= javascript_tag "window._token = '#{form_authenticity_token}'" %> + # + # Request forgery protection is disabled by default in test environment. If you are upgrading from Rails 1.x, add this to + # config/environments/test.rb: + # + # # Disable request forgery protection in test environment + # config.action_controller.allow_forgery_protection = false + # + # == Learn more about CSRF (Cross-Site Request Forgery) attacks + # + # Here are some resources: + # * 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 rails application. + # 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" + # 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::InvalidAuthenticityToken if the token doesn't match what was expected. And it will add - # a _authenticity_token parameter to all forms that are automatically generated by Rails. 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 rails application. - # 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 form_authenticity_token helper method and make it part of the parameters yourself. + # Turn on request forgery protection. Bear in mind that only non-GET, HTML/JavaScript requests are checked. # # Example: # @@ -54,16 +67,10 @@ module ActionController #:nodoc: # skip_before_filter :verify_authenticity_token # end # - # If you are upgrading from Rails 1.x, disable forgery protection to - # simplify your tests. Add this to config/environments/test.rb: - # - # # Disable request forgery protection in test environment - # config.action_controller.allow_forgery_protection = false - # # 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. + # * <tt>:only/:except</tt> - passed to the <tt>before_filter</tt> call. Set which actions are verified. + # * <tt>:secret</tt> - Custom salt used to generate the <tt>form_authenticity_token</tt>. # 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 = {}) |