view release on metacpan or  search on metacpan

lib/Catalyst/Plugin/HashedCookies.pm  view on Meta::CPAN

            $cookie->{value} = [
                @{ [ $cgicookie->value ] },
                '_hashedcookies_digest' => $hmac->hexdigest,
            ];
        }

        $hmac->reset;
    }

    $c->next::method(@_);
    return $c;
}

# ABSTRACT: Tamper-resistant HTTP Cookies


1;

__END__
=pod

=head1 NAME

Catalyst::Plugin::HashedCookies - Tamper-resistant HTTP Cookies

=head1 VERSION

version 1.131710

=head1 SYNOPSIS

 use Catalyst qw/HashedCookies/;
 MyApp->config->{hashedcookies} = {
     key       => $secret_key,
     algorithm => 'SHA1', # optional
     required  => 1,      # optional
 };
 MyApp->setup;

 # later, in another part of MyApp...

 print "this cookie tastes good!\n"
  if $c->request->valid_cookie('my_cookie_name');

=head1 DESCRIPTION

=head2 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 allows you to determine whether a cookie presented by a client was
created in its current state by your own application.

=head2 Implementation

HashedCookies adds a keyed cryptographic hash to each cookie that your
application creates, and checks every client-provided cookie for a valid hash.

This is done in a transparent way such that you do not need to change B<any>
application code that handles cookies when using this plugin. A cookie that
fails to contain a valid hash will still be available to your application
through C<< $c->request->cookie() >>.

Two additional methods within the Catalyst request object allow you to check
the status (in other words, the vailidity) of your cookies.

=head1 METHODS

=head2 Catalyst Request Object Methods

=over 4

=item C<< $c->request->valid_cookie($cookie_name) >>

If a cookie was successfully authenticated then this method will return True,
otherwise it will return False.

=item C<< $c->request->invalid_cookie($cookie_name) >>

If a cookie failed its authentication, then this method will return True,
otherwise it will return False. Please read the L</"CONFIGURATION"> section
below to understand what 'failed authentication' really means.

=back

=head1 CONFIGURATION

=over 4

=item key

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

This parameter is B<required>, and sets the secret key that is used to
generate a message authentication hash. Clearly, for a returned cookie to be
authenticated the same key must be used both when setting the cookie and
retrieving it.

=item algorithm

 MyApp->config->{hashedcookies}->{algorithm} = 'SHA1';
   # or
 MyApp->config->{hashedcookies}->{algorithm} = 'MD5';

This parameter is optional, and will default to C<SHA1> if not set. It
instructs the module to use the given message digest algorithm.

=item required

 MyApp->config->{hashedcookies}->{required} = 0;
   # or
 MyApp->config->{hashedcookies}->{required} = 1;

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

If a cookie is read from the client but does not contain a HashedCookies hash
(i.e. this module was not running when the cookie was set), then this
parameter controls whether the cookie is ignored.