| blob | d52c9b842cd5fa4870be097558aba6dceb87e79e |
3 <HTML>
4 <HEAD>
5 <TITLE>Common Gateway Interface - 1.1 *Draft 03* [http://cgi-spec.golux.com/draft-coar-cgi-v11-03-clean.html]
6 </TITLE>
7 <!--#if expr="$HTTP_USER_AGENT != /Lynx/" -->
8 <!--#set var="GUI" value="1" -->
9 <!--#endif -->
20 <!--
21 There are a lot of BNF fragments in this document. To make it work
22 in all possible browsers (including Lynx, which is used to turn it
23 into text/plain), we handle these by using PREformatted blocks with
24 a universal internal margin of 2, inside one-level DL blocks.
25 -->
26 </HEAD>
27 <BODY>
28 <!--
29 HTML doesn't do paper pagination, so we need to fake it out. Basing
30 our formatting upon RFC2068, there are four (4) lines of header and
31 four (4) lines of footer for each page.
33 <DIV ALIGN="CENTER">
34 <PRE>
39 Coar, et al. CGI/1.1 Specification May, 1998
40 INTERNET-DRAFT Expires 1 December 1998 [Page 2]
43 </PRE>
44 </DIV>
45 -->
46 <!--
47 The following weirdness wrt non-breaking spaces is to get Lynx
48 (which is barely TABLE-aware) to line the left/right justified
49 text up properly.
50 -->
55 INTERNET-DRAFT
56 </TD>
58 Ken A L Coar
59 </TD>
60 </TR>
63 draft-coar-cgi-v11-03.{html,txt}
64 </TD>
66 IBM Corporation
67 </TD>
68 </TR>
71
72 </TD>
74 D.R.T. Robinson
75 </TD>
76 </TR>
79
80 </TD>
83 </TD>
84 </TR>
87
88 </TD>
91 </TD>
92 </TR>
93 </TABLE>
94 </DIV>
97 The WWW Common Gateway Interface
98 <BR>
99 Version 1.1
100 </H1>
102 <!--#include virtual="I-D-statement" -->
104 <H2>
106 Abstract
107 </A>
108 </H2>
109 <P>
110 The Common Gateway Interface (CGI) is a simple interface for running
111 external programs, software or gateways under an information server
112 in a platform-independent manner. Currently, the supported information
113 servers are HTTP servers.
114 </P>
115 <P>
116 The interface has been in use by the World-Wide Web since 1993. This
117 specification defines the
118 "current practice" parameters of the
119 'CGI/1.1' interface developed and documented at the U.S. National
120 Centre for Supercomputing Applications [NCSA-CGI].
121 This document also defines the use of the CGI/1.1 interface
122 on the Unix and AmigaDOS(tm) systems.
123 </P>
124 <P>
125 Discussion of this draft occurs on the CGI-WG mailing list; see the
126 project Web page at
129 for details on the mailing list and the status of the project.
130 </P>
132 <!--#if expr="$GUI" -->
133 <H2>
134 Revision History
135 </H2>
136 <P>
137 The revision history of this draft is being maintained using Web-based
138 GUI notation, such as struck-through characters and colour-coded
139 sections. The following legend describes how to determine the origin
140 of a particular revision according to the colour of the text:
141 </P>
143 <DT>Black
144 </DT>
146 </DD>
147 <DT>Green
148 </DT>
150 <BR>
153 CGI Script."
154 Due to the size of this change, it is noted here and the text in its
157 by one. Other
158 large text movements are likewise not marked up. References to RFC
160 </DD>
161 <DT>Red
162 </DT>
164 <BR>
166 of HTTP/1.1
167 requests using "chunked" Transfer-Encoding. Labelled metavariable
169 numbers.
172 Internet-Draft language.
173 </DD>
174 <DT>Fuchsia
175 </DT>
177 <BR>
179 things like HTTP_ACCEPT. Changed 'entity-body' and 'content-body' to
180 'message-body.' Added a note that response headers must comply with
181 requirements of the protocol level in use. Added a lot of stuff about
182 security (section 11). Clarified a bunch of productions. Pointed out
183 that zero-length and omitted values are indistinguishable in this
184 specification. Clarified production describing order of fields in
185 script response header. Clarified issues surrounding encoding of
186 data. Acknowledged additional contributors, and changed one of
187 the authors' addresses.
188 </DD>
189 </DL>
190 <!--#endif -->
192 <H2>
194 Table of Contents
195 </A>
196 </H2>
198 <PRE>
397 </PRE>
398 </DIV>
400 <H2>
402 1. Introduction
403 </A>
404 </H2>
406 <H3>
408 1.1. Purpose
409 </A>
410 </H3>
411 <P>
413 and the CGI script are responsible
414 for servicing a client
415 request by sending back responses. The client
416 request comprises a Universal Resource Identifier (URI)
418 request method, and various ancillary
419 information about the request
420 provided by the transport mechanism.
421 </P>
422 <P>
423 The CGI defines the abstract parameters, known as
424 metavariables,
425 which describe the client's
426 request. Together with a
427 concrete programmer interface this specifies a platform-independent
428 interface between the script and the HTTP server.
429 </P>
431 <H3>
433 1.2. Requirements
434 </A>
435 </H3>
436 <P>
437 This specification uses the same words as RFC 1123
439 significance of each particular requirement. These are:
442 <DL>
444 </DT>
445 <DD>
446 <P>
447 This word or the adjective 'required' means that the item is an
448 absolute requirement of the specification.
449 </P>
450 </DD>
452 </DT>
453 <DD>
454 <P>
455 This word or the adjective 'recommended' means that there may
456 exist valid reasons in particular circumstances to ignore this
457 item, but the full implications should be understood and the case
458 carefully weighed before choosing a different course.
459 </P>
460 </DD>
462 </DT>
463 <DD>
464 <P>
465 This word or the adjective 'optional' means that this item is
466 truly optional. One vendor may choose to include the item because
467 a particular marketplace requires it or because it enhances the
468 product, for example; another vendor may omit the same item.
469 </P>
470 </DD>
471 </DL>
472 <P>
473 An implementation is not compliant if it fails to satisfy one or more
474 of the 'must' requirements for the protocols it implements. An
475 implementation that satisfies all of the 'must' and all of the
476 'should' requirements for its features is said to be 'unconditionally
477 compliant'; one that satisfies all of the 'must' requirements but not
478 all of the 'should' requirements for its features is said to be
479 'conditionally compliant.'
480 </P>
482 <H3>
484 1.3. Specifications
485 </A>
486 </H3>
487 <P>
488 Not all of the functions and features of the CGI are defined in the
489 main part of this specification. The following phrases are used to
490 describe the features which are not specified:
491 </P>
492 <DL>
494 </DT>
495 <DD>
496 <P>
497 The feature may differ between systems, but must be the same for
498 different implementations using the same system. A system will
499 usually identify a class of operating-systems. Some systems are
500 defined in
503 New systems may be defined
504 by new specifications without revision of this document.
505 </P>
506 </DD>
508 </DT>
509 <DD>
510 <P>
511 The behaviour of the feature may vary from implementation to
512 implementation, but a particular implementation must document its
513 behaviour.
514 </P>
515 </DD>
516 </DL>
518 <H3>
520 1.4. Terminology
521 </A>
522 </H3>
523 <P>
524 This specification uses many terms defined in the HTTP/1.1
526 used here in a
527 sense which may not accord with their definitions in that document,
528 or with their common meaning.
529 </P>
531 <DL>
533 </DT>
534 <DD>
535 <P>
536 A named parameter that carries information from the server to the
537 script. It is not necessarily a variable in the operating-system's
538 environment, although that is the most common implementation.
539 </P>
540 </DD>
543 </DT>
544 <DD>
545 <P>
547 interface. It
548 need not be a standalone program, but could be a
549 dynamically-loaded or shared library, or even a subroutine in the
551 interpreted at run-time, as the term 'script' is frequently
552 understood, but that is not a requirement and within the context
553 of this specification the term has the broader definition stated.
554 </P>
555 </DD>
557 </DT>
558 <DD>
559 <P>
560 The application program which invokes the script in order to service
561 requests.
562 </P>
563 </DD>
564 </DL>
566 <H2>
568 2. Notational Conventions and Generic Grammar
569 </A>
570 </H2>
572 <H3>
574 2.1. Augmented BNF
575 </A>
576 </H3>
577 <P>
578 All of the mechanisms specified in this document are described in
579 both prose and an augmented Backus-Naur Form (BNF) similar to that
581 the following constructs:
582 </P>
583 <DL>
584 <DT>name = definition
585 </DT>
586 <DD>
587 <P>
588 The
589 definition by the equal character ("="). Whitespace is only
590 significant in that continuation lines of a definition are
591 indented.
592 </P>
593 </DD>
595 </DT>
596 <DD>
597 <P>
598 Quotation marks (") surround literal text, except for a literal
600 Unless stated otherwise, the text is case-sensitive.
601 </P>
602 </DD>
603 <DT>rule1 | rule2
604 </DT>
605 <DD>
606 <P>
608 </P>
609 </DD>
610 <DT>(rule1 rule2 rule3)
611 </DT>
612 <DD>
613 <P>
614 Elements enclosed in parentheses are treated as a single element.
615 </P>
616 </DD>
617 <DT>*rule
618 </DT>
619 <DD>
620 <P>
622 occurrences. A rule preceded by an integer followed by an asterisk
623 must occur at least the specified number of times.
624 </P>
625 </DD>
626 <DT>[rule]
627 </DT>
628 <DD>
629 <P>
630 An element enclosed in square
632 </P>
633 </DD>
634 </DL>
636 <H3>
638 2.2. Basic Rules
639 </A>
640 </H3>
641 <P>
642 The following rules are used throughout this specification to
643 describe basic parsing constructs.
645 <P></P><!--#endif -->
646 <PRE>
647 alpha = lowalpha | hialpha
648 alphanum = alpha | digit
662 OCTET = <any 8-bit sequence of data>
663 CHAR = <any US-ASCII character (octets 0 - 127)>
664 CTL = <any US-ASCII control character
665 (octets 0 - 31) and DEL (127)>
666 CR = <US-ASCII CR, carriage return (13)>
667 LF = <US-ASCII LF, linefeed (10)>
668 SP = <US-ASCII SP, space (32)>
669 HT = <US-ASCII HT, horizontal tab (9)>
670 NL = CR | LF
671 LWSP = SP | HT | NL
674 | SP | HT | NL
679 including LWSP>
681 unreserved = alphanum | mark
684 uric = reserved | unreserved | escaped
685 </PRE>
686 <P>
687 Note that newline (NL) need not be a single character, but can be a
688 character sequence.
689 </P>
691 <H2>
693 3. Protocol Parameters
694 </A>
695 </H2>
697 <H3>
699 3.1. URL Encoding
700 </A>
701 </H3>
702 <P>
703 Some variables and constructs used here are described as being
704 'URL-encoded'. This encoding is described in section
705 2 of RFC
706 2396
708 </P>
709 <P>
711 character exists and is in common use. Scripts MUST be prepared to
712 recognise both '+' and '%20' as an encoded space in a
713 URL-encoded value.
714 </P>
715 <P>
716 Note that some unsafe characters may have different semantics if
717 they are encoded. The definition of which characters are unsafe
718 depends on the context.
719 For example, the following two URLs do not
720 necessarily refer to the same resource:
722 <P></P><!--#endif -->
723 <PRE>
724 http://somehost.com/somedir%2Fvalue
725 http://somehost.com/somedir/value
726 </PRE>
727 <P>
728 See section
729 2 of RFC
731 for authoritative treatment of this issue.
732 </P>
734 <H3>
736 3.2. The Script-URI
737 </A>
738 </H3>
739 <P>
740 The 'Script-URI' is defined as the URI of the resource identified
741 by the metavariables. Often,
742 this URI will be the same as
743 the URI requested by the client (the 'Client-URI'); however, it need
744 not be. Instead, it could be a URI invented by the server, and so it
745 can only be used in the context of the server and its CGI interface.
746 </P>
747 <P>
748 The Script-URI has the syntax of generic-RL as defined in section 2.1
750 parameters and
751 fragment identifiers are not permitted:
753 <P></P><!--#endif -->
754 <PRE>
755 <scheme>://<host><port>/<path>?<query>
756 </PRE>
757 <P>
758 The various components of the
759 Script-URI
760 are defined by some of the
761 metavariables (see
763 below);
765 <P></P><!--#endif -->
766 <PRE>
769 </PRE>
770 <P>
771 where 'protocol' is obtained
772 from SERVER_PROTOCOL, 'enc-script' is a
773 URL-encoded version of SCRIPT_NAME and 'enc-path-info' is a
774 URL-encoded version of PATH_INFO. See
776 metavariable.
777 </P>
778 <P>
779 Note that the scheme and the protocol are <EM>not</EM> identical;
780 for instance, a resource accessed <EM>via</EM> an SSL mechanism
783 for the script to reconstruct this, and therefore
784 the Script-URI includes the base protocol used.
785 </P>
787 <H2>
789 4. Invoking the Script
790 </A>
791 </H2>
792 <P>
793 The
794 script is invoked in a system defined manner. Unless specified
795 otherwise, the file containing the script will be invoked as an
796 executable program.
797 </P>
799 <H2>
801 5. The CGI Script Command Line
802 </A>
803 </H2>
804 <P>
805 Some systems support a method for supplying an array of strings to
806 the CGI script. This is only used in the case of an 'indexed' query.
808 query
810 request,
811 servers SHOULD parse the search string
812 into words, using the following rules:
814 <P></P><!--#endif -->
815 <PRE>
817 search-word = 1*schar
818 schar = xunreserved | escaped | xreserved
819 xunreserved = alpha | digit | xsafe | extra
822 </PRE>
823 <P>
824 After parsing, each word is URL-decoded, optionally encoded in a
825 system defined manner,
826 and then the argument list is set to the list
827 of words.
828 </P>
829 <P>
830 If the server cannot create any part of the argument list, then the
831 server SHOULD NOT generate any command line information. For example, the
832 number of arguments may be greater than operating system or server
833 limitations permit, or one of the words may not be representable as an
834 argument.
835 </P>
836 <P>
837 Scripts SHOULD check to see if the QUERY_STRING value contains an
839 if it does.
840 </P>
842 <H2>
844 6. Data Input to the CGI Script
845 </A>
846 </H2>
847 <P>
848 Information about a request comes from two different sources: the
849 request header, and any associated
850 message-body.
851 Servers MUST
852 make portions of this information available to
853 scripts.
854 </P>
856 <H3>
858 6.1. Request Metadata
859 (Metavariables)
860 </A>
861 </H3>
862 <P>
863 Each CGI server
864 implementation MUST define a mechanism
865 to pass data about the request from
866 the server to the script.
867 The metavariables containing these
868 data
869 are accessed by the script in a system
870 defined manner.
871 The
872 representation of the characters in the
873 metavariables is
874 system defined.
875 </P>
876 <P>
877 This specification does not distinguish between the representation of
878 null values and missing ones. Whether null or missing values
881 implementation-defined.
882 </P>
883 <P>
884 Case is not significant in the
885 metavariable
886 names, in that there cannot be two
887 different variables
888 whose names differ in case only. Here they are
889 shown using a canonical representation of capitals plus underscore
891 a particular system the representation MAY be defined differently
892 than this.
893 </P>
894 <P>
895 Metavariable
896 values MUST be
897 considered case-sensitive except as noted
898 otherwise.
899 </P>
900 <P>
901 The canonical
902 metavariables
903 defined by this specification are:
905 <P></P><!--#endif -->
906 <PRE>
907 AUTH_TYPE
908 CONTENT_LENGTH
909 CONTENT_TYPE
910 GATEWAY_INTERFACE
911 PATH_INFO
912 PATH_TRANSLATED
913 QUERY_STRING
914 REMOTE_ADDR
915 REMOTE_HOST
916 REMOTE_IDENT
917 REMOTE_USER
918 REQUEST_METHOD
919 SCRIPT_NAME
920 SERVER_NAME
921 SERVER_PORT
922 SERVER_PROTOCOL
923 SERVER_SOFTWARE
924 </PRE>
925 <P>
926 Metavariables with names beginning with the protocol name (<EM>e.g.</EM>,
928 fields. The number and meaning of these fields may change independently
930 </P>
932 <H4>
934 6.1.1. AUTH_TYPE
935 </A>
936 </H4>
937 <P>
938 This variable is specific to requests made
939 <EM>via</EM> the
941 scheme.
942 </P>
943 <P>
944 If the Script-URI
945 required access authentication for external
946 access, then the server
947 MUST set
948 the value of
949 this variable
950 from the '<SAMP>auth-scheme</SAMP>' token in
952 field.
953 Otherwise
954 it is
955 set to NULL.
957 <P></P><!--#endif -->
958 <PRE>
961 </PRE>
962 <P>
963 HTTP access authentication schemes are described in section 11 of the
965 not case-sensitive.
966 </P>
967 <P>
968 Servers
969 MUST
970 provide this metavariable
971 to scripts if the request
973 that was authenticated.
974 </P>
976 <H4>
978 6.1.2. CONTENT_LENGTH
979 </A>
980 </H4>
981 <P>
982 This
983 metavariable
984 is set to the
985 size of the message-body
986 entity attached to the request, if any, in decimal
987 number of octets. If no data are attached, then this
988 metavariable
989 is either NULL or not
990 defined. The syntax is
991 the same as for
995 <P></P><!--#endif -->
996 <PRE>
998 </PRE>
999 <P>
1000 Servers MUST provide this metavariable
1001 to scripts if the request
1002 was accompanied by a
1003 message-body entity.
1004 </P>
1006 <H4>
1008 6.1.3. CONTENT_TYPE
1009 </A>
1010 </H4>
1011 <P>
1012 If the request includes a
1013 message-body,
1014 CONTENT_TYPE is set
1015 to
1016 the Internet Media Type
1018 entity if the type was provided <EM>via</EM>
1020 request header, or if the server can determine it in the absence
1022 same as for the HTTP
1025 <P></P><!--#endif -->
1026 <PRE>
1029 type = token
1030 subtype = token
1032 attribute = token
1033 value = token | quoted-string
1034 </PRE>
1035 <P>
1036 The type, subtype,
1037 and parameter attribute names are not
1038 case-sensitive. Parameter values MAY be case sensitive.
1039 Media types and their use in HTTP are described
1040 in section 3.7 of the
1042 </P>
1043 <P>
1044 Example:
1046 <P></P><!--#endif -->
1047 <PRE>
1048 application/x-www-form-urlencoded
1049 </PRE>
1050 <P>
1051 There is no default value for this variable. If and only if it is
1052 unset, then the script MAY attempt to determine the media type from
1053 the data received. If the type remains unknown, then
1054 the script MAY choose to either assume a
1055 content-type of
1056 <SAMP>application/octet-stream</SAMP>
1059 for more information about returning error status values.
1060 </P>
1061 <P>
1062 Servers MUST provide this metavariable
1063 to scripts if
1065 in the original request header. If the server receives a request
1067 header field, it MAY attempt to
1068 determine the correct datatype, or it MAY omit this
1069 metavariable when
1070 communicating the request information to the script.
1071 </P>
1073 <H4>
1075 6.1.4. GATEWAY_INTERFACE
1076 </A>
1077 </H4>
1078 <P>
1079 This
1080 metavariable
1081 is set to
1082 the dialect of CGI being used
1083 by the server to communicate with the script.
1084 Syntax:
1086 <P></P><!--#endif -->
1087 <PRE>
1089 major = 1*digit
1090 minor = 1*digit
1091 </PRE>
1092 <P>
1093 Note that the major and minor numbers are treated as separate
1094 integers and hence each may be
1095 more than a single
1096 digit. Thus CGI/2.4 is a lower version than CGI/2.13 which in turn
1097 is lower than CGI/12.3. Leading zeros in either
1098 the major or the minor number MUST be ignored by scripts and
1099 SHOULD NOT be generated by servers.
1100 </P>
1101 <P>
1102 This document defines the 1.1 version of the CGI interface
1104 </P>
1105 <P>
1106 Servers MUST provide this metavariable
1107 to scripts.
1108 </P>
1110 <H4>
1112 6.1.5. Protocol-Specific Metavariables
1113 </A>
1114 </H4>
1115 <P>
1116 These metavariables are specific to
1117 the protocol
1118 <EM>via</EM> which the request is made.
1119 Interpretation of these variables depends on the value of
1120 the
1121 SERVER_PROTOCOL
1122 metavariable
1123 (see
1125 </P>
1126 <P>
1127 Metavariables
1129 values from the request header, if the
1130 scheme used was HTTP.
1131 Each
1132 HTTP header field name is converted to upper case, has all occurrences of
1135 the metavariable name.
1136 Similar transformations are applied for other
1137 protocols.
1138 The header data MAY be presented as sent
1139 by the client, or MAY be rewritten in ways which do not change its
1140 semantics. If multiple header fields with the same field-name are received
1141 then the server
1142 MUST rewrite them as though they
1143 had been received as a single header field having the same
1144 semantics before being represented in a
1145 metavariable.
1146 Similarly, a header field that is received on more than one line
1147 MUST be merged into a single line. The server MUST, if necessary,
1148 change the representation of the data (for example, the character
1149 set) to be appropriate for a CGI
1150 metavariable.
1151 <!-- ###NOTE: See if 2068 describes this thoroughly, and
1152 point there if so. -->
1153 </P>
1154 <P>
1155 Servers are
1156 not required to create
1157 metavariables for all
1158 the request
1159 header fields that they
1160 receive. In particular,
1161 they MAY
1162 decline to make available any
1163 header fields carrying authentication information, such as
1165 which are available to the script
1166 <EM>via</EM> other metavariables,
1168 </P>
1170 <H4>
1172 6.1.6. PATH_INFO
1173 </A>
1174 </H4>
1175 <P>
1176 The PATH_INFO
1177 metavariable
1178 specifies
1179 a path to be interpreted by the CGI script. It identifies the
1180 resource or sub-resource to be returned
1181 by the CGI
1182 script, and it is derived from the portion
1183 of the URI path following the script name but preceding
1184 any query data.
1185 The syntax
1186 and semantics are similar to a decoded HTTP URL
1187 'path' token
1188 (defined in
1189 RFC 2396
1192 represents a single void path segment.
1194 <P></P><!--#endif -->
1195 <PRE>
1198 segment = *pchar
1200 </PRE>
1201 <P>
1202 The PATH_INFO string is the trailing part of the <path> component of
1203 the Script-URI
1205 that follows the SCRIPT_NAME
1206 portion of the path.
1207 </P>
1208 <P>
1209 Servers MAY impose their own restrictions and
1210 limitations on what values they will accept for PATH_INFO, and MAY
1211 reject or edit any values they
1212 consider objectionable before passing
1213 them to the script.
1214 </P>
1215 <P>
1216 Servers MUST make this URI component available
1217 to CGI scripts. The PATH_INFO
1218 value is case-sensitive, and the
1219 server MUST preserve the case of the PATH_INFO element of the URI
1220 when making it available to scripts.
1221 </P>
1223 <H4>
1225 6.1.7. PATH_TRANSLATED
1226 </A>
1227 </H4>
1228 <P>
1229 PATH_TRANSLATED is derived by taking any path-info component of the
1230 request URI (see
1233 right, and performing any virtual-to-physical
1234 translation appropriate to map it onto the
1235 server's document repository structure.
1236 If the request URI includes no path-info
1237 component, the PATH_TRANSLATED metavariable SHOULD NOT be defined.
1239 <P></P><!--#endif -->
1240 <PRE>
1241 PATH_TRANSLATED = *CHAR
1242 </PRE>
1243 <P>
1244 For a request such as the following:
1246 <P></P><!--#endif -->
1247 <PRE>
1248 http://somehost.com/cgi-bin/somescript/this%2eis%2epath%2einfo
1249 </PRE>
1250 <P>
1251 the PATH_INFO component would be decoded, and the result
1252 parsed as though it were a request for the following:
1254 <P></P><!--#endif -->
1255 <PRE>
1256 http://somehost.com/this.is.the.path.info
1257 </PRE>
1258 <P>
1259 This would then be translated to a
1260 location in the server's document repository,
1261 perhaps a filesystem path something
1262 like this:
1264 <P></P><!--#endif -->
1265 <PRE>
1266 /usr/local/www/htdocs/this.is.the.path.info
1267 </PRE>
1268 <P>
1269 The result of the translation is the value of PATH_TRANSLATED.
1270 </P>
1271 <P>
1272 The value of PATH_TRANSLATED may or may not map to a valid
1273 repository
1274 location.
1275 Servers MUST preserve the case of the path-info
1276 segment if and only if the underlying
1277 repository
1278 supports case-sensitive
1279 names. If the
1280 repository
1281 is only case-aware, case-preserving, or case-blind
1282 with regard to
1283 document names,
1284 servers are not required to preserve the
1285 case of the original segment through the translation.
1286 </P>
1287 <P>
1288 The
1289 translation
1290 algorithm the server uses to derive PATH_TRANSLATED is
1291 implementation defined; CGI scripts which use this variable may
1292 suffer limited portability.
1293 </P>
1294 <P>
1295 Servers SHOULD provide this metavariable
1296 to scripts if and only if the request URI includes a
1297 path-info component.
1298 </P>
1300 <H4>
1302 6.1.8. QUERY_STRING
1303 </A>
1304 </H4>
1305 <P>
1306 A URL-encoded
1307 string; the <query> part of the
1308 Script-URI.
1309 (See
1312 <P></P><!--#endif -->
1313 <PRE>
1314 QUERY_STRING = query-string
1315 query-string = *uric
1316 </PRE>
1317 <P>
1318 The URL syntax for a query
1319 string is described in
1320 section 3 of
1321 RFC 2396
1323 </P>
1324 <P>
1325 Servers MUST supply this value to scripts.
1326 The QUERY_STRING value is case-sensitive.
1327 If the Script-URI does not include a query component,
1329 </P>
1331 <H4>
1333 6.1.9. REMOTE_ADDR
1334 </A>
1335 </H4>
1336 <P>
1337 The IP address of the client
1338 sending the request to the server. This
1339 is not necessarily that of the user
1340 agent
1341 (such as if the request came through a proxy).
1343 <P></P><!--#endif -->
1344 <PRE>
1345 REMOTE_ADDR = hostnumber
1346 hostnumber = ipv4-address | ipv6-address
1347 </PRE>
1348 <P>
1349 The definitions of <SAMP>ipv4-address</SAMP> and <SAMP>ipv6-address</SAMP>
1351 </P>
1352 <P>
1353 Servers MUST supply this value to scripts.
1354 </P>
1356 <H4>
1358 6.1.10. REMOTE_HOST
1359 </A>
1360 </H4>
1361 <P>
1362 The fully qualified domain name of the
1363 client sending the request to
1364 the server, if available, otherwise NULL.
1366 Fully qualified domain names take the form as described in
1369 </P>
1370 <P>
1371 Servers SHOULD provide this information to
1372 scripts.
1373 </P>
1375 <H4>
1377 6.1.11. REMOTE_IDENT
1378 </A>
1379 </H4>
1380 <P>
1381 The identity information reported about the connection by a
1383 available. Servers
1384 MAY choose not
1385 to support this feature, or not to request the data
1386 for efficiency reasons.
1388 <P></P><!--#endif -->
1389 <PRE>
1390 REMOTE_IDENT = *CHAR
1391 </PRE>
1392 <P>
1393 The data returned
1394 may be used for authentication purposes, but the level
1395 of trust reposed in them should be minimal.
1396 </P>
1397 <P>
1398 Servers MAY supply this information to scripts if the
1400 </P>
1402 <H4>
1404 6.1.12. REMOTE_USER
1405 </A>
1406 </H4>
1407 <P>
1409 mechanism (<EM>i.e.</EM>, the AUTH_TYPE
1410 metavariable is set
1412 metavariable is set to the
1413 user-ID supplied. In all other cases
1414 the value of this metavariable
1415 is undefined.
1417 <P></P><!--#endif -->
1418 <PRE>
1419 REMOTE_USER = *OCTET
1420 </PRE>
1421 <P>
1422 This variable is specific to requests made <EM>via</EM> the
1423 HTTP protocol.
1424 </P>
1425 <P>
1426 Servers SHOULD provide this metavariable
1427 to scripts.
1428 </P>
1430 <H4>
1432 6.1.13. REQUEST_METHOD
1433 </A>
1434 </H4>
1435 <P>
1436 The REQUEST_METHOD
1437 metavariable
1438 is set to the
1439 method with which the request was made, as described in section
1441 section 5.1.1 of the
1444 <P></P><!--#endif -->
1445 <PRE>
1446 REQUEST_METHOD = http-method
1449 extension-method = token
1450 </PRE>
1451 <P>
1452 The method is case sensitive.
1453 CGI/1.1 servers MAY choose to process some methods
1454 directly rather than passing them to scripts.
1455 </P>
1456 <P>
1457 This variable is specific to requests made with HTTP.
1458 </P>
1459 <P>
1460 Servers MUST provide this metavariable
1461 to scripts.
1462 </P>
1464 <H4>
1466 6.1.14. SCRIPT_NAME
1467 </A>
1468 </H4>
1469 <P>
1470 The SCRIPT_NAME
1471 metavariable
1472 is
1473 set to a URL path that could identify the CGI script (rather than the
1474 script's
1475 output). The syntax and semantics are identical to a
1476 decoded HTTP URL 'path' token
1477 (see RFC 2396
1480 <P></P><!--#endif -->
1481 <PRE>
1483 </PRE>
1484 <P>
1485 The SCRIPT_NAME string is some leading part of the <path> component
1486 of the Script-URI derived in some
1487 implementation defined manner.
1488 No PATH_INFO or QUERY_STRING segments
1491 in the SCRIPT_NAME value.
1492 </P>
1493 <P>
1494 Servers MUST provide this metavariable
1495 to scripts.
1496 </P>
1498 <H4>
1500 6.1.15. SERVER_NAME
1501 </A>
1502 </H4>
1503 <P>
1504 The SERVER_NAME
1505 metavariable
1506 is set to the
1507 name of the
1508 server, as
1509 derived from the <host> part of the
1510 Script-URI
1513 <P></P><!--#endif -->
1514 <PRE>
1515 SERVER_NAME = hostname | hostnumber
1516 </PRE>
1517 <P>
1518 Servers MUST provide this metavariable
1519 to scripts.
1520 </P>
1522 <H4>
1524 6.1.16. SERVER_PORT
1525 </A>
1526 </H4>
1527 <P>
1528 The SERVER_PORT
1529 metavariable
1530 is set to the
1531 port on which the
1532 request was received, as used in the <port>
1533 part of the Script-URI.
1535 <P></P><!--#endif -->
1536 <PRE>
1537 SERVER_PORT = 1*digit
1538 </PRE>
1539 <P>
1540 If the <port> portion of the script-URI is blank, the actual
1541 port number upon which the request was received MUST be supplied.
1542 </P>
1543 <P>
1544 Servers MUST provide this metavariable
1545 to scripts.
1546 </P>
1548 <H4>
1550 6.1.17. SERVER_PROTOCOL
1551 </A>
1552 </H4>
1553 <P>
1554 The SERVER_PROTOCOL
1555 metavariable
1556 is set to
1557 the
1558 name and revision of the information protocol with which
1559 the
1560 request
1561 arrived. This is not necessarily the same as the protocol version used by
1562 the server in its response to the client.
1564 <P></P><!--#endif -->
1565 <PRE>
1566 SERVER_PROTOCOL = HTTP-Version | extension-version
1567 | extension-token
1571 extension-token = token
1572 </PRE>
1573 <P>
1574 'protocol' is a version of the <scheme> part of the
1575 Script-URI, but is
1576 not identical to it. For example, the scheme of a request may be
1578 The protocol is not case sensitive, but
1579 by convention, 'protocol' is in
1580 upper case.
1581 </P>
1582 <P>
1584 which signals that the current document is being included as part of
1585 a composite document, rather than being the direct target of the
1586 client request.
1587 </P>
1588 <P>
1589 Servers MUST provide this metavariable
1590 to scripts.
1591 </P>
1593 <H4>
1595 6.1.18. SERVER_SOFTWARE
1596 </A>
1597 </H4>
1598 <P>
1599 The SERVER_SOFTWARE
1600 metavariable
1601 is set to the
1602 name and version of the information server software answering the
1603 request (and running the gateway).
1605 <P></P><!--#endif -->
1606 <PRE>
1607 SERVER_SOFTWARE = 1*product
1609 product-version = token
1610 </PRE>
1611 <P>
1612 Servers MUST provide this metavariable
1613 to scripts.
1614 </P>
1616 <H3>
1618 6.2. Request Message-Bodies
1619 </A>
1620 </H3>
1621 <P>
1622 As there may be a data entity attached to the request, there MUST be
1623 a system defined method for the script to read
1624 these data. Unless
1625 defined otherwise, this will be <EM>via</EM> the 'standard input' file
1626 descriptor.
1627 </P>
1628 <P>
1630 is non-NULL, the server MUST supply at least that many bytes to
1631 scripts on the standard input stream.
1632 Scripts are
1633 not obliged to read the data.
1634 Servers MAY signal an EOF condition after CONTENT_LENGTH bytes have been
1635 read, but are
1636 not obligated to do so. Therefore, scripts
1637 MUST NOT
1638 attempt to read more than CONTENT_LENGTH bytes, even if more data
1639 are available.
1640 </P>
1641 <P>
1642 For non-parsed header (NPH) scripts (see
1644 below),
1645 servers SHOULD
1646 attempt to ensure that the data
1647 supplied to the script are precisely
1648 as supplied by the client and unaltered by
1649 the server.
1650 </P>
1651 <P>
1653 servers with regard to requests that include
1654 message-bodies.
1655 </P>
1657 <H2>
1659 7. Data Output from the CGI Script
1660 </A>
1661 </H2>
1662 <P>
1663 There MUST be a system defined method for the script to send data
1664 back to the server or client; a script MUST always return some data.
1665 Unless defined otherwise, this will be <EM>via</EM> the 'standard
1666 output' file descriptor.
1667 </P>
1668 <P>
1669 There are two forms of output that scripts can supply to servers: non-parsed
1670 header (NPH) output, and parsed header output.
1671 Servers MUST support parsed header
1672 output and MAY support NPH output. The method of
1673 distinguishing between the two
1674 types of output (or scripts) is implementation defined.
1675 </P>
1676 <P>
1677 Servers MAY implement a timeout period within which data must be
1678 received from scripts. If a server implementation defines such
1679 a timeout and receives no data from a script within the timeout
1680 period, the server MAY terminate the script process and SHOULD
1681 abort the client request with
1682 either a
1683 '504 Gateway Timed Out' or a
1684 '500 Internal Server Error' response.
1685 </P>
1687 <H3>
1689 7.1. Non-Parsed Header Output
1690 </A>
1691 </H3>
1692 <P>
1693 Scripts using the NPH output form
1694 MUST return a complete HTTP response message, as described
1695 in Section 6 of the HTTP specifications
1697 NPH scripts
1698 MUST use the SERVER_PROTOCOL variable to determine the appropriate format
1699 for a response.
1700 </P>
1701 <P>
1702 Servers
1703 SHOULD attempt to ensure that the script output is sent
1704 directly to the client, with minimal
1705 internal and no transport-visible
1706 buffering.
1707 </P>
1709 <H3>
1711 7.2. Parsed Header Output
1712 </A>
1713 </H3>
1714 <P>
1715 Scripts using the parsed header output form MUST supply
1716 a CGI response message to the server
1717 as follows:
1719 <P></P><!--#endif -->
1720 <PRE>
1721 CGI-Response = *optional-field CGI-Field *optional-field NL [ Message-Body ]
1722 optional-field = ( CGI-Field | HTTP-Field )
1723 CGI-Field = Content-type
1724 | Location
1725 | Status
1726 | extension-header
1727 </PRE>
1728 <P><!-- ##### If HTTP defines x-headers, remove ours except x-cgi- -->
1729 The response comprises a header and a body, separated by a blank line.
1730 The body may be NULL.
1731 The header fields are either CGI header fields to be interpreted by
1732 the server, or HTTP header fields
1733 to be included in the response returned
1734 to the client
1735 if the request method is HTTP. At least one
1736 CGI-Field MUST be
1737 supplied, but no CGI field name may be used more than once
1738 in a response.
1740 header field MUST be
1741 supplied by the script,
1744 <SAMP>Location</SAMP> CGI-Field
1745 is returned, then the script MUST NOT supply
1746 any HTTP-Fields.
1747 </P>
1748 <P>
1749 Each header field in a CGI-Response MUST be specified on a single line;
1750 CGI/1.1 does not support continuation lines.
1751 </P>
1753 <H4>
1755 7.2.1. CGI header fields
1756 </A>
1757 </H4>
1758 <P>
1759 The CGI header fields have the generic syntax:
1761 <P></P><!--#endif -->
1762 <PRE>
1764 field-name = token
1765 field-value = *( field-content | LWSP )
1766 field-content = *( token | tspecial | quoted-string )
1767 </PRE>
1768 <P>
1769 The field-name is not case sensitive; a NULL field value is
1770 equivalent to the header field not being sent.
1771 </P>
1773 <H4>
1775 7.2.1.1. Content-Type
1776 </A>
1777 </H4>
1778 <P>
1780 body, which is to be sent unmodified to the client.
1782 <P></P><!--#endif -->
1783 <PRE>
1785 </PRE>
1786 <P>
1787 This is actually an HTTP-Field
1788 rather than a CGI-Field, but
1789 it is listed here because of its importance in the CGI dialogue as
1791 fields.
1792 </P>
1794 <H4>
1796 7.2.1.2. Location
1797 </A>
1798 </H4>
1799 <P>
1800 This is used to specify to the server that the script is returning a
1801 reference to a document rather than an actual document.
1803 <P></P><!--#endif -->
1804 <PRE>
1806 ( fragment-URI | rel-URL-abs-path ) NL
1807 fragment-URI = URI [ # fragmentid ]
1809 fragmentid = *qchar
1812 fpsegment = 1*hchar
1813 psegment = *hchar
1814 hchar = alpha | digit | safe | extra
1816 </PRE>
1817 <P>
1818 The Location
1819 value is either an absolute URI with optional fragment,
1822 omitting the scheme and network-related fields) and optional
1823 query-string. If an absolute URI is returned by the script,
1824 then the
1825 server MUST generate a
1826 '302 redirect' HTTP response
1827 message unless the script has supplied an
1828 explicit Status response header field.
1829 Scripts returning an absolute URI MAY choose to
1830 provide a message-body. Servers MUST make any appropriate modifications
1831 to the script's output to ensure the response to the user-agent complies
1832 with the response protocol version.
1833 If the Location value is a path, then the server
1834 MUST generate
1835 the response that it would have produced in response to a request
1836 containing the URL
1839 <PRE>
1841 </PRE>
1842 <P>
1843 Note: If the request was accompanied by a
1844 message-body
1845 (such as for a POST request), and the script
1846 redirects the request with a Location field, the
1847 message-body
1848 may not be
1849 available to the resource that is the target of the redirect.
1850 </P>
1852 <H4>
1854 7.2.1.3. Status
1855 </A>
1856 </H4>
1857 <P>
1858 The "<SAMP>Status</SAMP>" header field is used to indicate to the server what
1859 status code the server MUST use in the response message.
1862 <PRE>
1865 </PRE>
1866 <P>
1871 be used. If the script does not return a "<SAMP>Status</SAMP>" header
1872 field, then "200 OK" SHOULD be assumed by the server.
1873 </P>
1874 <P>
1875 If a script is being used to handle a particular error or condition
1876 encountered by the server, such as a '404 Not Found' error, the script
1877 SHOULD use the "<SAMP>Status</SAMP>" CGI header field to propagate the error
1879 SHOULD include a "Status: 404 Not Found" in the
1880 header data returned to the server.
1881 </P>
1883 <H4>
1885 7.2.1.4. Extension header fields
1886 </A>
1887 </H4>
1888 <P>
1889 Scripts MAY include in their CGI response header additional fields
1890 not defined in this or the HTTP specification.
1891 These are called "extension" fields,
1894 MUST NOT conflict with a field name defined in this or any other
1895 specification; extension field names SHOULD begin with "X-CGI-"
1896 to ensure uniqueness.
1897 </P>
1899 <H4>
1901 7.2.2. HTTP header fields
1902 </A>
1903 </H4>
1904 <P>
1905 The script MAY return any other header fields defined by the
1906 specification
1909 Servers MUST resolve conflicts beteen CGI header
1911 </P>
1913 <H2>
1915 8. Server Implementation
1916 </A>
1917 </H2>
1918 <P>
1919 This section defines the requirements that must be met by HTTP
1920 servers in order to provide a coherent and correct CGI/1.1
1921 environment in which scripts may function. It is intended
1922 primarily for server implementors, but it is useful for
1923 script authors to be familiar with the information as well.
1924 </P>
1926 <H3>
1928 8.1. Requirements for Servers
1929 </A>
1930 </H3>
1931 <P>
1932 In order to be considered CGI/1.1-compliant, a server must meet
1933 certain basic criteria and provide certain minimal functionality.
1934 The details of these requirements are described in the following sections.
1935 </P>
1937 <H3>
1939 8.1.1. Script-URI
1940 </A>
1941 </H3>
1942 <P>
1943 Servers MUST support the standard mechanism (described below) which
1944 allows
1945 script authors to determine
1946 what URL to use in documents
1947 which reference the script;
1948 specifically, what URL to use in order to
1949 achieve particular settings of the
1950 metavariables. This
1951 mechanism is as follows:
1952 </P>
1953 <P>
1954 The server
1955 MUST translate the header data from the CGI header field syntax to
1956 the HTTP
1957 header field syntax if these differ. For example, the character
1958 sequence for
1959 newline (such as Unix's ASCII NL) used by CGI scripts may not be the
1960 same as that used by HTTP (ASCII CR followed by LF). The server MUST
1961 also resolve any conflicts between header fields returned by the script
1962 and header fields that it would otherwise send itself.
1963 </P>
1965 <H3>
1967 8.1.2. Request Message-body Handling
1968 </A>
1969 </H3>
1970 <P>
1971 These are the requirements for server handling of message-bodies directed
1972 to CGI/1.1 resources:
1973 </P>
1974 <OL>
1975 <LI>The message-body the server provides to the CGI script MUST
1976 have any transfer encodings removed.
1977 </LI>
1978 <LI>The server MUST derive and provide a value for the CONTENT_LENGTH
1979 metavariable that reflects the length of the message-body after any
1980 transfer decoding.
1981 </LI>
1982 <LI>The server MUST leave intact any content-encodings of the message-body.
1983 </LI>
1984 </OL>
1986 <H3>
1988 8.1.3. Required Metavariables
1989 </A>
1990 </H3>
1991 <P>
1992 Servers MUST provide scripts with certain information and
1993 metavariables
1995 </P>
1997 <H3>
1999 8.1.4. Response Compliance
2000 </A>
2001 </H3>
2002 <P>
2003 Servers MUST ensure that responses sent to the user-agent meet all
2004 requirements of the protocol level in effect. This may involve
2005 modifying, deleting, or augmenting any header
2006 fields and/or message-body supplied by the script.
2007 </P>
2009 <H3>
2011 8.2. Recommendations for Servers
2012 </A>
2013 </H3>
2014 <P>
2015 Servers SHOULD provide the "<SAMP>query</SAMP>" component of the script-URI
2016 as command-line arguments to scripts if it does not
2017 contain any unencoded '=' characters and the command-line arguments can
2018 be generated in an unambiguous manner.
2020 </P>
2021 <P>
2022 Servers SHOULD set the AUTH_TYPE
2023 metavariable to the value of the
2025 field if it was supplied as part of the request header.
2027 </P>
2028 <P>
2029 Where applicable, servers SHOULD set the current working directory
2030 to the directory in which the script is located before invoking
2031 it.
2032 </P>
2033 <P>
2034 Servers MAY reject with error '404 Not Found'
2035 any requests that would result in
2036 an encoded "/" being decoded into PATH_INFO or SCRIPT_NAME, as this
2037 might represent a loss of information to the script.
2038 </P>
2039 <P>
2040 Although the server and the CGI script need not be consistent in
2041 their handling of URL paths (client URLs and the PATH_INFO data,
2042 respectively), server authors may wish to impose consistency.
2043 So the server implementation SHOULD define its behaviour for the
2044 following cases:
2045 </P>
2046 <OL>
2047 <LI>define any restrictions on allowed characters, in particular
2048 whether ASCII NUL is permitted;
2049 </LI>
2050 <LI>define any restrictions on allowed path segments, in particular
2051 whether non-terminal NULL segments are permitted;
2052 </LI>
2055 ordinary path
2056 segments or interpreted in accordance with the relative URL
2058 </LI>
2059 <LI>define any limits of the implementation, including limits on path or
2060 search string lengths, and limits on the volume of header data the server
2061 will parse.
2063 </OL>
2064 <P>
2065 Servers MAY generate the
2066 Script-URI in
2067 any way from the client URI,
2068 or from any other data (but the behaviour SHOULD be documented).
2069 </P>
2070 <P>
2071 For non-parsed header (NPH) scripts (see
2073 attempt to ensure that the script input comes directly from the
2074 client, with minimal buffering. For all scripts the data will be
2075 as supplied by the client.
2076 </P>
2078 <H3>
2080 8.3. Summary of
2081 MetaVariables
2082 </A>
2083 </H3>
2084 <P>
2085 Servers MUST provide the following
2086 metavariables to
2087 scripts. See the individual descriptions for exceptions and semantics.
2090 <PRE>
2103 </PRE>
2104 <P>
2105 Servers SHOULD define the following
2106 metavariables for scripts.
2107 See the individual descriptions for exceptions and semantics.
2110 <PRE>
2113 </PRE>
2114 <P>
2115 In addition, servers SHOULD provide
2116 metavariables for all fields present
2117 in the HTTP request header, with the exception of those involved with
2118 access control. Servers MAY at their discretion provide
2119 metavariables
2120 for access control fields.
2121 </P>
2122 <P>
2123 Servers MAY define the following
2124 metavariables. See the individual
2125 descriptions for exceptions and semantics.
2128 <PRE>
2132 </PRE>
2133 <P>
2134 Servers MAY
2135 at their discretion define additional implementation-specific
2136 extension metavariables
2137 provided their names do not
2138 conflict with defined header field names. Implementation-specific
2139 metavariable names SHOULD
2141 "X_DBA") to avoid the potential for such conflicts.
2142 </P>
2144 <H2>
2146 9.
2147 Script Implementation
2148 </A>
2149 </H2>
2150 <P>
2151 This section defines the requirements and recommendations for scripts
2152 that are intended to function in a CGI/1.1 environment. It is intended
2153 primarily as a reference for script authors, but server implementors
2154 should be familiar with these issues as well.
2155 </P>
2157 <H3>
2159 9.1. Requirements for Scripts
2160 </A>
2161 </H3>
2162 <P>
2163 Scripts using the parsed-header method to communicate with servers
2164 MUST supply a response header to the server.
2166 </P>
2167 <P>
2168 Scripts using the NPH method to communicate with servers MUST
2169 provide complete HTTP responses, and MUST use the value of the
2170 SERVER_PROTOCOL metavariable
2171 to determine the appropriate format.
2173 </P>
2174 <P>
2175 Scripts MUST check the value of the REQUEST_METHOD
2176 metavariable in order
2177 to provide an appropriate response.
2179 </P>
2180 <P>
2181 Scripts MUST be prepared to handled URL-encoded values in
2182 metavariables.
2184 quantities as representing the space character.
2186 </P>
2187 <P>
2188 Scripts MUST ignore leading zeros in the major and minor version numbers
2189 in the GATEWAY_INTERFACE
2190 metavariable value. (See
2192 </P>
2193 <P>
2194 When processing requests that include a
2195 message-body, scripts
2196 MUST NOT read more than CONTENT_LENGTH bytes from the input stream.
2198 </P>
2200 <H3>
2202 9.2. Recommendations for Scripts
2203 </A>
2204 </H3>
2205 <P>
2206 Servers may interrupt or terminate script execution at any time
2207 and without warning, so scripts SHOULD be prepared to deal with
2208 abnormal termination.
2209 </P>
2210 <P>
2211 Scripts MUST
2212 reject with
2213 error '405 Method Not
2214 Allowed' requests
2215 made using methods that they do not support. If the script does
2216 not intend
2217 processing the PATH_INFO data, then it SHOULD reject the request with
2218 '404 Not
2219 Found' if PATH_INFO is not NULL.
2220 </P>
2221 <P>
2222 If a script is processing the output of a form, it SHOULD
2223 verify that the CONTENT_TYPE
2225 or whatever other media type is expected.
2226 </P>
2227 <P>
2228 Scripts parsing PATH_INFO,
2229 PATH_TRANSLATED, or SCRIPT_NAME
2230 SHOULD be careful
2231 of void path segments ("<SAMP>//</SAMP>") and special path segments
2234 use in OS
2235 system calls, or the request SHOULD be rejected with
2236 '404 Not Found'.
2237 </P>
2238 <P>
2239 As it is impossible for
2240 scripts to determine the client URI that
2241 initiated a
2242 request without knowledge of the specific server in
2243 use, the script SHOULD NOT return "<SAMP>text/html</SAMP>"
2244 documents containing
2245 relative URL links without including a "<SAMP><BASE></SAMP>"
2246 tag in the document.
2247 </P>
2248 <P>
2249 When returning header fields,
2250 scripts SHOULD try to send the CGI
2251 header fields (see section
2253 SHOULD send them
2254 before any HTTP header fields. This may
2255 help reduce the server's memory requirements.
2256 </P>
2258 <H2>
2260 10. System Specifications
2261 </A>
2262 </H2>
2264 <H3>
2266 10.1. AmigaDOS
2267 </A>
2268 </H3>
2269 <P>
2270 The implementation of the CGI on an AmigaDOS operating system platform
2271 SHOULD use environment variables as the mechanism of providing
2272 request metadata to CGI scripts.
2273 </P>
2274 <DL>
2276 </DT>
2277 <DD>
2278 <P>
2280 flags argument SHOULD be 0. Case is ignored, but upper case is
2281 recommended for compatibility with case-sensitive systems.
2282 </P>
2283 </DD>
2285 </DT>
2286 <DD>
2287 <P>
2288 The current working directory for the script is set to the directory
2289 containing the script.
2290 </P>
2291 </DD>
2293 </DT>
2294 <DD>
2295 <P>
2296 The US-ASCII character set is used for the definition of environment
2297 variable names and header
2298 field names; the newline (NL) sequence is LF;
2299 servers SHOULD also accept CR LF as a newline.
2300 </P>
2301 </DD>
2302 </DL>
2304 <H3>
2306 10.2. Unix
2307 </A>
2308 </H3>
2309 <P>
2310 The implementation of the CGI on a UNIX operating system platform
2311 SHOULD use environment variables as the mechanism of providing
2312 request metadata to CGI scripts.
2313 </P>
2314 <P>
2315 For Unix compatible operating systems, the following are defined:
2316 </P>
2317 <DL>
2319 </DT>
2320 <DD>
2321 <P>
2323 </P>
2324 </DD>
2326 </DT>
2327 <DD>
2328 <P>
2329 This is accessed using the
2332 that
2333 are 'active' in the Bourne shell escaped with a backslash.
2334 If the value of the QUERY_STRING
2335 metavariable
2336 contains an unencoded equals-sign '=', then the command line
2337 SHOULD NOT be used by the script.
2338 </P>
2339 </DD>
2341 </DT>
2342 <DD>
2343 <P>
2344 The current working directory for the script
2345 SHOULD be set to the directory
2346 containing the script.
2347 </P>
2348 </DD>
2350 </DT>
2351 <DD>
2352 <P>
2353 The US-ASCII character set is used for the definition of environment
2354 variable names and header field names; the newline (NL) sequence is LF;
2355 servers SHOULD also accept CR LF as a newline.
2356 </P>
2357 </DD>
2358 </DL>
2360 <H2>
2362 11. Security Considerations
2363 </A>
2364 </H2>
2366 <H3>
2368 11.1. Safe Methods
2369 </A>
2370 </H3>
2371 <P>
2372 As discussed in the security considerations of the HTTP
2374 convention has been established that the
2375 GET and HEAD methods should be 'safe'; they should cause no
2376 side-effects and only have the significance of resource retrieval.
2377 </P>
2378 <P>
2379 CGI scripts are responsible for enforcing any HTTP security considerations
2381 with respect to the protocol version level of the request and
2382 any side effects generated by the scripts on behalf of
2383 the server. Primary
2384 among these
2385 are the considerations of safe and idempotent methods. Idempotent
2386 requests are those that may be repeated an arbitrary number of times
2387 and produce side effects identical to a single request.
2388 </P>
2390 <H3>
2392 11.2. HTTP Header
2393 Fields Containing Sensitive Information
2394 </A>
2395 </H3>
2396 <P>
2397 Some HTTP header fields may carry sensitive information which the server
2398 SHOULD NOT pass on to the script unless explicitly configured to do
2399 so. For example, if the server protects the script using the
2400 "<SAMP>Basic</SAMP>"
2401 authentication scheme, then the client will send an
2402 "<SAMP>Authorization</SAMP>"
2403 header field containing a username and password. If the server, rather
2404 than the script, validates this information then the password SHOULD
2406 metavariable
2407 without careful consideration.
2408 This also applies to the
2409 Proxy-Authorization header field and the corresponding
2410 HTTP_PROXY_AUTHORIZATION
2411 metavariable.
2412 </P>
2414 <H3>
2416 11.3. Script
2417 Interference with the Server
2418 </A>
2419 </H3>
2420 <P>
2421 The most common implementation of CGI invokes the script as a child
2422 process using the same user and group as the server process. It
2423 SHOULD therefore be ensured that the script cannot interfere with the
2424 server process, its configuration, or documents.
2425 </P>
2426 <P>
2427 If the script is executed by calling a function linked in to the
2428 server software (either at compile-time or run-time) then precautions
2429 SHOULD be taken to protect the core memory of the server, or to
2430 ensure that untrusted code cannot be executed.
2431 </P>
2433 <H3>
2435 11.4. Data Length and Buffering Considerations
2436 </A>
2437 </H3>
2438 <P>
2439 This specification places no limits on the length of message-bodies
2440 presented to the script. Scripts should not assume that statically
2441 allocated buffers of any size are sufficient to contain the entire
2442 submission at one time. Use of a fixed length buffer without careful
2443 overflow checking may result in an attacker exploiting 'stack-smashing'
2444 or 'stack-overflow' vulnerabilities of the operating system.
2445 Scripts may spool large submissions to disk or other buffering media,
2446 but a rapid succession of large submissions may result in denial of
2447 service conditions. If the CONTENT_LENGTH of a message-body is larger
2448 than resource considerations allow, scripts should respond with an
2449 error status appropriate for the protocol version; potentially applicable
2453 </P>
2455 <H3>
2457 11.5. Stateless Processing
2458 </A>
2459 </H3>
2460 <P>
2461 The stateless nature of the Web makes each script execution and resource
2462 retrieval independent of all others even when multiple requests constitute a
2463 single conceptual Web transaction. Because of this, a script should not
2464 make any assumptions about the context of the user-agent submitting a
2465 request. In particular, scripts should examine data obtained from the client
2466 and verify that they are valid, both in form and content, before allowing
2467 them to be used for sensitive purposes such as input to other
2468 applications, commands, or operating system services. These uses
2469 include, but are not
2470 limited to: system call arguments, database writes, dynamically evaluated
2471 source code, and input to billing or other secure processes. It is important
2472 that applications be protected from invalid input regardless of whether
2473 the invalidity is the result of user error, logic error, or malicious action.
2474 </P>
2475 <P>
2476 Authors of scripts involved in multi-request transactions should be
2477 particularly cautios about validating the state information;
2478 undesirable effects may result from the substitution of dangerous
2479 values for portions of the submission which might otherwise be
2480 presumed safe. Subversion of this type occurs when alterations
2481 are made to data from a prior stage of the transaction that were
2484 </P>
2486 <H2>
2488 12. Acknowledgements
2489 </A>
2490 </H2>
2491 <P>
2492 This work is based on a draft published in 1997 by David R. Robinson,
2493 which in turn was based on the original CGI interface that arose out of
2495 Rob McCool, John Franks, Ari Luotonen,
2496 George Phillips and
2497 Tony Sanders deserve special recognition for their efforts in
2498 defining and implementing the early versions of this interface.
2499 </P>
2500 <P>
2501 This document has also greatly benefited from the comments and
2502 suggestions made by Chris Adie, Dave Kristol,
2503 Mike Meyer, David Morris, Jeremy Madea,
2505 Ross Patterson, and Harald Alvestrand.
2506 </P>
2508 <H2>
2510 13. References
2511 </A>
2512 </H2>
2515 </DT>
2516 <DD>Berners-Lee, T., 'Universal Resource Identifiers in WWW: A
2517 Unifying Syntax for the Expression of Names and Addresses of
2518 Objects on the Network as used in the World-Wide Web', RFC 1630,
2519 CERN, June 1994.
2520 <P>
2521 </P>
2522 </DD>
2524 </DT>
2525 <DD>Berners-Lee, T. and Connolly, D., 'Hypertext Markup Language -
2527 <P>
2528 </P>
2529 </DD>
2531 </DT>
2532 <DD>Berners-Lee, T., Fielding, R. T. and Frystyk, H.,
2534 UC Irvine, May 1996.
2535 <P>
2536 </P>
2537 </DD>
2540 </DT>
2541 <DD>Berners-Lee, T., Fielding, R., and Masinter, L., Editors,
2542 'Uniform Resource Identifiers (URI): Generic Syntax', RFC 2396,
2543 MIT, U.C. Irvine, Xerox Corporation, August 1996.
2544 <P>
2545 </P>
2546 </DD>
2549 </DT>
2550 <DD>Braden, R., Editor, 'Requirements for Internet Hosts --
2552 <P>
2553 </P>
2554 </DD>
2556 </DT>
2557 <DD>Crocker, D.H., 'Standard for the Format of ARPA Internet Text
2559 <P>
2560 </P>
2561 </DD>
2563 </DT>
2565 UC Irvine, June 1995.
2566 <P>
2567 </P>
2568 </DD>
2570 </DT>
2571 <DD>Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and
2572 Berners-Lee, T., 'Hypertext Transfer Protocol -- HTTP/1.1',
2573 RFC 2068, UC Irvine, DEC,
2574 MIT/LCS, January 1997.
2575 <P>
2576 </P>
2577 </DD>
2579 </DT>
2580 <DD>Freed, N. and Borenstein N., 'Multipurpose Internet Mail
2581 Extensions (MIME) Part Two: Media Types', RFC 2046, Innosoft,
2582 First Virtual, November 1996.
2583 <P>
2584 </P>
2585 </DD>
2587 </DT>
2588 <DD>Mockapetris, P., 'Domain Names - Concepts and Facilities',
2590 <P>
2591 </P>
2592 </DD>
2594 </DT>
2596 Department of Defense, February 1993.
2597 <P>
2598 </P>
2599 </DD>
2601 </DT>
2603 Information Interchange', ANSI X3.4-1986.
2604 <P>
2605 </P>
2606 </DD>
2608 </DT>
2609 <DD>Hinden, R. and Deering, S.,
2611 Nokia, Cisco Systems,
2612 July 1998.
2613 <P>
2614 </P>
2615 </DD>
2616 </DL>
2618 <H2>
2620 14. Authors' Addresses
2621 </A>
2622 </H2>
2623 <ADDRESS>
2624 <P>
2625 Ken A L Coar
2626 <BR>
2627 MeepZor Consulting
2628 <BR>
2630 <BR>
2632 <BR>
2633 U.S.A.
2634 </P>
2635 <P>
2637 <BR>
2639 <BR>
2640 Email:
2641 <A
2644 </P>
2645 </ADDRESS>
2646 <ADDRESS>
2647 <P>
2648 David Robinson
2649 <BR>
2650 E*TRADE UK Ltd
2651 <BR>
2652 Mount Pleasant House
2653 <BR>
2654 2 Mount Pleasant
2655 <BR>
2656 Huntingdon Road
2657 <BR>
2658 Cambridge CB3 0RN
2659 <BR>
2660 UK
2661 </P>
2662 <P>
2664 <BR>
2666 <BR>
2667 Email:
2668 <A
2671 </ADDRESS>
2673 </BODY>
2674 </HTML>