suidcgi - a set UID wrapper for CGI scripts.
============================================

Contents
--------

1.0 Introduction
2.0 Using suidcgi
    2.1 Using suidcgi with perl scripts
3.0 Security
    3.1 Built in security measures
    3.2 Your security measures
4.0 Author


1.0 Introduction
----------------

When users access CGI scripts from your home page, the scripts are
executed by the Web server at your site. The server is normally run as
a dedicated user such as "www", or as the special low-privileged user
"nobody". This means that the Web server has no more access to your
files than any other users on the local system. If you want the server
to read or write some files on behalf of your CGI scripts, you will
also have to grant every other user access to the same files (unless,
of course, you are a system administrator that may change the
ownership of files). Most people aren't comfortable with having
globally writable files laying around.

suidcgi tries to overcome the problem of globally available files by
functioning as a set UID wrapper for your scripts. Programs running as
set UID programs, will be run as the _owner_ of the program file,
rather than as the one executing the program. When the Web server
starts suidcgi, the operating system will change the current user ID
from that of the server to yours. When suidcgi launches the actual CGI
script, it will be running as you, thus accessing all files as if you
were running the program.


2.0 Using suidcgi
-----------------

Please make sure you read the "Security" section below before you
start using the program!

The suidcgi program is supposed to be installed where you have your
CGI scripts. suidcgi uses the name by which it was started to
determine what script to start: It looks for files in the same
directory with the same name, but with a different extension. The
possible extensions are defined in `config.h' at compile time.

Let's say you have a CGI script called `count.cgi' that you want to
wrap inside suidcgi. Rename the script to something with an
appropriate extension, such as `count.pl' if it is a perl script, and
create a (possibly symbolic) link from `suidcgi' to `count.cgi'. When
the Web server is ordered to load `count.cgi', it starts suidcgi,
which in turn searches for other files named `count.*' in the same
directory. It locates `count.pl' and executes that program, running as
the user owning suidcgi.

2.1 Using suidcgi with perl scripts
-----------------------------------

When perl notices it is running a set UID script, it gets quite
paranoid and starts doing "taint checks" on everything. Most notably,
imported environment variables are considered dirty, and any operation
built on environment variables are taken as security threats, and are
thus aborted. If you run into this problem (you probably do), you will
have to "clean" the tainted variables using the following subroutine
(assuming perl 5):

	sub unTaint {
	    my($s) = @_;

	    $s =~ /^(.*)$/;
	    return $1;
	}

The problem is most notable when your script tries to run a separate
program. Perl assumes the environment variables PATH and IFS may be
set incorrectly, and breaks the program. However, both variables are
set by suidcgi, and are hopefully trustworthy. You may clean them
using the calls

	$ENV{PATH} = &unTaint($ENV{PATH});
	$ENV{IFS} = &unTaint($ENV{IFS});

Note that to be able to find the reason why perl aborted your script,
you may need access to the Web server's error log file.


3.0 Security
------------

First of all: suidcgi will _not_ prevent clever, local users from
running your CGI scripts. Any user who can gain access to the Web
server user, will be able to run your scripts. Gaining that access may
be quite easy if you know what to do. This means that you should be
very careful with what actions you allow your scripts to perform.

3.1 Built in security measures
------------------------------

The following precautions are taken by suidcgi to minimize the risk
that someone abuses your scripts:

* suidcgi may only be run by the user owning it, or by the Web server
  user. As mentioned above, any user may actually get access to the
  Web server account.

* The environment variables PATH and IFS are both initialized, to
  prevent attacks with preset variables. Undefined PATH and IFS makes
  up a well known security hole in set UID scripts.

* Programs not owned by the owner of suidcgi will not be run. This
  prevents people from putting their own files in your www directory
  (if you left it writable for some reason), and running them as you.

* Programs writable by others than the owner of suidcgi will not be
  run. People may change your scripts to do something harmful.

* Programs not in your www directory, or any of its subdirectories,
  will not be run. Otherwise, people could run _every_ program as you.

3.2 Your security measures
--------------------------

You may help suidcgi to operate securely by taking the following
precautions:

* Keep in mind that _anyone_ on the local system may run your scripts
  if they gain access to the Web server user.

* Tell the system administrator to periodically search for programs
  owned by the Web user, having the set UID bit set. Such programs are
  possible entry points for people abusing the Web server account.

* Don't run set UID more than necessary. If your script is written in
  perl, you may "turn off" set UID by issuing the following command:

	$> = $<;    # effective UID = real UID

* Don't let scripts execute programs of which you don't have full
  control. If an executed program spawns a shell, it will be running
  as you.

* Don't make your scripts readable to everyone, keep them executable
  only. This may prevent attacks due to known weakness in your
  scripts.

Note to system administrators: Allowing local users to create CGI
scripts, implies security problems. If you do, files accessed by CGI
scripts are in fact available to everyone. But heck, World Wide Web
wouldn't be any fun without CGI scripts. :)


4.0 Author
----------

The program is written by

        Sverre H. Huseby        sverrehu@online.no
        Kurvn. 30               http://home.sol.no/~sverrehu/
        N-0495 Oslo
        Norway

You can use and copy this for _free_, but I would be very happy if you
send me an E-mail and tell me that you use it. If you insist on paying
something, please donate some money to an organization that strives to
make the world a better place for everyone.

I don't like bugs, so please help me removing them by reporting
whatever you find!

