tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 6121

 Errata 
Proposed STD
Pages: 114
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: XMPP

Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence

Part 1 of 5, p. 1 to 15
None       Next RFC Part

Obsoletes:    3921


Top       ToC       Page 1 
Internet Engineering Task Force (IETF)                    P. Saint-Andre
Request for Comments: 6121                                         Cisco
Obsoletes: 3921                                               March 2011
Category: Standards Track
ISSN: 2070-1721


           Extensible Messaging and Presence Protocol (XMPP):
                     Instant Messaging and Presence

Abstract

   This document defines extensions to core features of the Extensible
   Messaging and Presence Protocol (XMPP) that provide basic instant
   messaging (IM) and presence functionality in conformance with the
   requirements in RFC 2779.  This document obsoletes RFC 3921.

Status of this Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 5741.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   http://www.rfc-editor.org/info/rfc6121.

Copyright Notice

   Copyright (c) 2011 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Top       Page 2 
Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   5
     1.1.  Overview  . . . . . . . . . . . . . . . . . . . . . . . .   5
     1.2.  History . . . . . . . . . . . . . . . . . . . . . . . . .   5
     1.3.  Requirements  . . . . . . . . . . . . . . . . . . . . . .   5
     1.4.  Functional Summary  . . . . . . . . . . . . . . . . . . .   7
     1.5.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   8
   2.  Managing the Roster . . . . . . . . . . . . . . . . . . . . .   9
     2.1.  Syntax and Semantics  . . . . . . . . . . . . . . . . . .   9
       2.1.1.  Ver Attribute . . . . . . . . . . . . . . . . . . . .  10
       2.1.2.  Roster Items  . . . . . . . . . . . . . . . . . . . .  10
         2.1.2.1.  Approved Attribute  . . . . . . . . . . . . . . .  10
         2.1.2.2.  Ask Attribute . . . . . . . . . . . . . . . . . .  10
         2.1.2.3.  JID Attribute . . . . . . . . . . . . . . . . . .  11
         2.1.2.4.  Name Attribute  . . . . . . . . . . . . . . . . .  11
         2.1.2.5.  Subscription Attribute  . . . . . . . . . . . . .  11
         2.1.2.6.  Group Element . . . . . . . . . . . . . . . . . .  12
       2.1.3.  Roster Get  . . . . . . . . . . . . . . . . . . . . .  12
       2.1.4.  Roster Result . . . . . . . . . . . . . . . . . . . .  13
       2.1.5.  Roster Set  . . . . . . . . . . . . . . . . . . . . .  14
       2.1.6.  Roster Push . . . . . . . . . . . . . . . . . . . . .  14
     2.2.  Retrieving the Roster on Login  . . . . . . . . . . . . .  16
     2.3.  Adding a Roster Item  . . . . . . . . . . . . . . . . . .  17
       2.3.1.  Request . . . . . . . . . . . . . . . . . . . . . . .  17
       2.3.2.  Success Case  . . . . . . . . . . . . . . . . . . . .  17
       2.3.3.  Error Cases . . . . . . . . . . . . . . . . . . . . .  18
     2.4.  Updating a Roster Item  . . . . . . . . . . . . . . . . .  22
       2.4.1.  Request . . . . . . . . . . . . . . . . . . . . . . .  22
       2.4.2.  Success Case  . . . . . . . . . . . . . . . . . . . .  24
       2.4.3.  Error Cases . . . . . . . . . . . . . . . . . . . . .  24
     2.5.  Deleting a Roster Item  . . . . . . . . . . . . . . . . .  24
       2.5.1.  Request . . . . . . . . . . . . . . . . . . . . . . .  24
       2.5.2.  Success Case  . . . . . . . . . . . . . . . . . . . .  25
       2.5.3.  Error Cases . . . . . . . . . . . . . . . . . . . . .  26
     2.6.  Roster Versioning . . . . . . . . . . . . . . . . . . . .  26
       2.6.1.  Stream Feature  . . . . . . . . . . . . . . . . . . .  26
       2.6.2.  Request . . . . . . . . . . . . . . . . . . . . . . .  26
       2.6.3.  Success Case  . . . . . . . . . . . . . . . . . . . .  27
   3.  Managing Presence Subscriptions . . . . . . . . . . . . . . .  30
     3.1.  Requesting a Subscription . . . . . . . . . . . . . . . .  30
       3.1.1.  Client Generation of Outbound Subscription Request  .  31
       3.1.2.  Server Processing of Outbound Subscription Request  .  32
       3.1.3.  Server Processing of Inbound Subscription Request . .  34
       3.1.4.  Client Processing of Inbound Subscription Request . .  35
       3.1.5.  Server Processing of Outbound Subscription Approval .  36
       3.1.6.  Server Processing of Inbound Subscription Approval  .  38

Top      ToC       Page 3 
     3.2.  Canceling a Subscription  . . . . . . . . . . . . . . . .  40
       3.2.1.  Client Generation of Subscription Cancellation  . . .  40
       3.2.2.  Server Processing of Outbound Subscription
               Cancellation  . . . . . . . . . . . . . . . . . . . .  40
       3.2.3.  Server Processing of Inbound Subscription
               Cancellation  . . . . . . . . . . . . . . . . . . . .  41
     3.3.  Unsubscribing . . . . . . . . . . . . . . . . . . . . . .  43
       3.3.1.  Client Generation of Unsubscribe  . . . . . . . . . .  43
       3.3.2.  Server Processing of Outbound Unsubscribe . . . . . .  43
       3.3.3.  Server Processing of Inbound Unsubscribe  . . . . . .  44
     3.4.  Pre-Approving a Subscription Request  . . . . . . . . . .  46
       3.4.1.  Client Generation of Subscription Pre-Approval  . . .  46
       3.4.2.  Server Processing of Subscription Pre-Approval  . . .  47
   4.  Exchanging Presence Information . . . . . . . . . . . . . . .  48
     4.1.  Presence Fundamentals . . . . . . . . . . . . . . . . . .  48
     4.2.  Initial Presence  . . . . . . . . . . . . . . . . . . . .  49
       4.2.1.  Client Generation of Initial Presence . . . . . . . .  49
       4.2.2.  Server Processing of Outbound Initial Presence  . . .  50
       4.2.3.  Server Processing of Inbound Initial Presence . . . .  50
       4.2.4.  Client Processing of Initial Presence . . . . . . . .  51
     4.3.  Presence Probes . . . . . . . . . . . . . . . . . . . . .  51
       4.3.1.  Server Generation of Outbound Presence Probe  . . . .  52
       4.3.2.  Server Processing of Inbound Presence Probe . . . . .  53
         4.3.2.1.  Handling of the 'id' Attribute  . . . . . . . . .  55
     4.4.  Subsequent Presence Broadcast . . . . . . . . . . . . . .  57
       4.4.1.  Client Generation of Subsequent Presence Broadcast  .  57
       4.4.2.  Server Processing of Subsequent Outbound Presence . .  57
       4.4.3.  Server Processing of Subsequent Inbound Presence  . .  58
       4.4.4.  Client Processing of Subsequent Presence  . . . . . .  59
     4.5.  Unavailable Presence  . . . . . . . . . . . . . . . . . .  59
       4.5.1.  Client Generation of Unavailable Presence . . . . . .  59
       4.5.2.  Server Processing of Outbound Unavailable Presence  .  59
       4.5.3.  Server Processing of Inbound Unavailable Presence . .  61
       4.5.4.  Client Processing of Unavailable Presence . . . . . .  62
     4.6.  Directed Presence . . . . . . . . . . . . . . . . . . . .  62
       4.6.1.  General Considerations  . . . . . . . . . . . . . . .  62
       4.6.2.  Client Generation of Directed Presence  . . . . . . .  63
       4.6.3.  Server Processing of Outbound Directed Presence . . .  63
       4.6.4.  Server Processing of Inbound Directed Presence  . . .  64
       4.6.5.  Client Processing of Inbound Directed Presence  . . .  64
       4.6.6.  Server Processing of Presence Probes  . . . . . . . .  64
     4.7.  Presence Syntax . . . . . . . . . . . . . . . . . . . . .  65
       4.7.1.  Type Attribute  . . . . . . . . . . . . . . . . . . .  65
       4.7.2.  Child Elements  . . . . . . . . . . . . . . . . . . .  66
         4.7.2.1.  Show Element  . . . . . . . . . . . . . . . . . .  66
         4.7.2.2.  Status Element  . . . . . . . . . . . . . . . . .  67
         4.7.2.3.  Priority Element  . . . . . . . . . . . . . . . .  68
       4.7.3.  Extended Content  . . . . . . . . . . . . . . . . . .  69

Top      ToC       Page 4 
   5.  Exchanging Messages . . . . . . . . . . . . . . . . . . . . .  69
     5.1.  One-to-One Chat Sessions  . . . . . . . . . . . . . . . .  69
     5.2.  Message Syntax  . . . . . . . . . . . . . . . . . . . . .  70
       5.2.1.  To Attribute  . . . . . . . . . . . . . . . . . . . .  70
       5.2.2.  Type Attribute  . . . . . . . . . . . . . . . . . . .  71
       5.2.3.  Body Element  . . . . . . . . . . . . . . . . . . . .  73
       5.2.4.  Subject Element . . . . . . . . . . . . . . . . . . .  74
       5.2.5.  Thread Element  . . . . . . . . . . . . . . . . . . .  75
     5.3.  Extended Content  . . . . . . . . . . . . . . . . . . . .  77
   6.  Exchanging IQ Stanzas . . . . . . . . . . . . . . . . . . . .  77
   7.  A Sample Session  . . . . . . . . . . . . . . . . . . . . . .  78
   8.  Server Rules for Processing XML Stanzas . . . . . . . . . . .  84
     8.1.  General Considerations  . . . . . . . . . . . . . . . . .  85
     8.2.  No 'to' Address . . . . . . . . . . . . . . . . . . . . .  85
     8.3.  Remote Domain . . . . . . . . . . . . . . . . . . . . . .  85
     8.4.  Local Domain  . . . . . . . . . . . . . . . . . . . . . .  86
     8.5.  Local User  . . . . . . . . . . . . . . . . . . . . . . .  86
       8.5.1.  No Such User  . . . . . . . . . . . . . . . . . . . .  86
       8.5.2.  localpart@domainpart  . . . . . . . . . . . . . . . .  86
         8.5.2.1.  Available or Connected Resources  . . . . . . . .  87
         8.5.2.2.  No Available or Connected Resources . . . . . . .  89
       8.5.3.  localpart@domainpart/resourcepart . . . . . . . . . .  90
         8.5.3.1.  Resource Matches  . . . . . . . . . . . . . . . .  90
         8.5.3.2.  No Resource Matches . . . . . . . . . . . . . . .  90
       8.5.4.  Summary of Message Delivery Rules . . . . . . . . . .  92
   9.  Handling of URIs  . . . . . . . . . . . . . . . . . . . . . .  93
   10. Internationalization Considerations . . . . . . . . . . . . .  94
   11. Security Considerations . . . . . . . . . . . . . . . . . . .  94
   12. Conformance Requirements  . . . . . . . . . . . . . . . . . .  95
   13. References  . . . . . . . . . . . . . . . . . . . . . . . . .  99
     13.1. Normative References  . . . . . . . . . . . . . . . . . .  99
     13.2. Informative References  . . . . . . . . . . . . . . . . .  99
   Appendix A.  Subscription States  . . . . . . . . . . . . . . . . 103
     A.1.  Defined States  . . . . . . . . . . . . . . . . . . . . . 103
     A.2.  Server Processing of Outbound Presence Subscription
           Stanzas . . . . . . . . . . . . . . . . . . . . . . . . . 104
       A.2.1.  Subscribe . . . . . . . . . . . . . . . . . . . . . . 105
       A.2.2.  Unsubscribe . . . . . . . . . . . . . . . . . . . . . 105
       A.2.3.  Subscribed  . . . . . . . . . . . . . . . . . . . . . 106
       A.2.4.  Unsubscribed  . . . . . . . . . . . . . . . . . . . . 106
     A.3.  Server Processing of Inbound Presence Subscription
           Stanzas . . . . . . . . . . . . . . . . . . . . . . . . . 106
       A.3.1.  Subscribe . . . . . . . . . . . . . . . . . . . . . . 107
       A.3.2.  Unsubscribe . . . . . . . . . . . . . . . . . . . . . 107
       A.3.3.  Subscribed  . . . . . . . . . . . . . . . . . . . . . 108
       A.3.4.  Unsubscribed  . . . . . . . . . . . . . . . . . . . . 109
   Appendix B.  Blocking Communication . . . . . . . . . . . . . . . 110
   Appendix C.  vCards . . . . . . . . . . . . . . . . . . . . . . . 110

Top      ToC       Page 5 
   Appendix D.  XML Schema for jabber:iq:roster  . . . . . . . . . . 110
   Appendix E.  Differences From RFC 3921  . . . . . . . . . . . . . 112
   Appendix F.  Acknowledgements . . . . . . . . . . . . . . . . . . 113

1.  Introduction

1.1.  Overview

   The Extensible Messaging and Presence Protocol (XMPP) is an
   application profile of the Extensible Markup Language [XML] that
   enables the near-real-time exchange of structured yet extensible data
   between any two or more network entities.  The core features of XMPP
   defined in [XMPP-CORE] provide the building blocks for many types of
   near-real-time applications, which can be layered on top of the core
   by sending application-specific data qualified by particular XML
   namespaces (refer to [XML-NAMES]).  This document defines XMPP
   extensions that provide the basic functionality expected of an
   instant messaging (IM) and presence application as described in
   [IMP-REQS].

1.2.  History

   The basic syntax and semantics of XMPP were developed originally
   within the Jabber open-source community, mainly in 1999.  In late
   2002, the XMPP Working Group was chartered with developing an
   adaptation of the core Jabber protocol that would be suitable as an
   IETF IM and presence technology in accordance with [IMP-REQS].  In
   October 2004, [RFC3920] and [RFC3921] were published, representing
   the most complete definition of XMPP at that time.

   Since 2004 the Internet community has gained extensive implementation
   and deployment experience with XMPP, including formal
   interoperability testing carried out under the auspices of the XMPP
   Standards Foundation (XSF).  This document incorporates comprehensive
   feedback from software developers and service providers, including a
   number of backward-compatible modifications summarized under
   Appendix E.  As a result, this document reflects the rough consensus
   of the Internet community regarding the IM and presence features of
   XMPP 1.0, thus obsoleting RFC 3921.

1.3.  Requirements

   Traditionally, IM applications have combined the following factors:

   1.  The central point of focus is a list of one's contacts or
       "buddies" (in XMPP this list is called a "roster").

Top      ToC       Page 6 
   2.  The purpose of using such an application is to exchange
       relatively brief text messages with particular contacts in close
       to real time -- often relatively large numbers of such messages
       in rapid succession, in the form of a one-to-one "chat session"
       as described under Section 5.1.

   3.  The catalyst for exchanging messages is "presence" -- i.e.,
       information about the network availability of particular contacts
       (thus knowing who is online and available for a one-to-one chat
       session).

   4.  Presence information is provided only to contacts that one has
       authorized by means of an explicit agreement called a "presence
       subscription".

   Thus at a high level this document assumes that a user needs to be
   able to complete the following use cases:

   o  Manage items in one's contact list

   o  Exchange messages with one's contacts

   o  Exchange presence information with one's contacts

   o  Manage presence subscriptions to and from one's contacts

   Detailed definitions of these functionality areas are contained in
   RFC 2779 [IMP-REQS], and the interested reader is referred to that
   document regarding in-depth requirements.  Although the XMPP IM and
   presence extensions specified herein meet the requirements of RFC
   2779, they were not designed explicitly with that specification in
   mind, since the base protocol evolved through an open development
   process within the Jabber open-source community before RFC 2779 was
   written.  Although XMPP protocol extensions addressing many other
   functionality areas have been defined in the XMPP Standards
   Foundation's XEP series (e.g., multi-user text chat as specified in
   [XEP-0045]), such extensions are not specified in this document
   because they are not mandated by RFC 2779.

      Implementation Note: RFC 2779 stipulates that presence services
      must be separable from IM services and vice-versa; i.e., it must
      be possible to use the protocol to provide a presence service, a
      messaging service, or both.  Although the text of this document
      assumes that implementations and deployments will want to offer a
      unified IM and presence service, it is not mandatory for an XMPP
      service to offer both a presence service and a messaging service,
      and the protocol makes it possible to offer separate and distinct

Top      ToC       Page 7 
      services for presence and for messaging.  (For example, a
      presence-only service could return a <service-unavailable/> stanza
      error if a client attempts to send a <message/> stanza.)

1.4.  Functional Summary

   This non-normative section provides a developer-friendly, functional
   summary of XMPP-based IM and presence features; consult the sections
   that follow for a normative definition of these features.

   [XMPP-CORE] specifies how an XMPP client connects to an XMPP server.
   In particular, it specifies the preconditions that need to be
   fulfilled before a client is allowed to send XML stanzas (the basic
   unit of meaning in XMPP) to other entities on an XMPP network.  These
   preconditions comprise negotiation of the XML stream and include
   exchange of XML stream headers, optional channel encryption via
   Transport Layer Security [TLS], mandatory authentication via Simple
   Authentication and Security Layer [SASL], and binding of a resource
   to the stream for client addressing.  The reader is referred to
   [XMPP-CORE] for details regarding these preconditions, and knowledge
   of [XMPP-CORE] is assumed herein.

      Interoperability Note: [RFC3921] specified one additional
      precondition: formal establishment of an instant messaging and
      presence session.  Implementation and deployment experience has
      shown that this additional step is unnecessary.  However, for
      backward compatibility an implementation MAY still offer that
      feature.  This enables older software to connect while letting
      newer software save a round trip.

   Upon fulfillment of the preconditions specified in [XMPP-CORE], an
   XMPP client has a long-lived XML stream with an XMPP server, which
   enables the user controlling that client to send and receive a
   potentially unlimited number of XML stanzas over the stream.  Such a
   stream can be used to exchange messages, share presence information,
   and engage in structured request-response interactions in close to
   real time.  After negotiation of the XML stream, the typical flow for
   an instant messaging and presence session is as follows:

   1.  Retrieve one's roster.  (See Section 2.2.)

   2.  Send initial presence to the server for broadcast to all
       subscribed contacts, thus "going online" from the perspective of
       XMPP communication.  (See Section 4.2.)

Top      ToC       Page 8 
   3.  Exchange messages, manage presence subscriptions, perform roster
       updates, and in general process and generate other XML stanzas
       with particular semantics throughout the life of the session.
       (See Sections 5, 3, 2, and 6.)

   4.  Terminate the session when desired by sending unavailable
       presence and closing the underlying XML stream.  (See
       Section 4.5.)

1.5.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in RFC
   2119 [KEYWORDS].

   This document inherits the terminology defined in [XMPP-CORE].

   The terms "automated client" and "interactive client" are to be
   understood in the sense defined in [TLS-CERTS].

   For convenience, this document employs the term "user" to refer to
   the owner of an XMPP account; however, account owners need not be
   humans and can be bots, devices, or other automated applications.

   Several other terms, such as "interested resource", are defined
   within the body of this document.

   Following the "XML Notation" used in [IRI] to represent characters
   that cannot be rendered in ASCII-only documents, some examples in
   this document use the form "&#x...." as a notational device to
   represent [UNICODE] characters (e.g., the string "&#x0159;" stands
   for the Unicode character LATIN SMALL LETTER R WITH CARON); this form
   is definitely not to be sent over the wire in XMPP systems.

   In examples, lines have been wrapped for improved readability,
   "[...]" means elision, and the following prepended strings are used
   (these prepended strings are not to be sent over the wire):

   o  C: = client

   o  CC: = contact's client

   o  CS: = contact's server

   o  S: = server

   o  UC: = user's client

Top      ToC       Page 9 
   o  US: = user's server

   Readers need to be aware that the examples are not exhaustive and
   that, in examples for some protocol flows, the alternate steps shown
   would not necessarily be triggered by the exact data sent in the
   previous step; in all cases, the protocol definitions specified in
   this document or in normatively referenced documents rule over any
   examples provided here.  All examples are fictional and the
   information exchanged (e.g., usernames and passwords) does not
   represent any existing users or servers.

2.  Managing the Roster

   In XMPP, a user's roster contains any number of specific contacts.  A
   user's roster is stored by the user's server on the user's behalf so
   that the user can access roster information from any device.  When
   the user adds items to the roster or modifies existing items, if an
   error does not occur then the server SHOULD store that data
   unmodified if at all possible and MUST return the data it has stored
   when an authorized client requests the roster.

      Security Warning: Because the user's roster can contain
      confidential data, the server MUST restrict access to this data so
      that only authorized entities (typically limited to the account
      owner) are able to retrieve, modify, or delete it.

   RFC 3921 assumed that the only place where a user stores their roster
   is the server where the user's account is registered and at which the
   user authenticates for access to the XMPP network.  This
   specification removes that strict coupling of roster storage to
   account registration and network authentication, with the result that
   a user could store their roster at another location, or could have
   multiple rosters that are stored in multiple locations.  However, in
   the absence of implementation and deployment experience with a more
   flexible roster storage model, this specification retains the
   terminology of RFC 3921 by using the terms "client" and "server" (and
   "the roster" instead of "a roster"), rather than coining a new term
   for "a place where a user stores a roster".  Future documents might
   provide normative rules for non-server roster storage or for the
   management of multiple rosters, but such rules are out of scope for
   this document.

2.1.  Syntax and Semantics

   Rosters are managed using <iq/> stanzas (see Section 8.2.3 of
   [XMPP-CORE]), specifically by means of a <query/> child element
   qualified by the 'jabber:iq:roster' namespace.  The detailed syntax
   and semantics are defined in the following sections.

Top      ToC       Page 10 
2.1.1.  Ver Attribute

   The 'ver' attribute is a string that identifies a particular version
   of the roster information.  The value MUST be generated only by the
   server and MUST be treated by the client as opaque.  The server can
   use any appropriate method for generating the version ID, such as a
   hash of the roster data or a strictly increasing sequence number.

   Inclusion of the 'ver' attribute is RECOMMENDED.

   Use of the 'ver' attribute is described more fully under Section 2.6.

      Interoperability Note: The 'ver' attribute of the <query/> element
      was not defined in RFC 3921 and is newly defined in this
      specification.

2.1.2.  Roster Items

   The <query/> element inside a roster set (Section 2.1.5) contains one
   <item/> child, and a roster result (Section 2.1.4) typically contains
   multiple <item/> children.  Each <item/> element describes a unique
   "roster item" (sometimes also called a "contact").

   The syntax of the <item/> element is described in the following
   sections.

2.1.2.1.  Approved Attribute

   The boolean 'approved' attribute with a value of "true" is used to
   signal subscription pre-approval as described under Section 3.4 (the
   default is "false", in accordance with [XML-DATATYPES]).

   A server SHOULD include the 'approved' attribute to inform the client
   of subscription pre-approvals.  A client MUST NOT include the
   'approved' attribute in the roster sets it sends to the server, but
   instead MUST use presence stanzas of type "subscribed" and
   "unsubscribed" to manage pre-approvals as described under
   Section 3.4.

      Interoperability Note: The 'approved' attribute of the <item/>
      element was not defined in RFC 3921 and is newly defined in this
      specification.

2.1.2.2.  Ask Attribute

   The 'ask' attribute of the <item/> element with a value of
   "subscribe" is used to signal various subscription sub-states that
   include a "Pending Out" aspect as described under Section 3.1.2.

Top      ToC       Page 11 
   A server SHOULD include the 'ask' attribute to inform the client of
   "Pending Out" sub-states.  A client MUST NOT include the 'ask'
   attribute in the roster sets it sends to the server, but instead MUST
   use presence stanzas of type "subscribe" and "unsubscribe" to manage
   such sub-states as described under Section 3.1.2.

2.1.2.3.  JID Attribute

   The 'jid' attribute of the <item/> element specifies the Jabber
   Identifier (JID) that uniquely identifies the roster item.

   The 'jid' attribute is REQUIRED whenever a client or server adds,
   updates, deletes, or returns a roster item.

2.1.2.4.  Name Attribute

   The 'name' attribute of the <item/> element specifies the "handle" to
   be associated with the JID, as determined by the user (not the
   contact).  Although the value of the 'name' attribute MAY have
   meaning to a human user, it is opaque to the server.  However, the
   'name' attribute MAY be used by the server for matching purposes
   within the context of various XMPP extensions (one possible
   comparison method is that described for XMPP resourceparts in
   [XMPP-ADDR]).

   It is OPTIONAL for a client to include the 'name' attribute when
   adding or updating a roster item.

2.1.2.5.  Subscription Attribute

   The state of the presence subscription is captured in the
   'subscription' attribute of the <item/> element.  The defined
   subscription-related values are:

   none:  the user does not have a subscription to the contact's
      presence, and the contact does not have a subscription to the
      user's presence; this is the default value, so if the subscription
      attribute is not included then the state is to be understood as
      "none"

   to:  the user has a subscription to the contact's presence, but the
      contact does not have a subscription to the user's presence

   from:  the contact has a subscription to the user's presence, but the
      user does not have a subscription to the contact's presence

   both:  the user and the contact have subscriptions to each other's
      presence (also called a "mutual subscription")

Top      ToC       Page 12 
   In a roster result (Section 2.1.4), the client MUST ignore values of
   the 'subscription' attribute other than "none", "to", "from", or
   "both".

   In a roster push (Section 2.1.6), the client MUST ignore values of
   the 'subscription' attribute other than "none", "to", "from", "both",
   or "remove".

   In a roster set (Section 2.1.5), the 'subscription' attribute MAY be
   included with a value of "remove", which indicates that the item is
   to be removed from the roster; in a roster set the server MUST ignore
   all values of the 'subscription' attribute other than "remove".

   Inclusion of the 'subscription' attribute is OPTIONAL.

2.1.2.6.  Group Element

   The <group/> child element specifies a category or "bucket" into
   which the roster item is to be grouped by a client.  An <item/>
   element MAY contain more than one <group/> element, which means that
   roster groups are not exclusive.  Although the XML character data of
   the <group/> element MAY have meaning to a human user, it is opaque
   to the server.  However, the <group/> element MAY be used by the
   server for matching purposes within the context of various XMPP
   extensions (one possible comparison method is that described for XMPP
   resourceparts in [XMPP-ADDR]).

   It is OPTIONAL for a client to include the <group/> element when
   adding or updating a roster item.  If a roster set (Section 2.1.5)
   includes no <group/> element, then the item is to be interpreted as
   being affiliated with no group.

2.1.3.  Roster Get

   A "roster get" is a client's request for the server to return the
   roster; syntactically it is an IQ stanza of type "get" sent from
   client to server and containing a <query/> element qualified by the
   'jabber:iq:roster' namespace, where the <query/> element MUST NOT
   contain any <item/> child elements.

   C: <iq from='juliet@example.com/balcony'
          id='bv1bs71f'
          type='get'>
       <query xmlns='jabber:iq:roster'/>
     </iq>

   The expected outcome of sending a roster get is for the server to
   return a roster result.

Top      ToC       Page 13 
2.1.4.  Roster Result

   A "roster result" is the server's response to a roster get;
   syntactically it is an IQ stanza of type "result" sent from server to
   client and containing a <query/> element qualified by the 'jabber:iq:
   roster' namespace.

   The <query/> element in a roster result contains one <item/> element
   for each contact and therefore can contain more than one <item/>
   element.

   S: <iq id='bv1bs71f'
          to='juliet@example.com/chamber'
          type='result'>
       <query xmlns='jabber:iq:roster' ver='ver7'>
         <item jid='nurse@example.com'/>
         <item jid='romeo@example.net'/>
       </query>
     </iq>

   If the roster exists but there are no contacts in the roster, then
   the server MUST return an IQ-result containing a child <query/>
   element that in turn contains no <item/> children (i.e., the server
   MUST NOT return an empty <iq/> stanza of type "error").

   S: <iq id='bv1bs71f'
          to='juliet@example.com/chamber'
          type='result'>
       <query xmlns='jabber:iq:roster' ver='ver9'/>
     </iq>

   If the roster does not exist, then the server MUST return a stanza
   error with a condition of <item-not-found/>.

   S: <iq id='bv1bs71f'
          to='juliet@example.com/chamber'
          type='error'>
       <error type='cancel'>
         <item-not-found
             xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
       </error>
     </iq>

Top      ToC       Page 14 
2.1.5.  Roster Set

   A "roster set" is a client's request for the server to modify (i.e.,
   create, update, or delete) a roster item; syntactically it is an IQ
   stanza of type "set" sent from client to server and containing a
   <query/> element qualified by the 'jabber:iq:roster' namespace.

   The following rules apply to roster sets:

   1.  The <query/> element MUST contain one and only one <item/>
       element.

   2.  The server MUST ignore any value of the 'subscription' attribute
       other than "remove" (see Section 2.1.2.5).

      Security Warning: Traditionally, the IQ stanza of the roster set
      included no 'to' address, with the result that all roster sets
      were sent from an authenticated resource (full JID) of the account
      whose roster was being updated.  Furthermore, RFC 3921 required a
      server to perform special-case checking of roster sets to ignore
      the 'to' address; however, this specification has removed that
      special-casing, which means that a roster set might include a 'to'
      address other than that of the sender.  Therefore, the entity that
      processes a roster set MUST verify that the sender of the roster
      set is authorized to update the roster, and if not return a
      <forbidden/> error.

   C: <iq from='juliet@example.com/balcony'
          id='rs1'
          type='set'>
       <query xmlns='jabber:iq:roster'>
         <item jid='nurse@example.com'/>
       </query>
     </iq>

2.1.6.  Roster Push

   A "roster push" is a newly created, updated, or deleted roster item
   that is sent from the server to the client; syntactically it is an IQ
   stanza of type "set" sent from server to client and containing a
   <query/> element qualified by the 'jabber:iq:roster' namespace.

   The following rules apply to roster pushes:

   1.  The <query/> element in a roster push MUST contain one and only
       one <item/> element.

Top      ToC       Page 15 
   2.  A receiving client MUST ignore the stanza unless it has no 'from'
       attribute (i.e., implicitly from the bare JID of the user's
       account) or it has a 'from' attribute whose value matches the
       user's bare JID <user@domainpart>.

   S: <iq id='a78b4q6ha463'
          to='juliet@example.com/chamber'
          type='set'>
       <query xmlns='jabber:iq:roster'>
         <item jid='nurse@example.com'/>
       </query>
     </iq>

   As mandated by the semantics of the IQ stanza as defined in
   [XMPP-CORE], each resource that receives a roster push from the
   server is supposed to reply with an IQ stanza of type "result" or
   "error" (however, it is known that many existing clients do not reply
   to roster pushes).

   C: <iq from='juliet@example.com/balcony'
          id='a78b4q6ha463'
          type='result'/>

   C: <iq from='juliet@example.com/chamber'
          id='a78b4q6ha463'
          type='result'/>

      Security Warning: Traditionally, a roster push included no 'from'
      address, with the result that all roster pushes were sent
      implicitly from the bare JID of the account itself.  However, this
      specification allows entities other than the user's server to
      maintain roster information, which means that a roster push might
      include a 'from' address other than the bare JID of the user's
      account.  Therefore, the client MUST check the 'from' address to
      verify that the sender of the roster push is authorized to update
      the roster.  If the client receives a roster push from an
      unauthorized entity, it MUST NOT process the pushed data; in
      addition, the client can either return a stanza error of <service-
      unavailable/> error or refuse to return a stanza error at all (the
      latter behavior overrides a MUST-level requirement from
      [XMPP-CORE] for the purpose of preventing a presence leak).

      Implementation Note: There is no error case for client processing
      of roster pushes; if the server receives an IQ of type "error" in
      response to a roster push then it SHOULD ignore the error.


Next RFC Part