Network Working Group J. Miller Internet-Draft The Jabber.org Project Expires: December 7, 2000 June 8, 2000 Jabber Protocol protocol Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on December 7, 2000. Copyright Notice Copyright (C) The Internet Society (2000). All Rights Reserved. Abstract This memo presents an easily extendable XML[1] protocol for Instant Messaging and Presence. Miller Expires December 7, 2000 [Page 1] Internet-Draft Jabber Protocol June 2000 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Memo Goals . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2 Protocol Goals . . . . . . . . . . . . . . . . . . . . . . 3 2. Conformance to RFC 2778 and RFC 2779 . . . . . . . . . . . 4 2.1 Exceptions to Conformance (needs additional wording) . . . 4 3. The error Element . . . . . . . . . . . . . . . . . . . . 5 3.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . 5 3.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. The message Element . . . . . . . . . . . . . . . . . . . 7 4.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . 7 4.2 Children . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 7 5. The presence Element . . . . . . . . . . . . . . . . . . . 9 5.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . 9 5.2 Children . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 10 6. The iq Element . . . . . . . . . . . . . . . . . . . . . . 11 6.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . 11 6.2 Children . . . . . . . . . . . . . . . . . . . . . . . . . 11 6.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 11 7. Extensions Through Namespaces . . . . . . . . . . . . . . 13 7.1 Info/Query Namespaces . . . . . . . . . . . . . . . . . . 13 7.1.1 Registration Request - jabber:iq:register . . . . . . . . 13 7.1.1.1 Children . . . . . . . . . . . . . . . . . . . . . . . . . 13 7.1.1.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 14 7.1.2 Simple Client Authentication - jabber:iq:auth . . . . . . 14 7.1.2.1 Children . . . . . . . . . . . . . . . . . . . . . . . . . 14 7.1.2.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 15 7.1.3 Roster (Contact List) Management - jabber:iq:roster . . . 15 7.1.3.1 Children . . . . . . . . . . . . . . . . . . . . . . . . . 15 7.1.3.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 16 7.2 X Namespaces . . . . . . . . . . . . . . . . . . . . . . . 17 7.2.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 18 7.3 Further Extensions . . . . . . . . . . . . . . . . . . . . 18 References . . . . . . . . . . . . . . . . . . . . . . . . 19 Author's Address . . . . . . . . . . . . . . . . . . . . . 19 A. The Jabber Protocol DTD . . . . . . . . . . . . . . . . . 20 B. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 22 Full Copyright Statement . . . . . . . . . . . . . . . . . 23 Miller Expires December 7, 2000 [Page 2] Internet-Draft Jabber Protocol June 2000 1. Introduction This memo describes an XML[1] protocol (referred to as the "Jabber protocol") for structured instant communication between Internet entities using XML Streams[2]. The protocol described in this memo is not theoretical. All aspects of the protocol discussed in this memo have been implemented in the GPL[3]/LGPL[4] licensed Jabber Server[10]. 1.1 Memo Goals The goals of this memo are to accuratly describe the implemented Jabber protocol and to provide short real-world examples. Furthermore, this memo aims to point out areas in which the protocol may be extended by future developement or third parties. 1.2 Protocol Goals The major goals of the Jabber protocol include: o Minimalistic o Ease of implementation, understanding, and manipulation. o Independent of transport and medium o Future extensibility with little or no modification by client applications. o Platform independence. The protocol should not be dependent in any way upon a certain operating system platform. Miller Expires December 7, 2000 [Page 3] Internet-Draft Jabber Protocol June 2000 2. Conformance to RFC 2778 and RFC 2779 The implemented protocol presented in this memo is in near conformance to RFC 2778[5], "A Model for Presence and Instant Messaging" and RFC 2779[6], "Instant Messaging / Presence Protocol Requirements." Notable exceptions to non-conformance are outlined in the following subsection. It should be noted that the Jabber protocol has been in evolution for approxiamtly two years as of the date of this memo, thus this protocol has not been designed in response to RFCs 2778 and 2779. 2.1 Exceptions to Conformance (needs additional wording) o RFC 2779, section 2.5 - Complete conformance with these requirements can be obtained by using a standard public key infrastructure such as GnuPG or PGP. o RFC 2779, section 4.1, paragraph 10 regarding message formats based on MIME. o RFC 2779, section 4.2 - Reliability. This type of guarantee of reliability can be obtained by creating a message structure based on the Info/Query (Section 6) structure. Miller Expires December 7, 2000 [Page 4] Internet-Draft Jabber Protocol June 2000 3. The error Element All of the main elements (message (Section 4), iq (Section 6), and presence (Section 5)) return error messages using a standard error method. 3.1 Attributes o code - a numerical error code coorisponding to a specific error description. The numerical codes used are nearly synchronous with HTTP error codes: * 302 - Redirect * 400 - Bad Request * 401 - Unauthorized * 402 - Payment Required * 403 - Forbidden * 404 - Not Found * 405 - Not Allowed * 406 - Not Acceptable * 407 - Registration Required * 408 - Request Timeout * 500 - Internal Server Error * 501 - Not Implemented * 502 - Remote Server Error * 503 - Service Unavailable * 504 - Remote Server Timeout Miller Expires December 7, 2000 [Page 5] Internet-Draft Jabber Protocol June 2000 3.2 Examples Message error: Angels and Ministers of Grace, defend us! Remote Server Error Presence error: Redirect IQ Error: hamlet hamlet@denmark gertrude 106c0a7b5510f192a408a1d054150ed1065e255a Remote Server Error Miller Expires December 7, 2000 [Page 6] Internet-Draft Jabber Protocol June 2000 4. The message Element The message structure is for sending regular instant messages between entities. Several message types are defined within the attributes. In use, this element is analogous to an email message. 4.1 Attributes o to - Specifies to whom the messages is intended to be delivered to. o from - Specifies the sender of the message. o type - Used to express the context as to what format the message should be displayed in. If no type is set, clients default to a type="normal". Values include: * normal - Single message dialog * chat - Traditional two-way chat similiar to AIM or IRC CTCP Chat * groupchat - Group interface similar to an IRC channel with multiple participants * headline - Ticker or active list of items * error - See the error element (Section 3). 4.2 Children o body - Contains the textual contents of the message for user display. No attributes. o subject - Contains the subject of the message. Similar to an email subject. No attributes. o thread - A random string generated by the originating client and copied back in replies. Used for tracking a conversation thread. o error - See the error element (Section 3). 4.3 Examples The following examples have been server processed and contain the from attribute. Miller Expires December 7, 2000 [Page 7] Internet-Draft Jabber Protocol June 2000 A simple message: Angels and Ministers of Grace, defend us! Complete chat message: Plotting Here, sweet lord, at your service. 100052 Miller Expires December 7, 2000 [Page 8] Internet-Draft Jabber Protocol June 2000 5. The presence Element The presence element allows for entities to express exact presence information (online, offline, away, etc.) to "subscribed" (authorized) users. The server keeps track of who is authorized to view an entity's status and to whom presence updates need to be sent to. 5.1 Attributes o to - Specifies to whome the presence is bound for. If none is specified, the server receives the presence. o from - Who the presence is from. o id - A unique identifier for the presence. Sender of the presence sets this attribute. o type - Describes the type of presence. Allowable types include: * available - Default. Signals that the user is online. * unavailable - Signals that the user is no longer available. Allows for offline options to be set (usually with x element extensions, see Section 7). * subscribe - An attempt to subscribe to a user's presence. * subscribed - The subscribe attempt was successful. * unsubscribe - An unsubscription request. The server handles the actual unsubscription, but clients receive for notification reasons. * unsubscribed - A presence unsubscribe completed succesfully. * probe - A query to a user's presence. This is used server-side only. * error - See the error element (Section 3). 5.2 Children o show - Describes a user's exact availability. Must be one of: * away - User is away from the client temporarily. * chat - User is free to chat. Miller Expires December 7, 2000 [Page 9] Internet-Draft Jabber Protocol June 2000 * xa - User is away for an extended period (eXtended Away). * dnd - User does not wish to be disturbed (Do Not Disturb). o status - Availability message. Used in conjunction with the show element to give a custom description of availability. May also be extended with the x element. See Section 7. 5.3 Examples Initial presence sent to server upon login: Request to subscribe to a user's presence: Response to a subscribe request: Full blown presence: xa Gone to England Miller Expires December 7, 2000 [Page 10] Internet-Draft Jabber Protocol June 2000 6. The iq Element Info/Query is a simple "client/server" framework within the protocol. It structures a rudimentary conversation between any two entities and allows them to pass XML formatted queries and responses back and forth. 6.1 Attributes o to - Specifies to whom the IQ is bound for. o from - Specifies from whom the IQ is from. o id - A unique identifier for the IQ for tracking the query exchange. Sender of the IQ sets this attribute. o type - The type attribute has several preset values. Each indicate a distinct step within an IQ converstation. * get - Indicates that the current query is a question or search for information. Default, assumed if no value to the type attribute is given. * error - The query failed. See the error element (Section 3). * set - This query contains data intended to set values or replace existing values. * result - This is a successful response to a get/set query. The IQ usually contains no further information on a sucessful result. 6.2 Children In the strictest terms, the iq element contains no children. In operation, a query element is usually contained within the iq element. The query element is defined by its namespace. See Section 7. 6.3 Examples The following examples are distinct parts of an IQ conversation for registration with jabber:iq:auth. Miller Expires December 7, 2000 [Page 11] Internet-Draft Jabber Protocol June 2000 Client request for registration information to a server service (service.denmark) Server response with registration fields required. Choose a username and password to register with this server. 106c0a7b5510f192a408a1d054150ed1065e255a Client request to register for an account. hamlet hamlet@denmark gertrude 106c0a7b5510f192a408a1d054150ed1065e255a Miller Expires December 7, 2000 [Page 12] Internet-Draft Jabber Protocol June 2000 7. Extensions Through Namespaces To extend the base protocol for new capabilities, the protocol makes extensive use of XML Namespaces[8]. 7.1 Info/Query Namespaces Numerous Info/Query (Section 6) namespaces have been implemented to faciliate exchange of information between Jabber entities. Namespaces currently implemented within the Jabber server include: o Simple Client Authentication (jabber:iq:auth) o Agent Properties (jabber:iq:agent) o Registration Requests (jabber:iq:register) o Roster (Contact List) management (jabber:iq:roster) o Available Agents List (jabber:iq:agents) o Out Of Band Data (jabber:iq:oob) o Client Time (jabber:iq:time) o Client Version (jabber:iq:version) o Temporary vCard (vcard-temp) Note that the Temporary vCard namespace is being used until the vCard XML standard has been finalized. The following subsections describe the three most fundamental extensions. 7.1.1 Registration Request - jabber:iq:register Through jabber:iq:register, clients can register with the Jabber server itself or with new services. 7.1.1.1 Children Note that while numerous fields are available, only the ones returned by the server are required for registration. o username o password Miller Expires December 7, 2000 [Page 13] Internet-Draft Jabber Protocol June 2000 o name o email o address o city o state o zip o phone o url o date o misc o text o instructions - contains server provided instructions for registration. o key - a unique key provided by the server, required for the entire registration process. 7.1.1.2 Examples A complete example is provided in the IQ examples (Section 6.3). 7.1.2 Simple Client Authentication - jabber:iq:auth The jabber:iq:auth namespaces provides a simple mechanism for clients to authenticate and create a resource representing their connection to the server. 7.1.2.1 Children o username - the unique user name for this user. o password - the secret key or passphrase for the user account. o digest - send a password in a SHA1 hash instead of clear text password. o resource - unique value to represent current connection. Miller Expires December 7, 2000 [Page 14] Internet-Draft Jabber Protocol June 2000 7.1.2.2 Examples The following is a complete example of how a client authenticates with the server. Client sends user information: hamlet gertrude Castle Server confirms login: 7.1.3 Roster (Contact List) Management - jabber:iq:roster Provides a simple method for server-side contact list management. Upon connecting to the server, clients should request for the roster using jabber:iq:roster. Since the roster may not be desirable for all clients (e.g., cellular phone client), the client request of the roster is optional. 7.1.3.1 Children o item - a specific roster item (contact) has the following attributes: * jid - the complete JID (Jabber ID) of the user that this item represents * subscription - the current status of the subscription related to this item. May have a value of: + none - no subscription. + from - this item has a subscription to the user. + to - the user has a subscription to this item. + both - subscription is both to and from. + remove - item is to be removed. * ask - the current status of a request to this item. May be one Miller Expires December 7, 2000 [Page 15] Internet-Draft Jabber Protocol June 2000 of: + subscription - the user is asking this item for a subscription. + unsubscription - the user is asking this item for an unsubscription. This element may contain one or more of the following element: * group - contains a user-specified user group name. 7.1.3.2 Examples Client request for current roster: Server response to client query: Family Friends Miller Expires December 7, 2000 [Page 16] Internet-Draft Jabber Protocol June 2000 Client adding new items and modifying an entry: Visitors Visitors Family Royalty The server would then respond with the new roster information, plus an IQ result: Visitors Visitors Family Royalty 7.2 X Namespaces For sending information that does not require the IQ structure, the X namespace series has been implemented. Clients can use this type of namespaces to send URLs, Roster (Contact List) items, Offline Options and other information. The following X namespaces are implemented in the Jabber server: o Offline Options (jabber:x:offline) o Delay Logging (jabber:x:delay) o Extended Identity/Routing Persistence (jabber:x:ident) Miller Expires December 7, 2000 [Page 17] Internet-Draft Jabber Protocol June 2000 o Out Of Band Data (File Transfers) (jabber:x:oob) o Embedded Roster Items (jabber:x:roster) 7.2.1 Examples Sending an embedded roster item to a user: Visitors This message contains roster items. Visitors Visitors 7.3 Further Extensions Anyone can implement their own namespace extensions without breaking the protocol. If the extended data is properly presented (i.e. within an x element), the server will simply pass the extended information on to the client. Clients will ignore the extended data if they are not capable of understanding it. For instance, the W3C's XHTML[9] namespace could easily be implemented within a regular Jabber message: Plotting Here, sweet lord, at your service. 100052 Miller Expires December 7, 2000 [Page 18] Internet-Draft Jabber Protocol June 2000 References [1] World Wide Web Consortium, "Extensible Markup Language (XML) 1.0", W3C xml, February 1998, . [2] Miller, J., "XML Streams", May 2000, . [3] Free Software Foundation, "GNU General Public License", June 1991, . [4] Free Software Foundation, "GNU Library General Public License", June 1991, . [5] Day, M., Rosenberg, J. and H. Sugano, "A Model for Presence and Instant Messaging", RFC 2778, February 2000, . [6] Day, M., Aggarwal, S., Mohr, G. and J. Vincent, "A Model for Presence and Instant Messaging", RFC 2779, February 2000, . [7] Berners-Lee, T., Fielding, R.T. and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. [8] World Wide Web Consortium, "Namespaces in XML", W3C xml-names, January 1999, . [9] World Wide Web Consortium, "XHTML 1.0: The Extensible HyperText Markup Language", W3C xhtml1, January 2000, . [10] http://jabber.org Author's Address Jeremie Miller The Jabber.org Project 414 DeLong St. Cascade, IA 52033 US Phone: 319-852-3464 EMail: jeremie@jabber.org Miller Expires December 7, 2000 [Page 19] Internet-Draft Jabber Protocol June 2000 Appendix A. The Jabber Protocol DTD Miller Expires December 7, 2000 [Page 21] Internet-Draft Jabber Protocol June 2000 Appendix B. Acknowledgments Of special note is Eliot Landrum who prepared and edited this specification memo. The entire Jabber.org team has been actively involved in the development of this protocol, yet the following individuals have directly contributed greatly to the evolution of the protocol. Thomas Muldowney Thomas Charron Julian Missig Peter Millard Miller Expires December 7, 2000 [Page 22] Internet-Draft Jabber Protocol June 2000 Full Copyright Statement Copyright (C) The Internet Society (2000). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC editor function is currently provided by the Internet Society. Miller Expires December 7, 2000 [Page 23]