1Taint::Runtime(3)     User Contributed Perl Documentation    Taint::Runtime(3)
2
3
4

NAME

6       Taint::Runtime - Runtime enable taint checking
7

SYNOPSIS

9         ### sample "enable" usage
10
11         #!/usr/bin/perl -w
12         use Taint::Runtime qw(enable taint_env);
13         taint_env();
14         # having the keyword enable in the import list starts taint
15
16
17         ### sample $TAINT usage
18
19         #!/usr/bin/perl -w
20         use Taint::Runtime qw($TAINT taint_env);
21         $TAINT = 1;
22         taint_env();
23
24         # taint is now enabled
25
26         if (1) {
27           local $TAINT = 0;
28
29           # do something we trust
30         }
31
32         # back to an untrustwory area
33
34
35
36         ### sample functional usage
37
38         #!/usr/bin/perl -w
39         use strict;
40         use Taint::Runtime qw(taint_start is_tainted taint_env
41                               taint untaint
42                               taint_enabled);
43
44         ### other operations here
45
46         taint_start(); # taint should become active
47         taint_env(); # %ENV was previously untainted
48
49         print taint_enabled() ? "enabled\n" : "not enabled\n";
50
51         my $var = taint("some string");
52
53         print is_tainted($var) ? "tainted\n" : "not tainted\n";
54
55         $var = untaint($var);
56         # OR
57         untaint \$var;
58
59         print is_tainted($var) ? "tainted\n" : "not tainted\n";
60

DESCRIPTION

62       First - you probably shouldn't use this module to control taint.  You
63       should probably use the -T switch on the commandline instead.  There
64       are a somewhat limited number of legitimate use cases where you should
65       use this module instead of the -T switch.  Unless you have a specific
66       and good reason for not using the -T option, you should use the -T
67       option.
68
69       Taint is a good thing.  However, few people (that I work with or talk
70       to or discuss items with) use taint even though they should.  The goal
71       of this module isn't to use taint less, but to actually encourage its
72       use more.  This module aims to make using taint as painless as possible
73       (This can be an argument against it - often implementation of security
74       implies pain - so taking away pain might lessen security - sort of).
75
76       In general - the more secure your script needs to be - the earlier on
77       in your program that tainting should be enabled.  For most setuid
78       scripts, you should enable taint by using the -T switch.  Without doing
79       so you allow for a non-root user to override @INC which allows for them
80       to put their own module in the place of trusted modules.  This is bad.
81       This is very bad.  Use the -T switch.
82
83       There are some common places where this module may be useful, and where
84       most people don't use it.  One such place is in a web server.  The -T
85       switch removes PERL5LIB and PERLLIB and '.' from @INC (or remove them
86       before they can be added).  This makes sense under setuid.  The use of
87       the -T switch in a CGI environment may cause a bit of a headache.  For
88       new development, CGI scripts it may be possible to use the -T switch
89       and for mod_perl environments there is the PerlTaint variable.  Both of
90       these methods will enable taint and from that point on development
91       should be done with taint.
92
93       However, many (possibly most) perl web server implentations add their
94       own paths to the PERL5LIB.  All CGI's and mod_perl scripts can then
95       have access.  Using the -T switch throws a wrench into the works as
96       suddenly PERL5LIB disappears (mod_perl can easily have the extra
97       directories added again using <perl>push @INC, '/our/lib/dir';</perl>).
98       The company I work for has 200 plus user visible scripts mixed with
99       some mod_perl.  Currently none of the scripts use taint.  We would like
100       for them all to, but it is not feasible to make the change all at once.
101       Taint::Runtime allows for moving legacy scripts over one at a time.
102
103       Again, if you are using setuid - don't use this script.
104
105       If you are not using setuid and have reasons not to use the -T and are
106       using this module, make sure that taint is enabled before processing
107       any user data.  Also remember that BECAUSE THE -T SWITCH WAS NOT USED
108       %ENV IS INITIALLY NOT MARKED AS TAINTED.  Call taint_env() to mark it
109       as tainted (especially important in CGI scripts which all read from
110       $ENV{'QUERY_STRING'}).
111
112       If you are not using the -T switch, you most likely should use the
113       following at the very top of your script:
114
115         #!/usr/bin/perl -w
116
117         use strict;
118         use Taint::Runtime qw(enable taint_env);
119         taint_env();
120
121       Though this module allows for you to turn taint off - you probably
122       shouldn't.  This module is more for you to turn taint on - and once it
123       is on it probably ought to stay on.
124

NON-EXPORTABLE XS FUNCTIONS

126       The following very basic functions provide the base functionality.
127
128       _taint_start()
129           Sets PL_tainting
130
131       _taint_stop()
132           Sets PL_tainting
133
134       _taint_enabled()
135           View of PL_tainting
136
137       _tainted()
138           Returns a zero length tainted string.
139

$TAINT VARIABLE

141       The variable $TAINT is tied to the current state of taint.  If $TAINT
142       is set to 0 taint mode is off.  When it is set to 1 taint mode is
143       enabled.
144
145         if (1) {
146           local $TAINT = 1;
147
148           # taint is enabled
149         }
150

EXPORT FUNCTIONS

152       enable/disable
153           Not really functions.  If these keywords are in the import list,
154           taint will be either enabled or disabled.
155
156       taint_start
157           Start taint mode.  $TAINT will equal 1.
158
159       taint_stop
160           Stop taint mode.  $TAINT will equal 0.
161
162       taint_env
163           Convenience function that taints the keys and values of %ENV.  If
164           the -T switch was not used - you most likely should call this as
165           soon as taint mode is enabled.
166
167       taint
168           Taints the passed in variable.  Only works on writeable scalar
169           values.  If a scalar ref is passed in - it is modified.  If a
170           scalar is passed in (non ref) it is copied, modified and returned.
171           If a value was undefined, it becomes a zero length defined and
172           tainted string.
173
174             taint(\$var_to_be_tainted);
175
176             my $tainted_copy = taint($some_var);
177
178           For a stronger taint, see the Taint module by Dan Sulgalski which
179           is capable of tainting most types of data.
180
181       untaint
182           Untaints the passed in variable.  Only works on writeable scalar
183           values.  If a scalar ref is passed in - it is modified.  If a
184           scalar is passed in (non ref) it is copied, modified and returned.
185           If a value was undefined it becomes an untainted undefined value.
186
187           Note:  Just because the variable is untainted, doesn't mean that it
188           is safe.  You really should use CGI::Ex::Validate, or
189           Data::FormValidator or any of the Untaint:: modules.  If you are
190           doing your own validation, and once you have put the user data
191           through very strict checks, then you can use untaint.
192
193             if ($var_to_be_untainted =~ /^[\w\.\-]{0,100}$/) {
194               untaint(\$var_to_be_untainted);
195             }
196
197             my $untainted_copy = untaint($some_var);
198
199       taint_enabled
200           Boolean - Is taint on.
201
202       tainted
203           Returns a zero length tainted string.
204
205       is_tainted
206           Boolean - True if the passed value is tainted.
207
208       taint_deeply
209           Convenience function that attempts to deply recurse a structure and
210           mark it as tainted.  Takes a hashref, arrayref, scalar ref, or
211           scalar and recursively untaints the structure.
212
213           For a stronger taint, see the Taint module by Dan Sulgalski which
214           is capable of tainting most types of data.
215

TURNING TAINT ON

217       (Be sure to call taint_env() after turning taint on the first time)
218
219         #!/usr/bin/perl -T
220
221
222         use Taint::Runtime qw(enable);
223         # this does not create a function called enable - just starts taint
224
225         use Taint::Runtime qw($TAINT);
226         $TAINT = 1;
227
228
229         use Taint::Runtime qw(taint_start);
230         taint_start;
231

TURNING TAINT OFF

233         use Taint::Runtime qw(disable);
234         # this does not create a function called disable - just stops taint
235
236
237         use Taint::Runtime qw($TAINT);
238         $TAINT = 0;
239
240
241         use Taint::Runtime qw(taint_stop);
242         taint_stop;
243

CREDITS

245       C code was provided by "hv" on perlmonks.  This module wouldn't really
246       be possible without insight into the internals that "hv" provided.  His
247       post with the code was shown in this node on perlmonks:
248
249         http://perlmonks.org/?node_id=434086
250
251       The basic premise in that node was the following code:
252
253         use Inline C => 'void _start_taint() { PL_tainting = 1; }';
254         use Inline C => 'SV* _tainted() { PL_tainted = 1; return newSVpvn("", 0); }';
255
256       In this module, these two lines have instead been turned into XS for
257       runtime speed (and so you won't need Inline and Parse::RecDescent).
258
259       Note: even though "hv" provided the base code example, that doesn't
260       mean that he necessarily endorses the idea.  If there are
261       disagreements, quirks, annoyances or any other negative side effects
262       with this module - blame me - not "hv."
263

THANKS

265       Thanks to Alexey A. Kiritchun for pointing out untaint failure on
266       multiline strings.
267

AUTHOR

269       Paul Seamons (2005)
270
271       C stub functions by "hv" on perlmonks.org
272

LICENSE

274       This module may be used and distributed under the same terms as Perl
275       itself.
276
277
278
279perl v5.12.0                      2007-06-14                 Taint::Runtime(3)
Impressum