NAME¶

CGI::Untaint - process CGI input parameters

SYNOPSIS¶

  use CGI::Untaint;
  my $q = new CGI;
  my $handler = CGI::Untaint->new( $q->Vars );
  my $handler2 = CGI::Untaint->new({
        INCLUDE_PATH => 'My::Untaint',
  }, $apr->parms);
  my $name     = $handler->extract(-as_printable => 'name');
  my $homepage = $handler->extract(-as_url => 'homepage');
  my $postcode = $handler->extract(-as_postcode => 'address6');
  # Create your own handler...
  package MyRecipes::CGI::Untaint::legal_age;
  use base 'CGI::Untaint::integer';
  sub is_valid { 
    shift->value > 21;
  }
  package main;
  my $age = $handler->extract(-as_legal_age => 'age');

DESCRIPTION¶

Dealing with large web based applications with multiple forms is a minefield. It's often hard enough to ensure you validate all your input at all, without having to worry about doing it in a consistent manner. If any of the validation rules change, you often have to alter them in many different places. And, if you want to operate taint-safe, then you're just adding even more headaches.

This module provides a simple, convenient, abstracted and extensible manner for validating and untainting the input from web forms.

You simply create a handler with a hash of your parameters (usually $q->Vars), and then iterate over the fields you wish to extract, performing whatever validations you choose. The resulting variable is guaranteed not only to be valid, but also untainted.

CONSTRUCTOR¶

  my $handler  = CGI::Untaint->new( $q->Vars );
  my $handler2 = CGI::Untaint->new({
        INCLUDE_PATH => 'My::Untaint',
  }, $apr->parms);

METHODS¶

  my $homepage = $handler->extract(-as_url => 'homepage');
  my $state = $handler->extract(-as_us_state => 'address4');
  my $state = $handler->extract(-as_like_us_state => 'address4');

  my $error = $handler->error;

LOCAL EXTRACTION HANDLERS¶

As well as as the handlers supplied with this module for extracting data, you may also create your own. In general these should inherit from 'CGI::Untaint::object', and must provide an '_untaint_re' method which returns a compiled regular expression, suitably bracketed such that $1 will return the untainted value required.

e.g. if you often extract single digit variables, you could create

  package My::Untaint::digit;
  use base 'CGI::Untaint::object';
  sub _untaint_re { qr/^(\d)$/ }
  1;

You should specify the path 'My::Untaint' in the INCLUDE_PATH configuration option. (See new() above.)

When extract() is called CGI::Untaint will also check to see if you have an is_valid() method also, and if so will run this against the value extracted from the regular expression (available as $self->value).

If this returns a true value, then the extracted value will be returned, otherwise we return undef.

is_valid() can also modify the value being returned, by assigning
$self->value($new_value)

e.g. in the above example, if you sometimes need to ensure that the digit extracted is prime, you would supply:

  sub is_valid { (1 x shift->value) !~ /^1?$|^(11+?)\1+$/ };

Now, when users call extract(), it will also check that the value is valid(), i.e. prime:

  my $number = $handler->extract(-as_digit => 'value');

A user wishing to skip the validation, but still ensure untainting can call

  my $number = $handler->extract(-as_like_digit => 'value');

AVAILABLE HANDLERS¶

This package comes with the following simplistic handlers:

  printable  - a printable string
  integer    - an integer
  hex        - a hexadecimal number (as a string)

To really make this work for you you either need to write, or download from CPAN, other handlers. Some of the handlers available on CPAN include:

  asin         - an Amazon ID
  boolean      - boolean value
  country      - a country code or name
  creditcard   - a credit card number
  date         - a date (into a Date::Simple)
  datetime     - a date (into a DateTime)
  email        - an email address
  hostname     - a DNS host name
  html         - sanitized HTML
  ipaddress    - an IP address
  isbn         - an ISBN
  uk_postcode  - a UK Postcode
  url          - a URL
  zipcode      - a US zipcode

BUGS¶

None known yet.

SEE ALSO¶

CGI. perlsec. Test::CGI::Untaint.

AUTHOR¶

Tony Bowden

BUGS and QUERIES¶

Please direct all correspondence regarding this module to:
bug-CGI-Untaint@rt.cpan.org

COPYRIGHT and LICENSE¶

Copyright (C) 2001-2005 Tony Bowden. All rights reserved.

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