Stronghold 2.1 Administration Guide: Common Gateway Interface

Chapter 10
Common Gateway Interface

The Common Gateway Interface (CGI) is a language-independent gateway between a Web server and other programs on the same platform. CGI can invoke executables on your platform and pass variables to it, then return the output to the client. This chapter discusses CGI topics, including

environment variables

CGI error logging

CGI security

FastCGI

Stronghold comes with two different CGI modules:

The regular CGI module implements traditional CGI functionality that invokes single-request programs, waits for them to die, then passes the output back to the server core. This module is compiled by default.

The optional FastCGI module implements high-performance CGI that keeps programs running and waiting for input, eliminating the overhead of starting, initializing, and killing programs.

Both modules give you the flexibility to write your Web applications in C, Perl, Java, Python, ksh, tsh, csh, or any other UNIX programming language. Both can execute either a binary program or a script (assuming you have an appropriate interpreter). Both binaries and scripts behave identically in the CGI environment, and for the purposes of this chapter we will refer to both as programs.

Environment Variables

Environment variables provide input for CGI programs. The value of an environment variable can depend on the server, the server platform, the state of the system, the date or time, or HTML form input. With Stronghold 2.0, environment variables can also depend on the browser used for the current request.

Server Variables

These variables pertain to the server software and its current configuration.

SERVER_SOFTWARE=Stronghold/2.0

The name and version number of the server software

GATEWAY_INTERFACE=CGI/1.1

The name and version number of your CGI gateway, which does not change unless you switch to a different version of the CGI module

SERVER_ADMIN=email-address

The server administrator's email address or other information, from httpd.conf

SERVER_ROOT=path

The path to the ServerRoot directory, from httpd.conf

DOCUMENT_ROOT=path

The root directory for Web documents, from httpd.conf

Request Variables

These variables are derived from the HTTP headers of client requests. Their values vary with the client software and the nature of the request.

SERVER_NAME=host

The host being addressed in this request, which may be the main host or a virtual host, either as a fully-qualified domain name or an IP address

HTTP_HOST=host

The same as SERVER_NAME

HTTP_ACCEPT=MIME-type[, MIME-type, MIME-type . . .]

One or more MIME types that the client can accept

HTTP_USER_AGENT=name/version (platform)

The name, version number, and platform of the client software

SERVER_PORT=port

The port number to which the request was sent

REMOTE_HOST=host

The hostname or IP number of the client host or proxy server that originated the request

NOTE: This is only set if Stronghold is not compiled with MINIMAL_DNS, or if HostnameLookups is set to "off."

REMOTE_PORT=port

The client-side port number that originated the request

REMOTE_ADDR=IP

The IP number of the client host

REMOTE_USER=username

The remote username, if the script is subject to basic authentication

REMOTE_IDENT=ident

The remote username as supplied by identd, if available

NOTE: This is only set if IdentityCheck is set to "on."

SERVER_PROTOCOL=protocol/version

The protocol and version number used to send the request, which Stronghold also uses in its response in order to ensure compatibility with the client

REQUEST_METHOD=method

The method used in this request, such as GET or POST

AUTH_TYPE=method

The authentication method used in this request, if any

CONTENT_TYPE=MIME-type

The MIME type of any data attached to the request header

CONTENT_LENGTH=n

The size, in bytes, of any data attached to the request header

SCRIPT_NAME=path/to/script

The URI of the requested script

SCRIPT_FILENAME=absolute/path/to/script

The absolute path to the requested script

SCRIPT_URI=method://host/path/to/script

The URI of the requested script

SCRIPT_URL=path/to/script

The URL of the requested script

QUERY_STRING=string

The query-string for this transaction, embedded in the requested URL

PATH_INFO=info

Extra path information submitted in the request URL and used as input to a CGI program

PATH_TRANSLATED=path

The absolute path of the requested file, if the value of PATH_INFO can be translated to a file

SSL Protocol Variables

These variables are specific to SSL.

SSL_PROTOCOL_VERSION=2|3

The version of SSL used in this transaction, either version 2 or 3

SSLEAY_VERSION=n

The current version of SSLeay

HTTPS=on|off

"On" or "off," depending on whether SSL is turned on

HTTPS_SECRETKEYSIZE=n

The size, in bytes, of the server's private key

HTTPS_KEYSIZE=n

The full size, in bytes, of the server's public key

NOTE: This is different from SECRETKEYSIZE only if you are using an export-crippled cryptography scheme.

HTTPS_CIPHER=cipher

Same as SSL_CIPHER

HTTPS_EXPORT=true|false

"False" if the session uses a cipher that is restricted for export, "true" if it uses an exportable (crippled) cipher

SSL_SERVER_SESSIONDIR=path

The session caching directory, if applicable

SSL_SERVER_CERTIFICATELOGDIR=path

The directory where Stronghold logs client certificates

SSL_CIPHER=cipher

The type of cipher used for the current session

SSL Server Variables

SSL_SERVER_CERTFILE=filename

The server's certificate file

SSL_SERVER_KEYFILE=filename

The server's private key file

SSL_SERVER_KEYFILETYPE=PEM

The format of the server's public key file; only PEM is supported

SSL_SERVER_KEY_SIZE=n

The size, in bytes, of the server's public key

SSL_SERVER_KEY_ALGORITHM=algorithm

The algorithm used to generate the server's public key

SSL_SERVER_KEY_EXP=expiry-time

The expiration date of the server's public key, in ASN1 format

SSL_SERVER_CERTIFICATE=hash

A hash of the certificate

SSL_SERVER_CERT_START=date

The date on which the server certificate becomes valid, in ASN1 format

SSL_SERVER_CERT_END=date

The date on which the server certificate is no longer valid

SSL_SERVER_EMAIL=email-address

The email address of the server administrator

SSL_SERVER_O=organization

The name of the organization to which the server certificate belongs

SSL_SERVER_C=country-code

The two-character code for the country in which the server resides

SSL_SERVER_SP=state|province

The state or province in which the server resides

SSL_SERVER_L=locality

The locality, such as a town or city, in which the server resides

SSL_SERVER_SIGNATURE_ALGORITHM=algorithm

The algorithm used the sign the server's certificate

SSL_SERVER_IO=CA

Issuer Organization, the name of the Certification Authority (CA) that issued the server's certificate

SSL_SERVER_IOU=organizational-unit

Issuer Organizational Unit, the name of the organizational unit of the CA that issued the server certificate

SSL_SERVER_IEMAIL=email-address

Issuer Email, the contact email address of the CA that signed the server certificate

SSL_SERVER_ICN=hostname

Issuer Common Name, the hostname of the CA that issued the server certificate

SSL_SERVER_IL=locality

Issuer Locality, the locality of the CA that issued the server certificate

SSL_SERVER_ISP=state|province

Issuer State/Province, the state or province of the CA that issued the server certificate

SSL_SERVER_IC=country-code

Issuer Country, the two-character code for the country in which the CA that issued the server certificate resides

SSL Client Variables

SSL_CLIENT_KEY_ALGORITHM=algorithm

The algorithm used to generate the client's public key

SSL_CLIENT_KEY_SIZE=n

The size, in bytes, of the client's public key

SSL_CLIENT_KEY_EXP=expiry-time

Expiration date of the client's certificate, in ASN1 format

SSL_CLIENT_CERTIFICATE=hash

A hash of the client's certificate

SSL_CLIENT_CN=name

The name of the client certificate's bearer

SSL_CLIENT_EMAIL=email-address

The email address of the client certificate's bearer

SSL_CLIENT_OU=organizational-unit

The organizational unit of the client certificate's bearer

SSL_CLIENT_C=country-code

The two-character code for the country in client resides

SSL_CLIENT_SP=state|province

The state or province in which the client resides

SSL_CLIENT_L=locality

The locality, such as a city or town, in which the client resides

SSL_CLIENT_CERT_START=date

The date on which the client's certificate becomes valid, in ASN1 format

SSL_CLIENT_CERT_END=date

The date on which the client's certificate is no longer valid, in ASN1 format

SSL_CLIENT_O=organization

The name of the organization to which the client belongs

SSL_CLIENT_IO=CA

The name of the CA that issued the client certificate

SSL_CLIENT_IOU=organizational-unit

The name of the organizational unit of the CA that issued the client certificate

SSL_CLIENT_IEMAIL=email-address

The contact email address of the CA that issued the client certificate

SSL_CLIENT_IC=country-code

The country in which the CA that issued the client certificate resides

SSL_CLIENT_IL=locality

The locality, such as a city or town, of the CA that issued the client certificate

SSL_CLIENT_ICN=hostname

The hostname of the CA that issued the client certificate

SSL_CLIENT_ISP=state|province

The state or province of the CA that issued the client certificate

SSL_CLIENT_SIGNATURE_ALGORITHM=algorithm

The algorithm used to sign the client certificate

Browser-Dependent Variables

Stronghold 2.0 includes a module for browser-dependent environment variables. This modules uses the User-Agent HTTP header field to detect the browser used for the client request, then sets environment variables according to the rules you set with the BrowserMatch and BrowserMatchNoCase directives, described in "Environment Variables" on page 3-10.

CGI Error Logging

For debugging purposes, the CGI module logs standard error data if the ScriptLog directive is set. Each error entry begins with two lines with this format:

%% [time] request-line
%% HTTP-status-code CGI-script-filename

These lines are followed by more specific error information, depending on the nature of the error. If CGI cannot start the script at all, the body of the error entry looks like this:

%%error
error-message

If the script returns incorrect header information, the body of the error entry looks like this:

%request
request-header(s) received by the script
%response
response-header(s) output by the script
%stdout
CGI-standard-output
%stderr
CGI-standard-error

If the script does not output anything on stdout or stderr, those fields may be empty.

CGI Security

Two characteristics of CGI pose security issues for your server:

CGI executes programs on the server platform.

Intruders can access CGI programs directly, bypassing any HTML interface.

Since CGI executes programs at the request of users, intruders can arbitrarily invoke programs that can directly influence your platform. By manipulating the input, a clever hacker can turn a benign program into a tool that threatens the integrity of your log files, user accounts, or programs. By bypassing the HTML interface to a CGI program, an intruder avoids its constraints and can freely enter manipulative data or view "hidden" data fields.

Authoring Tips

This section offers some authoring tips that can help you avoid potential security weaknesses on your system:

Exercise extreme caution when using system(), popen(), eval(), pipes, and backquotes.

In all CGI programs, check the input for invalid values, such as selection list values not included in the original list, or values that exceed the length you specified in your HTML form.

Reject variables whose names are not already defined in the program.

Reject hidden fields that your program did not create.

Reject unescaped control characters.

If your program must spawn a child process, avoid passing user input to that process. If you must, be sure to filter out meta characters.

If your program allows users to send mail, use /usr/lib/sendmail. Never use /bin/mailx or /usr/ucb/mail.

If you allow users on your system to use their own CGI programs, screen them carefully before posting them to the CGI directory.

Secure the CGI directory so that only an administrator can add, remove, or modify programs.

Delete all backup files that your editor creates while you are authoring programs, and advise users on your system to do the same.

Although "security through obscurity" is generally inadvisable, it is a very good idea where CGI programs are concerned. Do not allow users to read the CGI programs on your server platform, and do not allow anonymous FTP access to the CGI directory.

Exercise caution when using CGI programs written by others. If you download a CGI program from a remote site, examine it carefully before implementing it on your own site.

suEXEC

Stronghold 2.0 can run CGI programs under user IDs (UIDs) other than its own. For example, if your site hosts a number of users, some of whom have their own CGI programs, Stronghold can execute these under the UIDs of their owners. The suEXEC CGI wrapper provides this functionality.

When CGI programs are confined to the UIDs of their owners, weaknesses cannot be exploited outside the realm of that user's directories and files. In addition, the suEXEC wrapper uses these rules for added security:

The UID of the current CGI program must be a valid user on your system.

The UID of the current CGI program must be the HTTPD_USER.

The command being executed must not contain a slash (/).

The command being executed must reside in the DOC_ROOT.

The current working directory must be an actual directory.

The current working directory must not be writable by group or other.

The command being executed must not be a symbolic link.

The command being executed must not be writable by group or other.

The command being executed must not be a setuid or setgid program.

The target UID and group ID (GID) must be a valid user and group on your system.

The target UID and GID must match the UID and GID of the current working directory.

The target UID and GID must not be root.

These rules shore up many of the security weaknesses that CGI normally poses.

This is an advanced feature; use it with caution. If you configure it improperly, suEXEC can severely compromise the security of your site. However, if you are familiar with setuid programs and their security issues, and you configure suEXEC properly, it reinforces your site's security considerably.

To compile Stronghold with suEXEC

Edit ServerRoot/support/suexec.h so that the following macros match your server configuration:

HTTPD_USER

The UID of the server process. Only this user is allowed to execute suEXEC. The value must be the same as that of the User directive, usually "nobody."

LOG_EXEC

The path to the suEXEC error log file. Use a separate error file to isolate suEXEC errors.

DOC_ROOT

Stronghold's root document directory, and it should match the value for DocumentRoot. Only this directory and the user directories can use suEXEC.

NNAME

The name of the "nobody" account on your system. In most cases, this is simply "nobody."

NGID

The group number for your system's group "nobody," sometimes called "nogroup." In most cases, this is -1 or -2. If not, it is a number above 65000.

Compile suEXEC:

# gcc suexec.c -o suexec

Add the following line to the Makefile Configuration section of ServerRoot/src/Configuration:

EXTRA_FLAGS= -DSUEXEC_BIN="/path/to/suexec"

Recompile Stronghold according to the instructions in "Recompiling Stronghold" on page 4-6.

Move the suEXEC executable you created in step 2 to the location specified in step 3.

Set the setuid bit:

# chown root suexec
# chmod 4711 suexec

Start Stronghold.

On startup, the server should print the following line:

Configuring Apache for use with suexec wrapper.

Stronghold can now implement suEXEC. However, if this line does not appear, suEXEC is incorrectly configured.

With suEXEC in place, Stronghold sets the UID of each CGI program to that of the user directory in which the program resides. For CGI programs that belong to a virtual host, use the User and Group directives to set the UID for that host's CGI programs.

FastCGI

FastCGI eliminates the performance compromise traditionally accepted in CGI, while retaining the flexibility to integrate a wide variety of Web applications into your site. Rather than starting a program each time it is requested, FastCGI keeps all of its programs running and waiting for input. Like CGI, it passes variables to the programs via standard input, waits for the result to return via standard output, and passes the output back to the server core, which sends it to the client.

The most important implication of this scheme is that most existing CGI programs are incompatible with FastCGI. Many CGI programs are written to process a single request, pass the output to CGI, and then die. Rewriting existing CGI programs to handle multiple requests indefinitely can be time-consuming, but the performance rewards are well worthwhile, especially on a high-traffic site where response time is critical.

Stronghold includes an optional FastCGI module. See http://www.fastcgi.com/words/ for complete FastCGI documentation and specifications.

Before you use FastCGI, you must do three things:

Create a separate directory for FastCGI applications, such as fcgi-bin/. You cannot place FastCGI application files in cgi-bin/ because the ScriptAlias directive associates the contents of that directory with the regular CGI module.

Create a directory for sockets, which FastCGI creates and uses to communicate with its programs.

Add the following directives to httpd.conf:

AppClass directives specify the FastCGI programs that start up with the server. For example:

AppClass fcgi-bin/app1.fcg -initial-env TIMEZONE=PST

For a complete list of flags for the AppClass directive, see "FastCGI" on page 3-12.

FastCgiIpcDir sets the directory where FastCGI creates sockets for these programs. The default is /tmp, but if your system periodically purges /tmp, you should create a separate directory for sockets that is readable, writable, and searchable by Stronghold.

Add a new MIME type to httpd.conf for FastCGI:

AddType application/x-httpd-fcgi .fcg

With these modifications, you are ready to use FastCGI. You can download FastCGI application libraries at http://www.fastcgi.com/applibs/. When you create FastCGI programs, be sure to

give them the .fcg filename suffix,

save them in the directory you created, and

enter each one in httpd.conf with an AppClass directive.

[Top] [Prev] [Next] [Last]
© 1997 C2Net International
Feedback: stronghold-docs@c2.net