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