.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Taint 3pm"
.TH Taint 3pm "2004-08-10" "perl v5.14.2" "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"
Test::Taint \- Tools to test taintedness
.SH "VERSION"
.IX Header "VERSION"
Version 1.04
.PP
.Vb 1
\&    $Header: /home/cvs/test\-taint/Taint.pm,v 1.16 2004/08/10 03:06:57 andy Exp $
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\&    taint_checking_ok();        # We have to have taint checking on
\&    my $id = "deadbeef";        # Dummy session ID
\&    taint( $id );               # Simulate it coming in from the web
\&    tainted_ok( $id );
\&    $id = validate_id( $id );   # Your routine to check the $id
\&    untainted_ok( $id );        # Did it come back clean?
\&    ok( defined $id );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Tainted data is data that comes from an unsafe source, such as the
command line, or, in the case of web apps, any \s-1GET\s0 or \s-1POST\s0 transactions.
Read the perlsec man page for details on why tainted data is bad,
and how to untaint the data.
.PP
When you're writing unit tests for code that deals with tainted data,
you'll want to have a way to provide tainted data for your routines to
handle, and easy ways to check and report on the taintedness of your data,
in standard Test::More style.
.ie n .SH """Test::More""\-style Functions"
.el .SH "\f(CWTest::More\fP\-style Functions"
.IX Header "Test::More-style Functions"
All the \f(CW\*(C`xxx_ok()\*(C'\fR functions work like standard \f(CW\*(C`Test::More\*(C'\fR\-style
functions, where the last parm is an optional message, it outputs ok or
not ok, and returns a boolean telling if the test passed.
.SS "taint_checking_ok( [$message] )"
.IX Subsection "taint_checking_ok( [$message] )"
Test::More\-style test that taint checking is on.  This should probably
be the first thing in any \fI*.t\fR file that deals with taintedness.
.ie n .SS "tainted_ok( $var [, $message ] )"
.el .SS "tainted_ok( \f(CW$var\fP [, \f(CW$message\fP ] )"
.IX Subsection "tainted_ok( $var [, $message ] )"
Checks that \fI\f(CI$var\fI\fR is tainted.
.PP
.Vb 1
\&    tainted_ok( $ENV{FOO} );
.Ve
.ie n .SS "untainted_ok( $var [, $message ] )"
.el .SS "untainted_ok( \f(CW$var\fP [, \f(CW$message\fP ] )"
.IX Subsection "untainted_ok( $var [, $message ] )"
Checks that \fI\f(CI$var\fI\fR is not tainted.
.PP
.Vb 2
\&    my $foo = my_validate( $ENV{FOO} );
\&    untainted_ok( $foo );
.Ve
.ie n .SS "tainted_ok_deeply( $var [, $message ] )"
.el .SS "tainted_ok_deeply( \f(CW$var\fP [, \f(CW$message\fP ] )"
.IX Subsection "tainted_ok_deeply( $var [, $message ] )"
Checks that \fI\f(CI$var\fI\fR is tainted.  If \fI\f(CI$var\fI\fR
is a reference, it recursively checks every
variable to make sure they are all tainted.
.PP
.Vb 1
\&    tainted_ok_deeply( \e%ENV );
.Ve
.ie n .SS "untainted_ok_deeply( $var [, $message ] )"
.el .SS "untainted_ok_deeply( \f(CW$var\fP [, \f(CW$message\fP ] )"
.IX Subsection "untainted_ok_deeply( $var [, $message ] )"
Checks that \fI\f(CI$var\fI\fR is not tainted.  If \fI\f(CI$var\fI\fR
is a reference, it recursively checks every
variable to make sure they are all not tainted.
.PP
.Vb 2
\&    my %env = my_validate( \e%ENV );
\&    untainted_ok_deeply( \e%env );
.Ve
.SH "Helper Functions"
.IX Header "Helper Functions"
These are all helper functions.  Most are wrapped by an \f(CW\*(C`xxx_ok()\*(C'\fR
counterpart, except for \f(CW\*(C`taint\*(C'\fR which actually does something, instead
of just reporting it.
.SS "\fItaint_checking()\fP"
.IX Subsection "taint_checking()"
Returns true if taint checking is enabled via the \-T flag.
.ie n .SS "tainted( \fI\fP\fI$var\fP\fI\fP )"
.el .SS "tainted( \fI\fP\f(CI$var\fP\fI\fP )"
.IX Subsection "tainted( $var )"
Returns boolean saying if \f(CW$var\fR is tainted.
.ie n .SS "tainted_deeply( \fI\fP\fI$var\fP\fI\fP )"
.el .SS "tainted_deeply( \fI\fP\f(CI$var\fP\fI\fP )"
.IX Subsection "tainted_deeply( $var )"
Returns boolean saying if \f(CW$var\fR is tainted.  If
\&\f(CW$var\fR is a reference it recursively checks every
variable to make sure they are all tainted.
.ie n .SS "taint( @list )"
.el .SS "taint( \f(CW@list\fP )"
.IX Subsection "taint( @list )"
Marks each (apparently) taintable argument in \fI\f(CI@list\fI\fR as being tainted.
.PP
References can be tainted like any other scalar, but it doesn't make
sense to, so they will \fBnot\fR be tainted by this function.
.PP
Some \f(CW\*(C`tie\*(C'\fRd and magical variables may fail to be tainted by this routine,
try as it may.)
.ie n .SS "taint_deeply( @list )"
.el .SS "taint_deeply( \f(CW@list\fP )"
.IX Subsection "taint_deeply( @list )"
Similar to \f(CW\*(C`taint\*(C'\fR, except that if any elements in \fI\f(CI@list\fI\fR are
references, it walks deeply into the data structure and marks each
taintable argument as being tainted.
.PP
If any variables are \f(CW\*(C`tie\*(C'\fRd this will taint all the scalars within
the tied object.
.SH "AUTHOR"
.IX Header "AUTHOR"
Written by Andy Lester, \f(CW\*(C`<andy@petdance.com>\*(C'\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2004, Andy Lester, All Rights Reserved.
.PP
You may use, modify, and distribute this package under the
same terms as Perl itself.