Unix/Linux Go Back    


CentOS 7.0 - man page for taint::runtime (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Taint::Runtime(3)	       User Contributed Perl Documentation		Taint::Runtime(3)

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.

perl v5.16.3				    2007-06-14				Taint::Runtime(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 12:20 AM.