A Shorthand Notation and Header Field for Device Capabilities in the Session Initiation Protocol (SIP)
draft-hildebrand-sip-caps-00

Status of this Memo

This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on August 30, 2009.

Copyright Notice

Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document.

Abstract

This document defines a shorthand notation for device capabilities data that is advertised using the format specified in RFC 3840. The approach taken here is to define (1) a method for transforming any existing SIP capability into a Uniform Resource Name (URN) located in a new branch of the IETF URN tree, (2) an algorithm for canonical ordering, concatenation, and hashing of the URN-transformed capabilities, and (3) a header field for communicating the resulting hash.

Table of Contents

1.  Introduction
2.  URN Transformation
3.  Generation Algorithm
4.  Definition of the Caps Header Field
5.  Processing
6.  Example
7.  IANA Considerations
    7.1.  Caps Header Field
    7.2.  URN Namespace Name for SIP Capabilities
8.  Security Considerations
9.  References
    9.1.  Normative References
    9.2.  Informative References
§  Authors' Addresses

1.  Introduction

Entities that implement the Session Initiation Protocol [SIP] (Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, “SIP: Session Initiation Protocol,” June 2002.) can provide information about their capabilities using the SIP OPTIONS method as well as the format defined in [RFC3840] (Rosenberg, J., Schulzrinne, H., and P. Kyzivat, “Indicating User Agent Capabilities in the Session Initiation Protocol (SIP),” August 2004.). Because full capabilities information can become verbose and is frequently duplicated across entities (e.g., user agents that deploy identical software versions), there is value in defining a "shorthand" notation for capabilities data. This document defines such a shorthand notation. The approach taken here is to define the following:

1. A method for transforming any existing SIP capability into a Uniform Resource Name [URN] (Moats, R., “URN Syntax,” May 1997.).
2. An algorithm for canonical ordering, concatenation, and hashing of the URN-transformed capabilities.
3. A header field for communicating the resulting hash.

To help ensure interoperability, this shorthand notation is compatible with the shorthand notation currently used by Extensible Messaging and Presence Protocol [XMPP] (Saint-Andre, P., Ed., “Extensible Messaging and Presence Protocol (XMPP): Core,” October 2004.) technologies and defined in [XEP‑0115] (Hildebrand, J., Saint-Andre, P., Tronçon, R., and J. Konieczny, “Entity Capabilities,” February 2008.).

Note: The capitalized key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [TERMS].

2.  URN Transformation

The caps-generation algorithm requires consistent input formats, preferably Uniform Resource Names (URNs) or Uniform Resource Identifiers (URIs). We propose a new branch of the IETF URN tree for input to the caps-generation algorithm, where each SIP feature shall be of the following form:

urn:ietf:params:xml:ns:sip-feature:[tag]:[value]

Each feature tag shall be constructed according to the rules in [RFC3840] (Rosenberg, J., Schulzrinne, H., and P. Kyzivat, “Indicating User Agent Capabilities in the Session Initiation Protocol (SIP),” August 2004.).

Each feature value shall be constructed according to the rules in [RFC3840] (Rosenberg, J., Schulzrinne, H., and P. Kyzivat, “Indicating User Agent Capabilities in the Session Initiation Protocol (SIP),” August 2004.), with the following exceptions:

1. If the term of the conjunction is a disjunction, the value of the contact parameter is a quoted string, where the quoted string is a comma separated list of strings, each one derived from one of the terms in the disjunction. However, instead of converting the quote characters containing quoted strings to the less-than sign "<" and greater-than sign ">" as in [RFC3840] (Rosenberg, J., Schulzrinne, H., and P. Kyzivat, “Indicating User Agent Capabilities in the Session Initiation Protocol (SIP),” August 2004.), each entity from the comma-separated string shall be encapsulated as a separate URN. As an example, the feature value sip.description="PC, MyClient" shall be transformed into two URNs: "urn:ietf:params:xml:ns:sip-feature:description:PC" and "urn:ietf:params:xml:ns:sip-feature:description:MyClient".
2. Filters shall not be converted, since a conversion algorithm for filters has not yet been defined in this specification. (A future version of this specification might define such a transformation.)

As an example, consider the feature predicate shown in [RFC3840] (Rosenberg, J., Schulzrinne, H., and P. Kyzivat, “Indicating User Agent Capabilities in the Session Initiation Protocol (SIP),” August 2004.):

(& (sip.mobility=fixed)
   (| (! (sip.events=presence)) (sip.events=message-summary))
   (| (language=en) (language=de))
   (sip.description="PC")
   (sip.newparam=TRUE)
   (rangeparam=-4..5125/1000))

That feature predicate would be converted to the following URNs:

urn:ietf:params:xml:ns:sip-feature:mobility:fixed
urn:ietf:params:xml:ns:sip-feature:events:presence
urn:ietf:params:xml:ns:sip-feature:events:message-summary
urn:ietf:params:xml:ns:sip-feature:language:en
urn:ietf:params:xml:ns:sip-feature:language:de
urn:ietf:params:xml:ns:sip-feature:description:PC
urn:ietf:params:xml:ns:sip-feature:+sip.newparam
urn:ietf:params:xml:ns:sip-feature:+rangeparam:-4:+5.125

3.  Generation Algorithm

The value of the caps hash MUST be generated according to the following method.

Note: All sorting operations MUST be performed using "i;octet" collation as specified in Section 9.3 of [RFC4790] (Newman, C., Duerst, M., and A. Gulbrandsen, “Internet Application Protocol Collation Registry,” March 2007.).

1. Initialize an empty string S.
2. Generate one or more "identities" for the entity, where each identity formed of a string CATEGORY '/' [TYPE] '/' [LANG] '/' [NAME]. For user agents the CATEGORY shall be "client", the TYPE shall be "sip", the LANG shall be the value of the Accept-Language SIP header [SIP] (Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, “SIP: Session Initiation Protocol,” June 2002.) if typically included by the entity, and the NAME shall be the value of the User Agent SIP header [SIP] (Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, “SIP: Session Initiation Protocol,” June 2002.) if typically provided by the entity. If any of these fields is unknown, the value of the field MUST elided but the '/' separator MUST be included; as an example, for a user agent with User-Agent header value of "SIP Communicator 1.0" but no Accept-Language header value, the identity would be "client/sip//SIP Communicator 1.0".
3. For each identity (if there are multiple identities, e.g., because the entity advertises support for multiple languages), append the 'category/type/lang/name' to S, followed by the '<' character.
4. Sort the supported capabilities (where each capability is formed using the transformation method described under Section 2 (URN Transformation)).
5. For each capability, append the capability to S, followed by the '<' character.
6. Ensure that S is encoded according to the UTF-8 encoding as specified in [RFC3269] (Kermode, R. and L. Vicisano, “Author Guidelines for Reliable Multicast Transport (RMT) Building Blocks and Protocol Instantiation documents,” April 2002.).
7. Compute the verification string by hashing S using the desired hashing algorithm (e.g., SHA-1 as defined in [RFC3174] (Eastlake, D. and P. Jones, “US Secure Hash Algorithm 1 (SHA1),” September 2001.). The hashed data MUST be generated with binary output and encoded using Base64 as specified in Section 4 of [RFC4648] (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.) (note: the Base64 output MUST NOT include whitespace and MUST set padding bits to zero). For reference, the OpenSSL command for producing such output with SHA-1 is "echo -n 'S' | openssl dgst -binary -sha1 | openssl enc -nopad -base64".

4.  Definition of the Caps Header Field

The following is the augmented Backus-Naur Form (BNF) [RFC5234] (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.) syntax of the Caps header field. The hash-func element is defined in [RFC4572] (Lennox, J., “Connection-Oriented Media Transport over the Transport Layer Security (TLS) Protocol in the Session Description Protocol (SDP),” July 2006.).

   caps      = hash-func " " ver
   ver       = 1*(hash-out)
   hash-out  = ALPHA / DIGIT / "/" / "+" / "="

5.  Processing

When an entity receives a Caps header, it SHOULD proceed as follows.

1. If the value of the hash-func portion of the Caps header does not match one of the processing application's supported hash functions, do the following:
   1. Send a SIP OPTIONS request to the generating entity.
   2. Receive SIP OPTIONS response from the generating entity.
   3. Do not validate or globally cache the Caps header as described below; instead, the processing application SHOULD associate the discovered capabilities only with the SIP address of the generating entity.
2. If the value of the hash-func portion of the Caps header matches one of the processing application's supported hash functions, validate the value string by doing the following:
   • Send a SIP OPTIONS request to the generating entity.
   • Receive a SIP OPTIONS response from the generating entity.
   • If the response includes more than one identity with the same category/type/lang/name, consider the entire response to be ill-formed.
   • If the response includes more than one capability with the same XML character data, consider the entire response to be ill-formed.
   • If the response is considered well-formed, reconstruct the hash by using the OPTIONS response to generate a local hash in accordance with the generation method.
   • If the values of the received and reconstructed hashes match, the processing application MUST consider the result to be valid and SHOULD globally cache the result for all entities with which it communicates.
   • If the values of the received and reconstructed hashes do not match, the processing application MUST consider the result to be invalid and MUST NOT globally cache the value of the Caps header; however, it MAY send a SIP OPTIONS request to another generating entity who advertises that same value for the Caps header.

6.  Example

Consider a user agent that advertises an Accept-Language header value of "en", a User-Agent header value of "SIP Communicator 1.0", and capabilities of sip.mobility=fixed, sip.events=presence, sip.events=message-summary, language=en, sip.description="PC", sip.newparam=TRUE, and rangeparam=-4..5125/1000.

The output string "S" would be as follows (line breaks are not significant):

client/sip/en/SIP Communicator 1.0<
urn:ietf:params:xml:ns:sip-feature:mobility:fixed<
urn:ietf:params:xml:ns:sip-feature:events:presence<
urn:ietf:params:xml:ns:sip-feature:events:message-summary<
urn:ietf:params:xml:ns:sip-feature:language:en<
urn:ietf:params:xml:ns:sip-feature:description:PC<
urn:ietf:params:xml:ns:sip-feature:+sip.newparam<
urn:ietf:params:xml:ns:sip-feature:+rangeparam:-4:+5.125<

When hashed in accordance with SHA-1, the output string would then result in the following verification string.

x6Ra/0PZmzlFToQ7z6rPBTJ1QRA=

The resulting Caps header value would then be as follows.

Caps: sha-1 x6Ra/0PZmzlFToQ7z6rPBTJ1QRA=

This Caps header could be included in any outbound SIP response or notification that an entity generates, such as a SIP 200 OK or (as shown in the following example) a presence notification.

   NOTIFY sip:192.0.2.2 SIP/2.0
   Via: SIP/2.0/TCP x2s.example.com;branch=z9hG4bKna998sk
   From: <sip:juliet@example.com>;tag=gh19
   To: <sip:romeo@example.net>;tag=yt66
   Call-ID: j4s0h4vny@example.com
   Event: presence
   Subscription-State: active;expires=599
   Max-Forwards: 70
   CSeq: 157 NOTIFY
   Contact: <sip:sipgate.example.com;transport=tcp>
   User-Agent: SIP Communicator 1.0
   Caps: sha-1 x6Ra/0PZmzlFToQ7z6rPBTJ1QRA=
   Content-Type: application/pidf+xml
   Content-Length: 192

   <?xml version='1.0' encoding='UTF-8'?>
   <presence xmlns='urn:ietf:params:xml:ns:pidf'
             entity='pres:juliet@example.com'>
     <tuple id='balcony'>
       <status>
         <basic>open</basic>
       </status>
     </tuple>
   </presence>

As described, an entity that receives a SIP message with a Caps header can then send an OPTIONS request to the generating entity.

   OPTIONS sip:juliet@example.com SIP/2.0
   Via: SIP/2.0/TCP x2s.example.net;branch=z9hG4bKna998sk
   From: <sip:romeo@example.net>;tag=ffd2
   To: <sip:juliet@example.com>
   Call-ID: l04th3s1p@example.net
   Max-Forwards: 70
   CSeq: 63104 OPTIONS
   Contact: <sip:sip.example.net;transport=tcp>
   Accept: application/sdp
   Content-Length: 0

The generating entity would then reply.

   SIP/2.0 200 OK
   Via: SIP/2.0/TCP foo.example.com;branch=z9hG4bKna998sk
        ;received=192.0.2.4
   From: <sip:juliet@example.com>;tag=gh19
   To: <sip:romeo@example.net>;tag=ffd2
   Call-ID: l04th3s1p@example.net
   CSeq: 63104 OPTIONS
   Contact: <sip:juliet@example.com>
     ;mobility="fixed";events="!presence,message-summary"
     ;language="en";description="<PC>";+sip.newparam
     ;+rangeparam="#-4:+5.125"
   User-Agent: SIP Communicator 1.0
   Allow: INVITE, ACK, CANCEL, OPTIONS, BYE
   Accept: application/sdp
   Accept-Encoding: gzip
   Accept-Language: en
   Caps: sha-1 x6Ra/0PZmzlFToQ7z6rPBTJ1QRA=

The processing entity would then construct a capabilities hash from the capabilities communicated by the generating entity and check that the hashes match.

7.  IANA Considerations

7.1.  Caps Header Field

IANA shall add the following new SIP header field to the Header Fields subregistry under the SIP Parameters registry.

Header Name:

Caps

Compact Form:

(none)

Reference:

<THIS DOCUMENT>

7.2.  URN Namespace Name for SIP Capabilities

A URN sub-namespace for transformed capabitlies is defined as follows. (This namespace name adheres to the format defined in [XML‑REG] (Mealling, M., “The IETF XML Registry,” January 2004.).)

URI:

urn:ietf:params:xml:ns:sip-feature

Specification:

<THIS DOCUMENT>

Description:

This is the XML namespace name for transformations of SIP capabilities, where the tag name and value for each capability is of the form "urn:ietf:params:xml:ns:sip-feature:[tag]:[value]".

Registrant Contact:

IETF, SIP Working Group, <sip@ietf.org>

8.  Security Considerations

Absent signing of the full SIP message (including headers), both the Caps header and the OPTIONS reply could be modified in transit.

9.  References

9.1. Normative References

9.2. Informative References

Authors' Addresses