NAME
    CGI::Application::Plugin::LinkIntegrity - Make tamper-resisistent links
    in CGI::Application

VERSION
    Version 0.01

SYNOPSIS
    In your application:

        use base 'CGI::Application';
        use CGI::Application::Plugin::LinkIntegrity;

        sub setup {
            my $self = shift;
            $self->link_integrity_config(
                secret => 'some secret string known only to you and me',
            );
        }

        sub account_info {
            my $self = shift;

            my $account_id = get_user_account_id();

            my $template = $self->load_tmpl('account.html');

            $template->param(
                'balance'    => $self->make_link("/account.cgi?rm=balance&acct_id=$account_id");
                'transfer'   => $self->make_link("/account.cgi?rm=transfer&acct_id=$account_id");
                'withdrawal' => $self->make_link("/account.cgi?rm=withdrawl&acct_id=$account_id");
            );
        }

    In your template:

        <h1>Welcome to The Faceless Banking Corp.</h1>
        <h3>Actions:</h3>
        <br /><a href="<TMPL_VAR NAME="balance">">Show Balance</a>
        <br /><a href="<TMPL_VAR NAME="transfer">">Make a Transfer</a>
        <br /><a href="<TMPL_VAR NAME="withdrawal">">Get Cash</a>

    This will send the following HTML to the browser:

        <h1>Welcome to The Faceless Banking Corp.</h1>
        <h3>Actions:</h3>
        <br /><a href="/account.cgi?rm=balance&acct_id=73&_checksum=1d7c4b82d075785de04fa6b98b572691">Show Balance</a>
        <br /><a href="/account.cgi?rm=transfer&acct_id=73&_checksum=d41d8cd98f00b204e9800998ecf8427e">Make a Transfer</a>
        <br /><a href="/account.cgi?rm=withdrawl&acct_id=73&_checksum=3c5ad17bdeef3c4281abd39c6386cfd6">Get Cash</a>

    The URLs created are now tamper-resistent. If the user changes "acct_id"
    from 73 to 74, the "_checksum" will not match, and the system will treat
    it as an intrusion attempt.

DESCRIPTION
    "CGI::Application::Plugin::LinkIntegrity" lets you create
    tamper-resistent links within your CGI::Application project. When you
    create an URL with "make_link", a "_checksum" is added to the URL:

        my $link = $self->make_link("/account.cgi?rm=balance&acct_id=73");
        print $link; # /account.cgi?rm=balance&acct_id=73&_checksum=1d7c4b82d075785de04fa6b98b572691

    The checksum is a (cryptographic) hash of the URL, plus a secret string
    known only to the server.

    If the user attempts to change part of the URL (e.g. a query string
    parameter, or the PATH_INFO), then the checksum will not match. The run
    mode will be changed to "link_tampered", and the "invalid_checksum" hook
    will be called.

    You can define the "link_tampered" run mode yourself, or you can use the
    default "link_tampered" run mode built into
    CGI::Application::Plugin::LinkIntegrity.

    You can disable link checking during development by passing a true value
    to the "disable" parameter of "$self->link_integrity_config".

METHODS
  link_integrity_config
    Configure the CGI::Application::Plugin::LinkIntegrity. Usually, it makes
    sense to configure this in the "setup" method of your application's base
    class:

        use CGI::Application::Plugin::LinkIntegrity;
        use base 'CGI::Application';
        package My::Project;

        sub setup {
            my $self = shift;

            $self->run_modes(['bad_user_no_biscuit']);
            $self->link_integrity_config(
                secret                 => 'some secret string known only to you and me',
                link_tampered_run_mode => 'bad_user_no_biscuit',
                digest_module          => 'Digest::MD5',
                disable                => 1,
            );
        }

    Or you can pull in this configuration info from a config file. For
    instance, with using CGI::Application::Config::Context:

        use CGI::Application::Plugin::LinkIntegrity;
        use CGI::Application::Plugin::Config::Context;

        use base 'CGI::Application';
        package My::Project;

        sub setup {
            my $self = shift;

            $self->conf->init(
                file   => 'app.conf',
                driver => 'ConfigGeneral',
            );

            my $config = $self->conf->context;

            $self->link_integrity_config($config->{'LinkIntegrity'});
            $self->run_modes([$config->{'LinkIntegrity'}{'link_tampered_run_mode'} || 'link_tampered']);
        }

    Then in your configuration file:

        <LinkIntegrity>
            secret                 = some REALLY secret string
            link_tampered_run_mode = bad_user_no_biscuit
            hash_algorithm         = SHA1
            disable                = 1
        </LinkIntegrity>

    This strategy allows you to enable and disable link checking on the fly
    by changing the value of "disable" in the config file.

    The following configuration parameters are available:

    secret
        A string known only to your application. At a commandline, you can
        generate a secret string with md5:

         $ perl -MDigest::MD5 -le"print Digest::MD5::md5_hex($$, time, rand(42));"

        Or you can use Data::UUID:

         $ perl -MData::UUID -le"$ug = new Data::UUID; $uuid = $ug->create; print $ug->to_string($uuid)"

        If someone knows your secret string, then they can generate their
        own checksums on arbitrary data that will always pass the integrity
        check in your application. That's a Bad Thing, so don't let other
        people know your secret string, and don't use the default secret
        string if you can help it.

    checksum_param
        The name of the checksum parameter, which is added to the query
        string and contains the cryptographic checksum of link. By default,
        this parameter is named "_checksum".

    link_tampered_run_mode
        The run mode to go to when it has been detected that the user has
        tampered with the link. The default is "link_tampered".

        See "The link_tampered Run Mode", below.

    digest_module
        Which digest module to use to create the checksum. Typically, this
        will be either "Digest::MD5" or "Digest::SHA1". However any module
        supported by "Digest::HMAC" will work.

        The default "digest_module" is "Digest::MD5".

    checksum_generator
        If you want to provide a custom subroutine to make your own
        checksums, you can define your own subroutine do it via the
        "make_checksum" param. Here's an example of one that uses
        Digest::SHA2:

                $self->link_integrity_config(
                    checksum_generator => sub {
                        my ($url, $secret) = @_;
                        require Digest::SHA2;

                        my $ctx = Digest::SHA2->new();
                        $ctx->add($url . $secret);

                        return $ctx->hexdigest;
                    },
                );

    disable
        You can disable link checking entirely by setting "disable" to a
        true value. This can be useful when you are developing or debugging
        the application and you want the ability to tweak URL params without
        getting busted.

  make_link
    Create a link, and add a checksum to it.

    You can add parameters to the link directly in the URL:

        my $link = $self->make_link('/cgi-bin/app.cgi?var=value&var2=value2');

    Or you can add them as a hashref of parameters after the URL:

        my $link = $self->make_link(
            '/cgi-bin/app.cgi',
            {
                var  => 'value',
                var2 => 'value2',
            }
        );

  make_self_link
    Make a link to the current application, with optional parameters, and
    add a checksum to the URL.

        my $link = $self->make_self_link(
            params => {
                var1 => 'value1',
                var1 => 'value2',
            },
        );

    If you want to keep the existing "PATH_INFO" that was passed to the
    current application, use the "keep_path_info" param:

        my $link = $self->make_self_link(
            keep_path_info => 1,
            params         => {
                var1 => 'value1',
                var1 => 'value2',
            },
        );

    If you want to use a different "PATH_INFO" than the one that was used in
    calling the current application use the "path_info" param:

        my $link = $self->make_self_link(
            path_info      => '/some/path',
            params         => {
                var1 => 'value1',
                var1 => 'value2',
            },
        );

RUN MODES
  The link_tampered Run Mode
    Your application is redirected to this run mode when it has been
    detected that the user has tampered with the link. You can change the
    name of this run mode by changing the value of the
    "link_tampered_runmode" param to "link_integrity_config".

    CGI::Application::Plugin::LinkIntegrity provides a default
    "link_tampered" run mode, which just displays a page with some stern
    warning text.

    You can define your own as follows:

        sub link_tampered {
            my $self = shift;
            my $template = $self->load_template('stern_talking_to');
            return $template->output;
        }

HOOKS
    When a link is followed that doesn't match the checksum, the
    "invalid_checksum" hook is called. You can add a callback to this hook
    to do some cleanup such as deleting the user's session. For instance:

        sub setup {
            my $self = shift;
            $self->add_callback('invalid_checksum' => \&bad_user);
        }

        sub bad_user {
            my $self = shift;

            # The user has been messing with the URLs, possibly trying to
            # break into the system.  We don't tolerate this behaviour.
            # So we delete the user's session:

            $self->session->delete;
        }

AUTHOR
    Michael Graham, "<mag-perl@occamstoothbrush.com>"

ACKNOWLEDGEMENTS
    This module was based on the checksum feature originally built into
    Richard Dice's CGI::Application::Framework.

BUGS
    Please report any bugs or feature requests to
    "bug-cgi-application-plugin-linkintegrity@rt.cpan.org", or through the
    web interface at <http://rt.cpan.org>. I will be notified, and then
    you'll automatically be notified of progress on your bug as I make
    changes.

COPYRIGHT & LICENSE
    Copyright 2005 Michael Graham, All Rights Reserved.

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