Careful attention must be paid to the actual usage of terminology.
Many documents misuse the terms header, header field, and header
field values, for example. Document authors SHOULD do a careful
review of their documents for proper usage of these terms.
4.4. Syntactic Issues
Extensions that define new methods SHOULD use all capitals for the
method name. Method names SHOULD be shorter than 10 characters and
SHOULD attempt to convey the general meaning of the request. Method
names are case sensitive, and therefore, strictly speaking, they
don’t have to be capitalized. However, using capitalized method
names keeps with a long-standing convention in SIP and many similar
protocols, such as HTTP [15] and RTSP [16].
Extensions that define new header fields that are anticipated to be
heavily used MAY define a compact form if those header fields are
more than six characters. "Heavily used" means that the percentage
of all emitted messages that contain that header field is over thirty
percent. Usage of compact forms in these cases is only a MAY because
there are better approaches for reducing message overhead [20].
Compact header fields MUST be a single character. When all 26
characters are exhausted, new compact forms will no longer be
defined. Header field names are defined by the "token" production in
RFC 3261, Section 25.1, and thus include the upper and lowercase
letters, the digits 0 through 9, the HYPHEN-MINUS (-), FULL STOP (.),
EXCLAMATION MARK (!), PERCENT SIGN (%), ASTERISK (*), LOW LINE (_),
PLUS SIGN (+), GRAVE ACCENT (`), APOSTROPHE (’), and TILDE (~). They
SHOULD be descriptive but reasonably brief. Although header field
names are case insensitive, a single common capitalization SHOULD be
used throughout the document. It is RECOMMENDED that each English
word present in the header field name have its first letter
capitalized. For example, "ThisIsANewHeader".
As an example, the following are poor choices for header field names:
ThisIsMyNewHeaderThatDoesntDoVeryMuchButItHasANiceName
--.!A
Function
Case sensitivity of parameters and values is a constant source of
confusion, a difficulty that plagued RFC 2543 [17]. This has been
simplified through the usage of the BNF constructs of RFC 4234 [5],
which have clear rules of case sensitivity and insensitivity.
Therefore, the BNF for an extension completely defines the matching
rules.
Extensions MUST be consistent with the SIP conventions for case
sensitivity. Methods MUST be case sensitive. Header field names
MUST be case insensitive. Header field parameter names MUST be case
insensitive. Header field values and parameter values are sometimes
case sensitive, and sometimes case insensitive. However, generally,
they SHOULD be case insensitive. Defining a case-sensitive component
requires explicitly listing each character through its ASCII code.
Extensions that contain freeform text MUST allow that text to be
UTF-8, as per the IETF policies on character set usage [3]. This
ensures that SIP remains an internationalized standard. As a general
guideline, freeform text is never needed by programs to perform
protocol processing. It is usually entered by and displayed to the
user. If an extension uses a parameter that can contain UTF-8-
encoded characters, and that extension requires a comparison to be
made of this parameter to other parameters, the comparison MUST be
case sensitive. Case-insensitive comparison rules for UTF-8 text
are, at this time, impossible and MUST be avoided.
Extensions that make use of dates MUST use the SIP-Date BNF defined
in RFC 3261. No other date formats are allowed. However, the usage
of absolute dates to determine intervals (for example, the time at
which some timer fires) is NOT RECOMMENDED. This is because it
requires synchronized time between peers, and this is frequently not
the case. Therefore, relative times, expressed in numbers of
seconds, SHOULD be used.
Extensions that include network-layer addresses SHOULD permit dotted
quad IPv4 addresses, IPv6 addresses in the format described in [4],
and domain names.
Extensions that have header fields containing URIs SHOULD be explicit
about which URI schemes can be used in that header field. Header
fields SHOULD allow the broadest set of URI schemes possible that are
a match for the semantics of the header field.
Header fields MUST follow the standard formatting for SIP, defined as
follows:
header = header-name HCOLON header-value
*(COMMA header-value)
header-name = token
header-value = value *(SEMI value-parameter)
value-parameter = token [EQUAL gen-value]
gen-value = token / host / quoted-string
value = token / host / quoted-string
In some cases, this form is not sufficient. That is the case for
header fields that express descriptive text meant for human
consumption. An example is the Subject header field in SIP [2]. In
this case, an alternate form is:
header = header-name HCOLON [TEXT-UTF8-TRIM]
Developers of extensions SHOULD allow for extension parameters in
their header fields.
Header fields that contain a list of URIs SHOULD follow the same
syntax as the Contact header field in SIP. Implementors are also
encouraged to wrap these URI in angle brackets, "<" and ">", at all
times. We have found this to be a frequently misimplemented feature.
Beyond the compact form, there is no need to define compressed
versions of header field values. Compression of SIP messages SHOULD
be handled at lower layers, for example, using IP payload compression
[18] or signalling compression [20].
Syntax for header fields is expressed in Augmented Backus-Naur Form
and MUST follow the format of RFC 4234 [5]. Extensions MUST make use
of the primitive components defined in RFC 3261 [2]. If the
construction for a BNF element is defined in another specification,
it is RECOMMENDED that the construction be referenced rather than
copied. The reference SHOULD include both the document and section
number. All BNF elements must be either defined or referenced.
It is RECOMMENDED that BNF be collected into a single section near
the end of the document.
All tokens and quoted strings are separated by explicit linear white
space. Linear white space, for better or worse, allows for line
folding. Extensions MUST NOT define new header fields that use
alternate linear white space rules.
All SIP extensions MUST verify that any BNF productions that they
define in their grammar do not conflict with any existing grammar
defined in other SIP standards-track specifications.
4.5. Semantics, Semantics, Semantics
Developers of protocols often get caught up in syntax issues, without
spending enough time on semantics. The semantics of a protocol are
far more important. SIP extensions MUST clearly define the semantics
of the extensions. Specifically, the extension MUST specify the
behaviors expected of a UAC, UAS, and proxy in processing the
extension. This is often best described by having separate sections
for each of these three elements. Each section SHOULD step through
the processing rules in temporal order of the most common messaging
scenario.
Processing rules generally specify actions to be taken (in terms of
messages to be sent, variables to be stored, and rules to be
followed) on receipt of messages and expiration of timers. If an
action requires transmission of a message, the rule SHOULD outline
requirements for insertion of header fields or other information in
the message.
The extension SHOULD specify procedures to be taken in exceptional
conditions that are recoverable, or that require some kind of user
intervention. Handling of unrecoverable errors does not require
specification.
4.6. Examples Section
The specification SHOULD contain a section that gives examples of
call flows and message formatting. Extensions that define
substantial new syntax SHOULD include examples of messages containing
that syntax. Examples of message flows should be given to cover
common cases and at least one failure or unusual case.
For an example of how to construct a good examples section, see the
message flows and message formatting defined in the Basic Call Flows
specification [21]. Note that complete messages SHOULD be used. Be
careful to include tags, Via header fields (with the branch ID
cookie), Max-Forwards, Content-Lengths, Record-Route, and Route
header fields. Example INVITE messages MAY omit session
descriptions, and Content-Length values MAY be set to "..." to
indicate that the value is not provided. However, the specification
MUST explicitly call out the meaning of the "..." and explicitly
indicate that session descriptions were not included.
4.7. Overview Section
Too often, extension documents dive into detailed syntax and
semantics without giving a general overview of operation. This makes
understanding of the extension harder. It is RECOMMENDED that
extensions have a protocol overview section that discusses the basic
operation of the extension. Basic operation usually consists of the
message flow, in temporal order, for the most common case covered by
the extension. The most important processing rules for the elements
in the call flow SHOULD be mentioned. Usage of the RFC 2119 [1]
terminology in the overview section is NOT RECOMMENDED, and the
specification should explicitly state that the overview is tutorial
in nature only. This section SHOULD expand all acronyms, even those
common in SIP systems, and SHOULD be understandable to readers who
are not SIP experts. [27] provides additional guidance on writing
good overview sections.
4.8. IANA Considerations Section
Documents that define new SIP extensions will invariably have IANA
Considerations sections.
If your extension is defining a new event package, you MUST register
that package. RFC 3265 [6] provides the registration template. See
[22] for an example of the registration of a new event package. As
discussed in RFC 3427 [10], only standards-track documents can
register new event-template packages. Both standards-track and
informational specifications can register event packages.
If your extension is defining a new header field, you MUST register
that header field. RFC 3261 [2] provides a registration template.
See Section 8.2 of RFC 3262 [23] for an example of how to register
new SIP header fields. Both standards-track and informational
P-header specifications can register new header fields [10].
If your extension is defining a new response code, you MUST register
that response code. RFC 3261 [2] provides a registration template.
See Section 6.4 of RFC 3329 [19] for an example of how to register a
new response code. As discussed in RFC 3427 [10], only standards-
track documents can register new response codes.
If your extension is defining a new SIP method, you MUST register
that method. RFC 3261 [2] provides a registration template. See
Section 10 of RFC 3311 [24] for an example of how to register a new
SIP method. As discussed in RFC 3427 [10], only standards-track
documents can register new methods.
If your extension is defining a new SIP header field parameter, you
MUST register that header field parameter per the guidelines in RFC
3968 [7]. Section 4.1 of that specification provides a template.
Only IETF approved specifications can register new header field
parameters. However, there is no requirement that these be standards
track.
If your extension is defining a new SIP URI parameter, you MUST
register that URI parameter per the guidelines in RFC 3969 [8].
Section 4.1 of that specification provides a template. Only
standards-track documents can register new URI parameters.
Many SIP extensions make use of option tags, carried in the Require,
Proxy-Require, and Supported header fields. Section 4.1 discusses
some of the issues involved in the usage of these header fields. If
your extension does require them, you MUST register an option tag for
your extension. RFC 3261 [2] provides a registration template. See
Section 8.1 of RFC 3262 [23] for an example of how to register an
option tag. Only standards-track RFCs can register new option tags.
Some SIP extensions will require establishment of their own IANA
registries. RFC 2434 [25] provides guidance on how and when IANA
registries are established. For an example of how to set one up, see
Section 6 of RFC 3265 [6] for an example.
4.9. Document-Naming Conventions
An important decision to be made about the extension is its title.
The title MUST indicate that the document is an extension to SIP. It
is RECOMMENDED that the title follow the basic form of "A [summary of
function] for the Session Initiation Protocol (SIP)", where the
summary of function is a one- to three-word description of the
extension. For example, if an extension defines a new header field,
called Make-Coffee, for making coffee, the title would read, "Making
Coffee with the Session Initiation Protocol (SIP)". It is
RECOMMENDED that these additional words be descriptive rather than
naming the header field. For example, the extension for making
coffee should not be named "The Make-Coffee Header for the Session
Initiation Protocol".
For extensions that define new methods, an acceptable template for
titles is "The Session Initiation Protocol (SIP) X Method" where X is
the name of the method.
Note that the acronym SIP MUST be expanded in the titles of RFCs, as
per [26].
4.10. Additional Considerations for New Methods
Extensions that define new methods SHOULD take into consideration and
discuss the following issues:
o Can it contain bodies? If so, what is the meaning of the presence
of those bodies? What body types are allowed?
o Can a transaction with this request method occur while another
transaction, in the same and/or reverse direction, is in progress?
o The extension MUST define which header fields can be present in
requests of that method. It is RECOMMENDED that this information
be represented as a new column of Table 2/3 of RFC 3261 [2]. The
table MUST contain rows for all header fields defined in
standards-track RFCs at the time of writing of the extension.
o Can the request be sent within a dialog, or does it establish a
dialog?
o Is it a target refresh request?
o Extensions to SIP that define new methods MAY specify whether
offers and answers can appear in requests of that method or its
responses. However, those extensions MUST adhere to the protocol
rules specified in [28] and MUST adhere to the additional
constraints for offers and answers as specified in SIP [2].
o Because of the nature of reliability treatment of requests with
new methods, those requests need to be answered immediately by the
UAS. Protocol extensions that require longer durations for the
generation of a response (such as a new method that requires human
interaction) SHOULD instead use two transactions - one to send the
request, and another in the reverse direction to convey the result
of the request. An example of that is SUBSCRIBE and NOTIFY [6].
o The SIP specification [2] allows new methods to specify whether
transactions using that new method can be canceled using a CANCEL
request. Further study of the non-INVITE transaction [14] has
determined that non-INVITE transactions must be completed as soon
as possible. New methods must not plan for the transaction to
pend long enough for CANCEL to be meaningful. Thus, new methods
MUST declare that transactions initiated by requests with that
method cannot be canceled. Future work may relax this
restriction, at which point these guidelines will be revised.
o New methods that establish a new dialog must discuss the impacts
of forking. The design of such new methods should follow the
pattern of requiring an immediate request in the reverse direction
from the request establishing a dialog, similar to the immediate
NOTIFY sent when a subscription is created per RFC 3265 [6].
The reliability mechanisms for all new methods must be the same as
for BYE. The delayed response feature of INVITE is only available in
INVITE, never for new methods. The design of new methods must
encourage an immediate response. If the application being enabled
requires a delay, the design SHOULD follow a pattern using multiple
transactions, similar to RFC 3265’s use of NOTIFYs with different
Subscription-State header field values (pending and active in
particular) in response to SUBSCRIBE [6].
4.11. Additional Considerations for New Header Fields or Header Field
Parameters
The most important issue for extensions that define new header fields
or header field parameters is backwards compatibility. See
Section 4.1 for a discussion of the issues. The extension MUST
detail how backwards compatibility is addressed.
It is often tempting to avoid creation of a new method by overloading
an existing method through a header field or parameter. Header
fields and parameters are not meant to fundamentally alter the
meaning of the method of the request. A new header field cannot
change the basic semantic and processing rules of a method. There is
no shortage of method names, so when an extension changes the basic
meaning of a request, a new method SHOULD be defined.
For extensions that define new header fields, the extension MUST
define the request methods the header field can appear in, and what
responses it can be used in. It is RECOMMENDED that this information
be represented as a new row of Table 2/3 of RFC 3261 [2]. The table
MUST contain columns for all methods defined in standards-track RFCs
at the time of writing of the extension.
4.12. Additional Considerations for New Body Types
Because SIP can run over UDP, extensions that specify the inclusion
of large bodies (where large is several times the ethernet MTU) are
frowned upon unless end-to-end congestion controlled transport can be
guaranteed. If at all possible, the content SHOULD be included
indirectly [9], even if congestion controlled transports are
available.
Note that the presence of a body MUST NOT change the nature of the
message. That is, bodies cannot alter the state machinery associated
with processing a request of a particular method or a response.
Bodies enhance this processing by providing additional data.
5. Interactions with SIP Features
We have observed that certain capabilities of SIP continually
interact with extensions in unusual ways. Writers of extensions
SHOULD consider the interactions of their extensions with these SIP
capabilities and document any unusual interactions, if they exist.
The following are the most common causes of problems:
Forking: Forking by far presents the most troublesome interactions
with extensions. This is generally because it can cause (1) a
single transmitted request to be received by an unknown number of
UASes, and (2) a single INVITE request to have multiple responses.
CANCEL and ACK: CANCEL and ACK are "special" SIP requests, in that
they are exceptions to many of the general request processing
rules. The main reason for this special status is that CANCEL and
ACK are always associated with another request. New methods
SHOULD consider the meaning of cancellation, as described above.
Extensions that define new header fields in INVITE requests SHOULD
consider whether they also need to be included in ACK and CANCEL.
Frequently they do, in order to allow a stateless proxy to route
the CANCEL or ACK identically to the INVITE.
Routing: The presence of Route header fields in a request can cause
it to be sent through intermediate proxies. Requests that
establish dialogs can be record-routed, so that the initial
request goes through one set of proxies, and subsequent requests
through a different set. These SIP features can interact in
unusual ways with extensions.
Stateless Proxies: SIP allows a proxy to be stateless. Stateless
proxies are unable to retransmit messages and cannot execute
certain services. Extensions that depend on some kind of proxy
processing SHOULD consider how stateless proxies affect that
processing.
Dialog Usages: SIP allows for requests that normally create their own
dialog (such as SUBSCRIBE) to be used within a dialog created by
another method (such as INVITE). In such a case, there are said
to be multiple usages of that dialog. Extensions SHOULD consider
their interaction with dialog usages. In particular, extensions
that define new error response codes SHOULD describe whether that
response code causes the dialog and all usages to terminate, or
just a specific usage.
6. Security Considerations
The nature of this document is such that it does not introduce any
new security considerations. However, many of the principles
described in the document affect whether a potential SIP extension
design is likely to support the SIP security architecture.
7. Acknowledgements
The authors would like to thank Rohan Mahy and Spencer Dawkins for
their comments. Robert Sparks contributed important text on CANCEL
issues. Thanks to Allison Mankin for her support.
8. References
8.1. Normative References
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[2] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP:
Session Initiation Protocol", RFC 3261, June 2002.
[3] Alvestrand, H., "IETF Policy on Character Sets and Languages",
BCP 18, RFC 2277, January 1998.
[4] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986,
January 2005.
[5] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 4234, October 2005.
[6] Roach, A.B., "Session Initiation Protocol (SIP)-Specific Event
Notification", RFC 3265, June 2002.
[7] Camarillo, G., "The Internet Assigned Number Authority (IANA)
Header Field Parameter Registry for the Session Initiation
Protocol (SIP)", BCP 98, RFC 3968, December 2004.
[8] Camarillo, G., "The Internet Assigned Number Authority (IANA)
Uniform Resource Identifier (URI) Parameter Registry for the
Session Initiation Protocol (SIP)", BCP 99, RFC 3969, December
2004.
[9] Burger, E., Ed., "A Mechanism for Content Indirection in Session
Initiation Protocol (SIP) Messages", RFC 4483, May 2006.
8.2. Informative References
[10] Mankin, A., Bradner, S., Mahy, R., Willis, D., Ott, J., and B.
Rosen, "Change Process for the Session Initiation Protocol
(SIP)", BCP 67, RFC 3427, December 2002.
[11] Droms, R., "Dynamic Host Configuration Protocol", RFC 2131,
March 1997.
[12] Sparks, R., "The Session Initiation Protocol (SIP) Refer
Method", RFC 3515, April 2003.
[13] Donovan, S. and J. Rosenberg, "Session Timers in the Session
Initiation Protocol (SIP)", RFC 4028, April 2005.
[14] Sparks, R., "Problems Identified Associated with the Session
Initiation Protocol’s (SIP) Non-INVITE Transaction", RFC 4321,
January 2006.
[15] 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.
[16] Schulzrinne, H., Rao, A., and R. Lanphier, "Real Time Streaming
Protocol (RTSP)", RFC 2326, April 1998.
[17] Handley, M., Schulzrinne, H., Schooler, E., and J. Rosenberg,