| Denis Vlasenko | 136f42f | 2007-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="<draft-coar-cgi-v11-03.txt>"> |
| 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 | |
| 39 | Coar, et al. CGI/1.1 Specification May, 1998 |
| 40 | INTERNET-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 |
| 56 | </TD> |
| 57 | <TD ALIGN="RIGHT"> |
| 58 | Ken A L Coar |
| 59 | </TD> |
| 60 | </TR> |
| 61 | <TR VALIGN="TOP"> |
| 62 | <TD ALIGN="LEFT"> |
| 63 | draft-coar-cgi-v11-03.{html,txt} |
| 64 | </TD> |
| 65 | <TD ALIGN="RIGHT"> |
| 66 | IBM Corporation |
| 67 | </TD> |
| 68 | </TR> |
| 69 | <TR VALIGN="TOP"> |
| 70 | <TD ALIGN="LEFT"> |
| 71 | |
| 72 | </TD> |
| 73 | <TD ALIGN="RIGHT"> |
| 74 | D.R.T. Robinson |
| 75 | </TD> |
| 76 | </TR> |
| 77 | <TR VALIGN="TOP"> |
| 78 | <TD ALIGN="LEFT"> |
| 79 | |
| 80 | </TD> |
| 81 | <TD ALIGN="RIGHT"> |
| 82 | E*TRADE UK Ltd. |
| 83 | </TD> |
| 84 | </TR> |
| 85 | <TR VALIGN="TOP"> |
| 86 | <TD ALIGN="LEFT"> |
| 87 | |
| 88 | </TD> |
| 89 | <TD ALIGN="RIGHT"> |
| 90 | 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 |
| 126 | project Web page at |
| 127 | <SAMP><URL:<A HREF="http://CGI-Spec.Golux.Com/" |
| 128 | >http://CGI-Spec.Golux.Com/</A>></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 |
| 413 | and the CGI script are responsible |
| 414 | for servicing a client |
| 415 | request by sending back responses. The client |
| 416 | request comprises a Universal Resource Identifier (URI) |
| 417 | [<A HREF="#[1]">1</A>], a |
| 418 | request method, and various ancillary |
| 419 | information about the request |
| 420 | provided by the transport mechanism. |
| 421 | </P> |
| 422 | <P> |
| 423 | The CGI defines the abstract parameters, known as |
| 424 | metavariables, |
| 425 | which describe the client's |
| 426 | request. Together with a |
| 427 | concrete programmer interface this specifies a platform-independent |
| 428 | interface between the script and the HTTP server. |
| 429 | </P> |
| 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 |
| 438 | [<A HREF="#[5]">5</A>] to define the |
| 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> |
| 481 | |
| 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> |
| 517 | |
| 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 |
| 526 | used here in a |
| 527 | sense which may not accord with their definitions in that document, |
| 528 | or with their common meaning. |
| 529 | </P> |
| 530 | |
| 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> |
| 541 | |
| 542 | <DT><EM>script</EM> |
| 543 | </DT> |
| 544 | <DD> |
| 545 | <P> |
| 546 | The software which is invoked by the server <EM>via</EM> this |
| 547 | interface. It |
| 548 | need not be a standalone program, but could be a |
| 549 | dynamically-loaded or shared library, or even a subroutine in the |
| 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> |
| 565 | |
| 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 ("<" and ">"). |
| 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> |
| 635 | |
| 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 = <any 8-bit sequence of data> |
| 663 | CHAR = <any US-ASCII character (octets 0 - 127)> |
| 664 | CTL = <any US-ASCII control character |
| 665 | (octets 0 - 31) and DEL (127)> |
| 666 | CR = <US-ASCII CR, carriage return (13)> |
| 667 | LF = <US-ASCII LF, linefeed (10)> |
| 668 | SP = <US-ASCII SP, space (32)> |
| 669 | HT = <US-ASCII HT, horizontal tab (9)> |
| 670 | NL = CR | LF |
| 671 | LWSP = SP | HT | NL |
| 672 | tspecial = "(" | ")" | "@" | "," | ";" | ":" | "\" | <"> |
| 673 | | "/" | "[" | "]" | "?" | "<" | ">" | "{" | "}" |
| 674 | | SP | HT | NL |
| 675 | token = 1*<any CHAR except CTLs or tspecials> |
| 676 | quoted-string = ( <"> *qdtext <"> ) | ( "<" *qatext ">") |
| 677 | qdtext = <any CHAR except <"> and CTLs but including LWSP> |
| 678 | qatext = <any CHAR except "<", ">" and CTLs but |
| 679 | including LWSP> |
| 680 | mark = "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")" |
| 681 | unreserved = alphanum | mark |
| 682 | reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | |
| 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> |
| 690 | |
| 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> |
| 733 | |
| 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, |
| 742 | this URI will be the same as |
| 743 | the URI requested by the client (the 'Client-URI'); however, it need |
| 744 | not be. Instead, it could be a URI invented by the server, and so it |
| 745 | can only be used in the context of the server and its CGI interface. |
| 746 | </P> |
| 747 | <P> |
| 748 | The Script-URI has the syntax of generic-RL as defined in section 2.1 |
| 749 | of RFC 1808 [<A HREF="#[7]">7</A>], with the exception that object |
| 750 | parameters and |
| 751 | fragment identifiers are not permitted: |
| 752 | </P><!--#if expr="! $GUI" --> |
| 753 | <P></P><!--#endif --> |
| 754 | <PRE> |
| 755 | <scheme>://<host><port>/<path>?<query> |
| 756 | </PRE> |
| 757 | <P> |
| 758 | The various components of the |
| 759 | Script-URI |
| 760 | are defined by some of the |
| 761 | metavariables (see |
| 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> |
| 786 | |
| 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> |
| 798 | |
| 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 |
| 810 | request, |
| 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 |
| 865 | to pass data about the request from |
| 866 | the server to the script. |
| 867 | The metavariables containing these |
| 868 | data |
| 869 | are accessed by the script in a system |
| 870 | defined manner. |
| 871 | The |
| 872 | representation of the characters in the |
| 873 | metavariables is |
| 874 | system defined. |
| 875 | </P> |
| 876 | <P> |
| 877 | This specification does not distinguish between the representation of |
| 878 | null values and missing ones. Whether null or missing values |
| 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> |
| 938 | This variable is specific to requests made |
| 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 |
| 946 | access, then the server |
| 947 | MUST set |
| 948 | the value of |
| 949 | this variable |
| 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 |
| 965 | not case-sensitive. |
| 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 |
| 1021 | of a supplied "<SAMP>Content-type</SAMP>" field. The syntax is the |
| 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 |
| 1056 | <SAMP>application/octet-stream</SAMP> |
| 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 |
| 1094 | integers and hence each may be |
| 1095 | more than a single |
| 1096 | digit. Thus CGI/2.4 is a lower version than CGI/2.13 which in turn |
| 1097 | is lower than CGI/12.3. Leading zeros in either |
| 1098 | the major or the minor number MUST be ignored by scripts and |
| 1099 | SHOULD NOT be generated by servers. |
| 1100 | </P> |
| 1101 | <P> |
| 1102 | This document defines the 1.1 version of the CGI interface |
| 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 |
| 1117 | the protocol |
| 1118 | <EM>via</EM> which the request is made. |
| 1119 | Interpretation of these variables depends on the value of |
| 1120 | the |
| 1121 | SERVER_PROTOCOL |
| 1122 | metavariable |
| 1123 | (see |
| 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, |
| 1161 | they MAY |
| 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 |
| 1191 | that a PATH_INFO of "/" |
| 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 = <any CHAR except "/"> |
| 1200 | </PRE> |
| 1201 | <P> |
| 1202 | The PATH_INFO string is the trailing part of the <path> component of |
| 1203 | the Script-URI |
| 1204 | (see <A HREF="#3.2">section 3.2</A>) |
| 1205 | that follows the SCRIPT_NAME |
| 1206 | portion of the path. |
| 1207 | </P> |
| 1208 | <P> |
| 1209 | Servers MAY impose their own restrictions and |
| 1210 | limitations on what values they will accept for PATH_INFO, and MAY |
| 1211 | reject or edit any values they |
| 1212 | consider objectionable before passing |
| 1213 | them to the script. |
| 1214 | </P> |
| 1215 | <P> |
| 1216 | Servers MUST make this URI component available |
| 1217 | to CGI scripts. The PATH_INFO |
| 1218 | value is case-sensitive, and the |
| 1219 | server MUST preserve the case of the PATH_INFO element of the URI |
| 1220 | when making it available to scripts. |
| 1221 | </P> |
| 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> |
| 1288 | The |
| 1289 | translation |
| 1290 | algorithm the server uses to derive PATH_TRANSLATED is |
| 1291 | implementation defined; CGI scripts which use this variable may |
| 1292 | suffer limited portability. |
| 1293 | </P> |
| 1294 | <P> |
| 1295 | Servers SHOULD provide this metavariable |
| 1296 | to scripts if and only if the request URI includes a |
| 1297 | path-info component. |
| 1298 | </P> |
| 1299 | |
| 1300 | <H4> |
| 1301 | <A NAME="6.1.8"> |
| 1302 | 6.1.8. QUERY_STRING |
| 1303 | </A> |
| 1304 | </H4> |
| 1305 | <P> |
| 1306 | A URL-encoded |
| 1307 | string; the <query> part of the |
| 1308 | Script-URI. |
| 1309 | (See |
| 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> |
| 1374 | |
| 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> |
| 1401 | |
| 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> |
| 1429 | |
| 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 |
| 1441 | section 5.1.1 of the |
| 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> |
| 1452 | The method is case sensitive. |
| 1453 | CGI/1.1 servers MAY choose to process some methods |
| 1454 | directly rather than passing them to scripts. |
| 1455 | </P> |
| 1456 | <P> |
| 1457 | This variable is specific to requests made with HTTP. |
| 1458 | </P> |
| 1459 | <P> |
| 1460 | Servers MUST provide this metavariable |
| 1461 | to scripts. |
| 1462 | </P> |
| 1463 | |
| 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 <path> 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> |
| 1497 | |
| 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 |
| 1508 | server, as |
| 1509 | derived from the <host> 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 <port> |
| 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 <port> portion of the script-URI is blank, the actual |
| 1541 | port number upon which the request was received MUST be supplied. |
| 1542 | </P> |
| 1543 | <P> |
| 1544 | Servers MUST provide this metavariable |
| 1545 | to scripts. |
| 1546 | </P> |
| 1547 | |
| 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 <scheme> 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> |
| 1592 | |
| 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> |
| 1644 | below), |
| 1645 | servers SHOULD |
| 1646 | attempt to ensure that the data |
| 1647 | supplied to the script are precisely |
| 1648 | as supplied by the client and unaltered by |
| 1649 | the server. |
| 1650 | </P> |
| 1651 | <P> |
| 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> |
| 1708 | |
| 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> |
| 1793 | |
| 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>, |
| 1822 | omitting the scheme and network-related fields) and optional |
| 1823 | query-string. If an absolute URI is returned by the script, |
| 1824 | then the |
| 1825 | server MUST generate a |
| 1826 | '302 redirect' HTTP response |
| 1827 | message unless the script has supplied an |
| 1828 | explicit Status response header field. |
| 1829 | Scripts returning an absolute URI MAY choose to |
| 1830 | provide a message-body. Servers MUST make any appropriate modifications |
| 1831 | to the script's output to ensure the response to the user-agent complies |
| 1832 | with the response protocol version. |
| 1833 | If the Location value is a path, then the server |
| 1834 | MUST generate |
| 1835 | the response that it would have produced in response to a request |
| 1836 | containing the URL |
| 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 = *<CHAR, excluding CTLs, NL> |
| 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 |
| 1870 | specification [<A HREF="#[8]">8</A>] may |
| 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: 404 Not Found" in the |
| 1880 | header data returned to the server. |
| 1881 | </P> |
| 1882 | |
| 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 |
| 1944 | allows |
| 1945 | script authors to determine |
| 1946 | what URL to use in documents |
| 1947 | which reference the script; |
| 1948 | specifically, what URL to use in order to |
| 1949 | achieve particular settings of the |
| 1950 | metavariables. This |
| 1951 | mechanism is as follows: |
| 1952 | </P> |
| 1953 | <P> |
| 1954 | The server |
| 1955 | MUST translate the header data from the CGI header field syntax to |
| 1956 | the HTTP |
| 1957 | header field syntax if these differ. For example, the character |
| 1958 | sequence for |
| 1959 | newline (such as Unix's ASCII NL) used by CGI scripts may not be the |
| 1960 | same as that used by HTTP (ASCII CR followed by LF). The server MUST |
| 1961 | also resolve any conflicts between header fields returned by the script |
| 1962 | and header fields that it would otherwise send itself. |
| 1963 | </P> |
| 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 |
| 2055 | ordinary path |
| 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"> |
| 2146 | 9. |
| 2147 | Script Implementation |
| 2148 | </A> |
| 2149 | </H2> |
| 2150 | <P> |
| 2151 | This section defines the requirements and recommendations for scripts |
| 2152 | that are intended to function in a CGI/1.1 environment. It is intended |
| 2153 | primarily as a reference for script authors, but server implementors |
| 2154 | should be familiar with these issues as well. |
| 2155 | </P> |
| 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> |
| 2222 | If a script is processing the output of a form, it SHOULD |
| 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 |
| 2234 | use in OS |
| 2235 | system calls, or the request SHOULD be rejected with |
| 2236 | '404 Not Found'. |
| 2237 | </P> |
| 2238 | <P> |
| 2239 | As it is impossible for |
| 2240 | scripts to determine the client URI that |
| 2241 | initiated a |
| 2242 | request without knowledge of the specific server in |
| 2243 | use, the script SHOULD NOT return "<SAMP>text/html</SAMP>" |
| 2244 | documents containing |
| 2245 | relative URL links without including a "<SAMP><BASE></SAMP>" |
| 2246 | tag in the document. |
| 2247 | </P> |
| 2248 | <P> |
| 2249 | When returning header fields, |
| 2250 | scripts SHOULD try to send the CGI |
| 2251 | header fields (see section |
| 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> |
| 2257 | |
| 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> |
| 2303 | |
| 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> |
| 2359 | |
| 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 |
| 2374 | convention has been established that the |
| 2375 | GET and HEAD methods should be 'safe'; they should cause no |
| 2376 | side-effects and only have the significance of resource retrieval. |
| 2377 | </P> |
| 2378 | <P> |
| 2379 | CGI scripts are responsible for enforcing any HTTP security considerations |
| 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> |
| 2389 | |
| 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> |
| 2413 | |
| 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> |
| 2432 | |
| 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> |
| 2507 | |
| 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> |
| 2557 | <DD>Crocker, D.H., 'Standard for the Format of ARPA Internet Text |
| 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> |
| 2617 | |
| 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> |
| 2672 | |
| 2673 | </BODY> |
| 2674 | </HTML> |