Fix session fixation tests, kentnl++
[catagits/Catalyst-Plugin-Session.git] / lib / Catalyst / Plugin / Session.pm
index b603ce5..d1ab3ac 100644 (file)
@@ -1,38 +1,54 @@
 #!/usr/bin/perl
 
 package Catalyst::Plugin::Session;
-use base qw/Class::Accessor::Fast/;
 
-use strict;
-use warnings;
-
-use NEXT;
+use Moose;
+with 'MooseX::Emulate::Class::Accessor::Fast';
+use MRO::Compat;
 use Catalyst::Exception ();
 use Digest              ();
 use overload            ();
 use Object::Signature   ();
+use Carp;
+
+use namespace::clean -except => 'meta';
 
-our $VERSION = "0.05";
+our $VERSION = '0.28';
+$VERSION = eval $VERSION;
 
 my @session_data_accessors; # used in delete_session
-BEGIN {
-    __PACKAGE__->mk_accessors(
+
+__PACKAGE__->mk_accessors(
         "_session_delete_reason",
         @session_data_accessors = qw/
           _sessionid
           _session
           _session_expires
+          _extended_session_expires
           _session_data_sig
           _flash
-          _flash_stale_keys
+          _flash_keep_keys
+          _flash_key_hashes
+          _tried_loading_session_id
+          _tried_loading_session_data
+          _tried_loading_session_expires
+          _tried_loading_flash_data
           /
-    );
+);
+
+sub _session_plugin_config {
+    my $c = shift;
+    # FIXME - Start warning once all the state/store modules have also been updated.
+    #$c->log->warn("Deprecated 'session' config key used, please use the key 'Plugin::Session' instead")
+    #    if exists $c->config->{session}
+    #$c->config->{'Plugin::Session'} ||= delete($c->config->{session}) || {};
+    $c->config->{'Plugin::Session'} ||= $c->config->{session} || {};
 }
 
 sub setup {
     my $c = shift;
 
-    $c->NEXT::setup(@_);
+    $c->maybe::next::method(@_);
 
     $c->check_session_plugin_requirements;
     $c->setup_session;
@@ -58,60 +74,93 @@ sub check_session_plugin_requirements {
 sub setup_session {
     my $c = shift;
 
-    my $cfg = ( $c->config->{session} ||= {} );
+    my $cfg = $c->_session_plugin_config;
 
     %$cfg = (
         expires        => 7200,
-        verify_address => 1,
+        verify_address => 0,
+        verify_user_agent => 0,
         %$cfg,
     );
 
-    $c->NEXT::setup_session();
+    $c->maybe::next::method();
 }
 
 sub prepare_action {
     my $c = shift;
 
-    if (    $c->config->{session}{flash_to_stash}
-        and $c->_sessionid
+    $c->maybe::next::method(@_);
+
+    if (    $c->_session_plugin_config->{flash_to_stash}
+        and $c->sessionid
         and my $flash_data = $c->flash )
     {
         @{ $c->stash }{ keys %$flash_data } = values %$flash_data;
     }
+}
+
+sub finalize_headers {
+    my $c = shift;
+
+    # fix cookie before we send headers
+    $c->_save_session_expires;
 
-    $c->NEXT::prepare_action(@_);
+    return $c->maybe::next::method(@_);
 }
 
-sub finalize {
+sub finalize_body {
     my $c = shift;
 
+    # We have to finalize our session *before* $c->engine->finalize_xxx is called,
+    # because we do not want to send the HTTP response before the session is stored/committed to
+    # the session database (or whatever Session::Store you use).
+    $c->finalize_session;
+
+    return $c->maybe::next::method(@_);
+}
+
+sub finalize_session {
+    my $c = shift;
+
+    $c->maybe::next::method(@_);
+
+    $c->_save_session_id;
     $c->_save_session;
     $c->_save_flash;
 
-    $c->NEXT::finalize(@_);
+    $c->_clear_session_instance_data;
 }
 
-sub _save_session {
+sub _save_session_id {
     my $c = shift;
 
-    if ( my $sid = $c->_sessionid ) {
+    # we already called set when allocating
+    # no need to tell the state plugins anything new
+}
 
-        # all sessions are extended at the end of the request
-        my $now = time;
+sub _save_session_expires {
+    my $c = shift;
 
-        if ( my $expires = $c->session_expires ) {
-            $c->store_session_data( "expires:$sid" => $expires );
-        }
+    if ( defined($c->_session_expires) ) {
+        my $expires = $c->session_expires; # force extension
 
-        if ( my $session_data = $c->_session ) {
+        my $sid = $c->sessionid;
+        $c->store_session_data( "expires:$sid" => $expires );
+    }
+}
 
-            no warnings 'uninitialized';
-            if ( Object::Signature::signature($session_data) ne
-                $c->_session_data_sig )
-            {
-                $session_data->{__updated} = $now;
-                $c->store_session_data( "session:$sid" => $session_data );
-            }
+sub _save_session {
+    my $c = shift;
+
+    if ( my $session_data = $c->_session ) {
+
+        no warnings 'uninitialized';
+        if ( Object::Signature::signature($session_data) ne
+            $c->_session_data_sig )
+        {
+            $session_data->{__updated} = time();
+            my $sid = $c->sessionid;
+            $c->store_session_data( "session:$sid" => $session_data );
         }
     }
 }
@@ -119,41 +168,84 @@ sub _save_session {
 sub _save_flash {
     my $c = shift;
 
-    if ( my $sid = $c->_sessionid ) {
-        if ( my $flash_data = $c->_flash ) {
-            delete @{$flash_data}{ @{ $c->_flash_stale_keys || [] } };
+    if ( my $flash_data = $c->_flash ) {
 
-            if (%$flash_data) {
-                $c->store_session_data( "flash:$sid", $flash_data );
-            }
-            else {
-                $c->delete_session_data("flash:$sid");
+        my $hashes = $c->_flash_key_hashes || {};
+        my $keep = $c->_flash_keep_keys || {};
+        foreach my $key ( keys %$hashes ) {
+            if ( !exists $keep->{$key} and Object::Signature::signature( \$flash_data->{$key} ) eq $hashes->{$key} ) {
+                delete $flash_data->{$key};
             }
         }
+
+        my $sid = $c->sessionid;
+
+        my $session_data = $c->_session;
+        if (%$flash_data) {
+            $session_data->{__flash} = $flash_data;
+        }
+        else {
+            delete $session_data->{__flash};
+        }
+        $c->_session($session_data);
+        $c->_save_session;
     }
 }
 
+sub _load_session_expires {
+    my $c = shift;
+    return $c->_session_expires if $c->_tried_loading_session_expires;
+    $c->_tried_loading_session_expires(1);
+
+    if ( my $sid = $c->sessionid ) {
+        my $expires = $c->get_session_data("expires:$sid") || 0;
+
+        if ( $expires >= time() ) {
+            $c->_session_expires( $expires );
+            return $expires;
+        } else {
+            $c->delete_session( "session expired" );
+            return 0;
+        }
+    }
+
+    return;
+}
+
 sub _load_session {
     my $c = shift;
+    return $c->_session if $c->_tried_loading_session_data;
+    $c->_tried_loading_session_data(1);
 
-    if ( my $sid = $c->_sessionid ) {
-        if ( $c->session_expires ) {    # > 0
+    if ( my $sid = $c->sessionid ) {
+        if ( $c->_load_session_expires ) {    # > 0
 
-            my $session_data = $c->get_session_data("session:$sid");
+            my $session_data = $c->get_session_data("session:$sid") || return;
             $c->_session($session_data);
 
             no warnings 'uninitialized';    # ne __address
-            if (   $c->config->{session}{verify_address}
+            if (   $c->_session_plugin_config->{verify_address}
                 && $session_data->{__address} ne $c->request->address )
             {
                 $c->log->warn(
                         "Deleting session $sid due to address mismatch ("
                       . $session_data->{__address} . " != "
-                      . $c->request->address . ")",
+                      . $c->request->address . ")"
                 );
                 $c->delete_session("address mismatch");
                 return;
             }
+            if (   $c->_session_plugin_config->{verify_user_agent}
+                && $session_data->{__user_agent} ne $c->request->user_agent )
+            {
+                $c->log->warn(
+                        "Deleting session $sid due to user agent mismatch ("
+                      . $session_data->{__user_agent} . " != "
+                      . $c->request->user_agent . ")"
+                );
+                $c->delete_session("user agent mismatch");
+                return;
+            }
 
             $c->log->debug(qq/Restored session "$sid"/) if $c->debug;
             $c->_session_data_sig( Object::Signature::signature($session_data) ) if $session_data;
@@ -168,17 +260,23 @@ sub _load_session {
 
 sub _load_flash {
     my $c = shift;
+    return $c->_flash if $c->_tried_loading_flash_data;
+    $c->_tried_loading_flash_data(1);
 
-    if ( my $sid = $c->_sessionid ) {
-        if ( my $flash_data = $c->_flash
-            || $c->_flash( $c->get_session_data("flash:$sid") ) )
+    if ( my $sid = $c->sessionid ) {
+
+        my $session_data = $c->session;
+        $c->_flash($session_data->{__flash});
+
+        if ( my $flash_data = $c->_flash )
         {
-            $c->_flash_stale_keys( [ keys %$flash_data ] );
+            $c->_flash_key_hashes({ map { $_ => Object::Signature::signature( \$flash_data->{$_} ) } keys %$flash_data });
+
             return $flash_data;
         }
     }
 
-    return undef;
+    return;
 }
 
 sub _expire_session_keys {
@@ -186,23 +284,51 @@ sub _expire_session_keys {
 
     my $now = time;
 
-    my $expiry = ( $data || $c->_session || {} )->{__expire_keys} || {};
-    foreach my $key ( grep { $expiry->{$_} < $now } keys %$expiry ) {
+    my $expire_times = ( $data || $c->_session || {} )->{__expire_keys} || {};
+    foreach my $key ( grep { $expire_times->{$_} < $now } keys %$expire_times ) {
         delete $c->_session->{$key};
-        delete $expiry->{$key};
+        delete $expire_times->{$key};
     }
 }
 
+sub _clear_session_instance_data {
+    my $c = shift;
+    $c->$_(undef) for @session_data_accessors;
+    $c->maybe::next::method(@_); # allow other plugins to hook in on this
+}
+
+sub change_session_id {
+    my $c = shift;
+
+    my $sessiondata = $c->session;
+    my $oldsid = $c->sessionid;
+    my $newsid = $c->create_session_id;
+
+    if ($oldsid) {
+        $c->log->debug(qq/change_sessid: deleting session data from "$oldsid"/) if $c->debug;
+        $c->delete_session_data("${_}:${oldsid}") for qw/session expires flash/;
+    }
+
+    $c->log->debug(qq/change_sessid: storing session data to "$newsid"/) if $c->debug;
+    $c->store_session_data( "session:$newsid" => $sessiondata );
+
+    return $newsid;
+}
+
 sub delete_session {
     my ( $c, $msg ) = @_;
 
+    $c->log->debug("Deleting session" . ( defined($msg) ? "($msg)" : '(no reason given)') ) if $c->debug;
+
     # delete the session data
-    my $sid = $c->_sessionid || return;
-    $c->delete_session_data("${_}:${sid}") for qw/session expires flash/;
+    if ( my $sid = $c->sessionid ) {
+        $c->delete_session_data("${_}:${sid}") for qw/session expires flash/;
+        $c->delete_session_id($sid);
+    }
 
     # reset the values in the context object
     # see the BEGIN block
-    $c->$_(undef) for @session_data_accessors;
+    $c->_clear_session_instance_data;
 
     $c->_session_delete_reason($msg);
 }
@@ -210,59 +336,84 @@ sub delete_session {
 sub session_delete_reason {
     my $c = shift;
 
-    $c->_load_session
-      if ( $c->_sessionid && !$c->_session );    # must verify session data
+    $c->session_is_valid; # check that it was loaded
 
     $c->_session_delete_reason(@_);
 }
 
 sub session_expires {
-    my ( $c, $should_create ) = @_;
+    my $c = shift;
 
-    $c->_session_expires || do {
-        if ( my $sid = $c->_sessionid ) {
-            my $now = time;
+    if ( defined( my $expires = $c->_extended_session_expires ) ) {
+        return $expires;
+    } elsif ( defined( $expires = $c->_load_session_expires ) ) {
+        return $c->extend_session_expires( $expires );
+    } else {
+        return 0;
+    }
+}
 
-            if ( !$should_create ) {
-                if ( ( $c->get_session_data("expires:$sid") || 0 ) < $now ) {
+sub extend_session_expires {
+    my ( $c, $expires ) = @_;
+    $c->_extended_session_expires( my $updated = $c->calculate_extended_session_expires( $expires ) );
+    $c->extend_session_id( $c->sessionid, $updated );
+    return $updated;
+}
 
-                    # session expired
-                    $c->log->debug("Deleting session $sid (expired)")
-                      if $c->debug;
-                    $c->delete_session("session expired");
-                    return 0;
-                }
-            }
+sub calculate_initial_session_expires {
+    my $c = shift;
+    return ( time() + $c->_session_plugin_config->{expires} );
+}
 
-            return $c->_session_expires(
-                $now + $c->config->{session}{expires} );
-        }
-    };
+sub calculate_extended_session_expires {
+    my ( $c, $prev ) = @_;
+    $c->calculate_initial_session_expires;
+}
+
+sub reset_session_expires {
+    my ( $c, $sid ) = @_;
+
+    my $exp = $c->calculate_initial_session_expires;
+    $c->_session_expires( $exp );
+    $c->_extended_session_expires( $exp );
+    $exp;
 }
 
 sub sessionid {
     my $c = shift;
 
-    if (@_) {
-        if($c->_sessionid()) {
-            $c->log->warn('Session ID already set, ignoring.');
-            return $c->_sessionid();
-        }
-        if ( $c->validate_session_id( my $sid = shift ) ) {
+    return $c->_sessionid || $c->_load_sessionid;
+}
+
+sub _load_sessionid {
+    my $c = shift;
+    return if $c->_tried_loading_session_id;
+    $c->_tried_loading_session_id(1);
+
+    if ( defined( my $sid = $c->get_session_id ) ) {
+        if ( $c->validate_session_id($sid) ) {
+            # temporarily set the inner key, so that validation will work
             $c->_sessionid($sid);
-            return unless defined wantarray;
-        }
-        else {
+            return $sid;
+        } else {
             my $err = "Tried to set invalid session ID '$sid'";
             $c->log->error($err);
             Catalyst::Exception->throw($err);
         }
     }
 
-    $c->_load_session
-      if ( $c->_sessionid && !$c->_session );    # must verify session data
+    return;
+}
+
+sub session_is_valid {
+    my $c = shift;
 
-    return $c->_sessionid;
+    # force a check for expiry, but also __address, etc
+    if ( $c->_load_session ) {
+        return 1;
+    } else {
+        return;
+    }
 }
 
 sub validate_session_id {
@@ -275,18 +426,48 @@ sub session {
     my $c = shift;
 
     $c->_session || $c->_load_session || do {
-        $c->create_session_id;
-
+        $c->create_session_id_if_needed;
         $c->initialize_session_data;
     };
 }
 
-sub flash {
+sub keep_flash {
+    my ( $c, @keys ) = @_;
+    my $href = $c->_flash_keep_keys || $c->_flash_keep_keys({});
+    (@{$href}{@keys}) = ((undef) x @keys);
+}
+
+sub _flash_data {
     my $c = shift;
     $c->_flash || $c->_load_flash || do {
-        $c->create_session_id;
+        $c->create_session_id_if_needed;
         $c->_flash( {} );
-      }
+    };
+}
+
+sub _set_flash {
+    my $c = shift;
+    if (@_) {
+        my $items = @_ > 1 ? {@_} : $_[0];
+        croak('flash takes a hash or hashref') unless ref $items;
+        @{ $c->_flash }{ keys %$items } = values %$items;
+    }
+}
+
+sub flash {
+    my $c = shift;
+    $c->_flash_data;
+    $c->_set_flash(@_);
+    return $c->_flash;
+}
+
+sub clear_flash {
+    my $c = shift;
+
+    #$c->delete_session_data("flash:" . $c->sessionid); # should this be in here? or delayed till finalization?
+    $c->_flash_key_hashes({});
+    $c->_flash_keep_keys({});
+    $c->_flash({});
 }
 
 sub session_expire_key {
@@ -308,8 +489,13 @@ sub initialize_session_data {
             __updated => $now,
 
             (
-                $c->config->{session}{verify_address}
-                ? ( __address => $c->request->address )
+                $c->_session_plugin_config->{verify_address}
+                ? ( __address => $c->request->address||'' )
+                : ()
+            ),
+            (
+                $c->_session_plugin_config->{verify_user_agent}
+                ? ( __user_agent => $c->request->user_agent||'' )
                 : ()
             ),
         }
@@ -324,17 +510,23 @@ sub generate_session_id {
     return $digest->hexdigest;
 }
 
+sub create_session_id_if_needed {
+    my $c = shift;
+    $c->create_session_id unless $c->sessionid;
+}
+
 sub create_session_id {
     my $c = shift;
 
-    if ( !$c->_sessionid ) {
-        my $sid = $c->generate_session_id;
+    my $sid = $c->generate_session_id;
 
-        $c->log->debug(qq/Created session "$sid"/) if $c->debug;
+    $c->log->debug(qq/Created session "$sid"/) if $c->debug;
 
-        $c->sessionid($sid);
-        $c->session_expires(1);
-    }
+    $c->_sessionid($sid);
+    $c->reset_session_expires;
+    $c->set_session_id($sid);
+
+    return $sid;
 }
 
 my $counter;
@@ -368,7 +560,7 @@ sub dump_these {
     my $c = shift;
 
     (
-        $c->NEXT::dump_these(),
+        $c->maybe::next::method(),
 
         $c->sessionid
         ? ( [ "Session ID" => $c->sessionid ], [ Session => $c->session ], )
@@ -376,6 +568,12 @@ sub dump_these {
     );
 }
 
+
+sub get_session_id { shift->maybe::next::method(@_) }
+sub set_session_id { shift->maybe::next::method(@_) }
+sub delete_session_id { shift->maybe::next::method(@_) }
+sub extend_session_id { shift->maybe::next::method(@_) }
+
 __PACKAGE__;
 
 __END__
@@ -384,8 +582,7 @@ __END__
 
 =head1 NAME
 
-Catalyst::Plugin::Session - Generic Session plugin - ties together server side
-storage and client side state required to maintain session data.
+Catalyst::Plugin::Session - Generic Session plugin - ties together server side storage and client side state required to maintain session data.
 
 =head1 SYNOPSIS
 
@@ -397,11 +594,11 @@ storage and client side state required to maintain session data.
       Session::State::Cookie
       /;
 
-       # you can replace Store::FastMmap with Store::File - both have sensible
-       # default configurations (see their docs for details)
+    # you can replace Store::FastMmap with Store::File - both have sensible
+    # default configurations (see their docs for details)
 
-       # more complicated backends are available for other scenarios (DBI storage,
-       # etc)
+    # more complicated backends are available for other scenarios (DBI storage,
+    # etc)
 
 
     # after you've loaded the plugins you can save session data
@@ -446,7 +643,7 @@ made by the same client.
 
 This plugin links the two pieces together.
 
-=head1 RECCOMENDED BACKENDS
+=head1 RECOMENDED BACKENDS
 
 =over 4
 
@@ -500,8 +697,8 @@ lasts for longer than one request, letting you redirect instead of forward.
 
 The flash data will be cleaned up only on requests on which actually use
 $c->flash (thus allowing multiple redirections), and the policy is to delete
-all the keys which were present at the time the data was loaded just before the
-data is saved.
+all the keys which haven't changed since the flash data was loaded at the end
+of every request.
 
     sub moose : Local {
         my ( $self, $c ) = @_;
@@ -524,10 +721,26 @@ data is saved.
         my ( $self, $c ) = @_;
 
         if ( exists $c->flash->{beans} ) { # false
-        
+
         }
     }
 
+=item clear_flash
+
+Zap all the keys in the flash regardless of their current state.
+
+=item keep_flash @keys
+
+If you want to keep a flash key for the next request too, even if it hasn't
+changed, call C<keep_flash> and pass in the keys as arguments.
+
+=item delete_session REASON
+
+This method is used to invalidate a session. It takes an optional parameter
+which will be saved in C<session_delete_reason> if provided.
+
+NOTE: This method will B<also> delete your flash data.
+
 =item session_delete_reason
 
 This accessor contains a string with the reason a session was deleted. Possible
@@ -552,7 +765,7 @@ expiry time for the whole session).
 
 For example:
 
-    __PACKAGE__->config->{session}{expires} = 1000000000000; # forever
+    __PACKAGE__->config('Plugin::Session' => { expires => 1000000000000 }); # forever
 
     # later
 
@@ -563,6 +776,31 @@ an hour.
 
 Note that these values are not auto extended.
 
+=item change_session_id
+
+By calling this method you can force a session id change while keeping all
+session data. This method might come handy when you are paranoid about some
+advanced variations of session fixation attack.
+
+If you want to prevent this session fixation scenario:
+
+    0) let us have WebApp with anonymous and authenticated parts
+    1) a hacker goes to vulnerable WebApp and gets a real sessionid,
+       just by browsing anonymous part of WebApp
+    2) the hacker inserts (somehow) this values into a cookie in victim's browser
+    3) after the victim logs into WebApp the hacker can enter his/her session
+
+you should call change_session_id in your login controller like this:
+
+      if ($c->authenticate( { username => $user, password => $pass } )) {
+        # login OK
+        $c->change_session_id;
+        ...
+      } else {
+        # login FAILED
+        ...
+      }
+
 =back
 
 =head1 INTERNAL METHODS
@@ -581,26 +819,26 @@ application.
 
 =item setup_session
 
-This method populates C<< $c->config->{session} >> with the default values
+This method populates C<< $c->config('Plugin::Session') >> with the default values
 listed in L</CONFIGURATION>.
 
 =item prepare_action
 
-This methoid is extended.
+This method is extended.
 
-It's only effect is if the (off by default) C<flash_to_stash> configuration
+Its only effect is if the (off by default) C<flash_to_stash> configuration
 parameter is on - then it will copy the contents of the flash to the stash at
 prepare time.
 
-=item finalize
+=item finalize_headers
 
-This method is extended and will extend the expiry time, as well as persist the
-session data if a session exists.
+This method is extended and will extend the expiry time before sending
+the response.
 
-=item delete_session REASON
+=item finalize_body
 
-This method is used to invalidate a session. It takes an optional parameter
-which will be saved in C<session_delete_reason> if provided.
+This method is extended and will call finalize_session before the other
+finalize_body methods run.  Here we persist the session data if a session exists.
 
 =item initialize_session_data
 
@@ -609,7 +847,7 @@ called by the C<session> method if appropriate.
 
 =item create_session_id
 
-Creates a new session id using C<generate_session_id> if there is no session ID
+Creates a new session ID using C<generate_session_id> if there is no session ID
 yet.
 
 =item validate_session_id SID
@@ -624,7 +862,7 @@ insensitive hexadecimal characters.
 This method will return a string that can be used as a session ID. It is
 supposed to be a reasonably random string with enough bits to prevent
 collision. It basically takes C<session_hash_seed> and hashes it using SHA-1,
-MD5 or SHA-256, depending on the availibility of these modules.
+MD5 or SHA-256, depending on the availability of these modules.
 
 =item session_hash_seed
 
@@ -635,29 +873,19 @@ Currently it returns a concatenated string which contains:
 
 =over 4
 
-=item *
-
-A counter
+=item * A counter
 
-=item *
+=item * The current time
 
-The current time
+=item * One value from C<rand>.
 
-=item *
+=item * The stringified value of a newly allocated hash reference
 
-One value from C<rand>.
-
-=item *
-
-The stringified value of a newly allocated hash reference
-
-=item *
-
-The stringified value of the Catalyst context object
+=item * The stringified value of the Catalyst context object
 
 =back
 
-In the hopes that those combined values are entropic enough for most uses. If
+in the hopes that those combined values are entropic enough for most uses. If
 this is not the case you can replace C<session_hash_seed> with e.g.
 
     sub session_hash_seed {
@@ -679,11 +907,38 @@ Or even more directly, replace C<generate_session_id>:
 Also have a look at L<Crypt::Random> and the various openssl bindings - these
 modules provide APIs for cryptographically secure random data.
 
+=item finalize_session
+
+Clean up the session during C<finalize>.
+
+This clears the various accessors after saving to the store.
+
 =item dump_these
 
 See L<Catalyst/dump_these> - ammends the session data structure to the list of
 dumped objects if session ID is defined.
 
+
+=item calculate_extended_session_expires
+
+=item calculate_initial_session_expires
+
+=item create_session_id_if_needed
+
+=item delete_session_id
+
+=item extend_session_expires
+
+=item extend_session_id
+
+=item get_session_id
+
+=item reset_session_expires
+
+=item session_is_valid
+
+=item set_session_id
+
 =back
 
 =head1 USING SESSIONS DURING PREPARE
@@ -695,25 +950,25 @@ State plugins must set $c->session ID before C<prepare_action>, and during
 C<prepare_action> L<Catalyst::Plugin::Session> will actually load the data from
 the store.
 
-       sub prepare_action {
-               my $c = shift;
+    sub prepare_action {
+        my $c = shift;
 
-               # don't touch $c->session yet!
+        # don't touch $c->session yet!
 
-               $c->NEXT::prepare_action( @_ );
+        $c->NEXT::prepare_action( @_ );
 
-               $c->session;  # this is OK
-               $c->sessionid; # this is also OK
-       }
+        $c->session;  # this is OK
+        $c->sessionid; # this is also OK
+    }
 
 =head1 CONFIGURATION
 
-    $c->config->{session} = {
+    $c->config('Plugin::Session' => {
         expires => 1234,
-    };
+    });
 
 All configuation parameters are provided in a hash reference under the
-C<session> key in the configuration hash.
+C<Plugin::Session> key in the configuration hash.
 
 =over 4
 
@@ -727,6 +982,16 @@ hours).
 When true, C<<$c->request->address>> will be checked at prepare time. If it is
 not the same as the address that initiated the session, the session is deleted.
 
+Defaults to false.
+
+=item verify_user_agent
+
+When true, C<<$c->request->user_agent>> will be checked at prepare time. If it
+is not the same as the user agent that initiated the session, the session is
+deleted.
+
+Defaults to false.
+
 =item flash_to_stash
 
 This option makes it easier to have actions behave the same whether they were
@@ -759,6 +1024,11 @@ The time when the session was first created.
 The value of C<< $c->request->address >> at the time the session was created.
 This value is only populated if C<verify_address> is true in the configuration.
 
+=item __user_agent
+
+The value of C<< $c->request->user_agent >> at the time the session was created.
+This value is only populated if C<verify_user_agent> is true in the configuration.
+
 =back
 
 =head1 CAVEATS
@@ -773,13 +1043,13 @@ users' sessions cannot persist.
 To let these users access your site you can either disable address verification
 as a whole, or provide a checkbox in the login dialog that tells the server
 that it's OK for the address of the client to change. When the server sees that
-this box is checked it should delete the C<__address> sepcial key from the
+this box is checked it should delete the C<__address> special key from the
 session hash when the hash is first created.
 
 =head2 Race Conditions
 
-In this day and age where cleaning detergents and dutch football (not the
-american kind) teams roam the plains in great numbers, requests may happen
+In this day and age where cleaning detergents and Dutch football (not the
+American kind) teams roam the plains in great numbers, requests may happen
 simultaneously. This means that there is some risk of session data being
 overwritten, like this:
 
@@ -787,7 +1057,7 @@ overwritten, like this:
 
 =item 1.
 
-request a starts, request b starts, with the same session id
+request a starts, request b starts, with the same session ID
 
 =item 2.
 
@@ -812,7 +1082,7 @@ changes by request a
 
 =back
 
-If this is a concern in your application, a soon to be developed locking
+If this is a concern in your application, a soon-to-be-developed locking
 solution is the only safe way to go. This will have a bigger overhead.
 
 For applications where any given user is only making one request at a time this
@@ -820,25 +1090,31 @@ plugin should be safe enough.
 
 =head1 AUTHORS
 
-=over 4
+Andy Grundman
 
-=item Andy Grundman
+Christian Hansen
 
-=item Christian Hansen
+Yuval Kogman, C<nothingmuch@woobling.org>
 
-=item Yuval Kogman, C<nothingmuch@woobling.org> (current maintainer)
+Sebastian Riedel
 
-=item Sebastian Riedel
+Tomas Doran (t0m) C<bobtfish@bobtfish.net> (current maintainer)
 
-=back
+Sergio Salvi
+
+kmx C<kmx@volny.cz>
+
+Florian Ragwitz (rafl) C<rafl@debian.org>
+
+Kent Fredric (kentnl)
 
 And countless other contributers from #catalyst. Thanks guys!
 
 =head1 COPYRIGHT & LICENSE
 
-       Copyright (c) 2005 the aforementioned authors. All rights
-       reserved. This program is free software; you can redistribute
-       it and/or modify it under the same terms as Perl itself.
+    Copyright (c) 2005 the aforementioned authors. All rights
+    reserved. This program is free software; you can redistribute
+    it and/or modify it under the same terms as Perl itself.
 
 =cut