README
1NAME
2 Taint::Util - Test for and flip the taint flag without regex matches or
3 "eval"
4
5SYNOPSIS
6 #!/usr/bin/env perl -T
7 use Taint::Util;
8
9 # eek!
10 untaint $ENV{PATH};
11
12 # $sv now tainted under taint mode (-T)
13 taint(my $sv = "hlagh");
14
15 # Untaint $sv again
16 untaint $sv if tainted $sv;
17
18DESCRIPTION
19 Wraps perl's internal routines for checking and setting the taint flag
20 and thus does not rely on regular expressions for untainting or odd
21 tricks involving "eval" and "kill" for checking whether data is tainted,
22 instead it checks and flips a flag on the scalar in-place.
23
24FUNCTIONS
25 tainted
26 Returns a boolean indicating whether a scalar is tainted. Always false
27 when not under taint mode.
28
29 taint & untaint
30 Taints or untaints given values, arrays will be flattened and their
31 elements tainted, likewise with the values of hashes (keys can't be
32 tainted, see perlsec). Returns no value (which evaluates to false).
33
34 untaint(%ENV); # Untaints the environment
35 taint(my @hlagh = qw(a o e u)); # elements of @hlagh now tainted
36
37 References (being scalars) can also be tainted, a stringified reference
38 reference raises an error where a tainted scalar would:
39
40 taint(my $ar = \@hlagh);
41 system echo => $ar; # err: Insecure dependency in system
42
43 This feature is used by perl internally to taint the blessed object
44 "qr//" stringifies to.
45
46 taint(my $str = "oh noes");
47 my $re = qr/$str/;
48 system echo => $re; # err: Insecure dependency in system
49
50 This does not mean that tainted blessed objects with overloaded
51 stringification via overload need return a tainted object since those
52 objects may return a non-tainted scalar when stringified (see t/usage.t
53 for an example). The internal handling of "qr//" however ensures that
54 this holds true.
55
56 File handles can also be tainted, but this is pretty useless as the
57 handle itself and not lines retrieved from it will be tainted, see the
58 next section for details.
59
60 taint(*DATA); # *DATA tainted
61 my $ln = <DATA>; # $ln not tainted
62
63About tainting in Perl
64 Since this module is a low level interface that directly exposes the
65 internal "SvTAINTED*" functions it also presents new and exciting ways
66 for shooting yourself in the foot.
67
68 Tainting in Perl was always meant to be used for potentially hostile
69 external data passed to the program. Perl is passed a soup of strings
70 from the outside; it never receives any complex datatypes directly.
71
72 For instance, you might get tainted hash keys in %ENV or tainted strings
73 from *STDIN, but you'll never get a tainted Hash reference or a tainted
74 subroutine. Internally, the perl compiler sets the taint flag on
75 external data in a select few functions mainly having to do with IO and
76 string operations. For example, the "ucfirst" function will manually set
77 a tainted flag on its newly created string depending on whether the
78 original was tainted or not.
79
80 However, since Taint::Util is exposing some of perl's guts, things get
81 more complex. Internally, tainting is implemented via perl's MAGIC
82 facility, which allows you to attach attach magic to any scalar, but
83 since perl doesn't liberally taint scalars it's there to back you up if
84 you do.
85
86 You can "taint(*DATA)" and "tainted(*DATA)" will subsequently be true
87 but if you read from the filehandle via "<DATA>" you'll get untainted
88 data back. As you might have guessed this is completely useless.
89
90 The test file t/usage.t highlights some of these edge cases.
91
92 Back in the real world, the only reason tainting makes sense is because
93 perl will back you up when you use it, e.g. it will slap your hand if
94 you try to pass a tainted value to system().
95
96 If you taint references, perl doesn't offer that protection, because it
97 doesn't know anything about tainted references since it would never
98 create one. The things that do work like the stringification of
99 "taint($t = [])" (i.e. "ARRAY(0x11a5d48)") being tainted only work
100 incidentally.
101
102 But I'm not going to stop you. By all means, have at it! Just don't
103 expect it to do anything more useful than warming up your computer.
104
105 See RT #53988 <https://rt.cpan.org/Ticket/Display.html?id=53988> for the
106 bug that inspired this section.
107
108EXPORTS
109 Exports "tainted", "taint" and "untaint" by default. Individual
110 functions can be exported by specifying them in the "use" list, to
111 export none use "()".
112
113HISTORY
114 I wrote this when implementing re::engine::Plugin so that someone
115 writing a custom regex engine with it wouldn't have to rely on perl
116 regexps for untainting capture variables, which would be a bit odd.
117
118SEE ALSO
119 perlsec
120
121AUTHOR
122 �var Arnfj�r� Bjarmason <avar@cpan.org>
123
124LICENSE
125 Copyright 2007-2010 �var Arnfj�r� Bjarmason.
126
127 This program is free software; you can redistribute it and/or modify it
128 under the same terms as Perl itself.
129
130