%ents; Note: If the four characters '&', 'l', 't', ';' appear consecutively in any of the factors of the verification string S (e.g., a service discovery identity of 'SomeClient<http://jabber.org/protocol/muc') then that string of characters MUST be treated as literally '<' and MUST NOT be converted to the character '<', because completing such a conversion would open the protocol to trivial attacks.
"> ]>fix complex generation example by adding missing form field type
Added registrar consideration about stream features.
In response to persistent security concerns over caps poisoning, redefined ver attribute to be a hash of the service discovery identity and features in a way that is backwards-compatible with the legacy format.
Added developer-friendly introduction; specified that ext names must be stable across application versions; further clarified examples; added stream feature use case; removed message example (send directed presence instead).
Clarified motivation and handling of service discovery requests.
Clarified meaning of service discovery results for client#ver and client#ext.
Per a vote of the Jabber Council, advanced status to Draft.
Added several items to the Security Considerations; clarified naming requirements regarding 'node', 'ver', and 'ext' attributes.
Made a number of editorial adjustments.
Specified that the protocol can be used whenever presence is used (e.g., by gateways); improved the XML schema; made several editorial adjustments.
IQ eets must be to a resource, since they are intended to go to a particular session.
Servers MUST strip extras changed to MAY, due to implementer feedback.
Add more clarifying assumptions and requirements, make it clear that clients don't have to send capabilities every time if the server is optimizing.
Initial version.
It is often desirable for an 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:
In the past, after logging in some Jabber clients sent one &xep0030; and one &xep0092; request to each entity from which they received presence. That "disco/version flood" resulted in an excessive use of bandwidth and was impractical on a larger scale, particularly for users with large rosters. Therefore this document defines a more robust and scalable solution: namely, a presence-based mechanism
This section provides a friendly introduction to entity capabilities ("caps").
Imagine that you are a Shakespearean character named Juliet and one of your contacts, a handsome fellow named Romeo, becomes available. His client wants to publish its capabilities, and does this by adding to its presence packets a <c/> element with special attributes. As a result, your client receives the following presence packet:
]]>
The 'node' attribute represents the client software Romeo is using. The 'ver' attribute is a specially-constructed string (called a "verification string") that represents the entity's service discovery identity (category and type as registered at &DISCOCATEGORIES;, as well as, optionally, xml:lang and name) and supported features (as registered at &DISCOFEATURES; as well as, optionally, extended service discovery information data registered at &FORMTYPES;).
At this point, your client has no idea what the capabilities are of someone with a verification string 'QgayPKawpkPSDYmwT/WM94uAlu0='. Your client therefore sends a service discovery query to Romeo, asking what his client can do.
]]>
The response is:
]]>
At this point, your client knows that a contact who advertises a verification string of 'QgayPKawpkPSDYmwT/WM94uAlu0=' supports &xep0045; and the other features returned by Romeo because the contact in fact uses the same version of the same client software as Romeo, with the same enabled features, plugins, presented client name(s), and the like (i.e., the same input to the verification string generation method).
]]>
Therefore you know that she also supports the same features that Romeo does.
On the other hand, for a person with the following presence ...
]]>
... or the following presence ...
]]>
... you have no information about what this contact's client is capable of unless you have cached previous entity capabilities information; therefore you need to query for capabilities explicitly again via service discovery.
This document makes several assumptions:
The protocol defined herein addresses the following requirements:
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.
Name | Definition | Inclusion |
---|---|---|
ext | A set of nametokens specifying additional feature bundles; this attribute is deprecated (see the Legacy Format section of this document). | DEPRECATED |
hash | The hashing algorithm used to generate the verification string; see Mandatory-to-Implement Technologies regarding supported hashing algorithms. | REQUIRED |
node | A URI that uniquely identifies a software application, typically a URL at the website of the project or company that produces the software. * | REQUIRED |
ver | A string that is used to verify the identity and supported features of the entity. ** | REQUIRED |
* Note: It is RECOMMENDED for the value of the 'node' attribute to be an HTTP URL at which a user could find further information about the software product, such as "http://psi-im.org" for the Psi client; this enables a processing application to also determine a unique string for the generating application, which it could maintain in a list of known software implementations (e.g., associating the name received via the disco#info reply with the URL found in the caps data).
** Note: Before version 1.4 of this specification, the 'ver' attribute was used to specify the released version of the software; while the values of the 'ver' attribute that result from use of the algorithm specified herein are backwards-compatible, applications SHOULD appropriately handle the Legacy Format.
In order to help prevent poisoning of entity capabilities information, the value of the verification string 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;.
Consider an entity whose category is "client", whose service discovery type is "pc", whose service discovery name is "Exodus 0.9.1", and whose supported features are "http://jabber.org/protocol/disco#info", "http://jabber.org/protocol/disco#items", and "http://jabber.org/protocol/muc". Using the SHA-1 algorithm, the verification string would be generated as follows (note: line breaks in the verification string are included only for the purposes of readability):
S = ''
Only one identity: "client/pc"
S = 'client/pc//Exodus 0.9.1<'
Sort the features: "http://jabber.org/protocol/caps", "http://jabber.org/protocol/disco#info", "http://jabber.org/protocol/disco#items", "http://jabber.org/protocol/muc".
S = 'client/pc//Exodus 0.9.1<http://jabber.org/protocol/caps<http://jabber.org/protocol/disco#info<
http://jabber.org/protocol/disco#items<http://jabber.org/protocol/muc<'
ver = QgayPKawpkPSDYmwT/WM94uAlu0=
Consider a more complex example, where the entity includes several identities (with the service discovery name in different languages) as well as extended information formatted according to XEP-0128.
<iq from='benvolio@capulet.lit/230193'
id='disco1'
to='juliet@capulet.lit/chamber'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://psi-im.org#q07IKJEyjvHSyhy//CH0CxmKi8w='>
<identity xml:lang='en' category='client' name='Psi 0.11' type='pc'/>
<identity xml:lang='el' category='client' name='Ψ 0.11' type='pc'/>
<feature var='http://jabber.org/protocol/caps'/>
<feature var='http://jabber.org/protocol/disco#info'/>
<feature var='http://jabber.org/protocol/disco#items'/>
<feature var='http://jabber.org/protocol/muc'/>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:dataforms:softwareinfo</value>
</field>
<field var='ip_version' type='text-multi' >
<value>ipv4</value>
<value>ipv6</value>
</field>
<field var='os'>
<value>Mac</value>
</field>
<field var='os_version'>
<value>10.5.1</value>
</field>
<field var='software'>
<value>Psi</value>
</field>
<field var='software_version'>
<value>0.11</value>
</field>
</x>
</query>
</iq>
Using the SHA-1 algorithm, the verification string would be generated as follows (note: line breaks in the verification string are included only for the purposes of readability):
S = ''
Two identities: "client/pc/Psi" and "client/pc/Ψ"
S = 'client/pc/el/Ψ 0.11<client/pc/en/Psi 0.11<'
Sort the features: "http://jabber.org/protocol/caps", http://jabber.org/protocol/disco#info", "http://jabber.org/protocol/disco#items", "http://jabber.org/protocol/muc".
S = 'client/pc/el/Ψ 0.11<client/pc/en/Psi 0.11<http://jabber.org/protocol/caps<http://jabber.org/protocol/disco#info<
http://jabber.org/protocol/disco#items<http://jabber.org/protocol/muc<'.
Sort the extended service discovery forms by FORM_TYPE (there is only one: "urn:xmpp:dataforms:softwareinfo").
S = 'client/pc/el/Ψ 0.11<client/pc/en/Psi 0.11<http://jabber.org/protocol/caps<http://jabber.org/protocol/disco#info<
http://jabber.org/protocol/disco#items<http://jabber.org/protocol/muc<urn:xmpp:dataforms:softwareinfo<'
Sort the fields by var and append the value(s): "ip_version<ipv4<ipv6", "os<Mac", "os_version<10.5.1", "software<Psi", "software_version<0.11".
S = 'client/pc/el/Ψ 0.11<client/pc/en/Psi 0.11<http://jabber.org/protocol/caps<http://jabber.org/protocol/disco#info<
http://jabber.org/protocol/disco#items<http://jabber.org/protocol/muc<urn:xmpp:dataforms:softwareinfo<
ip_version<ipv4<ipv6<os<Mac<os_version<10.5.1<software<Psi<software_version<0.11<'
ver = q07IKJEyjvHSyhy//CH0CxmKi8w=
When an entity receives a value of the 'ver' attribute that appears to be a verification string generated in accordance with the generation method defined in this specification, it MUST process the 'ver' according to the following method.
Each time a generating entity sends presence, it annotates that presence with an entity identifier ('node' attribute) and identity and feature identifier ('ver' attribute). So that servers can remember the last presence for use in responding to probes, a client SHOULD include entity capabilities with every presence notification it sends.
If the supported features change during a generating entity's presence session (e.g., a user installs an updated version of a client plugin), the application MUST recompute the verification string and SHOULD send a new presence broadcast.
An application (the "requesting entity") can learn what features another entity supports by sending a disco#info request (see XEP-0030) to the entity that generated the caps information (the "generating entity").
The disco#info request is sent by the requesting entity to the generating entity. The value of the 'to' attribute MUST be the exact JID of the generating entity, which in the case of a client will be the full JID &LOCALFULL;.
Note: The generating entity SHOULD NOT include the "caps node" in the list of entities it returns in its disco#items responses; i.e., the caps node is a kind of virtual or phantom node, not a true items node that is associated with the generating entity for service discovery purposes.
The disco 'node' attribute MUST be included for backwards-compatibility. The value of the 'node' attribute SHOULD be generated by concatenating the value of the caps 'node' attribute (e.g., "http://code.google.com/p/exodus") as provided by the generating entity, the "#" character, and the value of the caps 'ver' attribute (e.g., "QgayPKawpkPSDYmwT/WM94uAlu0=") as provided by the generating entity.
The generating entity then returns all of the capabilities it supports.
Note: If the generating entity incorporated multiple identities with different xml:lang values in its verification string, it MUST return all of the identities even if the request specified a particular xml:lang.
A server MAY include its entity capabilities in a stream feature element so that connecting clients and peer servers do not need to send service discovery requests each time they connect.
When a connected client or peer server sends a service discovery information request to determine the entity capabilities of a server that advertises capabilities via the stream feature, the requesting entity MUST send the disco#info request to the server's JID as provided in the 'from' attribute of the response stream header (the 'from' attribute was recommended by &rfc3920; and is required by &rfc6120;). To enable this functionality, a server that advertises support for entity capabilities MUST provide a 'from' address in its response stream headers, in accordance with RFC 6120.
If an entity supports the entity capabilities protocol, it MUST advertise that fact by returning a feature of 'http://jabber.org/protocol/caps' in response to a service discovery information request.
If a server supports the Caps Optimization functionality, it MUST also return a feature of 'http://jabber.org/protocol/caps#optimize' in response to service discovery information requests.
An application SHOULD maintain a list of hashing algorithms it supports, which MUST include the algorithm or algorithms listed in the Mandatory-to-Implement Technologies section of this document.
It is RECOMMENDED for an application that processes entity capabilities information to cache associations between the verification string and discovered identity+features within the scope of one presence session. This obviates the need for extensive service discovery requests within a session.
It is RECOMMENDED for an application to cache associations across presence sessions, since this obviates the need for extensive service discovery requests at the beginning of a session (this is especially helpful in bandwidth-constrained environments).
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 presence broadcasts. Until and unless capabilities information has been received from another entity, an application MUST assume that the other entity does not support capabilities.
A server that is managing an connected client's presence session MAY optimize presence notification traffic sent through the server by stripping off redundant capabilities annotations (i.e., the <c/> element). Because of this, receivers of presence notifications MUST NOT expect an annotation on every presence notification they receive. If the server performs caps optimization, it MUST ensure that the first presence notification each subscriber receives contains the annotation. The server MUST also ensure that any changes in the caps information (e.g., an updated 'ver' attribute) are sent to all subscribers.
If a connected client determines that its server supports caps optimization, it MAY choose to send the capabilities annotation only on the first presence packet, as well as whenever its capabilities change.
The SHA-1 hashing algorithm is mandatory to implement. All implementations MUST support SHA-1.
An implementation MAY support other algorithms. Any such algorithm SHOULD be registered in the &ianahashes;.
In the future, the &COUNCIL; may, at its discretion, modify the mandatory-to-implement hashing algorithm if it determines that SHA-1 has become practically vulnerable to Preimage Attacks.
As described in &rfc4270;, protocols that use the output of hash functions such as MD5 or SHA-1 can be vulnerable to collision attacks or preimage attacks or both. Because of how the hash output is used in entity capabilities, the protocol will not be subject to collision attacks even if the hash function used is found to be vulnerable to collision attacks. However, it is possible that the protocol might become subject to preimage attacks if the hash function used is found to be vulnerable to preimage attacks.
In theory, such a preimage attack would take one of the following forms:
In practice, a preimage attack would need to meet all of the following criteria in order to be effective against the entity capabilities protocol:
It currently seems extremely unlikely that an attacker could meet all of the foregoing conditions in the foreseeable future. However, the XMPP Council shall continue to monitor the state of cryptanalysis regarding the mandatory-to-implement hash function as well as the possibility that any vulnerabilities in that function might lead to practical threats against the entity capabilities protocol. If and when it becomes practical (or even possible) to launch effective preimage attacks against the entity capabilities protocol, the XMPP Council shall consider updating this specification to change the mandatory-to-implement hashing algorithm to a safer technology.
<warning;Adherence to the method defined in the Verification String section of this document for both generation and processing of the 'ver' attribute helps to guard against poisoning of entity capabilities information by malicious or improperly implemented entities.
If the value of the 'ver' attribute is a verification string as defined herein (i.e., if the 'ver' attribute is not generated according to the Legacy Format), inclusion of the 'hash' attribute is REQUIRED. Knowing explicitly that the value of the 'ver' attribute is a verification string enables the recipient to avoid spurious notification of invalid or poisoned hashes.
Use of entity capabilities might make it easier for an attacker to launch certain application-specific attacks, since the attacker could more easily determine the type of client being used as well as its capabilities. However, since most clients respond to Service Discovery 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 &xep0016; 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 presence subscription of "both"); note, however, that such restrictions may be incompatible with the recommendation regarding Directed Presence.
This document requires no interaction with &IANA;.
The ®ISTRAR; includes "http://jabber.org/protocol/caps" in its registry of protocol namespaces (see &NAMESPACES;).
The XMPP Registrar includes "http://jabber.org/protocol/caps" and "http://jabber.org/protocol/caps#optimize" in its registry of service discovery features (see &DISCOFEATURES;).
The XMPP Registrar includes "http://jabber.org/protocol/caps" in its registry of stream features (see &STREAMFEATURES;).
The protocol documented by this schema is defined in
XEP-0115: http://www.xmpp.org/extensions/xep-0115.html
]]>
Before Version 1.4 of this specification, the 'ver' attribute was generated differently, the 'ext' attribute was used more extensively, and the 'hash' attribute was absent. For historical purposes, Version 1.3 of this specification is archived at <http://www.xmpp.org/extensions/attic/xep-0115-1.3.html>. For backwards-compatibility with the legacy format, the 'node' attribute is REQUIRED and the 'ext' attribute MAY be included.
An application can determine if the legacy format is in use by checking for the presence of the 'hash' attribute, which is REQUIRED in the current format.
If a caps-processing application supports the legacy format, it SHOULD check the 'node', 'ver', and 'ext' combinations as specified in the archived version 1.3 of this specification, and MAY cache the results.
If a caps-processing application does not support the legacy format, it SHOULD ignore the 'ver' value entirely (since the value cannot be verified) and SHOULD NOT cache it, since the application cannot validate the identity and features by checking the hash.
Thanks to Rachel Blackman, Dave Cridland, Richard Dobson, Olivier Goffart, Sergei Golovan, Justin Karneges, Ralph Meijer, Ian Paterson, Kevin Smith, Tomasz Sterna, Michal Vaner, and Matt Yacobucci for comments and suggestions.