<abstract>This specification defines an XMPP protocol extension for enabling or disabling communication with other entities on a network. The protocol, which was first standardized in Section 10 of RFC 3921, can be used to block communication with unknown or undesirable entities. Blocking can be based on Jabber Identifier, subscription state, or roster group. The blocked stanzas can be messages, IQs, inbound or outbound presence stanzas, or all stanzas. The protocol also enables an entity to create, modify, or delete its privacy lists, apply different lists to different connected resources, define a default list, and decline the use of any privacy list during a particular communications session.</abstract>
<remark><p>Modified message stanza handling (server should return <service-unavailable/> error) and added implementation note to maintain consistency with XEP-0191.</p></remark>
<remark><p>Copied Section 10 of RFC 3921.</p></remark>
</revision>
<revision>
<version>1.3</version>
<date>2004-07-26</date>
<initials>psa</initials>
<remark><p>Formally retracted this proposal in favor of XMPP IM.</p></remark>
</revision>
<revision>
<version>1.2</version>
<date>2003-03-12</date>
<initials>psa</initials>
<remark><p>Changed status to Deprecated since this protocol is now included in the XMPP IM Internet-Draft.</p></remark>
</revision>
<revision>
<version>1.1</version>
<date>2002-11-17</date>
<initials>pgm</initials>
<remark><p>Added remarks about default handling, and where list processing should take place.</p></remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-10-22</date>
<initials>psa</initials>
<remark><p>Changed status to Draft.</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2002-10-03</date>
<initials>pgm</initials>
<remark><p>Elaborated on various JID possibilities.</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-07-31</date>
<initials>pgm</initials>
<remark><p>Added info describing current session issues</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-07-30</date>
<initials>pgm</initials>
<remark><p>Added whitelists, subscription filtering, and multiple list capabilities. Changed block to deny.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-01-18</date>
<initials>pgm</initials>
<remark><p>Initial version.</p></remark>
</revision>
</header>
<section1topic="Introduction">
<p>Almost all types of Instant Messaging (IM) applications have found it necessary to develop some method for a user to block the receipt of messages and packets from other users (the rationale for such blockage depends on the needs of the individual user). This document defines a flexible method for communications blocking.</p>
<p><em>This section has been copied without modification from Section 10 of &rfc3921;, with the exception of the message stanza handling rule in the <linkurl='#protocol-error'>Blocked Entity Attempts to Communicate with User</link> subsection.</em></p>
<p>Most instant messaging systems have found it necessary to implement some method for users to block communications from particular other users (this is also required by sections 5.1.5, 5.1.15, 5.3.2, and 5.4.10 of &rfc2779;. In XMPP this is done by managing one's privacy lists using the 'jabber:iq:privacy' namespace.</p>
<p>Server-side privacy lists enable successful completion of the following use cases:</p>
<ul>
<li>Retrieving one's privacy lists.</li>
<li>Adding, removing, and editing one's privacy lists.</li>
<li>Setting, changing, or declining active lists.</li>
<li>Setting, changing, or declining the default list (i.e., the list that is active by default).</li>
<li>Allowing or blocking messages based on JID, group, or subscription type (or globally).</li>
<li>Allowing or blocking inbound presence notifications based on JID, group, or subscription type (or globally).</li>
<li>Allowing or blocking outbound presence notifications based on JID, group, or subscription type (or globally).</li>
<li>Allowing or blocking IQ stanzas based on JID, group, or subscription type (or globally).</li>
<li>Allowing or blocking all communications based on JID, group, or subscription type (or globally).</li>
</ul>
<p>Note: Presence notifications do not include presence subscriptions, only presence information that is broadcasted to entities that are subscribed to a user's presence information. Thus this includes presence stanzas with no 'type' attribute or of type='unavailable' only.</p>
<section2topic="Syntax and Semantics"anchor="protocol-syntax">
<p>A user MAY define one or more privacy lists, which are stored by the user's server. Each <list/> element contains one or more rules in the form of <item/> elements, and each <item/> element uses attributes to define a privacy rule type, a specific value to which the rule applies, the relevant action, and the place of the item in the processing order.</p>
<p>If the type is "group", then the 'value' attribute SHOULD contain the name of a group in the user's roster. (If a client attempts to update, create, or delete a list item with a group that is not in the user's roster, the server SHOULD return to the client an <item-not-found/> stanza error.)</p>
<p>If the type is "subscription", then the 'value' attribute MUST be one of "both", "to", "from", or "none" as defined <cite>RFC 3921</cite>, where "none" includes entities that are totally unknown to the user and therefore not in the user's roster at all.</p>
<p>If no 'type' attribute is included, the rule provides the "fall-through" case.</p>
<p>The 'action' attribute MUST be included and its value MUST be either "allow" or "deny". <note>An implementation MUST NOT block communications from one of a user's resources to another, even if the user happens to define a rule that would otherwise result in that behavior.</note></p>
<p>The 'order' attribute MUST be included and its value MUST be a non-negative integer that is unique among all items in the list. (If a client attempts to create or update a list with non-unique order values, the server MUST return to the client a <bad-request/> stanza error.)</p>
<p>The <item/> element MAY contain one or more child elements that enable an entity to specify more granular control over which kinds of stanzas are to be blocked (i.e., rather than blocking all stanzas). The allowable child elements are:</p>
<p>Within the 'jabber:iq:privacy' namespace, the <query/> child of an IQ stanza of type "set" MUST NOT include more than one child element (i.e., the stanza MUST contain only one <active/> element, one <default/> element, or one <list/> element); if a sending entity violates this rule, the receiving entity MUST return a <bad-request/> stanza error.</p>
<p>When a client adds or updates a privacy list, the <list/> element SHOULD contain at least one <item/> child element; when a client removes a privacy list, the <list/> element MUST NOT contain any <item/> child elements.</p>
<p>When a client updates a privacy list, it must include all of the desired items (i.e., not a "delta").</p>
<li><p>If there is an active list set for a session, it affects only the session(s) for which it is activated, and only for the duration of the session(s); the server MUST apply the active list only and MUST NOT apply the default list (i.e., there is no "layering" of lists).</p></li>
<li><p>The default list applies to the user as a whole, and is processed if there is no active list set for the target session/resource to which a stanza is addressed, or if there are no current sessions for the user.</p></li>
<li><p>If there is no active list set for a session (or there are no current sessions for the user), and there is no default list, then all stanzas SHOULD BE accepted or appropriately processed by the server on behalf of the user in accordance with the server rules for handling XML stanzas defined in <cite>RFC 3921</cite>.</p></li>
<li><p>Privacy lists MUST be the first delivery rule applied by a server, superseding (1) the routing and delivery rules specified in server rules for handling XML stanzas defined in <cite>RFC 3921</cite> and (2) the handling of subscription-related presence stanzas (and corresponding generation of roster pushes) specified in <cite>RFC 3921</cite>.</p></li>
<li><p>The order in which privacy list items are processed by the server is important. List items MUST be processed in ascending order determined by the integer values of the 'order' attribute for each <item/>.</p></li>
<li><p>As soon as a stanza is matched against a privacy list rule, the server MUST appropriately handle the stanza in accordance with the rule and cease processing.</p></li>
<li><p>If no fall-through item is provided in a list, the fall-through action is assumed to be "allow".</p></li>
<li><p>If a user updates the definition for an active list, subsequent processing based on that active list MUST use the updated definition (for all resources to which that active list currently applies).</p></li>
<li><p>If a change to the subscription state or roster group of a roster item defined in an active or default list occurs during a user's session, subsequent processing based on that list MUST take into account the changed state or group (for all resources to which that list currently applies).</p></li>
<li><p>When the definition for a rule is modified, the server MUST send an IQ stanza of type "set" to all connected resources, containing a <query/> element with only one <list/> child element, where the 'name' attribute is set to the name of the modified privacy list. These "privacy list pushes" adhere to the same semantics as the "roster pushes" used in roster management, except that only the list name itself (not the full list definition or the "delta") is pushed to the connected resources. It is up to the receiving resource to determine whether to retrieve the modified list definition, although a connected resource SHOULD do so if the list currently applies to it.</p></li>
<li><p>When a resource attempts to remove a list or specify a new default list while that list applies to a connected resource other than the sending resource, the server MUST return a <conflict/> error to the sending resource and MUST NOT make the requested change.</p></li>
<p>In this example, the user has three lists: (1) 'public', which allows communications from everyone except one specific entity (this is the default list); (2) 'private', which allows communications only with contacts who have a bidirectional subscription with the user (this is the active list); and (3) 'special', which allows communications only with three specific entities.</p>
<p>If the user attempts to retrieve a list but a list by that name does not exist, the server MUST return an <item-not-found/> stanza error to the user:</p>
<examplecaption='Client attempts to retrieve non-existent list'><![CDATA[
<p>The user is allowed to retrieve only one list at a time. If the user attempts to retrieve more than one list in the same request, the server MUST return a <bad request/> stanza error to the user:</p>
<examplecaption='Client attempts to retrieve more than one list'><![CDATA[
<section2topic="Managing Active Lists"anchor="protocol-active">
<p>In order to set or change the active list currently being applied by the server, the user MUST send an IQ stanza of type "set" with a <query/> element qualified by the 'jabber:iq:privacy' namespace that contains an empty <active/> child element possessing a 'name' attribute whose value is set to the desired list name.</p>
<examplecaption='Client requests change of active list'><![CDATA[
<p>If the user attempts to set an active list but a list by that name does not exist, the server MUST return an <item-not-found/> stanza error to the user:</p>
<examplecaption='Client attempts to set a non-existent list as active'><![CDATA[
<section2topic="Managing the Default List"anchor="protocol-default">
<p>In order to change its default list (which applies to the user as a whole, not only the sending resource), the user MUST send an IQ stanza of type "set" with a <query/> element qualified by the 'jabber:iq:privacy' namespace that contains an empty <default/> child element possessing a 'name' attribute whose value is set to the desired list name.</p>
<examplecaption='User requests change of default list'><![CDATA[
<p>If the user attempts to change which list is the default list but the default list is in use by at least one connected resource other than the sending resource, the server MUST return a <conflict/> stanza error to the sending resource:</p>
<examplecaption='Client attempts to change the default list but that list is in use by another resource'><![CDATA[
<p>If the user attempts to set a default list but a list by that name does not exist, the server MUST return an <item-not-found/> stanza error to the user:</p>
<examplecaption='Client attempts to set a non-existent list as default'><![CDATA[
<p>In order to decline the use of a default list (i.e., to use the domain's stanza routing rules at all times), the user MUST send an empty <default/> element with no 'name' attribute.</p>
<examplecaption='Client declines the use of the default list'><![CDATA[
<p>If one connected resource attempts to decline the use of a default list for the user as a whole but the default list currently applies to at least one other connected resource, the server MUST return a <conflict/> error to the sending resource:</p>
<examplecaption='Client attempts to decline a default list but that list is in use by another resource'><![CDATA[
<section2topic="Editing a Privacy List"anchor="protocol-edit">
<p>In order to edit a privacy list, the user MUST send an IQ stanza of type "set" with a <query/> element qualified by the 'jabber:iq:privacy' namespace that contains one <list/> child element possessing a 'name' attribute whose value is set to the list name the user would like to edit. The <list/> element MUST contain one or more <item/> elements, which specify the user's desired changes to the list by including all elements in the list (not the "delta").</p>
<examplecaption='Client edits a privacy list'><![CDATA[
<p>Note: The value of the 'order' attribute for any given item is not fixed. Thus in the foregoing example if the user would like to add 4 items between the "tybalt@example.com" item and the "paris@example.org" item, the user's client MUST renumber the relevant items before submitting the list to the server.</p>
<p>The server MUST now send a "privacy list push" to all connected resources:</p>
<examplecaption='Privacy list push on list edit'><![CDATA[
<p>In accordance with the semantics of IQ stanzas defined in &rfc3920;, each connected resource MUST return an IQ result to the server as well:</p>
<examplecaption='Acknowledging receipt of privacy list pushes'><![CDATA[
<iqfrom='romeo@example.net/orchard'
type='result'
id='push1'/>
<iqfrom='romeo@example.net/home'
type='result'
id='push2'/>
]]></example>
</section2>
<section2topic="Adding a New Privacy List"anchor="protocol-add">
<p>The same protocol used to edit an existing list is used to create a new list. If the list name matches that of an existing list, the request to add a new list will overwrite the old one. As with list edits, the server MUST also send a "privacy list push" to all connected resources.</p>
</section2>
<section2topic="Removing a Privacy List"anchor="protocol-remove">
<p>In order to remove a privacy list, the user MUST send an IQ stanza of type "set" with a <query/> element qualified by the 'jabber:iq:privacy' namespace that contains one empty <list/> child element possessing a 'name' attribute whose value is set to the list name the user would like to remove.</p>
<examplecaption='Client removes a privacy list'><