.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CGI::Untaint 3pm"
.TH CGI::Untaint 3pm "2022-06-10" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CGI::Untaint \- process CGI input parameters
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use CGI::Untaint;
\&
\&  my $q = new CGI;
\&  my $handler = CGI::Untaint\->new( $q\->Vars );
\&  my $handler2 = CGI::Untaint\->new({
\&        INCLUDE_PATH => \*(AqMy::Untaint\*(Aq,
\&  }, $apr\->parms);
\&
\&  my $name     = $handler\->extract(\-as_printable => \*(Aqname\*(Aq);
\&  my $homepage = $handler\->extract(\-as_url => \*(Aqhomepage\*(Aq);
\&
\&  my $postcode = $handler\->extract(\-as_postcode => \*(Aqaddress6\*(Aq);
\&
\&  # Create your own handler...
\&
\&  package MyRecipes::CGI::Untaint::legal_age;
\&  use base \*(AqCGI::Untaint::integer\*(Aq;
\&  sub is_valid { 
\&    shift\->value > 21;
\&  }
\&
\&  package main;
\&  my $age = $handler\->extract(\-as_legal_age => \*(Aqage\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Dealing with large web based applications with multiple forms is a
minefield. It's often hard enough to ensure you validate all your
input at all, without having to worry about doing it in a consistent
manner. If any of the validation rules change, you often have to alter
them in many different places. And, if you want to operate taint-safe,
then you're just adding even more headaches.
.PP
This module provides a simple, convenient, abstracted and extensible
manner for validating and untainting the input from web forms.
.PP
You simply create a handler with a hash of your parameters (usually
\&\f(CW$q\fR\->Vars), and then iterate over the fields you wish to extract,
performing whatever validations you choose. The resulting variable is
guaranteed not only to be valid, but also untainted.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new"
.IX Subsection "new"
.Vb 4
\&  my $handler  = CGI::Untaint\->new( $q\->Vars );
\&  my $handler2 = CGI::Untaint\->new({
\&        INCLUDE_PATH => \*(AqMy::Untaint\*(Aq,
\&  }, $apr\->parms);
.Ve
.PP
The simplest way to contruct an input handler is to pass a hash of
parameters (usually \f(CW$q\fR\->Vars) to \fBnew()\fR. Each parameter will then be able
to be extracted later by calling an \fBextract()\fR method on it.
.PP
However, you may also pass a leading reference to a hash of configuration
variables.
.PP
Currently the only such variable supported is '\s-1INCLUDE_PATH\s0', which
allows you to specify a local path in which to find extraction handlers.
See \*(L"\s-1LOCAL EXTRACTION HANDLERS\*(R"\s0.
.SH "METHODS"
.IX Header "METHODS"
.SS "extract"
.IX Subsection "extract"
.Vb 3
\&  my $homepage = $handler\->extract(\-as_url => \*(Aqhomepage\*(Aq);
\&  my $state = $handler\->extract(\-as_us_state => \*(Aqaddress4\*(Aq);
\&  my $state = $handler\->extract(\-as_like_us_state => \*(Aqaddress4\*(Aq);
.Ve
.PP
Once you have constructed your Input Handler, you call the 'extract'
method on each piece of data with which you are concerned.
.PP
The takes an \-as_whatever flag to state what type of data you
require. This will check that the input value correctly matches the
required specification, and return an untainted value. It will then call
the \fBis_valid()\fR method, where applicable, to ensure that this doesn't
just _look_ like a valid value, but actually is one.
.PP
If you want to skip this stage, then you can call \-as_like_whatever
which will perform the untainting but not the validation.
.SS "error"
.IX Subsection "error"
.Vb 1
\&  my $error = $handler\->error;
.Ve
.PP
If the validation failed, this will return the reason why.
.SH "LOCAL EXTRACTION HANDLERS"
.IX Header "LOCAL EXTRACTION HANDLERS"
As well as as the handlers supplied with this module for extracting
data, you may also create your own. In general these should inherit from
\&'CGI::Untaint::object', and must provide an '_untaint_re' method which
returns a compiled regular expression, suitably bracketed such that \f(CW$1\fR
will return the untainted value required.
.PP
e.g. if you often extract single digit variables, you could create
.PP
.Vb 1
\&  package My::Untaint::digit;
\&
\&  use base \*(AqCGI::Untaint::object\*(Aq;
\&
\&  sub _untaint_re { qr/^(\ed)$/ }
\&
\&  1;
.Ve
.PP
You should specify the path 'My::Untaint' in the \s-1INCLUDE_PATH\s0
configuration option.  (See \fBnew()\fR above.)
.PP
When \fBextract()\fR is called CGI::Untaint will also check to see if you have
an \fBis_valid()\fR method also, and if so will run this against the value
extracted from the regular expression (available as \f(CW$self\fR\->value).
.PP
If this returns a true value, then the extracted value will be returned,
otherwise we return undef.
.PP
\&\fBis_valid()\fR can also modify the value being returned, by assigning 
  \f(CW$self\fR\->value($new_value)
.PP
e.g. in the above example, if you sometimes need to ensure that the
digit extracted is prime, you would supply:
.PP
.Vb 1
\&  sub is_valid { (1 x shift\->value) !~ /^1?$|^(11+?)\e1+$/ };
.Ve
.PP
Now, when users call \fBextract()\fR, it will also check that the value
is \fBvalid()\fR, i.e. prime:
.PP
.Vb 1
\&  my $number = $handler\->extract(\-as_digit => \*(Aqvalue\*(Aq);
.Ve
.PP
A user wishing to skip the validation, but still ensure untainting can
call
.PP
.Vb 1
\&  my $number = $handler\->extract(\-as_like_digit => \*(Aqvalue\*(Aq);
.Ve
.SS "Test::CGI::Untaint"
.IX Subsection "Test::CGI::Untaint"
If you create your own local handlers, then you may wish to explore
Test::CGI::Untaint, available from the \s-1CPAN.\s0 This makes it very easy
to write tests for your handler. (Thanks to Profero Ltd.)
.SH "AVAILABLE HANDLERS"
.IX Header "AVAILABLE HANDLERS"
This package comes with the following simplistic handlers:
.PP
.Vb 3
\&  printable  \- a printable string
\&  integer    \- an integer
\&  hex        \- a hexadecimal number (as a string)
.Ve
.PP
To really make this work for you you either need to write, or download
from \s-1CPAN,\s0 other handlers. Some of the handlers available on \s-1CPAN\s0 include:
.PP
.Vb 10
\&  asin         \- an Amazon ID
\&  boolean      \- boolean value
\&  country      \- a country code or name
\&  creditcard   \- a credit card number
\&  date         \- a date (into a Date::Simple)
\&  datetime     \- a date (into a DateTime)
\&  email        \- an email address
\&  hostname     \- a DNS host name
\&  html         \- sanitized HTML
\&  ipaddress    \- an IP address
\&  isbn         \- an ISBN
\&  uk_postcode  \- a UK Postcode
\&  url          \- a URL
\&  zipcode      \- a US zipcode
.Ve
.SH "BUGS"
.IX Header "BUGS"
None known yet.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1CGI\s0. perlsec. Test::CGI::Untaint.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tony Bowden
.SH "BUGS and QUERIES"
.IX Header "BUGS and QUERIES"
Please direct all correspondence regarding this module to:
  bug\-CGI\-Untaint@rt.cpan.org
.SH "COPYRIGHT and LICENSE"
.IX Header "COPYRIGHT and LICENSE"
Copyright (C) 2001\-2005 Tony Bowden. All rights reserved.
.PP
This module is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.