<abstract>This document defines an XMPP protocol extension for broadcasting and dynamically discovering client, device, or generic entity capabilities. In order to minimize network impact, the transport mechanism is standard XMPP presence broadcast (thus forestalling the need for polling related to service discovery data), the capabilities information can be cached either within a session or across sessions. and the format has been kept as small as possible.</abstract>
<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 backwards-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>
<remark><p>Add more clarifying assumptions and requirements, make it clear that clients don't have to send capabilities every time if the server is optimizing.</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, 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 <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 to its presence packets a <c/> element with special attributes. As a result, your client receives the following presence packet:</p>
<p>The 'node' attribute represents the client software Romeo is using. The 'ver' attribute is a specially-constructed string that represents the entity's service discovery identity (category and type as registered at &DISCOCATEGORIES; as well as, optionally, the service discovery name) and supported features (as registered at &DISCOFEATURES; as well as, optionally, &xep0128; data registered at &FORMTYPES;).</p>
<p>At this point, your client has no idea what the capabilities are of someone with a version string 'SrFo9ar2CCk2EnOH4q4QANeuxLQ='. 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 'SrFo9ar2CCk2EnOH4q4QANeuxLQ=' 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, your Nurse may use the same client that Romeo does:</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>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>The hashing algorithm used to generate the 'ver' attribute; see <linkurl='#security-mti'>Mandatory-to-Implement Technologies</link> regarding supported hashing algorithms.</td>
<p>* 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).</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 backwards-compatible, applications SHOULD appropriately handle the <linkurl='#legacy'>Legacy Format</link>.</p>
<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>Sort the service discovery identities <note>A registry of service discovery identities is located at &DISCOCATEGORIES;.</note> by category and then by type (if it exists) and then by xml:lang (if it exists), formatted as CATEGORY '/' [TYPE] '/' [LANG] '/' [NAME]. Note that each slash is included even if the TYPE, LANG, or NAME is not included.</li>
<li>For each identity, append the 'category/type/lang/name' to S, followed by the '<' character.</li>
<li>If the service discovery information response includes <cite>XEP-0128</cite> data, sort the fields by the value of the "var" attribute.</li>
<li>For each "var":
<ol>
<li>Append the var name and the '<' character.</li>
<li>Sort values by the XML character data of the <value/> element.</li>
<li>For each value, append the value and the '<' character.</li>
</ol>
</li>
<li>Compute ver by hashing S using the algorithm specified in the 'hash' attribute (e.g., SHA-1 as defined in &rfc3174;). The hashed data MUST be generated with binary output and encoded 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 with SHA-1 is is "echo -n 'S' | openssl dgst -binary -sha1 | openssl enc -nopad -base64".</note></li>
<p>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 value of the 'ver' attribute would be generated as follows:</p>
<p>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 <cite>XEP-0128</cite>.</p>
<p>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.</p>
<p>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.</p>
<examplecaption='Presence with recomputed ver attribute'><