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.