NAME

Catalyst::Plugin::SecureCookies - Tamper-resistant, encrypted HTTP Cookies

SYNOPSIS

 use Catalyst qw/SecureCookies/;
 MyApp->config->{SecureCookies} = {
     key       => $blowfish_key,
     ssl       => 1       # send the checksum over ssl
 };
 MyApp->setup;

 # later, in another part of MyApp...

 $c->request->exp_secure_cookies( $expiration );
 $c->request->set_secure_cookie( 'my_cookie_name', $value );
 my $secure_data = $c->request->get_secure_cookie('my_cookie_name');

DESCRIPTION

Overview

When HTTP cookies are used to store a user's state or identity it's important that your application is able to distinguish legitimate cookies from those that have been edited or created by a malicious user.

This module creates a pair of cookies which encrypt a form so the user cannot modify cookie contents.

Implementation

SecureCookies is implemented using Crypt::CBC and MIME::Base64 to encrypt and encode a urlencoded string representing a perl hash. The encoded string is then hashed using Digest::SHA1 to prepare a sort of "checksum" or hash to make sure the user did not modify the cookie.

CONFIGURATION

key

 MyApp->config->{SecureCookies}->{key} = $secret_key;

This parameter is required, and sets the secret key that is used to encrypt the cookies with Crypt::CBC Blowfish. This needs to be a 16 hex character string.

ssl

 MyApp->config->{SecureCookies}->{ssl} = 0;
   # or
 MyApp->config->{SecureCookies}->{ssl} = 1;

This parameter is optional, and will default to 1 if not set.

If 1, the checksum or hash cookie will be sent over SSL for added security. This will prevent replay attacks from being used against the server.

If 0, the checksum will be sent as a normal, non-secure cookie.

DIAGNOSTICS

METHODS

Catalyst Request Object Methods

$c->request->get_secure_cookie($cookie_name)

If a cookie was successfully authenticated then this method will return the value of the cookie.

_encrypt

Description: Takes a hashref representing web form elements, encrypts the components, creates a base64 safe url string

Args: $form_hasref - hashref of vars

Return: $encoded - the encoded form $csum - the checksum

_decrypt

Description: Takes a base64 safe url string representing form elements, decrypts the components, creates a hashref m Args: $encoded - encoded form $csum - csum for the form

Return: $form_hashref - hashref of the variables

_base64_encode_url

Description: - safely encode using base64 to be used in urls

_base64_decode_url

Description: - safely decode base64 from urls

decode_url_hashref

Description:

convert a get string ( key1=val1&key2=val2 ) to a hash representing a web form. If you are really using a get string, you must be sure to only pass in the text after the question mark.

Args: $url_encoded - parse this text

Return: $form - hashref of the variables

_urlencode_string

Description: convert $string into a url safe format

SEE ALSO

Catalyst, Digest::SHA1, Crypt::CBC, MIME::Base64

http://www.schneier.com/blog/archives/2005/08/new_cryptanalyt.html

AUTHOR

Rob Johnson rob@giant-rock.com

ACKNOWLEDGEMENTS

 * Karim A. Nassar for converting this into a self-contained Catalyst Plugin.

 * All the helpful people in #catalyst.

COPYRIGHT

Copyright (c) 2007 Karim A. Nassar <karim.nassar@acm.org>

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.