NAME

HTTP::CryptoCookie - Perl extension for encrypted HTTP cookies

SYNOPSIS

use HTTP::CryptoCookie;
my $cc = new HTTP::CryptoCookie ($key);
# fair warning, if a $key is not passed, the call to
# "new" will die.  It is B<highly advised> that you wrap
# this in an eval to handle $@ under mod_perl!!

# $key is a scalar, secret key

my %cookie = (
  cookie_name => 'PREFS',
  cookie => {
    color => 'blue',
    number => 8,
    day_of_week => 'friday',
    people => [qw(joe sam megan)],
  },
  secure => 1,  # only available through SSL, defaults to 0
  exp => '+1M', # expires in one month
  domain => 'foo.com',  # readable by all hosts in the foo.com domain
);

my $rv = $cc->set_cookie(%cookie);
if(!$rv) {
  warn "oh no!  we couldn't set the cookie!";
}

DESCRIPTION

HTTP::CryptoCookie provides a convenient, fast interface to store complex data structures as cookies in a manner that cannot be humanly-read or tampered with. If the cookie is altered by even one bit, the attempt to read it will return garbage. Such is the price of security.

METHODS

new

This is the standard object constructor and requires a key be passed as an argument. If a key is not passed, there is a die statement. When running under mod_perl, this tends to be a Bad Thing[tm], so you are highly advised to wrap the call in an eval block to trap $@ and handle it sanely. You've been duly warned.

set_cookie

This method takes either a hash as an argument and the hash may contain a single hashref or an array of hashrefs with cookie details. This allows us to set one or more cookies in one call. The attributes available when setting a cookie (a hashref) are as follows:

• cookie_name

  The name of this cookie so we can recall the data later. This is a scalar.

• cookie

  This is the data structure we want to store. The exact structure is limited to one of the following: scalar, arrayref, hashref, and possibly coderefs. Blessed references and objects cannot be stored.

• secure

  If set to 1, the cookie is only available when the user is operating under SSL. Default is 0. This is 0 or any true value.

• exp

  The expiration date of the cookie. By default, the cookie exists until the user closes their browser. For more information about expiration formats, see perldoc CGI::Cookie. This is set as a scalar.

• path

  Cookies can be set such that they are only valid within certain request paths within the file system (be they actual or virtual). This is set as a scalar.

• domain

  Unless this is set, the cookie will only be able to be read by machines with the same host name (as far as the ServerName in the httpd is set) as the machine that set the cookie. e.g. a cookie set by 'www.foo.com' cannot be read by 'secure.foo.com' unless you've set domain equal to 'foo.com'.

get_cookie

This method takes a hash as an argument. The only available attribute is:

• cookie_name

  This is a scalar holding the name of the cookie you wish to retrieve.

del_cookie

This method deletes cookies (I know, such a obfuscated function name!). The only available attribute is:

• cookie_name

  This is either a scalar or an arrayref containing the name or names of cookies that should be deleted from the user's browser. A common application of this is a "log out" function.

EXPORT

None. This is an OO-only module.

AUTHOR

Dave Paris (a-mused), <amused@pobox.com>

COPYRIGHT AND LICENSE

Copyright 1998-2005, Dave Paris. All Rights Reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Crypt::Rijndael, Crypt::CBC, Storable, FreezeThaw, Compress::Zlib CGI::Cookie, Digest::SHA256, Convert::ASCII::Armour