1CGI::Untaint(3) User Contributed Perl Documentation CGI::Untaint(3)
2
6 CGI::Untaint - process CGI input parameters
7
9 use CGI::Untaint;
10 my $q = new CGI;
12 my $handler = CGI::Untaint->new( $q->Vars );
13 my $handler2 = CGI::Untaint->new({
14 INCLUDE_PATH => 'My::Untaint',
15 }, $apr->parms);
16 my $name = $handler->extract(-as_printable => 'name');
18 my $homepage = $handler->extract(-as_url => 'homepage');
19 my $postcode = $handler->extract(-as_postcode => 'address6');
21 # Create your own handler...
23 package MyRecipes::CGI::Untaint::legal_age;
25 use base 'CGI::Untaint::integer';
26 sub is_valid {
27 shift->value > 21;
28 }
29 package main;
31 my $age = $handler->extract(-as_legal_age => 'age');
32
34 Dealing with large web based applications with multiple forms is a
35 minefield. It's often hard enough to ensure you validate all your input
36 at all, without having to worry about doing it in a consistent manner.
37 If any of the validation rules change, you often have to alter them in
38 many different places. And, if you want to operate taint-safe, then
39 you're just adding even more headaches.
40 This module provides a simple, convenient, abstracted and extensible
42 manner for validating and untainting the input from web forms.
43 You simply create a handler with a hash of your parameters (usually
45 $q->Vars), and then iterate over the fields you wish to extract, per‐
46 forming whatever validations you choose. The resulting variable is
47 guaranteed not only to be valid, but also untainted.
48
50 new
51 my $handler = CGI::Untaint->new( $q->Vars );
53 my $handler2 = CGI::Untaint->new({
54 INCLUDE_PATH => 'My::Untaint',
55 }, $apr->parms);
56 The simplest way to contruct an input handler is to pass a hash of
58 parameters (usually $q->Vars) to new(). Each parameter will then be
59 able to be extracted later by calling an extract() method on it.
60 However, you may also pass a leading reference to a hash of configura‐
62 tion variables.
63 Currently the only such variable supported is 'INCLUDE_PATH', which
65 allows you to specify a local path in which to find extraction han‐
66 dlers. See "LOCAL EXTRACTION HANDLERS".
67
69 extract
70 my $homepage = $handler->extract(-as_url => 'homepage');
72 my $state = $handler->extract(-as_us_state => 'address4');
73 my $state = $handler->extract(-as_like_us_state => 'address4');
74 Once you have constructed your Input Handler, you call the 'extract'
76 method on each piece of data with which you are concerned.
77 The takes an -as_whatever flag to state what type of data you require.
79 This will check that the input value correctly matches the required
80 specification, and return an untainted value. It will then call the
81 is_valid() method, where applicable, to ensure that this doesn't just
82 _look_ like a valid value, but actually is one.
83 If you want to skip this stage, then you can call -as_like_whatever
85 which will perform the untainting but not the validation.
86 error
88 my $error = $handler->error;
90 If the validation failed, this will return the reason why.
92
94 As well as as the handlers supplied with this module for extracting
95 data, you may also create your own. In general these should inherit
96 from 'CGI::Untaint::object', and must provide an '_untaint_re' method
97 which returns a compiled regular expression, suitably bracketed such
98 that $1 will return the untainted value required.
99 e.g. if you often extract single digit variables, you could create
101 package My::Untaint::digit;
103 use base 'CGI::Untaint::object';
105 sub _untaint_re { qr/^(\d)$/ }
107 1;
109 You should specify the path 'My::Untaint' in the INCLUDE_PATH configu‐
111 ration option. (See new() above.)
112 When extract() is called CGI::Untaint will also check to see if you
114 have an is_valid() method also, and if so will run this against the
115 value extracted from the regular expression (available as
116 $self->value).
117 If this returns a true value, then the extracted value will be
119 returned, otherwise we return undef.
120 is_valid() can also modify the value being returned, by assigning
122 $self->value($new_value)
123 e.g. in the above example, if you sometimes need to ensure that the
125 digit extracted is prime, you would supply:
126 sub is_valid { (1 x shift->value) !~ /^1?$⎪^(11+?)\1+$/ };
128 Now, when users call extract(), it will also check that the value is
130 valid(), i.e. prime:
131 my $number = $handler->extract(-as_digit => 'value');
133 A user wishing to skip the validation, but still ensure untainting can
135 call
136 my $number = $handler->extract(-as_like_digit => 'value');
138 Test::CGI::Untaint
140 If you create your own local handlers, then you may wish to explore
142 Test::CGI::Untaint, available from the CPAN. This makes it very easy to
143 write tests for your handler. (Thanks to Profero Ltd.)
144
146 This package comes with the following simplistic handlers:
147 printable - a printable string
149 integer - an integer
150 hex - a hexadecimal number (as a string)
151 To really make this work for you you either need to write, or download
153 from CPAN, other handlers. Some of the handlers available on CPAN
154 include:
155 asin - an Amazon ID
157 boolean - boolean value
158 country - a country code or name
159 creditcard - a credit card number
160 date - a date (into a Date::Simple)
161 datetime - a date (into a DateTime)
162 email - an email address
163 hostname - a DNS host name
164 html - sanitized HTML
165 ipaddress - an IP address
166 isbn - an ISBN
167 uk_postcode - a UK Postcode
168 url - a URL
169 zipcode - a US zipcode
170
172 None known yet.
173
175 CGI. perlsec. Test::CGI::Untaint.
176
178 Tony Bowden
179
181 Please direct all correspondence regarding this module to:
182 bug-CGI-Untaint@rt.cpan.org
183
185 Copyright (C) 2001-2005 Tony Bowden. All rights reserved.
186 This module is free software; you can redistribute it and/or modify it
188 under the same terms as Perl itself.
189perl v5.8.8 2005-09-20 CGI::Untaint(3)