1CGI::Untaint(3)       User Contributed Perl Documentation      CGI::Untaint(3)
2
3
4

NAME

6       CGI::Untaint - process CGI input parameters
7

SYNOPSIS

9         use CGI::Untaint;
10
11         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
17         my $name     = $handler->extract(-as_printable => 'name');
18         my $homepage = $handler->extract(-as_url => 'homepage');
19
20         my $postcode = $handler->extract(-as_postcode => 'address6');
21
22         # Create your own handler...
23
24         package MyRecipes::CGI::Untaint::legal_age;
25         use base 'CGI::Untaint::integer';
26         sub is_valid {
27           shift->value > 21;
28         }
29
30         package main;
31         my $age = $handler->extract(-as_legal_age => 'age');
32

DESCRIPTION

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
41       This module provides a simple, convenient, abstracted and extensible
42       manner for validating and untainting the input from web forms.
43
44       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,
46       performing whatever validations you choose. The resulting variable is
47       guaranteed not only to be valid, but also untainted.
48

CONSTRUCTOR

50   new
51         my $handler  = CGI::Untaint->new( $q->Vars );
52         my $handler2 = CGI::Untaint->new({
53               INCLUDE_PATH => 'My::Untaint',
54         }, $apr->parms);
55
56       The simplest way to contruct an input handler is to pass a hash of
57       parameters (usually $q->Vars) to new(). Each parameter will then be
58       able to be extracted later by calling an extract() method on it.
59
60       However, you may also pass a leading reference to a hash of
61       configuration variables.
62
63       Currently the only such variable supported is 'INCLUDE_PATH', which
64       allows you to specify a local path in which to find extraction
65       handlers.  See "LOCAL EXTRACTION HANDLERS".
66

METHODS

68   extract
69         my $homepage = $handler->extract(-as_url => 'homepage');
70         my $state = $handler->extract(-as_us_state => 'address4');
71         my $state = $handler->extract(-as_like_us_state => 'address4');
72
73       Once you have constructed your Input Handler, you call the 'extract'
74       method on each piece of data with which you are concerned.
75
76       The takes an -as_whatever flag to state what type of data you require.
77       This will check that the input value correctly matches the required
78       specification, and return an untainted value. It will then call the
79       is_valid() method, where applicable, to ensure that this doesn't just
80       _look_ like a valid value, but actually is one.
81
82       If you want to skip this stage, then you can call -as_like_whatever
83       which will perform the untainting but not the validation.
84
85   error
86         my $error = $handler->error;
87
88       If the validation failed, this will return the reason why.
89

LOCAL EXTRACTION HANDLERS

91       As well as as the handlers supplied with this module for extracting
92       data, you may also create your own. In general these should inherit
93       from 'CGI::Untaint::object', and must provide an '_untaint_re' method
94       which returns a compiled regular expression, suitably bracketed such
95       that $1 will return the untainted value required.
96
97       e.g. if you often extract single digit variables, you could create
98
99         package My::Untaint::digit;
100
101         use base 'CGI::Untaint::object';
102
103         sub _untaint_re { qr/^(\d)$/ }
104
105         1;
106
107       You should specify the path 'My::Untaint' in the INCLUDE_PATH
108       configuration option.  (See new() above.)
109
110       When extract() is called CGI::Untaint will also check to see if you
111       have an is_valid() method also, and if so will run this against the
112       value extracted from the regular expression (available as
113       $self->value).
114
115       If this returns a true value, then the extracted value will be
116       returned, otherwise we return undef.
117
118       is_valid() can also modify the value being returned, by assigning
119         $self->value($new_value)
120
121       e.g. in the above example, if you sometimes need to ensure that the
122       digit extracted is prime, you would supply:
123
124         sub is_valid { (1 x shift->value) !~ /^1?$|^(11+?)\1+$/ };
125
126       Now, when users call extract(), it will also check that the value is
127       valid(), i.e. prime:
128
129         my $number = $handler->extract(-as_digit => 'value');
130
131       A user wishing to skip the validation, but still ensure untainting can
132       call
133
134         my $number = $handler->extract(-as_like_digit => 'value');
135
136   Test::CGI::Untaint
137       If you create your own local handlers, then you may wish to explore
138       Test::CGI::Untaint, available from the CPAN. This makes it very easy to
139       write tests for your handler. (Thanks to Profero Ltd.)
140

AVAILABLE HANDLERS

142       This package comes with the following simplistic handlers:
143
144         printable  - a printable string
145         integer    - an integer
146         hex        - a hexadecimal number (as a string)
147
148       To really make this work for you you either need to write, or download
149       from CPAN, other handlers. Some of the handlers available on CPAN
150       include:
151
152         asin         - an Amazon ID
153         boolean      - boolean value
154         country      - a country code or name
155         creditcard   - a credit card number
156         date         - a date (into a Date::Simple)
157         datetime     - a date (into a DateTime)
158         email        - an email address
159         hostname     - a DNS host name
160         html         - sanitized HTML
161         ipaddress    - an IP address
162         isbn         - an ISBN
163         uk_postcode  - a UK Postcode
164         url          - a URL
165         zipcode      - a US zipcode
166

BUGS

168       None known yet.
169

SEE ALSO

171       CGI. perlsec. Test::CGI::Untaint.
172

AUTHOR

174       Tony Bowden
175

BUGS and QUERIES

177       Please direct all correspondence regarding this module to:
178         bug-CGI-Untaint@rt.cpan.org
179
181       Copyright (C) 2001-2005 Tony Bowden. All rights reserved.
182
183       This module is free software; you can redistribute it and/or modify it
184       under the same terms as Perl itself.
185
186
187
188perl v5.28.1                      2005-09-20                   CGI::Untaint(3)
Impressum