| "None + Pending In" | yes * | "None" |
| "None + Pending Out/In" | yes * | "None + Pending Out" |
| "To" | no | no state change |
| "To + Pending In" | yes * | "To" |
| "From" | yes * | "None" |
| "From + Pending Out" | yes * | "None + Pending Out |
| "Both" | yes * | "To" |
+------------------------------------------------------------------+
* Server SHOULD auto-reply with "unsubscribed" stanza
When the user’s server receives a presence stanza of type
"subscribed" for the user from the contact, it MUST NOT deliver the
stanza to the user and MUST NOT change the subscription state if
there is no pending outbound request for access to the contact’s
presence information. If there is a pending outbound request for
access to the contact’s presence information and the inbound presence
stanza of type "subscribed" results in a subscription state change,
the user’s server MUST deliver the stanza to the user and MUST change
the subscription state. If the user already has access to the
contact’s presence information, the inbound presence stanza of type
"subscribed" does not result in a subscription state change;
therefore the user’s server SHOULD NOT deliver the stanza to the user
and MUST NOT change the subscription state. These rules are
summarized in the following table.
Table 5: Recommended handling of inbound "subscribed" stanzas
+------------------------------------------------------------------+
| EXISTING STATE | DELIVER? | NEW STATE |
+------------------------------------------------------------------+
| "None" | no | no state change |
| "None + Pending Out" | yes | "To" |
| "None + Pending In" | no | no state change |
| "None + Pending Out/In" | yes | "To + Pending In" |
| "To" | no | no state change |
| "To + Pending In" | no | no state change |
| "From" | no | no state change |
| "From + Pending Out" | yes | "Both" |
| "Both" | no | no state change |
+------------------------------------------------------------------+
When the user’s server receives a presence stanza of type
"unsubscribed" for the user from the contact, it MUST deliver the
stanza to the user and MUST change the subscription state if there is
a pending outbound request for access to the contact’s presence
information or if the user currently has access to the contact’s
presence information. Otherwise, the user’s server SHOULD NOT
deliver the stanza and MUST NOT change the subscription state. These
rules are summarized in the following table.
Table 6: Recommended handling of inbound "unsubscribed" stanzas
+------------------------------------------------------------------+
| EXISTING STATE | DELIVER? | NEW STATE |
+------------------------------------------------------------------+
| "None" | no | no state change |
| "None + Pending Out" | yes | "None" |
| "None + Pending In" | no | no state change |
| "None + Pending Out/In" | yes | "None + Pending In" |
| "To" | yes | "None" |
| "To + Pending In" | yes | "None + Pending In" |
| "From" | no | no state change |
| "From + Pending Out" | yes | "From" |
| "Both" | yes | "From" |
+------------------------------------------------------------------+
9.4. Server Delivery and Client Acknowledgement of Subscription
Requests and State Change Notifications
When a server receives an inbound presence stanza of type "subscribe"
(i.e., a subscription request) or of type "subscribed",
"unsubscribe", or "unsubscribed" (i.e., a subscription state change
notification), in addition to sending the appropriate roster push (or
updated roster when the roster is next requested by an available
resource), it MUST deliver the request or notification to the
intended recipient at least once. A server MAY require the recipient
to acknowledge receipt of all state change notifications (and MUST
require acknowledgement in the case of subscription requests, i.e.,
presence stanzas of type "subscribe"). In order to require
acknowledgement, a server SHOULD send the request or notification to
the recipient each time the recipient logs in, until the recipient
acknowledges receipt of the notification by "affirming" or "denying"
the notification, as shown in the following table:
Table 7: Acknowledgement of subscription state change notifications
+--------------------------------------------------+
| STANZA TYPE | ACCEPT | DENY |
+--------------------------------------------------+
| subscribe | subscribed | unsubscribed |
| subscribed | subscribe | unsubscribe |
| unsubscribe | unsubscribed | subscribed |
| unsubscribed | unsubscribe | subscribe |
+--------------------------------------------------+
Obviously, given the foregoing subscription state charts, some of the
acknowledgement stanzas will be routed to the contact and result in
subscription state changes, while others will not. However, any such
stanzas MUST result in the server’s no longer sending the
subscription state notification to the user.
Because a user’s server MUST automatically generate outbound presence
stanzas of type "unsubscribe" and "unsubscribed" upon receiving a
roster set with the ’subscription’ attribute set to a value of
"remove" (see Removing a Roster Item and Cancelling All Subscriptions
(Section 8.6)), the server MUST treat a roster remove request as
equivalent to sending both of those presence stanzas for purposes of
determining whether to continue sending subscription state change
notifications of type "subscribe" or "subscribed" to the user.
10. Blocking Communication
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 [IMP-REQS]). In XMPP this is done by managing one’s
privacy lists using the ’jabber:iq:privacy’ namespace.
Server-side privacy lists enable successful completion of the
following use cases:
o Retrieving one’s privacy lists.
o Adding, removing, and editing one’s privacy lists.
o Setting, changing, or declining active lists.
o Setting, changing, or declining the default list (i.e., the list
that is active by default).
o Allowing or blocking messages based on JID, group, or subscription
type (or globally).
o Allowing or blocking inbound presence notifications based on JID,
group, or subscription type (or globally).
o Allowing or blocking outbound presence notifications based on JID,
group, or subscription type (or globally).
o Allowing or blocking IQ stanzas based on JID, group, or
subscription type (or globally).
o Allowing or blocking all communications based on JID, group, or
subscription type (or globally).
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.
10.1. Syntax and Semantics
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.
The syntax is as follows:
<iq>
<query xmlns=’jabber:iq:privacy’>
<list name=’foo’>
<item
type=’[jid|group|subscription]’
value=’bar’
action=’[allow|deny]’
order=’unsignedInt’>
[<message/>]
[<presence-in/>]
[<presence-out/>]
[<iq/>]
</item>
</list>
</query>
</iq>
If the type is "jid", then the ’value’ attribute MUST contain a valid
Jabber ID. JIDs SHOULD be matched in the following order:
1. <user@domain/resource> (only that resource matches)
2. <user@domain> (any resource matches)
3. <domain/resource> (only that resource matches)
4. <domain> (the domain itself matches, as does any user@domain,
domain/resource, or address containing a subdomain)
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.)
If the type is "subscription", then the ’value’ attribute MUST be one
of "both", "to", "from", or "none" as defined under Roster Syntax and
Semantics (Section 7.1), where "none" includes entities that are
totally unknown to the user and therefore not in the user’s roster at
all.
If no ’type’ attribute is included, the rule provides the
"fall-through" case.
The ’action’ attribute MUST be included and its value MUST be either
"allow" or "deny".
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.)
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:
o <message/> -- blocks incoming message stanzas
o <iq/> -- blocks incoming IQ stanzas
o <presence-in/> -- blocks incoming presence notifications
o <presence-out/> -- blocks outgoing presence notifications
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.
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.
When a client updates a privacy list, it must include all of the
desired items (i.e., not a "delta").
10.2. Business Rules
1. 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).
2. 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.
3. 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 (Section 11).
4. 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 (Section 11), and (2)
the handling of subscription-related presence stanzas (and
corresponding generation of roster pushes) specified in
Integration of Roster Items and Presence Subscriptions (Section
8).
5. 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/>.
6. 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.
7. If no fall-through item is provided in a list, the fall-through
action is assumed to be "allow".
8. 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).
9. 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).
10. 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.
11. 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.
10.3. Retrieving One’s Privacy Lists
Example: Client requests names of privacy lists from server:
<iq from=’romeo@example.net/orchard’ type=’get’ id=’getlist1’>
<query xmlns=’jabber:iq:privacy’/>
</iq>
Example: Server sends names of privacy lists to client, preceded by
active list and default list:
<iq type=’result’ id=’getlist1’ to=’romeo@example.net/orchard’>
<query xmlns=’jabber:iq:privacy’>
<active name=’private’/>
<default name=’public’/>
<list name=’public’/>
<list name=’private’/>
<list name=’special’/>
</query>
</iq>
Example: Client requests a privacy list from server:
<iq from=’romeo@example.net/orchard’ type=’get’ id=’getlist2’>
<query xmlns=’jabber:iq:privacy’>
<list name=’public’/>
</query>
</iq>
Example: Server sends a privacy list to client:
<iq type=’result’ id=’getlist2’ to=’romeo@example.net/orchard’>
<query xmlns=’jabber:iq:privacy’>
<list name=’public’>
<item type=’jid’
value=’tybalt@example.com’
action=’deny’
order=’1’/>
<item action=’allow’ order=’2’/>
</list>
</query>
</iq>
Example: Client requests another privacy list from server:
<iq from=’romeo@example.net/orchard’ type=’get’ id=’getlist3’>
<query xmlns=’jabber:iq:privacy’>
<list name=’private’/>
</query>
</iq>
Example: Server sends another privacy list to client:
<iq type=’result’ id=’getlist3’ to=’romeo@example.net/orchard’>
<query xmlns=’jabber:iq:privacy’>
<list name=’private’>
<item type=’subscription’
value=’both’
action=’allow’
order=’10’/>
<item action=’deny’ order=’15’/>
</list>
</query>
</iq>
Example: Client requests yet another privacy list from server:
<iq from=’romeo@example.net/orchard’ type=’get’ id=’getlist4’>
<query xmlns=’jabber:iq:privacy’>
<list name=’special’/>
</query>
</iq>
Example: Server sends yet another privacy list to client:
<iq type=’result’ id=’getlist4’ to=’romeo@example.net/orchard’>
<query xmlns=’jabber:iq:privacy’>
<list name=’special’>
<item type=’jid’
value=’juliet@example.com’
action=’allow’
order=’6’/>
<item type=’jid’
value=’benvolio@example.org’
action=’allow’
order=’7’/>
<item type=’jid’
value=’mercutio@example.org’
action=’allow’
order=’42’/>
<item action=’deny’ order=’666’/>
</list>
</query>
</iq>
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.
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:
Example: Client attempts to retrieve non-existent list:
<iq to=’romeo@example.net/orchard’ type=’error’ id=’getlist5’>
<query xmlns=’jabber:iq:privacy’>
<list name=’The Empty Set’/>
</query>
<error type=’cancel’>
<item-not-found
xmlns=’urn:ietf:params:xml:ns:xmpp-stanzas’/>
</error>
</iq>
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:
Example: Client attempts to retrieve more than one list:
<iq to=’romeo@example.net/orchard’ type=’error’ id=’getlist6’>
<query xmlns=’jabber:iq:privacy’>
<list name=’public’/>
<list name=’private’/>
<list name=’special’/>
</query>
<error type=’modify’>
<bad-request
xmlns=’urn:ietf:params:xml:ns:xmpp-stanzas’/>
</error>
</iq>
10.4. Managing Active Lists
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.
Example: Client requests change of active list:
<iq from=’romeo@example.net/orchard’ type=’set’ id=’active1’>
<query xmlns=’jabber:iq:privacy’>
<active name=’special’/>
</query>
</iq>
The server MUST activate and apply the requested list before sending
the result back to the client.
Example: Server acknowledges success of active list change:
<iq type=’result’ id=’active1’ to=’romeo@example.net/orchard’/>
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:
Example: Client attempts to set a non-existent list as active:
<iq to=’romeo@example.net/orchard’ type=’error’ id=’active2’>
<query xmlns=’jabber:iq:privacy’>
<active name=’The Empty Set’/>
</query>
<error type=’cancel’>
<item-not-found
xmlns=’urn:ietf:params:xml:ns:xmpp-stanzas’/>
</error>
</iq>
In order to decline the use of any active list, the connected
resource MUST send an empty <active/> element with no ’name’
attribute.
Example: Client declines the use of active lists:
<iq from=’romeo@example.net/orchard’ type=’set’ id=’active3’>
<query xmlns=’jabber:iq:privacy’>
<active/>
</query>
</iq>
Example: Server acknowledges success of declining any active list:
<iq type=’result’ id=’active3’ to=’romeo@example.net/orchard’/>
10.5. Managing the Default List
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.
Example: User requests change of default list:
<iq from=’romeo@example.net/orchard’ type=’set’ id=’default1’>
<query xmlns=’jabber:iq:privacy’>
<default name=’special’/>
</query>
</iq>
Example: Server acknowledges success of default list change:
<iq type=’result’ id=’default1’ to=’romeo@example.net/orchard’/>
If the user attempts to change which list is the default list but the