NAME

       Taint::Util - Test for and flip the taint flag without regex matches or "eval"

SYNOPSIS

           #!/usr/bin/env perl -T
           use Taint::Util;

           # eek!
           untaint $ENV{PATH};

           # $sv now tainted under taint mode (-T)
           taint(my $sv = "hlagh");

           # Untaint $sv again
           untaint $sv if tainted $sv;

DESCRIPTION

       Wraps perl's internal routines for checking and setting the taint flag and thus does not
       rely on regular expressions for untainting or odd tricks involving "eval" and "kill" for
       checking whether data is tainted, instead it checks and flips a flag on the scalar in-
       place.

FUNCTIONS

   tainted
       Returns a boolean indicating whether a scalar is tainted. Always false when not under
       taint mode.

   taint & untaint
       Taints or untaints given values, arrays will be flattened and their elements tainted,
       likewise with the values of hashes (keys can't be tainted, see perlsec). Returns no value
       (which evaluates to false).

           untaint(%ENV);                  # Untaints the environment
           taint(my @hlagh = qw(a o e u)); # elements of @hlagh now tainted

       References (being scalars) can also be tainted, a stringified reference reference raises
       an error where a tainted scalar would:

           taint(my $ar = \@hlagh);
           system echo => $ar;      # err: Insecure dependency in system

       This feature is used by perl internally to taint the blessed object "qr//" stringifies to.

           taint(my $str = "oh noes");
           my $re = qr/$str/;
           system echo => $re;      # err: Insecure dependency in system

       This does not mean that tainted blessed objects with overloaded stringification via
       overload need return a tainted object since those objects may return a non-tainted scalar
       when stringified (see t/usage.t for an example). The internal handling of "qr//" however
       ensures that this holds true.

       File handles can also be tainted, but this is pretty useless as the handle itself and not
       lines retrieved from it will be tainted, see the next section for details.

           taint(*DATA);    # *DATA tainted
           my $ln = <DATA>; # $ln not tainted

About tainting in Perl

       Since this module is a low level interface that directly exposes the internal "SvTAINTED*"
       functions it also presents new and exciting ways for shooting yourself in the foot.

       Tainting in Perl was always meant to be used for potentially hostile external data passed
       to the program. Perl is passed a soup of strings from the outside; it never receives any
       complex datatypes directly.

       For instance, you might get tainted hash keys in %ENV or tainted strings from *STDIN, but
       you'll never get a tainted Hash reference or a tainted subroutine. Internally, the perl
       compiler sets the taint flag on external data in a select few functions mainly having to
       do with IO and string operations. For example, the "ucfirst" function will manually set a
       tainted flag on its newly created string depending on whether the original was tainted or
       not.

       However, since Taint::Util is exposing some of perl's guts, things get more complex.
       Internally, tainting is implemented via perl's MAGIC facility, which allows you to attach
       attach magic to any scalar, but since perl doesn't liberally taint scalars it's there to
       back you up if you do.

       You can "taint(*DATA)" and "tainted(*DATA)" will subsequently be true but if you read from
       the filehandle via "<DATA>" you'll get untainted data back. As you might have guessed this
       is completely useless.

       The test file t/usage.t highlights some of these edge cases.

       Back in the real world, the only reason tainting makes sense is because perl will back you
       up when you use it, e.g. it will slap your hand if you try to pass a tainted value to
       system().

       If you taint references, perl doesn't offer that protection, because it doesn't know
       anything about tainted references since it would never create one. The things that do work
       like the stringification of "taint($t = [])" (i.e. "ARRAY(0x11a5d48)") being tainted only
       work incidentally.

       But I'm not going to stop you. By all means, have at it! Just don't expect it to do
       anything more useful than warming up your computer.

       See RT #53988 <https://rt.cpan.org/Ticket/Display.html?id=53988> for the bug that inspired
       this section.

EXPORTS

       Exports "tainted", "taint" and "untaint" by default. Individual functions can be exported
       by specifying them in the "use" list, to export none use "()".

HISTORY

       I wrote this when implementing re::engine::Plugin so that someone writing a custom regex
       engine with it wouldn't have to rely on perl regexps for untainting capture variables,
       which would be a bit odd.

SEE ALSO

       perlsec

AUTHOR

       Ævar Arnfjörð Bjarmason <avar@cpan.org>

LICENSE

       Copyright 2007-2010 Ævar Arnfjörð Bjarmason.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.