package taint::CGI;

use 5.008;
use strict;
use warnings;
use warnings::register;

our $VERSION = '0.01';

sub untaint {
    $_[0]=($_[0] =~ m/(.*)/s)[0];
}

if(defined ${^TAINT}) {
    warnings::warnif("taint::CGI module used with taint mode off")
        unless ${^TAINT};
}

for(keys %ENV) {
    next if /^HTTPS?_/;
    untaint $ENV{$_};
}

1;

=head1 NAME

taint::CGI - Clean up tainted values that are safe in CGI scripts

=head1 SYNOPSIS

  use taint::CGI;
  system("foo");                    #ok
  system($ENV{HTTP_QUERY_STRING});  #still bad

=head1 ABSTRACT

taint::CGI is a module designed to be used in CGI scripts, where the 
full power of taint checking is unnecessary.  It removes the taint on 
most of the environment, leaving only the HTTP_* and HTTPS_* values 
tainted.

=head1 DESCRIPTION

Taint checking is always a wise idea when writing CGI scripts.  It hel
+ps 
you catch stupid security bugs, like passing a CGI parameter into a 
system() call without checking it.  But it also checks for things that
+ 
CGI programs don't need to worry about too much, like a $PATH that has
+n't 
been explicitly set.

C<taint::CGI> helps fix that.  It untaints most of the environment for
+ you, 
leaving the values the server (and often ultimately the user) gave you
+ alone.
Thus, you get the security of tainted user data without all the hassle
+ of 
mucking with your environment.

Note that this does I<not> remove the need to taint-check CGI paramete
+rs.  
Nor does it remove the need to put a -T or -t in your shebang line.  (
+It 
will warn you if you try to use it with tainting disabled, however.)  
+It 
merely removes a dozen or so boilerplate lines of code from your scrip
+t.

=head2 USAGE

A C<use taint::CGI;> statement untaints the safe parts of the environm
+ent.
This happens at compile-time, not runtime.  It applies to all packages
+ and 
classes.

There is no built-in facility for re-tainting the environment.

=head2 DIAGNOSTICS

=over 4

=item taint::CGI module used with taint mode off

This diagnostic is emitted when taint::CGI is used, but Perl was not s
+tarted 
with the -T or -t switch.  Try modifying the shebang line at the top o
+f your 
script, or comment out the call to taint::CGI.

=item Insecure dependency in %s

This diagnostic is emitted by Perl when taint checks are violated.  Ta
+ke a 
look at the indicated line number and operation, and see if you can fi
+gure out 
how it received a tainted argument.

=item Insecure directory in %s

Taint checks don't allow you to put a directory that's writable to all
+ users in 
your $PATH.  Sorry.  You'll have to explicitly set your $PATH to somet
+hing safe.

=item Insecure $ENV{%s} while running %s

If this diagnostic is emitted by Perl, this module probably isn't func
+tioning 
properly.  You should probably report it to the atuhor.

=back

=head1 SEE ALSO

L<perlsec>

L<taint> (on versions of Perl that support it)

=head1 AUTHOR

Brent Dax, E<lt>brentdax@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright 2003 by Brent Dax.  All Rights Reserved.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself. 

=cut