summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc3050.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc3050.txt')
-rw-r--r--doc/rfc/rfc3050.txt1963
1 files changed, 1963 insertions, 0 deletions
diff --git a/doc/rfc/rfc3050.txt b/doc/rfc/rfc3050.txt
new file mode 100644
index 0000000..eca6a2f
--- /dev/null
+++ b/doc/rfc/rfc3050.txt
@@ -0,0 +1,1963 @@
+
+
+
+
+
+
+Network Working Group J. Lennox
+Request for Comments: 3050 H. Schulzrinne
+Category: Informational Columbia U.
+ J. Rosenberg
+ dynamicsoft
+ January 2001
+
+
+ Common Gateway Interface for SIP
+
+Status of this Memo
+
+ This memo provides information for the Internet community. It does
+ not specify an Internet standard of any kind. Distribution of this
+ memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2001). All Rights Reserved.
+
+Abstract
+
+ In Internet telephony, there must be a means by which new services
+ are created and deployed rapidly. In the World Wide Web, the Common
+ Gateway Interface (CGI) has served as popular means towards
+ programming web services. Due to the similarities between the
+ Session Initiation Protocol (SIP) and the Hyper Text Transfer
+ Protocol (HTTP), CGI is a good candidate for service creation in a
+ SIP environment. This document defines a SIP CGI interface for
+ providing SIP services on a SIP server.
+
+IESG Note
+
+ The IESG notes that the mechanism specified here depends on the
+ Common Gateway Interface. Should this interface change or be
+ enhanced changes in this specification may also be necessary or
+ appropriate. According to the W3C, the CGI is presently maintained
+ by the NCSA Software Development Group. See
+
+ http://www.w3c.org/cgi
+
+ for additional information on the current state of the CGI interface.
+
+
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 1]
+
+RFC 3050 CGI for SIP January 2001
+
+
+Table of Contents
+
+ 1 Introduction ....................................... 3
+ 2 Motivations ........................................ 4
+ 3 Differences from HTTP CGI .......................... 5
+ 3.1 Basic Model ........................................ 6
+ 3.2 Persistence Model .................................. 8
+ 3.3 SIP CGI Triggers ................................... 9
+ 3.4 Naming ............................................. 9
+ 3.5 Environment Variables .............................. 9
+ 3.6 Timers ............................................. 10
+ 4 Overview of SIP CGI ................................ 10
+ 5 SIP CGI Specification .............................. 12
+ 5.1 Introduction ....................................... 12
+ 5.1.1 Relationship with HTTP CGI ......................... 12
+ 5.1.2 Conventions of This Document ....................... 12
+ 5.1.3 Specifications ..................................... 12
+ 5.1.4 Terminology ........................................ 13
+ 5.2 Notational Conventions and Generic Grammar ......... 13
+ 5.3 Invoking the Script ................................ 14
+ 5.4 The SIP CGI Script Command Line .................... 14
+ 5.5 Data Input to the SIP CGI Script ................... 14
+ 5.5.1 Message Metadata (Metavariables) ................... 14
+ 5.5.1.1 AUTH_TYPE .......................................... 16
+ 5.5.1.2 CONTENT_LENGTH ..................................... 16
+ 5.5.1.3 CONTENT_TYPE ....................................... 17
+ 5.5.1.4 GATEWAY_INTERFACE .................................. 17
+ 5.5.1.5 Protocol-Specific Metavariables .................... 18
+ 5.5.1.6 REGISTRATIONS ...................................... 18
+ 5.5.1.7 REMOTE_ADDR ........................................ 19
+ 5.5.1.8 REMOTE_HOST ........................................ 19
+ 5.5.1.9 REMOTE_IDENT ....................................... 19
+ 5.5.1.10 REMOTE_USER ........................................ 20
+ 5.5.1.11 REQUEST_METHOD ..................................... 20
+ 5.5.1.12 REQUEST_TOKEN ...................................... 21
+ 5.5.1.13 REQUEST_URI ........................................ 21
+ 5.5.1.14 RESPONSE_STATUS .................................... 21
+ 5.5.1.15 RESPONSE_REASON .................................... 21
+ 5.5.1.16 RESPONSE_TOKEN ..................................... 21
+ 5.5.1.17 SCRIPT_COOKIE ...................................... 22
+ 5.5.1.18 SERVER_NAME ........................................ 22
+ 5.5.1.19 SERVER_PORT ........................................ 22
+ 5.5.1.20 SERVER_PROTOCOL .................................... 22
+ 5.5.1.21 SERVER_SOFTWARE .................................... 23
+ 5.5.2 Message Bodies ..................................... 23
+ 5.6 Data Output from the SIP CGI Script ................ 23
+ 5.6.1 CGI Action Lines ................................... 25
+ 5.6.1.1 Status ............................................. 25
+
+
+
+Lennox, et al. Informational [Page 2]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ 5.6.1.2 Proxy Request ...................................... 25
+ 5.6.1.3 Forward Response ................................... 26
+ 5.6.1.4 Script Cookie ...................................... 26
+ 5.6.1.5 CGI Again .......................................... 27
+ 5.6.1.6 Default Action ..................................... 27
+ 5.6.2 CGI Header Fields .................................. 28
+ 5.6.2.1 Request-Token ...................................... 28
+ 5.6.2.2 Remove ............................................. 28
+ 5.7 Local Expiration Handling .......................... 28
+ 5.8 Locally-Generated Responses ........................ 29
+ 5.9 SIP CGI and REGISTER ............................... 29
+ 5.10 SIP CGI and CANCEL ................................. 29
+ 5.11 SIP CGI and ACK .................................... 30
+ 5.11.1 Receiving ACK's .................................... 30
+ 5.11.2 Sending ACK's ...................................... 30
+ 6 System Specifications .............................. 30
+ 6.1 Unix ............................................... 30
+ 6.2 Microsoft Windows .................................. 31
+ 7 Security Considerations ............................ 31
+ 7.1 Request Initiation ................................. 31
+ 7.2 Authenticated and Encrypted Messages ............... 31
+ 7.3 SIP Header Fields Containing Sensitive Information.. 32
+ 7.4 Script Interference with the Server ................ 32
+ 7.5 Data Length and Buffering Considerations ........... 32
+ 8 Acknowledgements ................................... 33
+ 9 Authors' Addresses ................................. 33
+ 10 Bibliography ....................................... 34
+ 11 Full Copyright Statement ........................... 35
+
+1 Introduction
+
+ In Internet telephony, there must be a means by which new services
+ are created and deployed rapidly. In traditional telephony networks,
+ this was accomplished through IN service creation environments, which
+ provided an interface for creating new services, often using GUI-
+ based tools.
+
+ The WWW has evolved with its own set of tools for service creation.
+ Originally, web servers simply translated URLs into filenames stored
+ on a local system, and returned the file content. Over time, servers
+ evolved to provide dynamic content, and forms provided a means for
+ soliciting user input. In essence, what evolved was a means for
+ service creation in a web environment. There are now many means for
+ creation of dynamic web content, including server side JavaScript,
+ servlets, and the common gateway interface (CGI) [1].
+
+
+
+
+
+
+Lennox, et al. Informational [Page 3]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ Multimedia communications, including Internet telephony, will also
+ require a mechanism for creating services. This mechanism is
+ strongly tied to the features provided by the signaling protocols.
+ The Session Initiation Protocol (SIP) [2] has been developed for
+ initiation and termination of multimedia sessions. SIP borrows
+ heavily from HTTP, inheriting its client-server interaction and much
+ of its syntax and semantics. For this reason, the web service
+ creation environments, and CGI in particular, seem attractive as
+ starting points for developing SIP based service creation
+ environments.
+
+2 Motivations
+
+ CGI has a number of strengths which make it attractive as an
+ environment for creating SIP services:
+
+ Language independence: CGI works with perl, C, VisualBasic, tcl,
+ and many other languages, as long as they support access to
+ environment variables.
+
+ Exposes all headers: CGI exposes the content of all the headers
+ in an HTTP request to the CGI application. An application
+ can make use of these as it sees fit, and ignore those it
+ doesn't care about. This allows all aspects of an HTTP
+ request to be considered for creation of content. In a SIP
+ environment, headers have greater importance than in HTTP.
+ They carry critical information about the transaction,
+ including caller and callee, subject, contact addresses,
+ organizations, extension names, registration parameters and
+ expirations, call status, and call routes, to name a few.
+ It is therefore critical for SIP services to have as much
+ access to these headers as possible. For this reason, CGI
+ is very attractive.
+
+ Creation of responses: CGI is advantageous in that it can create
+ all parts of a response, including headers, status codes
+ and reason phrases, in addition to message bodies. This is
+ not the case for other mechanisms, such as Java servlets,
+ which are focused primarily on the body. In a SIP
+ environment, it is critical to be able to generate all
+ aspects of a response (and, all aspects of new or proxied
+ requests), since the body is usually not of central
+ importance in SIP service creation.
+
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 4]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ Component reuse: Many of the CGI utilities allow for easy
+ reading of environment variables, parsing of form data, and
+ often parsing and generation of header fields. Since SIP
+ reuses the basic RFC822 [3] syntax of HTTP, many of these
+ tools are applicable to SIP CGI.
+
+ Familiar environment: Many web programmers are familiar with
+ CGI.
+
+ Ease of extensibility: Since CGI is an interface and not a
+ language, it becomes easy to extend and reapply to other
+ protocols, such as SIP.
+
+ The generality, extensibility, and detailed control and access to
+ information provided by CGI, coupled with the range of tools that
+ exist for it, which can be immediately applied to SIP, make it a good
+ mechanism for SIP service creation.
+
+3 Differences from HTTP CGI
+
+ While SIP and HTTP share a basic syntax and a request-response model,
+ there are important differences. Proxies play a critical role in
+ services for SIP, while they are less important for HTTP. SIP
+ servers can fork requests (proxying multiple requests when a single
+ request is received), an important capability absent from HTTP. SIP
+ supports additional features, such as registrations, which are absent
+ from HTTP. These differences are reflected in the differences
+ between SIP CGI and HTTP CGI. SIP CGI runs primarily on proxy,
+ redirect, and registrar servers, rather than user agent servers
+ (which are the equivalent of origin servers in HTTP). SIP CGI allows
+ the script to perform specific messaging functions not supported in
+ HTTP CGI (such as proxying requests), and SIP CGI introduces a
+ persistence model that allow a script to maintain control through
+ multiple message exchanges. HTTP CGI has no persistence for scripts.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 5]
+
+RFC 3050 CGI for SIP January 2001
+
+
+3.1 Basic Model
+
+ The basic model for HTTP CGI is depicted in figure 1.
+
+ ----- ------------
+ ~~~~~~~~ |req | | -------- |
+ | |----------| | http | |
+ | client | |resp | | | server | |
+ | |----------| | | |w
+ ~~~~~~~~ | | | -------- |e
+ ----- | s| /\s |b
+ net | t| |t |
+ |e d| C |d |s
+ |n i| G |o |e
+ |v n| I |u |r
+ | | |t |v
+ | \/ | |e
+ | ------- |r
+ | | | |
+ | | CGI | |
+ | | prog. | |
+ | | | |
+ | ------- |
+ ------------
+
+ Figure 1: HTTP CGI Model
+
+ A client issues an HTTP request, which is passed either directly to
+ the origin server (as shown), or is forwarded through a proxy server.
+ The origin server executes a CGI script, and the CGI script returns a
+ response, which is passed back to the client. The main job of the
+ script is to generate the body for the response. Only origin servers
+ execute CGI scripts, not proxy servers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 6]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ In a SIP server, the model is different, and is depicted in Figure 2.
+
+
+ ~~~~~~~~ req ------- req ------- req ~~~~~~~~
+ | |------| |-------| |---------| |
+ | client | resp | server| resp | server| resp | client |
+ | |------| |-------| |---------| |
+ ~~~~~~~~ ------- ------- --------
+ | | CGI
+ | |
+ -------
+ | |
+ | CGI |
+ | prog. |
+ | |
+ -------
+
+ Figure 2: SIP CGI Model
+
+ The client generates a request, which is forwarded to a server. The
+ server may generate a response (such as an error or redirect
+ response). Or, if the server is a proxy server, the request is
+ proxied to another server, and eventually to a user agent, and the
+ response is passed back upstream, through the server, and back
+ towards the client. A SIP proxy server may additionally fork
+ requests, generating multiple requests in response to a received
+ request. Generally, a proxy server will not generate the content in
+ responses. These contain session descriptions created by user
+ agents. Services, such as call forward and mobility services, are
+ based on the decisions the server makes about (1) when, to where, and
+ how many requests to proxy downstream, and (2) when to send a
+ response back upstream. Creation of services such as ad-hoc bridging
+ (where the server acts as a media mixer in a multiparty call, without
+ being asked to do so by the end users) will require the server to
+ generate new requests of its own, and for it to modify and generate
+ the body in responses.
+
+ An HTTP server is mainly concerned about generation of responses. A
+ SIP server is generally concerned about performing four basic
+ operations:
+
+ Proxying of Requests: Receiving a request, adding or modifying
+ any of the headers, deciding on a set of servers to forward
+ the request to, and forwarding it to them.
+
+ Returning Responses: Receiving a response, adding or modifying
+ any of the headers, and passing the response towards the
+ client.
+
+
+
+Lennox, et al. Informational [Page 7]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ Generating Requests: Creating a new request, originating at the
+ server, placing headers and a body into the message, and
+ sending it to a server.
+
+ Generation of Responses: Receiving a request, generating a
+ response to it, and sending it back to the client.
+
+ When a request is received, one or more of the above operations may
+ occur at once. For example, a SIP server may generate a provisional
+ response, generate a new request, and proxy the original request to
+ two servers. This implies that SIP CGI must encompass a greater set
+ of functions than HTTP CGI. These functions are a super-set of the
+ simple end-server request/response model.
+
+3.2 Persistence Model
+
+ In HTTP CGI, a script is executed once for each request. It
+ generates the response, and then terminates. There is no state
+ maintained across requests from the same user, as a general rule
+ (although this can be done -- and is -- for more complex services
+ such as database accesses, which essentially encapsulate state in
+ client-side cookies or dynamically-generated URLs). A transaction is
+ just a single request, and a response.
+
+ In SIP CGI, since a request can generate many new and proxied
+ requests, these themselves will generate responses. A service will
+ often require these responses to be processed, and additional
+ requests or responses to be generated. As a result, whereas an HTTP
+ CGI script executes once per transaction, a SIP CGI script must
+ maintain control somehow over numerous events.
+
+ In order to enable this, and to stay with the original CGI model, we
+ mandate that a SIP CGI script executes when a message arrives, and
+ after generating output (in the form of additional messages),
+ terminate. State is maintained by allowing the CGI to return an
+ opaque token to the server. When the CGI script is called again for
+ the same transaction, this token is passed back to the CGI script.
+ When called for a new transaction, no token is passed.
+
+ For example, consider a request which arrives at a SIP server. The
+ server calls a CGI script, which generates a provisional response and
+ a proxied request. It also returns a token to the server, and then
+ terminates. The response is returned upstream towards the client,
+ and the request is proxied. When the response to the proxied request
+ arrives, the script is executed again. The environment variables are
+ set based on the content of the new response. The script is also
+ passed back the token. Using the token as its state, the script
+ decides to proxy the request to a different location. It therefore
+
+
+
+Lennox, et al. Informational [Page 8]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ returns a proxied request, and another token. The server forwards
+ this new request, and when the response comes, calls the CGI script
+ once more, and passes back the token. This time, the script
+ generates a final response, and passes this back to the server. The
+ server sends the response to the client, destroys the token, and the
+ transaction is complete.
+
+3.3 SIP CGI Triggers
+
+ In many cases, calling the CGI script on the reception of every
+ message is inefficient. CGI scripts come at the cost of significant
+ overhead since they generally require creation of a new process.
+ Therefore, it is important in SIP CGI for a script to indicate, after
+ it is called the first time, under what conditions it will be called
+ for the remainder of the transaction. If the script is not called,
+ the server will take the "default" action, as specified in this
+ document. This allows an application designer to trade off
+ flexibility for computational resources. Making an analogy to the
+ Intelligent Network (IN) - a script is able to define the triggers
+ for its future execution.
+
+ So, in summary, whereas an HTTP CGI script executes once during a
+ transaction, a single SIP CGI script may execute many times during a
+ transaction, and may specify at which points it would like to have
+ control for the remainder of the transaction.
+
+3.4 Naming
+
+ In HTTP CGI, the CGI script itself is generally the resource named in
+ the request URI of the HTTP request. This is not so in SIP. In
+ general, the request URI names a user to be called. The mapping to a
+ script to be executed may depend on other SIP headers, including To
+ and From fields, the SIP method, status codes, and reason phrases.
+ As such, the mapping of a message to a CGI script is purely a matter
+ of local policy administration at a server. A server may have a
+ single script which always executes, or it may have multiple scripts,
+ and the target is selected by some parts of the header.
+
+3.5 Environment Variables
+
+ In HTTP CGI, environment variables are set with the values of the
+ paths and other aspects of the request. As there is no notion of a
+ path in SIP, some of these environment variables do not make sense.
+
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 9]
+
+RFC 3050 CGI for SIP January 2001
+
+
+3.6 Timers
+
+ In SIP, certain services require that the script gets called not only
+ when a message arrives, but when some timer expires. The classic
+ example of this is "call forward no answer." To be implemented with
+ SIP CGI, the first time the script is executed, it must generate a
+ proxied request, and also indicate a time at which to be called again
+ if no response comes. This kind of feature is not present in HTTP
+ CGI, and some rudimentary support for it is needed in SIP CGI.
+
+4 Overview of SIP CGI
+
+ When a request arrives at a SIP server, initiating a new transaction,
+ the server will set a number of environment variables, and call a CGI
+ script. The script is passed the body of the request through stdin.
+
+ The script returns, on stdout, a set of SIP action lines, each of
+ which may be modified by CGI and/or SIP headers. This set is
+ delimited through the use of two carriage returns. The action lines
+ allow the script to specify any of the four operations defined above,
+ in addition to the default operation. Generating a response is done
+ by copying the the status line of the response into an action line of
+ the CGI output. For example, the following will create a 200 OK to
+ the original request:
+
+ SIP/2.0 200 OK
+
+ The operation of proxying a request is supported by the CGI-PROXY-
+ REQUEST CGI action, which takes the URL to proxy to as an argument.
+ For example, to proxy a request to dante@inferno.com:
+
+ CGI-PROXY-REQUEST sip:dante@inferno.com SIP/2.0
+ Contact: sip:server1@company.com
+
+ In this example, the server will take the original request, and
+ modify any header fields normally changed during the proxy operation
+ (such as decrementing Max-Forwards, and adding a Via field). This
+ message is then "merged" with the output of the CGI script - SIP
+ headers specified below the action line in the CGI output will be
+ added to the outbound request. In the above example, the Contact
+ header will be added. Note that the action line looks like the
+ request line of a SIP request message. This is done in order to
+ simplify parsing.
+
+ To delete headers from the outgoing request, the merge process also
+ supports the CGI header CGI-Remove. Like SIP headers, CGI headers
+ are written underneath the action line. They are extracted by the
+ SIP server, and used to provide the server with additional guidance.
+
+
+
+Lennox, et al. Informational [Page 10]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ CGI headers always begin with CGI to differentiate them from SIP
+ headers. In this case, the supported values for the CGI-Remove
+ header are the names of headers in the original message.
+
+ Returning of responses is more complex. A server may receive
+ multiple responses as the result of forking a request. The script
+ should be able to ask the server to return any of the responses it
+ had received previously. To support this, the server will pass an
+ opaque token to the script through environment variables, unique for
+ each response received. To return a response, a CGI script needs to
+ indicate which response is to be returned. For example, to return a
+ response named with the token abcdefghij, the following output is
+ generated:
+
+ CGI-FORWARD-RESPONSE abcdefghij SIP/2.0
+
+ Finally, if the script does not output any of the above actions, the
+ server does what it would normally do upon receiving the message that
+ triggered the script.
+
+ A SIP CGI script is normally only executed when the original request
+ arrives. If the script also wants to be called for subsequent
+ messages in a transaction -- due to responses to proxied requests, or
+ (in certain circumstances) ACK and CANCEL requests, it can perform
+ the CGI-AGAIN action:
+
+ CGI-AGAIN yes SIP/2.0
+
+ This action applies only to the next invocation of the script; it
+ means to invoke the script one more time. Outputting "no" is
+ identical to outputting "yes" on this invocation of the script and
+ outputting nothing the next time the script is called.
+
+ When the script is re-executed, it may need access to some state in
+ order to continue processing. A script can generate one piece of
+ state, called a cookie, for any new request or proxied request. It
+ is passed to the server through the CGI-SET-COOKIE action. The
+ action contains a token, which is the cookie itself. The server does
+ not examine or parse the cookie. It is simply stored. When the
+ script is re-executed, the cookie is passed back to the script
+ through an environment variable.
+
+ CGI-SET-COOKIE khsihppii8asdl SIP/2.0
+
+ Finally, when the script causes the server to proxy a request,
+ responses to these requests will arrive. To ease matching of
+ responses to requests, the script can place a request token in the
+ CGI CGI-Request-Token header. This header is removed by the server
+
+
+
+Lennox, et al. Informational [Page 11]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ when the request is proxied. Any responses received to this request
+ will have the token passed in an environment variable.
+
+5 SIP CGI Specification
+
+5.1 Introduction
+
+5.1.1 Relationship with HTTP CGI
+
+ This SIP CGI specification is based on work-in-progress revision 1.1
+ of the HTTP CGI specification [1]. That document is a product of the
+ CGI-WG mailing list, which is not an official IETF working group.
+ CGI-WG's homepage is located at the URL
+ http://Web.Golux.Com/coar/cgi/, and the most recent versions of the
+ CGI specification are available there. This specification
+ incorporates a great deal of text from the work-in-progress version
+ of that document as of February 23, 2000. A future version of this
+ specification may be changed to cite parts of that document by
+ reference instead.
+
+5.1.2 Conventions of This Document
+
+ In this document, the key words "MUST", "MUST NOT", "REQUIRED",
+ "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
+ and "OPTIONAL" are to be interpreted as described in RFC 2119 [4] and
+ indicate requirement levels for compliant SIP CGI implementations.
+
+ Some paragraphs are indented, like this; they give
+ motivations of design choices, or questions for future
+ discussion in the development of SIP CGI. They are not
+ normative to the specification of the protocol.
+
+5.1.3 Specifications
+
+ Not all of the functions and features of SIP CGI are defined in the
+ main part of this specification. The following phrases are used to
+ describe the features which are not specified:
+
+ System-defined: The feature may differ between systems, but
+ must be the same for different implementations using the
+ same system. A system will usually identify a class of
+ operating systems. Some systems are defined in section 6
+ of this document. New systems may be defined by new
+ specifications without revision of this document.
+
+ Implementation-defined: The behavior of the feature may vary
+ from implementation to implementation, but a particular
+ implementation should be consistent in its behavior.
+
+
+
+Lennox, et al. Informational [Page 12]
+
+RFC 3050 CGI for SIP January 2001
+
+
+5.1.4 Terminology
+
+ This specification uses many terms defined in the SIP/2.0
+ specification [2]; however, the following terms are used here in a
+ sense which may not accord with their definitions in that document,
+ or with their common meaning.
+
+ metavariable: A named parameter that carries information from
+ the server to the script. It is not necessarily a
+ variable in the operating system's environment, although
+ that is the most common implementation.
+
+ script: The software which is invoked by the server via this
+ interface. It need not be a standalone program, but
+ could be a dynamically-loaded or shared library, or even
+ a subroutine in the server. It may be a set of
+ statements interpreted at run-time, as the term `script'
+ is frequently understood, but that is not a requirement
+ and within the context of this specification the term has
+ the broader definition stated.
+
+ server: The application program which invokes the script in
+ order to service messages.
+
+ message: A SIP request or response, typically either the one
+ that triggered the invocation of the CGI script, or one
+ that the CGI script caused to be sent.
+
+5.2 Notational Conventions and Generic Grammar
+
+ In this specification we use the Augmented Backus-Naur Form notation
+ as described in appendix C of the SIP/2.0 specification, RFC 2543
+ [2].
+
+ The following grammatical constructs are taken from other documents;
+ this table lists the appropriate sources.
+
+ OCTET SIP/2.0 [2] Appendix C.1
+ CHAR SIP/2.0 [2] Appendix C.1
+ digit SIP/2.0 [2] Appendix C.1
+ alphanum SIP/2.0 [2] Appendix C.1
+ token SIP/2.0 [2] Appendix C.1
+ hostname SIP/2.0 [2] Section 2
+ SIP-URL SIP/2.0 [2] Section 2
+ SIP-Version SIP/2.0 [2] Section 4.3.1
+ Status-Code SIP/2.0 [2] Section 5.1.1
+ Reason-Phrase SIP/2.0 [2] Section 5.1.1
+ media-type HTTP/1.1 [5] Section 3.7
+
+
+
+Lennox, et al. Informational [Page 13]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ (via SIP/2.0 [2] Section 6.16)
+ field-name SIP/2.0 [2] Section 6.6
+
+ Other grammatical constructs taken from outside sources are noted in
+ the text.
+
+5.3 Invoking the Script
+
+ The script is invoked in a system-defined manner. Unless specified
+ otherwise, the file containing the script will be invoked as an
+ executable program.
+
+ Only one CGI script at a time may be outstanding for a SIP
+ transaction. If subsequently arriving responses would cause a CGI
+ script to be invoked, handling of them is deferred, except for ACK,
+ until CGI scripts for previous messages in the transaction terminate.
+ Messages are processed in the order they are received.
+
+5.4 The SIP CGI Script Command Line
+
+ The server SHOULD NOT provide any command line arguments to the
+ script.
+
+ Command line arguments are used for indexed queries in HTTP
+ CGI; HTTP indexed queries do not have an equivalent in SIP.
+
+5.5 Data Input to the SIP CGI Script
+
+ Information about a message comes from two different sources: the
+ message header, and any associated content-body. Servers MUST make
+ portions of this information available to scripts.
+
+5.5.1 Message Metadata (Metavariables)
+
+ Each SIP CGI server implementation MUST define a mechanism to pass
+ data about the message from the server to the script. The
+ metavariables containing these data are accessed by the script in a
+ system-defined manner. The representation of the characters in the
+ metavariables is system-defined.
+
+ The representation of metavariables MUST distinguish between
+ undefined values (which are not present) and null values (which are
+ present, but have zero length). Null values are only allowed for
+ those metavariables whose grammar permits this.
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 14]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ For historical reasons, HTTP CGI does not distinguish
+ between null values and undefined values. This
+ specification eliminates this misfeature; null values and
+ undefined values are semantically different.
+
+ Case is not significant in the metavariable names, in that there
+ cannot be two different variables whose names differ in case only.
+ Here they are shown using a canonical representation of capitals plus
+ underscore ("_"). The actual representation of the names is system
+ defined; for a particular system the representation MAY be defined
+ differently than this.
+
+ Metavariable values MUST be considered case-sensitive except as noted
+ otherwise.
+
+ The canonical metavariables defined by this specification are:
+
+ AUTH_TYPE
+ CONTENT_LENGTH
+ CONTENT_TYPE
+ GATEWAY_INTERFACE
+ REMOTE_ADDR
+ REMOTE_HOST
+ REMOTE_IDENT
+ REMOTE_USER
+ REGISTRATIONS
+ REQUEST_METHOD
+ REQUEST_TOKEN
+ REQUEST_URI
+ RESPONSE_STATUS
+ RESPONSE_REASON
+ RESPONSE_TOKEN
+ SCRIPT_COOKIE
+ SERVER_NAME
+ SERVER_PORT
+ SERVER_PROTOCOL
+ SERVER_SOFTWARE
+
+ Metavariables with names beginning with the protocol name (e.g.,
+ "SIP_ACCEPT") are also canonical in their description of message
+ header fields. The number and meaning of these fields may change
+ independently of this specification. (See also section 5.5.1.5.)
+
+ A server MAY also specify additional non-canonical metavariables.
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 15]
+
+RFC 3050 CGI for SIP January 2001
+
+
+5.5.1.1 AUTH_TYPE
+
+ If the target of the message required access authentication for
+ external access, then the server MUST set the value of this variable
+ from the auth-scheme token in the message's Authorization header
+ field. Otherwise it is not defined.
+
+ AUTH_TYPE = "" | auth-scheme
+ auth-scheme = "Basic" | "Digest" | "PGP" | token
+
+ SIP access authentication schemes are described in sections 14 and 15
+ of the SIP/2.0 specification [2]. The auth-scheme is not case-
+ sensitive.
+
+ Servers MUST provide this metavariable to scripts if the message
+ header included an Authorization field that was authenticated.
+
+ For the complex authentication schemes, the server SHOULD perform the
+ authentication checking itself. If the authentication failed, this
+ metavariable SHOULD NOT be set.
+
+ If several authentication credentials, with multiple schemes, are
+ present in the message, this variable SHOULD be set to correspond to
+ the authenticated credentials with the strongest scheme the server
+ supports. If credentials are present for several domains, the server
+ SHOULD NOT perform any action on credentials from domains external to
+ it.
+
+ If both Authorization and Proxy-Authorization headers are present,
+ the server SHOULD perform the authorizations based on the appropriate
+ header for the context in which it is running. For example, a server
+ which is a proxy server and a registrar would use Authorization
+ headers for REGISTER messages aimed at its local domains, and Proxy-
+ Authorization headers for all other messages.
+
+5.5.1.2 CONTENT_LENGTH
+
+ This metavariable is set to the size of the message-body entity
+ attached to the message, if any, in decimal number of octets. If no
+ data are attached, then this metavariable is not defined. The syntax
+ is the same as for the SIP Content-Length header field (section 6.15,
+ SIP/2.0 specification [2]).
+
+ CONTENT_LENGTH = "" | 1*digit
+
+ Servers MUST provide this metavariable to scripts if the message was
+ a accompanied by a content-body entity, even if the message did not
+ include a Content-Length header field.
+
+
+
+Lennox, et al. Informational [Page 16]
+
+RFC 3050 CGI for SIP January 2001
+
+
+5.5.1.3 CONTENT_TYPE
+
+ If the message includes a message-body, CONTENT_TYPE is set to the
+ Internet Media Type [6] of the attached entity if the type was
+ provided via a Content-type field in the message header, or if the
+ server can determine it in the absence of a supplied Content-type
+ field. The syntax is the same as for the SIP Content-Type header
+ field.
+
+ CONTENT_TYPE = "" | media-type
+
+ The type, subtype, and parameter attribute names are not case-
+ sensitive. Parameter values MAY be case sensitive. Media types and
+ their use in SIP are described in section 6.16 of the SIP/2.0
+ specification [2], and by reference in section 3.7 of the HTTP/1.1
+ specification [5].
+
+ Since in SIP the Content-Type header MUST be specified if a body is
+ present, servers MUST provide this metavariable to scripts if a body
+ was present in the original message, unless the "body" is actually an
+ encrypted payload.
+
+5.5.1.4 GATEWAY_INTERFACE
+
+ This metavariable is set to the dialect of SIP CGI being used by the
+ server to communicate with the script. Syntax:
+
+ GATEWAY_INTERFACE = "SIP-CGI" "/" major "." minor
+ major = 1*digit
+ minor = 1*digit
+
+ Note that the major and minor numbers are treated as separate
+ integers and hence each may be more than a single digit. Thus SIP-
+ CGI/2.4 is a lower version than SIP-CGI/2.13 which in turn is lower
+ than SIP-CGI/12.3. Leading zeros in either the major or the minor
+ number MUST be ignored by scripts and SHOULD NOT be generated by
+ servers.
+
+ This document defines the 1.1 version of the SIP CGI interface
+ ("SIP-CGI/1.1").
+
+ Servers MUST provide this metavariable to scripts.
+
+ For maximal compatibility with existing HTTP CGI libraries,
+ we want to keep this as similar as possible to the syntax
+ of CGI 1.1. However, we do want it to be clear that this is
+ indeed SIP CGI. Making HTTP CGI's version identifier a
+ substring of the SIP CGI identifier seemed like a
+
+
+
+Lennox, et al. Informational [Page 17]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ reasonable compromise. (The existing CGI libraries we
+ checked do not seem to check the version.)
+
+5.5.1.5 Protocol-Specific Metavariables
+
+ These metavariables are specific to the protocol via which the method
+ is sent. Interpretation of these variables depends on the value of
+ the SERVER_PROTOCOL metavariable (see section 5.5.1.20).
+
+ Metavariables with names beginning with "SIP_" contain values from
+ the message header, if the protocol used was SIP. Each SIP header
+ field name is converted to upper case, has all occurrences of "-"
+ replaced with "_", and has "SIP_" prepended to form the metavariable
+ name. Similar transformations are applied for other protocols. The
+ header data MAY be presented as sent by the client, or MAY be
+ rewritten in ways which do not change its semantics. If multiple
+ header fields with the same field-name are received then the server
+ MUST rewrite them as though they had been received as a single header
+ field having the same semantics before being represented in a
+ metavariable. Similarly, a header field that is received on more
+ than one line MUST be merged into a single line. The server MUST, if
+ necessary, change the representation of the data (for example, the
+ character set) to be appropriate for a CGI metavariable.
+
+ Note: these metavariables' names were changed from HTTP_*
+ to SIP_* since the first draft of this specification. The
+ intention had been to make it easier to use existing CGI
+ libraries unmodified, but this convenience was felt to be
+ outweighed by the confusion this introduced.
+
+ Servers are not required to create metavariables for all the message
+ header fields they receive. However, because of the relatively high
+ importance of headers in SIP for messages' semantic content, the
+ server SHOULD provide all headers which do not contain potentially
+ sensitive authorization information, such as Authorization. Servers
+ SHOULD provide protocol-specific metavariables even for information
+ which is available through other SIP CGI metavariables, such as
+ CONTENT_LENGTH and CONTENT_TYPE.
+
+ This allows a SIP CGI script to determine, if necessary,
+ whether the information in the other metavariables was in
+ the original message, or was synthesized by the server.
+
+5.5.1.6 REGISTRATIONS
+
+ This metavariable contains a list the current locations the server
+ has registered for the user in the Request-URI of the initial request
+ of a transaction. It is syntactically identical to the protocol
+
+
+
+Lennox, et al. Informational [Page 18]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ metavariable SIP_CONTACT, and thus is defined by section 5.5.1.5 of
+ this document and by section 6.13 of the SIP/2.0 specification [2].
+ It contains all the uris, uri parameters, display names, and contact
+ parameters for the addresses registered with the server.
+
+ The syntax of REGISTRATIONS is identical to how SIP_CONTACT
+ would appear in a 302 response from a redirection server.
+ This allows parsing code to be re-used.
+
+ If a user's registrations change in the course of a transaction, the
+ server SHOULD update this metavariable accordingly for subsequent
+ script invocations for the transaction.
+
+5.5.1.7 REMOTE_ADDR
+
+ The IP address of the client that sent the message to the server.
+ This is not necessarily that of the originating user agent client or
+ server.
+
+ REMOTE_ADDR = hostnumber
+ hostnumber = IPv4address | IPv6address
+
+ The definitions of IPv4address and Ipv6address are provided in
+ Appendix B of RFC 2373 [7].
+
+ For locally-generated responses (see section 5.8), this SHOULD be the
+ loopback address (i.e., 127.0.0.1 for IPv4 or ::1 for IPv6).
+
+ Servers MUST supply this value to scripts.
+
+5.5.1.8 REMOTE_HOST
+
+ This is the fully qualified domain name of the host sending the
+ message to this server, if available, otherwise not defined. (See
+ section 5.5.1.7). Domain names are not case sensitive.
+
+ REMOTE_HOST = hostname
+
+ Servers SHOULD provide this information to scripts.
+
+5.5.1.9 REMOTE_IDENT
+
+ The identity information supported about the connection by a RFC 1413
+ [8] request, if available.
+
+ REMOTE_IDENT = *CHAR
+
+
+
+
+
+Lennox, et al. Informational [Page 19]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ The server MAY choose not to support this feature, and it is
+ anticipated that not many implementations will, as the information is
+ not particularly useful in the presence of complex proxy paths.
+
+5.5.1.10 REMOTE_USER
+
+ If the message requested authentication (i.e., the AUTH_TYPE
+ metavariable is set), then the value of the REMOTE_USER metavariable
+ is set to the user-ID supplied for the authentication. For Basic
+ authentication this is the content of the (decoded) "userid" grammar
+ element; for Digest it is content of "username-value." For PGP
+ authentication, it is the URI specified in the "signed-by" parameter
+ of the Authorization header, if present, otherwise the URI part of
+ the From header.
+
+ If some other authentication scheme was requested, this metavariable
+ SHOULD be set to an appropriate component of the authorization
+ information identifying the user or entity associated with the
+ credentials. If authentication was not requested, this metavariable
+ is not defined.
+
+ REMOTE_USER = *OCTET
+
+
+ Servers SHOULD provide this metavariable to scripts.
+
+5.5.1.11 REQUEST_METHOD
+
+ If the message triggering the script was a request, the
+ REQUEST_METHOD metavariable is set to the method with which the
+ request was made, as described in section 4.2 of the SIP/2.0
+ specification [2]; otherwise not defined.
+
+ REQUEST_METHOD = sip-method
+ sip-method = "INVITE" | "BYE" | "OPTIONS" | "CANCEL"
+ | "REGISTER" | "ACK"
+ | extension-method
+ extension-method = token
+
+ Note that ACK is usually not appropriate for the SIP CGI 1.1
+ environment; however, see section 5.11. The implications of REGISTER
+ in the CGI context are discussed in section 5.9, and CANCEL is
+ discussed in section 5.10. A SIP CGI 1.1 server MAY choose to
+ process some methods directly rather than passing them to scripts.
+
+ Servers MUST provide this metavariable to scripts if the triggering
+ message was a request.
+
+
+
+
+Lennox, et al. Informational [Page 20]
+
+RFC 3050 CGI for SIP January 2001
+
+
+5.5.1.12 REQUEST_TOKEN
+
+ REQUEST_TOKEN = token
+
+ If the script specified a request token in a proxied request, this
+ token is returned to the server in responses to that request. Note
+ that this token is chosen by the script, not by the server. Each
+ response to a proxied request contains the same value for this token.
+
+5.5.1.13 REQUEST_URI
+
+ This metavariable is specific to requests made with SIP.
+
+ REQUEST_URI = absoluteURI ; defined in RFC 2396 [9]
+
+ If the message triggering the script was a request, this variable
+ indicates the URI specified with the request method. This
+ metavariable is only defined if REQUEST_METHOD is defined; in that
+ case, servers MUST provide it to scripts.
+
+ This metavariable fills the roles of HTTP CGI's
+ SCRIPT_NAME, PATH_INFO, and QUERY_STRING.
+
+5.5.1.14 RESPONSE_STATUS
+
+ RESPONSE_STATUS = Status-Code
+
+ If the message triggering the script was a response, this variable
+ indicates the numeric code specified in the response; otherwise it is
+ not defined. In the former case, servers MUST provide this
+ metavariable to scripts.
+
+5.5.1.15 RESPONSE_REASON
+
+ RESPONSE_REASON = Reason-Phrase
+
+ If the message triggering the script was a response, this variable
+ indicates the textual string specified in the response.
+
+5.5.1.16 RESPONSE_TOKEN
+
+ RESPONSE_TOKEN = token
+
+ If the message triggering the script was a response, the server MUST
+ specify a token which subsequent invocations of the CGI script can
+ use to identify this response. This string is chosen by the server
+ and is opaque to the CGI script. See the discussion of CGI-FORWARD-
+ RESPONSE in section 5.6.1 below.
+
+
+
+Lennox, et al. Informational [Page 21]
+
+RFC 3050 CGI for SIP January 2001
+
+
+5.5.1.17 SCRIPT_COOKIE
+
+ SCRIPT_COOKIE = token
+
+ This is the value an earlier invocation of this script for this
+ transaction passed to the server in CGI action line CGI-SET-COOKIE.
+ See the description of that action in section 5.6.1.4 below.
+
+5.5.1.18 SERVER_NAME
+
+ The SERVER_NAME metavariable is set to the name of the server.
+
+ SERVER_NAME = hostname | hostnumber
+
+ Servers MUST provide this metavariable to scripts.
+
+5.5.1.19 SERVER_PORT
+
+ The SERVER_PORT metavariable is set to the port on which the message
+ was received.
+
+ SERVER_PORT = 1*digit
+
+ Servers MUST provide this metavariable to scripts.
+
+5.5.1.20 SERVER_PROTOCOL
+
+ The SERVER_PROTOCOL metavariable is set to the name and revision of
+ the protocol with which the message arrived. This will usually be
+ "SIP/2.0". This is not necessarily the same as the protocol version
+ used by the server in its response to the client.
+
+ SERVER_PROTOCOL = SIP-Version | extension-version
+ | extension-token
+ extension-version = protocol "/" 1*digit "." 1*digit
+ protocol = 1*( alphanum | "+" | "-" | "." )
+ extension-token = token
+
+ Servers MUST provide this metavariable to scripts.
+
+
+
+
+
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 22]
+
+RFC 3050 CGI for SIP January 2001
+
+
+5.5.1.21 SERVER_SOFTWARE
+
+ The SERVER_SOFTWARE metavariable is set to the name and version of
+ the information server software handling the message (and running the
+ gateway).
+
+ SERVER_SOFTWARE = 1*product
+ product = token [ "/" product-version ]
+ product-version = token
+
+ Servers MUST provide this metavariable to scripts.
+
+5.5.2 Message Bodies
+
+ As there may be a data entity attached to the message, there MUST be
+ a system-defined method for the script to read these data. Unless
+ defined otherwise, this will be via the `standard input' file
+ descriptor.
+
+ If the metavariable CONTENT_LENGTH (see section 5.5.1.2) is defined,
+ the server MUST supply at least that many bytes to scripts on the
+ standard input stream. Scripts are not obliged to read the data.
+ Servers MAY signal an EOF condition after CONTENT_LENGTH bytes have
+ been read, but are not obligated to do so. Therefore, scripts MUST
+ NOT attempt to read more than CONTENT_LENGTH bytes, even if more data
+ are available.
+
+5.6 Data Output from the SIP CGI Script
+
+ There MUST be a system-defined method for the script to send data
+ back to the server or client. Unless defined otherwise, this will be
+ via the `standard output' file descriptor.
+
+ Servers MAY implement a timeout period within which data must be
+ received from scripts, a maximum number of requests or responses that
+ a particular CGI script can initiate, a maximum total number of
+ requests or responses that can be sent by scripts over the lifetime
+ of a transaction, or any other resource limitations it desires. If a
+ script exceeds one of these limitations, the server MAY terminate the
+ script process and SHOULD abort the transaction with either a `504
+ Gateway Timed Out' or a `500 Internal Server Error' response.
+
+
+
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 23]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ A SIP CGI script's output consists of any number of messages, each
+ corresponding to actions which the script is requesting that the
+ server perform. Messages consist of an action line, whose syntax is
+ specific to the type of action, followed by CGI header fields and SIP
+ header fields. Action lines determine the nature of the action
+ performed, and are described in section 5.6.1. CGI header fields
+ pass additional instructions or information to the server, and are
+ described in section 5.6.2.
+
+ A message MUST contain exactly one action line, MAY also contain any
+ number of CGI header fields and SIP header fields, and MAY contain a
+ SIP body.
+
+ All header fields (both SIP and CGI) occurring in an output message
+ MUST be specified one per line; SIP CGI 1.1 makes no provision for
+ continuation lines.
+
+ The generic syntax of CGI header fields is specified in section
+ 5.6.2.
+
+ A server MAY choose to honor only some of the requests or responses;
+ in particular, it SHOULD NOT accept any responses following a Status
+ message which sends a definitive non-success response.
+
+ The messages sent by a script are delimited as follows:
+
+ 1. A message begins with an action line.
+
+ 2. If the message does not contain a Content-Type header
+ field, or if it contains the header field "Content-Length:
+ 0", then it is terminated by a blank line.
+
+ 3. If the message contains both Content-Type and Content-
+ Length header fields, the message has a body consisting of
+ the Content-Length octets following the blank line below
+ the set. The next message begins after the body (and
+ optionally some number of blank lines). If the script
+ closes its output prematurely, the server SHOULD report a
+ 500-class server error.
+
+ 4. If the message contains Content-Type but not Content-
+ Length, the message's body similarly begins with the blank
+ line following the set; this body extends until the script
+ closes its output. In this case, this is necessarily the
+ last message the script can send. The server SHOULD insert
+ a Content-Length header containing the amount of data read
+ before the script closed its output.
+
+
+
+
+Lennox, et al. Informational [Page 24]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ 5. If a message contains a non-zero Content-Length but does
+ not contain a Content-Type, it is an error. The server
+ SHOULD report a 500-class server error.
+
+ The output of a SIP CGI script is intended to be
+ syntactically identical to that of a UDP packet in which
+ multiple requests or responses are sent, so that the same
+ message parser may be used.
+
+5.6.1 CGI Action Lines
+
+5.6.1.1 Status
+
+ Status = SIP-Version 3*digit SP reason-phrase NL
+
+ This action line causes the server to generate a SIP response and
+ relay it upstream towards the client. The server MUST copy the To,
+ From, Call-ID, and CSeq headers from the original request into the
+ response if these headers are not specified in the script output.
+ The server SHOULD copy any other headers from the request which would
+ normally be copied in the response if these are not specified in the
+ script output.
+
+ For compatibility with HTTP CGI, a server MAY interpret a message
+ containing a Content-Type header field and no action line as though
+ it contained "SIP/2.0 200 OK". This usage is deprecated.
+
+5.6.1.2 Proxy Request
+
+ Proxy-Request = "CGI-PROXY-REQUEST" SIP-URL SIP-Version
+
+ This action line causes the server to forward a request to the
+ specified SIP URI. It may be sent either by a script triggered by a
+ request, in which case the triggering request is forwarded; or by a
+ script triggered by a response on a server which is running
+ statefully, in which case the initial request of the transaction is
+ sent.
+
+ Any SIP header field MAY be specified below the action line.
+ Specified SIP headers replace all those in the original message in
+ their entirety; if a script wants to preserve header elements from
+ the original message as well as adding new ones, it can concatenate
+ them by the usual rules of header concatenation, and place the result
+ in the script output. New header fields are added to the message
+ after any Via headers but before any other headers.
+
+
+
+
+
+
+Lennox, et al. Informational [Page 25]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ Any headers from the original request which are not generated by the
+ CGI script are copied into the proxied request, after modifications
+ normally performed by a proxy server. In particular, the server MUST
+ append a Via field and decrement Max-Forwards. A server MAY perform
+ additional modifications as it sees fit, such as adding a Record-
+ Route header. A server SHOULD NOT append these headers if they are
+ specified in the script output.
+
+ A script MAY specify that a SIP header is to be deleted from the
+ message by using the CGI-Remove CGI header; see section 5.6.2.
+
+ If the message does not specify a body, the body from the initial
+ request is used. A message with "Content-Length: 0" is specifying an
+ empty body; this causes the body to be deleted from the message.
+
+ If the original request was authenticated by any means other than
+ `basic,' the script SHOULD NOT add, change, or remove any end-to-end
+ headers, as this would break the authentication.
+
+5.6.1.3 Forward Response
+
+ Forward-Response = "CGI-FORWARD-RESPONSE" Response-Name
+ SIP-Version
+ Response-Name = response-token | "this"
+
+ This action line causes the server to forward a response on to its
+ appropriate final destination. The same rules apply for accompanying
+ SIP headers and message bodies as for CGI-PROXY-REQUEST.
+
+ The specified response name may either be a response token the server
+ previously submitted in a RESPONSE_TOKEN metavariable, or the string
+ "this." The string "this" may only be sent if the message which
+ triggered this CGI script was a response; it indicates that this
+ triggering response should be forwarded.
+
+5.6.1.4 Script Cookie
+
+ Script-Cookie = "CGI-SET-COOKIE" token SIP-Version
+
+ This action line causes the server to store a script cookie, passed
+ as a token in the action line. Subsequent script invocations for
+ messages within the same transaction carry the token in a meta-
+ header. The script can alter the value of the cookie by subsequent
+ script cookie actions. This alteration will take affect for all
+ subsequent script invocations.
+
+
+
+
+
+
+Lennox, et al. Informational [Page 26]
+
+RFC 3050 CGI for SIP January 2001
+
+
+5.6.1.5 CGI Again
+
+ CGI-Again = "CGI-AGAIN" ("yes" | "no") SIP-Version
+
+ This action line determines whether the script will be invoked for
+ subsequent requests and responses for this transaction. If the
+ parameter "yes" is given to this action, the script will be executed
+ again when the next message arrives. If the parameter is "no," or
+ this action is not specified, the script will not be executed again,
+ and the server will perform its default action for all subsequent
+ messages.
+
+5.6.1.6 Default Action
+
+ If none of the actions CGI-PROXY-REQUEST, CGI-FORWARD-RESPONSE, or a
+ new response are performed -- that is to say, the script outputs only
+ CGI-AGAIN, CGI-SET-COOKIE, or nothing -- the script performs its
+ default action. The default action to take depends on the event
+ which triggered the script:
+
+ Request received: When the request is first received, the
+ default action of the server is to check whether the
+ domain of the server matches the domain of the Request-
+ URI. If it does not, the request is proxied to the
+ request in the Request-URI. Otherwise, the server checks
+ its registration database against the request, and either
+ proxies or redirects the request based on the action
+ specified by the user agent in the registration.
+
+ Proxied response received: If a response is received to a
+ proxied request, the server forwards the response towards
+ the caller if the response was a 200 or 600 class
+ response, and sends a CANCEL on all pending branches. If
+ the response was 100 class, the state machinery for that
+ branch is updated, and the response is proxied upstream
+ towards the caller unless the it was a 100 response, not
+ some other 1xx. For 300, 400, and 500 class responses,
+ an ACK is sent, and the response is forwarded upstream
+ towards the caller if all other branches have terminated,
+ and the response is the best received so far. If not all
+ branches have terminated, the server does nothing. If
+ all branches have terminated, but this response is not
+ the best, the best is forwarded upstream. This is the
+ basic algorithm outlined in the SIP specification.
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 27]
+
+RFC 3050 CGI for SIP January 2001
+
+
+5.6.2 CGI Header Fields
+
+ CGI header fields syntactically resemble SIP header fields, but their
+ names all begin with the string "CGI-". The SIP server MUST strip
+ all CGI header fields from any message before sending it, including
+ those it does not recognize.
+
+ CGI header fields have the generic syntax specified in section 6.6 of
+ the SIP/2.0 specification [2]. The field-name is not case sensitive;
+ the field value MUST conform to the grammar of that specific field in
+ the specification where it is defined.
+
+5.6.2.1 Request-Token
+
+ Request-Token = "CGI-Request-Token" ":" token
+
+ To assist in matching responses to proxied requests, the script can
+ place a CGI-Request-Token CGI header in a CGI-PROXY-REQUEST or new
+ request. This header contains a token, opaque to the server. When a
+ response to this request arrives, the token is passed back to the
+ script as a meta-header.
+
+ This allows scripts to "fork" a proxy request, and
+ correlate which response corresponds to which branch of the
+ request.
+
+5.6.2.2 Remove
+
+ Remove = "CGI-Remove" ":" 1#field-name
+
+ The CGI-Remove header allows the script to remove SIP headers from
+ the outgoing request or response. The value of this header is a
+ comma-separated list of SIP headers which should be removed before
+ sending out the message.
+
+ A script MAY specify headers which are not in the request; the server
+ SHOULD silently ignore these. A script SHOULD NOT both specify a SIP
+ header in its output and also list that header in a CGI-Remove
+ header; the result of doing this is undefined.
+
+5.7 Local Expiration Handling
+
+ If a CGI script specifies an Expires header field along with CGI-
+ PROXY-REQUEST, the SIP server SHOULD track the expiration timeout
+ locally as well as sending the message to the remote server. When
+ the timeout expires, the server SHOULD generate a "408 Request
+
+
+
+
+
+Lennox, et al. Informational [Page 28]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ Timeout" response. The timeout response SHOULD be handled as
+ specified in section 5.8. At the time the request is timed out, the
+ server SHOULD also transmit CANCEL messages for the request.
+
+ This allows a SIP CGI script in a proxy server to implement
+ services like "Call Forward No Answer" to trigger after a
+ user-determined time, even if the remote user-agent server
+ is not responding or does not properly handle the Expires
+ header field.
+
+5.8 Locally-Generated Responses
+
+ In a proxy environment, locally-generated responses such as "408
+ Request Timeout" SHOULD be sent to the CGI script in the same manner
+ as received messages are. However, messages which merely report a
+ problem with a message, such as "400 Bad Request", SHOULD NOT be.
+
+ This is the other half of the requirements for the
+ implementation of the "Call Forward No Answer" service,
+ along with the local handling of the Expires header.
+
+5.9 SIP CGI and REGISTER
+
+ The specific semantics of a SIP CGI script which is triggered by a
+ REGISTER request are somewhat different than that of those triggered
+ by call-related requests; however, allowing user control of
+ registration may in some cases be useful. The two specific actions
+ for REGISTER that need to be discussed are the response "200" and the
+ default action. In the former case, the server SHOULD assume that
+ the CGI script is handling the registration internally, and SHOULD
+ NOT add the registration to its internal registration database; in
+ the latter case, the server SHOULD add the registration to its own
+ database. The server also SHOULD NOT add the registration if a 3xx,
+ 4xx, 5xx, or 6xx status was returned, or if the registration request
+ was proxied to another location.
+
+5.10 SIP CGI and CANCEL
+
+ SIP CGI servers SHOULD execute scripts when a CANCEL message is
+ received. The script SHOULD clean up any state it has for the
+ transaction as quickly as possible.
+
+
+
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 29]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ When a CANCEL is received at a server for an existing transaction,
+ the server SHOULD send a 200 OK response to the cancel and cancel all
+ currently outstanding branches. The transmission of the script on a
+ CANCEL message is purely advisory, and the script SHOULD NOT perform
+ any actions in response to it.
+
+5.11 SIP CGI and ACK
+
+5.11.1 Receiving ACK's
+
+ Under normal circumstances, if the server receives an ACK, the script
+ is not re-executed. If the ACK is destined for the proxy
+ (acknowledging a 300, 400, 500, or 600 response), the ACK causes
+ response retransmissions to cease. If the ACK is for a 200 response
+ forwarded from a downstream server, the ACK is proxied downstream.
+
+ However, if the script generated its own 200 response to an INVITE
+ request, the script SHOULD be re-executed with the ACK message. This
+ is necessary in cases where the script is causing the proxy to act as
+ a UAS. ACK messages can contain bodies, and would therefore be
+ useful to the script.
+
+5.11.2 Sending ACK's
+
+ When the server receives a non-200 final response to an INVITE
+ request, it SHOULD generate an ACK on its own, and not depend on the
+ script to do so. There is no way in SIP CGI 1.1 to override this
+ behavior. However, since the server will not generate an ACK for 200
+ responses to INVITE, a script causing the server to act as a UAC MUST
+ generate ACK's for them.
+
+6 System Specifications
+
+6.1 Unix
+
+ The implementation of SIP CGI on a Unix operating system platform
+ SHOULD use environment variables as the mechanism of providing
+ request metadata to CGI scripts.
+
+ For Unix compatible operating systems, the following are defined:
+
+ Environment variables: These are accessed by the C library
+ routine getenv.
+
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 30]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ The current working directory: The current working directory for
+ the script SHOULD be set to the directory containing the
+ script.
+
+ Character set: The US-ASCII character set is used for the
+ definition of environment variable names and header field
+ names; the newline (NL) sequence is LF; servers SHOULD also
+ accept CR LF as a newline.
+
+6.2 Microsoft Windows
+
+ The implementation of SIP CGI on 32-bit Microsoft Windows system
+ platforms (Windows 95, 98, NT, and 2000) SHOULD use environment
+ variables as the mechanism of providing request metadata to CGI
+ scripts.
+
+ For Microsoft Windows, the following are defined:
+
+ Environment variables: These are accessed by the C library
+ routine getenv.
+
+ The current working directory: The current working directory for
+ the script SHOULD be set to the directory containing the
+ script.
+
+ Character set: The US-ASCII character set is used for the
+ definition of environment variable names and header field
+ names; the newline (NL) sequence is CR LF; servers SHOULD
+ also accept LF as a newline.
+
+7 Security Considerations
+
+7.1 Request Initiation
+
+ CGI scripts are able to initiate arbitrary SIP transactions, or to
+ produce spoofed responses of any sort. This protocol does not
+ attempt to restrict the actions CGI scripts can take. Server
+ administrators MUST consider CGI scripts to be as security-sensitive
+ as their SIP server itself, and perform equivalent levels of security
+ review before installing them.
+
+7.2 Authenticated and Encrypted Messages
+
+ CGI scripts must be careful not to interfere with authentication. In
+ particular, adding or removing header fields that are below the
+ Authorization header will cause the message to fail authentication at
+ the user agent.
+
+
+
+
+Lennox, et al. Informational [Page 31]
+
+RFC 3050 CGI for SIP January 2001
+
+
+ When a SIP request is encrypted, the headers which are in the clear
+ are passed to the server according to this specification. The
+ encrypted portion of the request is passed to the script as a body.
+ Any SIP headers output by the script will be added to the message.
+ However, scripts should be aware that these may be discarded if they
+ also exist within the encrypted portion.
+
+7.3 SIP Header Fields Containing Sensitive Information
+
+ Some SIP header fields may carry sensitive information which the
+ server SHOULD NOT pass on to the script unless explicitly configured
+ to do so. For example, if the server protects the script using the
+ Basic authentication scheme, then the client will send an
+ Authorization header field containing a username and password. If
+ the server, rather than the script, validates this information then
+ the password SHOULD NOT be passed on to the script via the
+ HTTP_AUTHORIZATION metavariable.
+
+7.4 Script Interference with the Server
+
+ The most common implementation of CGI invokes the script as a child
+ process using the same user and group as the server process. It
+ SHOULD therefore be ensured that the script cannot interfere with the
+ server process, its configuration, or documents.
+
+ If the script is executed by calling a function linked in to the
+ server software (either at compile-time or run-time) then precautions
+ SHOULD be taken to protect the core memory of the server, or to
+ ensure that untrusted code cannot be executed.
+
+7.5 Data Length and Buffering Considerations
+
+ This specification places no limits on the length of entity bodies
+ presented to the script. Scripts SHOULD NOT assume that statically
+ allocated buffers of any size are sufficient to contain the entire
+ submission at one time. Use of a fixed length buffer without careful
+ overflow checking may result in an attacker exploiting `stack-
+ smashing' or `stack-overflow' vulnerabilities of the operating
+ system. Scripts may spool large submissions to disk or other
+ buffering media, but a rapid succession of large submissions may
+ result in denial of service conditions. If the CONTENT_LENGTH of an
+ entity-body is larger than resource considerations allow, scripts
+ SHOULD respond with `413 Request Entity Too Large.'
+
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 32]
+
+RFC 3050 CGI for SIP January 2001
+
+
+8 Acknowledgements
+
+ This work draws extremely heavily upon the HTTP CGI specification
+ [1]; approximately half the text of the specification section is
+ taken from that document.
+
+9 Authors' Addresses
+
+ Jonathan Lennox
+ Dept. of Computer Science
+ Columbia University
+ 1214 Amsterdam Avenue, MC 0401
+ New York, NY 10027
+ USA
+
+ EMail: lennox@cs.columbia.edu
+
+
+ Jonathan Rosenberg
+ dynamicsoft
+ 72 Eagle Rock Ave.
+ First Floor
+ East Hanover, NJ 07936
+
+ EMail: jdrosen@dynamicsoft.com
+
+
+ Henning Schulzrinne
+ Dept. of Computer Science
+ Columbia University
+ 1214 Amsterdam Avenue, MC 0401
+ New York, NY 10027
+ USA
+
+ EMail: schulzrinne@cs.columbia.edu
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 33]
+
+RFC 3050 CGI for SIP January 2001
+
+
+10 Bibliography
+
+ [1] http://hoohoo.ncsa.uiuc.edu/cgi/interface.html
+
+ [2] Handley, M, Schulzrinne, H., Schooler, E. and J. Rosenberg,
+ "SIP: Session Initiation Protocol", RFC 2543, March 1999.
+
+ [3] Crocker, D., "Standard for the Format of ARPA Internet Text
+ Messages", STD 10, RFC 822, August 1982.
+
+ [4] Bradner, S., "Key words for use in RFCs to indicate requirement
+ levels", BCP 14, RFC 2119, March 1997.
+
+ [5] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
+ Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
+ HTTP/1.1", RFC 2616, June 1999.
+
+ [6] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) Part Two: Media Types", RFC 2046, November
+ 1996.
+
+ [7] Hinden, R. and S. Deering, "IP Version 6 Addressing
+ Architecture", RFC 2373, July 1998.
+
+ [8] St. Johns, M., "Identification Protocol", RFC 1413, January
+ 1993.
+
+ [9] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource
+ Identifiers (URI): Generic Syntax", RFC 2396, August 1998.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 34]
+
+RFC 3050 CGI for SIP January 2001
+
+
+11 Full Copyright Statement
+
+ Copyright (C) The Internet Society (2001). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Lennox, et al. Informational [Page 35]
+