Request for Comments: 3875 K. Coar
Category: Informational The Apache Software Foundation
October 2004
The Common Gateway Interface (CGI) Version 1.1
Status of this Memo
This memo provides information for the Internet community. It does
not specify an Internet standard of any kind. Distribution of this
memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2004).
IESG Note
This document is not a candidate for any level of Internet Standard.
The IETF disclaims any knowledge of the fitness of this document for
any purpose, and in particular notes that it has not had IETF review
for such things as security, congestion control or inappropriate
interaction with deployed protocols. The RFC Editor has chosen to
publish this document at its discretion. Readers of this document
should exercise caution in evaluating its value for implementation
and deployment.
Abstract
The Common Gateway Interface (CGI) is a simple interface for running
external programs, software or gateways under an information server
in a platform-independent manner. Currently, the supported
information servers are HTTP servers.
The interface has been in use by the World-Wide Web (WWW) since 1993.
This specification defines the ’current practice’ parameters of the
’CGI/1.1’ interface developed and documented at the U.S. National
Centre for Supercomputing Applications. This document also defines
the use of the CGI/1.1 interface on UNIX(R) and other, similar
systems.
Table of Contents
1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Requirements . . . . . . . . . . . . . . . . . . . . . . 4
1.3. Specifications . . . . . . . . . . . . . . . . . . . . . 4
1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . 5
2. Notational Conventions and Generic Grammar. . . . . . . . . . 5
2.1. Augmented BNF . . . . . . . . . . . . . . . . . . . . . 5
2.2. Basic Rules . . . . . . . . . . . . . . . . . . . . . . 6
2.3. URL Encoding . . . . . . . . . . . . . . . . . . . . . . 7
3. Invoking the Script . . . . . . . . . . . . . . . . . . . . . 8
3.1. Server Responsibilities . . . . . . . . . . . . . . . . 8
3.2. Script Selection . . . . . . . . . . . . . . . . . . . . 9
3.3. The Script-URI . . . . . . . . . . . . . . . . . . . . . 9
3.4. Execution . . . . . . . . . . . . . . . . . . . . . . . 10
4. The CGI Request . . . . . . . . . . . . . . . . . . . . . . . 10
4.1. Request Meta-Variables . . . . . . . . . . . . . . . . . 10
4.1.1. AUTH_TYPE. . . . . . . . . . . . . . . . . . . . 11
4.1.2. CONTENT_LENGTH . . . . . . . . . . . . . . . . . 12
4.1.3. CONTENT_TYPE . . . . . . . . . . . . . . . . . . 12
4.1.4. GATEWAY_INTERFACE. . . . . . . . . . . . . . . . 13
4.1.5. PATH_INFO. . . . . . . . . . . . . . . . . . . . 13
4.1.6. PATH_TRANSLATED. . . . . . . . . . . . . . . . . 14
4.1.7. QUERY_STRING . . . . . . . . . . . . . . . . . . 15
4.1.8. REMOTE_ADDR. . . . . . . . . . . . . . . . . . . 15
4.1.9. REMOTE_HOST. . . . . . . . . . . . . . . . . . . 16
4.1.10. REMOTE_IDENT . . . . . . . . . . . . . . . . . . 16
4.1.11. REMOTE_USER. . . . . . . . . . . . . . . . . . . 16
4.1.12. REQUEST_METHOD . . . . . . . . . . . . . . . . . 17
4.1.13. SCRIPT_NAME. . . . . . . . . . . . . . . . . . . 17
4.1.14. SERVER_NAME. . . . . . . . . . . . . . . . . . . 17
4.1.15. SERVER_PORT. . . . . . . . . . . . . . . . . . . 18
4.1.16. SERVER_PROTOCOL. . . . . . . . . . . . . . . . . 18
4.1.17. SERVER_SOFTWARE. . . . . . . . . . . . . . . . . 19
4.1.18. Protocol-Specific Meta-Variables . . . . . . . . 19
4.2. Request Message-Body . . . . . . . . . . . . . . . . . . 20
4.3. Request Methods . . . . . . . . . . . . . . . . . . . . 20
4.3.1. GET. . . . . . . . . . . . . . . . . . . . . . . 20
4.3.2. POST . . . . . . . . . . . . . . . . . . . . . . 21
4.3.3. HEAD . . . . . . . . . . . . . . . . . . . . . . 21
4.3.4. Protocol-Specific Methods. . . . . . . . . . . . 21
4.4. The Script Command Line. . . . . . . . . . . . . . . . . 21
5. NPH Scripts . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.1. Identification . . . . . . . . . . . . . . . . . . . . . 22
5.2. NPH Response . . . . . . . . . . . . . . . . . . . . . . 22
6. CGI Response. . . . . . . . . . . . . . . . . . . . . . . . . 23
6.1. Response Handling. . . . . . . . . . . . . . . . . . . . 23
6.2. Response Types . . . . . . . . . . . . . . . . . . . . . 23
6.2.1. Document Response. . . . . . . . . . . . . . . . 23
6.2.2. Local Redirect Response. . . . . . . . . . . . . 24
6.2.3. Client Redirect Response . . . . . . . . . . . . 24
6.2.4. Client Redirect Response with Document . . . . . 24
6.3. Response Header Fields . . . . . . . . . . . . . . . . . 25
6.3.1. Content-Type . . . . . . . . . . . . . . . . . . 25
6.3.2. Location . . . . . . . . . . . . . . . . . . . . 26
6.3.3. Status . . . . . . . . . . . . . . . . . . . . . 26
6.3.4. Protocol-Specific Header Fields. . . . . . . . . 27
6.3.5. Extension Header Fields. . . . . . . . . . . . . 27
6.4. Response Message-Body. . . . . . . . . . . . . . . . . . 28
7. System Specifications . . . . . . . . . . . . . . . . . . . . 28
7.1. AmigaDOS . . . . . . . . . . . . . . . . . . . . . . . . 28
7.2. UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . 28
7.3. EBCDIC/POSIX . . . . . . . . . . . . . . . . . . . . . . 29
8. Implementation. . . . . . . . . . . . . . . . . . . . . . . . 29
8.1. Recommendations for Servers. . . . . . . . . . . . . . . 29
8.2. Recommendations for Scripts. . . . . . . . . . . . . . . 30
9. Security Considerations . . . . . . . . . . . . . . . . . . . 30
9.1. Safe Methods . . . . . . . . . . . . . . . . . . . . . . 30
9.2. Header Fields Containing Sensitive Information . . . . . 31
9.3. Data Privacy . . . . . . . . . . . . . . . . . . . . . . 31
9.4. Information Security Model . . . . . . . . . . . . . . . 31
9.5. Script Interference with the Server. . . . . . . . . . . 31
9.6. Data Length and Buffering Considerations . . . . . . . . 32
9.7. Stateless Processing . . . . . . . . . . . . . . . . . . 32
9.8. Relative Paths . . . . . . . . . . . . . . . . . . . . . 33
9.9. Non-parsed Header Output . . . . . . . . . . . . . . . . 33
10. Acknowledgements. . . . . . . . . . . . . . . . . . . . . . . 33
11. References. . . . . . . . . . . . . . . . . . . . . . . . . . 33
11.1. Normative References. . . . . . . . . . . . . . . . . . 33
11.2. Informative References. . . . . . . . . . . . . . . . . 34
12. Authors’ Addresses. . . . . . . . . . . . . . . . . . . . . . 35
13. Full Copyright Statement. . . . . . . . . . . . . . . . . . . 36
1. Introduction
1.1. Purpose
The Common Gateway Interface (CGI) [22] allows an HTTP [1], [4]
server and a CGI script to share responsibility for responding to
client requests. The client request comprises a Uniform Resource
Identifier (URI) [11], a request method and various ancillary
information about the request provided by the transport protocol.
The CGI defines the abstract parameters, known as meta-variables,
which describe a client’s request. Together with a concrete
programmer interface this specifies a platform-independent interface
between the script and the HTTP server.
The server is responsible for managing connection, data transfer,
transport and network issues related to the client request, whereas
the CGI script handles the application issues, such as data access
and document processing.
1.2. Requirements
The key words ’MUST’, ’MUST NOT’, ’REQUIRED’, ’SHALL’, ’SHALL NOT’,
’SHOULD’, ’SHOULD NOT’, ’RECOMMENDED’, ’MAY’ and ’OPTIONAL’ in this
document are to be interpreted as described in BCP 14, RFC 2119 [3].
An implementation is not compliant if it fails to satisfy one or more
of the ’must’ requirements for the protocols it implements. An
implementation that satisfies all of the ’must’ and all of the
’should’ requirements for its features is said to be ’unconditionally
compliant’; one that satisfies all of the ’must’ requirements but not
all of the ’should’ requirements for its features is said to be
’conditionally compliant’.
1.3. Specifications
Not all of the functions and features of the CGI are defined in the
main part of this specification. The following phrases are used to
describe the features that are not specified:
’system-defined’
The feature may differ between systems, but must be the same for
different implementations using the same system. A system will
usually identify a class of operating systems. Some systems are
defined in section 7 of this document. New systems may be defined
by new specifications without revision of this document.
’implementation-defined’
The behaviour of the feature may vary from implementation to
implementation; a particular implementation must document its
behaviour.
1.4. Terminology
This specification uses many terms defined in the HTTP/1.1
specification [4]; however, the following terms are used here in a
sense which may not accord with their definitions in that document,
or with their common meaning.
’meta-variable’
A named parameter which carries information from the server to the
script. It is not necessarily a variable in the operating
system’s environment, although that is the most common
implementation.
’script’
The software that is invoked by the server according to this
interface. It need not be a standalone program, but could be a
dynamically-loaded or shared library, or even a subroutine in the
server. It might be a set of statements interpreted at run-time,
as the term ’script’ is frequently understood, but that is not a
requirement and within the context of this specification the term
has the broader definition stated.
’server’
The application program that invokes the script in order to
service requests from the client.
2. Notational Conventions and Generic Grammar
2.1. Augmented BNF
All of the mechanisms specified in this document are described in
both prose and an augmented Backus-Naur Form (BNF) similar to that
used by RFC 822 [13]. Unless stated otherwise, the elements are
case-sensitive. This augmented BNF contains the following
constructs:
name = definition
The name of a rule and its definition are separated by the equals
character (’=’). Whitespace is only significant in that
continuation lines of a definition are indented.
"literal"
Double quotation marks (") surround literal text, except for a
literal quotation mark, which is surrounded by angle-brackets (’<’
and ’>’).
rule1 | rule2
Alternative rules are separated by a vertical bar (’|’).
(rule1 rule2 rule3)
Elements enclosed in parentheses are treated as a single element.
*rule
A rule preceded by an asterisk (’*’) may have zero or more
occurrences. The full form is ’n*m rule’ indicating at least n
and at most m occurrences of the rule. n and m are optional
decimal values with default values of 0 and infinity respectively.
[rule]
An element enclosed in square brackets (’[’ and ’]’) is optional,
and is equivalent to ’*1 rule’.
N rule
A rule preceded by a decimal number represents exactly N
occurrences of the rule. It is equivalent to ’N*N rule’.
2.2. Basic Rules
This specification uses a BNF-like grammar defined in terms of
characters. Unlike many specifications which define the bytes
allowed by a protocol, here each literal in the grammar corresponds
to the character it represents. How these characters are represented
in terms of bits and bytes within a system are either system-defined
or specified in the particular context. The single exception is the
rule ’OCTET’, defined below.
The following rules are used throughout this specification to
describe basic parsing constructs.
alpha = lowalpha | hialpha
lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" |
"i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" |
"q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" |
"y" | "z"
hialpha = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" |
"I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" |
"Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" |
"Y" | "Z"
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
"8" | "9"
alphanum = alpha | digit
OCTET = <any 8-bit byte>
CHAR = alpha | digit | separator | "!" | "#" | "$" |
"%" | "&" | "’" | "*" | "+" | "-" | "." | "`" |
"^" | "_" | "{" | "|" | "}" | "~" | CTL
CTL = <any control character>
SP = <space character>
HT = <horizontal tab character>
NL = <newline>
LWSP = SP | HT | NL
separator = "(" | ")" | "<" | ">" | "@" | "," | ";" | ":" |
"\" | <"> | "/" | "[" | "]" | "?" | "=" | "{" |
"}" | SP | HT
token = 1*<any CHAR except CTLs or separators>
quoted-string = <"> *qdtext <">
qdtext = <any CHAR except <"> and CTLs but including LWSP>
TEXT = <any printable character>
Note that newline (NL) need not be a single control character, but
can be a sequence of control characters. A system MAY define TEXT to
be a larger set of characters than <any CHAR excluding CTLs but
including LWSP>.
2.3. URL Encoding
Some variables and constructs used here are described as being
’URL-encoded’. This encoding is described in section 2 of RFC 2396
[2]. In a URL-encoded string an escape sequence consists of a
percent character ("%") followed by two hexadecimal digits, where the
two hexadecimal digits form an octet. An escape sequence represents
the graphic character that has the octet as its code within the
US-ASCII [9] coded character set, if it exists. Currently there is
no provision within the URI syntax to identify which character set
non-ASCII codes represent, so CGI handles this issue on an ad-hoc
basis.
Note that some unsafe (reserved) characters may have different
semantics when encoded. The definition of which characters are
unsafe depends on the context; see section 2 of RFC 2396 [2], updated
by RFC 2732 [7], for an authoritative treatment. These reserved
characters are generally used to provide syntactic structure to the
character string, for example as field separators. In all cases, the
string is first processed with regard to any reserved characters
present, and then the resulting data can be URL-decoded by replacing
"%" escape sequences by their character values.
To encode a character string, all reserved and forbidden characters
are replaced by the corresponding "%" escape sequences. The string
can then be used in assembling a URI. The reserved characters will
vary from context to context, but will always be drawn from this set:
reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" | "$" |
"," | "[" | "]"
The last two characters were added by RFC 2732 [7]. In any
particular context, a sub-set of these characters will be reserved;
the other characters from this set MUST NOT be encoded when a string
is URL-encoded in that context. Other basic rules used to describe
URI syntax are:
hex = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b"
| "c" | "d" | "e" | "f"
escaped = "%" hex hex
unreserved = alpha | digit | mark
mark = "-" | "_" | "." | "!" | "~" | "*" | "’" | "(" | ")"
3. Invoking the Script
3.1. Server Responsibilities
The server acts as an application gateway. It receives the request
from the client, selects a CGI script to handle the request, converts
the client request to a CGI request, executes the script and converts
the CGI response into a response for the client. When processing the
client request, it is responsible for implementing any protocol or
transport level authentication and security. The server MAY also
function in a ’non-transparent’ manner, modifying the request or
response in order to provide some additional service, such as media
type transformation or protocol reduction.
The server MUST perform translations and protocol conversions on the
client request data required by this specification. Furthermore, the
server retains its responsibility to the client to conform to the
relevant network protocol even if the CGI script fails to conform to
this specification.
If the server is applying authentication to the request, then it MUST
NOT execute the script unless the request passes all defined access
controls.
3.2. Script Selection
The server determines which CGI is script to be executed based on a
generic-form URI supplied by the client. This URI includes a
hierarchical path with components separated by "/". For any
particular request, the server will identify all or a leading part of
this path with an individual script, thus placing the script at a
particular point in the path hierarchy. The remainder of the path,
if any, is a resource or sub-resource identifier to be interpreted by
the script.
Information about this split of the path is available to the script
in the meta-variables, described below. Support for non-hierarchical
URI schemes is outside the scope of this specification.
3.3. The Script-URI
The mapping from client request URI to choice of script is defined by
the particular server implementation and its configuration. The
server may allow the script to be identified with a set of several
different URI path hierarchies, and therefore is permitted to replace
the URI by other members of this set during processing and generation
of the meta-variables. The server
1. MAY preserve the URI in the particular client request; or
2. it MAY select a canonical URI from the set of possible values
for each script; or
3. it can implement any other selection of URI from the set.
From the meta-variables thus generated, a URI, the ’Script-URI’, can
be constructed. This MUST have the property that if the client had
accessed this URI instead, then the script would have been executed
with the same values for the SCRIPT_NAME, PATH_INFO and QUERY_STRING
meta-variables. The Script-URI has the structure of a generic URI as