| 1 |
<?xml version="1.0" encoding="iso-8859-1"?> |
|---|
| 2 |
<!DOCTYPE html |
|---|
| 3 |
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
|---|
| 4 |
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|---|
| 5 |
|
|---|
| 6 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
|---|
| 7 |
<head> |
|---|
| 8 |
<title>Module: ActionController::RequestForgeryProtection::ClassMethods</title> |
|---|
| 9 |
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> |
|---|
| 10 |
<meta http-equiv="Content-Script-Type" content="text/javascript" /> |
|---|
| 11 |
<style type="text/css" media="screen"> |
|---|
| 12 |
body { |
|---|
| 13 |
font-family: Verdana,Arial,Helvetica,sans-serif; |
|---|
| 14 |
font-size: 90%; |
|---|
| 15 |
margin: 0; |
|---|
| 16 |
margin-left: 40px; |
|---|
| 17 |
padding: 0; |
|---|
| 18 |
background: white; |
|---|
| 19 |
} |
|---|
| 20 |
|
|---|
| 21 |
h1,h2,h3,h4 { margin: 0; color: #efefef; background: transparent; } |
|---|
| 22 |
h1 { font-size: 150%; } |
|---|
| 23 |
h2,h3,h4 { margin-top: 1em; } |
|---|
| 24 |
|
|---|
| 25 |
a { background: #eef; color: #039; text-decoration: none; } |
|---|
| 26 |
a:hover { background: #039; color: #eef; } |
|---|
| 27 |
|
|---|
| 28 |
/* Override the base stylesheet's Anchor inside a table cell */ |
|---|
| 29 |
td > a { |
|---|
| 30 |
background: transparent; |
|---|
| 31 |
color: #039; |
|---|
| 32 |
text-decoration: none; |
|---|
| 33 |
} |
|---|
| 34 |
|
|---|
| 35 |
/* and inside a section title */ |
|---|
| 36 |
.section-title > a { |
|---|
| 37 |
background: transparent; |
|---|
| 38 |
color: #eee; |
|---|
| 39 |
text-decoration: none; |
|---|
| 40 |
} |
|---|
| 41 |
|
|---|
| 42 |
/* === Structural elements =================================== */ |
|---|
| 43 |
|
|---|
| 44 |
div#index { |
|---|
| 45 |
margin: 0; |
|---|
| 46 |
margin-left: -40px; |
|---|
| 47 |
padding: 0; |
|---|
| 48 |
font-size: 90%; |
|---|
| 49 |
} |
|---|
| 50 |
|
|---|
| 51 |
|
|---|
| 52 |
div#index a { |
|---|
| 53 |
margin-left: 0.7em; |
|---|
| 54 |
} |
|---|
| 55 |
|
|---|
| 56 |
div#index .section-bar { |
|---|
| 57 |
margin-left: 0px; |
|---|
| 58 |
padding-left: 0.7em; |
|---|
| 59 |
background: #ccc; |
|---|
| 60 |
font-size: small; |
|---|
| 61 |
} |
|---|
| 62 |
|
|---|
| 63 |
|
|---|
| 64 |
div#classHeader, div#fileHeader { |
|---|
| 65 |
width: auto; |
|---|
| 66 |
color: white; |
|---|
| 67 |
padding: 0.5em 1.5em 0.5em 1.5em; |
|---|
| 68 |
margin: 0; |
|---|
| 69 |
margin-left: -40px; |
|---|
| 70 |
border-bottom: 3px solid #006; |
|---|
| 71 |
} |
|---|
| 72 |
|
|---|
| 73 |
div#classHeader a, div#fileHeader a { |
|---|
| 74 |
background: inherit; |
|---|
| 75 |
color: white; |
|---|
| 76 |
} |
|---|
| 77 |
|
|---|
| 78 |
div#classHeader td, div#fileHeader td { |
|---|
| 79 |
background: inherit; |
|---|
| 80 |
color: white; |
|---|
| 81 |
} |
|---|
| 82 |
|
|---|
| 83 |
|
|---|
| 84 |
div#fileHeader { |
|---|
| 85 |
background: #057; |
|---|
| 86 |
} |
|---|
| 87 |
|
|---|
| 88 |
div#classHeader { |
|---|
| 89 |
background: #048; |
|---|
| 90 |
} |
|---|
| 91 |
|
|---|
| 92 |
|
|---|
| 93 |
.class-name-in-header { |
|---|
| 94 |
font-size: 180%; |
|---|
| 95 |
font-weight: bold; |
|---|
| 96 |
} |
|---|
| 97 |
|
|---|
| 98 |
|
|---|
| 99 |
div#bodyContent { |
|---|
| 100 |
padding: 0 1.5em 0 1.5em; |
|---|
| 101 |
} |
|---|
| 102 |
|
|---|
| 103 |
div#description { |
|---|
| 104 |
padding: 0.5em 1.5em; |
|---|
| 105 |
background: #efefef; |
|---|
| 106 |
border: 1px dotted #999; |
|---|
| 107 |
} |
|---|
| 108 |
|
|---|
| 109 |
div#description h1,h2,h3,h4,h5,h6 { |
|---|
| 110 |
color: #125;; |
|---|
| 111 |
background: transparent; |
|---|
| 112 |
} |
|---|
| 113 |
|
|---|
| 114 |
div#validator-badges { |
|---|
| 115 |
text-align: center; |
|---|
| 116 |
} |
|---|
| 117 |
div#validator-badges img { border: 0; } |
|---|
| 118 |
|
|---|
| 119 |
div#copyright { |
|---|
| 120 |
color: #333; |
|---|
| 121 |
background: #efefef; |
|---|
| 122 |
font: 0.75em sans-serif; |
|---|
| 123 |
margin-top: 5em; |
|---|
| 124 |
margin-bottom: 0; |
|---|
| 125 |
padding: 0.5em 2em; |
|---|
| 126 |
} |
|---|
| 127 |
|
|---|
| 128 |
|
|---|
| 129 |
/* === Classes =================================== */ |
|---|
| 130 |
|
|---|
| 131 |
table.header-table { |
|---|
| 132 |
color: white; |
|---|
| 133 |
font-size: small; |
|---|
| 134 |
} |
|---|
| 135 |
|
|---|
| 136 |
.type-note { |
|---|
| 137 |
font-size: small; |
|---|
| 138 |
color: #DEDEDE; |
|---|
| 139 |
} |
|---|
| 140 |
|
|---|
| 141 |
.xxsection-bar { |
|---|
| 142 |
background: #eee; |
|---|
| 143 |
color: #333; |
|---|
| 144 |
padding: 3px; |
|---|
| 145 |
} |
|---|
| 146 |
|
|---|
| 147 |
.section-bar { |
|---|
| 148 |
color: #333; |
|---|
| 149 |
border-bottom: 1px solid #999; |
|---|
| 150 |
margin-left: -20px; |
|---|
| 151 |
} |
|---|
| 152 |
|
|---|
| 153 |
|
|---|
| 154 |
.section-title { |
|---|
| 155 |
background: #79a; |
|---|
| 156 |
color: #eee; |
|---|
| 157 |
padding: 3px; |
|---|
| 158 |
margin-top: 2em; |
|---|
| 159 |
margin-left: -30px; |
|---|
| 160 |
border: 1px solid #999; |
|---|
| 161 |
} |
|---|
| 162 |
|
|---|
| 163 |
.top-aligned-row { vertical-align: top } |
|---|
| 164 |
.bottom-aligned-row { vertical-align: bottom } |
|---|
| 165 |
|
|---|
| 166 |
/* --- Context section classes ----------------------- */ |
|---|
| 167 |
|
|---|
| 168 |
.context-row { } |
|---|
| 169 |
.context-item-name { font-family: monospace; font-weight: bold; color: black; } |
|---|
| 170 |
.context-item-value { font-size: small; color: #448; } |
|---|
| 171 |
.context-item-desc { color: #333; padding-left: 2em; } |
|---|
| 172 |
|
|---|
| 173 |
/* --- Method classes -------------------------- */ |
|---|
| 174 |
.method-detail { |
|---|
| 175 |
background: #efefef; |
|---|
| 176 |
padding: 0; |
|---|
| 177 |
margin-top: 0.5em; |
|---|
| 178 |
margin-bottom: 1em; |
|---|
| 179 |
border: 1px dotted #ccc; |
|---|
| 180 |
} |
|---|
| 181 |
.method-heading { |
|---|
| 182 |
color: black; |
|---|
| 183 |
background: #ccc; |
|---|
| 184 |
border-bottom: 1px solid #666; |
|---|
| 185 |
padding: 0.2em 0.5em 0 0.5em; |
|---|
| 186 |
} |
|---|
| 187 |
.method-signature { color: black; background: inherit; } |
|---|
| 188 |
.method-name { font-weight: bold; } |
|---|
| 189 |
.method-args { font-style: italic; } |
|---|
| 190 |
.method-description { padding: 0 0.5em 0 0.5em; } |
|---|
| 191 |
|
|---|
| 192 |
/* --- Source code sections -------------------- */ |
|---|
| 193 |
|
|---|
| 194 |
a.source-toggle { font-size: 90%; } |
|---|
| 195 |
div.method-source-code { |
|---|
| 196 |
background: #262626; |
|---|
| 197 |
color: #ffdead; |
|---|
| 198 |
margin: 1em; |
|---|
| 199 |
padding: 0.5em; |
|---|
| 200 |
border: 1px dashed #999; |
|---|
| 201 |
overflow: hidden; |
|---|
| 202 |
} |
|---|
| 203 |
|
|---|
| 204 |
div.method-source-code pre { color: #ffdead; overflow: hidden; } |
|---|
| 205 |
|
|---|
| 206 |
/* --- Ruby keyword styles --------------------- */ |
|---|
| 207 |
|
|---|
| 208 |
.standalone-code { background: #221111; color: #ffdead; overflow: hidden; } |
|---|
| 209 |
|
|---|
| 210 |
.ruby-constant { color: #7fffd4; background: transparent; } |
|---|
| 211 |
.ruby-keyword { color: #00ffff; background: transparent; } |
|---|
| 212 |
.ruby-ivar { color: #eedd82; background: transparent; } |
|---|
| 213 |
.ruby-operator { color: #00ffee; background: transparent; } |
|---|
| 214 |
.ruby-identifier { color: #ffdead; background: transparent; } |
|---|
| 215 |
.ruby-node { color: #ffa07a; background: transparent; } |
|---|
| 216 |
.ruby-comment { color: #b22222; font-weight: bold; background: transparent; } |
|---|
| 217 |
.ruby-regexp { color: #ffa07a; background: transparent; } |
|---|
| 218 |
.ruby-value { color: #7fffd4; background: transparent; } |
|---|
| 219 |
</style> |
|---|
| 220 |
<script type="text/javascript"> |
|---|
| 221 |
|
|---|
| 222 |
|
|---|
| 223 |
function popupCode( url ) { |
|---|
| 224 |
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400") |
|---|
| 225 |
} |
|---|
| 226 |
|
|---|
| 227 |
function toggleCode( id ) { |
|---|
| 228 |
if ( document.getElementById ) |
|---|
| 229 |
elem = document.getElementById( id ); |
|---|
| 230 |
else if ( document.all ) |
|---|
| 231 |
elem = eval( "document.all." + id ); |
|---|
| 232 |
else |
|---|
| 233 |
return false; |
|---|
| 234 |
|
|---|
| 235 |
elemStyle = elem.style; |
|---|
| 236 |
|
|---|
| 237 |
if ( elemStyle.display != "block" ) { |
|---|
| 238 |
elemStyle.display = "block" |
|---|
| 239 |
} else { |
|---|
| 240 |
elemStyle.display = "none" |
|---|
| 241 |
} |
|---|
| 242 |
|
|---|
| 243 |
return true; |
|---|
| 244 |
} |
|---|
| 245 |
|
|---|
| 246 |
|
|---|
| 247 |
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" ) |
|---|
| 248 |
|
|---|
| 249 |
|
|---|
| 250 |
</script> |
|---|
| 251 |
|
|---|
| 252 |
</head> |
|---|
| 253 |
<body> |
|---|
| 254 |
|
|---|
| 255 |
|
|---|
| 256 |
|
|---|
| 257 |
<div id="classHeader"> |
|---|
| 258 |
<table class="header-table"> |
|---|
| 259 |
<tr class="top-aligned-row"> |
|---|
| 260 |
<td><strong>Module</strong></td> |
|---|
| 261 |
<td class="class-name-in-header">ActionController::RequestForgeryProtection::ClassMethods</td> |
|---|
| 262 |
</tr> |
|---|
| 263 |
<tr class="top-aligned-row"> |
|---|
| 264 |
<td><strong>In:</strong></td> |
|---|
| 265 |
<td> |
|---|
| 266 |
<a href="../../../files/lib/action_controller/request_forgery_protection_rb.html"> |
|---|
| 267 |
lib/action_controller/request_forgery_protection.rb |
|---|
| 268 |
</a> |
|---|
| 269 |
<br /> |
|---|
| 270 |
</td> |
|---|
| 271 |
</tr> |
|---|
| 272 |
|
|---|
| 273 |
</table> |
|---|
| 274 |
</div> |
|---|
| 275 |
|
|---|
| 276 |
|
|---|
| 277 |
<div id="bodyContent"> |
|---|
| 278 |
|
|---|
| 279 |
|
|---|
| 280 |
|
|---|
| 281 |
<div id="contextContent"> |
|---|
| 282 |
|
|---|
| 283 |
<div id="description"> |
|---|
| 284 |
<p> |
|---|
| 285 |
Protecting controller actions from CSRF attacks by ensuring that all forms |
|---|
| 286 |
are coming from the current web application, not a forged link from another |
|---|
| 287 |
site, is done by embedding a token based on the session (which an attacker |
|---|
| 288 |
wouldn‘t know) in all forms and Ajax requests generated by Rails and |
|---|
| 289 |
then verifying the authenticity of that token in the controller. Only |
|---|
| 290 |
HTML/JavaScript requests are checked, so this will not protect your XML API |
|---|
| 291 |
(presumably you‘ll have a different authentication scheme there |
|---|
| 292 |
anyway). Also, GET requests are not protected as these should be |
|---|
| 293 |
indempotent anyway. |
|---|
| 294 |
</p> |
|---|
| 295 |
<p> |
|---|
| 296 |
This is turned on with the <tt><a |
|---|
| 297 |
href="ClassMethods.html#M000009">protect_from_forgery</a></tt> method, |
|---|
| 298 |
which will check the token and raise an |
|---|
| 299 |
ActionController::InvalidAuthenticityToken if it doesn‘t match what |
|---|
| 300 |
was expected. You can customize the error message in production by editing |
|---|
| 301 |
public/422.html. A call to this method in ApplicationController is |
|---|
| 302 |
generated by default in post-Rails 2.0 applications. |
|---|
| 303 |
</p> |
|---|
| 304 |
<p> |
|---|
| 305 |
The token parameter is named <tt>authenticity_token</tt> by default. If you |
|---|
| 306 |
are generating an HTML form manually (without the use of Rails’ |
|---|
| 307 |
<tt>form_for</tt>, <tt>form_tag</tt> or other helpers), you have to include |
|---|
| 308 |
a hidden field named like that and set its value to what is returned by |
|---|
| 309 |
<tt>form_authenticity_token</tt>. Same applies to manually constructed Ajax |
|---|
| 310 |
requests. To make the token available through a global variable to scripts |
|---|
| 311 |
on a certain page, you could add something like this to a view: |
|---|
| 312 |
</p> |
|---|
| 313 |
<pre> |
|---|
| 314 |
<%= javascript_tag "window._token = '#{form_authenticity_token}'" %> |
|---|
| 315 |
</pre> |
|---|
| 316 |
<p> |
|---|
| 317 |
Request forgery protection is disabled by default in test environment. If |
|---|
| 318 |
you are upgrading from Rails 1.x, add this to config/environments/test.rb: |
|---|
| 319 |
</p> |
|---|
| 320 |
<pre> |
|---|
| 321 |
# Disable request forgery protection in test environment |
|---|
| 322 |
config.action_controller.allow_forgery_protection = false |
|---|
| 323 |
</pre> |
|---|
| 324 |
<h2>Learn more about CSRF (Cross-Site Request Forgery) attacks</h2> |
|---|
| 325 |
<p> |
|---|
| 326 |
Here are some resources: |
|---|
| 327 |
</p> |
|---|
| 328 |
<ul> |
|---|
| 329 |
<li><a |
|---|
| 330 |
href="http://isc.sans.org/diary.html?storyid=1750">isc.sans.org/diary.html?storyid=1750</a> |
|---|
| 331 |
|
|---|
| 332 |
</li> |
|---|
| 333 |
<li><a |
|---|
| 334 |
href="http://en.wikipedia.org/wiki/Cross-site_request_forgery">en.wikipedia.org/wiki/Cross-site_request_forgery</a> |
|---|
| 335 |
|
|---|
| 336 |
</li> |
|---|
| 337 |
</ul> |
|---|
| 338 |
<p> |
|---|
| 339 |
Keep in mind, this is NOT a silver-bullet, plug ‘n’ play, warm |
|---|
| 340 |
security blanket for your rails application. There are a few guidelines you |
|---|
| 341 |
should follow: |
|---|
| 342 |
</p> |
|---|
| 343 |
<ul> |
|---|
| 344 |
<li>Keep your GET requests safe and idempotent. More reading material: |
|---|
| 345 |
|
|---|
| 346 |
<ul> |
|---|
| 347 |
<li><a |
|---|
| 348 |
href="http://www.xml.com/pub/a/2002/04/24/deviant.html">www.xml.com/pub/a/2002/04/24/deviant.html</a> |
|---|
| 349 |
|
|---|
| 350 |
</li> |
|---|
| 351 |
<li><a |
|---|
| 352 |
href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1">www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1</a> |
|---|
| 353 |
|
|---|
| 354 |
</li> |
|---|
| 355 |
</ul> |
|---|
| 356 |
</li> |
|---|
| 357 |
<li>Make sure the session cookies that Rails creates are non-persistent. Check |
|---|
| 358 |
in Firefox and look for "Expires: at end of session" |
|---|
| 359 |
|
|---|
| 360 |
</li> |
|---|
| 361 |
</ul> |
|---|
| 362 |
|
|---|
| 363 |
</div> |
|---|
| 364 |
|
|---|
| 365 |
|
|---|
| 366 |
</div> |
|---|
| 367 |
|
|---|
| 368 |
<div id="method-list"> |
|---|
| 369 |
<h3 class="section-bar">Methods</h3> |
|---|
| 370 |
|
|---|
| 371 |
<div class="name-list"> |
|---|
| 372 |
<a href="#M000009">protect_from_forgery</a> |
|---|
| 373 |
</div> |
|---|
| 374 |
</div> |
|---|
| 375 |
|
|---|
| 376 |
</div> |
|---|
| 377 |
|
|---|
| 378 |
|
|---|
| 379 |
|
|---|
| 380 |
|
|---|
| 381 |
<div id="section"> |
|---|
| 382 |
|
|---|
| 383 |
|
|---|
| 384 |
|
|---|
| 385 |
|
|---|
| 386 |
|
|---|
| 387 |
|
|---|
| 388 |
|
|---|
| 389 |
|
|---|
| 390 |
|
|---|
| 391 |
<div id="methods"> |
|---|
| 392 |
<h3 class="section-bar">Public Instance methods</h3> |
|---|
| 393 |
|
|---|
| 394 |
<div id="method-M000009" class="method-detail"> |
|---|
| 395 |
<a name="M000009"></a> |
|---|
| 396 |
|
|---|
| 397 |
<div class="method-heading"> |
|---|
| 398 |
<a href="ClassMethods.src/M000009.html" target="Code" class="method-signature" |
|---|
| 399 |
onclick="popupCode('ClassMethods.src/M000009.html');return false;"> |
|---|
| 400 |
<span class="method-name">protect_from_forgery</span><span class="method-args">(options = {})</span> |
|---|
| 401 |
</a> |
|---|
| 402 |
</div> |
|---|
| 403 |
|
|---|
| 404 |
<div class="method-description"> |
|---|
| 405 |
<p> |
|---|
| 406 |
Turn on request forgery protection. Bear in mind that only non-GET, |
|---|
| 407 |
HTML/JavaScript requests are checked. |
|---|
| 408 |
</p> |
|---|
| 409 |
<p> |
|---|
| 410 |
Example: |
|---|
| 411 |
</p> |
|---|
| 412 |
<pre> |
|---|
| 413 |
class FooController < ApplicationController |
|---|
| 414 |
# uses the cookie session store (then you don't need a separate :secret) |
|---|
| 415 |
protect_from_forgery :except => :index |
|---|
| 416 |
|
|---|
| 417 |
# uses one of the other session stores that uses a session_id value. |
|---|
| 418 |
protect_from_forgery :secret => 'my-little-pony', :except => :index |
|---|
| 419 |
|
|---|
| 420 |
# you can disable csrf protection on controller-by-controller basis: |
|---|
| 421 |
skip_before_filter :verify_authenticity_token |
|---|
| 422 |
end |
|---|
| 423 |
</pre> |
|---|
| 424 |
<p> |
|---|
| 425 |
Valid Options: |
|---|
| 426 |
</p> |
|---|
| 427 |
<ul> |
|---|
| 428 |
<li><tt>:only/:except</tt> - passed to the <tt>before_filter</tt> call. Set |
|---|
| 429 |
which actions are verified. |
|---|
| 430 |
|
|---|
| 431 |
</li> |
|---|
| 432 |
<li><tt>:secret</tt> - Custom salt used to generate the |
|---|
| 433 |
<tt>form_authenticity_token</tt>. Leave this off if you are using the |
|---|
| 434 |
cookie session store. |
|---|
| 435 |
|
|---|
| 436 |
</li> |
|---|
| 437 |
<li><tt>:digest</tt> - Message digest used for hashing. Defaults to |
|---|
| 438 |
‘SHA1‘ |
|---|
| 439 |
|
|---|
| 440 |
</li> |
|---|
| 441 |
</ul> |
|---|
| 442 |
</div> |
|---|
| 443 |
</div> |
|---|
| 444 |
|
|---|
| 445 |
|
|---|
| 446 |
</div> |
|---|
| 447 |
|
|---|
| 448 |
|
|---|
| 449 |
</div> |
|---|
| 450 |
|
|---|
| 451 |
|
|---|
| 452 |
<div id="validator-badges"> |
|---|
| 453 |
<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p> |
|---|
| 454 |
</div> |
|---|
| 455 |
|
|---|
| 456 |
</body> |
|---|
| 457 |
</html> |
|---|
