Debian Codegraph @

README

raw ◀ ▶
1 Debian patch touch this file
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