| 1 |
NAME |
| 2 |
CGI::Application::Plugin::LinkIntegrity - Make tamper-resisistent links |
| 3 |
in CGI::Application |
| 4 |
|
| 5 |
VERSION |
| 6 |
Version 0.06 |
| 7 |
|
| 8 |
SYNOPSIS |
| 9 |
In your application: |
| 10 |
|
| 11 |
use base 'CGI::Application'; |
| 12 |
use CGI::Application::Plugin::LinkIntegrity; |
| 13 |
|
| 14 |
sub setup { |
| 15 |
my $self = shift; |
| 16 |
$self->link_integrity_config( |
| 17 |
secret => 'some secret string known only to you and me', |
| 18 |
); |
| 19 |
} |
| 20 |
|
| 21 |
sub account_info { |
| 22 |
my $self = shift; |
| 23 |
|
| 24 |
my $account_id = get_user_account_id(); |
| 25 |
|
| 26 |
my $template = $self->load_tmpl('account.html'); |
| 27 |
|
| 28 |
$template->param( |
| 29 |
'balance' => $self->link("/account.cgi?rm=balance&acct_id=$account_id"); |
| 30 |
'transfer' => $self->link("/account.cgi?rm=transfer&acct_id=$account_id"); |
| 31 |
'withdrawal' => $self->link("/account.cgi?rm=withdrawl&acct_id=$account_id"); |
| 32 |
); |
| 33 |
} |
| 34 |
|
| 35 |
In your template: |
| 36 |
|
| 37 |
<h1>Welcome to The Faceless Banking Corp.</h1> |
| 38 |
<h3>Actions:</h3> |
| 39 |
<br /><a href="<TMPL_VAR NAME="balance">">Show Balance</a> |
| 40 |
<br /><a href="<TMPL_VAR NAME="transfer">">Make a Transfer</a> |
| 41 |
<br /><a href="<TMPL_VAR NAME="withdrawal">">Get Cash</a> |
| 42 |
|
| 43 |
This will send the following HTML to the browser: |
| 44 |
|
| 45 |
<h1>Welcome to The Faceless Banking Corp.</h1> |
| 46 |
<h3>Actions:</h3> |
| 47 |
<br /><a href="/account.cgi?rm=balance&acct_id=73&_checksum=1d7c4b82d075785de04fa6b98b572691">Show Balance</a> |
| 48 |
<br /><a href="/account.cgi?rm=transfer&acct_id=73&_checksum=d41d8cd98f00b204e9800998ecf8427e">Make a Transfer</a> |
| 49 |
<br /><a href="/account.cgi?rm=withdrawl&acct_id=73&_checksum=3c5ad17bdeef3c4281abd39c6386cfd6">Get Cash</a> |
| 50 |
|
| 51 |
The URLs created are now tamper-resistent. If the user changes "acct_id" |
| 52 |
from 73 to 74, the "_checksum" will not match, and the system will treat |
| 53 |
it as an intrusion attempt. |
| 54 |
|
| 55 |
Calling link and self_link directly from the template |
| 56 |
If you use "Template::Toolkit|Template" or |
| 57 |
"HTML::Template::Plugin::Dot", you can pass the "CGI::Application" $self |
| 58 |
object into the template and call "link" and "self_link" directly from |
| 59 |
the template. In your app: |
| 60 |
|
| 61 |
$template->param( |
| 62 |
'app' => $self, |
| 63 |
'name' => 'gordon', |
| 64 |
'email' => '[email protected]', |
| 65 |
); |
| 66 |
|
| 67 |
And in your template you can use |
| 68 |
|
| 69 |
# Template::Toolkit syntax |
| 70 |
<a href="[% app.self_link('name', name, 'email', email %]">...</a> |
| 71 |
|
| 72 |
# HTML::Template::Plugin::Dot syntax |
| 73 |
<a href="<TMPL_VAR NAME="app.self_link('name', name, 'email', email">">...</a> |
| 74 |
|
| 75 |
# Petal syntax |
| 76 |
<a href="http://www.example.com" |
| 77 |
tal:attributes="href app/self_link('name', name, 'email', email)">...</a> |
| 78 |
|
| 79 |
Note that in the parameters of the call to << link >>, items enclosed in |
| 80 |
quotes are treated as literal parameters and barewords are treated as |
| 81 |
template params. So 'email' is the literal string, and "email" is the |
| 82 |
template paramter named email (in this case '[email protected]'). |
| 83 |
|
| 84 |
DESCRIPTION |
| 85 |
"CGI::Application::Plugin::LinkIntegrity" lets you create |
| 86 |
tamper-resistent links within your CGI::Application project. When you |
| 87 |
create an URL with "link", a "_checksum" is added to the URL: |
| 88 |
|
| 89 |
my $link = $self->link("/account.cgi?rm=balance&acct_id=73"); |
| 90 |
print $link; # /account.cgi?rm=balance&acct_id=73&_checksum=1d7c4b82d075785de04fa6b98b572691 |
| 91 |
|
| 92 |
The checksum is a (cryptographic) hash of the URL, plus a secret string |
| 93 |
known only to the server. |
| 94 |
|
| 95 |
If the user attempts to change part of the URL (e.g. a query string |
| 96 |
parameter, or the PATH_INFO), then the checksum will not match. The run |
| 97 |
mode will be changed to "link_tampered", and the "invalid_checksum" hook |
| 98 |
will be called. |
| 99 |
|
| 100 |
You can define the "link_tampered" run mode yourself, or you can use the |
| 101 |
default "link_tampered" run mode built into |
| 102 |
CGI::Application::Plugin::LinkIntegrity. |
| 103 |
|
| 104 |
You can disable link checking during development by passing a true value |
| 105 |
to the "disable" parameter of "$self->link_integrity_config". |
| 106 |
|
| 107 |
METHODS |
| 108 |
link_integrity_config |
| 109 |
Configure the CGI::Application::Plugin::LinkIntegrity. Usually, it makes |
| 110 |
sense to configure this in the "setup" method of your application's base |
| 111 |
class: |
| 112 |
|
| 113 |
use CGI::Application::Plugin::LinkIntegrity; |
| 114 |
use base 'CGI::Application'; |
| 115 |
package My::Project; |
| 116 |
|
| 117 |
sub setup { |
| 118 |
my $self = shift; |
| 119 |
|
| 120 |
$self->run_modes(['bad_user_no_biscuit']); |
| 121 |
$self->link_integrity_config( |
| 122 |
secret => 'some secret string known only to you and me', |
| 123 |
link_tampered_run_mode => 'bad_user_no_biscuit', |
| 124 |
digest_module => 'Digest::MD5', |
| 125 |
disable => 1, |
| 126 |
); |
| 127 |
} |
| 128 |
|
| 129 |
Or you can pull in this configuration info from a config file. For |
| 130 |
instance, with using CGI::Application::Config::Context: |
| 131 |
|
| 132 |
use CGI::Application::Plugin::LinkIntegrity; |
| 133 |
use CGI::Application::Plugin::Config::Context; |
| 134 |
|
| 135 |
use base 'CGI::Application'; |
| 136 |
package My::Project; |
| 137 |
|
| 138 |
sub setup { |
| 139 |
my $self = shift; |
| 140 |
|
| 141 |
$self->conf->init( |
| 142 |
file => 'app.conf', |
| 143 |
driver => 'ConfigGeneral', |
| 144 |
); |
| 145 |
|
| 146 |
my $config = $self->conf->context; |
| 147 |
|
| 148 |
$self->link_integrity_config( |
| 149 |
$config->{'LinkIntegrity'}, |
| 150 |
additional_data => sub { |
| 151 |
my $self = shift; |
| 152 |
return $self->session->id; |
| 153 |
}, |
| 154 |
); |
| 155 |
|
| 156 |
my $link_tampered_rm = $config->{'LinkIntegrity'}{'link_tampered_run_mode'} || 'link_tampered'; |
| 157 |
|
| 158 |
$self->run_modes([$link_tampered_rm]); |
| 159 |
} |
| 160 |
|
| 161 |
Then in your configuration file: |
| 162 |
|
| 163 |
<LinkIntegrity> |
| 164 |
secret = some REALLY secret string |
| 165 |
link_tampered_run_mode = bad_user_no_biscuit |
| 166 |
hash_algorithm = SHA1 |
| 167 |
disable = 1 |
| 168 |
</LinkIntegrity> |
| 169 |
|
| 170 |
This strategy allows you to enable and disable link checking on the fly |
| 171 |
by changing the value of "disable" in the config file. |
| 172 |
|
| 173 |
The following configuration parameters are available: |
| 174 |
|
| 175 |
secret |
| 176 |
A string known only to your application. At a commandline, you can |
| 177 |
generate a secret string with md5: |
| 178 |
|
| 179 |
$ perl -MDigest::MD5 -le"print Digest::MD5::md5_hex($$, time, rand(42));" |
| 180 |
|
| 181 |
Or you can use Data::UUID: |
| 182 |
|
| 183 |
$ perl -MData::UUID -le"$ug = new Data::UUID; $uuid = $ug->create; print $ug->to_string($uuid)" |
| 184 |
|
| 185 |
If someone knows your secret string, then they can generate their |
| 186 |
own checksums on arbitrary data that will always pass the integrity |
| 187 |
check in your application. That's a Bad Thing, so don't let other |
| 188 |
people know your secret string, and don't use the default secret |
| 189 |
string if you can help it. |
| 190 |
|
| 191 |
additional_data |
| 192 |
You can pass constant additional data to the checksum generator for |
| 193 |
every link. |
| 194 |
|
| 195 |
$self->link_integrity_config( |
| 196 |
secret => 'really secret', |
| 197 |
additional_data => 'some other secret data', |
| 198 |
} |
| 199 |
|
| 200 |
For instance, to stop one user from following a second user's link, |
| 201 |
you can add a user-specific component to the session, such as the |
| 202 |
user's session id: |
| 203 |
|
| 204 |
$self->link_integrity_config( |
| 205 |
secret => 'really secret', |
| 206 |
additional_data => sub { |
| 207 |
my $self = shift; |
| 208 |
return $self->session->id; |
| 209 |
} |
| 210 |
} |
| 211 |
|
| 212 |
You can pass a string instead of a subroutine. But in the case of |
| 213 |
the user's session, a subroutine is useful so that you get the value |
| 214 |
of the user's session at the time when the checksum is generated, |
| 215 |
not at the time when the link integrity system is configured. |
| 216 |
|
| 217 |
checksum_param |
| 218 |
The name of the checksum parameter, which is added to the query |
| 219 |
string and contains the cryptographic checksum of link. By default, |
| 220 |
this parameter is named "_checksum". |
| 221 |
|
| 222 |
link_tampered_run_mode |
| 223 |
The run mode to go to when it has been detected that the user has |
| 224 |
tampered with the link. The default is "link_tampered". |
| 225 |
|
| 226 |
See "The link_tampered Run Mode", below. |
| 227 |
|
| 228 |
digest_module |
| 229 |
Which digest module to use to create the checksum. Typically, this |
| •230 |
will be either "Digest::MD5" or "Digest::SHA". However any module |
| 231 |
supported by "Digest::HMAC" will work. |
| 232 |
|
| 233 |
The default "digest_module" is "Digest::MD5". |
| 234 |
|
| 235 |
checksum_generator |
| 236 |
If you want to provide a custom subroutine to make your own |
| 237 |
checksums, you can define your own subroutine do it via the |
| 238 |
"make_checksum" param. Here's an example of one that uses |
| 239 |
Digest::SHA2: |
| 240 |
|
| 241 |
$self->link_integrity_config( |
| 242 |
checksum_generator => sub { |
| 243 |
my ($url, $secret) = @_; |
| 244 |
require Digest::SHA2; |
| 245 |
|
| 246 |
my $ctx = Digest::SHA2->new(); |
| 247 |
$ctx->add($url . $secret); |
| 248 |
|
| 249 |
return $ctx->hexdigest; |
| 250 |
}, |
| 251 |
); |
| 252 |
|
| 253 |
disable |
| 254 |
You can disable link checking entirely by setting "disable" to a |
| 255 |
true value. This can be useful when you are developing or debugging |
| 256 |
the application and you want the ability to tweak URL params without |
| 257 |
getting busted. |
| 258 |
|
| 259 |
link |
| 260 |
Create a link, and add a checksum to it. |
| 261 |
|
| 262 |
You can add parameters to the link directly in the URL: |
| 263 |
|
| 264 |
my $link = $self->link('/cgi-bin/app.cgi?var=value&var2=value2'); |
| 265 |
|
| 266 |
Or you can add them as a hash of parameters after the URL: |
| 267 |
|
| 268 |
my $link = $self->link( |
| 269 |
'/cgi-bin/app.cgi', |
| 270 |
'param1' => 'value', |
| 271 |
'param2' => 'value2', |
| 272 |
); |
| 273 |
|
| 274 |
self_link |
| 275 |
Make a link to the current application, with optional parameters, and |
| 276 |
add a checksum to the URL. |
| 277 |
|
| 278 |
my $link = $self->self_link( |
| 279 |
'param1' => 'value1', |
| 280 |
'param2' => 'value2', |
| 281 |
); |
| 282 |
|
| 283 |
"self_link" preserves the value of the current application's |
| 284 |
"PATH_INFO". For instance if the current URL is: |
| 285 |
|
| 286 |
/cgi-bin/app.cgi/some/path?foo=bar # PATH_INFO is 'some/path' |
| 287 |
|
| 288 |
Calling: |
| 289 |
|
| 290 |
$self->self_link('bar' => 'baz'); |
| 291 |
|
| 292 |
Will produce the URL: |
| 293 |
|
| 294 |
/cgi-bin/app.cgi/some/path?bar=baz |
| 295 |
|
| 296 |
If you want to remove the "PATH_INFO" value or replace it with a new |
| 297 |
value, use path_link. |
| 298 |
|
| 299 |
path_link |
| 300 |
Calling "path_link" is the same as calling "self_link", except the |
| 301 |
current value of "PATH_INFO" can be replaced. |
| 302 |
|
| 303 |
my $link = $self->path_link( |
| 304 |
'/new/path', |
| 305 |
'param1' => 'value1', |
| 306 |
'param2' => 'value2', |
| 307 |
); |
| 308 |
|
| 309 |
For instance if the current URL is: |
| 310 |
|
| 311 |
/cgi-bin/app.cgi/some/path?foo=bar # PATH_INFO is 'some/path' |
| 312 |
|
| 313 |
Calling: |
| 314 |
|
| 315 |
$self->path_link('/new/path'); |
| 316 |
|
| 317 |
Will produce the URL: |
| 318 |
|
| 319 |
/cgi-bin/app.cgi/new/path?foo=bar |
| 320 |
|
| 321 |
If you want to remove "PATH_INFO" entirely, call one of the following: |
| 322 |
|
| 323 |
$self->path_link; |
| 324 |
$self->path_link(undef, 'param1' => 'val1', 'param2 => 'val2' ...); |
| 325 |
$self->path_link('', 'param1' => 'val1', 'param2 => 'val2' ...); |
| 326 |
|
| 327 |
If you want to keep the existing "PATH_INFO" that was passed to the |
| 328 |
current application, use self_link instead. |
| 329 |
|
| 330 |
RUN MODES |
| 331 |
The link_tampered Run Mode |
| 332 |
Your application is redirected to this run mode when it has been |
| 333 |
detected that the user has tampered with the link. You can change the |
| 334 |
name of this run mode by changing the value of the |
| 335 |
"link_tampered_runmode" param to "link_integrity_config". |
| 336 |
|
| 337 |
CGI::Application::Plugin::LinkIntegrity provides a default |
| 338 |
"link_tampered" run mode, which just displays a page with some stern |
| 339 |
warning text. |
| 340 |
|
| 341 |
You can define your own as follows: |
| 342 |
|
| 343 |
sub link_tampered { |
| 344 |
my $self = shift; |
| 345 |
my $template = $self->load_template('stern_talking_to'); |
| 346 |
return $template->output; |
| 347 |
} |
| 348 |
|
| 349 |
HOOKS |
| 350 |
When a link is followed that doesn't match the checksum, the |
| 351 |
"invalid_checksum" hook is called. You can add a callback to this hook |
| 352 |
to do some cleanup such as deleting the user's session. For instance: |
| 353 |
|
| 354 |
sub setup { |
| 355 |
my $self = shift; |
| 356 |
$self->add_callback('invalid_checksum' => \&bad_user); |
| 357 |
} |
| 358 |
|
| 359 |
sub bad_user { |
| 360 |
my $self = shift; |
| 361 |
|
| 362 |
# The user has been messing with the URLs, possibly trying to |
| 363 |
# break into the system. We don't tolerate this behaviour. |
| 364 |
# So we delete the user's session: |
| 365 |
|
| 366 |
$self->session->delete; |
| 367 |
} |
| 368 |
|
| 369 |
AUTHOR |
| 370 |
Michael Graham, "<[email protected]>" |
| 371 |
|
| 372 |
ACKNOWLEDGEMENTS |
| 373 |
This module was based on the checksum feature originally built into |
| 374 |
Richard Dice's CGI::Application::Framework. |
| 375 |
|
| 376 |
BUGS |
| 377 |
Please report any bugs or feature requests to |
| 378 |
"[email protected]", or through the |
| 379 |
web interface at <http://rt.cpan.org>. I will be notified, and then |
| 380 |
you'll automatically be notified of progress on your bug as I make |
| 381 |
changes. |
| 382 |
|
| 383 |
COPYRIGHT & LICENSE |
| 384 |
Copyright 2005 Michael Graham, All Rights Reserved. |
| 385 |
|
| 386 |
This program is free software; you can redistribute it and/or modify it |
| 387 |
under the same terms as Perl itself. |
| 388 |
|