.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.19)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CGI::Application::Plugin::LinkIntegrity 3pm"
.TH CGI::Application::Plugin::LinkIntegrity 3pm "2011-11-11" "perl v5.12.4" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CGI::Application::Plugin::LinkIntegrity \- Make tamper\-resisistent links in CGI::Application
.SH "VERSION"
.IX Header "VERSION"
Version 0.06
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In your application:
.PP
.Vb 2
\&    use base \*(AqCGI::Application\*(Aq;
\&    use CGI::Application::Plugin::LinkIntegrity;
\&
\&    sub setup {
\&        my $self = shift;
\&        $self\->link_integrity_config(
\&            secret => \*(Aqsome secret string known only to you and me\*(Aq,
\&        );
\&    }
\&
\&    sub account_info {
\&        my $self = shift;
\&
\&        my $account_id = get_user_account_id();
\&
\&        my $template = $self\->load_tmpl(\*(Aqaccount.html\*(Aq);
\&
\&        $template\->param(
\&            \*(Aqbalance\*(Aq    => $self\->link("/account.cgi?rm=balance&acct_id=$account_id");
\&            \*(Aqtransfer\*(Aq   => $self\->link("/account.cgi?rm=transfer&acct_id=$account_id");
\&            \*(Aqwithdrawal\*(Aq => $self\->link("/account.cgi?rm=withdrawl&acct_id=$account_id");
\&        );
\&    }
.Ve
.PP
In your template:
.PP
.Vb 5
\&    <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>
.Ve
.PP
This will send the following \s-1HTML\s0 to the browser:
.PP
.Vb 5
\&    <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>
.Ve
.PP
The URLs created are now tamper-resistent.  If the user changes
\&\f(CW\*(C`acct_id\*(C'\fR from \f(CW73\fR to \f(CW74\fR, the \f(CW\*(C`_checksum\*(C'\fR will not match, and the
system will treat it as an intrusion attempt.
.SS "Calling link and self_link directly from the template"
.IX Subsection "Calling link and self_link directly from the template"
If you use \f(CW\*(C`Template::Toolkit|Template\*(C'\fR or
\&\f(CW\*(C`HTML::Template::Plugin::Dot\*(C'\fR, you can pass the \f(CW\*(C`CGI::Application\*(C'\fR
\&\f(CW$self\fR object into the template and call \f(CW\*(C`link\*(C'\fR and \f(CW\*(C`self_link\*(C'\fR directly
from the template.  In your app:
.PP
.Vb 5
\&    $template\->param(
\&        \*(Aqapp\*(Aq     => $self,
\&        \*(Aqname\*(Aq    => \*(Aqgordon\*(Aq,
\&        \*(Aqemail\*(Aq   => \*(Aqgordon@example.com\*(Aq,
\&    );
.Ve
.PP
And in your template you can use
.PP
.Vb 2
\&    # Template::Toolkit syntax
\&    <a href="[% app.self_link(\*(Aqname\*(Aq, name, \*(Aqemail\*(Aq, email %]">...</a>
\&
\&    # HTML::Template::Plugin::Dot syntax
\&    <a href="<TMPL_VAR NAME="app.self_link(\*(Aqname\*(Aq, name, \*(Aqemail\*(Aq, email">">...</a>
\&
\&    # Petal syntax
\&    <a href="http://www.example.com"
\&       tal:attributes="href app/self_link(\*(Aqname\*(Aq, name, \*(Aqemail\*(Aq, email)">...</a>
.Ve
.PP
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 \f(CW\*(Aqemail\*(Aq\fR is the literal string, and \f(CW\*(C`email\*(C'\fR is
the template parameter named email (in this case 'gordon@example.com').
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`CGI::Application::Plugin::LinkIntegrity\*(C'\fR lets you create
tamper-resistent links within your CGI::Application project.  When you
create an \s-1URL\s0 with \f(CW\*(C`link\*(C'\fR, a \f(CW\*(C`_checksum\*(C'\fR is added to the \s-1URL:\s0
.PP
.Vb 2
\&    my $link = $self\->link("/account.cgi?rm=balance&acct_id=73");
\&    print $link; # /account.cgi?rm=balance&acct_id=73&_checksum=1d7c4b82d075785de04fa6b98b572691
.Ve
.PP
The checksum is a (cryptographic) hash of the \s-1URL\s0, plus a secret string
known only to the server.
.PP
If the user attempts to change part of the \s-1URL\s0 (e.g. a query string
parameter, or the \s-1PATH_INFO\s0), then the checksum will not match.  The run
mode will be changed to \f(CW\*(C`link_tampered\*(C'\fR, and the \f(CW\*(C`invalid_checksum\*(C'\fR
hook will be called.
.PP
You can define the \f(CW\*(C`link_tampered\*(C'\fR run mode yourself, or you can use
the default \f(CW\*(C`link_tampered\*(C'\fR run mode built into
CGI::Application::Plugin::LinkIntegrity.
.PP
You can disable link checking during development by passing a true value
to the \f(CW\*(C`disable\*(C'\fR parameter of \f(CW\*(C`$self\->link_integrity_config\*(C'\fR.
.SH "METHODS"
.IX Header "METHODS"
.SS "link_integrity_config"
.IX Subsection "link_integrity_config"
Configure the CGI::Application::Plugin::LinkIntegrity.  Usually, it
makes sense to configure this in the \f(CW\*(C`setup\*(C'\fR method of your application's
base class:
.PP
.Vb 3
\&    use CGI::Application::Plugin::LinkIntegrity;
\&    use base \*(AqCGI::Application\*(Aq;
\&    package My::Project;
\&
\&    sub setup {
\&        my $self = shift;
\&
\&        $self\->run_modes([\*(Aqbad_user_no_biscuit\*(Aq]);
\&        $self\->link_integrity_config(
\&            secret                 => \*(Aqsome secret string known only to you and me\*(Aq,
\&            link_tampered_run_mode => \*(Aqbad_user_no_biscuit\*(Aq,
\&            digest_module          => \*(AqDigest::MD5\*(Aq,
\&            disable                => 1,
\&        );
\&    }
.Ve
.PP
Or you can pull in this configuration info from a config file.  For
instance, with using CGI::Application::Config::Context:
.PP
.Vb 2
\&    use CGI::Application::Plugin::LinkIntegrity;
\&    use CGI::Application::Plugin::Config::Context;
\&
\&    use base \*(AqCGI::Application\*(Aq;
\&    package My::Project;
\&
\&    sub setup {
\&        my $self = shift;
\&
\&        $self\->conf\->init(
\&            file   => \*(Aqapp.conf\*(Aq,
\&            driver => \*(AqConfigGeneral\*(Aq,
\&        );
\&
\&        my $config = $self\->conf\->context;
\&
\&        $self\->link_integrity_config(
\&            $config\->{\*(AqLinkIntegrity\*(Aq},
\&            additional_data => sub {
\&                my $self = shift;
\&                return $self\->session\->id;
\&            },
\&        );
\&
\&        my $link_tampered_rm = $config\->{\*(AqLinkIntegrity\*(Aq}{\*(Aqlink_tampered_run_mode\*(Aq} || \*(Aqlink_tampered\*(Aq;
\&
\&        $self\->run_modes([$link_tampered_rm]);
\&    }
.Ve
.PP
Then in your configuration file:
.PP
.Vb 6
\&    <LinkIntegrity>
\&        secret                 = some REALLY secret string
\&        link_tampered_run_mode = bad_user_no_biscuit
\&        hash_algorithm         = SHA1
\&        disable                = 1
\&    </LinkIntegrity>
.Ve
.PP
This strategy allows you to enable and disable link checking on the fly
by changing the value of \f(CW\*(C`disable\*(C'\fR in the config file.
.PP
The following configuration parameters are available:
.IP "secret" 4
.IX Item "secret"
A string known only to your application.  At a commandline, you can
generate a secret string with md5:
.Sp
.Vb 1
\& $ perl \-MDigest::MD5 \-le"print Digest::MD5::md5_hex($$, time, rand(42));"
.Ve
.Sp
Or you can use Data::UUID:
.Sp
.Vb 1
\& $ perl \-MData::UUID \-le"$ug = new Data::UUID; $uuid = $ug\->create; print $ug\->to_string($uuid)"
.Ve
.Sp
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.
.IP "additional_data" 4
.IX Item "additional_data"
You can pass constant additional data to the checksum generator for every link.
.Sp
.Vb 4
\&    $self\->link_integrity_config(
\&        secret          => \*(Aqreally secret\*(Aq,
\&        additional_data => \*(Aqsome other secret data\*(Aq,
\&    }
.Ve
.Sp
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:
.Sp
.Vb 7
\&    $self\->link_integrity_config(
\&        secret          => \*(Aqreally secret\*(Aq,
\&        additional_data => sub {
\&            my $self = shift;
\&            return $self\->session\->id;
\&        }
\&    }
.Ve
.Sp
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.
.IP "checksum_param" 4
.IX Item "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 \f(CW\*(C`_checksum\*(C'\fR.
.IP "link_tampered_run_mode" 4
.IX Item "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 \f(CW\*(C`link_tampered\*(C'\fR.
.Sp
See \*(L"The link_tampered Run Mode\*(R", below.
.IP "digest_module" 4
.IX Item "digest_module"
Which digest module to use to create the checksum.  Typically, this will
be either \f(CW\*(C`Digest::MD5\*(C'\fR or \f(CW\*(C`Digest::SHA\*(C'\fR.  However any module
supported by \f(CW\*(C`Digest::HMAC\*(C'\fR will work.
.Sp
The default \f(CW\*(C`digest_module\*(C'\fR is \f(CW\*(C`Digest::MD5\*(C'\fR.
.IP "checksum_generator" 4
.IX Item "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 \f(CW\*(C`make_checksum\*(C'\fR param.
Here's an example of one that uses Digest::SHA2:
.Sp
.Vb 4
\&        $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;
\&            },
\&        );
.Ve
.IP "disable" 4
.IX Item "disable"
You can disable link checking entirely by setting \f(CW\*(C`disable\*(C'\fR to a true
value.  This can be useful when you are developing or debugging the
application and you want the ability to tweak \s-1URL\s0 params without getting
busted.
.SS "link"
.IX Subsection "link"
Create a link, and add a checksum to it.
.PP
You can add parameters to the link directly in the \s-1URL:\s0
.PP
.Vb 1
\&    my $link = $self\->link(\*(Aq/cgi\-bin/app.cgi?var=value&var2=value2\*(Aq);
.Ve
.PP
Or you can add them as a hash of parameters after the \s-1URL:\s0
.PP
.Vb 5
\&    my $link = $self\->link(
\&        \*(Aq/cgi\-bin/app.cgi\*(Aq,
\&        \*(Aqparam1\*(Aq  => \*(Aqvalue\*(Aq,
\&        \*(Aqparam2\*(Aq => \*(Aqvalue2\*(Aq,
\&    );
.Ve
.SS "self_link"
.IX Subsection "self_link"
Make a link to the current application, with optional parameters, and
add a checksum to the \s-1URL\s0.
.PP
.Vb 4
\&    my $link = $self\->self_link(
\&        \*(Aqparam1\*(Aq => \*(Aqvalue1\*(Aq,
\&        \*(Aqparam2\*(Aq => \*(Aqvalue2\*(Aq,
\&    );
.Ve
.PP
\&\f(CW\*(C`self_link\*(C'\fR preserves the value of the current application's \f(CW\*(C`PATH_INFO\*(C'\fR.
For instance if the current \s-1URL\s0 is:
.PP
.Vb 1
\&    /cgi\-bin/app.cgi/some/path?foo=bar # PATH_INFO is \*(Aqsome/path\*(Aq
.Ve
.PP
Calling:
.PP
.Vb 1
\&    $self\->self_link(\*(Aqbar\*(Aq => \*(Aqbaz\*(Aq);
.Ve
.PP
Will produce the \s-1URL:\s0
.PP
.Vb 1
\&    /cgi\-bin/app.cgi/some/path?bar=baz
.Ve
.PP
If you want to remove the \f(CW\*(C`PATH_INFO\*(C'\fR value or replace it with a new
value, use path_link.
.SS "path_link"
.IX Subsection "path_link"
Calling \f(CW\*(C`path_link\*(C'\fR is the same as calling \f(CW\*(C`self_link\*(C'\fR, except
the current value of \f(CW\*(C`PATH_INFO\*(C'\fR can be replaced.
.PP
.Vb 5
\&    my $link = $self\->path_link(
\&        \*(Aq/new/path\*(Aq,
\&        \*(Aqparam1\*(Aq => \*(Aqvalue1\*(Aq,
\&        \*(Aqparam2\*(Aq => \*(Aqvalue2\*(Aq,
\&    );
.Ve
.PP
For instance if the current \s-1URL\s0 is:
.PP
.Vb 1
\&    /cgi\-bin/app.cgi/some/path?foo=bar # PATH_INFO is \*(Aqsome/path\*(Aq
.Ve
.PP
Calling:
.PP
.Vb 1
\&    $self\->path_link(\*(Aq/new/path\*(Aq);
.Ve
.PP
Will produce the \s-1URL:\s0
.PP
.Vb 1
\&    /cgi\-bin/app.cgi/new/path?foo=bar
.Ve
.PP
If you want to remove \f(CW\*(C`PATH_INFO\*(C'\fR entirely, call one of the following:
.PP
.Vb 3
\&    $self\->path_link;
\&    $self\->path_link(undef, \*(Aqparam1\*(Aq => \*(Aqval1\*(Aq, \*(Aqparam2 => \*(Aqval2\*(Aq ...);
\&    $self\->path_link(\*(Aq\*(Aq, \*(Aqparam1\*(Aq => \*(Aqval1\*(Aq, \*(Aqparam2 => \*(Aqval2\*(Aq ...);
.Ve
.PP
If you want to keep the existing \f(CW\*(C`PATH_INFO\*(C'\fR that was passed to the
current application, use self_link instead.
.SH "RUN MODES"
.IX Header "RUN MODES"
.SS "The link_tampered Run Mode"
.IX Subsection "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
\&\f(CW\*(C`link_tampered_runmode\*(C'\fR param to \f(CW\*(C`link_integrity_config\*(C'\fR.
.PP
CGI::Application::Plugin::LinkIntegrity provides a default
\&\f(CW\*(C`link_tampered\*(C'\fR run mode, which just displays a page with some stern
warning text.
.PP
You can define your own as follows:
.PP
.Vb 5
\&    sub link_tampered {
\&        my $self = shift;
\&        my $template = $self\->load_template(\*(Aqstern_talking_to\*(Aq);
\&        return $template\->output;
\&    }
.Ve
.SH "HOOKS"
.IX Header "HOOKS"
When a link is followed that doesn't match the checksum, the
\&\f(CW\*(C`invalid_checksum\*(C'\fR hook is called.  You can add a callback to this hook
to do some cleanup such as deleting the user's session.  For instance:
.PP
.Vb 4
\&    sub setup {
\&        my $self = shift;
\&        $self\->add_callback(\*(Aqinvalid_checksum\*(Aq => \e&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\*(Aqt tolerate this behaviour.
\&        # So we delete the user\*(Aqs session:
\&
\&        $self\->session\->delete;
\&    }
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael Graham, \f(CW\*(C`<mag\-perl@occamstoothbrush.com>\*(C'\fR
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
This module was based on the checksum feature originally built into
Richard Dice's CGI::Application::Framework.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-cgi\-application\-plugin\-linkintegrity@rt.cpan.org\*(C'\fR, 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.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2005 Michael Graham, All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.