CGI::Untaint(3pm)

💖 CGI::Untaint — process CGI input parameters 💖

okay bestie, gather round, because this one is a whole moment. it's CGI::Untaint, it lives in the User Contributed Perl Documentation section (manual page CGI::Untaint(3pm), yes we're fancy), and it is here to make form input stop being your villain origin story. 🎀

---

✨ SYNOPSIS ✨

like, here's the vibe:

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 🌸

bestie, dealing with big web apps that have, like, a million forms is genuinely a minefield. 💀 it's already hard enough to make sure you validate all your input at all, without also having to stress about doing it in a consistent way. and the second any of your validation rules change? suddenly you're editing them in like twelve different places. and if you wanna operate taint-safe on top of all that? that's just adding even more headaches, no cap.

this module gives you a simple, convenient, abstracted and extensible way to validate and untaint the input from your web forms. it's giving "finally, someone gets me". 🫶

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

---

🧚 CONSTRUCTOR 🧚

new

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

the simplest way to construct an input handler is to pass a hash of parameters (usually $q->Vars) to new(). each parameter will then be extractable later by calling an extract() method on it. slay.

however, you can also pass a leading reference to a hash of configuration variables. 💅

currently the only such variable supported is 'INCLUDE_PATH', which lets you specify a local path in which to find extraction handlers. see "LOCAL EXTRACTION HANDLERS". iykyk.

---

👑 METHODS 👑

extract

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

once you've constructed your Input Handler, you call the extract method on each piece of data you care about. 💖

it takes an -as_whatever flag to state what type of data you require. this will check that the input value correctly matches the required specification, and return an untainted value. then it'll call the is_valid() method, where applicable, to make sure this doesn't just look like a valid value, but actually is one. the way that it double-checks?? obsessed.

if you wanna skip that stage, then you can call -as_like_whatever, which performs the untainting but not the validation. 🌈

error

my $error = $handler->error;

if the validation failed, this returns the reason why. it's giving receipts. 🍓

---

🦋 LOCAL EXTRACTION HANDLERS 🦋

as well as the handlers supplied with this module for extracting data, you can also create your own. in general these should inherit from 'CGI::Untaint::object', and they 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 too, and if so it'll 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');

Test::CGI::Untaint

if you create your own local handlers, then you may wish to explore Test::CGI::Untaint, available from the CPAN. this makes it very easy to write tests for your handler. (thanks to Profero Ltd.) 🫶

---

🌸 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

not the CPAN having the whole range?? iconic behavior fr fr. 💅

---

💀 BUGS 💀

none known yet. (bestie is flawless, we fear her.) 🙈

---

🔥 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.

---

and that's the whole page, bestie. 🌟 this gem is perl v5.34.0, dated 2022-06-10, and it goes by CGI::Untaint(3pm) — go untaint something and stay hydrated. 🎀💖