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 helps 
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 hasn'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 parameters.  
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 script.

=head2 USAGE

A C<use taint::CGI;> statement untaints the safe parts of the environment.
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 started 
with the -T or -t switch.  Try modifying the shebang line at the top of 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.  Take a 
look at the indicated line number and operation, and see if you can figure 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 something safe.

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

If this diagnostic is emitted by Perl, this module probably isn't functioning 
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