view release on metacpan or  search on metacpan

SecureState.pm  view on Meta::CPAN

takes two arguments: a maximum idle time (in days) beyond which state files are deleted,
and a directory to clean.  The default behavior is to clean the current state directory
of any state files that have been idle for more than an hour.  You may also name the
arguments using the '-age' and '-directory' attributes if you want to specify things
out-of-order (like C<$cgi->clean_statedir(-directory => "foo", -age => 1/2);>).

=back


=head1 GLOBALS

You may set these options to globally affect the behavior of CGI::SecureState.

=over 4

=item B<NASTY_WARNINGS>

Set this to 0 if you want warnings about deprecated behavior to be suppressed.
This is especially true if you want to be left in peace while updating scripts based 
on older versions of CGI::SecureState.  However, the warnings issued should be heeded
because they generally result in better coding style and program security.

You may either do
    use CGI::SecureState qw(:no_nasty_warnings); #or
    $CGI::SecureState::NASTY_WARNINGS = 0;


=item B<AVOID_SYMLINKS>

Set this to 0 if you don't want CGI::SecureState to test for the presence of a symlink
before writing to a state file.  If this is set to 1 and CGI::SecureState sees a 
symlink in place of a real file, it will spit out a fatal error.  It is generally
a good idea to keep this in place, but if you have a good reason to, then do
    use CGI::SecureState qw(:dont_avoid_symlinks); #or
    $CGI::SecureState::AVOID_SYMLINKS = 1;


=item B<USE_FLOCK>

Set this to 0 if you do not want CGI::SecureState to use "flock" to assure that
only one instance of CGI::SecureState is accessing the state file at a time.
Leave this at 1 unless you really have a good reason not to.

For users running a version of Windows NT (including 2000 and XP), you should set
this variable to 1 because $^O will always report "MSWin32", regardless of whether
your system is Win9x (which does not support flock) or WinNT (which does).

To set to 0, do
    use CGI::SecureState qw(:no_flock); #or
    $CGI::SecureState::USE_FLOCK = 0;

To set to 1, do
    use CGI::SecureState qw(:use_flock); #or
    $CGI::SecureState::USE_FLOCK = 1;


=item B<Extra and Paranoid Security>

If the standard security is not enough, CGI::SecureState provides extra security
by setting the appropriate options in CGI.pm.  The ":extra_security" option
enables private file uploads and sets the maximum size for a CGI POST to be
10 kilobytes.  The ":paranoid_security" option disables file uploads entirely.
To use them, do
    use CGI::SecureState qw(:extra_security);  #or
    use CGI::SecureState qw(:paranoid_security);

To disable them, do
    use CGI::SecureState qw(:no_security);
=back


=head1 EXAMPLES

There is now an official example of how to use CGI::SecureState in a large
project.  If that is what you are looking for, check out the Anthill
Bug Manager at Sourceforge (L<http://anthillbm.sourceforge.net/>).


This example is a simple log-in script.  It should have a directory called "states"
that it can write to.

  #!/usr/bin/perl -wT
  use CGI::SecureState qw(:paranoid_security);

  my $cgi = new CGI::SecureState(-stateDir => 'states',
                                 -mindSet => 'forgetful');

  my ($user,$pass,$lo)=$cgi->params(qw(user pass logout));
  my $failtime = $cgi->param('failtime') || 0;

  print $cgi->header();
  $cgi->start_html(-title => "CGI::SecureState Example");

  if ($user ne 'Cottleston' || $pass ne 'Pie') {
    if (defined $user) {
      $failtime+=$cgi->age()*86400;
      print "Incorrect Username/Password. It took you only ",
	     $cgi->age*86400, " seconds to fail this time.";
      print " It has been $failtime seconds since you started.";
      $cgi->add(failtime => $failtime);
    }
    print $cgi->start_form(-action => $cgi->url());
    print $cgi->state_field();
    print "\n<b>Username: </b>", $cgi->textfield("user");
    print "\n<br><b>Password: </b>", $cgi->password_field("pass");
    print "<br>",$cgi->submit("Login"),$cgi->reset;
    print $cgi->end_form;
  } elsif (! defined $lo) {
    print "You logged in!\n<br>";
    print "Click <a href=\"",$cgi->url,"?",$cgi->state_param;
    print ";logout=true\">here</a> to logout.";
    $cgi->remember('user','pass');
  } else {
    print "You have logged out.";
    $cgi->delete_session;
  }
  print $cgi->end_html;

This example will show a form that will tell you what what previously
entered.  It should have a directory called "states" that it can write to.