Note: This JEP has been superseded by &xmppim;; please refer to that document for the most up-to-date protocol!

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). The method for implementing this functionality in the current Jabber system is for each client application to keep its own "blacklist" of the Jabber IDs from which the user does not wish to receive messages. This current implementation has the following drawbacks:

1. The XML packets are blocked at the client network endpoint. The unwanted packets need to traverse the entire Jabber network before they are blocked from being delivered. However, these packets could be blocked at the server and never delivered "across the wire" to the client, which becomes especially important for clients that have bandwidth restrictions or in situations where bandwidth is expensive.
2. Currently there exists no Jabber standard enabling clients to share their individual blacklists. Thus blacklist entries are not portable across clients and if a user accesses their account with a different client, the user must re-enter the blacklist entries.
3. Most implementations have no way of blocking specific types of packets -- they typically block only message packets.

The solution to these shortfalls is to have a common blacklist which is stored on the Jabber server along with the other information which clients receive from the server (primarily the roster).

This document proposes the addition of a new namespace to handle the storage and retrieval of the server-side blacklist and whitelist information. The proposed 'jabber:iq:privacy' namespace would be consistent with the existing jabber:* namespaces and use the <query/> element as a direct child under the main <iq/> element. A client application would use <iq type="get"> to retrieve the lists from the server, and use <iq type="set"> to add or edit items in a specific list. Each list is a combination of multiple items. Each item can be of type allow or deny. For this document, these lists will be called "zebra lists".

Each <query/> element would have one or more <list> elements which would contain the information for an entire zebra list. The <query> element also contains an <active> element and a <default> element. These elements contain the name of the currently active zebra list or the name of the default zebra list. A client application may perform a get request with an empty <active> element and/or and empty <default> which indicates that it only wants to know which list is currently active or the default list. A client application may also specify a default list to be used for offline processing and when no active list is directly specified. To fetch the currently active list and the rules for each list, the client application performs a simple blank get request.

The <default> element is used when processing packets and the client is offline, and is used whenver the client connection (session) does not specify a specific list to be active.

Each <item> element in the zebra list MAY contain a jid attribute (the Jabber ID, i.e. user@host, of the contact which is to be blocked or allowed), MAY contain a subscription attribute, and MUST contain a type attribute. If no jid attribute is specified, then the rule MUST apply to all jids. The possible values of the type attribute would be either "deny", "allow". To remove items from the list, simply send back the list tag with the various <item> elements missing.

If the <item> element contains a subscription attribute, it means that the rule applies to all jids in the current users roster which have matching subscription elements. Note that a subscription of "both" MUST be treated the same as "from" and "to" together.

If the <item> element contains no child elements, then all packets would be blocked or allowed. This includes: messages, presence packets, and iq packets. The <item> elements MAY contain the following empty child elements:

• The <message/> element (blocks or allows all message packets).
• The <presence/> element (blocks or allows all presence packets).
• The <iq/> element (blocks or allows all iq packets).

When a message or other XML packet is blocked according to the entries in the list, the server MUST bounce the packet back to the original sender. The bounced packet MUST be of type="error" and contain a child <error/> element with a code attribute of 405.

If a <list> element is sent that contains no child elements, the list of that name is removed. If the active list is not reset during the list removal, and the list removed was the active list, the user is returned back to a default state of allow all packets.

Setting your active zebra list is effective for the current session only, but the storage of the lists is for the user. During usage, a client application should set the active list before sending available presence or fetching the roster. If a client does not set the active zebra list for the current session, the default rules of allowing all packets would apply to that session.

When changing or editing in a specific zebra list, the client application MUST send back all items in the list in the desired order. Server side components that are performing the packet filtering MUST preserve the order of the individual <item> tags and process the rules in that order. All lists MUST have at least one rule that SHOULD specify the default action. The client application MAY send back an <active> element indicating the new currently active list. If no <active> element is sent, the currently active list is used.

When a client application wishes to just change the currently active zebra list, they MUST NOT send back all of the lists and their contents. The client application SHOULD send back just the new <active> element. If the named list does not exist, the server MUST send back an error using error code 406 (Not Acceptable).

Client applications can NOT set the default or active list, and alter the actual lists in the same packet. If a client connection attempts to modify both things at once, the server implementation must send back a iq-error using error code 406.

Implementations of zebra lists MAY choose to allow specific packet types to be checked. If a client attempts to set an item with a specific packet type (message, presence, or iq) and the implementation does not support that feature, the server MUST send back the <iq/> as a type="error" using an error code of 406 (Not Acceptable).

Implementation of zebra lists SHOULD NOT "push" new lists and additions to existing clients already connected using the same JID (as you would get jabber:iq:roster pushes). If a client application wants to know the current zebra list information, it SHOULD send a get request.

When a jabber ID is specified on a rule and the ID does not conform to user@host, the following rules apply:

• JIDs of the form 'domain.com' must apply to all users from that domain (ie, *@domain.com). Note that the asterisk (*) is a legal user character, thus, 'domain.com' is different from '*@domain.com'
• JIDs of the form 'user@domain.com/resource' apply to that specific resource. Packets from other resources from that user MUST not match the rule.
• JIDs of the form 'service.domain.com/resource' apply to that specific resource of that service. (As opposed to 'service.domain.com', which matches for '*@service.domain.com'.)

If a packet does not match any rules in the active list, the default action is to allow.

The following protocol segments illustrate the exchange of packets between the client application and the server in order to retrieve the zebra list information.

The following protocol segments illustrate the exchange of packets used to change the active zebra list.

The following protocol segments illustrate the exchange of packets used to add or edit a zebra list.

The following protocol segments illustrate how a client application would remove a zebra list.

The following protocol segments illustrate the exchange of message packets when the sender is blocked by the currently active zebra list.

In the future, it may be desirable at some point to allow clients to filter specific iq namespaces. The protocol could easily handle this capability by doing something like the following:

In the future, it may be desirable to have be able to block normal presence/availability packets, while still allowing subscription packets through the zebra list.

In the current open source Jabber server, there is a JSM module called mod_filter which has the capability to implement this type of functionality. However, most servers with large user bases have found it impossible to use mod_filter because of the load that it imposes on packet processing. Using normal whitelist/blacklist operations should make the processing much simpler than mod_filter's processing of an unknown set of rules various rules (not just blocking).

Peter Millard, the author of this specification from version 0.1 through version 0.3, died on April 26, 2006.