view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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

VERSION
    version 1.131710

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');

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

  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
    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->request->cookie()".

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

METHODS
  Catalyst Request Object Methods
    "$c->request->valid_cookie($cookie_name)"
        If a cookie was successfully authenticated then this method will
        return True, otherwise it will return False.

    "$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
        "CONFIGURATION" section below to understand what 'failed
        authentication' really means.

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

        This parameter is 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.

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

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

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

        This parameter is optional, and will default to 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.

        Setting this parameter to True means that a cookie without a hash is
        treated as if it did have a hash, and therefore the authentication
        will fail. Setting this parameter to False means that the cookie
        will be ignored.

        When a cookie is ignored, neither "$c->request->valid_cookie()" nor
        "$c->request->invalid_cookie()" will return True, but you can of
        course still access the cookie through "$c->request->cookie()".

DIAGNOSTICS
    'Request for unknown digest algorithm to ...'
        You have attempted to configure this module with an unrecognized