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