PERL CGI HOWTO

------------------------------------------------------------------------------
INTRODUCTION

CGI stands for "Common Gateway Interface".
CGI programs can be written in any language, as long
as they produce output conforming to the CGI protocol.
CGI programs reside on a web server. CGI programs are activated by
a request a web user makes through a web browser, typically 
by submitting a form on a web page. CGI programs run on the web server
and produce an output that the web server will send back to the web browser 
that activated the program. That output can contain HTML/XHTML/XML
and will be displayed by the browser.
Web pages created by running programs are called "dynamic",
as opposed to "static web pages" which reside in HTML/XHTML/XML files.

Perl with the CGI module is often used for writing CGI programs;

------------------------------------------------------------------------------
FILE EXTENSIONS

Some web servers, including ours, are configured to 
recognize a CGI program by the file extension .cgi

Some web servers (other than ours) are configured to look for cgi programs
only in a specific directory such as public_html/cgi/ 
in such cases CGI program files do not need any extension.

------------------------------------------------------------------------------
CGI PROGRAM TEMPLATE

#!/usr/local/perl -wT
use strict;
use CGI qw(:standard);
use CGI::Carp qw(warningsToBrowser fatalsToBrowser); # comment this line out
            # before placing the program on a publicly visible web server.

print header;
print start_html("Phonebook");
print h1("My Phonebook");
if (param()) {
  my $name = param("name");
  if ($name !~ m/(^[a-zA-Z0-9 .-]{2,50})$/) {
    print "<p><strong> ERROR: The name may contain only letters\n"
          . "digits, spaces, periods and dashes.</strong></p>\n";
  } else {
    $name = $1; # $name has been laundered; it is no longer tainted.
    # process $name
  }
} else {
  # print an html form
}
print end_html;

------------------------------------------------------------------------------
SECURITY IN CGI PROGRAMS

1. Use -T option in the first line of the file:
   #!/usr/local/perl -wT
   With this you will get messages error messages 
   concerning insecure operations of your program.
   If -T produces an error message and you do not know
   how to fix the error, it would be very hazardous to web server security
   to remove the -T option and
   place your uncorrected program on a publicly visible web server.

2. Every string that comes from html forms 
   should be checked for correctness using pattern matching.
   This check should be done in the CGI program, even if
   a client side code (say, JavaScript) already completed a similar check.
   For instance:
   
   my $name = param("name");
   if ($name !~ m/(^[a-zA-Z0-9 .-]+)$/) {
      print "<p><strong>ERROR: The name may contain only letters\n", 
            "digits, spaces, periods and dashes.</strong></p>\n";
   } else {
      # process $name
   }
   
   This is used to prevent hackers who invoke your program in a web browser
   to store ARBITRARY data on the server or to execute ARBITRARY
   commands.

3. Check the length of every string which comes from html forms;
   if it is too long, do not process it and do not store it.
   You do not want hackers to slow down the server or to clog its disk with
   gigabytes of data dumped into, say, a "name" filed in an HTML form.

4. Before the program becomes publicly available 
   for running from web browsers, comment out the Carp line:
   # use CGI::Carp qw(warningsToBrowser fatalsToBrowser);
   otherwise warning/error messages about errors you missed while
   testing the program could disclose server configuration details to hackers.

5. Do not use the GET method in HTML forms. Use POST instead.
   Parameters sent via GET method are visible as a part of the URL
   in the browser window, after the form has been submitted.
   A string typed into a password field of a form
   will not be visible in the field, but you do not want it to become
   visible as a part of the URL, in case somebody is watching the screen
   over a shoulder of the user who typed the password.
 
6. If data transferred between a browser and a server is sensitive
   (passwords, credit card numbers, dates of birth, etc.)
   place your program on a secure (https) server, not a regular server
   (http). Only https encodes data before transmissions.

------------------------------------------------------------------------------
CHECKING SYNTAX

To check the syntax in myProgramFile.cgi type at the shell prompt:

	perl -cT myProgramFile.cgi

------------------------------------------------------------------------------
TESTING CGI PROGRAMS IN THE SHELL

To run a CGI program in the shell providing parameters
which otherwise would be sent by the POST method
use this syntax:

    myProgramFile.cgi parameter1=value1 parameter2=value2

------------------------------------------------------------------------------
FURTHER READING

Look up chapters on CGI and web in 
"Perl Cookbook", following links from instructor's web page.

------------------------------------------------------------------------------