<abstract>This document defines an XMPP protocol extension for broadcasting and discovering client, device, or generic entity capabilities in a way that minimizes network impact.</abstract>
<remark><p>In response to persistent security concerns over caps poisoning, defined method for hashing concatenation of identity and supported features.</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 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:</p>
<ul>
<li>Showing a different set of icons depending on the capabilities of other clients.</li>
<li>Not sending &xep0071; content to plaintext clients such as cell phones.</li>
<li>Not showing a "Send a File" button if another user's client does not support &xep0096;.</li>
</ul>
<p>Some older Jabber clients send one &xep0030; and one &xep0092; request to each entity from which they received presence after login. That "disco+version flood" results in an excessive use of bandwidth and is impractical on a larger scale, particularly for users or applications with large rosters. Therefore this document proposes 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 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>At this point, your client knows that anyone advertising a version string of '8RovUdtOmiAjzj+xI7SK5BCw3A8=' has a client that can do &xep0045;. 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>Different clients may support the same capabilities.</li>
<li>Members of a community tend to cluster around a small set of clients. 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 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>It MUST be possible to publish a change in capabilities within a single 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>
<tablecaption='Attributes'>
<tr>
<th>Name</th>
<th>Definition</th>
<th>Inclusion</th>
</tr>
<tr>
<td>ext</td>
<td>A set of nametokens specifying additional feature bundles; this attribute is deprecated.</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>hash</td>
<td>The hashing algorithm used in generated the 'ver' attribute (see &ianahashes;); the value defaults to "sha-1".</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; although this information is an "FYI" in the current version of entity capabilities, it is required for backward-compatibility with older versions.</td>
<td>A string that specifies the identity and supported features of the entity. <note>Before version 1.4 of this specification, the 'ver' attribute was used to specify the released version of the software.</note></td>
<td>REQUIRED</td>
</tr>
</table>
</section1>
<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 client sends presence, it annotates that presence with a client identifier ('node' attribute) and identity and feature identifier ('ver' attribute). 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.</p>
<p>If the supported features change during a client's 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>Note: The values of the <strong>'node'</strong> and <strong>'ver'</strong> attributes MUST NOT contain the '#' character, since that character is used as a separator in the <linkurl="#discover">Discovering Capabilities</link> use case.</p>
<p>A contact can learn what features a user's client supports by sending a disco#info request (as defined in <strong>XEP-0030: Service Discovery</strong>) to any client that sent a particular value of the <strong>ver</strong> attribute.</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 the 'ver' value as reliable and SHOULD check the value 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'><