1Util(3)               User Contributed Perl Documentation              Util(3)
2
3
4

NAME

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

SYNOPSIS

10           #!/usr/bin/env perl -T
11           use Taint::Util;
12
13           # eek!
14           untaint $ENV{PATH};
15
16           # $sv now tainted under taint mode (-T)
17           taint(my $sv = "hlagh");
18
19           # Untaint $sv again
20           untaint $sv if tainted $sv;
21

DESCRIPTION

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

FUNCTIONS

29   tainted
30       Returns a boolean indicating whether a scalar is tainted. Always false
31       when not under taint mode.
32
33   taint & untaint
34       Taints or untaints given values, arrays will be flattened and their
35       elements tainted, likewise with the values of hashes (keys can't be
36       tainted, see perlsec). Returns no value (which evaluates to false).
37
38           untaint(%ENV);                  # Untaints the environment
39           taint(my @hlagh = qw(a o e u)); # elements of @hlagh now tainted
40
41       References (being scalars) can also be tainted, a stringified reference
42       reference raises an error where a tainted scalar would:
43
44           taint(my $ar = \@hlagh);
45           system echo => $ar;      # err: Insecure dependency in system
46
47       This feature is used by perl internally to taint the blessed object
48       "qr//" stringifies to.
49
50           taint(my $str = "oh noes");
51           my $re = qr/$str/;
52           system echo => $re;      # err: Insecure dependency in system
53
54       This does not mean that tainted blessed objects with overloaded
55       stringification via overload need return a tainted object since those
56       objects may return a non-tainted scalar when stringified (see t/usage.t
57       for an example). The internal handling of "qr//" however ensures that
58       this holds true.
59
60       File handles can also be tainted, but this is pretty useless as the
61       handle itself and not lines retrieved from it will be tainted, see the
62       next section for details.
63
64           taint(*DATA);    # *DATA tainted
65           my $ln = <DATA>; # $ln not tainted
66

About tainting in Perl

68       Since this module is a low level interface that directly exposes the
69       internal "SvTAINTED*" functions it also presents new and exciting ways
70       for shooting yourself in the foot.
71
72       Tainting in Perl was always meant to be used for potentially hostile
73       external data passed to the program. Perl is passed a soup of strings
74       from the outside; it never receives any complex datatypes directly.
75
76       For instance, you might get tainted hash keys in %ENV or tainted
77       strings from *STDIN, but you'll never get a tainted Hash reference or a
78       tainted subroutine. Internally, the perl compiler sets the taint flag
79       on external data in a select few functions mainly having to do with IO
80       and string operations. For example, the "ucfirst" function will
81       manually set a tainted flag on its newly created string depending on
82       whether the original was tainted or not.
83
84       However, since Taint::Util is exposing some of perl's guts, things get
85       more complex. Internally, tainting is implemented via perl's MAGIC
86       facility, which allows you to attach attach magic to any scalar, but
87       since perl doesn't liberally taint scalars it's there to back you up if
88       you do.
89
90       You can "taint(*DATA)" and "tainted(*DATA)" will subsequently be true
91       but if you read from the filehandle via "<DATA>" you'll get untainted
92       data back. As you might have guessed this is completely useless.
93
94       The test file t/usage.t highlights some of these edge cases.
95
96       Back in the real world, the only reason tainting makes sense is because
97       perl will back you up when you use it, e.g. it will slap your hand if
98       you try to pass a tainted value to system().
99
100       If you taint references, perl doesn't offer that protection, because it
101       doesn't know anything about tainted references since it would never
102       create one. The things that do work like the stringification of
103       "taint($t = [])" (i.e. "ARRAY(0x11a5d48)") being tainted only work
104       incidentally.
105
106       But I'm not going to stop you. By all means, have at it! Just don't
107       expect it to do anything more useful than warming up your computer.
108
109       See RT #53988 <https://rt.cpan.org/Ticket/Display.html?id=53988> for
110       the bug that inspired this section.
111

EXPORTS

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

HISTORY

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

SEE ALSO

123       perlsec
124

AUTHOR

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

LICENSE

129       Copyright 2007-2010 Ævar Arnfjörð Bjarmason.
130
131       This program is free software; you can redistribute it and/or modify it
132       under the same terms as Perl itself.
133
134
135
136perl v5.34.0                      2022-01-21                           Util(3)
Impressum