Specified that inclusion of hash attribute is required and removed default value of sha-1; mentioned pre-image attack and added reference to RFC 4270; clarified meaning and construction of caps node attribute and disco node attribute; specified that node attribute shall be included in disco#info request for backwards-compatibility; further specified security considerations; clarified handling of the legacy format to assist developers; defined optional v attribute for the software version.
Specified that inclusion of hash attribute is required and removed default value of sha-1; mentioned pre-image attack and added reference to RFC 4270; clarified meaning and construction of caps node attribute and disco node attribute; specified that node attribute shall be included in disco#info request for backwards-compatibility; further specified security considerations; clarified handling of the legacy format to assist developers; defined optional v attribute for the software version; added service discovery feature for caps optimization to prevent confusion regarding server support of caps vs. caps optimization.
In the past, some Jabber clients sent one &xep0030; and one &xep0092; request to each entity from which they received presence after login. That "disco+version flood" resulted in an excessive use of bandwidth and was impractical on a larger scale, particularly for users or applications with large rosters. Therefore this document defines a more robust and scalable solution: namely, a presence-based mechanism
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 a <c/> element with special attributes to its presence packets. As a result, your client receives the following presence packet:
+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 Romeo is using (the client identifier is an "FYI" and is not used further in Entity Capabilities). The 'ver' attribute is a specially-constructed string that represents the identity (see &DISCOCATEGORIES;) and supported features (see &DISCOFEATURES;) of the entity.
+The 'node' attribute represents the client software Romeo is using. The optional 'v' attribute represents the specific version of that client software (it is only an "FYI" and is not used further in entity capabilities). The 'ver' attribute is a specially-constructed string that represents the identity (see &DISCOCATEGORIES;) and supported features (see &DISCOFEATURES;) of the entity.
At this point, your client has no idea what the capabilities are of someone with a version string '8RovUdtOmiAjzj+xI7SK5BCw3A8='. Your client therefore sends a service discovery query to Romeo, asking what his client can do.
]]>
- At this point, your client knows that anyone advertising a version string of '8RovUdtOmiAjzj+xI7SK5BCw3A8=' has a client that can do &xep0045; and the other features returned by Romeo's client (the string can be relied upon because of how it is generated and checked as explained later in this document). Your client remembers this information, so that it does not need to explicitly query the capabilities of a contact with the same version string. For example, Benvolio may send you the following presence:
+At this point, your client knows that anyone advertising a version string of '8RovUdtOmiAjzj+xI7SK5BCw3A8=' has a client that can do &xep0045; and the other features returned by Romeo's client (the string can be relied upon because of how it is generated and checked, as explained later in this document). Your client remembers this information, so that it does not need to explicitly query the capabilities of a contact with the same version string. For example, Benvolio may send you the following presence:
@@ -202,9 +202,9 @@
* 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 products (e.g., associating the name received via the disco#info reply with the URL found in the caps data).
+* 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.5 of this specification, the version information was contained in the 'ver' attribute as described below.
*** 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 '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 &rfc4790;.
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". Using the SHA-1 algorightm, the value of the 'ver' attribute would be generated as follows:
Each time a generating entity sends presence, it annotates that presence with an entity identifier ('node' attribute) and identity and feature identifier ('ver' attribute). In order that servers can remember the last presence for use in responding to probes, a client SHOULD include entity capabilities with every presence change.
-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 'ver' attribute and SHOULD send a new presence broadcast.
- -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 'ver' attribute and SHOULD send a new presence broadcast.
+An application (here called 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 (here called the "generating entity").
+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 requesting entity MUST check the identities and supported features against the 'ver' value by calculating the hash as described under Generating the ver Attribute and making sure that the values match. If the values do not match, the requesting entity MUST NOT accept or cache the 'ver' value as reliable and SHOULD check the service discovery identity and supported features of another generating entity who advertises that value (if any). This helps to prevent poisoning of entity capabilities information.
+The requesting entity MUST check the identities and supported features against the 'ver' value by calculating the hash as described under Generation of the ver Attribute and making sure that the values match. If the values do not match, the requesting entity MUST NOT accept or cache the 'ver' value as reliable and SHOULD check the service discovery identity and supported features of another generating entity who advertises that value (if any). This helps to prevent poisoning of entity capabilities information.
A server MAY include its own 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:
+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.
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) are sent to all subscribers.
-If the server did not advertise its capabilities using the Stream Feature, a connected 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.
+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. 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 infomration (e.g., an updated 'ver' attribute) are sent to all subscribers.
+If a connected client determines that its server supports caps optimization, MAY choose to send the capabilities annotation only on the first presence packet, as well as whenever its capabilities change.
+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 Server Optimization functionality, it MUST also return a feature of 'http://jabber.org/protocol/caps#optimize' in response to service discovery information requests.
+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.
+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. Until and unless capabilities information has not been received from another entity, an application MUST assume that the other entity does not support capabilities.
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 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 subscription of "both"); note, however, that such restrictions may be incompatible with the recommendation regarding Directed Presence.
-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.
-If the value of the 'ver' attribute is a hash 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 hash enables the recipient to avoid spurious notification of invalid hashes.
+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 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.
+Adherence to the algorithm defined in the Generation of the 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.
+If the value of the 'ver' attribute is a hash 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 hash enables the recipient to avoid spurious notification of invalid hashes.
Theoretically it may become possible to launch a "pre-image" attack (see &rfc4270;) against the hashes used in the 'ver' attribute, at least when the SHA-1 algorithm is used. However, such attacks are not currently practical, and may not become practical in the foreseeable future. If and when such attacks become practical, this specification will be updated to strongly recommend use of a hashing algorithm that is safer than SHA-1, such as SHA-256. Nevertheless, the SHA-256 algorithm can be used today if implementors are concerned about the safety of the SHA-1 algorithm.
The 'name' attribute of the service discovery <identity/> element is not included in the hash generation method. The primary reason for excluding it is that it is human-readable text and therefore may be provided in different localized versions. As a result, its inclusion would needlessly multiply the number of possible hash values and thus the time and resources required to validate values of the 'ver' attribute.
The ®ISTRAR; includes 'http://jabber.org/protocol/caps' in its registry of protocol namespaces (see &NAMESPACES;).
The XMPP Registrar shall include "http://jabber.org/protocol/caps#optimize" in its registry of service discovery features (see &DISCOFEATURES;).
+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.
+Before Version 1.4 of this specification, the 'ver' attribute was generated differently, the 'ext' attribute was used more extensively, and the 'hash' and 'v' attributes were 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 an application supports the legacy format, it SHOULD proceed as follows:
-If an application does not support the legacy format, it SHOULD proceed as follows:
-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, Jacek Konieczny, Ian Paterson, Kevin Smith, Tomasz Sterna, Michal Vaner, and Matt Yacobucci for comments and suggestions.
+Thanks to Rachel Blackman, Dave Cridland, Richard Dobson, Olivier Goffart, Sergei Golovan, Justin Karneges, Ian Paterson, Kevin Smith, Tomasz Sterna, Michal Vaner, and Matt Yacobucci for comments and suggestions.