mirror of https://github.com/moparisthebest/xeps
496 lines
32 KiB
XML
496 lines
32 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
|
%ents;
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
|
<xep>
|
|
<header>
|
|
<title>Entity Capabilities</title>
|
|
<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>
|
|
&LEGALNOTICE;
|
|
<number>0115</number>
|
|
<status>Draft</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
<spec>XMPP IM</spec>
|
|
<spec>XEP-0030</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>caps</shortname>
|
|
<schemaloc>
|
|
<url>http://www.xmpp.org/schemas/caps.xsd</url>
|
|
</schemaloc>
|
|
&hildjj;
|
|
&stpeter;
|
|
&remko;
|
|
<author>
|
|
<firstname>Jacek</firstname>
|
|
<surname>Konieczny</surname>
|
|
<email>jajcus@jajcus.net</email>
|
|
<jid>jajcus@jabber.bnet.pl</jid>
|
|
</author>
|
|
<revision>
|
|
<version>1.5pre12</version>
|
|
<date>in progress, last updated 2007-12-18</date>
|
|
<initials>jjh/psa</initials>
|
|
<remark><p>Specified that inclusion of hash attribute is required, removed default value of sha-1, and added reference to IANA registry; 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.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.4</version>
|
|
<date>2007-08-13</date>
|
|
<initials>psa/jk/jjh</initials>
|
|
<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>
|
|
</revision>
|
|
<revision>
|
|
<version>1.3</version>
|
|
<date>2007-04-10</date>
|
|
<initials>psa/rt/jjh</initials>
|
|
<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>
|
|
</revision>
|
|
<revision>
|
|
<version>1.2</version>
|
|
<date>2007-02-15</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Clarified motivation and handling of service discovery requests.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.1</version>
|
|
<date>2004-10-29</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Clarified meaning of service discovery results for client#ver and client#ext.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.0</version>
|
|
<date>2004-08-01</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Per a vote of the Jabber Council, advanced status to Draft.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.7</version>
|
|
<date>2004-06-29</date>
|
|
<initials>jjh/psa</initials>
|
|
<remark><p>Added several items to the Security Considerations; clarified naming requirements regarding 'node', 'ver', and 'ext' attributes.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.6</version>
|
|
<date>2004-04-25</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Made a number of editorial adjustments.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.5</version>
|
|
<date>2004-01-05</date>
|
|
<initials>psa</initials>
|
|
<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>
|
|
</revision>
|
|
<revision>
|
|
<version>0.4</version>
|
|
<date>2003-09-04</date>
|
|
<initials>jjh</initials>
|
|
<remark><p>IQ eets must be to a resource, since they are intended to go to a particular session.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.3</version>
|
|
<date>2003-09-02</date>
|
|
<initials>jjh</initials>
|
|
<remark><p>Servers MUST strip extras changed to MAY, due to implementer feedback.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.2</version>
|
|
<date>2003-08-28</date>
|
|
<initials>jjh</initials>
|
|
<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>
|
|
</revision>
|
|
<revision>
|
|
<version>0.1</version>
|
|
<date>2003-08-27</date>
|
|
<initials>jjh</initials>
|
|
<remark><p>Initial version.</p></remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<section2 topic='Motivation' anchor='motivation'>
|
|
<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>
|
|
<ul>
|
|
<li>Showing a different set of icons depending on the capabilities of other entities.</li>
|
|
<li>Not sending &xep0071; or other rich content to plaintext clients such as cell phones.</li>
|
|
<li>Allowing the initiation of a Voice over IP (VoIP) session only to clients that support &xep0166; and &xep0167;.</li>
|
|
<li>Not showing a "Send a File" button if another user's client does not support &xep0096;.</li>
|
|
<li>Filtering &xep0060; notifications based on advertised subscriber interests.</li>
|
|
</ul>
|
|
<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>
|
|
</section2>
|
|
<section2 topic='How It Works' anchor='howitworks'>
|
|
<p>This section provides a friendly introduction to entity capabilities ("caps").</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>
|
|
<code><![CDATA[
|
|
<presence from='romeo@montague.lit/orchard'>
|
|
<c xmlns='http://jabber.org/protocol/caps'
|
|
hash='sha-1'
|
|
node='http://code.google.com/p/exodus'
|
|
v='0.9.1'
|
|
ver='8RovUdtOmiAjzj+xI7SK5BCw3A8='/>
|
|
</presence>
|
|
]]></code>
|
|
<p>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.</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>
|
|
<code><![CDATA[
|
|
<iq from='juliet@capulet.lit/chamber'
|
|
id='disco1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='get'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
|
node='http://code.google.com/p/exodus#8RovUdtOmiAjzj+xI7SK5BCw3A8='/>
|
|
</iq>
|
|
]]></code>
|
|
<p>The response is:</p>
|
|
<code><![CDATA[
|
|
<iq from='romeo@montague.lit/orchard'
|
|
id='disco1'
|
|
to='juliet@capulet.lit/chamber'
|
|
type='result'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
|
node='http://code.google.com/p/exodus#8RovUdtOmiAjzj+xI7SK5BCw3A8='>
|
|
<identity category='client' name='Exodus 0.9.1' type='pc'/>
|
|
<feature var='http://jabber.org/protocol/disco#info'/>
|
|
<feature var='http://jabber.org/protocol/disco#items'/>
|
|
<feature var='http://jabber.org/protocol/muc'/>
|
|
</query>
|
|
</iq>
|
|
]]></code>
|
|
<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>
|
|
<code><![CDATA[
|
|
<presence from='benvolio@capulet.lit/230193'>
|
|
<c xmlns='http://jabber.org/protocol/caps'
|
|
hash='sha-1'
|
|
node='http://psi-im.org/'
|
|
v='0.11'
|
|
ver='8RovUdtOmiAjzj+xI7SK5BCw3A8='/>
|
|
</presence>
|
|
]]></code>
|
|
<p>Now your client automatically knows that Benvolio can do MUC, without needing to ask him explicitly via service discovery.</p>
|
|
<p>On the other hand, for a person with the following presence ...</p>
|
|
<code><![CDATA[
|
|
<presence from='nurse@capulet.lit/chamber'>
|
|
<c xmlns='http://jabber.org/protocol/caps'
|
|
hash='sha-1'
|
|
node='http://psi-im.org/'
|
|
v='0.10'
|
|
ver='uCoVCteRe3ty2wU2gHxkMaA7xhs='/>
|
|
</presence>
|
|
]]></code>
|
|
<p>... or the following presence ...</p>
|
|
<code><![CDATA[
|
|
<presence from='bard@shakespeare.lit/globe'>
|
|
<c xmlns='http://jabber.org/protocol/caps'
|
|
hash='sha-1'
|
|
node='http://www.chatopus.com'
|
|
ver='zHyEOgxTrkpSdGcQKH8EFPLsriY='/>
|
|
</presence>
|
|
]]></code>
|
|
<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>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Assumptions' anchor='assumptions'>
|
|
<p>This document makes several assumptions:</p>
|
|
<ul>
|
|
<li>The type of client I am using is of interest to the people in my roster.</li>
|
|
<li>Clients for the people on my roster might want to make user interface decisions based on my capabilities.</li>
|
|
<li>Different clients may support the same capabilities.</li>
|
|
<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>Some clients are running on networks without server-to-server connectivity enabled and without access to the Internet via HTTP.</li>
|
|
<li>Conversations are possible between users who are not on each other's rosters.</li>
|
|
<li>Client capabilities may change over the course of a presence session, as features are enabled or disabled.</li>
|
|
</ul>
|
|
</section1>
|
|
|
|
<section1 topic='Requirements' anchor='reqs'>
|
|
<p>The protocol defined herein addresses the following requirements:</p>
|
|
<ol>
|
|
<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 every entity with which they communicate.</li>
|
|
<li>Since presence is normally broadcasted to many contacts, 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>
|
|
<li>The defined mechanism must not be limited to clients but must be usable be servers, components, and other network entities.</li>
|
|
</ol>
|
|
</section1>
|
|
|
|
<section1 topic='Protocol' anchor='protocol'>
|
|
<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>
|
|
<table caption='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 (see the <link url='#legacy'>Legacy Format</link> section of this document).</td>
|
|
<td>DEPRECATED</td>
|
|
</tr>
|
|
<tr>
|
|
<td>hash</td>
|
|
<td>The hashing algorithm used to generate the 'ver' attribute; expected values are sha-1 and sha-256, although other values may be used (such values SHOULD be as registered in the &ianahashes;).</td>
|
|
<td>REQUIRED</td>
|
|
</tr>
|
|
<tr>
|
|
<td>node</td>
|
|
<td>A URI that uniquely identifies a software application, typically a URL at the website of the project or company that produces the software. *</td>
|
|
<td>REQUIRED</td>
|
|
</tr>
|
|
<tr>
|
|
<td>v</td>
|
|
<td>A specific version of the software. **</td>
|
|
<td>RECOMMENDED</td>
|
|
</tr>
|
|
<tr>
|
|
<td>ver</td>
|
|
<td>A string that specifies the identity and supported features of the entity. ***</td>
|
|
<td>REQUIRED</td>
|
|
</tr>
|
|
</table>
|
|
<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.5 of this specification, the version information was contained in the 'ver' attribute as described below.</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 <link url='#legacy'>Legacy Format</link>.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Generation of the 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>
|
|
<ol>
|
|
<li>Initialize an empty string S.</li>
|
|
<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), formatted as 'category' '/' 'type'.</li>
|
|
<li>For each identity, append the 'category/type' to S, followed by the '<' character.</li>
|
|
<li>Sort the supported service discovery features. <note>A registry of service discovery features is located at &DISCOFEATURES;.</note></li>
|
|
<li>For each feature, append the feature to S, followed by the '<' character.</li>
|
|
<li>Compute ver by hashing S using the algorithm specified in 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>
|
|
</ol>
|
|
<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". Using the SHA-1 algorightm, the value of the 'ver' attribute would be generated as follows:</p>
|
|
<ol>
|
|
<li>S = ''</li>
|
|
<li>Only one identity: "client/pc"</li>
|
|
<li>S = 'client/pc<'</li>
|
|
<li>Sort the features: "http://jabber.org/protocol/disco#info", "http://jabber.org/protocol/disco#items", "http://jabber.org/protocol/muc".</li>
|
|
<li>S = 'client/pc<http://jabber.org/protocol/disco#info<http://jabber.org/protocol/disco#items<http://jabber.org/protocol/muc<'</li>
|
|
<li>ver = 8RovUdtOmiAjzj+xI7SK5BCw3A8=</li>
|
|
</ol>
|
|
</section1>
|
|
|
|
<section1 topic='Use Cases' anchor='usecases'>
|
|
<section2 topic='Advertising Capabilities' anchor='advertise'>
|
|
<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>
|
|
<example caption='Presence with caps'><![CDATA[
|
|
<presence>
|
|
<c xmlns='http://jabber.org/protocol/caps'
|
|
hash='sha-1'
|
|
node='http://code.google.com/p/exodus'
|
|
v='0.9.1'
|
|
ver='8RovUdtOmiAjzj+xI7SK5BCw3A8='/>
|
|
</presence>
|
|
]]></example>
|
|
<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>
|
|
<example caption='Presence with recomputed ver attribute'><![CDATA[
|
|
<presence>
|
|
<c xmlns='http://jabber.org/protocol/caps'
|
|
hash='sha-1'
|
|
node='http://code.google.com/p/exodus'
|
|
v='0.9.1'
|
|
ver='66/0NaeaBKkwk85efJTGmU47vXI='/>
|
|
</presence>
|
|
]]></example>
|
|
</section2>
|
|
|
|
<section2 topic="Discovering Capabilities" anchor='discover'>
|
|
<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>
|
|
|
|
<example caption='Disco#info request'><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='disco1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='get'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
|
node='http://code.google.com/p/exodus#8RovUdtOmiAjzj+xI7SK5BCw3A8='/>
|
|
</iq>
|
|
]]></example>
|
|
|
|
<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 (&FULLJID;).</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., "8RovUdtOmiAjzj+xI7SK5BCw3A8=") as provided by the generating entity.</p>
|
|
|
|
<p>The generating entity then returns all of the capabilities it supports.</p>
|
|
|
|
<example caption='Disco#info response'><![CDATA[
|
|
<iq from='romeo@montague.lit/orchard'
|
|
id='disco1'
|
|
to='juliet@capulet.lit/balcony'
|
|
type='result'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
node='http://code.google.com/p/exodus#8RovUdtOmiAjzj+xI7SK5BCw3A8='>
|
|
<identity category='client' type='pc'/>
|
|
<feature var='http://jabber.org/protocol/disco#info'/>
|
|
<feature var='http://jabber.org/protocol/disco#items'/>
|
|
<feature var='http://jabber.org/protocol/muc'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
|
|
<p>The requesting entity MUST check the identities and supported features against the 'ver' value by calculating the hash as described under <link url='#ver'>Generation of the ver Attribute</link> 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.</p>
|
|
|
|
</section2>
|
|
|
|
<section2 topic='Stream Feature' anchor='stream'>
|
|
<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>
|
|
<example caption='Stream feature element including capabilities'><![CDATA[
|
|
<stream:features>
|
|
<c xmlns='http://jabber.org/protocol/caps'
|
|
hash='sha-1'
|
|
node='http://jabberd.org'
|
|
v='1.6.1'
|
|
ver='ItBTI0XLDFvVxZ72NQElAzKS9sU='>
|
|
</stream:features>
|
|
]]></example>
|
|
<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>rfc3921bis</cite>.</p>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Caps Optimization' anchor='optimization'>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Determining Support' anchor='support'>
|
|
<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>
|
|
<example caption="Service discovery information request"><![CDATA[
|
|
<iq from='romeo@montague.lit/orchard'
|
|
id='disco2'
|
|
to='juliet@capulet.lit/balcony'
|
|
type='get'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Service discovery information response"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='disco2'
|
|
to='romeo@montague.lit/orchard'
|
|
type='result'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
...
|
|
<feature var='http://jabber.org/protocol/caps'/>
|
|
...
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>If a server supports the <link url='#optimization'>Server Optimization</link> functionality, it MUST also return a feature of <strong>'http://jabber.org/protocol/caps#optimize'</strong> in response to service discovery information requests.</p>
|
|
<example caption="Service discovery information request"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='disco3'
|
|
to='capulet.lit'
|
|
type='get'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Service discovery information response"><![CDATA[
|
|
<iq from='capulet.lit'
|
|
id='disco3'
|
|
to='juliet@capulet.lit/balcony'
|
|
type='result'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
...
|
|
<feature var='http://jabber.org/protocol/caps#optimize'/>
|
|
...
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section1>
|
|
|
|
<section1 topic='Directed Presence' anchor='directed'>
|
|
<p>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.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Caching' anchor='caching'>
|
|
<p>It is RECOMMENDED for an application that processes entity capabilities information to cache associations between the 'ver' attribute and discovered features within the scope of one presence session. This obviates the need for extensive service discovery requests within a session.</p>
|
|
<p>It is OPTIONAL for an application to cache associates across presence sessions. However, since this obviates the need for extensive service discovery requests at the beginning of a session, such caching is strongly encouraged, especially in bandwidth-constrained environments.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Security Considerations' anchor='security'>
|
|
<p>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 <link url='#directed'>Directed Presence</link>.</p>
|
|
<p>Adherence to the algorithm defined in the <link url='#ver'>Generation of the ver Attribute</link> 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.</p>
|
|
<p>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 <link url='#legacy'>Legacy Format</link>), 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.</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
</section1>
|
|
|
|
<section1 topic='IANA Considerations' anchor='iana'>
|
|
<p>This document requires no interaction with &IANA;. </p>
|
|
</section1>
|
|
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
|
<section2 topic='Protocol Namespaces' anchor='ns'>
|
|
<p>The ®ISTRAR; includes 'http://jabber.org/protocol/caps' in its registry of protocol namespaces (see &NAMESPACES;).</p>
|
|
</section2>
|
|
<section2 topic='Service Discovery Features' anchor='registrar-features'>
|
|
<p>The XMPP Registrar shall include "http://jabber.org/protocol/caps#optimize" in its registry of service discovery features (see &DISCOFEATURES;).</p>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='XML Schema' anchor='schema'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='http://jabber.org/protocol/caps'
|
|
xmlns='http://jabber.org/protocol/caps'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:annotation>
|
|
<xs:documentation>
|
|
The protocol documented by this schema is defined in
|
|
XEP-0115: http://www.xmpp.org/extensions/xep-0115.html
|
|
</xs:documentation>
|
|
</xs:annotation>
|
|
|
|
<xs:element name='c'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='ext' type='xs:NMTOKENS' use='optional'/>
|
|
<xs:attribute name='hash' type='xs:NMTOKEN' use='required'/>
|
|
<xs:attribute name='node' type='xs:string' use='required'/>
|
|
<xs:attribute name='v' type='xs:string' use='optional'/>
|
|
<xs:attribute name='ver' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:simpleType name='empty'>
|
|
<xs:restriction base='xs:string'>
|
|
<xs:enumeration value=''/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section1>
|
|
|
|
<section1 topic='Legacy Format' anchor='legacy'>
|
|
<p>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 <<link url='http://www.xmpp.org/extensions/attic/xep-0115-1.3.html'>http://www.xmpp.org/extensions/attic/xep-0115-1.3.html</link>>. For backwards-compatibility with the legacy format, the 'node' attribute is REQUIRED and the 'ext' attribute MAY be included.</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Acknowledgements' anchor='ack'>
|
|
<p>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.</p>
|
|
</section1>
|
|
|
|
</xep>
|