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.

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'.

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.

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

  • cookie_name

    This is either a hash (or arrayref of hashes) 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. They key in the hash is "cookie_name".

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