NAME

Mail::SpamCannibal::Session - session management utilities

SYNOPSIS

  use Mail::SpamCannibal::Session qw(
        encode
        decode
        mac
        new_ses
        clean
        validate
        sesswrap
  );

  $encoded = encode($string);
  $string = decode($encoded);
  $mac = mac(@elements);
  $sess_id=new_ses($base64ID,$session_dir,\$error,$ses_val);
  $var = clean($tainted);
  $user=validate($session_dir,$sess_id,$secret,\$error,$expire);
  ($user,$content,$file)=validate($session_dir,$sess_id,$secret,\$error,$expire);
  $rv = sesswrap($command,$stdin);

DESCRIPTION

Mail::SpamCannibal::Session provides utilities to manage web sessions.

$encoded = encode($string);
This function encodes an ascii string into the URL and Filename safe Base64 character set. Character 62 (0x3E) ``+'' is replaced with a ``-'' (minus sign) and character 63 (0x3F) ``/'' is replaced with a ``_'' (underscore). Pad characters ``='' are removed.
```
  input:        ascii string
  returns:      modified Base64 encoded string
```
$string = decode($encoded);
This function decodes a <URL and Filename safe> Base64 encoded string.
```
  input:        encoded string
  returns:      text string
```
$mac = mac(@elements);
This function makes a URL and Filename safe BASE64 MD5 hash of from the supplies text string(s). Character 62 (0x3E) ``+'' is replaced with a ``-'' (minus sign) and character 63 (0x3F) ``/'' is replaced with a ``_'' (underscore).
```
  input:        one or more input elements
  returns:      modified base64 string
```
$sess_id = new_ses($base64ID,$session_dir,\$error,$ses_val);
Create a new session and return the identifying string.
```
  input:        session directory path,
                base64 unique ID, (URL safe)
                secret key for MAC,
                pointer to $error scalar,
                [optional] value for session
                file contents, default -1
```
Normally the session file is created containing a -1 with the presumption that the login procedure and password verification was successful. If the application needs to track conditional login attempts, then the session value can be initialized to a positive value and the 'validate' function (below) will return a false (undef) for 'user' when called with a SCALAR return value. The application must set the session value negative for the 'user' string to be returned.
```
  returns:      session ID or undef
```
$user=validate($session_dir,$sess_id,$secret,\$error,$expire);
($user,$content,$file)=validate($session_dir,$sess_id,$secret,\$error,$expire);
Validate a current session. The session directory is swept for sessions that have exceeded the expire time (seconds), then checked for the presence of a matching session. On error, a descriptive message is placed in the external scalar $error and undef is returned.
```
  input:        session directory path,
                session ID,
                secret key for MAC,
                pointer to error,
                expire (seconds) [optional]
                        default = 15 minutes
```
```
  returns:      scalar: user name or undef
                array: (user,contents,sess file)
                        or ()
```
NOTE: in SCALAR mode, the return value will always be false if the session contents are > 0.
$rv = sesswrap($command,$stdin);
Execute a session wrap command and return results.
```
  input:        command string,
                stdin string [optional]
  returns:      wrapper output
```
The wrapper is opened with the command string in it's command line. $stdin, if any, is written to the wrapper's STDIN.

For calls which have a $stdin argument, this routine uses 'fork' and spawns a child httpd process. The routine is enhanced for modperl to properly kill off the child

DEPENDENCIES

        none


=head1 EXPORT_OK

        encode
        decode
        mac
        new_ses
        validate
        sesswrap

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

AUTHOR

Michael Robinton <michael@bizsystems.com>