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
18 #!/usr/bin/perl -w
20 use Taint::Runtime qw($TAINT taint_env);
21 $TAINT = 1;
22 taint_env();
23 # taint is now enabled
25 if (1) {
27 local $TAINT = 0;
28 # do something we trust
30 }
31 # back to an untrustwory area
33 ### sample functional usage
37 #!/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 ### other operations here
45 taint_start(); # taint should become active
47 taint_env(); # %ENV was previously untainted
48 print taint_enabled() ? "enabled\n" : "not enabled\n";
50 my $var = taint("some string");
52 print is_tainted($var) ? "tainted\n" : "not tainted\n";
54 $var = untaint($var);
56 # OR
57 untaint \$var;
58 print is_tainted($var) ? "tainted\n" : "not tainted\n";
60
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 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 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 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 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 Again, if you are using setuid - don't use this script.
104 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 If you are not using the -T switch, you most likely should use the
113 following at the very top of your script:
114 #!/usr/bin/perl -w
116 use strict;
118 use Taint::Runtime qw(enable taint_env);
119 taint_env();
120 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
126 The following very basic functions provide the base functionality.
127 _taint_start()
129 Sets PL_tainting
130 _taint_stop()
132 Sets PL_tainting
133 _taint_enabled()
135 View of PL_tainting
136 _tainted()
138 Returns a zero length tainted string.
139
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 if (1) {
146 local $TAINT = 1;
147 # taint is enabled
149 }
150
152 enable/disable
153 Not really functions. If these keywords are in the import list,
154 taint will be either enabled or disabled.
155 taint_start
157 Start taint mode. $TAINT will equal 1.
158 taint_stop
160 Stop taint mode. $TAINT will equal 0.
161 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 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 taint(\$var_to_be_tainted);
175 my $tainted_copy = taint($some_var);
177 For a stronger taint, see the Taint module by Dan Sulgalski which
179 is capable of tainting most types of data.
180 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 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 if ($var_to_be_untainted =~ /^[\w\.\-]{0,100}$/) {
194 untaint(\$var_to_be_untainted);
195 }
196 my $untainted_copy = untaint($some_var);
198 taint_enabled
200 Boolean - Is taint on.
201 tainted
203 Returns a zero length tainted string.
204 is_tainted
206 Boolean - True if the passed value is tainted.
207 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 For a stronger taint, see the Taint module by Dan Sulgalski which
214 is capable of tainting most types of data.
215
217 (Be sure to call taint_env() after turning taint on the first time)
218 #!/usr/bin/perl -T
220 use Taint::Runtime qw(enable);
223 # this does not create a function called enable - just starts taint
224 use Taint::Runtime qw($TAINT);
226 $TAINT = 1;
227 use Taint::Runtime qw(taint_start);
230 taint_start;
231
233 use Taint::Runtime qw(disable);
234 # this does not create a function called disable - just stops taint
235 use Taint::Runtime qw($TAINT);
238 $TAINT = 0;
239 use Taint::Runtime qw(taint_stop);
242 taint_stop;
243
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 http://perlmonks.org/?node_id=434086
250 The basic premise in that node was the following code:
252 use Inline C => 'void _start_taint() { PL_tainting = 1; }';
254 use Inline C => 'SV* _tainted() { PL_tainted = 1; return newSVpvn("", 0); }';
255 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 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
265 Thanks to Alexey A. Kiritchun for pointing out untaint failure on
266 multiline strings.
267
269 Paul Seamons (2005)
270 C stub functions by "hv" on perlmonks.org
272
274 This module may be used and distributed under the same terms as Perl
275 itself.
276perl v5.28.1 2007-06-14 Taint::Runtime(3)