XEP-0115: Entity Capabilities

This document defines an XMPP protocol extension for broadcasting and dynamically discovering client, device, or generic entity capabilities in a way that minimizes network impact.

NOTICE: The protocol defined herein is a Draft Standard of the XMPP Standards Foundation. Implementations are encouraged and the protocol is appropriate for deployment in production systems, but some changes to the protocol are possible before it becomes a Final Standard.

Document Information

Series: XEP
Number: 0115
Publisher: XMPP Standards Foundation
Status: Draft
Type: Standards Track
Version: 1.4
Last Updated: 2007-08-13
Approving Body: XMPP Council
Dependencies: XMPP Core, XMPP IM, XEP-0030
Supersedes: None
Superseded By: None
Short Name: caps
Schema: <http://www.xmpp.org/schemas/caps.xsd>
Wiki Page: <http://wiki.jabber.org/index.php/Entity Capabilities (XEP-0115)>

Author Information

Legal Notice

This XMPP Extension Protocol is copyright 1999 - 2007 by the XMPP Standards Foundation (XSF) and is in full conformance with the XSF's Intellectual Property Rights Policy <http://www.xmpp.org/extensions/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards discussion list: <http://mail.jabber.org/mailman/listinfo/standards>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

The following keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Table of Contents

1. Introduction

<presence from='romeo@montague.lit/orchard'>
  <c xmlns='http://jabber.org/protocol/caps' 
     node='http://exodus.jabberstudio.org/#0.9.1'
     ver='8RovUdtOmiAjzj+xI7SK5BCw3A8='/>
</presence>
      

<iq from='juliet@capulet.lit/chamber' 
    id='disco1'
    to='romeo@montague.lit/orchard' 
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
      

<iq from='romeo@montague.lit/orchard' 
    id='disco1'
    to='juliet@capulet.lit/chamber' 
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity category='client' type='pc'/>
    <feature var='http://jabber.org/protocol/disco#info'/>
    <feature var='http://jabber.org/protocol/disco#items'/>
    <feature var='http://jabber.org/protocol/muc'/>
  </query>
</iq>
      

<presence from='benvolio@capulet.lit/230193'>
  <c xmlns='http://jabber.org/protocol/caps' 
     node='http://psi-im.org/#0.11'
     ver='8RovUdtOmiAjzj+xI7SK5BCw3A8='/>
</presence>
      

<presence from='nurse@capulet.lit/chamber'>
  <c xmlns='http://jabber.org/protocol/caps' 
     node='http://psi-im.org/#0.10'
     ver='uCoVCteRe3ty2wU2gHxkMaA7xhs='/>
</presence>
      

<presence from='bard@shakespeare.lit/globe'>
  <c xmlns='http://jabber.org/protocol/caps' 
     node='http://www.chatopus.com/#2.2'
     ver='zHyEOgxTrkpSdGcQKH8EFPLsriY='/>
</presence>
      

2. Assumptions

This document makes several assumptions:

• The type of client I am using is of interest to the people in my roster.
• Clients for the people on my roster might want to make user interface decisions based on my capabilities.
• Different clients may support the same capabilities.
• Members of a community tend to cluster around a small set of clients with a small set of capabilities. More specifically, multiple people in my roster use the same client, and they upgrade versions relatively slowly (commonly a few times a year, perhaps once a week at most, certainly not once a minute).
• Some clients are running against servers without server-to-server connectivity enabled, and without access to the Internet via HTTP.
• Conversations are possible between users who are not on each other's rosters.
• Client capabilities may change over the course of a presence session, due to features being enabled and disabled.

3. Requirements

The protocol defined herein addresses the following requirements:

1. Clients must be able to participate even if they support only XMPP Core [10], XMPP IM [11], and XEP-0030.
2. Clients must be able to participate even if they are on networks without connectivity to other XMPP servers, services offering specialized XMPP extensions, or HTTP servers. [12]
3. Clients must be able to retrieve information without querying each user.
4. Since presence is normally broadcasted to many users, the byte size of the proposed extension must be as small as possible.
5. It must be possible to write a XEP-0045 server implementation that passes the given information along.
6. It must be possible to publish a change in capabilities within a single presence session.
7. Server infrastructure above and beyond that defined in XMPP Core and XMPP IM must not be required for this approach to work, although additional server infrastructure may be used for optimization purposes.

4. Protocol

Entity capabilities are encapsulated in a <c/> element qualified by the 'http://jabber.org/protocol/caps' namespace. The attributes of the <c/> element are as follows.

Table 1: Attributes

5. Generation of ver Attribute

In order to help prevent poisoning of entity capabilities information, the value of the 'ver' attribute 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 RFC 4790 [16].

1. Initialize an empty string S.
2. Sort the service discovery identities by category and then by type (if it exists), formatted as 'category' '/' 'type'.
3. For each identity, append the 'category/type' to S, followed by the '<' character.
4. Sort the supported features.
5. For each feature, append the feature to S, followed by the '<' character.
6. Compute ver by hashing S using the SHA-1 algorithm as specified in RFC 3174 [17] (with binary output) and encoding the hash using Base64 as specified in Section 4 of RFC 4648 [18] (note: the Base64 output MUST NOT include whitespace and MUST set padding bits to zero). [19]

For example, consider an entity whose service discovery category is "client", whose service discovery type is "pc", and whose supported features are "http://jabber.org/protocol/disco#info", "http://jabber.org/protocol/disco#items", and "http://jabber.org/protocol/muc". The value of the 'ver' attribute would be generated as follows:

1. S = ''
2. Only one identity: "client/pc"
3. S = 'client/pc<'
4. Sort the features: "http://jabber.org/protocol/disco#info", "http://jabber.org/protocol/disco#items", "http://jabber.org/protocol/muc".
5. S = 'client/pc<http://jabber.org/protocol/disco#info<http://jabber.org/protocol/disco#items<http://jabber.org/protocol/muc<'
6. ver = 8RovUdtOmiAjzj+xI7SK5BCw3A8=

6. Use Cases

<presence>
  <c xmlns='http://jabber.org/protocol/caps'
     node='http://exodus.jabberstudio.org/#0.9.1'
     ver='8RovUdtOmiAjzj+xI7SK5BCw3A8='/>
</presence>
      

<iq from='juliet@capulet.lit/balcony' 
    id='disco1'
    to='romeo@montague.lit/orchard' 
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
      

<iq from='romeo@montague.lit/orchard' 
    id='disco1'
    to='juliet@capulet.lit/balcony' 
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
    <identity category='client' type='pc'/>
    <feature var='http://jabber.org/protocol/disco#info'/>
    <feature var='http://jabber.org/protocol/disco#items'/>
    <feature var='http://jabber.org/protocol/muc'/>
  </query>
</iq>
      

<stream:features>
  <c xmlns='http://jabber.org/protocol/caps'
     node='http://jabberd.org/entity'
     ver='ItBTI0XLDFvVxZ72NQElAzKS9sU='>
</stream:features>
      

7. Server Optimizations

A server that is managing an entity's presence session MAY choose to optimize traffic through the server. In this case, the server MAY strip off redundant capabilities annotations. Because of this, receivers of annotations MUST NOT expect an annotation on every presence packet they receive. If the server wants to perform this traffic optimization, it MUST ensure that the first presence each subscriber receives contains the annotation. The server MUST also ensure that any changes in the annotation (e.g., an updated 'ver' attribute)(e.g., an updated 'ver' attribute) are sent to all subscribers.

A client MAY query the server using disco#info to determine if the server supports the 'http://jabber.org/protocol/caps' feature. If so, the server MUST perform the optimization delineated above, and the client MAY choose to send the capabilities annotation only on the first presence packet, as well as whenever its capabilities change.

Example 5. Disco#info request for server optimization

<iq from='juliet@capulet.lit/balcony'
    to='capulet.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

<iq from='capulet.lit'
    to='juliet@capulet.lit/balcony'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='http://jabber.org/protocol/caps'/>
    ...
  </query>
</iq>
    

8. Directed Presence

If two entities exchange messages but they do not normally exchange presence (i.e., via presence subscription), the entities MAY choose to send directed presence to each other, where the presence information SHOULD be annotated with the same capabilities information as each entity sends in broadcasted presence. If capabilities information has not been received from another entity, an application MUST assume that the other entity does not support capabilities.

9. Caching

An application that accepts entity capabilities information SHOULD cache associations between the 'ver' attribute and discovered features within the scope of one presence session and MAY cache such associations across sessions. This obviates the need for extensive service discovery requests within a session or at the beginning of a session.

10. Security Considerations

Use of the protocol specified in this document might make some client-specific forms of attack slightly easier, since the attacker could more easily determine the type of client being used. However, since most clients respond to Service Discoery and Software Version requests without performing access control checks, there is no new vulnerability. Entities that wish to restrict access to capabilities information SHOULD use Server-Based Privacy Rules [20] to define appropriate communications blocking (e.g., an entity MAY choose to allow IQ requests only from "trusted" entities, such as those with whom it has a subscription of "both").

Adherence to the algorithm defined in the Generation of ver Attribute section of this document for both generation and checking of the 'ver' attribute helps to guard against poisoning of entity capabilities information by malicious or improperly implemented entities.

11. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [21].

12. XMPP Registrar Considerations

13. XML Schema

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/caps'
    xmlns='http://jabber.org/protocol/caps'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0115: http://www.xmpp.org/extensions/xep-0115.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='c'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='ext' type='xs:NMTOKENS' use='optional'/>
          <xs:attribute name='hash' type='xs:NMTOKEN' use='optional' default='sha-1'/>
          <xs:attribute name='node' type='xs:string' use='required'/>
          <xs:attribute name='ver' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
    

14. Legacy Format

Before Version 1.4 of this specification, the 'ver' attribute was generated differently and the 'ext' attribute was used more extensively. For historical purposes, Version 1.3 of this specification is archived at <http://www.xmpp.org/extensions/attic/xep-0115-1.3.html>. For backward-compatibility with the legacy format, the 'node' attribute is REQUIRED and the 'ext' attribute MAY be included.

15. Acknowledgements

Thanks to Rachel Blackman, Dave Cridland, Richard Dobson, Sergei Golovan, Justin Karneges, Jacek Konieczny, Ian Paterson, Kevin Smith, Tomasz Sterna, and Michal Vaner for comments and suggestions.

Notes

Revision History

END