| 1 |
NAME |
| 2 |
Catalyst::Plugin::Session - Generic Session plugin - ties together |
| 3 |
server side storage and client side state required to maintain session |
| 4 |
data. |
| 5 |
|
| 6 |
SYNOPSIS |
| 7 |
# To get sessions to "just work", all you need to do is use these plugins: |
| 8 |
|
| 9 |
use Catalyst qw/ |
| 10 |
Session |
| 11 |
Session::Store::FastMmap |
| 12 |
Session::State::Cookie |
| 13 |
/; |
| 14 |
|
| 15 |
# you can replace Store::FastMmap with Store::File - both have sensible |
| 16 |
# default configurations (see their docs for details) |
| 17 |
|
| 18 |
# more complicated backends are available for other scenarios (DBI storage, |
| 19 |
# etc) |
| 20 |
|
| 21 |
|
| 22 |
# after you've loaded the plugins you can save session data |
| 23 |
# For example, if you are writing a shopping cart, it could be implemented |
| 24 |
# like this: |
| 25 |
|
| 26 |
sub add_item : Local { |
| 27 |
my ( $self, $c ) = @_; |
| 28 |
|
| 29 |
my $item_id = $c->req->param("item"); |
| 30 |
|
| 31 |
# $c->session is a hash ref, a bit like $c->stash |
| 32 |
# the difference is that it' preserved across requests |
| 33 |
|
| 34 |
push @{ $c->session->{items} }, $item_id; |
| 35 |
|
| 36 |
$c->forward("MyView"); |
| 37 |
} |
| 38 |
|
| 39 |
sub display_items : Local { |
| 40 |
my ( $self, $c ) = @_; |
| 41 |
|
| 42 |
# values in $c->session are restored |
| 43 |
$c->stash->{items_to_display} = |
| 44 |
[ map { MyModel->retrieve($_) } @{ $c->session->{items} } ]; |
| 45 |
|
| 46 |
$c->forward("MyView"); |
| 47 |
} |
| 48 |
|
| 49 |
DESCRIPTION |
| 50 |
The Session plugin is the base of two related parts of functionality |
| 51 |
required for session management in web applications. |
| 52 |
|
| 53 |
The first part, the State, is getting the browser to repeat back a |
| 54 |
session key, so that the web application can identify the client and |
| 55 |
logically string several requests together into a session. |
| 56 |
|
| 57 |
The second part, the Store, deals with the actual storage of information |
| 58 |
about the client. This data is stored so that the it may be revived for |
| 59 |
every request made by the same client. |
| 60 |
|
| 61 |
This plugin links the two pieces together. |
| 62 |
|
| 63 |
RECOMENDED BACKENDS |
| 64 |
Session::State::Cookie |
| 65 |
The only really sane way to do state is using cookies. |
| 66 |
|
| 67 |
Session::Store::File |
| 68 |
A portable backend, based on Cache::File. |
| 69 |
|
| 70 |
Session::Store::FastMmap |
| 71 |
A fast and flexible backend, based on Cache::FastMmap. |
| 72 |
|
| 73 |
METHODS |
| 74 |
sessionid |
| 75 |
An accessor for the session ID value. |
| 76 |
|
| 77 |
session |
| 78 |
Returns a hash reference that might contain unserialized values from |
| 79 |
previous requests in the same session, and whose modified value will |
| 80 |
be saved for future requests. |
| 81 |
|
| 82 |
This method will automatically create a new session and session ID |
| 83 |
if none exists. |
| 84 |
|
| 85 |
You can also set session keys by passing a list of key/value pairs |
| 86 |
or a hashref. |
| 87 |
|
| 88 |
$c->session->{foo} = "bar"; # This works. |
| 89 |
$c->session(one => 1, two => 2); # And this. |
| 90 |
$c->session({ answer => 42 }); # And this. |
| 91 |
|
| 92 |
session_expires |
| 93 |
This method returns the time when the current session will expire, |
| 94 |
or 0 if there is no current session. If there is a session and it |
| 95 |
already expired, it will delete the session and return 0 as well. |
| 96 |
|
| 97 |
flash |
| 98 |
This is like Ruby on Rails' flash data structure. Think of it as a |
| 99 |
stash that lasts for longer than one request, letting you redirect |
| 100 |
instead of forward. |
| 101 |
|
| 102 |
The flash data will be cleaned up only on requests on which actually |
| 103 |
use $c->flash (thus allowing multiple redirections), and the policy |
| 104 |
is to delete all the keys which haven't changed since the flash data |
| 105 |
was loaded at the end of every request. |
| 106 |
|
| 107 |
Note that use of the flash is an easy way to get data across |
| 108 |
requests, but it's also strongly disrecommended, due it it being |
| 109 |
inherently plagued with race conditions. This means that it's |
| 110 |
unlikely to work well if your users have multiple tabs open at once, |
| 111 |
or if your site does a lot of AJAX requests. |
| 112 |
|
| 113 |
Catalyst::Plugin::StatusMessage is the recommended alternative |
| 114 |
solution, as this doesn't suffer from these issues. |
| 115 |
|
| 116 |
sub moose : Local { |
| 117 |
my ( $self, $c ) = @_; |
| 118 |
|
| 119 |
$c->flash->{beans} = 10; |
| 120 |
$c->response->redirect( $c->uri_for("foo") ); |
| 121 |
} |
| 122 |
|
| 123 |
sub foo : Local { |
| 124 |
my ( $self, $c ) = @_; |
| 125 |
|
| 126 |
my $value = $c->flash->{beans}; |
| 127 |
|
| 128 |
# ... |
| 129 |
|
| 130 |
$c->response->redirect( $c->uri_for("bar") ); |
| 131 |
} |
| 132 |
|
| 133 |
sub bar : Local { |
| 134 |
my ( $self, $c ) = @_; |
| 135 |
|
| 136 |
if ( exists $c->flash->{beans} ) { # false |
| 137 |
|
| 138 |
} |
| 139 |
} |
| 140 |
|
| 141 |
clear_flash |
| 142 |
Zap all the keys in the flash regardless of their current state. |
| 143 |
|
| 144 |
keep_flash @keys |
| 145 |
If you want to keep a flash key for the next request too, even if it |
| 146 |
hasn't changed, call "keep_flash" and pass in the keys as arguments. |
| 147 |
|
| 148 |
delete_session REASON |
| 149 |
This method is used to invalidate a session. It takes an optional |
| 150 |
parameter which will be saved in "session_delete_reason" if |
| 151 |
provided. |
| 152 |
|
| 153 |
NOTE: This method will also delete your flash data. |
| 154 |
|
| 155 |
session_delete_reason |
| 156 |
This accessor contains a string with the reason a session was |
| 157 |
deleted. Possible values include: |
| 158 |
|
| 159 |
* "address mismatch" |
| 160 |
|
| 161 |
* "session expired" |
| 162 |
|
| 163 |
session_expire_key $key, $ttl |
| 164 |
Mark a key to expire at a certain time (only useful when shorter |
| 165 |
than the expiry time for the whole session). |
| 166 |
|
| 167 |
For example: |
| 168 |
|
| 169 |
__PACKAGE__->config('Plugin::Session' => { expires => 10000000000 }); # "forever" |
| 170 |
(NB If this number is too large, Y2K38 breakage could result.) |
| 171 |
|
| 172 |
# later |
| 173 |
|
| 174 |
$c->session_expire_key( __user => 3600 ); |
| 175 |
|
| 176 |
Will make the session data survive, but the user will still be |
| 177 |
logged out after an hour. |
| 178 |
|
| 179 |
Note that these values are not auto extended. |
| 180 |
|
| 181 |
change_session_id |
| 182 |
By calling this method you can force a session id change while |
| 183 |
keeping all session data. This method might come handy when you are |
| 184 |
paranoid about some advanced variations of session fixation attack. |
| 185 |
|
| 186 |
If you want to prevent this session fixation scenario: |
| 187 |
|
| 188 |
0) let us have WebApp with anonymous and authenticated parts |
| 189 |
1) a hacker goes to vulnerable WebApp and gets a real sessionid, |
| 190 |
just by browsing anonymous part of WebApp |
| 191 |
2) the hacker inserts (somehow) this values into a cookie in victim's browser |
| 192 |
3) after the victim logs into WebApp the hacker can enter his/her session |
| 193 |
|
| 194 |
you should call change_session_id in your login controller like |
| 195 |
this: |
| 196 |
|
| 197 |
if ($c->authenticate( { username => $user, password => $pass } )) { |
| 198 |
# login OK |
| 199 |
$c->change_session_id; |
| 200 |
... |
| 201 |
} else { |
| 202 |
# login FAILED |
| 203 |
... |
| 204 |
} |
| 205 |
|
| 206 |
change_session_expires $expires |
| 207 |
You can change the session expiration time for this session; |
| 208 |
|
| 209 |
$c->change_session_expires( 4000 ); |
| 210 |
|
| 211 |
Note that this only works to set the session longer than the config |
| 212 |
setting. |
| 213 |
|
| 214 |
INTERNAL METHODS |
| 215 |
setup |
| 216 |
This method is extended to also make calls to |
| 217 |
"check_session_plugin_requirements" and "setup_session". |
| 218 |
|
| 219 |
check_session_plugin_requirements |
| 220 |
This method ensures that a State and a Store plugin are also in use |
| 221 |
by the application. |
| 222 |
|
| 223 |
setup_session |
| 224 |
This method populates "$c->config('Plugin::Session')" with the |
| 225 |
default values listed in "CONFIGURATION". |
| 226 |
|
| 227 |
prepare_action |
| 228 |
This method is extended. |
| 229 |
|
| 230 |
Its only effect is if the (off by default) "flash_to_stash" |
| 231 |
configuration parameter is on - then it will copy the contents of |
| 232 |
the flash to the stash at prepare time. |
| 233 |
|
| 234 |
finalize_headers |
| 235 |
This method is extended and will extend the expiry time before |
| 236 |
sending the response. |
| 237 |
|
| 238 |
finalize_body |
| 239 |
This method is extended and will call finalize_session before the |
| 240 |
other finalize_body methods run. Here we persist the session data if |
| 241 |
a session exists. |
| 242 |
|
| 243 |
initialize_session_data |
| 244 |
This method will initialize the internal structure of the session, |
| 245 |
and is called by the "session" method if appropriate. |
| 246 |
|
| 247 |
create_session_id |
| 248 |
Creates a new session ID using "generate_session_id" if there is no |
| 249 |
session ID yet. |
| 250 |
|
| 251 |
validate_session_id SID |
| 252 |
Make sure a session ID is of the right format. |
| 253 |
|
| 254 |
This currently ensures that the session ID string is any amount of |
| 255 |
case insensitive hexadecimal characters. |
| 256 |
|
| 257 |
generate_session_id |
| 258 |
This method will return a string that can be used as a session ID. |
| 259 |
It is simply a hexidecimal string of raw bytes from the system |
| 260 |
entropy source, e.g. /dev/urandom. |
| 261 |
|
| 262 |
session_hash_seed |
| 263 |
This method returns raw bytes from the system random source. It is |
| 264 |
no longer used but exists for legacy code that might override |
| 265 |
"generate_session_id" but still uses this method. |
| 266 |
|
| 267 |
finalize_session |
| 268 |
Clean up the session during "finalize". |
| 269 |
|
| 270 |
This clears the various accessors after saving to the store. |
| 271 |
|
| 272 |
dump_these |
| 273 |
See "dump_these" in Catalyst - ammends the session data structure to |
| 274 |
the list of dumped objects if session ID is defined. |
| 275 |
|
| 276 |
calculate_extended_session_expires |
| 277 |
calculate_initial_session_expires |
| 278 |
create_session_id_if_needed |
| 279 |
delete_session_id |
| 280 |
extend_session_expires |
| 281 |
Note: this is *not* used to give an individual user a longer |
| 282 |
session. See 'change_session_expires'. |
| 283 |
|
| 284 |
extend_session_id |
| 285 |
get_session_id |
| 286 |
reset_session_expires |
| 287 |
session_is_valid |
| 288 |
set_session_id |
| 289 |
initial_session_expires |
| 290 |
|
| 291 |
USING SESSIONS DURING PREPARE |
| 292 |
The earliest point in time at which you may use the session data is |
| 293 |
after Catalyst::Plugin::Session's "prepare_action" has finished. |
| 294 |
|
| 295 |
State plugins must set $c->session ID before "prepare_action", and |
| 296 |
during "prepare_action" Catalyst::Plugin::Session will actually load the |
| 297 |
data from the store. |
| 298 |
|
| 299 |
sub prepare_action { |
| 300 |
my $c = shift; |
| 301 |
|
| 302 |
# don't touch $c->session yet! |
| 303 |
|
| 304 |
$c->NEXT::prepare_action( @_ ); |
| 305 |
|
| 306 |
$c->session; # this is OK |
| 307 |
$c->sessionid; # this is also OK |
| 308 |
} |
| 309 |
|
| 310 |
CONFIGURATION |
| 311 |
$c->config('Plugin::Session' => { |
| 312 |
expires => 1234, |
| 313 |
}); |
| 314 |
|
| 315 |
All configuation parameters are provided in a hash reference under the |
| 316 |
"Plugin::Session" key in the configuration hash. |
| 317 |
|
| 318 |
expires |
| 319 |
The time-to-live of each session, expressed in seconds. Defaults to |
| 320 |
7200 (two hours). |
| 321 |
|
| 322 |
expiry_threshold |
| 323 |
Only update the session expiry time if it would otherwise expire |
| 324 |
within this many seconds from now. |
| 325 |
|
| 326 |
The purpose of this is to keep the session store from being updated |
| 327 |
when nothing else in the session is updated. |
| 328 |
|
| 329 |
Defaults to 0 (in which case, the expiration will always be |
| 330 |
updated). |
| 331 |
|
| 332 |
verify_address |
| 333 |
When true, "$c->request->address" will be checked at prepare time. |
| 334 |
If it is not the same as the address that initiated the session, the |
| 335 |
session is deleted. |
| 336 |
|
| 337 |
Defaults to false. |
| 338 |
|
| 339 |
verify_user_agent |
| 340 |
When true, "$c->request->user_agent" will be checked at prepare |
| 341 |
time. If it is not the same as the user agent that initiated the |
| 342 |
session, the session is deleted. |
| 343 |
|
| 344 |
Defaults to false. |
| 345 |
|
| 346 |
flash_to_stash |
| 347 |
This option makes it easier to have actions behave the same whether |
| 348 |
they were forwarded to or redirected to. On prepare time it copies |
| 349 |
the contents of "flash" (if any) to the stash. |
| 350 |
|
| 351 |
SPECIAL KEYS |
| 352 |
The hash reference returned by "$c->session" contains several keys which |
| 353 |
are automatically set: |
| 354 |
|
| 355 |
__expires |
| 356 |
This key no longer exists. Use "session_expires" instead. |
| 357 |
|
| 358 |
__updated |
| 359 |
The last time a session was saved to the store. |
| 360 |
|
| 361 |
__created |
| 362 |
The time when the session was first created. |
| 363 |
|
| 364 |
__address |
| 365 |
The value of "$c->request->address" at the time the session was |
| 366 |
created. This value is only populated if "verify_address" is true in |
| 367 |
the configuration. |
| 368 |
|
| 369 |
__user_agent |
| 370 |
The value of "$c->request->user_agent" at the time the session was |
| 371 |
created. This value is only populated if "verify_user_agent" is true |
| 372 |
in the configuration. |
| 373 |
|
| 374 |
CAVEATS |
| 375 |
Round the Robin Proxies |
| 376 |
"verify_address" could make your site inaccessible to users who are |
| 377 |
behind load balanced proxies. Some ISPs may give a different IP to each |
| 378 |
request by the same client due to this type of proxying. If addresses |
| 379 |
are verified these users' sessions cannot persist. |
| 380 |
|
| 381 |
To let these users access your site you can either disable address |
| 382 |
verification as a whole, or provide a checkbox in the login dialog that |
| 383 |
tells the server that it's OK for the address of the client to change. |
| 384 |
When the server sees that this box is checked it should delete the |
| 385 |
"__address" special key from the session hash when the hash is first |
| 386 |
created. |
| 387 |
|
| 388 |
Race Conditions |
| 389 |
In this day and age where cleaning detergents and Dutch football (not |
| 390 |
the American kind) teams roam the plains in great numbers, requests may |
| 391 |
happen simultaneously. This means that there is some risk of session |
| 392 |
data being overwritten, like this: |
| 393 |
|
| 394 |
1. request a starts, request b starts, with the same session ID |
| 395 |
|
| 396 |
2. session data is loaded in request a |
| 397 |
|
| 398 |
3. session data is loaded in request b |
| 399 |
|
| 400 |
4. session data is changed in request a |
| 401 |
|
| 402 |
5. request a finishes, session data is updated and written to store |
| 403 |
|
| 404 |
6. request b finishes, session data is updated and written to store, |
| 405 |
overwriting changes by request a |
| 406 |
|
| 407 |
For applications where any given user's session is only making one |
| 408 |
request at a time this plugin should be safe enough. |
| 409 |
|
| 410 |
AUTHORS |
| 411 |
Andy Grundman |
| 412 |
|
| 413 |
Christian Hansen |
| 414 |
|
| 415 |
Yuval Kogman, "[email protected]" |
| 416 |
|
| 417 |
Sebastian Riedel |
| 418 |
|
| 419 |
Tomas Doran (t0m) "[email protected]" (current maintainer) |
| 420 |
|
| 421 |
Sergio Salvi |
| 422 |
|
| 423 |
kmx "[email protected]" |
| 424 |
|
| 425 |
Florian Ragwitz (rafl) "[email protected]" |
| 426 |
|
| 427 |
Kent Fredric (kentnl) |
| 428 |
|
| 429 |
And countless other contributers from #catalyst. Thanks guys! |
| 430 |
|
| 431 |
Contributors |
| 432 |
Devin Austin (dhoss) <[email protected]> |
| 433 |
|
| 434 |
Robert Rothenberg <[email protected]> |
| 435 |
|
| 436 |
COPYRIGHT & LICENSE |
| 437 |
Copyright (c) 2005 the aforementioned authors. All rights |
| 438 |
reserved. This program is free software; you can redistribute |
| 439 |
it and/or modify it under the same terms as Perl itself. |
| 440 |
|