Guidelines for Authors of Extensions to the Session Initiation Protocol (SIP)
draft-ietf-sip-guidelines-09

[Ballot discuss]
Discuss for a few AD Review points and so that comments of a number of ADs/Areas
will be adddressed. 

3.2  SIP Architectural Model
OLD:
      Extensions SHOULD NOT work only under the assumption of a single
      hop or single provider.
NEW:
      Extensions MUST NOT work only under the assumption of a single
      hop or single provider.

I think this is of general architectural import.  Another take
might be to separate single hop and single provider
and cite the use of P-Headers:

  Extensions MUST NOT work only under the assumption of a
  single hop or specialized network topology.  They SHOULD
  avoid the assumption of a single provider (but see the use
  of P-Headers, RFC 3427).


-------

6. Security Considerations

OLD:

  The nature of this document is such that it does not introduce any
  new security considerations.

NEW:

  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.

-------

Under the IANA Considerations guidance, RFC 3427 needs to be cited; it limits what
status of rfc-to-be can register particular fields.  Also, now worth adding mention
of the header parameter and uri parameter registrations RFCs, since you're in there
(3968, 3969).

[Ballot discuss]
Discuss for a few AD Review points and so that comments of a number of ADs/Areas
will be adddressed. 

3.2  SIP Architectural Model
OLD:
      Extensions SHOULD NOT work only under the assumption of a single
      hop or single provider.
NEW:
      Extensions MUST NOT work only under the assumption of a single
      hop or single provider.

-------

6. Security Considerations

OLD:

  The nature of this document is such that it does not introduce any
  new security considerations.

NEW:

  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.

-------

Under the IANA Considerations guidance, RFC 3427 needs to be cited; it limits what
status of rfc-to-be can register particular fields.  Also, now worth adding mention
of the header parameter and uri parameter registrations RFCs, since you're in there
(3968, 3969).

[Ballot comment]
  Compression of SIP messages SHOULD be
  handled at lower layers, for example, using IP payload compression
  [16] or signalling compression [18]

Reference 16 should be to RFC 3173, rather than 2393, which is
obsolete.

-----

Under 4.7, it's good that the discussion of the overview section is there.  Could you
add guidance that authors should be sure to expand even the most familiar terms such
as UA on first occurrence, and treat the overview section as providing context to non-SIP
experts?

[Ballot discuss]
Discuss so that comments of a number of ADs can be addressed. 

Here are the ones from me:

3.2  SIP Architectural Model
OLD:
      Extensions SHOULD NOT work only under the assumption of a single
      hop or single provider.
NEW:
      Extensions MUST NOT work only under the assumption of a single
      hop or single provider.

-------

6. Security Considerations

OLD:

  The nature of this document is such that it does not introduce any
  new security considerations.

NEW:

  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.

-------
Minor:
  Compression of SIP messages SHOULD be
  handled at lower layers, for example, using IP payload compression
  [16] or signalling compression [18]

Reference 16 should be to RFC 3173, rather than 2393, which is
obsolete.

And a couple more:

Under the IANA Considerations guidance, RFC 3427 needs to be cited; it limits what
status of rfc-to-be can register particular fields.  Also, now worth adding mention
of the header parameter and uri parameter registrations rfcs (I realize this document
could go on forever...)

Under 4.7, it's good that the discussion of the overview section is there.  Could you
add guidance that authors should be sure to expand even the most familiar terms such
as UA on first occurrence, and treat the overview section as providing context to non-SIP
experts?

[Ballot comment]
Reviewed by Spencer Dawkins, Gen-ART

Full review in document comments; there are some issues that should be addressed (in particular, the comment about "compact form" headers) if the document is respun for other reasons.

But no show-stoppers.

Review by Spencer Dawkins, Gen-ART:

This draft is definitely on the right track for Informational,
and is definitely helpful and useful. It's been kicking around
the SIP working group since mid-2000, and should be published
Real Soon.

I think I found a couple of sentences that hadn't been looked at
closely, so I do have questions, but I believe most/all of these
are addressable in AUTH48 (probably less than 100 bytes of
edits).

Spencer

3.  Should I define a SIP Extension?

  While the first criteria might seem obvious, we have observed that
  numerous extensions to SIP have been proposed because some function
  is needed in a device which also speaks SIP.  The argument is
  generally given that "I'd rather implement one protocol than many".
  As an example, user agents, like all other IP hosts, need
  some way to obtain their IP address.  This is generally done through
  DHCP [9]. SIP's multicast registration mechanisms might supply an
  alternate way to obtain an IP address.  This would eliminate the need
  for DHCP in clients.  However, we do not believe such extensions are
  appropriate. We believe that protocols should be defined to provide
  specific, narrow functions, rather than being defined based on all
  protocols needed between a pair of devices.  The latter approach to
  protocol design yields modular protocols with broad application.  It
  also

Spencer: I'm almost sure that you intended to say "the FORMER
approach"?

  facilitates extensibility and growth; single protocols can be removed
  and changed without affecting the entire system.  We observe that this
  approach to protocol engineering mirrors object oriented software
  engineering.

3.2  SIP Architectural Model

    SIP and Session Path Independence: We have already touched on this
    once, but it is worth noting again.  The set of routers and/or
    networks and/or autonomous systems traversed by SIP messages are
    unrelated to the set of routers and/or networks and/or autonomous
    systems traversed by session packets.  They may be the same in some
    cases, but it is fundamental to SIP's architecture that they need not
    be the same.  Extensions which only work under some assumption of
    overlap are not generally applicable to SIP's operation and should be
    scrutinized carefully.

Spencer: I may be misunderstanding, but - why does this sentence
not end with "not generally applicable to SIP's operation"?
("How carefully must I scrutinize if the answer is going to be
NO?")

4.1  Backwards Compatibility

    In order to achieve backwards compatibility for extensions that define
    new methods, the Allow header field is used.  There are two types of
    new methods - those that are used for established dialogs (initiated
    by INVITE, for example), and those that are sent as the initial
    request to a UA.  Since INVITE and its response both SHOULD contain an
    Allow header field, a UA can readily determine whether the new method
    can be supported within the dialog.  For example, once an INVITE
    dialog is established, a user agent could determine if the REFER
    method [10] is supported if it is present in an Allow header. If it
    was, the "transfer" button on the UI could be "greyed out" once the
    call is established.

Spencer: I may be confused, but wouldn't you "grey out" the
"transfer" button if REFER is NOT present in Allow?

4.4  Syntactic Issues

    Extensions that define new methods SHOULD use all capitals
    for the method name.  Method names SHOULD be less than 10 characters,
    and SHOULD attempt to convey the general meaning of the request.
    Method names are case sensitive, and therefore there is no
    requirement that they be capitalized.  However, using
    capitalized method names keeps with a long-standing convention in SIP
    and manysimilar protocols, such as HTTP [13] and RTSP [14]

Spencer: - not sure why this paragraph is indented?

    Extensions that define new header fields that are anticipated to be
    heavily used SHOULD define a compact form if those header fields are
    more than four characters.  Compact header fields MUST be a single
    character.  When all 26 characters are exhausted, new compact forms

Spencer: wow. This SHOULD seems way off, given the number of
current drafts in the SIP community! Maybe "more than SIX"
characters? Is this guideline semi-universally ignored, or are
we already out of letters? :-)

    will no longer be defined.  Header field names SHOULD be composed
    primarily of ASCII characters and marks.  They SHOULD be descriptive

Spencer: is there a citation reference you can give for "ASCII
characters and marks"? It's not common terminology for me
(sorry).

  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".

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 RECOMMENED

Spencer: s/RECOMMENED/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".

4.12  Additional Considerations for New Body Types

  Because SIP can run over UDP, extensions that specify the inclusion of
    large bodies are frowned upon unless end-to-end congestion controlled
    transport can be guaranteed.  If at all possible, the content SHOULD
    be included indirectly [7] even if congestion controlled transports
    are available.

Spencer: can you give any explicit guidance on "large"?

[Ballot comment]
In Section 3:

  First, the problem SHOULD fit into the general purvey of SIP's
  solution space.

I believe they mean "purview".

In 4.1, the document says:

  Yet another type of extension is that which defines new body types to
  be carried in SIP messages.  According to the SIP specification,
  bodies must be understood in order to process a request.  As such,
  the interoperability issues are similar to new methods.  However, the
  Content-Disposition header field has been defined to allow a client
  or server to indicate that the message body is optional [2].  Usage
  of optional bodies, as opposed to mandatory ones, is RECOMMENDED
  wherever possible.

It might be valuable to highlight "by whom" here, since the text above
notes that proxies should not be required to understand new body types.
I believe that the intent is to say:  when the design allows, use optional
bodies so that end points are not needlessly prevented from participating
in the SIP-arranged session.  This is fine, but a little different from the
world as seen by a proxy.

In section 4.2, it might be useful to highlight the difference between the
security provided by SIP (for its signalling) vs. the security provided by
the protocol being set up.  Conflating the two seems to be a common
problem in this kind of extension, and it might be valuable to capture it here.

In section 4.4, the draft says:

  Extensions which have header fields containing URIs SHOULD allow any
  URI, not just SIP URIs.

It might be valuable to say instead that extensions which have header fields containing
URIs should be explicit about the supported URI schemes, and it should not be
assumed that only SIP URIs are permitted.  There are valid reasons to restrict URI
schemes, and though the SHOULD allows that restriction, it seems to plump
pretty hard for unlimited extensions.  That may be more rope than we want to
hand out.