<abstract>This document defines an XMPP protocol extension for exchanging roster items, including the ability to suggest whether the item is to be added, deleted, or modified.</abstract>
<remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
</revision>
<revision>
<version>0.6</version>
<date>2005-07-28</date>
<initials>psa</initials>
<remark>Incorporated Council feedback: specified that a body MAY be included when sending a message stanza; changed prohibition on mixing of additions, deletions, and modifications from SHOULD NOT to MUST NOT; clarified status of bots as sending entities.</remark>
<remark>Simplified processing of roster item deletions.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2004-10-27</date>
<initials>psa</initials>
<remark>Clarified the nature of sending entities (users, gateways, and group services); specified "directory/group" service discovery identity for shared group services.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2004-10-04</date>
<initials>psa</initials>
<remark>Further defined the nature of trusted entities.</remark>
<remark>Forked XEP-0093 by adding the action attribute, defining requirements and use cases, specifying processing rules, and detailing security considerations.</remark>
<p>The Jabber protocols have long included a method for sending roster items from one entity to another, making use of the 'jabber:x:roster' namespace. Because this protocol extension was not required by &rfc2779;, it was removed from &xmppim; and documented for historical purposes in &xep0093;. However, since that time discussions in the &SSIG; have revealed that it would be helpful to use roster item exchange in the problem spaces of "shared groups" (e.g., predefined roster groups used within an organization) and roster synchronization (e.g., keeping a Jabber roster in sync with a contact list on a legacy IM service). These problem spaces require a slightly more sophisticated kind of roster item exchange than was documented in XEP-0093, specifically the ability to indicate whether a roster item is to be added, deleted, or modified. Therefore this document redefines roster item exchange to provide this functionality in a way that is backwards-compatible with existing implementations, albeit using a modern namespace URI of 'http://jabber.org/protocol/rosterx' rather than the old 'jabber:x:roster' namespace name. Further specifications will define how to solve the problems of shared groups and roster synchronization using the protocol defined herein.</p>
<p>Roster item exchange meets the following requirements:</p>
<ol>
<li>Enable an entity to send one or more roster items to another entity, with the suggestion that the roster item(s) be added to the recipient's roster.</li>
<li>Enable an entity to send one or more roster items to another entity, with the suggestion that the roster item(s) be deleted from the recipient's roster.</li>
<li>Enable an entity to send one or more roster items to another entity, with the suggestion that the roster item(s) be modified in the recipient's roster.</li>
<p>This document deliberately speaks of rosters and roster items, not presence subscriptions. Although rosters and subscriptions are closely connected (as explained in <cite>RFC 3921</cite>), they are not identical. The protocol defined herein enables an entity to suggest that another entity might want to add, delete, or modify roster items only, and does not dictate the suggested presence subscription state associated with those roster items. This is intentional.</p>
<p>In order to programatically suggest that the receiving entity should add one or more items to its roster, the sending entity MUST send a &MESSAGE; or &IQ; stanza containing an &X; element qualified by the 'http://jabber.org/protocol/rosterx' namespace (see <linkurl='#stanza'>Recommended Stanza Type</link> regarding when to use &MESSAGE; and when to use &IQ;); the &X; element in turn MUST contain one or more <item/> child elements, each of which SHOULD possess an 'action' attribute whose value is "add" <note>The default value of the 'action' attribute is "add"; therefore, if the 'action' attribute is not included or the receiving application does not understand the 'action' attribute, the receiving application MUST treat the item as if the value were "add".</note>, MUST possess a 'jid' attribute that specifies the JabberID of the item to be added, MAY possess a 'name' attribute that specifies a natural-language name or nickname for the item, and MAY contain one or more <group/> elements specifying roster groups into which to place the item. If a &MESSAGE; stanza is sent, it MAY contain a &BODY; element but SHOULD NOT contain any other child elements. Here is an example:</p>
<p>In determining how to handle any given roster item whose 'action' attribute has a value of "add" (either explicitly or as the default value), the receiving application SHOULD proceed as follows:</p>
<ol>
<li>If the item already exists in the roster and the item is in the specified group (or no group is specified), the receiving application MUST NOT prompt a human user for approval regarding that item and MUST NOT add that item to the roster.</li>
<li>If the item does not already exist in the roster, the receiving application SHOULD prompt a human user for approval regarding that item and, if approval is granted, MUST add that item to the roster.</li>
<li>If the item already exists in the roster but not in the specified group, the receiving application MAY prompt the user for approval and SHOULD edit the existing item so that will also belong to the specified group (in addition to the existing group, if any).</li>
</ol>
<p>If the roster item addition stanza will result in adding the item to the roster, the receiving application MUST (either with approval by a human user or automatically subject to configuration) send a roster set to the user's server containing the new item as described in <cite>RFC 3921</cite>. After completing the roster set, the receiving application SHOULD also send a &PRESENCE; stanza of type "subscribe" to the JID of the new item.</p>
<p>For a description of the recommended application behavior when a roster item addition stanza actually results in editing of an existing roster item, refer to the <linkurl='#modify'>Suggesting Roster Item Modification</link> section of this document.</p>
<p>In order to programatically suggest that the receiving entity should delete one or more items from its roster, the sending entity MUST send a &MESSAGE; or &IQ; stanza containing an &X; element qualified by the 'http://jabber.org/protocol/rosterx' namespace; the &X; element in turn MUST contain one or more <item/> child elements, each of which MUST possess an 'action' attribute whose value is "delete", MUST possess a 'jid' attribute that specifies the JabberID of the item to be deleted, MAY possess a 'name' attribute that specifies a natural-language name or nickname for the item, and MAY contain one or more <group/> elements specifying roster groups for the item. If a &MESSAGE; stanza is sent, it MAY contain a &BODY; element but SHOULD NOT contain any other child elements. Here is an example:</p>
<p>In determining how to handle any given roster item whose 'action' attribute has a value of "delete", the receiving application SHOULD proceed as follows:</p>
<ol>
<li>If the item does not exist in the roster, the receiving application MUST NOT prompt a human user for approval regarding that item and MUST NOT delete that item from the roster.</li>
<li>If the item exists in the roster but not in the specified group, the receiving application MUST NOT prompt the user for approval and MUST NOT delete the existing item.</li>
<li>If the item exists in the roster and is in both the specified group and another group, the receiving application MAY prompt the user for approval and SHOULD edit the existing item so that it no longer belongs to the specified group.</li>
</ol>
<p>If the item is to be deleted, the receiving application SHOULD remove the item from the roster by sending a roster set to the user's server with the 'subscription' attribute set to a value of "remove" as described in <cite>RFC 3921</cite>, since this results in generation of the appropriate &PRESENCE; stanzas by the user's server.</p>
<p>In order to programatically suggest that the receiving entity should modify one or more items from its roster, the sending entity MUST send a &MESSAGE; or &IQ; stanza containing an &X; element qualified by the 'http://jabber.org/protocol/rosterx' namespace; the &X; element in turn MUST contain one or more <item/> child elements, each of which MUST possess an 'action' attribute whose value is "modify", MUST possess a 'jid' attribute that specifies the JabberID of the item to be modified, MAY possess a 'name' attribute that specifies a natural-language name or nickname for the item, and MAY contain one or more <group/> elements specifying roster groups into which to place the item. If a &MESSAGE; stanza is sent, it MAY contain a &BODY; element but SHOULD NOT contain any other child elements. Here is an example:</p>
<p>In determining how to handle any given roster item whose 'action' attribute has a value of "modify", the receiving application SHOULD proceed as follows:</p>
<ol>
<li>If the item does not exist in the roster, the receiving application MUST NOT prompt a human user for approval regarding that item and MUST NOT add that item to the roster.</li>
<li>If the item exists in the roster and the modification results in a change of group only, the receiving application MAY prompt the user for approval and SHOULD move the item to the specified group.</li>
<li>If the item exists in the roster and the modification results in adding the item to a new group in addition to its existing group, the receiving application MAY prompt the user for approval and SHOULD add the item to the specified group.</li>
<li>If the item exists in the roster and the modification results in a change of name only, the receiving application MAY prompt the user for approval and SHOULD modify the name to that specified in the modification suggestion.</li>
</ol>
<p>If a roster item addition, deletion, or modification stanza will result in editing of an existing item in the roster, the receiving application MUST (either with approval by a human user or automatically subject to configuration) send a roster set to the user's server with no changes to the 'subscription' attribute but rather with appropriate changes to the value of 'name' attribute or the <group/> child element or elements, as described in <cite>RFC 3921</cite>.</p>
<p>In order to determine whether a receiving entity supports the protocol defined herein, the sending entity SHOULD use &xep0030; but MAY depend on the "profile" of Service Discovery defined in &xep0115;. If an entity supports roster item exchange, it MUST (subject to appropriate security considerations as described under <linkurl='#security-support'>Advertising Support</link>) include <feature var='http://jabber.org/protocol/rosterx'/> in its responses to disco#info queries. Thus a sending entity can discover if a receiving entity supports the protocol defined herein by sending an IQ request of the following form:</p>
<p>If the sending entity has knowledge (e.g., via presence or an active chat conversation) that the receiving entity is online and available, it SHOULD: <note>If the receiving entity has more than one available resource, the sending application SHOULD communicate with the "most available" resource according its best estimation (e.g., the resource with the highest priority).</note></p>
<ol>
<li>Discover if the receiving entity supports the protocol defined herein (see the <linkurl='#disco'>Service Discovery</link> section of this document).</li>
<li>If so, send its roster item exchange stanza to a particular resource (user@host/resource) of the receiving entity using an &IQ; stanza rather than a &MESSAGE; stanza.</li>
</ol>
<p>If the sending entity does not know that the receiving entity is online and available, it MUST send a &MESSAGE; stanza to the receiving entity's "bare JID" (user@host) rather than an &IQ; stanza to a particular resource.</p>
<section2topic='IQ Semantics'anchor='stanza-iq'>
<p>If the sending entity uses &IQ; stanzas to communicate its roster item exchange suggestions, the receiving entity MUST adhere to the IQ semantics defined in &xmppcore;. Specifically:</p>
<ol>
<li>If the receiving entity successfully processes the suggested action(s) (which may include ignoring certain suggestions), the receiving entity MUST return an empty IQ result to the sending entity.</li>
<li>If the receiving entity does not understand the roster item exchange namespace, the receiving entity MUST return an error to the sending entity, which error SHOULD be &unavailable;.</li>
<li>If the receiving entity will not process the suggested action(s) because the receiving entity is not registered with the sending entity, the receiving entity MUST return an error to the sending entity, which error SHOULD be ®istration;.</li>
<li>If the receiving entity will not process the suggested action(s) because the sending entity is not in the receiving entity's roster, the receiving entity MUST return an error to the sending entity, which error SHOULD be ¬authorized;.</li>
<li>If the receiving entity will not process the suggested action(s) because the sending entity is not trusted (see <linkurl='#security-trust'>Trusted Entities</link>), the receiving entity MUST return an error to the sending entity, which error SHOULD be &forbidden;.</li>
</ol>
<p>Naturally, other IQ errors may be more appropriate; however, if the receiving entity will not or cannot process the suggested action(s), it MUST return an error to the sending entity.</p>
</section2>
</section1>
<section1topic='Business Rules'anchor='bizrules'>
<ol>
<li><p>The sending entity or sending application MUST NOT send additions, deletions, and modifications in the same &X; element and &MESSAGE; or &IQ; stanza; instead, it SHOULD send separate stanzas for the additions, deletions, and modifications.</p></li>
<li><p>If approval is required or recommended regarding more than one item suggested by the sending entity, the receiving entity SHOULD present all of the items for approval at the same time or in the same interface.</p></li>
<li><p>If the sending entity is in some sense "trusted" (see <linkurl='#security-trust'>Trusted Entities</link>), then the receiving application MAY skip the approval steps described above.</p></li>
<li><p>The receiving application SHOULD NOT accept an unreasonable number of roster items from any one sending entity at one time. Unfortunately, it can be difficult to determine how many roster items count as "unreasonable". For example, when a user registers with a gateway, it is possible that the initial set of roster items may be quite large (however, note that most existing consumer IM services enforce a limit of 100 to 150 items in their contact lists). Users who have newly registered with or been newly created on a server (e.g., within an organization) may also receive a large set of initial roster items in order to sync up with shared groups established on the server. However, after such initialization, the subsequent roster item sets should be much smaller. In any case, sets of more than 150 or 200 roster items SHOULD be treated with suspicion, and entities that repeatedly send such sets SHOULD NOT be trusted.</p></li>
</ol>
</section1>
<section1topic='Types of Sending Entities'anchor='entities'>
<p>The foregoing protocol description speaks only of "sending entities" and does not differentiate between different types of sending entities. However, it is envisioned that roster items will be sent to receiving entities by three different kinds of senders:</p>
<p>Roster item exchange as developed within the early Jabber community and documented in XEP-0093 was used to send a roster item from one user to another in a manner more structured than simply typing a third party's JID in a chat window. This usage is still encouraged. However, if the sender is a human user and/or the sending application has a primary <cite>Service Discovery</cite> category of "client" (e.g., a bot) <note>See <<linkurl='http://www.xmpp.org/registrar/disco-categories.html#client'>http://www.xmpp.org/registrar/disco-categories.html#client</link>>.</note>, the sending application SHOULD NOT specify an 'action' attribute other than "add", the receiving application MAY ignore values of the 'action' attribute other than "add", and the receiving application MUST prompt a human user regarding whether to add the suggested item or items to the user's roster.</p>
<p>The nature of client proxy gateways (i.e., entities with a service discovery category of "gateway") is specified more fully in &xep0100;. Herein we describe how such gateways should use roster item exchange, and how receiving applications should treat roster items received from such gateways.</p>
<p>In order to make use of a gateway's protocol translation service, a user MUST first register with the gateway. If the gateway advertises support for a service discovery feature of 'http://jabber.org/protocol/rosterx', then the user's client SHOULD expect that it may receive roster item suggestions from the gateway. In order to maintain synchronization between the user's contact list on a legacy IM service and the user's Jabber roster, the gateway SHOULD send roster items with an 'action' attribute of "add", "delete", or "modify" as appropriate, and the receiving application SHOULD process such roster item suggestions. Such processing MAY occur automatically (i.e., without the user's approval of each roster item or batch of roster items) if and only if the receiving application has explicitly informed the user that it will automatically process roster items from the gateway. Furthermore, the receiving application SHOULD periodically verify automatic processing with the user (e.g., once per session in which the gateway sends roster item suggestions to the user).</p>
<p>There is a third category of entities that might initiate roster item exchanges, which we label a "group service" and identify by a <cite>Service Discovery</cite> category of "directory" and type of "group". A group service enables an administrator to centrally define and administer roster groups so that they can be shared among a user population in an organized fashion. Such a service could prove useful in enterprise environments
<note>For example, when Alice is hired by the marketing department of Big Company Enterprises, it makes sense for her to automatically have the other members of the marketing department in her roster the first time she logs in, and for the rest of the marketing department to have Alice in their rosters as soon as her account has been set up. Similarly, when Bob in logistics gets fired, it makes sense for him to disappear from the rosters of everyone else in the logistics department.</note>
and other settings where it is beneficial to synchronize rosters across individuals (e.g., schools, social networking applications, consumer IM services, and anywhere else that it is important to build and manage small communities of users).</p>
<p>In some contexts, an IM server could function as a group service (e.g., if there is a single server deployed on a small company intranet); in other contexts, it may make more sense to deploy a standalone group service (e.g., in a larger or more heterogeneous environment with users on multiple servers). In both cases, the group service MUST advertise a service discovery identity of "directory/group" and SHOULD use the protocol specified herein to communicate changes ("add", "delete", and "modify") to the relevant shared groups; in addition, a user MUST first register with the service (either over Jabber via &xep0077; or out of band, e.g., via the web) or be otherwise provisioned to use the service (e.g., by a system administrator) before accepting roster item suggestions from the service.</p>
<p>If the user has registered with a group service or been otherwise provisioned to use a group service, the receiving application SHOULD process roster item suggestions received from the service. Such processing MAY occur automatically (i.e., without the user's approval of each roster item or batch of roster items) if and only if the receiving application has explicitly informed the user that it will automatically process roster items from the service. Furthermore, the receiving application SHOULD periodically verify automatic processing with the user (e.g., once per session in which the service sends roster item suggestions to the user).</p>
<p>A principal (user) or receiving application MAY establish a list of trusted entities from which roster item exchanges are processed automatically, i.e., without explicit approval by a human user. In order to avoid corruption of the roster, it is STRONGLY RECOMMENDED that such trusted entities be limited to gateways and group services as defined above. In addition, the receiving application SHOULD periodically verify such automatic processing with the principal, e.g., once per session in which the trusted entity sends roster item suggestions to the user.</p>
</section2>
<section2topic='Denial of Service'anchor='security-dos'>
<p>A sending entity could effectively deny service to the receiving entity by rapidly and repeatedly sending (1) alternating add and delete suggestions or (2) modify suggestions, thus invoking throttling mechanisms enforced by the receiving entity's server. The receiving application SHOULD guard against this by monitoring roster item exchanges received from each sending entity and refusing or ignoring roster item exchanges from offending entities (e.g., by adding such entities to a list of distrusted entities).</p>
<p>A receiving application MAY refuse to advertise its support for the roster item exchange protocol (see the <linkurl='#disco'>Service Discovery</link> section of this document) to entities that that are (1) not explicitly trusted or (2) explicitly distrusted.</p>
<p>The XMPP Registrar includes a <cite>Service Discovery</cite> type of "group" under the "directory" category in its registry of service discovery identities.</p>
