This JEP defines a protocol for broadcasting and 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 Jabber Software 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.
Status: Draft
Type: Standards Track
Number: 0115
Version: 1.0
Last Updated: 2004-08-01
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, XMPP IM, JEP-0030
Supersedes: None
Superseded By: None
Short Name: caps
Schema: <http://jabber.org/protocol/caps/caps.xsd>
Email: jhildebrand@jabber.com
JID: hildjj@jabber.org
Email: stpeter@jabber.org
JID: stpeter@jabber.org
This Jabber Enhancement Proposal is copyright 1999 - 2004 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.php>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at <http://www.opencontent.org/openpub/>).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core and XMPP IM specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocols defined in this JEP have been developed outside the Internet Standards Process and are to be understood as extensions to XMPP rather than as an evolution, development, or modification of XMPP itself.
The keywords "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.
It is often desirable for a Jabber/XMPP application (commonly but not necessarily a client) to take different actions depending on the capabilities of another application from which it receives presence information. Examples include:
Recently, some existing Jabber clients have begun sending Software Version [3] requests to each entity from which they receive presence. That solution is impractical on a larger scale, particularly for users or applications with large rosters. This JEP proposes a more robust and scalable solution: namely, a presence-based mechanism for exchanging information about entity capabilities. [4]
This JEP makes several assumptions:
The protocol defined herein addresses the following requirements:
Each time a conformant client sends presence, it annotates that presence with an element that specifies the client type, the version of that client, and which feature bundles (if any) are currently enabled. Unless the server optimizations shown later are being used, the client MUST send this with every presence change (except for unavailable presence) to enable existing servers to remember the last presence for use in responding to probes. The client MUST send the 'node' and 'ver' attributes.
In addition, the client MAY send an 'ext' attribute (short for "extensions") if it has one or more feature bundles to advertise. A feature bundle is any non-standard addition or extension to the core application, such as a client plugin. If more than one feature bundle is advertised, the value of the 'ext' attribute MUST be a space-separated list of bundle names. [11] The client MUST NOT send an 'ext' attribute if there are no interesting non-core features enabled. The names of the feature bundles MUST NOT be used for semantic purposes: they are merely identifiers that will be used in other use cases. If a feature bundle changes in any way (e.g., a user installs an updated version of a client plugin), the application MUST change the bundle name.
The values of the 'node', 'ver', and 'ext' attributes MUST NOT contain the '#' character, since that character is used as a separator in the Discovering Capabilities use case.
Example 1. Annotated presence sent
<presence>
<c xmlns='http://jabber.org/protocol/caps'
node='http://exodus.jabberstudio.org/caps'
ver='0.9'/>
</presence>
Example 2. Annotated presence sent, with feature extensions
<presence>
<c xmlns='http://jabber.org/protocol/caps'
node='http://exodus.jabberstudio.org/caps'
ver='0.9'
ext='tins ftrans xhtml'/>
</presence>
Once someone on my roster knows what client I am using, they need to be able to figure out what features are supported by that client. The client that received the annotated presence sends a disco#info request (as defined in JEP-0030: Service Discovery) to exactly one of the users that sent a particular combination of node and ver. If the requestor has received the same annotation from multiple JIDs, the requestor SHOULD pick a random JID from that list to which the requestor will send the disco#info request.
The disco#info request is sent to a JID + node combination that consists of the chosen <user@host/resource> JID and a service discovery node that is constructed as follows: concatenate (1) the value of the caps 'node' attribute, (2) the "#" character, and (3) the version number specified in the caps 'ver' attribute.
Example 3. Disco#info request for client#version
<iq type='get' to='randomuser1@capulet.com/resource'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://exodus.jabberstudio.org/caps#0.9'/>
</iq>
Subsequent requests MAY be made to determine the info for each extension. These requests MUST be sent to a random <user@host/resource> JID that sent a caps annotation that included a particular node/ext combination. The disco#info request shall be sent to a JID + node combination that consists of the chosen JID and a service discovery node that is constructed as follows: concatenate (1) the value of the caps 'node' attribute, (2) the "#" character, and (3) the extension name specified by one of the space-separated names in the caps 'ext' attribute. The requestor SHOULD try to use different JIDs for each of these requests, as well as for the first request.
Example 4. Disco#info requests for client#extension
<iq type='get' to='randomuser2@capulet.com/resource'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://exodus.jabberstudio.org/caps#tins'/>
</iq>
<iq type='get' to='randomuser3@capulet.com/resource'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://exodus.jabberstudio.org/caps#ftrans'/>
</iq>
<iq type='get' to='randomuser4@capulet.com/resource'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://exodus.jabberstudio.org/caps#xhtml'/>
</iq>
All of the responses to the disco#info queries SHOULD be cached. If a particular entity cannot store the responses, it SHOULD NOT make the requests. An entity SHOULD NOT make the service discovery requests unless the information is required for some local functionality. An entity MUST NOT ever make a request to another entity that has the same version of the same application as the requesting entity, except for extensions that are not supported by the requestor's installation (e.g., one "Exodus 0.9" client MUST NOT query another "Exodus 0.9" client unless the second client has advertised an extension or plugin that the first client does not have).
If an application sends message to an entity from which it has not received presence, it MAY choose to append a capabilities annotation to only the first message sent to that entity within a particular conversation thread or "session". The application MUST NOT append a capabilities annotation to later messages and MUST NOT send the annotation to entities from which it has received presence. Also, an application MUST NOT send the capabilities annotation to entities which are in a user's roster (or equivalent entity store, as in a gateway) with subscription='both' or subscription='to' (since presence would have been received from these entities if they were online).
Example 5. Message including capabilities
<message to='romeo@example.net'
from='juliet@example.com/balcony'>
<thread>thread1</thread>
<body>Art thou not Romeo, and a Montague?</example>
<c xmlns='http://jabber.org/protocol/caps'
node='http://exodus.jabberstudio.org/caps'
ver='0.9'
ext='xhtml'/>
</message>
If the recipient responds to one of these annotated messages, the first message back in the other direction SHOULD be annotated with capabilities.
Example 6. Response message including capabilities
<message from='romeo@example.net/orchard'
to='juliet@example.com/balcony'>
<thread>thread1</example>
<body>Neither, fair saint, if either thee dislike.</example>
<c xmlns='http://jabber.org/protocol/caps'
node='http://exodus.jabberstudio.org/caps'
ver='0.9'/>
</message>
Alternatively, unsubscribed entities MAY send directed presence to each other, for which the same rules apply as listed above for messages.
A server that is managing an entity's 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 (typically in the 'ext' 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 only send the capabilities annotation on the first presence packet, as well as whenever its capabilities change.
Example 7. Disco#info request for server optimization
<iq from='juliet@capulet.com/balcony'
to='capulet.com'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
<iq from='capulet.com'
to='juliet@capulet.com/balcony'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://jabber.org/protocol/caps'/>
...
</query>
</iq>
If capabilities information has not been received from another entity, an application MUST assume that the other entity does not support capabilities.
No application-specific error codes are defined by this document. See JEP-0030: Service Discovery for a list of potential service discovery error codes.
Use of the protocol specified in this JEP 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 jabber:iq:version requests without performing access control checks, there is no new vulnerability. Entities that wish to restrict access to capabilities information SHOULD use the privacy lists protocol defined in XMPP IM 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").
It is possible (though unlikely) for a bad actor or rogue application to poison other entities by providing incorrect information in response to disco#info requests. To guard against such poisoning, a requesting entity MAY send disco#info requests to multiple entities that match the same node/ver or node/ext combination and then compare the results to ensure consistency. The requesting entity SHOULD NOT send the same request to more than five entities and MUST ensure that the entities are truly different by not sending the same request to multiple entities for which the <user@host> portion matches.
This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA) [13].
Upon advancement of this JEP to a status of Draft, the Jabber Registrar [14] shall add 'http://jabber.org/protocol/caps' to its registries of protocol namespaces and service discovery features.
If it is useful or interesting, the Registrar may also provide registration of the URIs to be used in the 'node' attribute, but since these URIs can be scoped according to well-defined existing rules, this is not necessary.
<?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
JEP-0115: http://www.jabber.org/jeps/jep-0115.html
</xs:documentation>
</xs:annotation>
<xs:element name='c'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='ext' type='xs:string' use='optional'/>
<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>
1. JEP-0071: XHTML-IM <http://www.jabber.org/jeps/jep-0071.html>.
2. JEP-0096: File Transfer <http://www.jabber.org/jeps/jep-0096.html>.
3. JEP-0092: Software Version <http://www.jabber.org/jeps/jep-0092.html>.
4. This proposal is not limited to clients, and could be used by any entity that exchanges presence with another entity, e.g., a gateway. However, this JEP uses the example of clients throughout.
5. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.
6. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://www.ietf.org/rfc/rfc3921.txt>.
7. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.
8. These first two requirements effectively eliminated Publish-Subscribe [9] as a possible implementation of entity capabilities.
9. JEP-0060: Publish-Subscribe <http://www.jabber.org/jeps/jep-0060.html>.
10. JEP-0045: Multi-User Chat <http://www.jabber.org/jeps/jep-0045.html>.
11. While it might be objected that a space-separated list is not structured data, space-separated lists of attribute values are recommended by XML 1.0 [12].
12. Extensible Markup Language (XML) 1.0 (Third Edition) <http://www.w3.org/TR/REC-xml/>.
13. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
14. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.
END