CGI::Session::TutorialUser Contributed Perl DocumentaCGI::Session::Tutorial(3)NAMECGI::Session::Tutorial - Extended CGI::Session manual
STATE MAINTENANCE OVERVIEW
Since HTTP is a stateless protocol, each subsequent click to a web site
is treated as new request by the Web server. The server does not relate
a visit with a previous one, thus all the state information from the
previous requests are lost. This makes creating such applications as
shopping carts, web sites requiring users to authenticate, impossible.
So people had to do something about this despair situation HTTP was
putting us in.
For our rescue come such technologies as HTTP Cookies and QUERY_STRINGs
that help us save the users' session for a certain period. Since HTTP
Cookies and QUERY_STRINGs alone cannot take us too far (RFC 2965,
Section 5, "Implementation Limitations"), several other libraries have
been developed to extend their capabilities and promise a more reliable
solution. CGI::Session is one of them.
Before we discuss this library, let's look at some alternative
solutions.
COOKIE
Cookie is a piece of text-information that a web server is entitled to
place in the user's hard disk, assuming a user agent (such as Internet
Explorer, Mozilla, etc) is compatible with the specification. After the
cookie is placed, user agents are required to send these cookies back
to the server as part of the HTTP request. This way the server
application ( CGI, for example ) will have a way of relating previous
requests by the same user agent, thus overcoming statelessness of HTTP.
Although HTTP Cookies seem to be promising solution for the
statelessness of HTTP, they do carry certain limitations, such as
limited number of cookies per domain and per user agent and limited
size on each cookie. User Agents are required to store at least 300
cookies at a time, 20 cookies per domain and allow 4096 bytes of
storage for each cookie. They also rise several Privacy and Security
concerns, the lists of which can be found on the sections 6-"Privacy"
and 7-"Security Considerations" of RFC 2965.
QUERY STRING
Query string is a string appended to URL following a question mark (?)
such as:
http://my.dot.com/login.cgi?user=sherzodr;password=top-secret
As you probably guessed, it can also help you pass state information
from a click to another, but how secure is it do you think, considering
these URLs tend to get cached by most of the user agents and also
logged in the servers access log, to which everyone can have access.
HIDDEN FIELDS
Hidden field is another alternative to using query strings and they
come in two flavors: hidden fields used in POST methods and the ones in
GET. The ones used in GET methods will turn into a true query strings
once submitted, so all the disadvantages of QUERY_STRINGs apply.
Although POST requests do not have limitations of its sister-GET, the
pages that hold them get cached by Web browser, and are available
within the source code of the page (obviously). They also become
unwieldily to manage when one has oodles of state information to keep
track of ( for instance, a shopping cart or an advanced search engine).
Query strings and hidden fields are also lost easily by closing the
browser, or by clicking the browser's "Back" button.
SERVER SIDE SESSION MANAGEMENT
This technique is built upon the aforementioned technologies plus a
server-side storage device, which saves the state data on the server
side. Each session has a unique id associated with the data in the
server. This id is also associated with the user agent either in the
form of a HTTP Cookie, a QUERY_STRING, hidden field or any combination
of the above. This is necessary to make the connection with the client
and his data.
Advantages:
· We no longer need to depend on User Agent constraints in cookie
size.
· Sensitive data no longer need to be traveling across the network at
each request (which is the case with query strings, cookies and
hidden fields). The only thing that travels is the unique id
generated for the session (5767393932698093d0b75ef614376314, for
instance), which should make no sense to third parties.
· User will not have sensitive data stored in his/her computer in
unsecured file (which is a cookie file).
· It's possible to handle very big and even complex data structures
transparently (which HTTP Cookies do not handle).
That's what CGI::Session is all about - implementing server side
session management. Now is a good time to get feet wet.
PROGRAMMING STYLE
Server side session management system might be seeming awfully
convoluted if you have never dealt with it. Fortunately, with
CGI::Session all the complexity is handled by the library
transparently. This section of the manual can be treated as an
introductory tutorial to both logic behind session management, and to
CGI::Session programming style.
All applications making use of server side session management rely on
the following pattern of operation regardless of the way the system is
implemented:
1. Check if the user has session cookie dropped in his computer from
previous request
2. If the cookie does not exist, create a new session identifier, and
drop it as cookie to the user's computer.
3. If session cookie exists, read the session ID from the cookie and
load any previously saved session data from the server side
storage. If session had any expiration date set it's useful to re-
drop the same cookie to the user's computer so its expiration time
will be reset to be relative to user's last activity time.
4. Store any necessary data in the session that you want to make
available for the next HTTP request.
CGI::Session will handle all of the above steps. All you have to do is
to choose what to store in the session.
GETTING STARTED
To make CGI::Session's functionality available in your program do
either of the following somewhere on top of your program file:
use CGI::Session;
# or
require CGI::Session;
Whenever you're ready to create a new session in your application, do
the following:
$session = new CGI::Session() or die CGI::Session->errstr;
Above line will first try to re-initialize an existing session by
consulting cookies and necessary QUERY_STRING parameters. If it fails
will create a brand new session with a unique ID, which is normally
called session ID, SID for short, and can be accessed through id()-
object method.
We didn't check for any session cookies above, did we? No, we didn't,
but CGI::Session did. It looked for a cookie called "CGISESSID", and if
it found it tried to load existing session from server side storage
(file in our case). If cookie didn't exist it looked for a QUERY_STRING
parameter called "CGISESSID". If all the attempts to recover session ID
failed, it created a new session.
NOTE: For the above syntax to work as intended your application needs
to have write access to your computer's TEMPDIR folder, which is
usually /tmp in UNIX. If it doesn't, or if you wish to store this
application's session files in a different place, you may pass the
third argument like so:
$session = new CGI::Session(undef, undef, {Directory=>'../tmp/sessions'});
Now it will store all the newly created sessions in (and will attempt
to initialize requested sessions from) that folder. Don't worry if the
directory hierarchy you want to use doesn't already exist. It will be
created for you. For details on how session data are stored refer to
CGI::Session::Driver::file, which is the default driver used in our
above example.
There is one small, but very important thing your application needs to
perform after creating CGI::Session object as above. It needs to drop
Session ID as an HTTP cookie into the user's computer. CGI::Session
will use this cookie to identify the user at his/her next request and
will be able to load his/her previously stored session data.
To make sure CGI::Session will be able to read your cookie at next
request you need to consult its "name()" method for cookie's suggested
name:
$cookie = $query->cookie( -name => $session->name,
-value => $session->id );
print $query->header( -cookie=>$cookie );
"name()" returns "CGISESSID" by default. If you prefer a different
cookie name, you can change it as easily too, but you have to do it
before CGI::Session object is created:
CGI::Session->name("SID");
$session = new CGI::Session();
Baking the cookie wasn't too difficult, was it? But there is an even
easier way to send a cookie using CGI::Session:
print $session->header();
The above will create the cookie using CGI::Cookie and will return
proper http headers using CGI.pm's CGI method. Any arguments to
CGI::Session will be passed to CGI::header().
Of course, this method of initialization will only work if client is
accepting cookies. If not you would have to pass session ID in each URL
of your application as QUERY_STRING. For CGI::Session to detect it the
name of the parameter should be the same as returned by name():
printf ("<a href=\"$ENV{SCRIPT_NAME}?%s=%s\">click me</a>", $session->name, $session->id);
If you already have session id to be initialized you may pass it as the
only argument, or the second argument of multi-argument syntax:
$session = new CGI::Session( $sid );
$session = new CGI::Session( "serializer:freezethaw", $sid );
$session = new CGI::Session( "driver:mysql", $sid, {Handle=>$dbh} );
By default CGI::Session uses standard CGI to parse queries and cookies.
If you prefer to use a different, but compatible object you can pass
that object in place of $sid:
$cgi = new CGI::Simple();
$session = new CGI::Session ( $cgi );
$session = new CGI::Session( "driver:db_file;serializer:storable", $cgi);
# etc
See CGI::Simple
STORING DATA
CGI::Session offers param() method, which behaves exactly as CGI.pm's
param() with identical syntax. param() is used for storing data in
session as well as for accessing already stored data.
Imagine your customer submitted a login form on your Web site. You, as
a good host, wanted to remember the guest's name, so you can a) greet
him accordingly when he visits your site again, or b) to be helpful by
filling out user name part of his login form, so the customer can jump
right to the password field without having to type his username again.
my $name = $cgi->param('username');
$session->param('username', $name);
Notice, we're grabbing username value of the field using CGI.pm's (or
another compatible library's) "param()" method, and storing it in
session using CGI::Session's param() method.
If you have too many stuff to transfer into session, you may find
yourself typing the above code over and over again. I've done it, and
believe me, it gets very boring too soon, and is also error-prone. So
we introduced the following handy method:
$session->save_param(['name']);
If you wanted to store multiple form fields just include them all in
the second list:
$session->save_param(['name', 'email']);
If you want to store all the available QUERY_STRING parameters you can
omit the arguments:
$session->save_param();
See save_param() for more details.
When storing data in the session you're not limited to strings. You can
store arrays, hashes and even most objects. You will need to pass them
as references (except objects).
For example, to get all the selected values of a scrolling list and
store it in the session:
my @fruits = $cgi->param('fruits');
$session->param('fruits', \@fruits);
For parameters with multiple values save_param() will do the right
thing too. So the above is the same as:
$session->save_param($cgi, ['fruits']);
All the updates to the session data using above methods will not
reflect in the data store until your application exits, or $session
goes out of scope. If, for some reason, you need to commit the changes
to the data store before your application exits you need to call
flush() method:
$session->flush();
I've written a lot of code, and never felt need for using "flush()"
method, since CGI::Session calls this method at the end of each
request. There are, however, occasions I can think of one may need to
call flush().
ACCESSING STORED DATA
There's no point of storing data if you cannot access it. You can
access stored session data by using the same param() method you once
used to store them. Remember the Username field from the previous
section that we stored in the session? Let's read it back so we can
partially fill the Login form for the user:
$name = $session->param("name");
printf "<input type=\"text\" name=\"name\" value=\"%s\" />", $name;
To retrieve previously stored @fruits do not forget to de reference it:
@fruits = @{ $session->param('fruits') };
Very frequently, you may find yourself having to create pre-filled and
pre-selected forms, like radio buttons, checkboxes and drop down menus
according to the user's preferences or previous action. With text and
textareas it's not a big deal - you can simply retrieve a single
parameter from the session and hard code the value into the text field.
But how would you do it when you have a group of radio buttons,
checkboxes and scrolling lists? For this purpose, CGI::Session provides
load_param() method, which loads given session parameters to a CGI
object (assuming they have been previously saved with save_param() or
alternative):
$session->load_param($cgi, ["fruits"]);
Now when you say:
print $cgi->checkbox_group(fruits=>['apple', 'banana', 'apricot']);
See load_param() for details.
Generated checkboxes will be pre-filled using previously saved
information. To see example of a real session-powered application
consider http://handalak.com/cgi-bin/subscriptions.cgi
If you're making use of HTML::Template to separate the code from the
skin, you can as well associate CGI::Session object with HTML::Template
and access all the parameters from within HTML files. We love this
trick!
$template = new HTML::Template(filename=>"some.tmpl", associate=>$session);
print $template->output();
Assuming the session object stored "first_name" and "email" parameters
while being associated with HTML::Template, you can access those values
from within your "some.tmpl" file now:
Hello <a href="mailto:<TMPL_VAR email>"> <TMPL_VAR first_name> </a>!
See HTML::Template's online manual for details.
CLEARING SESSION DATA
You store session data, you access session data and at some point you
will want to clear certain session data, if not all. For this purpose
CGI::Session provides clear() method which optionally takes one
argument as an arrayref indicating which session parameters should be
deleted from the session object:
$session->clear(["~logged-in", "email"]);
Above line deletes "~logged-in" and "email" session parameters from the
session. And next time you say:
$email = $session->param("email");
it returns undef. If you omit the argument to clear(), be warned that
all the session parameters you ever stored in the session object will
get deleted. Note that it does not delete the session itself. Session
stays open and accessible. It's just the parameters you stored in it
gets deleted
See clear() for details.
DELETING A SESSION
If there's a start there's an end. If session could be created, it
should be possible to delete it from the disk for good:
$session->delete();
The above call to delete() deletes the session from the disk for good.
Do not confuse it with clear(), which only clears certain session
parameters but keeps the session open.
See delete() for details.
EXPIRATION
CGI::Session provides limited means to expire sessions. Expiring a
session is the same as deleting it via delete(), but deletion takes
place automatically. To expire a session, you need to tell the library
how long the session would be valid after the last access time. When
that time is met, CGI::Session refuses to retrieve the session. It
deletes the session and returns a brand new one. To assign expiration
ticker for a session, use expire():
$session->expire(3600); # expire after 3600 seconds
$session->expire('+1h'); # expire after 1 hour
$session->expire('+15m'); # expire after 15 minutes
$session->expire('+1M'); # expire after a month and so on.
When session is set to expire at some time in the future, but session
was not requested at or after that time has passed it will remain in
the disk. When expired session is requested CGI::Session will remove
the data from disk, and will initialize a brand new session.
See expire() for details.
Before CGI::Session 4.x there was no way of intercepting requests to
expired sessions. CGI::Session 4.x introduced new kind of constructor,
load(), which is identical in use to new(), but is not allowed to
create sessions. It can only load them. If session is found to be
expired, or session does not exist it will return an empty CGI::Session
object. And if session is expired, in addition to being empty, its
status will also be set to expired. You can check against these
conditions using empty() and is_expired() methods. If session was
loaded successfully object returned by "load()" is as good a session as
the one returned by "new()":
$session = CGI::Session->load() or die CGI::Session->errstr;
if ( $session->is_expired ) {
die "Your session expired. Please refresh your browser to re-start your session";
}
if ( $session->is_empty ) {
$session = $session->new();
}
Above example is worth an attention. Remember, all expired sessions are
empty sessions, but not all empty sessions are expired sessions.
Following this rule we have to check with "is_expired()" before
checking with "is_empty()". There is another thing about the above
example. Notice how its creating new session when un existing session
was requested? By calling "new()" as an object method! Handy thing
about that is, when you call "new()" on a session object new object
will be created using the same configuration as the previous object.
For example:
$session = CGI::Session->load("driver:mysql;serializer:storable", undef, {Handle=>$dbh});
if ( $session->is_expired ) {
die "Your session is expired. Please refresh your browser to re-start your session";
}
if ( $session->is_empty ) {
$session = $session->new();
}
Initial $session object was configured with mysql as the driver,
storable as the serializer and $dbh as the database handle. Calling "
new() " on this object will return an object of the same configuration.
So $session object returned from " new() " in the above example will
use mysql as the driver, storable as the serializer and $dbh as the
database handle.
See is_expired(), is_empty(), load() for details.
Sometimes it makes perfect sense to expire a certain session parameter,
instead of the whole session. I usually do this in my login enabled
sites, where after the user logs in successfully, I set his/her
"_logged_in" session parameter to true, and assign an expiration ticker
on that flag to something like 30 minutes. It means, after 30 idle
minutes CGI::Session will clear "_logged_in" flag, indicating the user
should log in over again. I agree, the same effect can be achieved by
simply expiring() the session itself, but by doing this we would loose
other session parameters, such as user's shopping cart, session-
preferences and the like.
This feature can also be used to simulate layered authentication, such
as, you can keep the user's access to his/her personal profile
information for as long as 60 minutes after a successful login, but
expire his/her access to his credit card information after 5 idle
minutes. To achieve this effect, we will use expire() method again:
$session->expire(_profile_access, '1h');
$session->expire(_cc_access, '5m');
With the above syntax, the person will still have access to his
personal information even after 5 idle hours. But when he tries to
access or update his/her credit card information, he may be displayed a
"login again, please" screen.
See expire() for details.
This concludes our discussion of CGI::Session programming style. The
rest of the manual covers some "SECURITY" issues. Driver specs from the
previous manual were moved to CGI::Session::Driver.
SECURITY
"How secure is using CGI::Session?", "Can others hack down people's
sessions using another browser if they can get the session id of the
user?", "Are the session ids easy to guess?" are the questions I find
myself answering over and over again.
STORAGE
Security of the library does in many aspects depend on the
implementation. After making use of this library, you no longer have to
send all the information to the user's cookie except for the session
id. But, you still have to store the data in the server side. So
another set of questions arise, can an evil person get access to
session data in your server, even if he does, can he make sense out of
the data in the session file, and even if he can, can he reuse the
information against a person who created that session. As you see, the
answer depends on yourself who is implementing it.
· First rule of thumb, do not store users' passwords or other
sensitive data in the session, please. If you have to, use one-way
encryption, such as md5, or SHA-1-1. For my own experience I can
assure you that in properly implemented session-powered Web
applications there is never a need for it.
· Default configuration of the driver makes use of Data::Dumper class
to serialize data to make it possible to save it in the disk.
Data::Dumper's result is a human readable data structure, which, if
opened, can be interpreted easily. If you configure your session
object to use either Storable or FreezeThaw as a serializer, this
would make it more difficult for bad guys to make sense out of
session data. But don't use this as the only precaution. Since evil
fingers can type a quick program using Storable or FreezeThaw to
decipher session files very easily.
· Do not allow anyone to update contents of session files. If you're
using default serializer serialized data string needs to be
eval()ed to bring the original data structure back to life. Of
course, we use Safe to do it safely, but your cautiousness does no
harm either.
· Do not keep sessions open for very long. This will increase the
possibility that some bad guy may have someone's valid session id
at a given time (acquired somehow). To do this use expire() method
to set expiration ticker. The more sensitive the information on
your Web site is, the sooner the session should be set to expire.
SESSION IDs
Session ids are not easily guessed (unless you're using incr ID
generator)! Default configuration of CGI::Session uses Digest::MD5 to
generate random, 32 character long identifier. Although this string
cannot be guessed as easily by others, if they find it out somehow, can
they use this identifier against the other person?
Consider the scenario, where you just give someone either via email or
an instant messaging a link to a Web site where you're currently logged
in. The URL you give to that person contains a session id as part of a
query string. If the site was initializing the session solely using
query string parameter, after clicking on that link that person now
appears to that site as you, and might have access to all of your
private data instantly.
Even if you're solely using cookies as the session id transporters,
it's not that difficult to plant a cookie in the cookie file with the
same id and trick the web browser to send that particular session id to
the server. So key for security is to check if the person who's asking
us to retrieve a session data is indeed the person who initially
created the session data.
One way to help with this is by also checking that the IP address that
the session is being used from is always same. However, this turns out
not to be practical in common cases because some large ISPs (such as
AOL) use proxies which cause each and every request from the same user
to come from different IP address.
If you have an application where you are sure your users' IPs are
constant during a session, you can consider enabling an option to make
this check:
use CGI::Session ( '-ip_match' );
For backwards compatibility, you can also achieve this by setting
$CGI::Session::IP_MATCH to a true value. This makes sure that before
initializing a previously stored session, it checks if the ip address
stored in the session matches the ip address of the user asking for
that session. In which case the library returns the session, otherwise
it dies with a proper error message.
LICENSING
For support and licensing see CGI::Session
perl v5.10.1 2008-07-15 CGI::Session::Tutorial(3)