/ 
CGI-Safe-1.25
River stage one • 1 direct dependent • 1 total dependent
/ CGI::Safe

NAME

CGI::Safe - Safe method of using CGI.pm. This is pretty much a two-line change for most CGI scripts.

SYNOPSIS

use CGI::Safe qw/ taint /;
my $q = CGI::Safe->new;

DESCRIPTION

If you've been working with CGI.pm for any length of time, you know that it allows uploads by default and does not have a maximum post size. Since it saves the uploads as a temp file, someone can simply upload enough data to fill up your hard drive to initiate a DOS attack. To prevent this, we're regularly warned to include the following two lines at the top of our CGI scripts:

$CGI::DISABLE_UPLOADS = 1;          # Disable uploads
$CGI::POST_MAX        = 512 * 1024; # limit posts to 512K max

As long as those are their before you instantiate a CGI object (or before you access param and related CGI functions with the function oriented interface), you have pretty safely plugged this problem. However, most CGI scripts don't have these lines of code. Some suggest changing these settings directly in CGI.pm. I dislike this for two reasons:

  • If you upgrade CGI.pm, you might forget to make the change to the new version.

  • You may break a lot of existing code (which may or may not be a good thing depending upon the security implications).

Hence, the CGI::Safe module. It will establish the defaults for those variables and require virtually no code changes. Additionally, it will delete %ENV variables listed in perlsec as dangerous. The $ENV{ PATH } and $ENV{ SHELL } are explicitly set in the INIT method to ensure that they are not tainted. These may be overriden by passing named args to the CGI::Safe's constructor or by setting them manually.

METHODS

new

my $cgi = CGI::Safe->new;
my $cgi = CGI::Safe->new( %args );

Contructor for a new CGI::Safe object. See "USAGE DETAILS" for more information about which arguments are accepted and how they are used.

set

CGI::Safe->set( DISABLE_UPLOADS => 0, POST_MAX => 1_024 * 1_024 );
my $cgi = CGI::Safe->new;

Class method which sets the value for DISABLE_UPLOADS and POST_MAX. Calling this method after the constructor is effectively a no-op.

get_path

my $path = $cgi->get_path;

Returns the original $ENV{'PATH'} value. This value is tainted.

get_shell

my $path = $cgi->get_path;

Returns the original $ENV{'SHELL'} value. This value is tainted.

USAGE DETAILS

Some people prefer the object oriented interface for CGI.pm and others prefer the function oriented interface. Naturally, the CGI::Safe module allows both.

use CGI::Safe qw/ taint /;
my $q = CGI::Safe->new( DISABLE_UPLOADS => 0 );

Or:

use CGI::Safe qw/ :standard taint /;
$CGI::DISABLE_UPLOADS = 0;

Uploads and Maximum post size

As mentioned earlier, most scripts that do not need uploading should have something like the following at the start of their code to disable uploads:

$CGI::DISABLE_UPLOADS = 1;          # Disable uploads
$CGI::POST_MAX        = 512 * 1024; # limit posts to 512K max

The CGI::Safe sets these values in an BEGIN{} block. If necessary, the programmer can override these values two different ways. When using the function oriented interface, if needing file uploads and wanting to allow up to a 1 megabyte upload, they would set these values directly before using any of the CGI.pm CGI functions:

use CGI::Safe qw/ :standard taint /;
$CGI::DISABLE_UPLOADS = 0;
$CGI::POST_MAX        = 1_024 * 1_024; # limit posts to 1 meg max

If using the OO interface, you can set these explicitly or pass them as parameters to the CGI::Safe constructor:

use CGI::Safe qw/ taint /;
my $q = CGI::Safe->new(
    DISABLE_UPLOADS => 0,
    POST_MAX        => 1_024 * 1_024 );

CGI.pm objects from input files and other sources

You can instantiate a new CGI.pm object from an input file, properly formatted query string passed directly to the object, or even a has with name value pairs representing the query string. To use this functionality with the CGI::Safe module, pass this extra information in the source key:

use CGI::Safe qw/ taint /;
my $q = CGI::Safe->new( source = $some_file_handle );

Alternatively:

use CGI::Safe qw/ taint /;
my $q = CGI::Safe->new( source => 'color=red&name=Ovid' );

CGI::Safe::set

As of CGI::Safe::VERSION 1.1, this is a new method which allows the client a cleaner method of setting the $CGI::POST_MAX and $CGI::DISABLE_UPLOADS variables. As expected, you may use this with both the OO or function-oriented interface. When used with the OO interface, it should be treated as a class method and called before instantiation of the CGI object.

use CGI::Safe qw/ taint /;
CGI::Safe->set( DISABLE_UPLOADS => 0, POST_MAX => 1_024 * 1_024 );
my $q = CGI::Safe->new;

This is equivalent to the following:

use CGI::Safe qw/ taint /;
my $q = CGI::Safe->new(
    DISABLE_UPLOADS => 0,
    POST_MAX        => 1_024 * 1_024 );

When using the function oriented interface, the set method is imported into the client's namespace whenever :standard or :cgi is imported. The set must be called prior to using the cgi methods.

use CGI::Safe qw/:standard taint /;
set( POST_MAX => 512 * 1024 );

Since the set method is imported into your namespace, you should be aware of the possibility of namespace collisions. If you already have a subroutine named set, you should either rename the subroutine or consider using the OO interface to CGI::Safe.

admin

If you are running your own Web server and you find deleting the $ENV{PATH} and $ENV{SHELL} variables too restrictive, you can declare yourself to be the administrator and have those variables restored. Simply add admin to the import list:

use CGI::Safe we/admin taint/;

Those variables will be restored, but they will still be tainted and it is your responsibility to ensure that this is done properly. Don't use this feature unless you know exactly what you are doing. Period.

CGI::get_shell and CGI::get_path

These two methods/functions will return the original shell and path, respectively. These are, of course, tainted. If either :standard or :cgi is specified in the import list, these will be exported into the caller's namespace. These are provided in case you need them. Once again, don't use 'em if you're unsure of yourself.

TODO

You've probably noticed by now that all instances of CGI::Safe list taint in the import list. This is because the next major release of this module is intended to allow for much easier untainting of form data and cookies. Specifying taint in the import list, in that release, will tell CGI::Safe that nothing is to be untainted. As that is the default behavior, at the present time, I wanted you to get used to it so future releases wouldn't break your code.

Perlmonks

Many thanks to the wonderful Monks at Perlmonks.org for holding my hand while I learned Perl. There are far too many to name here. Two, however, deserve special thanks:

Ben Tilly. http://www.perlmonks.org/index.pl?node_id=26179. I thought I was a good programmer until I started reading his stuff. I've learned more about programming from him than almost any other source.

Tye McQueen. tye@metronet.com http://www.perlmonks.org/index.pl?node_id=22609. Tye, in addition to being an excellent programmer, gave me good feedback about this module and future releases will be heavily incorporating some of his suggestions. Tye is also sometimes known as "Lord Throll, Konqueror of..."... oh, wait, he told me not to say that.

COPYRIGHT

Copyright (c) 2001 Curtis "Ovid" Poe. All rights reserved. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself

AUTHOR

Curtis "Ovid" Poe <poec@yahoo.com> Address bug reports and comments to: poec@yahoo.com. When sending bug reports, please provide the version of CGI.pm, the version of CGI::Safe, the version of Perl, and the version of the operating system you are using.

BUGS

2001/07/13 There are no known bugs at this time. However, I am somewhat concerned about the use of this module with the function oriented interface. CGI.pm uses objects internally, even when using the function oriented interface (which is part of the reason why the function oriented interface is not faster than the OO version).

SEE ALSO

CGI