Calling link and self_link directly from the template

    $template->param(
        'app'     => $self,
        'name'    => 'gordon',
        'email'   => 'gordon@example.com',
    );

And in your template you can use

    # Template::Toolkit syntax
    <a href="[% app.self_link('name', name, 'email', email %]">...</a>

    # HTML::Template::Plugin::Dot syntax
    <a href="<TMPL_VAR NAME="app.self_link('name', name, 'email', email">">...</a>

    # Petal syntax
    <a href="http://www.example.com"
       tal:attributes="href app/self_link('name', name, 'email', email)">...</a>

Note that in the parameters of the call to << link >>, items enclosed in quotes are treated as literal parameters and barewords are treated as template params. So 'email' is the literal string, and "email" is the template paramter named email (in this case 'gordon@example.com').

link_integrity_config

    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'},
            additional_data => sub {
                my $self = shift;
                return $self->session->id;
            },
        );

        my $link_tampered_rm = $config->{'LinkIntegrity'}{'link_tampered_run_mode'} || 'link_tampered';

        $self->run_modes([$link_tampered_rm]);
    }

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.

additional_data

You can pass constant additional data to the checksum generator for every link.

    $self->link_integrity_config(
        secret          => 'really secret',
        additional_data => 'some other secret data',
    }
    

For instance, to stop one user from following a second user's link, you can add a user-specific component to the session, such as the user's session id:

    $self->link_integrity_config(
        secret          => 'really secret',
        additional_data => sub {
            my $self = shift;
            return $self->session->id;
        }
    }
    

You can pass a string instead of a subroutine. But in the case of the user's session, a subroutine is useful so that you get the value of the user's session at the time when the checksum is generated, not at the time when the link integrity system is configured.

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.

link

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

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

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

    my $link = $self->link(
        '/cgi-bin/app.cgi',
        'param1'  => 'value',
        'param2' => 'value2',
    );

self_link

    my $link = $self->self_link(
        'param1' => 'value1',
        'param2' => 'value2',
    );

"self_link" preserves the value of the current application's "PATH_INFO". For instance if the current URL is:

    /cgi-bin/app.cgi/some/path?foo=bar # PATH_INFO is 'some/path'

Calling:

    $self->self_link('bar' => 'baz');

Will produce the URL:

    /cgi-bin/app.cgi/some/path?bar=baz

If you want to remove the "PATH_INFO" value or replace it with a new value, use path_link.

path_link

    my $link = $self->path_link(
        '/new/path',
        'param1' => 'value1',
        'param2' => 'value2',
    );

For instance if the current URL is:

    /cgi-bin/app.cgi/some/path?foo=bar # PATH_INFO is 'some/path'

Calling:

    $self->path_link('/new/path');

Will produce the URL:

    /cgi-bin/app.cgi/new/path?foo=bar

If you want to remove "PATH_INFO" entirely, call one of the following:

    $self->path_link;
    $self->path_link(undef, 'param1' => 'val1', 'param2 => 'val2' ...);
    $self->path_link('', 'param1' => 'val1', 'param2 => 'val2' ...);

If you want to keep the existing "PATH_INFO" that was passed to the current application, use self_link instead.

The link_tampered Run Mode

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;
    }