.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 "Taint::Runtime 3pm"
.TH Taint::Runtime 3pm "2018-11-01" "perl v5.28.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"
Taint::Runtime \- Runtime enable taint checking
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  ### sample "enable" usage
\&
\&  #!/usr/bin/perl \-w
\&  use Taint::Runtime qw(enable taint_env);
\&  taint_env();
\&  # having the keyword enable in the import list starts taint
\&
\&
\&  ### sample $TAINT usage
\&
\&  #!/usr/bin/perl \-w
\&  use Taint::Runtime qw($TAINT taint_env);
\&  $TAINT = 1;
\&  taint_env();
\&
\&  # taint is now enabled
\&
\&  if (1) {
\&    local $TAINT = 0;
\&
\&    # do something we trust
\&  }
\&
\&  # back to an untrustwory area
\&
\&
\&
\&  ### sample functional usage
\&
\&  #!/usr/bin/perl \-w
\&  use strict;
\&  use Taint::Runtime qw(taint_start is_tainted taint_env
\&                        taint untaint
\&                        taint_enabled);
\&
\&  ### other operations here
\&
\&  taint_start(); # taint should become active
\&  taint_env(); # %ENV was previously untainted
\&
\&  print taint_enabled() ? "enabled\en" : "not enabled\en";
\&
\&  my $var = taint("some string");
\&
\&  print is_tainted($var) ? "tainted\en" : "not tainted\en";
\&
\&  $var = untaint($var);
\&  # OR
\&  untaint \e$var;
\&
\&  print is_tainted($var) ? "tainted\en" : "not tainted\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
First \- you probably shouldn't use this module to control taint.
You should probably use the \-T switch on the commandline instead.
There are a somewhat limited number of legitimate use cases where
you should use this module instead of the \-T switch.  Unless you
have a specific and good reason for not using the \-T option, you
should use the \-T option.
.PP
Taint is a good thing.  However, few people (that I work with or talk
to or discuss items with) use taint even though they should.  The goal of
this module isn't to use taint less, but to actually encourage its use
more.  This module aims to make using taint as painless as possible (This
can be an argument against it \- often implementation of security implies
pain \- so taking away pain might lessen security \- sort of).
.PP
In general \- the more secure your script needs to be \- the earlier
on in your program that tainting should be enabled.  For most setuid scripts,
you should enable taint by using the \-T switch.  Without doing so you allow
for a non-root user to override \f(CW@INC\fR which allows for them to put their
own module in the place of trusted modules.  This is bad.  This is very bad.
Use the \-T switch.
.PP
There are some common places where this module may be useful, and where
most people don't use it.  One such place is in a web server.  The \-T switch
removes \s-1PERL5LIB\s0 and \s-1PERLLIB\s0 and '.' from \f(CW@INC\fR (or remove them before
they can be added).  This makes sense under setuid.  The use of the \-T switch
in a \s-1CGI\s0 environment may cause a bit of a headache.  For new development,
\&\s-1CGI\s0 scripts it may be possible to use the \-T switch and for mod_perl environments
there is the PerlTaint variable.  Both of these methods will enable taint
and from that point on development should be done with taint.
.PP
However, many (possibly most) perl web server implentations add their
own paths to the \s-1PERL5LIB.\s0  All \s-1CGI\s0's and mod_perl scripts can then have access.
Using the \-T switch throws a wrench into the works as suddenly \s-1PERL5LIB\s0
disappears (mod_perl can easily have the extra directories added again
using <perl>push \f(CW@INC\fR, '/our/lib/dir';</perl>).  The company I work for
has 200 plus user visible scripts mixed with some mod_perl.  Currently
none of the scripts use taint.  We would like for them all to, but it
is not feasible to make the change all at once.  Taint::Runtime allows for moving legacy
scripts over one at a time.
.PP
Again, if you are using setuid \- don't use this script.
.PP
If you are not using setuid and have reasons not to use the \-T and are
using this module, make sure that taint is enabled before processing
any user data.  Also remember that \s-1BECAUSE THE\s0 \-T \s-1SWITCH WAS NOT USED\s0
\&\f(CW%ENV\fR \s-1IS INITIALLY NOT MARKED AS TAINTED.\s0  Call \fBtaint_env()\fR to mark
it as tainted (especially important in \s-1CGI\s0 scripts which all read from
\&\f(CW$ENV\fR{'\s-1QUERY_STRING\s0'}).
.PP
If you are not using the \-T switch, you most likely should use the
following at the very top of your script:
.PP
.Vb 1
\&  #!/usr/bin/perl \-w
\&
\&  use strict;
\&  use Taint::Runtime qw(enable taint_env);
\&  taint_env();
.Ve
.PP
Though this module allows for you to turn taint off \- you probably shouldn't.
This module is more for you to turn taint on \- and once it is on it probably
ought to stay on.
.SH "NON-EXPORTABLE XS FUNCTIONS"
.IX Header "NON-EXPORTABLE XS FUNCTIONS"
The following very basic functions provide the base functionality.
.IP "\fB_taint_start()\fR" 4
.IX Item "_taint_start()"
Sets PL_tainting
.IP "\fB_taint_stop()\fR" 4
.IX Item "_taint_stop()"
Sets PL_tainting
.IP "\fB_taint_enabled()\fR" 4
.IX Item "_taint_enabled()"
View of PL_tainting
.IP "\fB_tainted()\fR" 4
.IX Item "_tainted()"
Returns a zero length tainted string.
.ie n .SH "$TAINT VARIABLE"
.el .SH "\f(CW$TAINT\fP VARIABLE"
.IX Header "$TAINT VARIABLE"
The variable \f(CW$TAINT\fR is tied to the current state of taint.
If \f(CW$TAINT\fR is set to 0 taint mode is off.  When it is set to
1 taint mode is enabled.
.PP
.Vb 2
\&  if (1) {
\&    local $TAINT = 1;
\&
\&    # taint is enabled
\&  }
.Ve
.SH "EXPORT FUNCTIONS"
.IX Header "EXPORT FUNCTIONS"
.IP "enable/disable" 4
.IX Item "enable/disable"
Not really functions.  If these keywords are in
the import list, taint will be either enabled
or disabled.
.IP "taint_start" 4
.IX Item "taint_start"
Start taint mode.  \f(CW$TAINT\fR will equal 1.
.IP "taint_stop" 4
.IX Item "taint_stop"
Stop taint mode.  \f(CW$TAINT\fR will equal 0.
.IP "taint_env" 4
.IX Item "taint_env"
Convenience function that taints the keys and values of \f(CW%ENV\fR.  If
the \-T switch was not used \- you most likely should call
this as soon as taint mode is enabled.
.IP "taint" 4
.IX Item "taint"
Taints the passed in variable.  Only works on writeable scalar values.
If a scalar ref is passed in \- it is modified.  If a scalar is passed in
(non ref) it is copied, modified and returned.  If a value was undefined,
it becomes a zero length defined and tainted string.
.Sp
.Vb 1
\&  taint(\e$var_to_be_tainted);
\&
\&  my $tainted_copy = taint($some_var);
.Ve
.Sp
For a stronger taint, see the Taint module by Dan Sulgalski which is
capable of tainting most types of data.
.IP "untaint" 4
.IX Item "untaint"
Untaints the passed in variable.  Only works on writeable scalar values.
If a scalar ref is passed in \- it is modified.  If a scalar is passed in
(non ref) it is copied, modified and returned.  If a value was undefined
it becomes an untainted undefined value.
.Sp
Note:  Just because the variable is untainted, doesn't mean that it
is safe.  You really should use CGI::Ex::Validate, or Data::FormValidator
or any of the Untaint:: modules.  If you are doing your own validation, and
once you have put the user data through very strict checks, then you
can use untaint.
.Sp
.Vb 3
\&  if ($var_to_be_untainted =~ /^[\ew\e.\e\-]{0,100}$/) {
\&    untaint(\e$var_to_be_untainted);
\&  }
\&
\&  my $untainted_copy = untaint($some_var);
.Ve
.IP "taint_enabled" 4
.IX Item "taint_enabled"
Boolean \- Is taint on.
.IP "tainted" 4
.IX Item "tainted"
Returns a zero length tainted string.
.IP "is_tainted" 4
.IX Item "is_tainted"
Boolean \- True if the passed value is tainted.
.IP "taint_deeply" 4
.IX Item "taint_deeply"
Convenience function that attempts to deply recurse a
structure and mark it as tainted.  Takes a hashref, arrayref,
scalar ref, or scalar and recursively untaints the structure.
.Sp
For a stronger taint, see the Taint module by Dan Sulgalski which is
capable of tainting most types of data.
.SH "TURNING TAINT ON"
.IX Header "TURNING TAINT ON"
(Be sure to call \fBtaint_env()\fR after turning taint on the first time)
.PP
.Vb 1
\&  #!/usr/bin/perl \-T
\&
\&
\&  use Taint::Runtime qw(enable);
\&  # this does not create a function called enable \- just starts taint
\&
\&  use Taint::Runtime qw($TAINT);
\&  $TAINT = 1;
\&
\&
\&  use Taint::Runtime qw(taint_start);
\&  taint_start;
.Ve
.SH "TURNING TAINT OFF"
.IX Header "TURNING TAINT OFF"
.Vb 2
\&  use Taint::Runtime qw(disable);
\&  # this does not create a function called disable \- just stops taint
\&
\&
\&  use Taint::Runtime qw($TAINT);
\&  $TAINT = 0;
\&
\&
\&  use Taint::Runtime qw(taint_stop);
\&  taint_stop;
.Ve
.SH "CREDITS"
.IX Header "CREDITS"
C code was provided by \*(L"hv\*(R" on perlmonks.  This module wouldn't
really be possible without insight into the internals that \*(L"hv\*(R"
provided.  His post with the code was shown in this node on
perlmonks:
.PP
.Vb 1
\&  http://perlmonks.org/?node_id=434086
.Ve
.PP
The basic premise in that node was the following code:
.PP
.Vb 2
\&  use Inline C => \*(Aqvoid _start_taint() { PL_tainting = 1; }\*(Aq;
\&  use Inline C => \*(AqSV* _tainted() { PL_tainted = 1; return newSVpvn("", 0); }\*(Aq;
.Ve
.PP
In this module, these two lines have instead been turned into
\&\s-1XS\s0 for runtime speed (and so you won't need Inline and Parse::RecDescent).
.PP
Note: even though \*(L"hv\*(R" provided the base code example, that doesn't mean that he
necessarily endorses the idea.  If there are disagreements, quirks, annoyances
or any other negative side effects with this module \- blame me \- not \*(L"hv.\*(R"
.SH "THANKS"
.IX Header "THANKS"
Thanks to Alexey A. Kiritchun for pointing out untaint failure on multiline strings.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Seamons (2005)
.PP
C stub functions by \*(L"hv\*(R" on perlmonks.org
.SH "LICENSE"
.IX Header "LICENSE"
This module may be used and distributed under the same
terms as Perl itself.