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.
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.
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.
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
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.
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.
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.
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.'
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
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", RFC2543, March 1999.
[3] Crocker, D., "Standard for the Format of ARPA Internet Text
Messages", STD 10, RFC822, August 1982.
[4] Bradner, S., "Key words for use in RFCs to indicate requirement
levels", BCP 14, RFC2119, 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", RFC2616, June 1999.
[6] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC2046, November
1996.
[7] Hinden, R. and S. Deering, "IP Version 6 Addressing
Architecture", RFC2373, July 1998.
[8] St. Johns, M., "Identification Protocol", RFC1413, January
1993.
[9] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource
Identifiers (URI): Generic Syntax", RFC2396, August 1998.
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 RFCEditor function is currently provided by the
Internet Society.