<abstract>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.</abstract>
<remark><p>To avoid confusion, renamed the hash attribute to the algo attribute; required inclusion of the algo attribute in non-legacy mode; removed schema default for algo attribute; to help prevent a race condition and ensure backward compatibility, specified that the disco#info request is sent to node#ver; clarified meaning of node attribute; further specified security considerations; clarified handling of the legacy format to assist developers.</p></remark>
<remark><p>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 backward-compatible with the legacy format.</p></remark>
<remark><p>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).</p></remark>
<remark><p>Added several items to the Security Considerations; clarified naming requirements regarding 'node', 'ver', and 'ext' attributes.</p></remark>
<remark><p>Specified that the protocol can be used whenever presence is used (e.g., by gateways); improved the XML schema; made several editorial adjustments.</p></remark>
<p>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:</p>
<p>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 <note>This proposal is not limited to clients, and can be used by any entity that exchanges presence with another entity, e.g., a gateway. However, this document uses the example of clients throughout.</note> for exchanging information about entity capabilities. Clients should not engage in the older "disco+version flood" behavior and instead should use Entity Capabilities as specified herein.</p>
<p>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:</p>
<p>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.</p>
<p>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.</p>
<p>(Note: The disco#info request is sent to a service discovery node formed of the caps 'node' attribute and the caps 'ver' attribute to help prevent a race condition; see <linkurl='#discover'>Discovering Capabilities</link>.)</p>
<p>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:</p>
<p>... 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.</p>
<li>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).</li>
<li>Clients must be able to participate even if they support only &xmppcore;, &xmppim;, and <cite>XEP-0030</cite>.</li>
<li>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.<note>These first two requirements effectively eliminated &xep0060; as a possible implementation of entity capabilities.</note></li>
<li>Clients must be able to retrieve information without querying each user.</li>
<li>Since presence is normally broadcasted to many users, the byte size of the proposed extension must be as small as possible.</li>
<li>It must be possible to write a XEP-0045 server implementation that passes the given information along.</li>
<li>It must be possible to publish a change in capabilities within a single presence session.</li>
<li>Server infrastructure above and beyond that defined in <cite>XMPP Core</cite> and <cite>XMPP IM</cite> must not be required for this approach to work, although additional server infrastructure may be used for optimization purposes.</li>
<p>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.</p>
<td>A set of nametokens specifying additional feature bundles; this attribute is deprecated (see the <linkurl='#legacy'>Legacy Format</link> section of this document).</td>
<td>A unique identifier for the software underlying the entity, typically a URL at the website of the project or company that produces the software. *</td>
<p>* Note: It is RECOMMENDED for the value of the 'node' attribute to identify both the software product and the released version in the form "ProductURL;SoftwareVersion", such as "http://psi-im.org/;0.11" <note>This enables a processing application to strip off everything after the ";" character and thereby determine a unique string for the generating application, which it could maintain in a list of known products or (if the string is a URL) which it could use to find more detailed information about the generating application.</note>. In any case, the value of the 'node' attribute MUST NOT include the "#" character, which is used as a separator character in the <linkurl='#discover'>Discovering Capabilities</link> use case.</p>
<p>** 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 backward-compatible, applications SHOULD appropriately handle the <linkurl='#legacy'>Legacy Format</link>.</p>
<section1topic='Generation of ver Attribute'anchor='ver'>
<p>In order to help prevent poisoning of entity capabilities information, the value of the 'ver' attribute MUST be generated according to the following method.</p>
<p>Note: All sorting operations MUST be performed using "i;octet" collation as specified in Section 9.3 of &rfc4790;.</p>
<li>Compute ver by hashing S using the SHA-1 algorithm as specified in &rfc3174; (with binary output) and encoding the hash using Base64 as specified in Section 4 of &rfc4648; (note: the Base64 output MUST NOT include whitespace and MUST set padding bits to zero). <note>The OpenSSL command for producing such output is "echo -n 'S' | openssl dgst -binary -sha1 | openssl enc -nopad -base64".</note></li>
<p>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:</p>
<p>Each time a conformant 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, the client SHOULD include entity capabilities with every presence change.</p>
<p>If the supported features change during a client'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.</p>
<p>An application can learn what features another entity supports by sending a disco#info request (see <cite>XEP-0030</cite>) to any entity that sent a particular value of the <strong>ver</strong> attribute.</p>
<p>The disco#info request is sent to a service discovery node whose value is generated as follows:</p>
<ol>
<li>The value of the caps 'node' attribute.</li>
<li>The "#" character.</li>
<li>The value of the caps 'ver' attribute.</li>
</ol>
<p>Inclusion of the service discovery 'node' attribute (which is not to be confused with the entity capabilities 'node' attribute) helps to prevent a race condition, namely: if the user sends presence but changes capabilities (e.g., by enabling a plugin) before the contact requests the user's service discovery information.</p>
<p>The responding entity then returns all of the capabilities it supports.</p>
<p>The client MUST check the identities and supported features against the 'ver' value by calculating the hash as described under <linkurl='#ver'>Generating the ver Attribute</link> and making sure that the values match. If the values do not match, the client MUST NOT accept or cache the 'ver' value as reliable and SHOULD check the service discovery identity and supported features of another user who advertises that value (if any). This helps to prevent poisoning of entity capabilities information.</p>
<p>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:</p>
<examplecaption='Stream feature element including capabilities'><