1Taint::Runtime(3) User Contributed Perl Documentation Taint::Runtime(3)
2
6 Taint::Runtime - Runtime enable taint checking
7
9 ### sample "enable" usage
10 #!/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 ### sample $TAINT usage
17 #!/usr/bin/perl -w
19 use Taint::Runtime qw($TAINT taint_env);
20 $TAINT = 1;
21 taint_env();
22 # taint is now enabled
24 if (1) {
26 local $TAINT = 0;
27 # do something we trust
29 }
30 # back to an untrustwory area
32 ### sample functional usage
34 #!/usr/bin/perl -w
36 use strict;
37 use Taint::Runtime qw(taint_start is_tainted taint_env
38 taint untaint
39 taint_enabled);
40 ### other operations here
42 taint_start(); # taint should become active
44 taint_env(); # %ENV was previously untainted
45 print taint_enabled() ? "enabled\n" : "not enabled\n";
47 my $var = taint("some string");
49 print is_tainted($var) ? "tainted\n" : "not tainted\n";
51 $var = untaint($var);
53 # OR
54 untaint \$var;
55 print is_tainted($var) ? "tainted\n" : "not tainted\n";
57
59 First - you probably shouldn't use this module to control taint. You
60 should probably use the -T switch on the commandline instead. There
61 are a somewhat limited number of legitimate use cases where you should
62 use this module instead of the -T switch. Unless you have a specific
63 and good reason for not using the -T option, you should use the -T
64 option.
65 Taint is a good thing. However, few people (that I work with or talk
67 to or discuss items with) use taint even though they should. The goal
68 of this module isn't to use taint less, but to actually encourage its
69 use more. This module aims to make using taint as painless as possible
70 (This can be an argument against it - often implementation of security
71 implies pain - so taking away pain might lessen security - sort of).
72 In general - the more secure your script needs to be - the earlier on
74 in your program that tainting should be enabled. For most setuid
75 scripts, you should enable taint by using the -T switch. Without doing
76 so you allow for a non-root user to override @INC which allows for them
77 to put their own module in the place of trusted modules. This is bad.
78 This is very bad. Use the -T switch.
79 There are some common places where this module may be useful, and where
81 most people don't use it. One such place is in a web server. The -T
82 switch removes PERL5LIB and PERLLIB and '.' from @INC (or remove them
83 before they can be added). This makes sense under setuid. The use of
84 the -T switch in a CGI environment may cause a bit of a headache. For
85 new development, CGI scripts it may be possible to use the -T switch
86 and for mod_perl environments there is the PerlTaint variable. Both of
87 these methods will enable taint and from that point on development
88 should be done with taint.
89 However, many (possibly most) perl web server implentations add their
91 own paths to the PERL5LIB. All CGI's and mod_perl scripts can then
92 have access. Using the -T switch throws a wrench into the works as
93 suddenly PERL5LIB disappears (mod_perl can easily have the extra direc‐
94 tories added again using <perl>push @INC, '/our/lib/dir';</perl>). The
95 company I work for has 200 plus user visible scripts mixed with some
96 mod_perl. Currently none of the scripts use taint. We would like for
97 them all to, but it is not feasible to make the change all at once.
98 Taint::Runtime allows for moving legacy scripts over one at a time.
99 Again, if you are using setuid - don't use this script.
101 If you are not using setuid and have reasons not to use the -T and are
103 using this module, make sure that taint is enabled before processing
104 any user data. Also remember that BECAUSE THE -T SWITCH WAS NOT USED
105 %ENV IS INITIALLY NOT MARKED AS TAINTED. Call taint_env() to mark it
106 as tainted (especially important in CGI scripts which all read from
107 $ENV{'QUERY_STRING'}).
108 If you are not using the -T switch, you most likely should use the fol‐
110 lowing at the very top of your script:
111 #!/usr/bin/perl -w
113 use strict;
115 use Taint::Runtime qw(enable taint_env);
116 taint_env();
117 Though this module allows for you to turn taint off - you probably
119 shouldn't. This module is more for you to turn taint on - and once it
120 is on it probably ought to stay on.
121
123 The following very basic functions provide the base functionality.
124 _taint_start()
126 Sets PL_tainting
127 _taint_stop()
129 Sets PL_tainting
130 _taint_enabled()
132 View of PL_tainting
133 _tainted()
135 Returns a zero length tainted string.
136
138 The variable $TAINT is tied to the current state of taint. If $TAINT
139 is set to 0 taint mode is off. When it is set to 1 taint mode is
140 enabled.
141 if (1) {
143 local $TAINT = 1;
144 # taint is enabled
146 }
147
149 enable/disable
150 Not really functions. If these keywords are in the import list,
151 taint will be either enabled or disabled.
152 taint_start
154 Start taint mode. $TAINT will equal 1.
155 taint_stop
157 Stop taint mode. $TAINT will equal 0.
158 taint_env
160 Convenience function that taints the keys and values of %ENV. If
161 the -T switch was not used - you most likely should call this as
162 soon as taint mode is enabled.
163 taint
165 Taints the passed in variable. Only works on writeable scalar val‐
166 ues. If a scalar ref is passed in - it is modified. If a scalar
167 is passed in (non ref) it is copied, modified and returned. If a
168 value was undefined, it becomes a zero length defined and tainted
169 string.
170 taint(\$var_to_be_tainted);
172 my $tainted_copy = taint($some_var);
174 For a stronger taint, see the Taint module by Dan Sulgalski which
176 is capable of tainting most types of data.
177 untaint
179 Untaints the passed in variable. Only works on writeable scalar
180 values. If a scalar ref is passed in - it is modified. If a
181 scalar is passed in (non ref) it is copied, modified and returned.
182 If a value was undefined it becomes an untainted undefined value.
183 Note: Just because the variable is untainted, doesn't mean that it
185 is safe. You really should use CGI::Ex::Validate, or Data::Form‐
186 Validator or any of the Untaint:: modules. If you are doing your
187 own validation, and once you have put the user data through very
188 strict checks, then you can use untaint.
189 if ($var_to_be_untainted =~ /^[\w\.\-]{0,100}$/) {
191 untaint(\$var_to_be_untainted);
192 }
193 my $untainted_copy = untaint($some_var);
195 taint_enabled
197 Boolean - Is taint on.
198 tainted
200 Returns a zero length tainted string.
201 is_tainted
203 Boolean - True if the passed value is tainted.
204 taint_deeply
206 Convenience function that attempts to deply recurse a structure and
207 mark it as tainted. Takes a hashref, arrayref, scalar ref, or
208 scalar and recursively untaints the structure.
209 For a stronger taint, see the Taint module by Dan Sulgalski which
211 is capable of tainting most types of data.
212
214 (Be sure to call taint_env() after turning taint on the first time)
215 #!/usr/bin/perl -T
217 use Taint::Runtime qw(enable);
219 # this does not create a function called enable - just starts taint
220 use Taint::Runtime qw($TAINT);
222 $TAINT = 1;
223 use Taint::Runtime qw(taint_start);
225 taint_start;
226
228 use Taint::Runtime qw(disable);
229 # this does not create a function called disable - just stops taint
230 use Taint::Runtime qw($TAINT);
232 $TAINT = 0;
233 use Taint::Runtime qw(taint_stop);
235 taint_stop;
236
238 C code was provided by "hv" on perlmonks. This module wouldn't really
239 be possible without insight into the internals that "hv" provided. His
240 post with the code was shown in this node on perlmonks:
241 http://perlmonks.org/?node_id=434086
243 The basic premise in that node was the following code:
245 use Inline C => 'void _start_taint() { PL_tainting = 1; }';
247 use Inline C => 'SV* _tainted() { PL_tainted = 1; return newSVpvn("", 0); }';
248 In this module, these two lines have instead been turned into XS for
250 runtime speed (and so you won't need Inline and Parse::RecDescent).
251 Note: even though "hv" provided the base code example, that doesn't
253 mean that he necessarily endorses the idea. If there are disagree‐
254 ments, quirks, annoyances or any other negative side effects with this
255 module - blame me - not "hv."
256
258 Thanks to Alexey A. Kiritchun for pointing out untaint failure on mul‐
259 tiline strings.
260
262 Paul Seamons (2005)
263 C stub functions by "hv" on perlmonks.org
265
267 This module may be used and distributed under the same terms as Perl
268 itself.
269perl v5.8.8 2007-06-14 Taint::Runtime(3)