<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>Entity capabilities is not limited to clients, and can be used by any entity that exchanges presence with another entity, e.g., a gateway. However, this specification mainly uses the example of clients.</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 (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;).</p>
<p>At this point, your client has no idea what the capabilities are of someone with a version string 'QgayPKawpkPSDYmwT/WM94uAlu0='. 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 a contact who advertises a version 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 <linkurl='#ver-gen'>generation method</link>). <note>The string can be relied upon because of how it is generated and checked, as explained later in this document.</note> 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 are on networks without connectivity to other XMPP servers, services offering specialized XMPP extensions, or HTTP servers.<note>These first two requirements effectively eliminated <cite>XEP-0060</cite> 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 verification string; 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 verification string 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 and then by xml:lang (if it exists), formatted as CATEGORY '/' [TYPE] '/' [LANG] '/' [NAME]. <note>The combination of category, type, and xml:lang forms a unique combination, so it is not necessary to also sort by name (the name merely provides some human-readable text associated with a category/type/lang).</note> Note that each slash is included even if the TYPE, LANG, or NAME is not included.</li>
<li>If the service discovery information response includes <cite>XEP-0128</cite> data forms, sort the forms by the FORM_TYPE (i.e., by the XML character data of the <value/> element).</li>
<li>Ensure that S is encoded according to the UTF-8 encoding (&rfc3269;).</li>
<li>Compute the verification string 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 "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 verification string would be generated as follows (note: line breaks in the verification string are included only for the purposes of readability):</p>
<olstart='1'>
<li>
<p>S = ''</p>
</li>
<li>
<p>Only one identity: "client/pc"</p>
</li>
<li>
<p>S = 'client/pc//Exodus 0.9.1<'</p>
</li>
<li>
<p>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".</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>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):</p>
<p>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".</p>
<p>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.</p>
<li>Verify that the <c/> element includes a 'hash' attribute. If it does not, ignore the 'ver' or treat it as generated in accordance with the <linkurl='#legacy'>Legacy Format</link> (if supported).</li>
<li>If the value of the 'hash' attribute does not match one of the processing application's supported hash functions, do the following:
<li>Send a service discovery information request to the generating entity.</li>
<li>Receive a service discovery information response from the generating entity.</li>
<li>Do not validate or globally cache the verification string as described below; instead, the processing application SHOULD associate the discovered identity+features <em>only</em> with the JabberID of the generating entity.</li>
</ol>
</li>
<li>If the value of the 'hash' attribute matches one of the processing application's supported hash functions, validate the verification string by doing the following:
<li>Send a service discovery information request to the generating entity.</li>
<li>Receive a service discovery information response from the generating entity.</li>
<li>If the response includes more than one service discovery identity with the same category/type/lang/name, consider the entire response to be ill-formed.</li>
<li>If the response includes more than one service discovery feature with the same XML character data, consider the entire response to be ill-formed.</li>
<li>If the response includes more than one extended service discovery information form with the same FORM_TYPE or the FORM_TYPE field contains more than one <value/> element with different XML character data, consider the entire response to be ill-formed.</li>
<li>If the response includes an extended service discovery information form where the FORM_TYPE field is not of type "hidden" or the form does not include a FORM_TYPE field, ignore the form but continue processing.</li>
<li>If the response is considered well-formed, reconstruct the hash by using the service discovery information response to generate a local hash in accordance with the <linkurl='#ver-gen'>Generation Method</link>).</li>
<li>If the values of the received and reconstructed hashes match, the processing application MUST consider the result to be valid and SHOULD globally cache the result for all JabberIDs with which it communicates.</li>
<li>If the values of the received and reconstructed hashes do not match, the processing application MUST consider the result to be invalid and MUST NOT globally cache the verification string; however, it SHOULD check the service discovery identity and supported features of another generating entity who advertises that value.</li>
<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 verification string and SHOULD send a new presence broadcast.</p>
<p>An application (the "requesting entity") can learn what features another entity supports by sending a disco#info request (see <cite>XEP-0030</cite>) to the entity that generated the caps information (the "generating entity").</p>
<p>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;.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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 &rfc3920bis;). 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 <cite>rfc3920bis</cite>.</p>
<p>If an entity supports the entity capabilities protocol, it MUST advertise that fact by returning a feature of <strong>'http://jabber.org/protocol/caps'</strong> in response to a service discovery information request.</p>
<examplecaption="Service discovery information request"><