NAME

Untaint - Module for laundering tainted data.

SYNOPSIS

        use Untaint;

        my $pattern = qr(^k\w+);

        my $foo = $ARGV[0];

        # Untaint a scalar
        if (is_tainted($foo)) {
                print "\$foo is tainted. Attempting to launder\n";
                $foo = untaint($pattern, $foo);
        }else{
                print "\$foo is not tainted!!\n";
        }

        # Untaint an array 
        my @foo = @ARGV;

        push @foo, "not tainted";

        if (is_tainted(@foo)) {
                print "\@foo is tainted. Attempting to launder\n";
                my @new = untaint($pattern, @foo);
        }else{
                print "\@foo is not tainted!!\n";
        }

        # Another way for an list
        ($a, $b, $c) = untaint(qr(^\d+$), ($a, $b , $c));

        # Untaint a hash
        my $test = {'name' => $ARGV[0],
                    'age' => $ARGV[1],
                    'gender' => $ARGV[2],
                    'time' => 'late'
                   };

        my $patterns = {'name' => qr(^k\w+),
                        'age' => qr(^\d+),
                        'gender' => qr(^\w$)
                       };

        $UNTAINT_ALLOW_HASH++;

        my %new = untaint_hash($patterns, %{$test});

DESCRIPTION

This module is used to launder data which has been tainted by using the -T switch to be in taint mode. This can be used for CGI scripts as well as command line scripts.

The module will untaint scalars, arrays, and hashes. When laundering an array, only array elements which are tainted will be laundered.

FUNCTIONS

is_tainted(<scalar or array>);

You can use this to check the taintedness of data if you wish, but it is also used internally by Untaint.pm to do this when untaint() is called. This method returns 1 if tainted, 0 if not. This is actually a pass-through to Taint.pm's is_tainted method, since that already accomplishes this task.

newvar = untaint(<pattern>, <scalar or array/list>);

This method will launder the data (if it can) and return the newly laundered variable. It should be passed either a scalar, or an array reference. This will return either an array, or a scalar depending on which you want returned. The pattern should be a regular expression pattern to match the data against.

If this method can not launder a variable, it will croak().

untaint_hash(<hashref of patterns>, hash)

When laundering a hash, a hash of patterns can be passed. This allows you to define a different pattern for each element of the hash. If there is no pattern for an element in the hash, the value itself will be used as the pattern (therefore untainting itself). This behavior isn't really safe, so you need to specify that you want to do this by setting a special variable to a true value like this:

        $UNTAINT_ALLOW_HASH++;

That scalar is exported so you need to specifically say it is ok to do this.

If this is not done, any key/value pair which does not have a pattern will not be laundered and the returned hash will only contain the key/value pairs which had a corresponding pattern.

It appears that whenever there is one value in a hash that is tainted, ALL values in that hash are tainted. This is a bug in Perl versions which are pre-5.6. This is somewhat of a quagmire since key/value pairs you actually set are now tainted, and need laundering. That's all well and good, but now there is the chance that when you pass the hash ref, you pass something without a pattern unknowingly, and data you don't want untainted is then laundered. Another current bug is that all hash keys are not considered tainted. So, be wary of using hash keys which come from unknown sources in Bad ways. But, if you are trying to use a hash key which you do not know where it's name is from in a dangerous manner, there may be other problems!

$UNTAINT_ALLOW_HASH

This variable must be set to a true value of you wish to allow hash values to be untainted based on their own value as a pattern. In other words, the pattern that will be matched to untaint it, will be itself, hence always being untainted. USE THIS WITH CAUTION.

INSTALLATION

perl Makefile.PL make make test make install make clean

Look at the test scripts to see how this can be implemented.

BUGS

None known at this time. PATCHES WELCOME.

COPYRIGHT

AUTHOR

Kevin Meltzer, <perlguy@perlguy.com>

CREDITS

Tom Phoenix, <rootbeer@teleport.com>