NAME¶
Taint::Runtime - Runtime enable taint checking
SYNOPSIS¶
### sample "enable" usage
#!/usr/bin/perl -w
use Taint::Runtime qw(enable taint_env);
taint_env();
# having the keyword enable in the import list starts taint
### sample $TAINT usage
#!/usr/bin/perl -w
use Taint::Runtime qw($TAINT taint_env);
$TAINT = 1;
taint_env();
# taint is now enabled
if (1) {
local $TAINT = 0;
# do something we trust
}
# back to an untrustwory area
### sample functional usage
#!/usr/bin/perl -w
use strict;
use Taint::Runtime qw(taint_start is_tainted taint_env
taint untaint
taint_enabled);
### other operations here
taint_start(); # taint should become active
taint_env(); # %ENV was previously untainted
print taint_enabled() ? "enabled\n" : "not enabled\n";
my $var = taint("some string");
print is_tainted($var) ? "tainted\n" : "not tainted\n";
$var = untaint($var);
# OR
untaint \$var;
print is_tainted($var) ? "tainted\n" : "not tainted\n";
DESCRIPTION¶
First - you probably shouldn't use this module to control taint. You should
probably use the -T switch on the commandline instead. There are a somewhat
limited number of legitimate use cases where you should use this module
instead of the -T switch. Unless you have a specific and good reason for not
using the -T option, you should use the -T option.
Taint is a good thing. However, few people (that I work with or talk to or
discuss items with) use taint even though they should. The goal of this module
isn't to use taint less, but to actually encourage its use more. This module
aims to make using taint as painless as possible (This can be an argument
against it - often implementation of security implies pain - so taking away
pain might lessen security - sort of).
In general - the more secure your script needs to be - the earlier on in your
program that tainting should be enabled. For most setuid scripts, you should
enable taint by using the -T switch. Without doing so you allow for a non-root
user to override @INC which allows for them to put their own module in the
place of trusted modules. This is bad. This is very bad. Use the -T switch.
There are some common places where this module may be useful, and where most
people don't use it. One such place is in a web server. The -T switch removes
PERL5LIB and PERLLIB and '.' from @INC (or remove them before they can be
added). This makes sense under setuid. The use of the -T switch in a CGI
environment may cause a bit of a headache. For new development, CGI scripts it
may be possible to use the -T switch and for mod_perl environments there is
the PerlTaint variable. Both of these methods will enable taint and from that
point on development should be done with taint.
However, many (possibly most) perl web server implentations add their own paths
to the PERL5LIB. All CGI's and mod_perl scripts can then have access. Using
the -T switch throws a wrench into the works as suddenly PERL5LIB disappears
(mod_perl can easily have the extra directories added again using
<perl>push @INC, '/our/lib/dir';</perl>). The company I work for
has 200 plus user visible scripts mixed with some mod_perl. Currently none of
the scripts use taint. We would like for them all to, but it is not feasible
to make the change all at once. Taint::Runtime allows for moving legacy
scripts over one at a time.
Again, if you are using setuid - don't use this script.
If you are not using setuid and have reasons not to use the -T and are using
this module, make sure that taint is enabled before processing any user data.
Also remember that BECAUSE THE -T SWITCH WAS NOT USED %ENV IS INITIALLY NOT
MARKED AS TAINTED. Call
taint_env() to mark it as tainted (especially
important in CGI scripts which all read from $ENV{'QUERY_STRING'}).
If you are not using the -T switch, you most likely should use the following at
the very top of your script:
#!/usr/bin/perl -w
use strict;
use Taint::Runtime qw(enable taint_env);
taint_env();
Though this module allows for you to turn taint off - you probably shouldn't.
This module is more for you to turn taint on - and once it is on it probably
ought to stay on.
NON-EXPORTABLE XS FUNCTIONS¶
The following very basic functions provide the base functionality.
- _taint_start()
- Sets PL_tainting
- _taint_stop()
- Sets PL_tainting
- _taint_enabled()
- View of PL_tainting
- _tainted()
- Returns a zero length tainted string.
$TAINT VARIABLE¶
The variable $TAINT is tied to the current state of taint. If $TAINT is set to 0
taint mode is off. When it is set to 1 taint mode is enabled.
if (1) {
local $TAINT = 1;
# taint is enabled
}
EXPORT FUNCTIONS¶
- enable/disable
- Not really functions. If these keywords are in the import list, taint will
be either enabled or disabled.
- taint_start
- Start taint mode. $TAINT will equal 1.
- taint_stop
- Stop taint mode. $TAINT will equal 0.
- taint_env
- Convenience function that taints the keys and values of %ENV. If the -T
switch was not used - you most likely should call this as soon as taint
mode is enabled.
- taint
- Taints the passed in variable. Only works on writeable scalar values. If a
scalar ref is passed in - it is modified. If a scalar is passed in (non
ref) it is copied, modified and returned. If a value was undefined, it
becomes a zero length defined and tainted string.
taint(\$var_to_be_tainted);
my $tainted_copy = taint($some_var);
For a stronger taint, see the Taint module by Dan Sulgalski which is capable
of tainting most types of data.
- untaint
- Untaints the passed in variable. Only works on writeable scalar values. If
a scalar ref is passed in - it is modified. If a scalar is passed in (non
ref) it is copied, modified and returned. If a value was undefined it
becomes an untainted undefined value.
Note: Just because the variable is untainted, doesn't mean that it is safe.
You really should use CGI::Ex::Validate, or Data::FormValidator or any of
the Untaint:: modules. If you are doing your own validation, and once you
have put the user data through very strict checks, then you can use
untaint.
if ($var_to_be_untainted =~ /^[\w\.\-]{0,100}$/) {
untaint(\$var_to_be_untainted);
}
my $untainted_copy = untaint($some_var);
- taint_enabled
- Boolean - Is taint on.
- tainted
- Returns a zero length tainted string.
- is_tainted
- Boolean - True if the passed value is tainted.
- taint_deeply
- Convenience function that attempts to deply recurse a structure and mark
it as tainted. Takes a hashref, arrayref, scalar ref, or scalar and
recursively untaints the structure.
For a stronger taint, see the Taint module by Dan Sulgalski which is capable
of tainting most types of data.
TURNING TAINT ON¶
(Be sure to call
taint_env() after turning taint on the first time)
#!/usr/bin/perl -T
use Taint::Runtime qw(enable);
# this does not create a function called enable - just starts taint
use Taint::Runtime qw($TAINT);
$TAINT = 1;
use Taint::Runtime qw(taint_start);
taint_start;
TURNING TAINT OFF¶
use Taint::Runtime qw(disable);
# this does not create a function called disable - just stops taint
use Taint::Runtime qw($TAINT);
$TAINT = 0;
use Taint::Runtime qw(taint_stop);
taint_stop;
CREDITS¶
C code was provided by "hv" on perlmonks. This module wouldn't really
be possible without insight into the internals that "hv" provided.
His post with the code was shown in this node on perlmonks:
http://perlmonks.org/?node_id=434086
The basic premise in that node was the following code:
use Inline C => 'void _start_taint() { PL_tainting = 1; }';
use Inline C => 'SV* _tainted() { PL_tainted = 1; return newSVpvn("", 0); }';
In this module, these two lines have instead been turned into XS for runtime
speed (and so you won't need Inline and Parse::RecDescent).
Note: even though "hv" provided the base code example, that doesn't
mean that he necessarily endorses the idea. If there are disagreements,
quirks, annoyances or any other negative side effects with this module - blame
me - not "hv."
THANKS¶
Thanks to Alexey A. Kiritchun for pointing out untaint failure on multiline
strings.
AUTHOR¶
Paul Seamons (2005)
C stub functions by "hv" on perlmonks.org
LICENSE¶
This module may be used and distributed under the same terms as Perl
itself.