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