Gitiles
Code Review Sign In
gerrit.nordix.org / codeaurora / busybox / 48af95e039d5cc9e5e4ad74791d0e7cd13de70b3 / . / docs / draft-coar-cgi-v11-03-clean.html
blob: d52c9b842cd5fa4870be097558aba6dceb87e79e [file] [log] [blame]
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
2 "http://www.w3.org/TR/REC-html40/loose.dtd">
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 -->
10 <LINK HREF="mailto:Ken.Coar@Golux.Com" rev="revised">
11 <LINK REL="STYLESHEET" HREF="cgip-style-rfc.css" TYPE="text/css">
12 <META name="latexstyle" content="rfc">
13 <META name="author" content="Ken A L Coar">
14 <META name="institute" content="IBM Corporation">
15 <META name="date" content="25 June 1999">
16 <META name="expires" content="Expires 31 December 1999">
17 <META name="document" content="INTERNET-DRAFT">
18 <META name="file" content="&lt;draft-coar-cgi-v11-03.txt&gt;">
19 <META name="group" content="INTERNET-DRAFT">
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.
32
33<DIV ALIGN="CENTER">
34 <PRE>
35
36
37
38
39Coar, et al. CGI/1.1 Specification May, 1998
40INTERNET-DRAFT Expires 1 December 1998 [Page 2]
41
42
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 -->
51 <DIV ALIGN="CENTER">
52 <TABLE WIDTH="100%" CELLPADDING=0 CELLSPACING=0>
53 <TR VALIGN="TOP">
54 <TD ALIGN="LEFT">
55 INTERNET-DRAFT&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
56 </TD>
57 <TD ALIGN="RIGHT">
58 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Ken A L Coar
59 </TD>
60 </TR>
61 <TR VALIGN="TOP">
62 <TD ALIGN="LEFT">
63 draft-coar-cgi-v11-03.{html,txt}&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
64 </TD>
65 <TD ALIGN="RIGHT">
66 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;IBM Corporation
67 </TD>
68 </TR>
69 <TR VALIGN="TOP">
70 <TD ALIGN="LEFT">
71 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
72 </TD>
73 <TD ALIGN="RIGHT">
74 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;D.R.T. Robinson
75 </TD>
76 </TR>
77 <TR VALIGN="TOP">
78 <TD ALIGN="LEFT">
79 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
80 </TD>
81 <TD ALIGN="RIGHT">
82 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;E*TRADE&nbsp;UK&nbsp;Ltd.
83 </TD>
84 </TR>
85 <TR VALIGN="TOP">
86 <TD ALIGN="LEFT">
87 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
88 </TD>
89 <TD ALIGN="RIGHT">
90 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;25 June 1999
91 </TD>
92 </TR>
93 </TABLE>
94 </DIV>
95
96 <H1 ALIGN="CENTER">
97 The WWW Common Gateway Interface
98 <BR>
99 Version 1.1
100 </H1>
101
102<!--#include virtual="I-D-statement" -->
103
104 <H2>
105 <A NAME="Abstract">
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
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]126 project Web page at
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]127 <SAMP>&lt;URL:<A HREF="http://CGI-Spec.Golux.Com/"
128 >http://CGI-Spec.Golux.Com/</A>&gt;</SAMP>
129 for details on the mailing list and the status of the project.
130 </P>
131
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>
142 <DL COMPACT>
143 <DT>Black
144 </DT>
145 <DD>Revision 00, released 28 May 1998
146 </DD>
147 <DT>Green
148 </DT>
149 <DD>Revision 01, released 28 December 1998
150 <BR>
151 Major structure change: Section 4, "Request Metadata (Meta-Variables)"
152 was moved entirely under <A HREF="#7.0">Section 7</A>, "Data Input to the
153 CGI Script."
154 Due to the size of this change, it is noted here and the text in its
155 former location does <EM>not</EM> appear as struckthrough. This has
156 caused major <A HREF="#6.0">sections 5</A> and following to decrement
157 by one. Other
158 large text movements are likewise not marked up. References to RFC
159 1738 were changed to 2396 (1738's replacement).
160 </DD>
161 <DT>Red
162 </DT>
163 <DD>Revision 02, released 2 April, 1999
164 <BR>
165 Added text to <A HREF="#8.3">section 8.3</A> defining correct handling
166 of HTTP/1.1
167 requests using "chunked" Transfer-Encoding. Labelled metavariable
168 names in <A HREF="#8.0">section 8</A> with the appropriate detail section
169 numbers.
170 Clarified allowed usage of <SAMP>Status</SAMP> and
171 <SAMP>Location</SAMP> response header fields. Included new
172 Internet-Draft language.
173 </DD>
174 <DT>Fuchsia
175 </DT>
176 <DD>Revision 03, released 25 June 1999
177 <BR>
178 Changed references from "HTTP" to "Protocol-Specific" for the listing of
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 -->
191
192 <H2>
193 <A NAME="Contents">
194 Table of Contents
195 </A>
196 </H2>
197 <DIV ALIGN="CENTER">
198 <PRE>
199 1 Introduction..............................................<A
200 HREF="#1.0"
201 >TBD</A>
202 1.1 Purpose................................................<A
203 HREF="#1.1"
204 >TBD</A>
205 1.2 Requirements...........................................<A
206 HREF="#1.2"
207 >TBD</A>
208 1.3 Specifications.........................................<A
209 HREF="#1.3"
210 >TBD</A>
211 1.4 Terminology............................................<A
212 HREF="#1.4"
213 >TBD</A>
214 2 Notational Conventions and Generic Grammar................<A
215 HREF="#2.0"
216 >TBD</A>
217 2.1 Augmented BNF..........................................<A
218 HREF="#2.1"
219 >TBD</A>
220 2.2 Basic Rules............................................<A
221 HREF="#2.2"
222 >TBD</A>
223 3 Protocol Parameters.......................................<A
224 HREF="#3.0"
225 >TBD</A>
226 3.1 URL Encoding...........................................<A
227 HREF="#3.1"
228 >TBD</A>
229 3.2 The Script-URI.........................................<A
230 HREF="#3.2"
231 >TBD</A>
232 4 Invoking the Script.......................................<A
233 HREF="#4.0"
234 >TBD</A>
235 5 The CGI Script Command Line...............................<A
236 HREF="#5.0"
237 >TBD</A>
238 6 Data Input to the CGI Script..............................<A
239 HREF="#6.0"
240 >TBD</A>
241 6.1 Request Metadata (Metavariables).......................<A
242 HREF="#6.1"
243 >TBD</A>
244 6.1.1 AUTH_TYPE...........................................<A
245 HREF="#6.1.1"
246 >TBD</A>
247 6.1.2 CONTENT_LENGTH......................................<A
248 HREF="#6.1.2"
249 >TBD</A>
250 6.1.3 CONTENT_TYPE........................................<A
251 HREF="#6.1.3"
252 >TBD</A>
253 6.1.4 GATEWAY_INTERFACE...................................<A
254 HREF="#6.1.4"
255 >TBD</A>
256 6.1.5 Protocol-Specific Metavariables.....................<A
257 HREF="#6.1.5"
258 >TBD</A>
259 6.1.6 PATH_INFO...........................................<A
260 HREF="#6.1.6"
261 >TBD</A>
262 6.1.7 PATH_TRANSLATED.....................................<A
263 HREF="#6.1.7"
264 >TBD</A>
265 6.1.8 QUERY_STRING........................................<A
266 HREF="#6.1.8"
267 >TBD</A>
268 6.1.9 REMOTE_ADDR.........................................<A
269 HREF="#6.1.9"
270 >TBD</A>
271 6.1.10 REMOTE_HOST........................................<A
272 HREF="#6.1.10"
273 >TBD</A>
274 6.1.11 REMOTE_IDENT.......................................<A
275 HREF="#6.1.11"
276 >TBD</A>
277 6.1.12 REMOTE_USER........................................<A
278 HREF="#6.1.12"
279 >TBD</A>
280 6.1.13 REQUEST_METHOD.....................................<A
281 HREF="#6.1.13"
282 >TBD</A>
283 6.1.14 SCRIPT_NAME........................................<A
284 HREF="#6.1.14"
285 >TBD</A>
286 6.1.15 SERVER_NAME........................................<A
287 HREF="#6.1.15"
288 >TBD</A>
289 6.1.16 SERVER_PORT........................................<A
290 HREF="#6.1.16"
291 >TBD</A>
292 6.1.17 SERVER_PROTOCOL....................................<A
293 HREF="#6.1.17"
294 >TBD</A>
295 6.1.18 SERVER_SOFTWARE....................................<A
296 HREF="#6.1.18"
297 >TBD</A>
298 6.2 Request Message-Bodies................................<A
299 HREF="#6.2"
300 >TBD</A>
301 7 Data Output from the CGI Script...........................<A
302 HREF="#7.0"
303 >TBD</A>
304 7.1 Non-Parsed Header Output...............................<A
305 HREF="#7.1"
306 >TBD</A>
307 7.2 Parsed Header Output...................................<A
308 HREF="#7.2"
309 >TBD</A>
310 7.2.1 CGI header fields...................................<A
311 HREF="#7.2.1"
312 >TBD</A>
313 7.2.1.1 Content-Type.....................................<A
314 HREF="#7.2.1.1"
315 >TBD</A>
316 7.2.1.2 Location.........................................<A
317 HREF="#7.2.1.2"
318 >TBD</A>
319 7.2.1.3 Status...........................................<A
320 HREF="#7.2.1.3"
321 >TBD</A>
322 7.2.1.4 Extension header fields..........................<A
323 HREF="#7.2.1.3"
324 >TBD</A>
325 7.2.2 HTTP header fields..................................<A
326 HREF="#7.2.2"
327 >TBD</A>
328 8 Server Implementation.....................................<A
329 HREF="#8.0"
330 >TBD</A>
331 8.1 Requirements for Servers...............................<A
332 HREF="#8.1"
333 >TBD</A>
334 8.1.1 Script-URI..........................................<A
335 HREF="#8.1"
336 >TBD</A>
337 8.1.2 Request Message-body Handling.......................<A
338 HREF="#8.1.2"
339 >TBD</A>
340 8.1.3 Required Metavariables..............................<A
341 HREF="#8.1.3"
342 >TBD</A>
343 8.1.4 Response Compliance.................................<A
344 HREF="#8.1.4"
345 >TBD</A>
346 8.2 Recommendations for Servers............................<A
347 HREF="#8.2"
348 >TBD</A>
349 8.3 Summary of Metavariables...............................<A
350 HREF="#8.3"
351 >TBD</A>
352 9 Script Implementation.....................................<A
353 HREF="#9.0"
354 >TBD</A>
355 9.1 Requirements for Scripts...............................<A
356 HREF="#9.1"
357 >TBD</A>
358 9.2 Recommendations for Scripts............................<A
359 HREF="#9.2"
360 >TBD</A>
361 10 System Specifications....................................<A
362 HREF="#10.0"
363 >TBD</A>
364 10.1 AmigaDOS..............................................<A
365 HREF="#10.1"
366 >TBD</A>
367 10.2 Unix..................................................<A
368 HREF="#10.2"
369 >TBD</A>
370 11 Security Considerations..................................<A
371 HREF="#11.0"
372 >TBD</A>
373 11.1 Safe Methods..........................................<A
374 HREF="#11.1"
375 >TBD</A>
376 11.2 HTTP Header Fields Containing Sensitive Information...<A
377 HREF="#11.2"
378 >TBD</A>
379 11.3 Script Interference with the Server...................<A
380 HREF="#11.3"
381 >TBD</A>
382 11.4 Data Length and Buffering Considerations..............<A
383 HREF="#11.4"
384 >TBD</A>
385 11.5 Stateless Processing..................................<A
386 HREF="#11.5"
387 >TBD</A>
388 12 Acknowledgments..........................................<A
389 HREF="#12.0"
390 >TBD</A>
391 13 References...............................................<A
392 HREF="#13.0"
393 >TBD</A>
394 14 Authors' Addresses.......................................<A
395 HREF="#14.0"
396 >TBD</A>
397 </PRE>
398 </DIV>
399
400 <H2>
401 <A NAME="1.0">
402 1. Introduction
403 </A>
404 </H2>
405
406 <H3>
407 <A NAME="1.1">
408 1.1. Purpose
409 </A>
410 </H3>
411 <P>
412 Together the HTTP [<A HREF="#[3]">3</A>,<A HREF="#[8]">8</A>] server
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]413 and the CGI script are responsible
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]414 for servicing a client
415 request by sending back responses. The client
416 request comprises a Universal Resource Identifier (URI)
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]417 [<A HREF="#[1]">1</A>], a
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]418 request method, and various ancillary
419 information about the request
420 provided by the transport mechanism.
421 </P>
422 <P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]423 The CGI defines the abstract parameters, known as
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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>
430
431 <H3>
432 <A NAME="1.2">
433 1.2. Requirements
434 </A>
435 </H3>
436 <P>
437 This specification uses the same words as RFC 1123
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]438 [<A HREF="#[5]">5</A>] to define the
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]439 significance of each particular requirement. These are:
440 </P><!--#if expr="! $GUI" -->
441 <P></P><!--#endif -->
442 <DL>
443 <DT><EM>MUST</EM>
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>
451 <DT><EM>SHOULD</EM>
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>
461 <DT><EM>MAY</EM>
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]481
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]482 <H3>
483 <A NAME="1.3">
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>
493 <DT><EM>system defined</EM>
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
501 <A HREF="#10.0"
502 >section 10</A> of this document.
503 New systems may be defined
504 by new specifications without revision of this document.
505 </P>
506 </DD>
507 <DT><EM>implementation defined</EM>
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]517
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]518 <H3>
519 <A NAME="1.4">
520 1.4. Terminology
521 </A>
522 </H3>
523 <P>
524 This specification uses many terms defined in the HTTP/1.1
525 specification [<A HREF="#[8]">8</A>]; however, the following terms are
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]526 used here in a
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]527 sense which may not accord with their definitions in that document,
528 or with their common meaning.
529 </P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]530
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]531 <DL>
532 <DT><EM>metavariable</EM>
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]541
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]542 <DT><EM>script</EM>
543 </DT>
544 <DD>
545 <P>
546 The software which is invoked by the server <EM>via</EM> this
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]547 interface. It
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]548 need not be a standalone program, but could be a
549 dynamically-loaded or shared library, or even a subroutine in the
550 server. It <EM>may</EM> be a set of statements
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>
556 <DT><EM>server</EM>
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]565
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]566 <H2>
567 <A NAME="2.0">
568 2. Notational Conventions and Generic Grammar
569 </A>
570 </H2>
571
572 <H3>
573 <A NAME="2.1">
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
580 used by RFC 822 [<A HREF="#[6]">6</A>]. This augmented BNF contains
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>
594 <DT>"literal"
595 </DT>
596 <DD>
597 <P>
598 Quotation marks (") surround literal text, except for a literal
599 quotation mark, which is surrounded by angle-brackets ("&lt;" and "&gt;").
600 Unless stated otherwise, the text is case-sensitive.
601 </P>
602 </DD>
603 <DT>rule1 | rule2
604 </DT>
605 <DD>
606 <P>
607 Alternative rules are separated by a vertical bar ("|").
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>
621 A rule preceded by an asterisk ("*") may have zero or more
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
631 brackets ("[" and "]") is optional.
632 </P>
633 </DD>
634 </DL>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]635
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]636 <H3>
637 <A NAME="2.2">
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.
644 </P><!--#if expr="! $GUI" -->
645 <P></P><!--#endif -->
646 <PRE>
647 alpha = lowalpha | hialpha
648 alphanum = alpha | digit
649 lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h"
650 | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p"
651 | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x"
652 | "y" | "z"
653 hialpha = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H"
654 | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P"
655 | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X"
656 | "Y" | "Z"
657 digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7"
658 | "8" | "9"
659 hex = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a"
660 | "b" | "c" | "d" | "e" | "f"
661 escaped = "%" hex hex
662 OCTET = &lt;any 8-bit sequence of data&gt;
663 CHAR = &lt;any US-ASCII character (octets 0 - 127)&gt;
664 CTL = &lt;any US-ASCII control character
665 (octets 0 - 31) and DEL (127)&gt;
666 CR = &lt;US-ASCII CR, carriage return (13)&gt;
667 LF = &lt;US-ASCII LF, linefeed (10)&gt;
668 SP = &lt;US-ASCII SP, space (32)&gt;
669 HT = &lt;US-ASCII HT, horizontal tab (9)&gt;
670 NL = CR | LF
671 LWSP = SP | HT | NL
672 tspecial = "(" | ")" | "@" | "," | ";" | ":" | "\" | &lt;"&gt;
673 | "/" | "[" | "]" | "?" | "&lt;" | "&gt;" | "{" | "}"
674 | SP | HT | NL
675 token = 1*&lt;any CHAR except CTLs or tspecials&gt;
676 quoted-string = ( &lt;"&gt; *qdtext &lt;"&gt; ) | ( "&lt;" *qatext "&gt;")
677 qdtext = &lt;any CHAR except &lt;"&gt; and CTLs but including LWSP&gt;
678 qatext = &lt;any CHAR except "&lt;", "&gt;" and CTLs but
679 including LWSP&gt;
680 mark = "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")"
681 unreserved = alphanum | mark
682 reserved = ";" | "/" | "?" | ":" | "@" | "&amp;" | "=" |
683 "$" | ","
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]690
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]691 <H2>
692 <A NAME="3.0">
693 3. Protocol Parameters
694 </A>
695 </H2>
696
697 <H3>
698 <A NAME="3.1">
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
707 [<A HREF="#[4]">4</A>].
708 </P>
709 <P>
710 An alternate "shortcut" encoding for representing the space
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:
721 </P><!--#if expr="! $GUI" -->
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
730 2396 [<A HREF="#[4]">4</A>]
731 for authoritative treatment of this issue.
732 </P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]733
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]734 <H3>
735 <A NAME="3.2">
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,
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]742 this URI will be the same as
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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
749 of RFC 1808 [<A HREF="#[7]">7</A>], with the exception that object
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]750 parameters and
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]751 fragment identifiers are not permitted:
752 </P><!--#if expr="! $GUI" -->
753 <P></P><!--#endif -->
754 <PRE>
755 &lt;scheme&gt;://&lt;host&gt;&lt;port&gt;/&lt;path&gt;?&lt;query&gt;
756 </PRE>
757 <P>
758 The various components of the
759 Script-URI
760 are defined by some of the
761 metavariables (see
762 <A HREF="#4.0">section 4</A>
763 below);
764 </P><!--#if expr="! $GUI" -->
765 <P></P><!--#endif -->
766 <PRE>
767 script-uri = protocol "://" SERVER_NAME ":" SERVER_PORT enc-script
768 enc-path-info "?" QUERY_STRING
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
775 <A HREF="#4.6">section 4.6</A> for more information about the PATH_INFO
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
781 may have a Client-URI with a scheme of "<SAMP>https</SAMP>"
782 rather than "<SAMP>http</SAMP>". CGI/1.1 provides no means
783 for the script to reconstruct this, and therefore
784 the Script-URI includes the base protocol used.
785 </P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]786
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]787 <H2>
788 <A NAME="4.0">
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]798
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]799 <H2>
800 <A NAME="5.0">
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.
807 This is identified by a "GET" or "HEAD" HTTP request with a URL
808 query
809 string not containing any unencoded "=" characters. For such a
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]810 request,
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]811 servers SHOULD parse the search string
812 into words, using the following rules:
813 </P><!--#if expr="! $GUI" -->
814 <P></P><!--#endif -->
815 <PRE>
816 search-string = search-word *( "+" search-word )
817 search-word = 1*schar
818 schar = xunreserved | escaped | xreserved
819 xunreserved = alpha | digit | xsafe | extra
820 xsafe = "$" | "-" | "_" | "."
821 xreserved = ";" | "/" | "?" | ":" | "@" | "&"
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
838 unencoded "=" character, and SHOULD NOT use the command line arguments
839 if it does.
840 </P>
841
842 <H2>
843 <A NAME="6.0">
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>
855
856 <H3>
857 <A NAME="6.1">
858 6.1. Request Metadata
859 (Metavariables)
860 </A>
861 </H3>
862 <P>
863 Each CGI server
864 implementation MUST define a mechanism
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]865 to pass data about the request from
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]866 the server to the script.
867 The metavariables containing these
868 data
869 are accessed by the script in a system
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]870 defined manner.
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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
879 (such as a query component of "?" or "", respectively) are represented
880 by undefined metavariables or by metavariables with values of "" is
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
890 ("_"). The actual representation of the names is system defined; for
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:
904 </P><!--#if expr="! $GUI" -->
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>,
927 "HTTP_ACCEPT") are also canonical in their description of request header
928 fields. The number and meaning of these fields may change independently
929 of this specification. (See also <A HREF="#6.1.5">section 6.1.5</A>.)
930 </P>
931
932 <H4>
933 <A NAME="6.1.1">
934 6.1.1. AUTH_TYPE
935 </A>
936 </H4>
937 <P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]938 This variable is specific to requests made
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]939 <EM>via</EM> the
940 "<CODE>http</CODE>"
941 scheme.
942 </P>
943 <P>
944 If the Script-URI
945 required access authentication for external
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]946 access, then the server
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]947 MUST set
948 the value of
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]949 this variable
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]950 from the '<SAMP>auth-scheme</SAMP>' token in
951 the request's "<SAMP>Authorization</SAMP>" header
952 field.
953 Otherwise
954 it is
955 set to NULL.
956 </P><!--#if expr="! $GUI" -->
957 <P></P><!--#endif -->
958 <PRE>
959 AUTH_TYPE = "" | auth-scheme
960 auth-scheme = "Basic" | "Digest" | token
961 </PRE>
962 <P>
963 HTTP access authentication schemes are described in section 11 of the
964 HTTP/1.1 specification [<A HREF="#[8]">8</A>]. The auth-scheme is
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]965 not case-sensitive.
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]966 </P>
967 <P>
968 Servers
969 MUST
970 provide this metavariable
971 to scripts if the request
972 header included an "<SAMP>Authorization</SAMP>" field
973 that was authenticated.
974 </P>
975
976 <H4>
977 <A NAME="6.1.2">
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
992 the HTTP "<SAMP>Content-Length</SAMP>" header field (section 14.14, HTTP/1.1
993 specification [<A HREF="#[8]">8</A>]).
994 </P><!--#if expr="! $GUI" -->
995 <P></P><!--#endif -->
996 <PRE>
997 CONTENT_LENGTH = "" | 1*digit
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>
1005
1006 <H4>
1007 <A NAME="6.1.3">
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
1017 [<A HREF="#[9]">9</A>] of the attached
1018 entity if the type was provided <EM>via</EM>
1019 a "<SAMP>Content-type</SAMP>" field in the
1020 request header, or if the server can determine it in the absence
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1021 of a supplied "<SAMP>Content-type</SAMP>" field. The syntax is the
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1022 same as for the HTTP
1023 "<SAMP>Content-Type</SAMP>" header field.
1024 </P><!--#if expr="! $GUI" -->
1025 <P></P><!--#endif -->
1026 <PRE>
1027 CONTENT_TYPE = "" | media-type
1028 media-type = type "/" subtype *( ";" parameter)
1029 type = token
1030 subtype = token
1031 parameter = attribute "=" value
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
1041 HTTP/1.1 specification [<A HREF="#[8]">8</A>].
1042 </P>
1043 <P>
1044 Example:
1045 </P><!--#if expr="! $GUI" -->
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
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1056 <SAMP>application/octet-stream</SAMP>
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1057 or reject the request with a 415 ("Unsupported Media Type")
1058 error. See <A HREF="#7.2.1.3">section 7.2.1.3</A>
1059 for more information about returning error status values.
1060 </P>
1061 <P>
1062 Servers MUST provide this metavariable
1063 to scripts if
1064 a "<SAMP>Content-Type</SAMP>" field was present
1065 in the original request header. If the server receives a request
1066 with an attached entity but no "<SAMP>Content-Type</SAMP>"
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>
1072
1073 <H4>
1074 <A NAME="6.1.4">
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:
1085 </P><!--#if expr="! $GUI" -->
1086 <P></P><!--#endif -->
1087 <PRE>
1088 GATEWAY_INTERFACE = "CGI" "/" major "." minor
1089 major = 1*digit
1090 minor = 1*digit
1091 </PRE>
1092 <P>
1093 Note that the major and minor numbers are treated as separate
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1094 integers and hence each may be
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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
1103 ("CGI/1.1").
1104 </P>
1105 <P>
1106 Servers MUST provide this metavariable
1107 to scripts.
1108 </P>
1109
1110 <H4>
1111 <A NAME="6.1.5">
1112 6.1.5. Protocol-Specific Metavariables
1113 </A>
1114 </H4>
1115 <P>
1116 These metavariables are specific to
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1117 the protocol
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1118 <EM>via</EM> which the request is made.
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1119 Interpretation of these variables depends on the value of
1120 the
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1121 SERVER_PROTOCOL
1122 metavariable
1123 (see
1124 <A HREF="#6.1.17">section 6.1.17</A>).
1125 </P>
1126 <P>
1127 Metavariables
1128 with names beginning with "HTTP_" contain
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
1133 "-" replaced with "_",
1134 and has "HTTP_" prepended to form
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,
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1161 they MAY
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1162 decline to make available any
1163 header fields carrying authentication information, such as
1164 "<SAMP>Authorization</SAMP>", or
1165 which are available to the script
1166 <EM>via</EM> other metavariables,
1167 such as "<SAMP>Content-Length</SAMP>" and "<SAMP>Content-Type</SAMP>".
1168 </P>
1169
1170 <H4>
1171 <A NAME="6.1.6">
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
1190 [<A HREF="#[4]">4</A>]), with the exception
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1191 that a PATH_INFO of "/"
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1192 represents a single void path segment.
1193 </P><!--#if expr="! $GUI" -->
1194 <P></P><!--#endif -->
1195 <PRE>
1196 PATH_INFO = "" | ( "/" path )
1197 path = segment *( "/" segment )
1198 segment = *pchar
1199 pchar = &lt;any CHAR except "/"&gt;
1200 </PRE>
1201 <P>
1202 The PATH_INFO string is the trailing part of the &lt;path&gt; component of
1203 the Script-URI
1204 (see <A HREF="#3.2">section 3.2</A>)
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1205 that follows the SCRIPT_NAME
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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>
1222
1223 <H4>
1224 <A NAME="6.1.7">
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
1231 <A HREF="#6.1.6">section 6.1.6</A>), decoding it
1232 (see <A HREF="#3.1">section 3.1</A>), parsing it as a URI in its own
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.
1238 </P><!--#if expr="! $GUI" -->
1239 <P></P><!--#endif -->
1240 <PRE>
1241 PATH_TRANSLATED = *CHAR
1242 </PRE>
1243 <P>
1244 For a request such as the following:
1245 </P><!--#if expr="! $GUI" -->
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:
1253 </P><!--#if expr="! $GUI" -->
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:
1263 </P><!--#if expr="! $GUI" -->
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1288 The
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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>
1299
1300 <H4>
1301 <A NAME="6.1.8">
1302 6.1.8. QUERY_STRING
1303 </A>
1304 </H4>
1305 <P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1306 A URL-encoded
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1307 string; the &lt;query&gt; part of the
1308 Script-URI.
1309 (See
1310 <A HREF="#3.2">section 3.2</A>.)
1311 </P><!--#if expr="! $GUI" -->
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
1322 [<A HREF="#[4]">4</A>].
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,
1328 the QUERY_STRING metavariable MUST be defined as an empty string ("").
1329 </P>
1330
1331 <H4>
1332 <A NAME="6.1.9">
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).
1342 </P><!--#if expr="! $GUI" -->
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>
1350 are provided in Appendix B of RFC 2373 [<A HREF="#[13]">13</A>].
1351 </P>
1352 <P>
1353 Servers MUST supply this value to scripts.
1354 </P>
1355
1356 <H4>
1357 <A NAME="6.1.10">
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.
1365 (See <A HREF="#6.1.9">section 6.1.9</A>.)
1366 Fully qualified domain names take the form as described in
1367 section 3.5 of RFC 1034 [<A HREF="#[10]">10</A>] and section 2.1 of
1368 RFC 1123 [<A HREF="#[5]">5</A>]. Domain names are not case sensitive.
1369 </P>
1370 <P>
1371 Servers SHOULD provide this information to
1372 scripts.
1373 </P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1374
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1375 <H4>
1376 <A NAME="6.1.11">
1377 6.1.11. REMOTE_IDENT
1378 </A>
1379 </H4>
1380 <P>
1381 The identity information reported about the connection by a
1382 RFC 1413 [<A HREF="#[11]">11</A>] request to the remote agent, if
1383 available. Servers
1384 MAY choose not
1385 to support this feature, or not to request the data
1386 for efficiency reasons.
1387 </P><!--#if expr="! $GUI" -->
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
1399 RFC1413 [<A HREF="#[11]">11</A>] lookup is performed.
1400 </P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1401
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1402 <H4>
1403 <A NAME="6.1.12">
1404 6.1.12. REMOTE_USER
1405 </A>
1406 </H4>
1407 <P>
1408 If the request required authentication using the "Basic"
1409 mechanism (<EM>i.e.</EM>, the AUTH_TYPE
1410 metavariable is set
1411 to "Basic"), then the value of the REMOTE_USER
1412 metavariable is set to the
1413 user-ID supplied. In all other cases
1414 the value of this metavariable
1415 is undefined.
1416 </P><!--#if expr="! $GUI" -->
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1429
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1430 <H4>
1431 <A NAME="6.1.13">
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
1440 5.1.1 of the HTTP/1.0 specification [<A HREF="#[3]">3</A>] and
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1441 section 5.1.1 of the
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1442 HTTP/1.1 specification [<A HREF="#[8]">8</A>].
1443 </P><!--#if expr="! $GUI" -->
1444 <P></P><!--#endif -->
1445 <PRE>
1446 REQUEST_METHOD = http-method
1447 http-method = "GET" | "HEAD" | "POST" | "PUT" | "DELETE"
1448 | "OPTIONS" | "TRACE" | extension-method
1449 extension-method = token
1450 </PRE>
1451 <P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1452 The method is case sensitive.
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1463
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1464 <H4>
1465 <A NAME="6.1.14">
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
1478 [<A HREF="#[4]">4</A>]).
1479 </P><!--#if expr="! $GUI" -->
1480 <P></P><!--#endif -->
1481 <PRE>
1482 SCRIPT_NAME = "" | ( "/" [ path ] )
1483 </PRE>
1484 <P>
1485 The SCRIPT_NAME string is some leading part of the &lt;path&gt; component
1486 of the Script-URI derived in some
1487 implementation defined manner.
1488 No PATH_INFO or QUERY_STRING segments
1489 (see sections <A HREF="#6.1.6">6.1.6</A> and
1490 <A HREF="#6.1.8">6.1.8</A>) are included
1491 in the SCRIPT_NAME value.
1492 </P>
1493 <P>
1494 Servers MUST provide this metavariable
1495 to scripts.
1496 </P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1497
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1498 <H4>
1499 <A NAME="6.1.15">
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
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1508 server, as
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1509 derived from the &lt;host&gt; part of the
1510 Script-URI
1511 (see <A HREF="#3.2">section 3.2</A>).
1512 </P><!--#if expr="! $GUI" -->
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>
1521
1522 <H4>
1523 <A NAME="6.1.16">
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 &lt;port&gt;
1533 part of the Script-URI.
1534 </P><!--#if expr="! $GUI" -->
1535 <P></P><!--#endif -->
1536 <PRE>
1537 SERVER_PORT = 1*digit
1538 </PRE>
1539 <P>
1540 If the &lt;port&gt; 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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1547
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1548 <H4>
1549 <A NAME="6.1.17">
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.
1563 </P><!--#if expr="! $GUI" -->
1564 <P></P><!--#endif -->
1565 <PRE>
1566 SERVER_PROTOCOL = HTTP-Version | extension-version
1567 | extension-token
1568 HTTP-Version = "HTTP" "/" 1*digit "." 1*digit
1569 extension-version = protocol "/" 1*digit "." 1*digit
1570 protocol = 1*( alpha | digit | "+" | "-" | "." )
1571 extension-token = token
1572 </PRE>
1573 <P>
1574 'protocol' is a version of the &lt;scheme&gt; part of the
1575 Script-URI, but is
1576 not identical to it. For example, the scheme of a request may be
1577 "<SAMP>https</SAMP>" while the protocol remains "<SAMP>http</SAMP>".
1578 The protocol is not case sensitive, but
1579 by convention, 'protocol' is in
1580 upper case.
1581 </P>
1582 <P>
1583 A well-known extension token value is "INCLUDED",
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1592
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1593 <H4>
1594 <A NAME="6.1.18">
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).
1604 </P><!--#if expr="! $GUI" -->
1605 <P></P><!--#endif -->
1606 <PRE>
1607 SERVER_SOFTWARE = 1*product
1608 product = token [ "/" product-version ]
1609 product-version = token
1610 </PRE>
1611 <P>
1612 Servers MUST provide this metavariable
1613 to scripts.
1614 </P>
1615
1616 <H3>
1617 <A NAME="6.2">
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>
1629 If the CONTENT_LENGTH value (see <A HREF="#6.1.2">section 6.1.2</A>)
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
1643 <A HREF="#7.1">section 7.1</A>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1644 below),
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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>
1652 <A HREF="#8.1.2">Section 8.1.2</A> describes the requirements of
1653 servers with regard to requests that include
1654 message-bodies.
1655 </P>
1656
1657 <H2>
1658 <A NAME="7.0">
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>
1686
1687 <H3>
1688 <A NAME="7.1">
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
1696 [<A HREF="#[3]">3</A>,<A HREF="#[8]">8</A>].
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1708
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1709 <H3>
1710 <A NAME="7.2">
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:
1718 </P><!--#if expr="! $GUI" -->
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.
1739 If a body is supplied, then a "<SAMP>Content-type</SAMP>"
1740 header field MUST be
1741 supplied by the script,
1742 otherwise the script MUST send a "<SAMP>Location</SAMP>"
1743 or "<SAMP>Status</SAMP>" header field. If a
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>
1752
1753 <H4>
1754 <A NAME="7.2.1">
1755 7.2.1. CGI header fields
1756 </A>
1757 </H4>
1758 <P>
1759 The CGI header fields have the generic syntax:
1760 </P><!--#if expr="! $GUI" -->
1761 <P></P><!--#endif -->
1762 <PRE>
1763 generic-field = field-name ":" [ field-value ] NL
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>
1772
1773 <H4>
1774 <A NAME="7.2.1.1">
1775 7.2.1.1. Content-Type
1776 </A>
1777 </H4>
1778 <P>
1779 The Internet Media Type [<A HREF="#[9]">9</A>] of the entity
1780 body, which is to be sent unmodified to the client.
1781 </P><!--#if expr="! $GUI" -->
1782 <P></P><!--#endif -->
1783 <PRE>
1784 Content-Type = "Content-Type" ":" media-type NL
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
1790 a member of the "one of these is required" set of header
1791 fields.
1792 </P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1793
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1794 <H4>
1795 <A NAME="7.2.1.2">
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.
1802 </P><!--#if expr="! $GUI" -->
1803 <P></P><!--#endif -->
1804 <PRE>
1805 Location = "Location" ":"
1806 ( fragment-URI | rel-URL-abs-path ) NL
1807 fragment-URI = URI [ # fragmentid ]
1808 URI = scheme ":" *qchar
1809 fragmentid = *qchar
1810 rel-URL-abs-path = "/" [ hpath ] [ "?" query-string ]
1811 hpath = fpsegment *( "/" psegment )
1812 fpsegment = 1*hchar
1813 psegment = *hchar
1814 hchar = alpha | digit | safe | extra
1815 | ":" | "@" | "& | "="
1816 </PRE>
1817 <P>
1818 The Location
1819 value is either an absolute URI with optional fragment,
1820 as defined in RFC 1630 [<A HREF="#[1]">1</A>], or an absolute path
1821 within the server's URI space (<EM>i.e.</EM>,
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1822 omitting the scheme and network-related fields) and optional
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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
1837 </P><!--#if expr="! $GUI" -->
1838 <P></P><!--#endif -->
1839 <PRE>
1840 scheme "://" SERVER_NAME ":" SERVER_PORT rel-URL-abs-path
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>
1851
1852 <H4>
1853 <A NAME="7.2.1.3">
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.
1860 </P><!--#if expr="! $GUI" -->
1861 <P></P><!--#endif -->
1862 <PRE>
1863 Status = "Status" ":" digit digit digit SP reason-phrase NL
1864 reason-phrase = *&lt;CHAR, excluding CTLs, NL&gt;
1865 </PRE>
1866 <P>
1867 The valid status codes are listed in section 6.1.1 of the HTTP/1.0
1868 specifications [<A HREF="#[3]">3</A>]. If the SERVER_PROTOCOL is
1869 "HTTP/1.1", then the status codes defined in the HTTP/1.1
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1870 specification [<A HREF="#[8]">8</A>] may
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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
1878 condition back to the client. <EM>E.g.</EM>, in the example mentioned it
1879 SHOULD include a "Status:&nbsp;404&nbsp;Not&nbsp;Found" in the
1880 header data returned to the server.
1881 </P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1882
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]1883 <H4>
1884 <A NAME="7.2.1.4">
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,
1892 and have the syntax of a <SAMP>generic-field</SAMP> as defined in
1893 <A HREF="#7.2.1">section 7.2.1</A>. The name of an extension field
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>
1898
1899 <H4>
1900 <A NAME="7.2.2">
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
1907 for the SERVER_PROTOCOL (HTTP/1.0 [<A HREF="#[3]">3</A>] or HTTP/1.1
1908 [<A HREF="#[8]">8</A>]).
1909 Servers MUST resolve conflicts beteen CGI header
1910 and HTTP header formats or names (see <A HREF="#8.0">section 8</A>).
1911 </P>
1912
1913 <H2>
1914 <A NAME="8.0">
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>
1925
1926 <H3>
1927 <A NAME="8.1">
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>
1936
1937 <H3>
1938 <A NAME="8.1.1">
1939 8.1.1. Script-URI
1940 </A>
1941 </H3>
1942 <P>
1943 Servers MUST support the standard mechanism (described below) which
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1944 allows
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1954 The server
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]1958 sequence for
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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>
1964
1965 <H3>
1966 <A NAME="8.1.2">
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>
1985
1986 <H3>
1987 <A NAME="8.1.3">
1988 8.1.3. Required Metavariables
1989 </A>
1990 </H3>
1991 <P>
1992 Servers MUST provide scripts with certain information and
1993 metavariables
1994 as described in <A HREF="#8.3">section 8.3</A>.
1995 </P>
1996
1997 <H3>
1998 <A NAME="8.1.4">
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>
2008
2009 <H3>
2010 <A NAME="8.2">
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.
2019 (See <A HREF="#5.0">section 5</A>.)
2020 </P>
2021 <P>
2022 Servers SHOULD set the AUTH_TYPE
2023 metavariable to the value of the
2024 '<SAMP>auth-scheme</SAMP>' token of the "<SAMP>Authorization</SAMP>"
2025 field if it was supplied as part of the request header.
2026 (See <A HREF="#6.1.1">section 6.1.1</A>.)
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>
2053 <LI>define the behaviour for <SAMP>"."</SAMP> or <SAMP>".."</SAMP> path
2054 segments; <EM>i.e.</EM>, whether they are prohibited, treated as
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2055 ordinary path
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2056 segments or interpreted in accordance with the relative URL
2057 specification [<A HREF="#[7]">7</A>];
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.
2062 </LI><!-- ##### Move the field resolution/translation para below here -->
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
2072 <A HREF="#7.1">section 7.1</A>), servers SHOULD
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>
2077
2078 <H3>
2079 <A NAME="8.3">
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.
2088 </P><!--#if expr="! $GUI" -->
2089 <P></P><!--#endif -->
2090 <PRE>
2091 CONTENT_LENGTH (section <A HREF="#6.1.2">6.1.2</A>)
2092 CONTENT_TYPE (section <A HREF="#6.1.3">6.1.3</A>)
2093 GATEWAY_INTERFACE (section <A HREF="#6.1.4">6.1.4</A>)
2094 PATH_INFO (section <A HREF="#6.1.6">6.1.6</A>)
2095 QUERY_STRING (section <A HREF="#6.1.8">6.1.8</A>)
2096 REMOTE_ADDR (section <A HREF="#6.1.9">6.1.9</A>)
2097 REQUEST_METHOD (section <A HREF="#6.1.13">6.1.13</A>)
2098 SCRIPT_NAME (section <A HREF="#6.1.14">6.1.14</A>)
2099 SERVER_NAME (section <A HREF="#6.1.15">6.1.15</A>)
2100 SERVER_PORT (section <A HREF="#6.1.16">6.1.16</A>)
2101 SERVER_PROTOCOL (section <A HREF="#6.1.17">6.1.17</A>)
2102 SERVER_SOFTWARE (section <A HREF="#6.1.18">6.1.18</A>)
2103 </PRE>
2104 <P>
2105 Servers SHOULD define the following
2106 metavariables for scripts.
2107 See the individual descriptions for exceptions and semantics.
2108 </P><!--#if expr="! $GUI" -->
2109 <P></P><!--#endif -->
2110 <PRE>
2111 AUTH_TYPE (section <A HREF="#6.1.1">6.1.1</A>)
2112 REMOTE_HOST (section <A HREF="#6.1.10">6.1.10</A>)
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.
2126 </P><!--#if expr="! $GUI" -->
2127 <P></P><!--#endif -->
2128 <PRE>
2129 PATH_TRANSLATED (section <A HREF="#6.1.7">6.1.7</A>)
2130 REMOTE_IDENT (section <A HREF="#6.1.11">6.1.11</A>)
2131 REMOTE_USER (section <A HREF="#6.1.12">6.1.12</A>)
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
2140 be prefixed with "X_" (<EM>e.g.</EM>,
2141 "X_DBA") to avoid the potential for such conflicts.
2142 </P>
2143
2144 <H2>
2145 <A NAME="9.0">
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2146 9.
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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>
2156
2157 <H3>
2158 <A NAME="9.1">
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.
2165 (See <A HREF="#7.0">section 7</A>.)
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.
2172 (See <A HREF="#7.1">section 7.1</A>.)
2173 </P>
2174 <P>
2175 Scripts MUST check the value of the REQUEST_METHOD
2176 metavariable in order
2177 to provide an appropriate response.
2178 (See <A HREF="#6.1.13">section 6.1.13</A>.)
2179 </P>
2180 <P>
2181 Scripts MUST be prepared to handled URL-encoded values in
2182 metavariables.
2183 In addition, they MUST recognise both "+" and "%20" in URL-encoded
2184 quantities as representing the space character.
2185 (See <A HREF="#3.1">section 3.1</A>.)
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
2191 <A HREF="#6.1.4">section 6.1.4</A>.)
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.
2197 (See sections <A HREF="#6.1.2">6.1.2</A> and <A HREF="#6.2">6.2</A>.)
2198 </P>
2199
2200 <H3>
2201 <A NAME="9.2">
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2222 If a script is processing the output of a form, it SHOULD
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2223 verify that the CONTENT_TYPE
2224 is "<SAMP>application/x-www-form-urlencoded</SAMP>" [<A HREF="#[2]">2</A>]
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
2232 (<SAMP>"."</SAMP> and
2233 <SAMP>".."</SAMP>). They SHOULD either be removed from the path before
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2234 use in OS
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2235 system calls, or the request SHOULD be rejected with
2236 '404 Not Found'.
2237 </P>
2238 <P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2239 As it is impossible for
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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>&lt;BASE&gt;</SAMP>"
2246 tag in the document.
2247 </P>
2248 <P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2249 When returning header fields,
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2250 scripts SHOULD try to send the CGI
2251 header fields (see section
2252 <A HREF="#7.2">7.2</A>) as soon as possible, and
2253 SHOULD send them
2254 before any HTTP header fields. This may
2255 help reduce the server's memory requirements.
2256 </P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2257
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2258 <H2>
2259 <A NAME="10.0">
2260 10. System Specifications
2261 </A>
2262 </H2>
2263
2264 <H3>
2265 <A NAME="10.1">
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>
2275 <DT><STRONG>Environment variables</STRONG>
2276 </DT>
2277 <DD>
2278 <P>
2279 These are accessed by the DOS library routine <SAMP>GetVar</SAMP>. The
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>
2284 <DT><STRONG>The current working directory</STRONG>
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>
2292 <DT><STRONG>Character set</STRONG>
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2303
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2304 <H3>
2305 <A NAME="10.2">
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>
2318 <DT><STRONG>Environment variables</STRONG>
2319 </DT>
2320 <DD>
2321 <P>
2322 These are accessed by the C library routine <SAMP>getenv</SAMP>.
2323 </P>
2324 </DD>
2325 <DT><STRONG>The command line</STRONG>
2326 </DT>
2327 <DD>
2328 <P>
2329 This is accessed using the
2330 <SAMP>argc</SAMP> and <SAMP>argv</SAMP>
2331 arguments to <SAMP>main()</SAMP>. The words have any characters
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>
2340 <DT><STRONG>The current working directory</STRONG>
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>
2349 <DT><STRONG>Character set</STRONG>
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2359
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2360 <H2>
2361 <A NAME="11.0">
2362 11. Security Considerations
2363 </A>
2364 </H2>
2365
2366 <H3>
2367 <A NAME="11.1">
2368 11.1. Safe Methods
2369 </A>
2370 </H3>
2371 <P>
2372 As discussed in the security considerations of the HTTP
2373 specifications [<A HREF="#[3]">3</A>,<A HREF="#[8]">8</A>], the
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2374 convention has been established that the
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]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
2380 [<A HREF="#[3]">3</A>,<A HREF="#[8]">8</A>]
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2389
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2390 <H3>
2391 <A NAME="11.2">
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
2405 NOT be passed on to the script <EM>via</EM> the HTTP_AUTHORIZATION
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2413
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2414 <H3>
2415 <A NAME="11.3">
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>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2432
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2433 <H3>
2434 <A NAME="11.4">
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
2450 status codes include '503 Service Unavailable' (HTTP/1.0 and HTTP/1.1),
2451 '413 Request Entity Too Large' (HTTP/1.1), and
2452 '414 Request-URI Too Long' (HTTP/1.1).
2453 </P>
2454
2455 <H3>
2456 <A NAME="11.5">
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
2482 not meant to be controlled by the client (<EM>e.g.</EM>, hidden
2483 HTML form elements, cookies, embedded URLs, <EM>etc.</EM>).
2484 </P>
2485
2486 <H2>
2487 <A NAME="12.0">
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
2494 discussions on the <EM>www-talk</EM> mailing list. In particular,
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,
2504 Patrick M<SUP>c</SUP>Manus, Adam Donahue,
2505 Ross Patterson, and Harald Alvestrand.
2506 </P>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2507
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2508 <H2>
2509 <A NAME="13.0">
2510 13. References
2511 </A>
2512 </H2>
2513 <DL COMPACT>
2514 <DT><A NAME="[1]">[1]</A>
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>
2523 <DT><A NAME="[2]">[2]</A>
2524 </DT>
2525 <DD>Berners-Lee, T. and Connolly, D., 'Hypertext Markup Language -
2526 2.0', RFC 1866, MIT/W3C, November 1995.
2527 <P>
2528 </P>
2529 </DD>
2530 <DT><A NAME="[3]">[3]</A>
2531 </DT>
2532 <DD>Berners-Lee, T., Fielding, R. T. and Frystyk, H.,
2533 'Hypertext Transfer Protocol -- HTTP/1.0', RFC 1945, MIT/LCS,
2534 UC Irvine, May 1996.
2535 <P>
2536 </P>
2537 </DD>
2538
2539 <DT><A NAME="[4]">[4]</A>
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>
2547
2548 <DT><A NAME="[5]">[5]</A>
2549 </DT>
2550 <DD>Braden, R., Editor, 'Requirements for Internet Hosts --
2551 Application and Support', STD 3, RFC 1123, IETF, October 1989.
2552 <P>
2553 </P>
2554 </DD>
2555 <DT><A NAME="[6]">[6]</A>
2556 </DT>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2557 <DD>Crocker, D.H., 'Standard for the Format of ARPA Internet Text
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2558 Messages', STD 11, RFC 822, University of Delaware, August 1982.
2559 <P>
2560 </P>
2561 </DD>
2562 <DT><A NAME="[7]">[7]</A>
2563 </DT>
2564 <DD>Fielding, R., 'Relative Uniform Resource Locators', RFC 1808,
2565 UC Irvine, June 1995.
2566 <P>
2567 </P>
2568 </DD>
2569 <DT><A NAME="[8]">[8]</A>
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>
2578 <DT><A NAME="[9]">[9]</A>
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>
2586 <DT><A NAME="[10]">[10]</A>
2587 </DT>
2588 <DD>Mockapetris, P., 'Domain Names - Concepts and Facilities',
2589 STD 13, RFC 1034, ISI, November 1987.
2590 <P>
2591 </P>
2592 </DD>
2593 <DT><A NAME="[11]">[11]</A>
2594 </DT>
2595 <DD>St. Johns, M., 'Identification Protocol', RFC 1431, US
2596 Department of Defense, February 1993.
2597 <P>
2598 </P>
2599 </DD>
2600 <DT><A NAME="[12]">[12]</A>
2601 </DT>
2602 <DD>'Coded Character Set -- 7-bit American Standard Code for
2603 Information Interchange', ANSI X3.4-1986.
2604 <P>
2605 </P>
2606 </DD>
2607 <DT><A NAME="[13]">[13]</A>
2608 </DT>
2609 <DD>Hinden, R. and Deering, S.,
2610 'IP Version 6 Addressing Architecture', RFC 2373,
2611 Nokia, Cisco Systems,
2612 July 1998.
2613 <P>
2614 </P>
2615 </DD>
2616 </DL>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2617
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2618 <H2>
2619 <A NAME="14.0">
2620 14. Authors' Addresses
2621 </A>
2622 </H2>
2623 <ADDRESS>
2624 <P>
2625 Ken A L Coar
2626 <BR>
2627 MeepZor Consulting
2628 <BR>
2629 7824 Mayfaire Crest Lane, Suite 202
2630 <BR>
2631 Raleigh, NC 27615-4875
2632 <BR>
2633 U.S.A.
2634 </P>
2635 <P>
2636 Tel: +1 (919) 254.4237
2637 <BR>
2638 Fax: +1 (919) 254.5250
2639 <BR>
2640 Email:
2641 <A
2642 HREF="mailto:Ken.Coar@Golux.Com"
2643 ><SAMP>Ken.Coar@Golux.Com</SAMP></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>
2663 Tel: +44 (1223) 566926
2664 <BR>
2665 Fax: +44 (1223) 506288
2666 <BR>
2667 Email:
2668 <A
2669 HREF="mailto:drtr@etrade.co.uk"
2670 ><SAMP>drtr@etrade.co.uk</SAMP></A>
2671 </ADDRESS>
Denis Vlasenkoc86e0522007-03-20 11:30:28 +0000[diff] [blame]2672
Denis Vlasenko136f42f2007-02-11 14:52:07 +0000[diff] [blame]2673 </BODY>
2674</HTML>