XEP Editor
+In accordance with XEP-0001, the XEP Editor is responsible for overall management of the Jabber Software Foundation's standards process and publication of XMPP Extension Protocols; in particular, the XEP Editor:
+-
+
- works with XEP authors +
- ensures that each XEP is properly formatted +
- assigns a unique number to each XEP +
- assigns or modifies the status of each XEP +
- maintains each XEP under source control +
- maintains the canonical list of XEPs +
- publishes each XEP to the xmpp.org website +
- publicly announces the existence and status of each XEP +
- gathers and tallies the votes of the XMPP Council +
- fulfills the responsibilities of the XMPP Registrar +
Since the founding of the Jabber Software Foundation in 2001, the XEP Editor has been Peter Saint-Andre, who may be contacted via <editor@jabber.org>.
+ + diff --git a/fo.xsl b/fo.xsl new file mode 100644 index 000000000..dda73c455 --- /dev/null +++ b/fo.xsl @@ -0,0 +1,399 @@ + +GPS Datum Example
+The following example of GPS datum differences was kindly provided by Randy Steele of Apollo, Pennsylvania (URL: <http://www.nb.net/~resteele/>) and is archived here so that a permanent link is available from JEP-0080: User Geolocation.
+BEGIN EXAMPLE
++
This is an example of the differences in the datums you can use with a GPS. +Below is a site I was checking out. I marked it on my GPS in the field. When I got back +home to find it on the topo map, I noticed something was not right. Using +the UTM coordinates from the GPS, I located the site on the topo map. But +the map site and the site I checked in the field did not match. The terrain +was different, the site I actually checked was near the road (the top red +circle). I then remembered about map datums. The topo map was made to NAD27, while +my GPS was set to WGS84. After changing the GPS to the NAD27 datum, all was fine. +So the moral of this story is: MAKE SURE THE GPS DATUM AND THE MAP DATUM MATCH!!! +Note the difference in the circle locations. I also changed my GPS datum to NAD27.
+
+
+
END EXAMPLE
+ + diff --git a/index.shtml b/index.shtml new file mode 100755 index 000000000..11a6b05ac --- /dev/null +++ b/index.shtml @@ -0,0 +1,29 @@ + + +XMPP Extensions
+ + + +The Jabber Software Foundation (JSF) develops extensions to XMPP through a standards process centered around XMPP Extension Protocols (XEPs). The process is managed by the XMPP Extensions Editor and involves intensive discussion on the Standards-JIG mailing list, formal review and voting by the XMPP Council, and modification based on implementation experience and interoperability testing. All documents in the XEP series are available under a liberal IPR Policy for wide implementation. Submissions are welcome (see also the "inbox"). Changes are tracked via a CVS repository (see instructions), old versions are available, and IETF-style XML reference files are provided.
+ +This page lists approved XMPP extensions as well as proposals that are under active consideration. A list of all XEPs (including retracted, rejected, deprecated, and obsolete XEPs) is also available. Good places for developers to start are the basic and intermediate protocol suites.
+ +Note: The following table is sortable, just click on the headers (click twice to reverse the sort order).
+ +| Number | +Name | +Type | +Status | +Date | +
|---|
JSF IPR Policy
+This document defines the official policy of the Jabber Software Foundation regarding intellectual property rights (IPR) pertaining to XMPP Extension Protocol (XEPs) specifications.
+Version 1.2
++Table of Contents:
-
+
- 1. Introduction + +
- 2. Terms +
- 2.1. XMPP +
- 2.2. XMPP Extension Protocol +
- 2.3. Implementation +
- 2.4. Intellectual Property Claim +
- 3. Terms of Contributing to XMPP Extensions +
- 3.1. Ownership +
- 3.2. Approval of XMPP Extensions +
- 3.3. A Note about Private Extensions +
- 4. Legal Notice + +
-
+
-
+
+
1. Introduction
+This document defines the official policy of the Jabber Software Foundation (JSF) regarding intellectual property rights (IPR) as they pertain to extensions to XMPP in the form of XMPP Extension Protocol specifications (XEPs). [1]
+++1.1 History
+The Jabber/XMPP protocols have been under development since 1998 and have been discussed and documented in public forums since January 1999 in the open-source projects that were a precursor to the JSF. Through force of history and activity since its founding in the summmer of 2001, the JSF has assumed responsibility for managing the evolution of the Jabber/XMPP protocols in two ways: (1) through working with the IETF to standardize the core protocols under the name Extensible Messaging and Presence Protocol (XMPP); and (2) through the definition of extensions to the core protocol in the JSF's XMPP Extension Protocol (XEP) specification series. Through this work, the JSF has in effect "homesteaded" the domain of XMPP Extensions and has acted as a trusted third party or "intellectual property conservancy" [2] to which new and established participants in the Jabber community have entrusted their XMPP Extensions.
+1.2 Purpose
+The JSF does not seek to disparage the legitimate rights of any individual or organization to assert ownership over an Implementation of XMPP or of any XMPP Extension. However, the JSF must ensure that XMPP Extensions do not pollute the free and open nature of the protocols. Preventing such pollution means that in perpetuity any entity may independently, and without payment or hindrance, create, use, sell, distribute, or dispose of implementations of XMPP and of any XMPP Extension. Such is the intent of this policy.
+
2. Terms
+++2.1 XMPP +
+The core XML streaming, instant messaging, and presence protocols developed by the Jabber community have been contributed by the JSF to the Internet Engineering Task Force (IETF) under the name Extensible Messaging and Presence Protocol (XMPP). XMPP is all and only these core protocols, as currently defined in RFC 3920 and RFC 3921.
+
++2.2 XMPP Extension
+For the purposes of this IPR policy, an XMPP Extension is any specification approved by, or submitted for approval or consideration by, the JSF or its constituent committees (most particularly the XMPP Council). Such a specification must exist in the form of a standards-track XMPP Extension Protocol (XEP) specification in order to be considered an official submission. (Also referred to as an Extension.)
+
++2.3 Implementation
+Any software that implements XMPP or XMPP Extensions for the purpose of providing the functionality defined by the relevant specification(s).
+
++2.4 Intellectual Property Claim
+Any patent, copyright, or other proprietary claim or claims made by an entity regarding a XMPP Extension. (Also referred to as a Claim.)
+
3. Terms of Contributing an XMPP Extension
+The JSF recognizes the possibility that the creator of an XMPP Extension may make an Intellectual Property Claim regarding an XMPP Extension. Therefore, the JSF takes the following positions:
+++3.1 Ownership
+By submitting an XMPP Extension for consideration by the JSF, the author of the Extension shall assign any ownership rights or other Claims asserted over the Extension to the JSF. This does not apply to Claims regarding any Implementations of the Extension, but rather to the Extension itself. Any documentation of the Extension (in the form of a XEP specification) shall be copyrighted by the JSF. Once an author assigns ownership to the JSF, the JSF shall in turn make the Extension available to all entities so that they may create, use, sell, distribute, or dispose of implementations of XMPP and all XMPP Extensions in perpetuity and without payment or hindrance.
+ +3.3 Approval of Extensions
+No Extension shall be approved by the JSF or its constituent committees if there are Claims to the Extension itself, or any Claims that would prevent perpetual, unrestricted, royalty-free use of the Extension in a compliant Implementation by any interested party. If Claims preventing such use are discovered, the JSF shall immediately seek to replace the Extension with unencumbered protocols that may be implemented without condition by any entity.
+3.3 A Note about Private Extensions
+By its nature as XML, XMPP enables implementers to create their own private extensions to XMPP within custom XML namespaces. Such extensions may be kept private, and there is no compulsion for implementers to contribute such extensions to the Jabber community. It is only when an implementer seeks to have an extension standardized through the JSF's public standards process that ownership over such an extension must be transferred to the JSF. If an implementer wishes to keep its extensions private, it may simply refrain from submitting them to the JSF. However, private extensions exist outside the boundaries of XMPP and approved XMPP Extensions and must not be considered or described as part of XMPP or JSF-approved XMPP Extensions.
+
5. Legal Notice
+All XMPP Extension Protocol (XEP) specifications shall contain the following Legal Notice:
+++This XMPP Extension Protocol is copyright 1999 - [year] +by the Jabber Software Foundation (JSF) and is in full +conformance with the JSF's Intellectual Property Rights +Policy (<http://www.xmpp.org/extensions/ipr-policy.shtml>). +This material may be distributed only subject to the terms and +conditions set forth in the Creative Commons Attribution +License (<http://creativecommons.org/by/2.5/>). +
+
Notes
+1. For information about XMPP Extension Protocols, see <http://www.xmpp.org/extensions/> and JEP-0001.
+2. For information about intellectual property conservancies, see <http://www.creativecommons.org/concepts/#ip> and M. van Houweling, "Cultivating Open Information Platforms: A Land Trust Model." Journal of Telecommunications & High Technology Law 1, no. 1 (2002): 309-23.
+Acknowledgements
+Many thanks to Lawrence Lessig and Molly van Houweling for their assistance in formulating this policy.
+Changelog
+Version 1.2 (2006-10-04): Modified terminology to reflect protocol branding change from Jabber to XMPP (e.g., Jabber Enhancement Proposal to XMPP Extension Protocol).
+Version 1.1 (2005-10-04): Replaced Open Publication License with Creative Commons Attribution License.
+Version 1.0 (2002-10-29): Initial version approved by JSF Board of Directors.
+ + diff --git a/lastcall.py b/lastcall.py new file mode 100755 index 000000000..1c35caa3c --- /dev/null +++ b/lastcall.py @@ -0,0 +1,146 @@ +#!/usr/bin/env python + +# File: lastcall.py +# Version: 0.2 +# Description: a script for announcing JEP Last Calls +# Last Modified: 2004-09-29 +# Author: Peter Saint-Andre (stpeter@jabber.org) +# License: public domain +# HowTo: ./lastcall.py jepnum enddate dbuser dbpw + +# IMPORTS: +# +import glob +import MySQLdb +import os +from select import select +import smtplib +import socket +from string import split,strip,join,find +import sys +import time +from xml.dom.minidom import parse,parseString,Document + +def getText(nodelist): + thisText = "" + for node in nodelist: + if node.nodeType == node.TEXT_NODE: + thisText = thisText + node.data + return thisText + +# get the seconds in the Unix era +now = int(time.time()) + +# READ IN ARGS: +# +# 1. JEP number +# 2. end date +# 3. database user +# 4. database password + +jepnum = sys.argv[1]; +enddate = sys.argv[2]; +dbuser = sys.argv[3]; +dbpw = sys.argv[4]; + +jepfile = jepnum + '/jep-' + jepnum + '.xml' + +# PARSE JEP HEADERS: +# +# - title +# - abstract +# - version +# - date +# - initials +# - remark + +thejep = parse(jepfile) +jepNode = (thejep.getElementsByTagName("jep")[0]) +headerNode = (jepNode.getElementsByTagName("header")[0]) +titleNode = (headerNode.getElementsByTagName("title")[0]) +title = getText(titleNode.childNodes) +abstractNode = (headerNode.getElementsByTagName("abstract")[0]) +abstract = getText(abstractNode.childNodes) +statusNode = (headerNode.getElementsByTagName("status")[0]) +jepstatus = getText(statusNode.childNodes) +typeNode = (headerNode.getElementsByTagName("type")[0]) +jeptype = getText(typeNode.childNodes) +revNode = (headerNode.getElementsByTagName("revision")[0]) +versionNode = (revNode.getElementsByTagName("version")[0]) +version = getText(versionNode.childNodes) +dateNode = (revNode.getElementsByTagName("date")[0]) +date = getText(dateNode.childNodes) +initialsNode = (revNode.getElementsByTagName("initials")[0]) +initials = getText(initialsNode.childNodes) +remarkNode = (revNode.getElementsByTagName("remark")[0]) +remark = getText(remarkNode.childNodes) + +# UPDATE DATABASE: +# +# number is $jepnum +# name is $title +# type is $jeptype +# status is $jepstatus +# notes is "Version $version of JEP-$jepnum released $date." +# version is $version +# last_modified is $now +# abstract is $abstract +# changelog is "$remark ($initials)" + +db = MySQLdb.connect("localhost", dbuser, dbpw, "foundation") +cursor = db.cursor() +theNotes = "Version " + version + " of JEP-" + jepnum + " released " + date + "; Last Call ends " + enddate + "." +theLog = remark + " (" + initials + ")" +theStatement = "UPDATE jeps SET name='" + title + "', type='" + jeptype + "', status='Proposed', notes='" + theNotes + "', version='" + str(version) + "', last_modified='" + str(now) + "', abstract='" + abstract + "', changelog='" + theLog + "' WHERE number='" + str(jepnum) + "';" +cursor.execute(theStatement) +result = cursor.fetchall() + +# SEND MAIL: +# +# From: editor@jabber.org +# To: standards-jig@jabber.org +# Subject: LAST CALL: JEP-$jepnum ($title) +# Body: +# This message constitutes notice of a Last Call +# for JEP-$jepnum ($title). +# +# Abstract: $abstract +# +# URL: http://www.jabber.org/jeps/jep-$jepnum.html +# +# This Last Call begins now and shall end at the close +# of business on $enddate. +# + +fromaddr = "editor@jabber.org" +# for testing... +# toaddrs = "stpeter@jabber.org" +# for real... +toaddrs = "standards-jig@jabber.org" + +thesubject = 'LAST CALL: JEP-' + jepnum + " (" + title + ")" +introline = 'This message constitutes notice of a Last Call for JEP-' + jepnum + ' (' + title + ').' +abstractline = 'Abstract: ' + abstract +urlline = 'URL: http://www.jabber.org/jeps/jep-' + jepnum + '.html' +schedline = 'This Last Call begins today and shall end at the close of business on ' + enddate + '.' + +#msg = "From: %s\r\n" % fromaddr +msg = "From: JEP Editor <%s>\r\n" % fromaddr +msg = msg + "To: %s\r\n" % toaddrs +msg = msg + "Subject: %s\r\n" % thesubject +msg = msg + introline +msg = msg + "\r\n\n" +msg = msg + abstractline +msg = msg + "\r\n\n" +msg = msg + urlline +msg = msg + "\r\n\n" +msg = msg + schedline +msg = msg + "\r\n" + +server = smtplib.SMTP('localhost') +server.set_debuglevel(1) +server.sendmail(fromaddr, toaddrs, msg) +server.quit() + +# END + diff --git a/protopage.xsl b/protopage.xsl new file mode 100644 index 000000000..8711ba4a7 --- /dev/null +++ b/protopage.xsl @@ -0,0 +1,73 @@ + + + +This page provides information about the XML namespaces defined in
+
+
The following XML schemas are available for the
-
+
Last Updated:
How to Submit an XMPP Extension Protocol
+Here is how to submit a proposal to the Jabber Software Foundation for consideration as an XMPP Extension Protocol:
+-
+
Contact the XMPP Extensions Editor so that he knows to expect your submission.
+Write your proposal following the guidelines described in XEP-0143: Guidelines for Authors of XMPP Extension Protocols.
+- Make sure you read, understand, and agree to the JSF's IPR Policy before you submit your proposal! +
Email the XML file (or a URL for the file) to the XMPP Extensions Editor with a subject line of "ProtoJEP: [your title here]".
+
Note: It is the author's responsibility to provide a properly-formatted source file (see the template and CVS repository). Proposals submitted in HTML, TXT, MS Word, Open Document Format, etc. will be returned to the proposal author for proper formatting.
+ + diff --git a/xep-0001.xml b/xep-0001.xml new file mode 100644 index 000000000..e553b7e01 --- /dev/null +++ b/xep-0001.xml @@ -0,0 +1,688 @@ + + +%ents; +]> + +Clarified and simplified the state charts based on implementation experience; summarized state definitions.
Specified that a Standards Track JEP defines either (1) a wire protocol or (2) a protocol suite.
Defined Procedural JEP type as the union of JIG Formation JEPs and certain Informational JEPs in order to clarify the JEP categories; added Modifications to Approved JEPs section in order to make explicit existing Council practices regarding Active and Final JEPs; specified that JEPs on which voting was not complete at the end of a Council term shall undergo a second Last Call and subsequent vote by the new Council; modified Proposal Process to specify that the Jabber Council shall issue Last Calls on JEPs for which it is the approving body, with all discussion to occur on the Standards-JIG list; updated the schema.
Further specified the goals of the JEP process; mentioned Board-approved JEPs.
Specified the procedure for changing a JEP from Historical to Standards Track.
Specified the procedure for acceptance of a proposal as a JEP; clarified the JEP types; completed editorial review.
Added rule about automatic deferral of inactive JEPs.
Clarified the definition of informational JEP.
Added status of Retracted; corrected several errors related to the Jabber Registrar.
Further clarified the proposal process per discussion on the JSF members list.
Major revision based on experience. In addition to a reorganization of the content to improve the clarity of the presentation, changes include: (1) no anonymous authors; (2) proposal must be seconded by at least 5% of JSF members before being proposed for a Council vote; (3) clarification that the Council votes only on a particular revision of a JEP (e.g., version 1.3 when proceeding from Draft to Final); (4) added information about the "Call for Experience" phase before proceeding from Draft to Final; (5) added reference to RFC 2119; (6) added sections for security considerations, IANA considerations, and Jabber Registrar considerations. Approved by the JSF Board and Jabber Council on 2002-11-20.
Added information about the new "Experimental" state for Standards Track JEPs and made appropriate changes to the JEP process.
Added link to DTD.
(1) Added information about the "cooling off" period before a Standards Track JEP may be advanced from Draft to Final; (2) Added a link to the JEP template file; (3) Performed several minor fixes.
(1) Added information about expiration dates; (2) Added a status of Deprecated to Standards Track JEPs.
(1) Changed "Jabber Foundation" to "Jabber Software Foundation"; (2) Changed "JIG Proposal JEP" to "JIG Formation JEP"; (3) Removed reference to the Secretary of the Jabber Software Foundation in connection with the role of JEP Editor; (4) Clarified the possible states of acceptance of each kind of JEP and described in greater detail the criteria for advancement from one state to another.
Changed status to Active.
Initial release -- a simplified and updated version of Rahul Dave's Jabberization of the process and format for Python Enhancement Proposals
The &JSF; adheres to an open standards process that enables interested parties to document existing protocols used within the Jabber/XMPP developer community and to submit proposals that define new protocols; with a few exceptions,
The Jabber Software Foundation was founded in the year 2001 to openly document, safeguard, manage, and extend the wire protocols used within the Jabber/XMPP developer community. The work of the Jabber Software Foundation has several objectives:
+-
+
- To produce practical, technically excellent solutions to important problems of real-time communication based on the set of streaming XML technologies known as Jabber/XMPP. +
- To document Jabber protocols and XMPP extensions in a clear, concise manner so that the task of implementing the protocols is straightforward. +
- To ensure interoperability among the disparate technologies used on Jabber/XMPP networks. +
- To guarantee that any person or entity may implement the protocols without encumbrance. +
- To work in an fair, open, objective manner. +
The standards process specified herein has been developed and refined in order to meet these objectives.
+The five JEP types are described in the following sections.
+The approving body for all Standards Track, Informational, Historical, and Humorous JEPs is the &COUNCIL;; the approving body for Procedural JEPs may be either the &BOARD; or the Jabber Council.
+This document focuses primarily on Standards Track JEPs since they are the vehicle for defining new protocols, but also discusses the other JEP types.
+A Standards Track JEP defines one of the following:
+-
+
- A wire protocol intended to be used as a standard part of Jabber/XMPP technologies.
+
Note well that a protocol defined in a Standards Track JEP is not considered a full standard of the Jabber Software Foundation until it achieves a status of Final within the standards process defined herein (a Standards Track JEP that has achieved a status of Draft may be referred to as a Draft Standard; a Standards Track JEP that has a status of Experimental must not be referred to as a standard, but instead should be referred to as a work in progress). +
+ - A protocol suite that determines conformance requirements (e.g., &jep0073;). +
An Informational JEP defines one of the following:
+-
+
- Best practices for protocol development (e.g., &jep0128;). +
- A usage profile for an existing protocol (e.g., &jep0126;). +
An Historical JEP documents a protocol that was developed before the JEP process was instituted, but that is still in use within the Jabber/XMPP developer community; such a JEP may or may not be obsoleted by a Standards Track JEP, or upgraded to Standards Track.
+A Humorous JEP attempts to be funny by defining a protocol that would never be used in the real world; such JEPs are usually published on April 1 and automatically have a status of Active.
+A Procedural JEP defines a process or activity to be followed by the JSF, including JIG charters as specified by &jep0002;.
+The JSF welcomes and encourages the submission of protocols to the JSF's standards process.
Note well that JEP authors must transfer ownership of their protocols (but not implementations thereof) to the JSF. Refer to the &JSFIPR; for details. JEP authors must make sure that they have read, understood, and agreed to the JSF IPR Policy before submitting a proposal to the JEP Editor!
+All proposals submitted to the JSF for consideration as JEPs must contain the following information:
+-
+
Legal Notice -- the legal notice must be exactly that which is specified in the JSF IPR Policy
+ Author Information -- first name, last name, email address, and Jabber ID are all required and must be provided for all authors
+
Finally, Standards Track, Informational, and Historical JEPs must conform to &rfc2119; in the use of terminology regarding requirements levels.
+The approving body for almost all JEPs is the Jabber Council; therefore, in order to be published as a JEP, a proposal must first be accepted by the Jabber Council (the only exceptions are certain kinds of Procedural JEPs, for which the approving body may be the JSF Board of Directors and which may be accepted for publication by the JEP Editor in consultation with the Board). Upon receiving a proposal, the JEP Editor shall do the following:
+-
+
- ensure that its format is correct +
- publish it to <http://www.jabber.org/jeps/inbox/> +
- publicly announce its existence by sending a message to the discussion list of the &SJIG; +
- request acceptance of the proposal as a JEP by the Jabber Council +
If no member of the Jabber Council objects to publication of the proposal within seven (7) days or at the next meeting of the Council, the JEP Editor shall accept it as a JEP. If objections are raised by the Council on the Standards-JIG list or in its meeting, the JEP author is encouraged to address the feedback of the Council and to submit a revised version of the proposal and/or confer with the JEP Editor or objecting Council member(s) regarding how to proceed.
+If the proposal is accepted as a JEP, the JEP Editor shall do the following:
+-
+
- assign it a number +
- specify an appropriate type +
- specify a status of Experimental +
- add it to source control
JEPs are kept under source control in the 'jeps' module of the CVS repository maintained at the jabberstudio.org service. Instructions for accessing these files can be found at <http://www.jabberstudio.org/cvs.php>, and a web interface to these files is available at <http://www.jabberstudio.org/cgi-bin/viewcvs.cgi/jeps/>.
+ - add tracking information to the JEPs database +
- publish version 0.1 of the JEP to the JSF website
The canonical URL for accessing JEPs is <http://www.jabber.org/jeps/>.
+ - publicly announce the existence of the JEP by sending a message to the Standards-JIG list +
Note well that no special criteria (other than acceptance by the Jabber Council and minimal formatting compliance) need to be met in order for a JEP to be granted a status of Experimental. The granting of Experimental status must not be construed as indicating any level of approval by the JSF, the Jabber Council, or the Jabber/XMPP developer community. Implementation of Experimental JEPs is encouraged in an exploratory fashion (e.g., in a proof of concept) in order to gain experience with and iteratively improve the protocol defined therein, but such implementations may not be appropriate for deployment in production systems.
+Once a JEP is published, it becomes available for public discussion within the Standards JIG and the broader Jabber/XMPP developer community. The JEP author is responsible for collecting feedback from the Jabber/XMPP developer community during the life of the JEP and for incorporating such feedback into the proposal. In order to fully participate in discussion of the proposal, the JEP author should be subscribed to the Standards-JIG list, which is the primary venue for discussion of JEPs. Changes made based on feedback received by the JEP author must be captured in updated versions of the JEP (e.g., 0.2 after 0.1), each of which must be put under source control and subsequently published and announced by the JEP Editor.
+If an Experimental JEP is inactive (i.e., no updated versions are published) for a period of six (6) months, the JEP Editor shall automatically change the status of the JEP to Deferred unless it is in the queue of JEPs under active consideration for advancement by the Jabber Council; upon submission of an updated version, the JEP Editor shall change the status back to Experimental.
+Before an Experimental JEP may be proposed to the Jabber Council for advancement to Draft (Standards Track JEPs) or Active (Historical, Informational, and Procedural JEPs), the Jabber Council must agree that the JEP is ready to be considered for advancement. Once the Council so agrees, it shall instruct the JEP Editor to (1) change the status of the JEP from Experimental to Proposed and (2) issue a Last Call for open discussion on the Standards JIG list. The Last Call shall expire not less than 10 days after the date of issue.
+Once the consensus of the Standards JIG has been incorporated into the JEP and all issues of substance raised during the Last Call have been addressed by the JEP author, the JEP Editor shall formally propose a specific revision of the JEP to the Jabber Council for its vote. If necessary, the JEP Editor may, at his discretion and in consultation with the Jabber Council, extend the Last Call or issue a new Last Call if the JEP requires further discussion.
+Last Calls regarding Procedural JEPs for which the approving body is the JSF Board of Directors may be issued directly by the JEP Editor once instructed by the Board.
+After a JEP has been proposed to the Jabber Council, any change in its status shall be determined by a vote of the Jabber Council. All members of the Council must vote, with the possible values being +1 (approve), 0 (neutral), or -1 (disapprove, with reasons). A JEP shall not be advanced to the next stage in the approval process so long as any Council Member continues to vote -1; that Council Member's written concerns must be addressed in order for the JEP to advance. A majority of Council members must vote +1 in order for a JEP to advance. (Additional voting policies, such as voting periods and defaults if a member does not vote, may be set by the Jabber Council.) A vote of the Jabber Council is final and binding, although a JEP author is free to address the concerns of the Council and to resubmit the JEP for future consideration.
+If the Jabber Council does not complete voting on a JEP before the end of its term, the JEP Editor shall issue a new Last Call on the Standards JIG list and the newly-elected Council shall vote anew on the JEP after completion of the Last Call. This provides an opportunity for any member of the previous Council who had voted -1 to voice his or her concerns in a public forum before the new Council votes on the JEP.
+A vote of the Jabber Council applies only to the specific revision of the JEP that has been presented to it. Further revisions may need to be re-submitted for approval.
+Any change in the status of a JEP must be announced on the Standards-JIG list by the JEP Editor. If a JEP advances to a status of Final, it shall be so announced and also published as one of the official JSF protocols
Approval of Procedural JEPs for which the approving body is the JSF Board of Directors shall occur upon approval by the Board in accordance with the rules defined in the &BYLAWS;.
+More detailed information about the approval process is provided below, including criteria for Standards Track JEPs and for Historical, Informational, and Procedural JEPs.
+The possible states for a Standards Track JEP are as follows:
+
+
+ +--> Retracted
+ |
+ |
+ +--> Deferred +--> Rejected
+ | |
+ | |
+Experimental ----> Proposed ----> Draft ----> Final
+ | |
+ | |
+ +-----------+---> Deprecated ---> Obsolete
+
+ The ideal path is for a Standards Track JEP is to be advanced by the Jabber Council from Proposed to Draft to Final (the criteria for this advancement are described in the following paragraphs). However, an Experimental JEP shall be assigned a status of Deferred if it has not been updated in six (6) months (e.g., because of a lack of interest or because it depends on other specifications that have yet to move forward). In addition, rather than being advanced from Proposed to Draft, a Standards Track JEP may be voted to a status of Rejected if the Jabber Council deems it unacceptable. (Note that if a JEP is Deferred, the JEP Editor may at some point re-assign it to Experimental status, and that, even if a JEP is Rejected, it is retained in source control and on the Jabber Software Foundation website for future reference.) Finally, a JEP author may voluntarily remove an Experimental JEP from further consideration, resulting in a status of Retracted.
+In order for a Standards Track JEP to advance from Proposed to Draft, it must:
+-
+
- fill known gaps in Jabber/XMPP technologies or deficiencies with existing protocols +
- be clearly described and accurately documented so that it can be understood and implemented by interested and knowledgeable members of the Jabber/XMPP developer community +
- document any known security considerations with the proposed technology +
- be generally stable and appropriate for further field experience +
- have achieved rough consensus (though not necessarily unanimity) within the Standards JIG +
- be formally defined by an XML schema +
- receive the requisite votes from the Jabber Council +
Elevation to Draft status (version 1.0) is a major advancement for the JEP, indicating a strong sense on the part of the Jabber Council and Jabber/XMPP developer community that the specification will be of lasting value. Since a Draft standard must be well-understood and must be known to be reasonably stable, it is relatively safe to use it as the basis for implementations and production deployments. However, note that because a Draft standard may still require additional field experience and may be subject to change based on such experience, mission-critical or large-scale implementations of the Draft standard may not be advisable (although every effort shall be made to ensure that any changes to a Draft JEP will be backwards-compatible with the 1.0 version). Note also that any changes to a Draft JEP must be provisionally published at <http://www.jabber.org/jeps/tmp/>, announced on the Standards-JIG mailing list, and formally approved by the Jabber Council before being officially published at the canonical URL for the JEP.
+In order for a JEP to advance from Draft status to Final status (version 2.0), it must be shown to be stable and well-received by the Jabber/XMPP developer community. Before presenting a Draft standard to the Jabber Council for consideration as a Final standard, the JEP Editor shall issue a Call for Experience on the Standards-JIG list so that feedback can be gathered from those who have implemented the Draft standard (the Call for Experience shall expire not less than 14 days after the date of issue, and shall not be issued until at least 60 days have passed since advancement to Draft). In addition, at least two implementations of the JEP must exist, at least one of which must be free software (in accordance with the &GPL; or &LGPL;) or open-source software (in accordance with the definition provided by &OSI;). Until two implementations are produced, a Standards Track JEP shall retain a status of Draft. Once (1) two implementations have been presented to the Jabber Council, (2) feedback provided during the Call for Experience has been incorporated into the JEP, and (3) the JEP has been fully checked for accuracy, the status of the JEP may be changed to Final upon a vote of the Council.
+Finally, a Standards Track JEP that has been granted a status of Final may be superseded by a future JEP approved by the Jabber Council. In such cases, the status of the earlier JEP shall be changed to Deprecated, possibly with an expiration date assigned by the Jabber Council (see the Expiration Dates section below). After a reasonable period of time or upon the passing of the expiration date, the status of the JEP shall be changed to Obsolete.
+The possible states for a Historical, Informational, or Procedural JEP are as follows:
+
+
+ +--> Retracted
+ |
+ |
+ +--> Deferred +--> Rejected
+ | |
+ | |
+Experimental ----> Proposed ----> Active
+ |
+ |
+ +--> Deprecated --> Obsolete
+
+ Because such JEPs do not seek to define standard protocols, in general they are less controversial and tend to proceed from Proposed to Active without controversy on a vote of the Jabber Council. However, some of these JEPs may be remanded from the Council to the JEP author and/or JEP Editor for revision in order to be suitable for advancement from Proposed to Active (e.g., documentation of protocols in use must be accurate and describe any existing security concerns). As with Standards Track JEPs, the JEP author may retract such a JEP when it is Experimental, and the Council may reject such a JEP when it is Proposed.
+Once approved, Historical, Informational, and Procedural JEPs will have a status of Active. Such a JEP may be replaced by a new JEP on the same or a similar topic, thus rendering the earlier JEP out of date; in such cases, the earlier JEP shall be assigned a status of Deprecated (and eventually Obsolete) with a note specifying the superseding JEP.
+The Jabber Council may, at its discretion, decide to convert an Historical JEP into a Standards Track JEP if the protocol defined in the JEP has been in long use, is deemed stable and uncontroversial, and is unlikely to be superseded by a newer protocol. The Historical JEP shall be treated in the same way as a Standards Track JEP that has a status of Experimental, beginning with the Proposal Process. If after the Last Call and voting by the Jabber Council the JEP is approved for advancement on the standards track, its type shall be changed to Standards Track and its status shall be changed to Draft.
+The possible states for a JEP are summarized in the following sections.
+A JEP of any type is in the Experimental state after it has been accepted by the Jabber Council and published by the Jabber Software Foundation but before it has advanced within the standards process to a state of Active or Draft.
+A JEP of any type is in the Proposed state while it is in Last Call or under consideration by the Jabber Council for advancement from Experimental to Draft or Active.
+A Standards Track JEP is in the Draft state after it has undergone extensive discussion and technical review on the Standards-JIG list and has been voted forward on the standards track by the Jabber Council.
+A Standards Track JEP is in the Final state after it has been in the Draft state for at least 60 days, has been implemented in at least two separate codebases, and has been voted forward on the standards track by the Jabber Council.
+A JEP of any type other than Standards Track is advanced to a status of Active after it has been voted forward from Experimental by the Jabber Council.
+An Experimental JEP of any type is changed to the Deferred state if it has not been updated in six (6) months.
+A JEP of any type is in the Retracted state if the authors have asked the JEP Editor to remove the JEP from further consideration in the JSF's standards process.
+A JEP of any type is in the Rejected state if the Jabber Council has deemed it unacceptable and has voted to not move it forward within the standards process.
+A JEP of any type is in the Deprecated state if the Jabber Council has determined that the protocol defined therein is out of date and that new implementations are no longer encouraged (e.g., because it has been superseded by a more modern protocol).
+A JEP of any type is changed from Deprecated to Obsolete if the Jabber Council has determined that the protocol defined therein should no longer be implemented or deployed.
+Sometimes it is necessary to modify JEPs that have received final approval by the Jabber Council or JSF Board of Directors (e.g., to correct errors, incorporate the lessons of experience, or document new security concerns). This section describes the process for doing so with regard to Standards Track JEPs that have achieved a status of Final and Historical, Informational, and Procedural JEPs that have achieved a status of Active.
+With regard to Standards Track JEPs, the Jabber Software Foundation (in particular, the Jabber Council) strives to ensure that such JEPs are accurate, complete, and stable before advancing them to a status of Final (corresponding to document version 2.0 of the JEP). The Call for Experience and discussion within the Standards JIG help to ensure this result, but final responsibility rests with the Jabber Council. Despite the best efforts of all concerned, errors are sometimes discovered in Final JEPs (the individual who discovers such an error should inform the Council via the Standards-JIG mailing list or communicate directly with the JEP Editor). Whereas other standards development organizations may issue errata while leaving the specification itself unchanged, the JSF makes changes to the Final JEP and publishes a revised document version (e.g., version 2.1). In general the changes are made by the JEP Editor or JEP author in consultation with the Jabber Council, discussed within the Standards JIG if appropriate, and agreed upon by the full Jabber Council. Upon agreement regarding the exact changes, the Jabber Council shall instruct the JEP Editor to publish a revised version of the JEP and announce the existence of the revised version through the normal channels (e.g., on the JSF website and to the Standards-JIG list). Naturally, if members of the Jabber/XMPP developer community have concerns regarding the changes made, they are free to discuss the matter in the relevant forum (usually the Standards-JIG list) before or after the revised version has been published.
+The process is similar with regard to Historical and Informational JEPs that have achieved a status of Active (corresponding to document version 1.0 of the JEP): the Jabber Council agrees on the exact changes to be made and instructs the JEP Editor to publish and announce a revised version (e.g., version 1.1). Here again the Jabber Council bears responsibility for any changes and public discussion is welcome.
+Procedural JEPs may be modified more frequently as the Jabber Software Foundation gains experience with the processes defined therein. For example, JEP-0001 is modified periodically in order to document processes previously not made explicit or to modify existing processes based on experience with the JEP process; similar changes are sometimes made to the &jep0053; JEP and to various JIG-related JEPs. Changes to these JEPs are discussed by the Jabber Council, JSF Board of Directors, JSF membership, and Standards JIG as appropriate, and exact changes are agreed to by the relevant approving body (Jabber Council or JSF Board of Directors). The approving body then instructs the JEP Editor to publish and announce the revised version as described above.
+In rare cases, a protocol enhancement may be accepted as an interim solution, especially when it is recognized that expected future improvements in technology or the underlying Jabber/XMPP protocols will make possible a much better solution to the problem at hand (e.g., a better protocol for user avatars may be contingent upon the development of a robust protocol for publish/subscribe functionality). In such cases, a JEP may be approved provisionally and be assigned an expiration date.
+The exact form of such an expiration date shall be left up to the discretion of the Jabber Council. However, the preferred form is to assign an expiration date of six (6) months in the future, at which time the Jabber Council must re-affirm the status of the JEP and, if desired, extend the expiration date for another six (6) months. While this process may continue indefinitely (although that is unlikely), it has the virtue of forcing the Jabber Council and Jabber/XMPP developer community to re-examine the provisional protocol on a fairly regular basis in the light of technological changes. Alternatively, a JEP may be assigned a "soft" expiration date: that is, the JEP will expire when an expected future protocol comes into existence, whenever that may be. In either case, the status of the JEP shall be changed to Deprecated when it expires.
+In addition, an expiration date may be assigned when the status of a JEP is changed from Final (or, potentially, Draft) to Deprecated. In this case, the expiration date applies to the date when the JEP is expected to change from Deprecated to Obsolete. These dates may be flexible; however it is expected that they will follow the same six-month rule as provisional protocol enhancements.
+Every JEP must contain a section entitled "Security Considerations", detailing security concerns or features related to the proposal; in particular, a Standards Track JEP should list the security threats that the protocol addresses and does not address, as well as security issues related to implementation of the protocol. JEP authors should refer to &rfc3552; for helpful information about documenting security considerations and should also confer with the JEP Editor and/or Jabber Council regarding this important task.
+Some JEPs may require interaction with &IANA;. The IANA acts as a clearinghouse to assign and coordinate the use of numerous Internet protocol parameters, such as MIME types and port numbers (e.g., the TCP ports 5222 and 5269 used by the Jabber/XMPP developer community are registered with the IANA). Whether or not a JEP requires registration of parameters with the IANA, that fact must be noted and explained in a distinct section of the JEP entitled "IANA Considerations". Registration with the IANA should not occur until a JEP advances to a status of Draft (Standards Track JEPs) or Active (Informational and Historical JEPs), and should be initiated by the Jabber Registrar in consultation with the JEP author, not by the JEP author directly with the IANA.
+The ®ISTRAR; performs a function similar to the IANA, although limited to the Jabber/XMPP developer community. It does so by reserving protocol namespaces and by uniquely assigning parameters for use in the context of Jabber/XMPP protocols (for example, the categories and types used in &jep0030;).
+Whether or not a JEP requires registration of protocol namespaces or parameters with the Jabber Registrar, that fact must be noted and explained in a distinct section of the JEP entitled "Jabber Registrar Considerations". Such registration should not occur until a JEP advances to a status of Draft (Standards Track JEPs) or Active (Informational and Historical JEPs). Registration of protocol namespaces is initiated by the JEP Editor when a JEP advances to Draft or Active. Registration of particular parameters used within a specification may be initiated by a JEP author within the text of the JEP, or by an implementor of the JEP after it has advanced to Draft or Active. For details regarding the Jabber Registrar and its processes, refer to &jep0053;.
+A JEP may also request that a new registry is to be created by the Jabber Registrar. The JEP author must clearly define the nature of the new registry as well as the process for submitting data to the registry, and must do so in collaboration with the Registrar.
+JEPs that define official JSF protocols must include a schema that conforms to &w3xmlschema1; and &w3xmlschema2;.
+The schema for the JEP format itself is as follows:
+
+
+
+
+
+
+
+
+ This schema defines the document format for Jabber Enhancement
+ Proposals (JEPs). For further information about JEPs, visit:
+
+ http://www.jabber.org/jeps/
+
+ The canonical URL for this schema is:
+
+ http://www.jabber.org/jeps/jep.xsd
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+A Jabber Interest Group (JIG) is a working group approved by the Jabber Council to address specific areas of growth or concern within the Jabber community, usually by means of developing and publishing Jabber Enhancements Proposals (JEPs).
+The main function of most JIGs is to produce acceptable enhancements to the Jabber protocol (delivered in the form of Jabber Enhancement Proposals or JEPs
Anyone (not limited to members of the Jabber Software Foundation) may propose the formation of a JIG by completing a Jabber Enhancement Proposal outlining the need for the JIG and its proposed focus. However, JIG leaders must be members of the Jabber Software Foundation. The number of leaders for a JIG is flexible, and shall be determined by each JIG, in consultation with the Jabber Council if necessary. The concept of "membership" with regard to JIGs is loose, and is essentially co-extensive with membership in the appropriate mailing list (each JIG has its own mailing list, which is archived for public review). JIG members do not need to be members of the Jabber Software Foundation, and any member of the general public may subscribe to JIG mailing lists.
+It is expected that all JIGs (other than certain standing JIGs) will remain active for as long as necessary in order to produce one or more standards-track JEPs for review by the Jabber Council in the JIG's area of focus. However, if a JIG does not show signs of activity for an extended period of time (usually six months of inactivity on the JIG's mailing list), the JIG may be disbanded at the discretion of the Jabber Council with appropriate warning to the JIG members (usually in the form of an email sent to the JIG's mailing list).
+Complete direct client-to-client file transfers presents a major problem for clients that are behind a firewall or NAT. Proxy Accept Socket Service (PASS) enables clients to do real-time file transfers via a third party; in addition, it does not limit clients to file transfers but enables any two clients to create a raw TCP socket between them for any purpose, such as VoIP (SIP/RTP), BEEP, or binary game data.
+The first step is to communicate with a PASS service to set it up.
+At this point, the PASS service is now listening on the given IP and port for incoming connections on behalf of the Jabber Entity. The provided IP and port can now be sent to any other entity as a connection point, for file transfers or any other use.
+The default behavior for the PASS service is to listen on the port forever, unless the requesting client specifies an <expire/> value (in seconds). If the service is not configured with an expire value, it will not timeout the connection, and will start listening on the port again after one of the two sides disconnects.
+| Code | +Message | +Cause | +
|---|---|---|
| 502 | +No more ports available. Try again later. | +The PASS service is listening on all of its available ports. | +
When an incoming connection is attempted to that IP and port, the PASS service MUST send an IQ request to the entity on whose behalf it is listening:
+The entity SHOULD now immediately connect to the given proxy IP and port, and upon connection all data written to that socket will be copied to the client connection, and vice-versa. Any disconnect on either side MUST cause a disconnect on the other (initiated by the service). If the IQ set to the entity fails or returns an error, the client socket MUST be dropped as well. The client XML element provides the information about the remote end of the incoming socket.
+Abuse in bandwidth or resources could become an issue, so PASS implementations SHOULD include strict and detailed rate and usage limits, allowing only limited usage by single entities and rate-limiting bandwidth used if necessary for both single connections or overall usage. These limits are implementation-specific.
+A Jabber client can send various controls to the PASS service via the set to control how the PASS service behaves, how the server handles a listening port.
+This tells the server to shut down the port after a specified number of seconds. After the timeout period, the PASS service MUST send an <iq/> to the JID to tell it that the port has been closed down. It notifies the client with:
+This tells the server to listen once, and then close the port. Even if the <expire/> has not been met, the <oneshot/> overrides that and shuts down the listening port. When this happens the server notifies the client with the following packet:
+This tells the server to explicitly shut down a listening port. Useful for when the client shuts down and can tell the PASS service to recycle the port. The server sends back:
+| Code | +Message | +Cause | +
|---|---|---|
| 400 | +Missing <proxy/> specification. | +Sent a <close/> w/o a <proxy/> | +
| 401 | +Port not registered to your JID. | +You did not register this port with the server. | +
| 404 | +Port not found in registry. | +The <proxy port=''/> was not a defined port. | +
| 405 | +Proxy IP does not match. | +The IP sent in the <proxy/> does not match the IP of the pass-service | +
The PASS protocol can be used for clients to talk to each other and find out information about each other. When a client wants to send a file to another client, it can use the jabber:iq:pass namespace to query the IP address of the other client. For example:
+You send the other client:
+The other client SHOULD send back:
+Obviously the port is not going to be known, but the IP address will let you authenticate the JID via the PASS service since the PASS service tells you the <client/> information upon a connection.
+When a server gets an Incoming Connection notification the client has the right to deny that connection based on the <client/> information that it receives. It can return an error to the PASS service specifying the <proxy/> port and hangup on the active <client/> connection and start listening again. This does not affect the <oneshot/> control. For example:
+The PASS service sends you:
+Your client would send back:
+| Code | +Message | +Cause | +
|---|---|---|
| 401 | +Unauthorized | +The incoming <client/> does not match the <client/> from the client you want to exchange data with. | +
This JEP requires no interaction with &IANA;.
+No action on the part of the ®ISTRAR; is necessary as a result of this JEP, since 'jabber:iq:pass' is already a registered protocol namespace.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0003: http://www.jabber.org/jeps/jep-0003.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Several existing Jabber/XMPP protocols involve the exchange of structured data between users and applications for common tasks such as registration (&jep0077;) and searching (&jep0055;). Unfortunately, these early protocols were "hard coded" and thus place significant restrictions on the range of information that can be exchanged. Furthermore, other protocols (e.g., &jep0045;) may need to exchange data for purposes such as configuration, but the configuration options may differ depending on the specific implementation or deployment. Finally, developers may want to extend other protocols (e.g., &jep0030;) in a flexible manner in order to provide information that is not defined in the base protocol. In all of these cases, it would be helpful to use a generic data description format that can be used for dynamic forms generation and data "modelling" in a variety of circumstances.
+An example may be helpful. Let us imagine that when a user creates a multi-user chatroom on a text conferencing service, the service allows the user to configure the room in various ways. While most implementations will probably provide a somewhat common set of configurable features (discussion logging, maximum number of room occupants, etc.), there will be some divergence: perhaps one implementation will enable archiving of the room log in a variety of file types (XML, HTML, PDF, etc.) and for a variety of time periods (hourly, daily, weekly, etc.), whereas another implementation may present a boolean on/off choice of logging in only one format (e.g., daily logs saved in HTML). Obviously, the first implementation will have more configuration options than the second implementation. Rather than "hard-coding" every option via distinct XML elements (e.g., <room_logging_period/>), a better design would involve a more flexible format.
+The 'jabber:x:data' protocol described herein defines such a flexible format for use by Jabber/XMPP entities, steering a middle course between the simplicity of "name-value" pairs and the complexity of &w3xforms; (on which development had just begun when this protocol was designed). In many ways, 'jabber:x:data' is similar to the Forms Module of &w3xhtml;; however, it provides several Jabber-specific data types, enables applications to require data fields, integrates more naturally into the "workflow" semantics of IQ stanzas, and can be included as an extension of existing Jabber/XMPP protocols in ways that the XHTML Forms Module could not when this protocol was developed (especially because &w3xhtmlmod; did not exist at that time).
+This JEP addresses the following requirements:
+-
+
- Data Gathering -- the protocol should enable a form-processing entity (commonly a server, service, or bot) to gather data from a form-submitting entity (commonly a client controlled by a human user); this should be done via distinct data fields (e.g., items in a questionnaire or configuration form), each of which can be a different data "type" and enable free-form input or a choice between multiple options (as is familiar from HTML forms). +
- Data Reporting -- the protocol should enable a form-processing entity to report data (e.g., search results) to a form-submitting entity, again via distinct data fields. +
- Portability -- the protocol should as much as possible define generic data formats and basic datatypes only; hints may be provided regarding the user interface, but they should be hints only and not hard-and-fast requirements. +
- Simplicity -- the protocol should be simple for clients to implement, and most of the complexity (e.g., data validation and processing) should be the responsibility of servers and components rather than clients. +
- Flexibility -- the protocol should be flexible and extensible rather than "hard-coded". +
- Compatibility -- the protocol should define an extension to existing Jabber/XMPP protocols and not break existing implementations unless absolutely necessary. +
The base syntax for the 'jabber:x:data' namespace is as follows (a formal description can be found in the XML Schema section below):
+
+
+ field-value
+
+
+
+
+ ]]>
+ The &X; element qualified by the 'jabber:x:data' namespace SHOULD be included as a first-level child of an XML stanza; the stanza MAY be of any kind (&IQ;, &MESSAGE;, or &PRESENCE;), although it is RECOMMENDED to use &IQ; or &MESSAGE; (see also the restrictions enumerated below).
+The OPTIONAL <title/> and <instructions/> elements enable the form-processing entity to label the form as a whole and specify natural-language instructions to be followed by the form-submitting entity. The XML character data for these elements SHOULD NOT contain newlines (the \n and \r characters), and any handling of newlines (e.g., presentation in a user interface) is unspecified herein; however, multiple instances of the <instructions/> element MAY be included.
+The data gathered or provided in a 'jabber:x:data' form can be situated in a number of different contexts. Examples include an empty form that needs to be filled out, a completed form, the results of a submission, a search result, or simply a set of data that is encapsulated using the 'jabber:x:data' namespace. The full context for the data is provided by three things:
+-
+
- the "wrapper" protocol (i.e., the namespace whose root element is the direct child of the &IQ; stanza and the parent of the &X; element qualified by the 'jabber:x:data' namespace) +
- the place of the form within a transaction (e.g., an IQ "set" or "result") or structured conversation (e.g., a message <thread/>) +
- the 'type' attribute on the form's root &X; element +
The first two pieces of contextual information are provided by other protocols, whereas the form types are described in the following table.
+| Type | +Description | +
|---|---|
| form | +The form-processing entity is asking the form-submitting entity to complete a form. | +
| submit | +The form-submitting entity is submitting data to the form-processing entity. | +
| cancel | +The form-submitting entity has cancelled submission of data to the form-processing entity. | +
| result | +The form-processing entity is returning data (e.g., search results) to the form-submitting entity, or the data is a generic data set. | +
In order to maintain the context of the data as captured in the form type, the following rules MUST be observed:
+-
+
For &IQ; stanzas, the root element qualified by the "wrapper" namespace in a form of type "form" or "submit" MUST be returned in a form of type "result". The &X; element qualified by the 'jabber:x:data' namespace MUST be a child of the "wrapper" namespace's root element. As defined in &xmppcore;, the 'id' attribute MUST be copied in the IQ result. For data forms of type "form" or "result", the &IQ; stanza SHOULD be of type "result". For data forms of type "submit" or "cancel", the &IQ; stanza SHOULD be of type "set".
+ For &MESSAGE; stanzas, the <thread/> SHOULD be copied in the reply if provided. The &X; element qualified by the 'jabber:x:data' namespace MUST be a child of the &MESSAGE; stanza.
+ The only data form type allowed for <presence/> stanzas is "result". The &X; element qualified by the 'jabber:x:data' namespace MUST be a child of the &PRESENCE; stanza. In accordance with XMPP Core, use of data forms is not recommended unless necessary to provide information that is directly related to an entity's network availability.
+
A data form of type "form", "submit", or "result" SHOULD contain at least one <field/> element; a data form of type "cancel" SHOULD NOT contain any <field/> elements.
+The <field/> element MAY contain any of the following child elements:
+-
+
<desc/> -- The XML character data of this element provides a natural-language description of the field, intended for presentation in a user-agent (e.g., as a "tool-tip", help button, or explanatory text provided near the field). The <desc/> element SHOULD NOT contain newlines (the \n and \r characters), since layout is the responsibility of a user agent, and any handling of newlines (e.g., presentation in a user interface) is unspecified herein. (Note: To provide a description of a field, it is RECOMMENDED to use a <desc/> element rather than a separate <field/> element of type "fixed".)
+ <required/> -- This element, which MUST be empty, flags the field as required in order for the form to be considered valid.
+ <value/> -- The XML character data of this element defines the default value for the field (according to the form-processing entity), the data provided by a form-submitting entity, or a data result. In data forms of type "form", if the form-processing entity provides a default value via the <value/> element, then the form-submitting entity SHOULD NOT attempt to enforce a different default value (although it MAY do so to respect user preferences or anticipate expected user input). Fields of type list-multi, jid-multi, text-multi, and hidden MAY contain more than one <value/> element; all other field types MUST NOT contain more than one <value/> element.
+ <option/> -- One of the options in a field of type "list-single" or "list-multi". The XML character of the <value/> child defines the option value, and the 'label' attribute defines a human-readable name for the option. The <option/> element MUST contain one and only one <value/> child. If the field is not of type "list-single" or "list-multi", it MUST NOT contain an <option/> element.
+
If the <field/> element type is anything other than "fixed" (see below), it MUST possess a 'var' attribute that uniquely identifies the field in the context of the form (if it is "fixed", it MAY possess a 'var' attribute). The <field/> element MAY possess a 'label' attribute that defines a human-readable name for the field. For data forms of type "form", each <field/> element SHOULD possess a 'type' attribute that defines the data "type" of the field data (if no 'type' is specified, the default is "text-single"); fields provided in the context of other forms types MAY possess a 'type' attribute as well.
+If fields are presented in a user interface (e.g., as items in a questionnaire or form result), the order of the field elements in the XML SHOULD determine the order of items presented to the user.
+The following field types represent data "types" that are commonly exchanged between Jabber/XMPP entities. These field types are not intended to be as comprehensive as the datatypes defined in, for example, &w3xmlschema2;, nor do they define user interface elements.
+| Type | +Description | +
|---|---|
| boolean | +The field enables an entity to gather or provide an either-or choice between two options. The default value is "false". &BOOLEANNOTE; | +
| fixed | +The field is intended for data description (e.g., human-readable text such as "section" headers) rather than data gathering or provision. The <value/> child SHOULD NOT contain newlines (the \n and \r characters); instead an application SHOULD generate multiple fixed fields, each with one <value/> child. | +
| hidden | +The field is not shown to the form-submitting entity, but instead is returned with the form. | +
| jid-multi * | +The field enables an entity to gather or provide multiple Jabber IDs. | +
| jid-single * | +The field enables an entity to gather or provide a single Jabber ID. | +
| list-multi | +The field enables an entity to gather or provide one or more options from among many. | +
| list-single | +The field enables an entity to gather or provide one option from among many. | +
| text-multi ** | +The field enables an entity to gather or provide multiple lines of text. | +
| text-private | +The field enables an entity to gather or provide a single line or word of text, which shall be obscured in an interface (e.g., *****). | +
| text-single | +The field enables an entity to gather or provide a single line or word of text, which may be shown in an interface. This field type is the default and MUST be assumed if a form-submitting entity receives a field type it does not understand. | +
* Note: Data provided for fields of type "jid-single" or "jid-multi" MUST contain one or more valid Jabber IDs, where validity is determined by the addressing rules defined in XMPP Core (see the Data Validation section below).
+** Note: Data provided for fields of type "text-multi" SHOULD NOT contain any newlines (the \n and \r characters). Instead, the application SHOULD split the data into multiple strings (based on the newlines inserted by the platform), then specify each string as the XML character data of a distinct <value/> element. Similarly, an application that receives multiple <value/> elements for a field of type "text-multi" SHOULD merge the XML character data of the value elements into one text block for presentation to a user, with each string separated by a newline character as appropriate for that platform.
+In some contexts (e.g., the results of a search request), it may be necessary to communicate multiple items. Therefore, a data form of type "result" MAY contain two child elements not described in the basic syntax above: one <reported/> element followed by zero or more <item/> elements. The syntax is as follows:
+
+
+
+ -
+
+ field-value
+
+
+ -
+
+ field-value
+
+
+ .
+ .
+ .
+
+ ]]>
+ Each of these elements MUST contain one or more <field/> children. The <reported/> element defines the data format for the result items by specifying the fields to be expected for each item; for this reason, the <field/> elements SHOULD possess a 'type' attribute and 'label' attribute in addition to the 'var' attribute, and SHOULD NOT contain a <value/> element. Each <item/> element defines one item in the result set, and MUST contain each field specified in the <reported/> element (although the XML character data of the <value/> element MAY be null).
+Data validation is the responsibility of the form-processing entity (commonly a server, service, or bot) rather than the form-submitting entity (commonly a client controlled by a human user). This helps to meet the requirement for keeping client implementations simple. If the form-processing entity determines that the data provided is not valid, it SHOULD return a "Not Acceptable" error, optionally providing a textual explanation in the XMPP <text/> element or an application-specific child element that identifies the problem (see &jep0086; for information about mappings and formats).
+For the sake of the following examples, let us suppose that there exists a bot hosting service on the Jabber network, located at <botster.shakespeare.lit>. This service enables registered users to create and configure new bots, find and interact with existing bots, and so on. We will assume that these interactions occur using the &jep0050; protocol, which is used as a "wrapper" protocol for data forms qualified by the 'jabber:x:data' namespace. The examples in the sections that follow show most of the features of the data forms protocol described above.
+Note: Additional examples can be found in the specifications for various using protocols, such as JEP-0045: Multi-User Chat and JEP-0055: Jabber Search.
+The first step is for a user to create a new bot on the hosting service. We will assume that this is done by sending a "create" command to the desired bot:
+The hosting service then returns a data form to the user:
+The user then submits the configuration form:
+The service then returns the results to the user:
+Now that the user has created this search bot, let us suppose that one of the friends he has invited decides to try it out by sending a search request:
+There are no security concerns related to this specification above and beyond those described in the relevant section of XMPP Core.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes the 'jabber:x:data' namespace in its registry of protocol namespaces.
+The Jabber Registrar maintains a registry of parameter values related to the 'jabber:x:data' namespace, specifically as defined in &jep0068;; the registry is located at <http://www.jabber.org/registrar/formtypes.html>.
+This schema is descriptive, not normative.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0004: http://www.jabber.org/jeps/jep-0004.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ When contained in a "reported" element, the "field" element
+ SHOULD NOT contain a "value" child.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+The following protocol changes were incorporated in the Final specification as a result of experience with the Draft specification (described in version 1.0 of this document):
+-
+
- The <x/> element MAY be included in <message/> and <presence/> elements. +
- The <x/> element MAY contain a <title/> child for forms and results. +
- The <x/> element MUST possess a 'type' attribute. +
- A <field/> element MAY be of type='jid-single'. +
- Results MAY be reported back in <item/> tags. +
- Results MAY contain a <reported/> element with result set. +
- The <reported/> fields MAY possess a 'type' attribute to provide hints about how to interact with the data (type='jid-single' being the most useful). +
-
+
- Michael Bauer / bauer@jabber.com +
- Julian Missig / julian@jabber.org +
- Terry Smelser / tsmelser@sltscommunications.net +
- DJ Adams / dj.adams@pobox.com +
- Mike Szczerban / mikeszcz@delanet.com +
Determine standards for implementing derivative trademarks (e.g., "100% Jabber Protocol Compliant") and test software and services for compliance.
+-
+
- Ryan Eatmon / reatmon@jabber.org +
- Jer / jer@jabber.org +
- Stephen Lee / srlee@myjabber.org +
- Jim Powell / PowellJF@navair.navy.mil +
- Zad / zadk@mynet.com +
- Michael J. Emswiler / memswiler@hotmail.com +
Resolve issues around using the jabber:*:oob namespaces, and explore extending them to support additional requirements for managing multimedia streams (SIP). +Create additional protocols and methods to assist exchanging OOB data in heterogeneous environments where direct connections are not possible (PASS).
+-
+
- Thomas Muldowney / temas@jabber.org +
- Al Sutton / al@alsutton.com +
- Rahul Dave / rahul@mozdev.org +
Focusing on authentication, message encryption, connection security, etc.
+-
+
- Ryan Eatmon / reatmon@jabber.org +
- Thomas Muldowney / temas@jabber.org +
- Adam Theo / adamtheo@theoretic.com +
- Mike Szczerban / mikeszcz@delanet.com +
- Michael J. Emswiler / memswiler@hotmail.com +
To define a new namespace for dynamic forms. Minimally to supplant jabber:iq:register and jabber:iq:search.
+-
+
- Julian Missig / julian@jabber.org +
- Michael J. Emswiler / memswiler@hotmail.com +
Will determine the protocol for sending and receiving formatted messages in Jabber (XHTML-Basic)
+-
+
- Jer / jer@jabber.org +
- Peter Millard / me@pgmillard.com +
- David Waite / dwaite@jabber.com +
The replacement for agents, including extensible directory lookups and namespace feature negotiation. Defined as a draft protocol but needs additional work.
+-
+
- Dave Smith / dave@jabber.org +
- Oliver Wing / owing@vianetworks.co.uk +
- David Waite / dwaite@jabber.com +
- Rahul Dave / rahul@mozdev.org +
- Peter Millard / me@pgmillard.com +
Describe in detail how presence management currently works, and work on proposals for things like invisibility.
+Although popular, the vCard spec is too inflexible and limited. These problems become apparent when a User wants to set information outside the scope of the vCard in a standard format others will know is there. The so called 'IQ-Set' in custom namespaces is not sufficient because set information is often not in a standard format that others recognize or support. A short list of problems with vCard:
+-
+
- It is inflexible, as you can only store information that is defined by a subset of the vCard format. +
- It is inefficient, as the whole vCard must be retrieved even if all you want to know is the name of a user. +
- It is impersonal, as the vCard format was designed for electronic business cards, and as such is focused on things like business contact details. We believe that people should be able to describe themselves in much greater detail than this. +
- It is unreliable, as the data is not controlled or verified by any program. I have had many problems in the past with corrupted vCards. +
But instead of bringing down the entire customization of the 'IQ-Set' to only pre-defined schemas, it is important to keep the flexibility and power of it.
+Therefore, we propose that Jabber needs a very flexible, extensible, and powerful information structure and retrieval system. There exist four aspects to solve for when designing an improved information storage and retrieval system for any platform, especially Jabber: Interface, Structure, Storage, and Gate.
+Interface is the process, steps, and protocol a Service has to go through to access the information with the User's approval, for the User to approve or reject the access, and the User's Server to manage and secure it all.
+Although it will be part of the Jabber protocol, it is still undecided how heavily the Profiles specification will rely on and use the Jabber system. This is the first thing that will have to be decided on, but thankfully there are some plans we have already outlined as possibilities, listed at the Theoretic Identity website.
+Structure is the format that the information will be stored in and accessed by. It will have to be very flexible, likely eventually allowing the User to specify the info-sets they want to use instead of having them all set by this project.
+The personal information will be stored in XML documents or info-sets, called 'Profiles', possibly making use of RDF, and usually following Schema specifications, although that should not be a requirement.
+Storage is describing and accessing the physical location where the Profiles are kept. It will likely start off being only the Jabber Server, but will eventually allow for remote (specialized network hard drive services) and local (on the User's local machine or a portable floppy) storage. It also describes how this data will be transferred between computers and networks in an efficient and secure manner.
+This will likely be the most other-JIG dependent part of the system, since we will have to make heavy use of encryption in Jabber, and likely file transfers. So we may want to help out those related JIGs when we get to this point to make sure their results can be used by this system.
+Gate gives the User complete control at all times of others' access to and power over their Profiles. Since this system is designed to hold the bulk, if not all, of a User's personal information, they *must* have a powerful way to prevent unwanted others to access their data. So there must exist a powerful access regulation framework to precisely control which, when, and how other parties can get this information.
+Since we want this kept flexible and very secure, the techniques used in this system will likely be a new Jabber server module that receives special 'jabber:profiles' namespaces, compares the sending JID to a User-stored list of permission-granted JIDs, and acts upon the message accordingly, either following through or rejecting the requested transfer of information.
+To make sure this project progresses smoothly and orderly, it has been decided it will be split up into steps, or 'Phases'. Each of the above four aspects will be split into two to four Phases, and the Road-map for the entire project will follow along these Phases. Version 1.0 of the Profiles system will be little more than an expanded vCard schema with simple rules and permissions to regulate access to it. It will progress up to Version 4.0 or 5.0, adding in advanced verification to persuade Services to use a User's Jabber Profiles instead of forcing them to set up a local account, and also adding write permissions so Services can set receipts of purchases and similar information in a User's Account.
+This Road-map will be produced soon after the JIG is set up, and will give a good feature list and time-line to follow.
+Such an improved system would obviously provide for more types of information storage and management, but there are some other side-benefits that can be conceived of.
+-
+
- Since the User will have all personal information in their one account, and Services can retrieve this information with permission, this could mean no more having to fill out forms, especially account sign-up forms with Services. The information can be automatically retrieved and filled in for you. This is similar to client-side form-filler applications, except it can be used from any computer, no matter what software it has installed on it. +
- With write permission allowed to Services by the User, the Service can store their own Profiles about you in your Jabber Account. Information such as your Amazon wish list, receipts of purchases, calendar events, etc. This is similar to what Services do now, except you have control over where and how this information is physically stored and accessed. +
- Also, with an advanced authentication system (which will be the focus of a future JIG), a Service could use your Jabber Account to verify you are who you say you are, instead of requiring you set up a new account just with them. This is often called 'Universal Accounts', and similar to Microsoft's Passport and AOL's new Magic Carpet services. +
- With cookies and other auto-detection methods allowed by the User, Services can automatically detect their JID from the web browser or other tool. This eliminates the step of the User having to type in their JID, and can make this system all the more seamless to them. Combined with the above universal account benefit, this is similar to single sign-on systems such as Microsoft's Passport or AOL's new Magic Carpet. +
Eventually we would like this Profiles specification to completely replace the strict vCard schema that is 'hard-coded' into the protocol. We do not expect vCard to disappear from Jabber at all, simply be one possible Profile among many in a User's Account. At the end of this JIGs existence, we would like to see it integrate the Profiles and special 'jabber:profiles' namespaces fully into the rest of the Jabber protocol, having it become the method by which all User information (such as Roster, client-side preferences, and filters) is stored and retrieved.
+It is important to note that this JIG will not be a stand-alone JIG. It will draw upon many other JIGs (that currently exist and that have yet to be created). It will need encryption from the Security JIG for safe transfer of the information, a versatile forms format from the Forms JIG for Profiles administration, and advanced authentication from a future JIG for Services to authenticate the User against their Jabber account.
+The concept of Jabber Profiles was started by Eric Murphy and Mike Hearn. They both had begun to come up with similar ideas, but did not meet and exchange ideas until around early 2001. Adam Theo also came across them soon after that, and after some discussion, the three authors of this JEP agreed to start a serious effort on developing it. We started it as a project at Theoretic Solutions (http://www.theoretic.com/identity/), although at that time it was as a full-fledged identity specification, complete with Profiles, Authentication, and Trust. It was not until we have now moved to set it up as an official JIG that we have split the individual parts up, to make it easier to develop.
+The following proposal is for the formation of a Jabber Interest Group that will create a new conferencing protocol, as well as create additional functionality and standardize communications on top of said conferencing protocol.
+The initial task of the Conferencing JIG will be to propose a Jabber Conferencing specification that will solve various problems which exist in the current "groupchat" specification. This specification is meant to be a foundation for additional functionality; it defines the framework needed to provide additional features, without requiring changes to the framework specification itself. There is also to be a certain amount of feature-negotiation included; the conferencing service can define what features can be declared for a room, both as optional and required client features for room participation.
+The framework's scope consists of the following minimum functionality:
+-
+
- Browsing a list of public rooms +
- Finding a public room based on search parameters +
- Creating new rooms +
- Destroying rooms +
- Entering existing rooms +
- Altering functionality of a room +
- Querying a room for public information +
- Sending and accepting invitations to a room +
- Changing a participant's nickname within a room +
- Discovering and changing features on a running room +
- Changing a participant's status within a room +
- Sending a message to a room or a specific participant within a room +
In addition to these basic functions, we can imagine numerous different types of conferencing features; for example, hidden rooms created on the fly for discussions between a Jabber user and their friends or co-workers, transports providing access to similar foreign systems such as IRC, additional client functionality such as shared-location (URL/Co-browsing) and whiteboarding, and so on. There might also be requirements for security levels (for instance, normal participant, moderator, and room admin). Additional information may also be conveyed to users about one another, such as a user's real Jabber ID. Room entry or participation within a discussion might also have restrictions on some systems.
+The framework protocol is meant to provide a basis for designing these additional features. Some features, such as co-browsing, could be implemented entirely client-side; others may require significant logic within the conferencing implementation. In addition, some features may be optional for participation within a room, while other features could be required in order for a client to participate within a room.
+While the current "groupchat" specification is rather simple to implement, it is rather inflexible and cannot easily be extended; specifically, it has the following disadvantages:
+-
+
- There is no control over how you enter a room - for instance, you can not specify a password for entering a password-protected room. +
- There is no way to create a room without entering it, and no way to tell the state of the room without being a participant within it. This means among other things that a client can not transparently use groupchat for starting multi-user chats. +
- Changes in room state are often conveyed via text messages rather than XML. Among other things, this limits the display of messages to the English language and limits a client author's freedom in displaying this information. +
- A Participant's entry into a room is abstracted from their real Jabber account in both the old and new protocols; however, "groupchat" provides no way of tracking users across nickname changes or across sessions within a conference room. +
- The "groupchat" protocol has no way of performing feature negotiation (e.g., specifying the additional protocol elements needed to participate in a room, or optionally allowed from participants within a room). If there were participants with clients sending custom data through the room (such as XHTML or whiteboarding), you would receive that information even without your client being able to support it, and have no way of distinguishing altered behavior due to additional features of a "groupchat" implementation. +
This new conferencing protocol will be designed to solve these problems.
+Because of the prevalence of the existing "groupchat" specification for multi-user chats, a long conversion process is anticipated. A server implementation which supports both protocols will simply not allow "groupchat"-only clients to participate in rooms with required features.
+As listed above, there is a fairly large number of features that could be developed on top of a well-designed framework. The Conferencing JIG will first be established to develop a framework, with features mainly being compared against the framework for feasibility of implementation. After a proposal has been formalized as a specification, the JIG will become a group for discussing and proposing new features, and for formally specifying those features.
+Many communication applications now allow for the association of a small image or buddy icon (avatar) with a user of that application. The avatar is not intended to be a defining portrait of the user, but rather a simple expression of the user's appearance, mood, status, and the like. This proposal outlines a way to incorporate avatars into the current Jabber platform.
+Certain restrictions are placed upon the image. First, the image height and width must be between thirty-two (32) and sixty-four (64) pixels. The suggested size is sixty-four (64) pixels high and sixty-four (64) pixels wide
There are two methods of showing that a client has an avatar available:
+-
+
- Embedding the jabber:x:avatar namespace within <presence/> packets using Jabber's <x/> element +
- Displaying the jabber:iq:avatar namespace in browse requests +
Partly because Jabber browsing is relatively undeveloped, this proposal focuses on the first option.
+The <x/> element in the jabber:x:avatar namespace contains a SHA1 hash (hexadecimal, not base64) of the image data itself (not the base64-encoded version) in a <hash/> element. (Because the odds of creating an identical hash are small, the hash is considered unique to the image and can be used to cache images between client sessions, resulting in fewer requests for the image.) The initial announcement of the availability of an avatar is done by sending a presence packet with the jabber:x:avatar information, as follows:
+If the avatar-generating user changes the avatar, a new presence packet is sent out with the updated information:
+To disable the avatar, the avatar-generating user's client will send a presence packet with the jabber:x:avatar namespace but with no hash information:
+Clients should send the current avatar hash in every <presence/> packet even if the avatar has not changed. Remember that other clients logging in will receive a copy of the most recent <presence/> element, which should therefore always contain the most recent avatar hash. However, if the client's connection is lost unexpectedly or the client disconnects without sending an unavailable presence, the server will send other clients a <presence/> element containing no jabber:x:avatar extension. Therefore if, after receiving one or more presence packets containing jabber:x:avatar information, an avatar-receiving client receives a presence packet that does not include the jabber:x:avatar namespace, it is recommended that the client save the avatar image until the next set of information is received. In this case the avatar-generating client might send something as simple as the following:
+There are two methods for retrieving the actual avatar data:
+-
+
- An exchange between clients of <iq/> elements in the jabber:iq:avatar namespace +
- Public XML storage from the avatar-generating client to the server and public XML retrieval from the server to the avatar-requesting client
Refer to the Generic XML Namespace Storage draft protocol.
+
The first of these methods is preferred. On this model, a query is sent directly to the avatar-generating client using an <iq/> element of type "get" in the jabber:iq:avatar namespace
The avatar-generating client will reply with an <iq/> element of type "result" in the jabber:iq:avatar namespace; this reply will contain a query element that in turn contains a <data/> element with the MIME type in the 'mimetype' attribute and the data base64-encoded in the body of the <data/> element:
+If the first method fails, the second method that should be attempted by sending a request to the server for the avatar-generating user's public XML containing the avatar data. This data is to be stored in the storage:client:avatar namespace. This method presumes that the avatar-generating client has already stored its avatar data on the server:
+Once such data has been set, the avatar can be retrieved by any requesting client from the avatar-generating client's public XML storage:
+It is acknowledged that sending avatar information within presence packets is less than desirable in many respects (e.g., in network traffic generated); however, there currently exists in Jabber no generic framework for addressing these shortcomings. Possible solutions on the horizon include live browsing and a pub/sub model, but these are still embryonic and experimental. Once something of that nature is accepted by the Council, the avatar spec will be modified to work within that framework rather than by attaching to presence.
+Peter Millard, a co-author of this specification from version 0.1 through version 0.3, died on April 26, 2006.
+&xmlrpc; is a method of encoding RPC requests and responses in XML. The original specification defines HTTP (see &rfc2068;) as the only valid transport for XML-RPC payloads.
+Various initiatives exist already to transport XML-RPC payloads over Jabber. These initiatives were independent of each other and used slightly differing methods (e.g. carrying the payload in a
A working session during JabberCon 2001 resulted in a formalisation of a single method. This JEP describes that method, which is labelled as Jabber-RPC to differentiate it from XML-RPC itself.
+The &IQ; stanza is used to transport XML-RPC payloads. XML-RPC requests are transported using an &IQ; stanza of type "set", and XML-RPC responses are transported using an &IQ; stanza of type "result". An &IQ; stanza MUST NOT contain more than one request or response.
+The &IQ; stanza contains a single &QUERY; sub-element in the jabber:iq:rpc namespace. The direct child of the &QUERY; element will be either a single <methodCall/> element (in the case of a request) or a single <methodResponse/> element (in the case of a response). This child element will contain the XML-RPC payload. Note that the XML declaration that normally appears at the head of an XML-RPC request or response when transported as the payload of an HTTP POST request MUST BE omitted when it is transported via a Jabber &IQ; stanza.
+The encoding of the Jabber XML stream is UTF-8. It is assumed that the encoding of the XML-RPC payload is also UTF-8.
+Application-level errors will be indicated within the XML-RPC payload (as is the case with the traditional HTTP-based XML-RPC mechanism). Transport level errors will be indicated in the normal way for &IQ; stanzas -- namely, by an &IQ; stanza of type "error" and the addition of an <error/> tag as a direct child of the &IQ; stanza. There are no specific XML-RPC-related, transport-level errors.
+If the requesting entity does not have sufficient permissions to perform remote procedure calls, the responding entity MUST return a &forbidden; error:
+If an entity supports the Jabber-RPC protocol, it SHOULD advertise that fact in response to &jep0030; information ("diso#info") requests by returning an identity of "automation/rpc" and a feature of "jabber:iq:rpc":
+An entity that supports Jabber-RPC SHOULD establish a "whitelist" of entities that are allowed to perform remote procedure calls and MUST return a &forbidden; error if entities with insufficient permissions attempt such calls.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'jabber:iq:rpc' in its registry of protocol namespaces.
+The Jabber Registrar includes a Service Discovery type of "rpc" within the "automation" category in its registry of service discovery identities.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0009: http://www.jabber.org/jeps/jep-0009.html
+
+ There is no official XML schema for XML-RPC. The main body
+ of this schema has been borrowed from an unofficial schema
+ representation contained in the book "Processing XML With
+ Java" by Elliotte Rusty Harold, as located at:
+
+ http://www.ibiblio.org/xml/books/xmljava/chapters/ch02s05.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Jabber is often thought of simply as a system for instant messaging, albeit an open one. However, Jabber technology can be used, and is being used, in applications quite different from simple IM. One of these applications is whiteboarding. In collaborative work, the ability to draw (for example, to design sketches, UML schemas, house architectures, and organizational plans) is essential, as exemplified by the success of real-world whiteboarding applications such as Microsoft NetMeeting. Whiteboarding can also be used for entertainment purposes such as games and quizzes. Because of the value of whiteboarding as an important real-time collaboration tool, other IM services are beginning to offer these capabilities. For these and other reasons, I believe that a good protocol for whiteboarding in Jabber would be of great value.
+There exists today a protocol draft for sending streaming XPM over Jabber
Therefore, the Whiteboard JIG should develop a standard way of handling whiteboards in Jabber and a format for data transfer. This might be based on vector graphics, bitmap data, or a combination of these two. In addition, the protocol should work in the context of both regular messaging and conferencing. The protocol for whiteboarding during conferencing might depend on the new protocol proposal to come from the Conferencing JIG
The Whiteboarding JIG should produce the following deliverables (these deliverables will be presented to the Jabber Council as a JEP):
+A set of requirements that the proposed protocol should fulfill.
+There are today at least four different attempts
One or more data formats for the graphics data, presented both as a description and as a DTD or XML schema.
+The actual protocol for how the graphics data is sent over Jabber. This will also include an analysis of any associated functionality that must be performed by Jabber servers and clients.
+The Jabber world is a diverse place, with lots of services, transports, software agents, users, groupchat rooms, translators, headline tickers, and just about anything that might interact on a real-time basis using conversational messages or presence. Every JabberID (JID) is a node that can be interacted with via messages, presence, and special purpose IQ namespaces. Some JIDs are parents (such as transports), and often many JIDs have relationships with other JIDs (such as a user to their resources, a server to its services, etc.). We need a better way to structure and manage this culture of multi-namespace JID stew. The answer: Jabber Browsing.
+Note well that implementors are encouraged to implement &jep0030; instead of Jabber Browsing.
+One of the concepts in browsing which helps to extend the interaction between JIDs is a "JID-Type", a simple heirarchy for identifying the role of any JabberID that is similar to the mime-type format. Many programmers are comfortable with the concept of identifying file types by mime-types, which use the format "category/type". A JID-Type, once discovered, is to be used in the same way that a mime-type would be for a file, to alter the user interface representing that JID or provide alternative functionality for interacting with it (either automatically or driven by user interaction). The following categories and types are proposed as the canonical list for the purpose of JID-Types:
+| Category | +Type | +Description | +
|---|---|---|
| application/ | ++ | Specific applications running as a resource on a user@host | +
| bot | +Automated conversations | +|
| calendar | +Calendaring and scheduling service | +|
| editor | +Collaborative editor | +|
| fileserver | +Available files | +|
| game | +Multi-player game | +|
| whiteboard | +Whiteboard tool | +|
| conference/ | ++ | Nodes of this category provide multi-user chat facilities (a.k.a. conference rooms). | +
| irc | +IRC rooms (note: this enables Jabber users to connect to Internet Relay Chat rooms) | +|
| list | +Mailing-list-style conferences | +|
| private | +Private, dynamically-generated conference rooms | +|
| public | +Public, permanent conference rooms | +|
| topic | +Topic-based conferences | +|
| url | +Website-hosted conferences | +|
| headline/ | ++ | Recognize different sources of headlines, GUI hints | +
| logger | +Log messages (usually presented in a scrolling GUI) | +|
| notice | +Alerts and warnings (usually presented as popup messages) | +|
| rss | +Rich Site Summary syndication | +|
| stock | +Stock market information by symbol (ticker) | +|
| keyword/ | ++ | Keyword-based lookup services (search engines, etc.) | +
| dictionary | +Dictionary lookup service | +|
| dns | +DNS resolver | +|
| software | +Software search | +|
| thesaurus | +Thesaurus lookup service | +|
| web | +Web search | +|
| whois | +Whois query service | +|
| render/ | ++ | Automated translation services | +
| en2fr | +English to French | +|
| *2* | +Other language to language (using standard language codes) | +|
| tts | +Text to Speech | +|
| service/ | ++ | Nodes of this category provide a link to another Instant Messaging network or messaging gateway. The 'jabber:iq:register' namespace can be used to gain access to such networks, and the 'jabber:iq:search' namespace may also be available. | +
| aim | +AIM transport | +|
| icq | +ICQ transport | +|
| irc | +IRC gateway (note: this enables IRC users to connect to Jabber) | +|
| jabber | +A Jabber server which conforms to the specification for the 'jabber:client' namespace | +|
| jud | +Jabber User Directory | +|
| msn | +MSN transport | +|
| pager | +Pager gateway | +|
| serverlist | +A list of servers. It is assumed that this node has service/* children | +|
| sms | +SMS gateway | +|
| smtp | +SMTP gateway | +|
| yahoo | +Yahoo! transport | +|
| user/ | ++ | Nodes of this category are Jabber users, typically implementing enough of the 'jabber:client' namespace to be compliant. | +
| client | +A standard or fully-featured Jabber client compliant with the 'jabber:client' namespace | +|
| forward | +A forward alias | +|
| inbox | +An alternate inbox | +|
| portable | +A portable device implementing some of the 'jabber:client' namespace | +|
| voice | +A node providing phone or voice access | +|
| validate/ | ++ | Validation services | +
| grammar | +Grammar-checking tool | +|
| spell | +Spell-checking tool | +|
| xml | +XML validator | +
Historically each category was used as the name of an element, and the type was an attribute, such as ]]>. The proper expression for all new implementations supporting this specification is to express the type information as attributes on a generic item element: ]]>. When processing returned browse information this new syntax should always be handled first, and the old syntax only used if it is important to be able to access older implementations.
+Additional unofficial categories or types may be specified by prefixing their name with an "x-", such as "service/x-virgeim" or "x-location/gps". Changes to the official categories and subtypes may be defined either by revising this JEP or by activating another JEP. Removal of a category or subtype must be noted in this document.
+The namespace containing the Jabber Browsing data is jabber:iq:browse. The primary element within this namespace is 'item' (again, historically every category listed above would also be an element).
+The common way to browse to a JabberID using IQ is:
+The item element has these attributes in a browse result:
+-
+
- jid [required] -- The full JabberID of the entity described. +
- category [optional] -- One of the categories from the list above, or a non-standard category prefixed with the string "x-". +
- type [optional] -- One of the official types from the specified category, or a non-standard type prefixed with the string "x-". +
- name [optional] -- A friendly name that may be used in a user interface. +
- version [optional] -- A string containing the version of the node, equivalent to the response provided to a query in the 'jabber:iq:version' namespace. This is useful for servers, especially for lists of services (see the 'service/serverlist' category/type above). +
Any item may contain any number of additional items as a child, which describes the hierarchical relationship between the parent and the child items. This relationship could be represented as a "link" in a wizard or page-based user interface, or as a branch in a tree as it is expanded. Browse results usually only contain the direct children of a node, not the grandchildren. Browsing to a user, but not a resource, will return results from the server (still with the user's JID) containing the list of resources.
+For example, this could be the result of browsing to jer@jabber.org:
+More definitively, throughout all of browsing, a parent describes the children, and the children when browsed to fully describe themselves. The browse data received from the child takes precedence.
+Parents should list children only if they are available. This means that if for a user a child client goes offline, the parent should remove it from its browse result.
+On top of the browsing framework, a simple form of "feature advertisement" can be built. This enables any entity to advertise which features it supports, based on the namespaces associated with those features. The <ns/> element is allowed as a subelement of the item. This element contains a single namespace that the entity supports, and multiple <ns/> elements can be included in any item. For a connected client this might be <ns>jabber:iq:oob</ns>, or for a service <ns>jabber:iq:search</ns>. This list of namespaces should be used to present available options for a user or to automatically locate functionality for an application.
+The children of a browse result may proactively contain a few <ns/> elements (such as the result of the service request to the home server), which advertises the features that the particular service supports. This list may not be complete (it is only for first-pass filtering by simpler clients), and the JID should be browsed if a complete list is required.
+Clients should answer incoming browsing requests to advertise the namespaces they support.
+When a JabberID is browsed, the result may contain children or it may be empty. An empty result means there are no further relationships or links under that JID, which could be represented as a page containing a list of functions available for the JID, such as vCard, message, register, etc. When the result contains children, they may also be empty (as in the first result from jer@jabber.org above). An empty child does not mean anything, and to determine the namespaces supported or if there are more children, it must be browsed to directly.
+The first important use of jabber:iq:browse is to replace the jabber:iq:agents namespace. When a client connects, it may optionally browse to the server to which it connected in order to retrieve a list of available services. The resulting iq might look like the following example:
+To determine any further details from this list, each child would have to be browsed. The elements within the icq service are only hints to a client for building user interface elements. The icq.jabber.org service would still need to be browsed in order to determine any relationships or additional namespaces. This top-level list is the master "services" list available from the server, and should be used for any default functionality when available. This list could also serve as the "home page" for a page-based browsing user interface.
+A client should not just blindly request browse information every time the user requests it, rather, a client should cache the browse results based on JabberID. Any display or use of the browse data should then be returned from the cache. This model is similiar to that of presence.
+There are no security features or concerns related to this proposal.
+This JEP requires no interaction with &IANA;.
+No action on the part of the ®ISTRAR; is necessary as a result of this JEP, since 'jabber:iq:browse' is already a registered protocol namespace.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0011: http://www.jabber.org/jeps/jep-0011.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+The 'jabber:iq:browse' namespace has been in use for quite some time. However, live browsing still needs to be better defined by a generic publication/subscription system. It is assumed that when such a system is defined, updates to this JEP will be made. It is, however, possible that no futher changes to jabber:iq:browse itself may be needed.
+It is often helpful to know the time of the last activity associated with a Jabber Entity. The canonical usage is to discover when a disconnected user last accessed the server (a closely related usage is to discover when a connected user was last active on the server, i.e., the user's idle time). The 'jabber:iq:last' namespace provides a method for retrieving this kind of information. In historical usage, the 'jabber:iq:last' namespace has also been used to query Jabber servers and components about their current uptime; however, this is an extension to the core usage of the 'jabber:iq:last' namespace and may require the addition of a separate namespace in the future.
+Although the 'jabber:iq:last' namespace has been in use since January 2001, it is still not considered one of the standard Jabber protocols. While the &jabberd; server, many components, and some clients already implement this namespace, it is often overlooked by new developers because of the lack of standardization. This informational JEP defines the protocol as it is used today in order to more fully document it for historical purposes.
+The 'jabber:iq:last' namespace is used as the value of the 'xmlns' attribute of a <query> element contained within an <iq/> element. When requesting last activity information, a Jabber Entity sends an <iq> element of type='get' to another Jabber Entity (i.e., a JID). When responding to such a request, a Jabber Entity sends an <iq> element of type='result'. The <query> element never has any children and contains only one attribute and CDATA, depending on the scenario in which it is used.
+As currently implemented, the Jabber Entity receiving an IQ reply in the 'jabber:iq:last' namespace must interpret it based on the sending JID's type in order to determine the meaning of the information. Specifically, currently the information means something different depending on whether the JID sending the reply is of the form 'host', 'user@host', or 'user@host/resource'. These differences and established usage are explained more fully below.
+As noted above, the primary usage of the 'jabber:iq:last' namespace is to find out how long ago a user logged out (and, additionally, what their status message was at that time). This primary usage assumes that the IQ get is sent to (and the IQ reply is received from) a JID of the form 'user@host'. When used in this way, the <query> element contained in the IQ reply has a 'seconds' attribute, which is the number of seconds that have passed since the user last logged out, and the element CDATA is the status message of the last unavailable presence received from the user. An example is shown below:
+In this example, the user logged out fifteen minutes and three seconds ago, and when they logged out they sent a presence packet of type='unavailable' whose <status/> element contained the text "Heading home".
+If the user has at least one available resource when the server receives the request, the response SHOULD contain an empty <query/> element whose 'seconds' attribute is set to a value of '0'.
+Note well that, as specified in &xmppcore; and &xmppim;, an IQ query sent to a JID of the form user@host is handled by a server on the user's behalf, not forwarded to one or more active resources. In addition, a server MUST NOT return last activity information to an entity that is not authorized to view the user's presence information (normally via presence subscription), and MUST return a "Forbidden" error in response to such a request (for information about error conditions, refer to &jep0086;).
+When the IQ get in the 'jabber:iq:last' namespace is sent to a specific resource of an online user (i.e., a JID of the form of 'user@host/resource'), the JID sending the reply MAY respond with the idle time of the user. This is not a required protocol for clients to support, so clients sending such requests MUST NOT depend on receiving a meaningful result from the target user (although a client that does not support the protocol, or that does not wish to divulge this information, SHOULD return a "Service Unavailable" error). The standard does not specify what resolution the clients must use for the idle times, so the result SHOULD NOT be used as a precise measurement. Here is an example:
+In this example, the user has been idle for about two minutes.
+If there is no available resource matching the user@host/resource in the 'to' attribute of the request, the server MUST follow the rules in XMPP IM in order to determine what error stanza to return.
+When the IQ get in the 'jabber:iq:last' namespace is sent to a server or component (i.e., to a JID of the form 'host'), the information contained in the IQ reply reflects the uptime of the JID sending the reply. The seconds attribute is how long the host has been up, and the CDATA is unused.
+In this example, the server has been up for a little more than 34 hours.
+A server MUST NOT allow an unauthorized entity to learn a user's network availability by sending a Last Activity request to a JID of the form user@host or user@host/resource; Last Activity information MAY be divulged only to those entities that have permission to view the user's presence (normally via presence subscription), potentially as restricted by privacy rules (as defined in XMPP IM and further profiled in &jep0126;).
+This JEP requires no interaction with &IANA;.
+No action on the part of the ®ISTRAR; is necessary as a result of this JEP, since 'jabber:iq:last' is already a registered protocol namespace.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0012: http://www.jabber.org/jeps/jep-0012.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+The 'jabber:iq:last' namespace has been used intensively (in the jabberd server, components such as most transports, and some Jabber clients), and no major faults have been found in the current implementations. However, as noted, it has not necessarily been used widely, and many Jabber clients lack support for this namespace. For this reason it is probably best to consider it a non-core namespace.
+The current specification assumes that the 'resource' portion of a JID is equivalent to a device or connection (laptop, PDA, etc.). While in that context it makes sense to interpret the information returned by an IQ reply in the 'jabber:iq:last' namespace as client idle time, such an assumption will make less sense in a future world where a resource may be not a device or connection but truly a more generic resource such as a calendar or weblog. The current interpretation of 'jabber:iq:last' for 'user@host/resource' as idle time may not be appropriate for the more diverse Jabber resources of the future.
+The most significant point of contention regarding the 'jabber:iq:last' namespace is the perceived ambiguity of the information contained in an IQ reply for this namespace. Specifically, for a 'user@host' the information is the time since the JID was last connected to the host, for a 'user@host/resource' the information is the time since the resource was last active (i.e., in most circumstances the client idle time), and for a 'host' the information is the uptime for the server or component. Because of this ambiguity (real or perceived), there is some sentiment in the Jabber community that it would be better to create a separate 'jabber:iq:uptime' namespace (and perhaps even a 'jabber:iq:idletime' namespace), leaving the 'jabber:iq:last' namespace for last disconnection time only. These potential namespaces may be proposed in one or more future JEPs if needed.
+Although not required to do so by &rfc3920; and &rfc3921;, many existing Jabber/XMPP instant messaging servers will store messages received while a user is offline and deliver them when the user is next online. Such messages are commonly called "offline messages". The current means of retrieving one's offline messages is simple: one sends available presence to the server and, as a consequence, the server sends a one-time "flood" of all the messages that have been stored while one was offline. This simplification has the following deficiencies:
+-
+
It can be overwhelming, which is undesirable for the vacationer or heavy user. Many individuals upon returning to work from a weeklong vacation spend the first few hours wading through the dozens, even hundreds, of emails that they received during their absence. Unlucky, however, is this user who then logs onto their Jabber server and is bombarded by hundreds of instant messages, possibly in scores of popup dialogs, simultaneously. Should their client crash, they have lost all communication that occurred while they were away.
+ It can be difficult to integrate with web-based email clients, which is undesirable for some portals. Several large portals are currently trying to blur the distinction between IM and email -- providing both through one web interface. With offline retrieval semantics so vastly different between the two, this is quite difficult.
+
What is needed is a flexible semantic for offline message handling, similar to POP3 in the email world (see &rfc1939;). This would enable the wireless user to view header information for all offline messages and select only those from their boss and important clients for viewing. It would enable the vacationer to read and delete their messages one at a time, minimizing the possibility of losing all correspondence. And it would provide for seamless integration with existing web-based email clients.
+In particular, such a protocol should support the following use cases:
+-
+
- Client determines server support for this protocol. +
- Client requests number of messages. +
- Client requests message "header" information (thereby choosing flexible offline message retrieval as opposed to old-fashioned "flood" mode). +
- Client retrieves specific messages. +
- Client removes specific messages. +
- Client retrieves all messages. +
- Client removes all messages. +
In order to discover whether one's server supports this protocol, one uses &jep0030;.
+If the server supports this protocol, it MUST return a <feature/> element in the disco result with the 'var' attribute set to the namespace name for this protocol: 'http://jabber.org/protocol/offline'.
+RFC 1939 includes a feature (the "STAT" command) that enables a user to determine how many messages are waiting to be retrieved (without retrieving all of the headers). Such a feature would be helpful in Jabber/XMPP as well, especially if the client is constrained with regard to storage capacity or available bandwidth.
+In order to determine the number of messages in the offline message queue, the user sends a disco#info request without a 'to' address (i.e., implicitly to the user himself) and with the disco node specified as 'http://jabber.org/protocol/offline':
+If the server supports retrieval of the number of messages, it MUST include &jep0128; data specifying the number of messages:
+Upon receiving a service discovery request addressed to a node of "http://jabber.org/protocol/offline" (either a disco#info request as in this use case or a disco#items request as in the next use case), the server MUST NOT send a flood of offline messages if the user subsequently sends initial presence to the server during this session. Thus the user is now free to send initial presence (if desired) and to engage in normal IM activities while continuing to read through offline messages. However, once the user sends presence, the user's server MUST deliver in-session messages as usual; this JEP applies to offline messages only. In addition, if the user authenticates and provides presence for another resource while the first (non-flood) resource still has an active session, the server MUST NOT flood the second resource with the offline message queue.
+In order to retrieve headers for all of the messages in the queue, the user sends a disco#items request without a 'to' address (i.e., implicitly to the user himself) and with the disco node specified as 'http://jabber.org/protocol/offline'.
+The server now MUST return headers for all of the user's offline messages. So that the user may determine whether to view a full message, the header information provided MUST include the full Jabber ID of the sender (encoded in the 'name' attribute) and a unique identifier for the message within the user's "inbox" (encoded in the 'node' attribute), so that the user may appropriately manage (view or remove) the message.
+If the requester is a JID other than an authorized resource of the user (i.e., the user@host of the requester does not match the user@host of the user), the server MUST return a &forbidden; error. If the requester is authorized but the node does not exist, the server MUST return an ¬found; error. If there are no offline messages for this user, the server MUST return an empty query as defined in JEP-0030. (For information about the syntax of error conditions, refer to &jep0086;.)
+The syntax and semantics of the attributes are as follows:
+-
+
- The 'jid' attribute is the Jabber ID with which the item nodes are associated, i.e., the user himself. +
- The 'name' attribute is the full JID of the sender as received in the 'from' address of the message itself. +
- The 'node' attribute is a unique identifier for the message. The value SHOULD be considered opaque, but applications MAY perform character-by-character dictionary ordering on the values. This enables applications to implement ordering on messages, such as that shown above, wherein the node values are UTC timestamps (if timestamps are used, they MUST conform to the 'Datetime' profile defined in &jep0082;). +
Messages are viewed based on the value of the 'node' attribute as provided for each item returned by the server in the header information. A user MAY request one or more messages in the same IQ get.
+If the requester is a JID other than an authorized resource of the user, the server MUST return a &forbidden; error. If the requester is authorized but the node does not exist, the server MUST return an ¬found; error. Otherwise, the server MUST send the requested message(s) plus an IQ result:
+In order to distinguish incoming messages, each message MUST contain the node value. It is RECOMMENDED for the server to include &jep0091; information in the message.
+A server MUST NOT remove a message simply because it has been requested by and delivered to the user; instead, the user must specifically request to remove a message. This further implies that the user's offline message queue SHOULD NOT be automatically cleared out by the server if there are offline messages remaining when the user's session ends. However, an implementation or deployment MAY remove messages according to its own algorithms (e.g., storage timeouts based on a "first in first out" rule) or policies (e.g., message queue size limits) if desired.
+As with viewing, messages are removed based on the value of the 'node' attribute as provided for each item returned by the server in the header information. The user MAY request the removal of one or more messages in the same IQ set.
+If the requester is a JID other than an authorized resource of the user, the server MUST return a &forbidden; error. If the requester is authorized but the node does not exist, the server MUST return a ¬found; error. Otherwise, the server MUST remove the messages and inform the user:
+The user retrieves all message by sending the "fetch" command:
+If the requester is a JID other than an authorized resource of the user, the server MUST return a &forbidden; error. If the requester is authorized but the node does not exist, the server MUST return a ¬found; error. Otherwise, the server MUST retrieve all messages and inform the user:
+A client MAY retrieve all messages without first requesting message headers. In this case, the server MUST return all of the user's offline messages and also MUST NOT send a flood of offline messages if the user subsequently sends initial presence to the server during this session. That is, the semantics here are the same as for requesting message headers.
+The user removes all message by sending the "purge" command:
+If the requester is a JID other than an authorized resource of the user, the server MUST return a &forbidden; error. If the requester is authorized but the node does not exist, the server MUST return a ¬found; error. Otherwise, the server MUST remove all messages and inform the user:
+This section shows the flow of protocol between client (C:) and server (S:) for the existing (flood) scenario and the improved (POP3-like) scenario.
+The semantics change with POP-like offline message handling, and server behavior changes as well...
+A server MUST NOT deliver a user's offline messages to any JID except one of the user's authorized resources.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'http://jabber.org/protocol/offline' in its registry of protocol namespaces.
+The Jabber Registrar includes "automation" in its registry of Service Discovery categories for use for any entities and nodes that provide automated or programmed interaction. This JEP specifies the following new types for the "automation" category:
+| Type | +Description | +
|---|---|
| message-list | +The node for the offline message queue; valid only for the node "http://jabber.org/protocol/offline". | +
| message-node | +A node for a specific offline message if service discovery is provided for messages. | +
The registry submission is as follows:
+
+ message-list
+
+ The node for the offline message queue; valid only for the node
+ "http://jabber.org/protocol/offline"
+
+ JEP-0013
+
+
+ message-node
+ A node for a specific offline message if service discovery is provided for messages
+ JEP-0013
+
+
+ ]]>
+ The Jabber Registrar includes "http://jabber.org/protocol/offline" in its registry of well-known Service Discovery nodes.
+&jep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace. There is one uses of such forms in offline message retrieval as described in the Requesting Number of Messages section of this JEP. The registry submission is as follows:
+
+ http://jabber.org/protocol/offline
+ JEP-0013
+
+ Service Discovery extension for number of messages
+ in an offline message queue.
+
+
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0013: http://www.jabber.org/jeps/jep-0013.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+When people speak to one another, they use various tones of voice and body language to express themselves. When communicating online, people have no easy way of expressing themselves clearly. By incorporating message tones into Jabber, people will be able to convey tones such as anger, sarcasm, and confusion.
+Tone can be added only to messages, and it is added as an <x> tag inside a message. The <x> tag will look something like this:
+The specified tone is included as CDATA within the <x> element.
+Here is an example of a message with a tone:
+Tones are not meant to be sent with every message. They should be used only in cases where a tone dramatically applies. The overuse of tones will cause them to lose their effect.
+Because tones are abstract and not clearly defined, there is no standard list of tones. Clients should receive the tone as it is and display it as plain text, in such a way that it is linked to a specific message. Clients may want to have a specified list of tones that a user can select from when sending a message.
+Tones should be short and simple. Here is a list of good tones:
+-
+
- angry +
- confused +
- excited +
- joking +
- sad +
- sarcastic +
- serious +
I have found the need in the past to migrate an account from + one server to another for various reasons. Many of the people who + ask me about Jabber ask if there is a way to migrate their account + from one server to another if the need arises. There is no reason + Jabber can not handle this internally and update all the + JID-references appropriately.
+ +Jabber servers come and go, especially ones run by people who + are just playing with the technology. Computers also die and + funding runs out. It can be hard on users to have to re-create + their rosters every time they have to change to a different + server. Administrators also want to provide an 'out' for their + users, so that they feel more secure in the time spent setting up + rosters. For these reasons there should be a way to migrate an + account from one server to another.
+ +A basic overview of the behavior would be as follows.
+-
+
- Bob has a jabber account on a server, floobin.cx + specifically: olduser@floobin.cx. + +
- Bob knows that the floobin.cx server is going to go down soon + and therefore needs to find a new jabber server. + +
- He realizes that jabber.org offers accounts to anyone, so he + sets out to migrate his account to jabber.org. + +
- Bob does not yet have an account on jabber.org. +
Throughout most of the account transfer the server hosting + the old account will be acting for the user. The end client + should have very little to do with the actual transfer.
+ +-
+
- Bob creates an account on Jabber.org: + bobsnewaccount@jabber.org. + +
- Bob logs into both bobsnewaccount@jabber.org and + olduser@floobin.cx. + +
- From olduser@floobin.cx he sends the 'I want to migrate my + account' packet to Floobin.cx. This packet includes the JID + to migrate to. + +
- Floobin.cx sends the 'user wants to migrate account to + you' packet to bobsnewaccount@jabber.org. This packet contains + the JID of the old account. + +
- bobsnewsaccount@jabber.org receives the 'user wants to + migrate account to you' packet and authorizes the + transfer. + +
- Once the migration is authorized the floobin.cx server + will start the migration process. The first part is to + notify each person subscribed to olduser@floobin.cx's + presence that the account has moved to + bobsnewaccount@jabber.org. + +
- Once that is complete the roster itself + must be added into bobsnewaccount@jabber.cx's roster. There are + many issues with that remain and should be dealt with in the + future. See the section on scope for more information. + +
- finally floobin.cx informs olduser@floobin.cx that the + transfer was completed. +
On acceptance the server on which the old account resides + starts the migration process by sending this to each person + subscribed to the user's presence.
+Once that update has been sent to all the contacts on the + roster the floobin.cx server sends to the jabber.org server airog@floobin.cx's roster as follows:
+Once the migration finishes a notification is sent to the user:
+Because we cannot determine easily if the new server will + support the same transports as the old server we cannot + easily transfer entities that pass through the + transport. Therefore, until jabber:iq:browse matures, or + some other solution for determining if two transports + support the same functionality we should not attempt to + migrate transport information.
+ +I propose the following algorithm for determining if a + particular roster item is a sub-item of a transport. There are + jabber roster items for each of the transports themselves, + something to the effect of icq.jabber.org or + aim.jabber.org. They contain no user portion of the jid. We + record all of these in a list that we will call the + 'transport-list'. Then for each roster item we want to migrate + we compare its 'host' part of the jid to all items in the + 'transport-list'. If the roster item matches, then the roster + item is a hosted through the transport and shouldn't be + migrated.
+Does the server keep an empty account that redirects requests + to the new account? I've been hearing mass rumblings of 'NO' + here.
+How do we handle vCard information or server side stored + preferences? Since the account we're migrating to can be any + account some of that information might already be there, how do + we resolve conflicts?
+ +Also, we cannot be sure that the new server supports + storage of private data. This again needs some sort of + features negotiation, discovery which could be provided by + jabber:iq:browse.
+ +Until jabber:iq:browse is in the 'standards' stage, I + recommend we only transfer regular jabber users, and not + transfer anything but the roster. All the client software will + have to set their preferences for themselves on the new + server.
+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:
+-
+
- 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. +
- 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. +
- 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:
+-
+
- +
- +
-
+
jabber:iq:oob +- +
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.
+Framing is the mechanism by which a listener is able to separate a stream of information into discrete semantic units. In Jabber, each of these semantic units is a fragment of a <stream:stream> document consisting of a direct (depth=1) child element of the <stream:stream> document element, and all its attributes and child nodes. These semantic units are hereafter called packets. A Jabber session document, excluding the document element start tag and end tag which are handled as special cases, is implicitly encoded into these packets and transmitted across the network.
+This JEP describes a framing method that may provide performance and code simplicity advantages over the framing method currently used.
+The current scheme for framing in Jabber relies on the inherent structure of XML to determine packet boundaries. Since each packet is a well-formed XML fragment, the start of the packet is unambiguously denoted by the element start tag at depth=1, and the end of the packet is unambiguously denoted by the corresponding close tag at depth=1.
+This method of framing is elegant because all the necessary framing information is inherent in the XML; it makes framing independent of the underlying transport layer so long as that transport layer guarantees per-session FIFO delivery. However, it has significant performance and implementation disadvantages, as it requires any Jabber node (endpoint or router) to XML-parse the packet as it is still being received in order to determine the packet boundary. Many XML parsing suites are not designed to be used in this manner, and various hacks and workarounds have emerged in current Jabber software in order to adapt them for this purpose.
+Consider a simple method that prefixes the byte length of each packet as an XML text node at depth=1. Put more simply, the transmitting agent calculates the byte length of the element it wishes to transmit. It then transmits this integer length encoded as text, immediately followed by the element.
+This technique has the following advantages:
+-
+
- The receiving agent is able to anticipate the size of the incoming packet. It can then buffer the element without having to parse it while it is only partially received, which is significantly more straightforward and more efficient to implement given the design of most current XML parsing suites. For large packets, this also allows the receiving agent to reduce potentially expensive memory realocation and copying. +
- A router needs not load the entire packet payload into a DOM; it has the option of parsing only the element start tag and retransmitting the rest of the packet verbatim after checking for well-formedness. +
- Since the framing data are just XML text nodes, their addition should be largely backwards compatible with current Jabber software, which should be made to ignore the extraneous depth=1 text with few, or possibly no, modifications. +
- Implementation of the protocol takes very little effort. Transmitting agents generally should know the size of the packets they are about to transmit. In comparison to the work they must currently do, receiving agents are only helped by the addition of framing data; in any case, interpretation of the framing data is optional. +
This technique has the following disadvantages:
+-
+
- The simple insertion of framing data into the streaming XML document does not pay attention to the logical distinction between the XML document and the framing transport over which it is being transmitted. +
- Error-handling semantics must be arbitrarily defined in the event that a transmitting agent misframes a packet (that is, sends the incorrect packet size). +
Framing data is included for the <stream:stream> and </stream:stream> tags as if they were their own packets, although they are not independently well-formed XML. These should be handled as special cases in a Jabber XML streams implementation.
+The connecting agent (client) implicitly requests that the receiving agent (server) use JEP-0017 framing by transmitting JEP-0017 framing data in its own outgoing stream (the connecting agent always "goes first"). Servers should detect the presence of framing data in the client's stream (by testing whether the first character received is a digit or a <) and, if it is detected, activate outgoing framing for that session.
+Regardless of the use of framing data, all nodes must verify the well-formedness of XML payloads in order to avoid propagating misframes.
+This framing method is not intended as a fully satisfactory or permanent solution to XML stream framing. In the "distant" (longer than one year) time span, it may be desirable to consider more thorough systems such as BEEP. The intent of this JEP is to establish an intermediate solution that will provide code simplicity advantages to new implementations in the near term without requiring fundamental changes to the Jabber transport or protocol (as adopting BEEP would almost certainly require).
+Jabber users have long wanted the ability to come online using Jabber, but appear "unavailable" to a subset of their roster, an ability which is commonly referred to as invisible mode. While several current implementations have various ways of providing this functionality, the systems currently in place often lack clear behavior and documentation. This document provides requirements for invisible mode and clarifies the existing protocol-in-use to provide the desired functionality.
+Note well: The functionality described herein can and should be implemented by means of the Privacy Rules namespace defined in &xmppim;. This document is provided for historical purposes only.
+The requirements for invisible mode are basic:
+-
+
- A user should be able to become visible or invisible at any time. +
- When in either mode, users should be able to selectively allow or block presence updates to be distributed to their contacts. +
For the purposes of this discussion, we will assume this terminology.
+-
+
- Undirected Presence - A presence stanza without a "to" attribute. +
- Directed Presence - A presence stanza with a "to" attribute. +
Assuming the user's client has authenticated with the system normally, it would send the following presence stanza to become invisible (note: this can be the initial presence stanza sent by the user). To do so, the client will send undirected presence with a type="invisible" attribute.
+If a user chooses to become visible after being invisible, the client will send undirected presence with a type="visible" attribute.
+If a user is visible to all of their contacts, and wishes to become invisible to selected contacts on their roster, then their client will send the following directed presence stanza.
+In this case, the server begins to track that the user is invisible to the contact joe@foo.com, and does not forward further presence updates to joe@foo.com. If the user wishes joe@foo.com to received further presence updates, then their client must send either an undirected presence stanza with a type="visible" attribute (see Example 2), or a directed presence stanza to joe@foo.com with a type="visible" attribute as below.
+The opposite behavior of the previous section should, also, be present in the server. For example, if a user is invisible to all of their contacts, they should be able to become visible to a selected contact by send a stanza similar to the one in Example 4.
+As with the previous section, a user can later choose to hide his presence updates for joe@foo.com by either sending an undirected presence stanza (see Example 1), or by sending a directed presence stanza to joe@foo.com (see Example 3).
+The above section documents the major points of the invisible mode protocol. It is important to understand how the server should interact with the protocol documented above.
+Normally, when a server receives a presence stanza, it stamps the appropriate 'from' attribute on the stanza and sends it on its way. If the stanza does not possess a 'to' attribute, the process of sending the stanza on its way involves broadcasting that stanza to all contacts listed in the user's roster. If the stanza does have a 'to' attribute, the stanza is simply routed to the correct contact. With the addition of invisible mode presence, the server MUST now verify that a stanza should be directed to contacts on a user's roster before sending it on. In addition, stanzas that are directly related to invisible presence (stanzas with a 'type' attribute of either "visible" or "invisible") MUST NOT be sent to any contacts, but MAY cause other presence stanzas to be sent instead.
+One of the biggest failings of older invisible mode implementations were client features like auto-away. In most cases, these auto-away stanza would inadvertently cause a user to become visible (although away) to all contacts on its roster. This invisible presence protocol has been designed to deal with that problem elegantly.
+Consider the following situation (the protocol for which is shown in the examples below):
+-
+
- joe@foo.com has contacts stpeter@foo.com, pgmillard@foo.com and rynok@foo.com on his roster. +
- joe@foo.com has logged into the foo.com sever, but has set his presence to invisible. +
- Assume that stpeter@foo.com, pgmillard@foo.com and rynok@foo.com are all online and visible. +
- joe@foo.com wants rynok@foo.com to see his presence updates, but not stpeter@foo.com or pgmillard@foo.com +
- joe@foo.com sets his presence to extended away. +
- joe@foo.com decides to become visible to all contacts on his roster. +
- joe@foo.com decides to become invisible to pgmillard@foo.com. +
- joe@foo.com set his presence to free to chat. +
Since joe@foo.com has just come online, the server SHOULD NOT forward any presence stanzas to contacts on his roster.
+Note that in this example, presence updates from joe@foo.com are routed only to rynok@foo.com, despite the fact that stpeter@foo.com and pgmillard@foo.com are both online and available. This is because joe@foo.com has chosen to be visible only to rynok@foo.com. If joe@foo.com chooses to become visible to his entire roster, he simply sends an undirected presence stanza with the type="visible" attribute. In this case the server SHOULD forward the last undirected presence stanza received to stpeter@foo.com and pgmillard@foo.com.
+Now Joe has decided that he doesn't want pgmillard@foo.com to receive further presence updates. Since he is currently visible to all contacts, he simply needs to send a directed presence stanza to pgmillard@foo.com with the type="invisible" attribute set.
+In this case, the server will send a directed presence stanza to pgmillard@foo.com with the type="unavailable" attribute set, which indicates to pgmillard@foo.com's client that joe@foo.com has gone "offline."
+Further presence updates sent by joe@foo.com will now be forwarded to stpeter@foo.com and rynok@foo.com, and MUST NOT be forwarded pgmillard@foo.com.
+The server MUST NOT forward presence stanzas containing the type="visible" or type="invisible" attribute to a client.
+There are no security features or concerns related to this proposal.
+No interaction with &IANA; is required as a result of this JEP.
+No namespaces or parameters need to be registered with the ®ISTRAR; as a result of this JEP.
+The Jabber Software Foundation is an experiment. When we initially set up our policies, processes, and structures, we knew that our initial thoughts might not be our final thoughts, and that we would need to make adjustments as experience dictated. In this JEP, I argue that just such an adjustment is now necessary with regard to the Jabber Interest Groups (JIGs).
JEP-0002
Unfortunately, it is widely recognized in the Jabber community that the JIGs are not working. Ten JIGs have been approved by the Jabber Council,
In perhaps the best measure of success or failure, only one JIG has produced a JEP for submission to the Jabber Council, and that JEP (JEP-0009
In other words, an honest assessment forces us to conclude that the JIGs are not working.
+I see several possible solutions to the JIG problem:
+-
+
- "Crack the whip" -- encourage and cajole the existing JIGs into becoming more active, and energetically manage them so that they produce JEPs. +
- "Wait and see" -- immediately disband the JIGs that are clearly inactive but keep the existing JIGs and hope that they will eventually produce something of value (over time disbanding any that are conspicuously inactive). +
- "Bite the bullet" -- recognize that, for whatever reason, the existing structure (many special-purpose interest groups) is not working and seek a better way to produce enhancements to the Jabber protocols. +
Given the lack of activity in the JIGs so far (and the lack of time available to those who would manage them), I am skeptical that "cracking the whip" will produce results, and I believe the onus of proof is on those who would argue that the existing JIGs can be successful. Similarly, taking a "wait and see" attitude will simply let a bad situation continue unchecked, and in my opinion will at some point require us to choose between option 1 and option 3. Rather than postpone the day of reckoning, I argue that we need to address the problem head-on and take action to streamline the JIGs and find a better way of working.
+But what is that "better way"? In order to figure that out, we need to understand why things are not working now. I don't think it's that the current JIG members are lazy, stupid, or incompetent -- after all, these are the same people who have in many instances created good Jabber-based software. Nor do I think it's that members of the Jabber community are incapable of creating JEPs, because individually and in small, ad-hoc groups they have created quite a few.
+I see several reasons why the JIGs are not working:
+-
+
- The Jabber community right now is too small to be split up successfully into smaller interest groups. +
- We have tried to overlay too much structure too quickly. Jabber has traditionally been a fairly anarchic project (or set of projects), and creating ten JIGs right away was at odds with that successful lack of structure. +
- Good JEPs, like good software programs, are usually created by at most a few interested people, not a formal group. Formal groups are not needed to move Jabber forward. +
If we reflect on what is working, we see that JEPs are being produced by individuals and small, ad-hoc groups. We also see that active discussion of those proposals is taking place in the Standards JIG, which contains everyone who is strongly interested in the Jabber protocols. Finally, we notice that the special-purpose JIGs have not played any appreciable role in our success so far.
+My proposed solution takes into account everything we have learned to date about producing JEPs and advancing the state of the Jabber protocols. Specifically, I propose that we take the following steps:
+-
+
- Immediately disband all but the Standards JIG.
In an earlier version of this JEP, I proposed that we retain the Security JIG. However, since there is a security aspect to all protocols, I now think it is best if security-related topics are discussed within the Standards JIG, not in a separate Security JIG.
+ - Rely on individuals and small, ad-hoc groups to create JEPs. +
- Continue to use the Standards JIG as the preferred forum for discussion of experimental JEPs before they are submitted to the Jabber Council. +
- If the Standards JIG cannot reach a working consensus on a given topic, let the JEP author(s) continue to rework their proposal informally outside the context of the Standards JIG.
One option would be to send interested parties off to their own ad-hoc mailing list (e.g., on JabberStudio, http://www.jabberstudio.org/). Unlike the current JIGs, such a list would be established on the initiative of the JEP author(s) and would not require any formal approval by the Jabber Council.
+
There may be value in bringing back specialized JIGs in the future when the Jabber community becomes larger. However, at this time I urge that we face the facts and proactively implement the solution I have outlined in this JEP.
A discovery protocol such as &jep0030; enables Jabber entities to query other entities regarding the features they support, but does not provide a means for the two entities to negotiate specific options related to the advertised features (e.g., specific methods of file transfer such as &jep0047; or &jep0065;).
+The protocol defined herein enables Jabber entities to negotiate options for specific features. These features could be negotiated between any two endpoints on the Jabber network, such as two clients, a client and a component, two components, a client and a server, or two servers. The protocol is generic enough that it can be used whenever options need to be negotiated between two Jabber entities.
+Features are negotiated though the exchange of &IQ; stanzas containing &QUERY; child elements qualified by the 'http://jabber.org/protocol/feature-neg' namespace. However, this &QUERY; element is simply a wrapper for structured data encapsulated in the &jep0004; protocol.
In order to begin a negotation, the initiator sends an &IQ; stanza of type "get" to the recipient with a single <feature/> element containing a data form of type "form" which defines the available options for one or more features. Each feature is represented as an x-data "field", which MUST be of type "list-single" as specified in JEP-0004.
+The recipient SHOULD examine each feature and the options provided. In order to indicate preferred options, the recipient then SHOULD specify one option for each feature and return a data form of type "submit" to the initiator in an &IQ; stanza of type "result".
+The following examples show some likely scenarios for feature negotiation between entities. Further examples can be found in using protocols, such as &jep0096;.
+A typical negotiation flow is shown in the following example of two entities negotiating the time and place for a meeting.
+If the responding entity does not support one or more of the features, it MUST return a &feature; error, and SHOULD specify the feature(s) not implemented in the XMPP <text/> element.
+If the responding entity supports none of the options offered for a certain feature, it MUST return a ¬acceptable; error, and SHOULD specify the relevant feature in the XMPP <text/> element.
+If at least one feature offered by an entity is subject to &jep0020;, the entity's response to a service discovery information request MUST include <feature var='http://jabber.org/protocol/feature-neg'/> as one of the features.
+The using protocol (in these examples, &jep0045;) SHOULD specify which features might be negotiable, either in the relevant documentation or in the entry for that feature in the service discovery features registry maintained by the Jabber Registrar. However, the requesting entity MAY also query the responding entity in order to determine which features are negotiable, as shown below.
+The using protocol (in these examples, JEP-0045) SHOULD specify which features might be negotiable, either in the relevant documentation or in the entry for that feature in the service discovery features registry maintained by the Jabber Registrar (see <http://www.jabber.org/registrar/disco-vars.html>). However, the requesting entity MAY also query the responding entity in order to determine which features are negotiable, as shown below.
+If that feature is not negotiable, the responding entity MUST return a "Feature Not Implemented" error:
+If that feature is negotiable, the responding entity MUST return an appropriate negotiation form:
+The requesting entity MAY then submit a data form containing the required information.
+Security considerations are the responsibility of the using protocol.
+This JEP requires no interaction with &IANA;.
+In order for Jabber entities to adequately leverage Data Forms (e.g., by using machine-readable fields), it is RECOMMENDED to register standard x-data fields with the ®ISTRAR; via the mechanisms defined in &jep0068;. Whether to do so for any given features and options shall be determined by the using protocol.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0020: http://www.jabber.org/jeps/jep-0020.html
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Peter Millard, the primary author of this specification from version 0.1 through version 1.4, died on April 26, 2006. The remaining author is thankful for Peter's work on this specification.
+The Jabber Event Notification Service (ENS) acts as a dispatcher and may be used by applications as a central point of collection for certain types of events that are of interest to them. Examples of events include:
+ +-
+
- User has logged in +
- A new message has arrived +
- User's avatar has changed +
- The coffee machine is empty +
In Jabber, the role of the ENS has traditionally been filled by overloading the <presence/> packet type. However, this method was never designed to be used as a general publish-and-subscribe mechanism, and so has the following problems:
+ +-
+
- Dispatching of <presence/> packets is performed by the JSM (Jabber Session Manager), and so is not easily usable by components and other entities that don't connect via a client manager (c2s, CCM). +
- An entity cannot subscribe to the presence of a specific resource of another entity, only to any presence from that entity. This lack of granularity makes its difficult to use <presence/> in situations where large chunks of data must be dispatched to subscribers (eg avatars). +
The protocol consists of two parts - the subscriber-to-ENS protocol, and the publisher-to-ENS protocol. Since there is no direct interaction between a publisher and a subscriber, it makes sense to seperate the two parts of the protocol.
+ +The protocol operates in the 'http://xml.cataclysm.cx/jabber/ens/' namespace.
+ +A reference implementation is available at http://cataclysm.cx/jabber/ens.html.
+Before we begin describing the protocol, is it necessary to define some terms, including the function and responsibilties of the entities that communicate with the ENS.
+ +An event can be defined as a change to the value of one or more properties of a resource.
+ +In the ENS, an event type is referred to by a JID (Jabber IDentifier), including the JID resource. For example, consider a hypothetical publisher that is linked to an IMAP message store. It might notify the ENS of the fact the a message has arrived, deleted, or filed, using the following JIDs:
+ +-
+
- rob@imap.cataclysm.cx/NewMessage +
- joe@imap.cataclysm.cx/DeletedMessage +
- jim@imap.cataclysm.cx/FiledMessage +
Alternatively, an end-user client that wanted to notify the ENS when its avatar changes might do so using a JID like "rob@cataclysm.cx/avatar"
+A subscriber is a Jabber entity that receives notifications about events. Usually, a subscriber will be an end-user client, but it may be any Jabber entity.
+ +As the name suggests, a subscriber can subscribe and unsubscribe to various events via the ENS. When it subscribes, the publisher responsible for the event it is subscribing to will be asked by the ENS to authorise the subscription request. To facilitate this, the subscriber may provide an XML fragment containing information that the publisher can use to authorise it. The use of this fragment is application specific. +
+ +Once subscribed to an event, the subscriber will receive any notifications that the publisher sends about that event.
+A publisher is the Jabber entity responsible for actually sending event notifications to the ENS. A notification contains the event type JID of the event that occured, and an optional "payload" XML fragment, that is passed untouched by the ENS to the subscriber. The contents of this payload is application-specific and can be used to provide detailed information about the event to the subscriber. For example, in the case of the NewMessage event above, the payload might contain the contents of the To:, From: and Subject: headers of the message.
+ +Additionally, the publisher is responsible for deciding who may subscribe to events it publishes. When the ENS receives a subscription request, it will ask the publisher to decide whether or not the subscriber may subscribe to a particular event. This authorisation request may also contain an XML fragment from the subscriber containing information that may be used for authorisation.
+To subscribe to a particular event, the subscriber sends a packet like of the following form to the ENS:
+ +The subscriber may include an <auth-info/> XML fragment containing some (application-specific) information that the publisher can use to authorise it:
+ +If it wishes, the subscriber may request a "reliable" subscription. This option guarantees that the subscriber will receive all notifications about this event (as far as the Jabber architecture guarantees delivery). This changes the semantics of the subscriber publish protocol - see section 3.6 for more details.
+ +Once subscribed, the ENS will return a packet of the following form to the subscriber:
+ +If an error occured during subscription (such as the publisher not allowing the subscriber to subscribe), an error packet will be returned to the subscriber:
+ +The actual error fragment in the packet is a direct copy of the one returned by the publisher when it fails the authorisation request from the ENS. If the publisher does not provide one, error code 503 (Service Unavailable) will be returned instead. If the publisher does not respond to the authorisation request (after an implementation-specific timeout), error code (Remote Server Timeout) will be returned.
+To unsubscribe from a particular event, the subscriber sends a packet like of the following form to the ENS:
+ +Once unsubscribed, the ENS will return a packet of the following form to the subscriber:
+ +No further notifications for the event will be received.
+When a publisher publishes a notification to the ENS, the ENS will forward the notification to any subscribers for that event. A notification sent to a subscriber takes the following form:
+ +A notification may also contain a (application-specific) "payload" XML fragment:
+ +Section 4.1 has more information about the payload.
+ +If the subscriber responds to the notification with an error, the subscriber will be automatically unsubscribed from the event by the ENS.
+If the <reliable/> option was specified when the subscriber subscribed to the event, then the subscriber is expected to acknowledge a notification with a packet of the following form:
+ +If the subscriber does not respond, or responds with an error, the notification will be resent by the ENS after a (implementation-specific) timeout.
+To publish a notification, the publisher sends a packet of the following form to the ENS:
+ +A notification may also contain a (application-specific) "payload" XML fragment:
+ +The payload can be any well-formed XML data. Everything inside the <publish/> tag will be forwarded untouched to the subscriber.
+Once the ENS has dispatched the notification to subscribers, it will return a packet of the following form to the publisher:
+ +A publisher is required to approve subcription requests. When a subscriber attempts to subscribe to an event, the publisher will receive a packet of the following form from the ENS:
+ +The subscriber may include an <auth-info/> XML fragment containing some (application-specific) information that the publisher can use to authorise it:
+ +To signal to the ENS that a subscriber should be allowed to subscribe, the publisher should return a packet of the following form:
+ +To deny the subscription, the publisher should return an error packet, containing the appropriate <error/> fragment:
+ +The <error/> fragment will be copied untouched into the error response sent back to the subscriber. See section 3.2 for more details.
+The ENS will respond with error code 400 (Bad Request) any time it receives a request that it cannot understand (a malformed packet, for example).
+ +Other errors may occur, and they are described in the appropriate sections of the above protocol specification.
+The following items should be discussed before this proposal is approved by the Council:
+ +The ENS, as described, works well. However, no provisions are made for a subscriber to find out which ENS a publisher is publishing to. It does a subscriber no good to subscribe to an event on the wrong ENS - the subscription would succeed (assuming the publisher allows it), but no notifications would ever be received.
+ +There are several potential solutions, each with their problems:
+ +-
+
- Leave it to the subscriber to find the appropriate ENS outside of the ENS framework itself. This might be via a browse to the publisher, or maybe just entering it into their client's configuration. Obviously, this is very application-specific. +
- Force the publisher to publish to multiple ENSs, as necessary. This would require additions to the protocol (to tell the publisher of new ENSs), and would require the publisher to maintain a list of JIDs it needs to publish to. This solution is pointless - if the publisher is going to publish to multiple JIDs and maintain its own list, it might as well publish direct to subscribers. +
- Have some sort of ENS-to-ENS protocol, and have ENSs proxy publishes for other ENSs. This does not fix the problem, it just moves it away from the subscriber and into the ENS. An ENS will still need to find out which ENS the publisher is publishing to. +
- Integrate ENS into the session manager. This leaves us with a glorified presence system, and makes the ENS basically unusable by non-session-manager-based server components. +
This problem may be outside of the scope of this specification.
+Currently, if a subscriber obtains a reliable subscription, and then disappears from the network (as an end-user client might), the ENS will continue to send notifications to it (ignoring errors) until it unsubscribes. If the subscriber never comes back, then ENS will send notifications forever (in theory).
+ +At what point should even <reliable/> have its limits? Should we unsubscribe a reliable subscriber who bounces (ie. the Jabber server failed to deliver) more than, say, 10 publishes? Or maybe they should be unsubscribed if they do not respond (as in section 3.6) to anything for, say, 10 minutes?
+ +<reliable/> is an interesting idea, but it may be that it is too problematic for its own good.
+The topic of reliable subscriptions raises the question as to how long a subscription lasts. Should a subscription last forever (like <presence/> does), even across restarts of the server?
+ +If end-user clients are to be subscribers, then under this scheme the ENS would have to subscribe to presence, so as to know when the client has disconnected. Since presence is a function of the session manager, this could have the effect of making the ENS less generic that we may like.
+As I see it, basic presence will always be a function of the session manager, for the following reasons:
+ +-
+
- No ENS discovery problems +
- Subscriptions are maintained across sessions +
- In very widespread use (ie. everywhere) +
I think the places where the ENS can boom will be in applications like avatars, and genuine event-based systems (like the kind described above - "you have new mail", "someone has scheduled a meeting with you in your online calendar", etc).
+The 'jabber:x:event' namespace defines extensions used to request and respond to events relating to the delivery, display, and composition of messages.
+By attaching a jabber:x:event extension to a &MESSAGE; element, the sender can track stages in the delivery of that message to its recipient.
+There are four message events currently defined in this namespace:
+ +Indicates that the message has been stored offline by the intended recipient's server. This event is triggered only if the intended recipient's server supports offline storage, has that support enabled, and the recipient is offline when the server receives the message for delivery.
+Indicates that the message has been delivered to the recipient. This signifies that the message has reached the recipient's Jabber client, but does not necessarily mean that the message has been displayed. This event is to be raised by the Jabber client.
+Once the message has been received by the recipient's Jabber client, it may be displayed to the user. This event indicates that the message has been displayed, and is to be raised by the Jabber client. Even if a message is displayed multiple times, this event should be raised only once.
+In threaded chat conversations, this indicates that the recipient is composing a reply to a message. The event is to be raised by the recipient's Jabber client. A Jabber client is allowed to raise this event multiple times in response to the same request, providing the original event is cancelled first.
+Extensions qualified by the jabber:x:event namespace may be used only in the context of &MESSAGE; elements. That is, event information should be requested, and given in response, in relation to &MESSAGE; elements only, and not &PRESENCE; or &IQ; elements.
+Event information should only be sent in response to a request for that information. Unsolicited event information is illegal. In addition, a client should not request message event information from a correspondent if it is known (for example through the results of a previous browse request) that the correspondent does not support message events.
+Any request for the offline event in a message that has been stored offline must be removed by the server before the message is forwarded to the Jabber client. This means that any <offline/> tag should be removed from the extension.
+ +Event notifications are requested by attaching an extension qualified by the jabber:x:event namespace to a &MESSAGE; element. A tag representing each event type requested for that message should be placed within the extension. Only one jabber:x:event extension may be attached to a &MESSAGE; element, but multiple event types may be requested within that one extension. The tags representing each of the event types are <offline/>, <delivered/>, <displayed/>, and <composing/>.
+An example of a &MESSAGE; element with a jabber:x:event extension is shown here.
+Here we see the sender wants to be notified if the message is stored offline (by the server), notified when the message is delivered (to the client), and notified if the recipient begins replying to the message. In this case, the sender will potentially receive three events based on this request. The first if the recipient is offline and the message is stored on the server, the second when the recipient becomes available and the message is delivered, and the third if the recipient begins composing a reply to the message.
+Note that the &MESSAGE; element requesting event notification contains an 'id' attribute. While these attributes are optional in the Jabber protocol, messages that contain event notification requests MUST contain an 'id' attribute so that raised events may be matched up with their original requests.
+If the message is stored by the server, the server must raise the requested event (offline) by sending a message to the sender as shown in this example:
+When raising an event, the raiser must send a &MESSAGE; element constructed according to the following rules:
+-
+
- The element must contain only a jabber:x:event extension. Standard message elements such as <subject/>, <body/>, MUST NOT be included. +
- The extension must contain one tag representing the event being raised. For example, if the offline event is being raised, an <offline/> tag must be included. (The events are temporally exclusive, thus only one event tag should ever be included.) +
- The extension must also contain an <id/> tag. The contents of this tag MUST be the value of the 'id' attribute of the original message to which this event notification pertains. (If no 'id' attribute was included in the original message, then the <id/> tag must still be included with no CDATA.) +
- The message's from attribute should be set to the recipient of the original message for which the event is being raised. (This is an issue more relevant for the server, in responding to the offline event, because clients should rely on the server to stamp the elements that they send out with a from attribute.) +
- The link between the original message for which the event is being raised, and the message containing that raised event, is the <id/> tag in the jabber:x:event extension of the message containing that raised event, that points to the id attribute of the original message. +
The composing event is slightly different from the other events in that it can be raised and cancelled multiple times. This is to allow the reflection of what actually is happening when a user replies to a message; he may start composing a reply, which would trigger the composing event, get halfway through, and stop (by some definition of "stop", which may be implementation-specific). At this stage the event is no longer valid, or at least doesn't make much sense. So the client may send a cancellation for the composing event just raised.
+The cancellation is raised by sending another jabber:x:event; however, in contrast to how the events are usually raised, no <composing/> tag is sent, just an <id/> tag, like this:
+The lack of an <composing/> tag (and any other event tag) signifies that the composing event, indicated previously by the id value, has been cancelled. In this example, the composing event being cancelled is that event that was previously raised with the id of message22. After cancelling a composing event, a new one may be raised, following the same rules as before, when the typing of the reply is resumed.
+This section contains a number of examples to illustrate the full flow of messages, event notifications, and event cancellations for a fictional conversation.
+Romeo temporarily loses his wireless connection in the Capulet's orchard and therefore his message is stored offline by the montague.net server, which generates the offline event and sends that notification to Juliet.
+Romeo reconnects and the message is delivered to his Jabber client, which generates a delivered event and sends it to Juliet's client.
+Romeo's Jabber client displays the message and sends a displayed event to Juliet's client.
+Romeo begins composing a reply to Juliet's heartfelt question, and his Jabber client notifies Juliet that he is composing a reply.
+Romeo realizes his reply is too rash and pauses to choose the right words; his Jabber client senses the delay and cancels the previous composing event.
+Romeo starts composing again, and his Jabber client sends a notification to Juliet's client.
+Romeo finally sends his reply, and requests composing events related to it.
+Compliant implementations SHOULD observe the following business rules:
+-
+
- Every outgoing message sent from a compliant client should contain a request for event notifications (if such notifications are desired). The request for notifications cannot be sent just once in a conversation, since it applies to every message sent. +
- When a client receives a request for events from another entity, it should cache the most recent ID. +
- When a user begins replying to a message received from a contact, the user's client should check to see whether events have been requested by the contact for that message and set the CDATA of the <id/> element to the cached ID value. +
- The CDATA of the <id/> element MUST be the same as the value of the 'id' attribute of the notification request. +
There are no security features or concerns related to this proposal.
+This JEP requires no interaction with &IANA;.
+No action on the part of the ®ISTRAR; is necessary as a result of this JEP, since 'jabber:x:event' is already a registered protocol namespace.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0022: http://www.jabber.org/jeps/jep-0022.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+-
+
- In a Standards Track JEP addressing event functionality, it would be desirable to have more cancellation methods for composing events than those defined in this Informational JEP. For instance, is someone still composing if they become unavailable? This example points to the fact that cancellation of a composing event can either be explicit (the default or desired scenario) or implicit (e.g., through a change in the availability state of a client or the existence of the session associated with the message composition). +
Note Well: The protocol described herein has been deprecated by the &JSF;. The recommended protocol for implementing message expiration functionality is now &jep0079;.
+It is sometimes helpful to indicate that a piece of information has a finite useful life or time-to-live (TTL). In the context of instant messaging, the main use of a TTL is to indicate that a message must or should be used by or read by a certain time, usually because the message has meaning or purpose only within a finite amount of time. In normal usage, such a message should be discarded after the specified time has passed if it has not been used or read by that time.
+In Jabber, TTL functionality has been implemented informally using the jabber:x:expire namespace. Support for this namespace was added to the &jabberd; server as well as some clients and components in early 2001. Specifically, that support has involved the following two areas of responsibility:
+-
+
- The sender of the message is responsible for attaching a jabber:x:expire extension to the XML stanza (usually a message). +
- Mechanisms involved in the store-and-forward of such a stanza
+
The best-known example of a mechanism that handles storing and forwarding of XML stanzas is the Jabber Session Manager (JSM) within current Jabber server implementations, specifically the mod_offline module. However, expiration of an XML stanza could also be handled by a Jabber client. +en route to its intended recipient are responsible for checking the remaining time to live and expiring (discarding) the XML stanza if necessary.
+
An Endpoint can specify a TTL for an XML stanza that it wishes to send by attaching an <x/> extension qualified by the jabber:x:expire namespace. The extension contains no children, only a 'seconds' attribute that contains a value representing the stanza's TTL, in seconds.
+ +Any mechanism that is involved in the storage, forwarding, and general handling of XML stanzas must check for the presence of such an extension and act accordingly, expiring (discarding) any stanzas that have exceeded their TTL lifetime. The jabber:x:expire namespace allows for a further attribute inside the <x/> extension: 'stored'. Here, the mechanism can record a value representing when the stanza was committed to storage, so that when the stanza is eventually retrieved for forwarding to the intended recipient, the elapsed time of storage can be calculated. This is to prevent the stanza from being held in 'suspended animation'.
+Here we see what the original message looks like after the stanza has been committed to storage and the time of storage recorded:
+When Sabine attempts to retrieve her offline messages, the store-and-forward mechanism (e.g., mod_offline) compares the current time against the stored attribute. If the 1800 seconds have passed, the mechanism should simply drop the message, without notifying either the sender or the intended recipient. No Eccles cakes for Sabine!
+Although current usage of jabber:x:expire is most commonly seen in server implementations to address any TTL requirements of stored messages, Jabber clients can also be seen as handlers of messages that may contain expiration extension information. If a message is received by a Jabber client, and not immediately displayed to the user, the client must check for TTL information and expire the message (rather than display it to the user) if appropriate.
+There are no security features or concerns related to this proposal.
+This JEP requires no interaction with &IANA;.
+No action on the part of the ®ISTRAR; is necessary as a result of this JEP, since 'jabber:x:expire' is already a registered protocol namespace.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0023: http://www.jabber.org/jeps/jep-0023.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+-
+
- The jabber:x:expire namespace is processed only for delayed messages and only by servers and subsystems which support this informational draft. Therefore it is possible or even likely that a TTL will not be properly handled from the user perspective. +
- A physical, time-based TTL is not implemented by this JEP, and would not be possible across systems without synchronized time. +
+Pubsub ("publish/subscribe") is a technique for coordinating the efficient
+delivery of information from publisher to consumer. This specification
+
-
+
- to be able to exchange information _within_ a Jabber environment +(for example continuously changing personal information between users) +
- to be able to exchange information _using_ Jabber as a mechanism for
+
-
+
- organising that exchange +
- providing transport for the information +
+
+The specification details the use of the Jabber protocol elements and +introduces a new namespace, jabber:iq:pubsub. +It also includes notes on actual implementation of such a +mechanism in Jabber. +
+ ++It's clear that as Jabber is deployed over a wider spectrum of platforms +and circumstances, more and more information will be exchanged. Whether +that information is specific to Jabber (JSM) users, or components, we need +an mechanism to be able to manage the exchange of this information in an +efficient way. +
+ ++For example, it is currently the trend to embed information about a +particular client's circumstance inside presence packets, either in the +<status/> tag or in an <x/> extension. One example that comes +to mind is "song currently playing on my MP3 player" (to which I have to +admit some responsibility for the meme in the first place). While embedding +information inside presence packets and having that information diffused to +the users who are subscribed to that user's presence has the desired effect, +it has a couple of non-trivial drawbacks: +
+ +-
+
- the diffusion is inefficient, sending potentially huge amounts of data +to recipients who aren't interested +
- the distribution is tied to closely to presence subscription; any entity +that wants to receive information must be subscribed to the source's presence, +and there is no mechanism for specifying _what_ information they wish to +receive. It is also arguably too closely tied to the JSM to be useful for +_component_-based information exchange. +
+This is above and beyond the simple fact that this overloading of presence +packets and the presence subscription and diffusion mechanism can only end +in tears. +
+ ++It would be far better to have a separate (sub-)protocol that enabled +entities to take part in publish/subscribe relationships, and have a service +that facilitated the efficient exchange of information. Not only would it +relax the undue pressure on the presence mechanism, but it would also allow +people to use Jabber, which is, after all, about exchanging structured content +between endpoints, as a publish/subscribe _mechanism_ in its own right. +
+ +
+This specification describes a publish/subscribe protocol in terms
+of IQ packets with payload data in a new namespace, jabber:iq:pubsub. The
+choice for this namespace is slightly arbitrary - it was the same namespace
+used in temas's original document, seems to fit well, and we need a namespace
+to focus on.
+The aim of the specification is to provide for a facility where Jabber +entities can subscribe to (consume) and publish (emit) information in an +efficient and organised way. These entities could be JSM users or components. +
+ ++Push technology is back with a vengeance. Jabber can play a fundamental +part. +
+ ++The pubsub services will be typically provided by a component. In what +follows, there are generally three parties involved: +
+ +-
+
- the subscriber +
- the pubsub service +
- the publisher +
+Bear in mind that it is perfectly possible for a subscriber to be a +publisher, and a publisher to be a subscriber, too. +
+ ++The pubsub traffic will be carried in info/query (IQ) packets. All of the +data in these packets will be qualified by the jabber:iq:pubsub namespace. +
+ ++Pubsub scenarios can be seen in a subscribe (or unsubscribe) context or a +publish context. In light of this, we will examine the IQ packets +used in these contexts. +
+ ++A potential consumer, or recipient, of published information, needs to +request that he be sent that published information. Requesting to receive, +or be pushed, information is known as subscribing. +
+ ++A subscription request generally takes this form: +
+ ++Note - sections inside [...] are optional. +
+ ++Subscriptions can be specific to a publisher, in which case a to attribute +is specified in the <subscribe/> tag: +
+ ++In this case, the namespaces specified will be added to any existing list +of namespaces already recorded for that subscriber:publisher relationship. +In other words, it's a relative, not an absolute, subscription request. +
+ ++It is also possible in a publisher-specific subscription to omit specific +namespaces, if you want to be sent everything that particular publisher +might publish: +
+ ++This type of subscription should have the effect of absolutely replacing any +previous namespace-specific subscription to the publisher specified. +
+ ++If a subscriber wishes to cancel a subscription from a particular publisher, +he can send an unsubscribe like this: +
+ ++This should have the effect of removing the subscription from that publisher +for the namespaces specified. +
+ ++You can also send an unsubscribe without specifying any namespaces: +
+ ++This should have the effect of removing any subscription relationship with +the publisher specified. Note, however, that this won't stop the subscriber +being pushed information from that publisher if he's specified a +"publisher-generic" subscription (see next section). +
+ ++As well as being able to subscribe to specific publishers, it is also +possible to subscribe to receive data, according to namespace, regardless +of publisher: +
+ ++This means that the subscriber wishes to be pushed information in the +namespaces specified, regardless of who publishes it. Like the +publisher-specific subscribe that specifies namespaces, this request is +relative, in the namespaces are added to any existing namespaces already +recorded for this generic subscription. +
+ ++Subscribing to everything from everyone is probably not a good idea and +we should not allow this. (The format of the request is actually used in +an IQ-get context - see later). +
+ ++Likewise, you can unsubscribe from certain namespaces in this non-publisher-specific context like this: +
+ ++If there are any subscriptions to specific publishers for the namespaces +specified here, they should be removed (for those namespaces) in addition +to the removal from the 'all publishers' list. +
+ ++Finally, a subscriber can wipe the slate clean like this: +
+ ++which should have the effect of removing all namespace subscriptions +from everywhere. +
+ ++All the examples so far have shown actions on the subscriber's part, and +have consisted of IQ-sets. In an IQ-set, within the jabber:iq:pubsub +namespace, multiple children can exist in the query payload, but those +children must be of the same type. In other words, you can send multiple +<subscribe/>s, or multiple <unsubscribe/>s, but not a combination +of the two. +
+ ++This is allowed: +
+ ++But this is not allowed: +
+ ++In the case where multiple <subscribe/>s or <unsubscribe/>s +appear in an action, each element will be processed in turn, as they appear +in the payload. +
+ ++As well as actions, the subscriber can query his subscription using an +IQ-get in the jabber:iq:pubsub namespace. This should return a list of +the subscribers current subscriptions, like this: +
+ ++Note the two references to namespace:2 - one inside the non-publisher-specific +subscription list and one inside the subscription list specific to publisherA. +This example implies that the non-publisher-specific and publisher-specific +subscription information should be kept separately. This is designed to make +it easier on the subscriber to manage his specific subscriptions over time. +
+ ++In contrast to the subscribe and unsubscribe context, the publishing +context is a lot simpler to explain. +
+ ++A publisher can publish information within a certain namespace, like this: +
+ ++It's also possible for a publisher to publish more than one item at once, +like this: +
+ ++Each published item is wrapped in a <publish/> tag. This tag +must contain the namespace of the item being publishes, in an ns +attribute, as shown. This is distinct from the xmlns attribute of +the fragment of XML actually being published. It is theoretically +none of the pubsub component's business to go poking around in the +real published data, nor should it have to. It needs to know what +namespace is qualifying the published information that has been +received, so that the list of appropriate recipients can be +determined. +
+ ++While it's the responsibility of the publishing entities to publish +information, it's the responsibility of the pubsub +component to push out that published data to the subscribers. The +list of recipient subscribers must be determined by the information +stored by the pubsub component as a result of receiving subscription +requests (which are described earlier). +
+
+On receipt of an IQ-set containing published information, the pubsub
+entity must determine the list of subscribers to which that information
+should be pushed. If the IQ-set contains multiple <publish/>
+fragments, this process must be carried out for each one in turn.
+
+Taking the earlier example of the publishing of data in the 'foo' +namespace, the following example shows what the pubsub component +must send to push this foo data out to a subscriber. +
++The recipient is _not_ required to send an 'acknowledgement' in the +form of an IQ-result; the idea that this _push_ of information is +akin to how information is pushed in a live browsing context (see +jabber:iq:browse documentation for more details). +
+ ++When a pubsub service receives a publish packet like the ones above, it +needs to deliver (push) the information out according to the subscriptions +that have been made. +
+ ++However, we can introduce a modicum of sensitivity by using a presence +subscription between the pubsub service and the subscriber(s). If the +subscriber wishes only to receive information when he's online (this is +a JSM-specific issue), then he needs to set up a presence subscription +relationship with the pubsub service. The pubsub service should respond +to presence subscriptions and unsubscriptions by +
+ +-
+
- accepting the (un)subscription request +
- reciprocating the (un)subscription request +
+If the pubsub service deems that a published piece of information should +be pushed to a subscriber, and there is a presence subscription relationship +with that subscriber, the service should only push that information to the +subscriber if he is available. If he is not available, the information is not +to be sent. +
+ ++Thus the subscriber can control the sensitivity by initiating (or not) a +presence relationship with the service. If the subscriber wishes to receive +information regardless of availability, he should not initiate a (or cancel +any previous) presence relationship with the service. +
+ ++This loose coupling of presence relationships for sensitivity allows this +specification to be used in the wider context of component-to-component +publish/subscribe where presence is not a given. +
+ ++When in receipt of a pubsub subscription request from an entity +where a resource is specified in the JID, the pubsub component must +honour the resource specified in the from attribute of the request. +For example, here's a typical subscription request from a JSM user: +
++When storing the subscriber/publisher/namespace relationship matrix for +eventual querying when a publisher publishes some information, the +pubsub component must use the full JID, not just the username@host part. +
++Similarly, in this example: +
++the full JID of the component subscriber - news.server/politics-listener, +should be used to qualify the matrix. +
++This is because it allows the subscribing entities to arrange the +receipt of pushed items by resource. In the case of a JSM user, it +allows him to organise his clients, which may have different capabilities +(some being able to handle the jabber:iq:pubsub data, others not) to +receive the 'right' data. In the case of a component, it allows the +component to associate component-specific data with incoming published +namespace-qualified information. +
+ ++While the specification describes the fundamental building blocks of the +pubsub protocol, there are ideas that are not discussed above but nonetheless +may be incorporated into an implementation. There are other considerations +that have to be made in the wider context of publish and subscribe. Some of +the main ones are discussed briefly here too. +
+ ++There is no part of this pubsub specification that determines how a +potential subscriber might discover publishers. After all, there are +no rules governing which pubsub component a publisher could or should +publish to. And since pubsub subscriptions are specific to a pubsub +component, there is an information gap - "how do I find out what +publishers there are, and through which pubsub components they're publishing +information?" +
++This problem domain should be solved using other methods, not with the +actual jabber:iq:pubsub specific namespace. A combination of jabber:iq:browse +usage (the magic ointment that heals all things) and perhaps a DNS style +(or at least root-node-based) knowledge hierarchy might be the right +direction. +
++In the case where a server administrator wishes to facilitate pubsub +flow between JSM users on a server, a pubsub component can be plugged +into the jabberd backbone, and there is potentially no real issue with +knowing which pubsub component to use, and where it is. +But what about if the JSM users on one server wish to build pubsub +relationships with JSM users on another server? (Note that this general +question is not specific to JSM users, although that example will be used +here). The next two sections look at how these things might pan out. +
++When JSM users on server1 wish to subscribe to information published +by JSM users on server2 (let's say it's the mp3 player info, or avatars) +then there are some issues that come immediately to mind: +
+-
+
- Does a JSM user on server1 (userA@server1) send his IQ-set subscription +to the pubsub component on server2 (pubsub.server2), or server1 +(pubsub.server1)? +
- If he sends it to pubsub.server2, can we expect +pubsub.server2 to always accept that subscription request, i.e. to +be willing to serve userA@server1 (if pubsub.server2 knows that +pubsub.server1 exists)? +
- Will there be performance (or at least server-to-server traffic) +implications if many subscription relationships exist between subscribers on +server1 and publishers on server2? +
+To reduce the amount of server-to-server traffic, we can employ the +concept of "proxy subscriptions". This is simply getting a pubsub component +to act on behalf of a (server-local) subscriber. Benefit comes when a pubsub +component acts on behalf of multiple (server-local) subscribers. +
++Here's how such proxy subscriptions can work, to reduce the amount of +server-to-server traffic: +
++Step 1: Subscriber sends original subscription +
++JSM users on server1 wish to subscribe to information published by an +entity on server2. Each of them sends a subscription request to the +_local_ pubsub component: +
++Step2: Pubsub component subscribes on subscriber's behalf +
++The pubsub component knows about the publisher, and where (to which +pubsub component) that publisher publishes information. It formulates +a subscription request and sends it to the remote pubsub component: +
++The remote pubsub component receives and acknowledges the subscription +request, and the local pubsub component relays the response back to +the original requester: +
++If the remote pubsub server was unable or unwilling to accept the +subscription request, this should be reflected in the response: +
++Step3: Publisher publishes information +
++The publisher, publisher.server2, publishes information in the +namespace:1 namespace, to the remote pubsub component pubsub.server2: +
++Step4: Pubsub component receives published information +
++The pubsub component pushes the published information to pubsub.server1, +who has been determined to be a valid recipient: +
++Step5: Pubsub component forwards published information to original subscriber +
++The local pubsub component then diffuses the information received to the +original subscriber: +
++This way, only a single published element must travel between servers +to satisfy a multiplex of subscribed entities at the delivery end. +
+ ++Of course, this mechanism will rely upon knowledge about pubsub components +and where they're available; furthermore, it will require knowledge about +where publisher entities publish their information. +This knowledge, and the mechanisms to discover this sort of information, +is not to be covered in this spec, which purely deals with the subscription +and publishing of information. As SOAP is to UDDI (to use a slightly +controversial pair of technologies), so is jabber:iq:pubsub to this +discovery mechanism as yet undefined. To include the definition of such +a discovery mechanism in this specification is wrong on two counts: +
+-
+
- Discovery mechanisms by nature should not be tied to specific areas +
- Trying to load too much onto jabber:iq:pubsub will only produce a +complex and hard-to-implement specification +
+After all, the jabber:iq:pubsub spec as defined here is usable out of the +box for the simple scenarios, and scenarios where discovery is not +necessary or the information can be exchanged in other ways. +
+ ++There are some situations where it might be appropriate for a pubsub +component to refuse particular subscription requests. Here are two +examples: +
+-
+
- Where a pubsub component that's been designed, implemented, or
+configured to handle local-only pubsub traffic, and a subscription request
+is received, specifying a publisher that the local pubsub component knows
+to be one that publishes to a remote pubsub component
under other +circumstances, this would trigger a 'Proxy Subscription', as described earlier, if supported . In this case, the local pubsub component would be +unwilling to provoke a server-to-server connection and therefore unwilling to +honour the request.
+ - Where a pubsub component receives a subscription request from a +remote subscriber, and that pubsub component knows that there's a +pubsub component local to the subscriber. In this case, the (administrator +of the) remote pubsub component might want to encourage proxy subscriptions. + +
+A refusal could take one of a number of guises: +
+
+The jabber:iq:pubsub specification makes no provision for
+publishers to query a pubsub component to ask for a list of those entities
+that are subscribed to (namespaces) it (publishes). This is deliberate.
+Do we wish to add to the specification to allow the publisher to discover
+this information? If so, it must be as an optional 'opt-in' (or 'opt-out')
+tag for the subscriber, to determine whether his JID will show up on the
+list.
+
+Associated with this is the semi-reciprocal issue of acceptance? The +specification deliberately makes no provision for a subscription acceptance +mechanism (where the publisher must first accept a subscriber's request, +via the pubsub component). If we're to prevent the publishers knowing +who is subscribing, ought we to give them the power of veto, to 'balance +things out'? +
++Note that if we do, the acceptance issue is not necessarily one for the +pubsub specification to resolve; there are other ways of introducing +access control, at least in a component environment; use of a mechanism +that the Jabber::Component::Proxy Perl module represents is one example: +wedge a proxy component in front of a real (pubsub) component and have +the ability to use ACLs (access control lists) to control who gets to +connect to the real component. +
+ +Per a vote of the Jabber Council, changed status to Deprecated.
Per a vote of the Jabber Council, advanced status to Active.
Changed format to allow socket-equivalent security.
Initial version.
Note Well: This protocol specified in this document has been superseded by the protocol specified in &jep0124;.
++ This JEP documents a method to allow Jabber clients to access Jabber + servers from behind existing firewalls. Although several similar methods + have been proposed, this approach should work through all known firewall + configurations which allow outbound HTTP access. +
++ In general, a firewall is a box that protects a network from outsiders, + by controlling the IP connections that are allowed to pass through the + box. Often, a firewall will also allow access outside only by proxy, + either explicit proxy support or implicit through Network Address + Translation (NAT). +
++ In the interest of security, many firewall administrators do not allow + outbound connections to unknown and unused ports. Until Jabber becomes + more widely deployed, port 5222/tcp (for Jabber client connections) will + often be blocked. +
+
+ The best solution for sites that are concerned about security is to run
+ their own Jabber server, either inside the firewall, or in a DMZ
+
+ In addition, many firewalls/proxy servers will also not allow or not + honor HTTP Keep-alives (as defined in section 19.7.1.1 of &rfc2068;) + and will consider long-lived socket connections as security issues. + Because of this the traditional Jabber connection model, where one + socket is one stream is one session, will not work reliably. +
++ In light of all of the ways that default firewall rules can interfere + with Jabber connectivity, a lowest-common denominator approach was + selected. HTTP is used to send XML as POST requests and receieve pending + XML within the responses. Additional information is prepended in the + request body to ensure an equivalent level of security to TCP/IP sockets. +
++ The client makes HTTP requests periodically to the server. Whenever the + client has something to send, that XML is included in the body of the + request. When the server has something to send to the client, it must be + contained in the body of the response. +
++ In some browser/platform combinations, sending cookies from the client is + not possible due to design choices and limitations in the + browser. Therefore, a work-around was needed to support clients based on + these application platforms. +
++ All requests to the server are HTTP POST requests, with Content-Type: + application/x-www-form-urlencoded. Responses from the server have + Content-Type: text/xml. Both the request and response bodies are UTF-8 + encoded text, even if an HTTP header to the contrary exists. All + responses contain a Set-Cookie header with an identifier, which is sent + along with future requests as described below. This identifier cookie + must have a name of 'ID'. The first request to a server always uses 0 as + the identifier. The server must always return a 200 response code, + sending any session errors as specially-formatted identifiers. +
+
+ The client sends requests with bodies in the following format:
+
| Identifier | +Purpose | +
|---|---|
| identifier | ++ To uniquely identify the session server-side. This field is only + used to identify the session, and provides no security. + | +
| key | ++ To verify this request is from the originator of the session. The + client generates a new key in the manner described below for each + request, which the server then verifies before processing the + request. + | +
| new_key | ++ The key algorithm can exhaust valid keys in a sequence, which + requires a new key sequence to be used in order to continue the + session. The new key is sent along with the last used key in the + old sequence. + | +
| xml_body | ++ The body of text to send. Since a POST must be sent in order for + the server to respond with recent messages, a client may send + a request without an xml_body in order to just retrieve new + incoming packets. This is not required to be a full XML document or + XML fragment, it does not need to start or end on element boundaries. + | +
+ The identifier is everything before the first semicolon, and must consist + of the characters [A-Za-z0-9:-]. The identifier returned from the first + request is the identifier for the session. Any new identifier that ends + in ':0' indicates an error, with the entire identifier indicating the + specific error condition. Any new identifier that does not end in ':0' is + a server programming error, the client should discontinue the + session. For new sessions, the client identifier is considered to be 0. +
++ Any identifier that ends in ':0' indicates an error. Any previous + identifier associated with this session is no longer valid. +
++ Server returns ID=0:0. The response body can contain a textual error + message. +
+Server returns ID=-1:0
+Server returns ID=-2:0
+Server returns ID=-3:0
++ The key is a client security feature to allow TCP/IP socket equivalent + security. It does not protect against intermediary attacks, but does + prevent a person who is capable of listening to the HTTP traffic from + sending messages and receiving incoming traffic from another machine. +
+The key algorithm should be familiar with those with knowledge of Jabber zero-knowledge authentication.
+Note: Base64 encoding is defined in &rfc3548;. SHA1 is defined in &rfc3174;.
++ No framing is implied by a single request or reply. A single request can + have no content sent, in which case the body contains only the identifier + followed by a comma. A reply may have no content to send, in which case + the body is empty. Zero or more XMPP packets may be sent in a single + request or reply, including partial XMPP packets. +
++ The absense of a long-lived connection requires the server to consider + client traffic as a heartbeat to keep the session alive. If a + server-configurable period of time passes without a successful POST + request sent by the client, the server must end the client session. Any + client requests using the identifier associated with that now dead + session must return an error of '0:0'. +
++ The maximum period of time to keep a client session active without an + incoming POST request is not defined, but five minutes is the recommended + minimum. The maximum period of time recommended for clients between + requests is two minutes; if the client has not sent any XML out for two + minutes, a request without an XML body should be sent. If a client is + disconnecting from the server, a closing <stream:stream> must be + sent to end the session. Failure to do this may have the client continue + to be represented to other users as available. +
++ If the server disconnects the user do to a session timeout, the server + MUST bounce pending IQ requests and either bounce or store offline + incoming messages. +
++ The following is the sequence used for client communication +
-
+
- + The client generates some initial K(0, seed) and runs the algorithm + above 'n' times to determine the initial key sent to the server, + K(n, seed) + +
- + The client sends the request to the server to start the stream, + including an identifier with a value of zero and K(n, seed) + +
- + The server responds with the session identifier in the headers + (within the Set-Cookie field). + +
- + For each further request done by the client, the identifier from the + server and K(n - 1, seed) are sent along. + +
- + The server verifies the incoming value by generating + K(1, incoming_value), and verifying that value against the value sent + along with the last client request. If the values do not match, the + request should be ignored or logged, with an error code being + returned of -3:0. The request must not be processed, and must not + extend the session keepalive. + +
- + The client may send a new key K(m, seed') at any point, but should + do this for n > 0 and must do this for n = 0. If K(0, seed) is + sent without a new key, the client will not be able to continue the + session. + +
-
+
- This method works over HTTPS, which is good from the standpoint of functionality, but bad in the sense that a massive amount of hardware would be needed to support reasonable polling intervals for non-trivial numbers of clients. +
+ Jabber is meant to allow people everywhere in the world to communicate + with each other. However, people converse in many different languages, not just + English. Many humans in fact don't even understand English. Hence, + Jabber should not be tied to a particular language, but rather allow + usage of any language, be it English, Chinese, Inuit, or anything else. +
++ One important step towards this goal is that Jabber is based upon + Unicode, allowing for many different languages. But that alone is not + enough. Jabber promotes a server-based system for many of its + components and services, like the JUD, or transports. Many of these have + to interact with users in some way. Currently, they do so in only one + fixed language (usually English). Even if the server admin is willing + to translate the messages, forms, etc. involved, there can only be one + localization active for a given server/component. +
++ Hence, Jabber must support a way for clients to inform the server about + their preferred language. In addition, the server and other components + have to understand and honor this information. Only this way can we + ensure that Jabber is able to work in a multi-national, multi-lingual + environment. +
++ Some examples on how this information could and should be used, include +
+-
+
- Forms (e.g. for registration or searching, refer also to JEP-0004) can be localized, so that instructions and field labels are in the native language of the person who has to fill them out +
- Even if the form can't be sent in the proper language (e.g. simply because it hasn't yet been translated), the component still should tag its reply with the language being used +
- Incoming messages in a different language could be automatically translated (server-side or client-side) +
- Redirection of messages based on their language (think of a help desk which services world wide requests) +
- Transports to services which are not unicode based could use the language information as a hint at the best encoding (least lossage) for converted messages +
+ The basic idea behind this proposal was to use existing standards where possible, and to make it fully backward compatible. Furthermore it was a goal to allow clients to support it now, even without any server support, while at the same time permitting improved functionality once servers start to implement this spec. +
+ +To encode the locale on any given XML packet, we use the xml:lang attribute, as defined in the XML specification. This in turn uses values as specified in RFC 1766 to encode languages and regions. This way, you can even distinguish between British and Australian English. +
++ An xml:lang tag can be put onto any XML element; for the purposes of this JEP, however, we will limit its usage to the four central Jabber elements: <stream/>, <message/>, <iq/> and <presence/>. +
++ A client claiming to support this JEP has to initiate server connection slightly differently by putting an xml:lang attribute in the initial <stream:stream> element. +
++ Servers not supporting this JEP will just ignore the additional attribute. Compliant server can be distinguished by the fact that their reply <stream:stream> element also contains an xml:lang attribute, indicating the main language of the server. A compliant client has to detect whether the server is compliant or not, and base its future behavior on this information. +
++ If the client thus determines that the server is compliant, then it doesn't have to do anything beyond this point. All its outgoing messages will automatically be flagged by the server with an xml:lang attribute if necessary. Thus writing a minimal compliant client is trivial. +
++ If it is determined that the server does not support this JEP, and the client still wants to offer locale support, it may start flagging all its outgoing message/iq/presence elements with the xml:lang attribute, to ensure that other components/clients which do conform to this JEP can handle the localization despite the local server not doing so. +
++ Finally, if for whatever reasons the client wants to flag particular messages with a different locale (e.g. if the user is bilingual), it can do so at any time by putting an appropriate xml:lang element in the outgoing data. This will override the previously set default locale for this message only. +
++ A compliant server must detect the xml:lang attribute in incoming <stream:stream> elements. The server then has to store this information for later use, i.e. it has to remember the default language for each active session. +
++ Additionally, a compliant server must attach an xml:lang attribute to the reply <stream:stream> element sent in response to a newly initiated connection. This attribute should reflect the default language of that server, and is used to indicate to clients that the server implements this JEP. +
++ The server should not only allow user clients to specify a default language this way, but also server-side components, like the JUD should be allowed to do this. +
++ Whenever a message leave the server, it has to tag the message automatically with the xml:lang attribute of the corresponding seesion, if any was specified, unless the message is already tagged this way. In that case, the already existing xml:lang attribute takes precedence, thus allowing for greater flexibility. +
++ If a client send a message to another local client which uses the same xml:lang value, then no change is applied. But if the recipient uses a different xml:lang, and if the message has no xml:lang attribute attached yet, the xml:lang of the server has to be attached before delievey of the message. +
++ Jabber based services that wish to comply to this JEP have to make sure that all information they send to clients is tagged with an xml:lang attribute corresponding to the language used in the outgoing data, if appropriate, even if the component supports no other localizations. An example for this is a search form based on JEP-0004. +
++ This way, a client could for example offer to translate the form since it now knows the language the form was written in. Previously it could just guess the language was English, which never was guaranteed. +
++ To be able to tailor replies to the user's preferred language, the component has to know this information. This is simply inferred from any xml:lang attribute on incoming requests. If none is present, the default locale is assumed. If the client's default locale diverges from that of the component, it is the server's responsibility to tag the query with an appropriate xml:lang attribute (refer to the "Server support" section). If on the other hand the server is not compliant, then any interested client will manually tag its queries with an xml:lang attribute. Thus it is sufficient to check for this attribute. +
++ A more sophisticated component supporting multiple localizations of its forms/messages could now honor the requested language and send this search form instead of the English one shown previously: +
++ If the component doesn't have the requested localization available, it replies with the default localization (but of course with the matching xml:lang attribute tagged to it, and not the one of the request). +
+ +The Jabber community has long acknowledged the need for privacy and security features in a well-rounded instant messaging system. Unfortunately, finding a consensus solution to the problem of end-to-end encryption during the community's younger days was not easy. Eventually, early contributors created a quick solution using OpenPGP. This JEP documents the OpenPGP solution as it is used today, so that others may interoperate with clients that support it. This JEP is not intended to present a standard, because more complete solutions are being investigated.
+All operations described here are done with standard OpenPGP software such as GnuPG. All program output is US-ASCII armored output with the headers removed. This allows for easy transportation of the program output directly in the XML. All keys are exchanged using OpenPGP key servers, and usually are retrieved when a signed &PRESENCE; stanza is received (key retrieval does not happen in-band).
+Signing enables a sender to verify that they sent a certain block of text. In Jabber, signing uses the 'jabber:x:signed' namespace, and is primarily used with &PRESENCE;, but may also be used with &MESSAGE;. Because signing requires a block of text, it creates new restrictions on the &PRESENCE; and &MESSAGE; stanzas:
+-
+
- A &PRESENCE; stanza MUST have a <status> element containing XML character data. +
- A &MESSAGE; stanza MUST have a <body> element containing XML character data. +
These requirements are necessary so that there is always common text to sign and verify against. When signing presence, the sender SHOULD sign the XML character data of the <status> element. The sender SHOULD sign presence using the private key whose KeyID corresponds to the public key to be used in encrypting messages (see below).
+Encryption enables the sender to encrypt a message to a specific recipient. This is accomplished using the 'jabber:x:encrypted' namespace in conjunction with &MESSAGE; stanzas. Because a block of text is necessary in order to have something to encrypt, &MESSAGE; stanzas intended to be encrypted have the same restrictions as signing (see above). The data encrypted MUST be the XML character data of the <body> element. The sender SHOULD encrypt the message body using the public key whose KeyID corresponds to the private key used in signing presence (see above).
+It is considered polite to include an unencrypted message <body/> explaining that the actual message body is encrypted. This helps if the client experiences an error while decrypting the message, or if the user's a client that does not support encryption (although generally this should not happen, since the signed presence can be used to indicate that a client accepts encrypted messages).
+The method defined herein has the following security issues:
+-
+
- Key exchange relies on the web of trust model used on the OpenPGP keys network. +
- There is no mechanism for checking a fingerprint or ownership of a key other than checking the user IDs on a key. +
- When the recipient is not mentioned in the encrypted body, replay attacks are possible on messages. +
- Replay of the signed &PRESENCE; status is possible. +
- It relies on signing or encryption of XML character data; therefore, it does not support signing or encryption of &IQ; stanzas, and it allows signing of the presence <status/> element and encryption of the message <body/> element only. Thus the method is not acceptable when signing or encryption of full stanzas is required. +
- It does not enable both signing and encryption of a stanza, only signing of the presence status and encryption of the message body. +
In addition to the security considerations listed above, there are several other known issues with this method:
+-
+
- It is limited to PGP keys and does not support X.509 certificates, Kerberos, RSA keys, etc. +
- It does not include feature negotiation; instead, signed &PRESENCE; is used as an indicator of support. Because of the lack of negotiation it is possible for encrypted &MESSAGE; elements to be stored offline and then read by a client that cannot support them. +
- It is verbose (the example encrypted &MESSAGE; is "Hi"). +
This JEP requires no interaction with &IANA;.
+The ®ISTRAR; shall register the 'jabber:x:encrypted' and 'jabber:x:signed' namespaces as a result of this JEP.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0027: http://www.jabber.org/jeps/jep-0027.html
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0027: http://www.jabber.org/jeps/jep-0027.html
+
+
+
+
+ ]]>
+ Jabber Identifiers (JIDs) uniquely identify individual entities in the Jabber network. To date, their syntax has been defined by convention, existing implementations, and available documentation. As it exists, certain characters that are allowed in JIDs cause ambiguity, and the lack of a size limit on resources defies database schemas and causes some trivial JID operations to require dynamic memory allocation. This JEP seeks to both define and improve the existing JID syntax. This JEP will not explain the general usage or nature of JIDs, instead focusing on syntax.
+JIDs consist of three main parts:
+-
+
- The node identifier (optional) +
- The domain identifier (required) +
- The resource identifier (optional) +
JIDs are encoded UTF-8. A grammar will be presented first, followed by specific clarifying and further restricting remarks.
+
+
+<JID> ::= [<node>"@"]<domain>["/"<resource>]
+<node> ::= <conforming-char>[<conforming-char>]*
+<domain> ::= <hname>["."<hname>]*
+<resource> ::= <any-char>[<any-char>]*
+<hname> ::= <let>|<dig>[[<let>|<dig>|"-"]*<let>|<dig>]
+<let> ::= [a-z] | [A-Z]
+<dig> ::= [0-9]
+<conforming-char> ::= #x21 | [#x23-#x25] | [#x28-#x2E] |
+ [#x30-#x39] | #x3B | #x3D | #x3F |
+ [#x41-#x7E] | [#x80-#xD7FF] |
+ [#xE000-#xFFFD] | [#x10000-#x10FFFF]
+<any-char> ::= [#x20-#xD7FF] | [#xE000-#xFFFD] |
+ [#x10000-#x10FFFF]
+
+
A domain identifier is a standard DNS hostname as specified in RFC952
Node identifiers are restricted to 256 bytes, They may contain any Unicode character higher than #x20 with the exception of the following:
+-
+
- #x22 (") +
- #x26 (&) +
- #x27 (') +
- #x2F (/) +
- #x3A (:) +
- #x3C (<) +
- #x3E (>) +
- #x40 (@) +
- #x7F (del) +
- #xFFFE (BOM) +
- #xFFFF (BOM) +
Case is preserved, but comparisons will be made in case-normalized canonical form.
+Resources identifiers are case-sensitive and are limited to 256 bytes. They may include any Unicode character greater than #x20, except #xFFFE and #xFFFF.
+To date, resource identifiers have not had a fixed limit on their length. This JEP seeks to limit it to 256 bytes for the following reasons:
+-
+
- In order to perform JID manipulations safely, one cannot use stack space if there is no limit. This forces temporary calculations onto the heap which is unnecessarily costly. +
- As a fixed length character field, a resource identifier is more easily stored in, searched on, and retrieved from a database. If an end user may store an encyclopedia's worth of information in their resource, then the only way it can be stored without truncating it is to store it as a large object (BLOB or CLOB). Depending on the database used, that makes it either grossly inefficient or impossible to search on. +
- There exist denial of service attacks stemming from an unlimited resource length. +
In a worst-case encoding, such as Han ideographs, 256 bytes will provide enough storage space for 64 character points. This provides a lower bound on the number of characters a node may have in its resource.
+Specifying limits in terms of bytes instead of characters is somewhat arbitrary once a lower bound for characters is established. This JEP proposes limits in terms of bytes mainly because doing so results in parsing efficiency; specifically, an implementation does not have to un-encode the UTF-8 string for the sole purpose of further restricting character sets that require fewer than four bytes per character point. It is sufficient to have a lower bound on characters and an upper bound on bytes.
+The ability to discover information about entities on the Jabber network is extremely valuable. Such information might include features offered or protocols supported by the entity, the entity's type or identity, and additional entities that are associated with the original entity in some way (often thought of as "children" of the "parent" entity). While mechanisms for doing so are not defined in &xmppcore;, several protocols have been used in the past within the Jabber community for service discovery, specifically &jep0011; and &jep0094;. However, those protocols are perceived to be inadequate for several reasons:
+-
+
Neither Jabber Browsing nor Agent Information is easily extensible. For example, the categories and subcategories listed for JID-Types in JEP-0011 are explicitly defined as the only official categories, and any additions to the list of JID-Types would require a modification to JEP-0011. While the Jabber Browsing specification does allow for the use of unofficial categories and types prefixed with the string 'x-', this introduces migration issues. This lack of flexibility violates one of the Jabber community's core &jep0134;.
+ In Agent Information, there is no way to advertise supported features. While Jabber Browsing includes such a mechanism, the only way to express the availability of a feature is to advertise a supported protocol namespace. Yet some features may not be uniquely associated with a protocol namespace, which are one implementation of features but not the only one.
+ A Jabber Browsing result returns a combination of (1) namespaces supported by a Jabber Entity, (2) items associated with a Jabber Entity, and (3) namespaces supported by the associated items. This approach mixes information levels and requires parents to know everything about child nodes, thereby introducing significant confusion.
+ In both Jabber Browsing and Agent Information, items must be addressable as JIDs; however, this may not be possible in some applications.
+
This JEP addresses the perceived weaknesses of both the Jabber Browsing and Agent Information protocols. The result is a standards-track protocol for service discovery (often abbreviated to "disco", as is familiar in protocols such as &w3soap;).
+The authors have designed the service discovery protocol with the following requirements in mind:
+-
+
The protocol MUST support all functionality supported by the protocols it supersedes (Jabber Browsing and Agent Information).
+ -
+
There are three kinds of information that need to be discovered about an entity:
+-
+
- its basic identity (type and/or category) +
- the features it offers and protocols it supports +
- any additional items associated with the entity, whether or not they are addressable as JIDs +
All three MUST be supported, but the first two kinds of information relate to the entity itself whereas the third kind of information relates to items associated with the entity itself; therefore two different query types are needed.
+
+ Discovering information about a child item MUST be accomplished by sending a separate discovery request to that item, not to the parent entity. (One result of this is that discovering complete information about an entire tree will require multiple request/response pairs in order to "walk the tree".)
+ The lists of identities and features MUST be flexible.
+ The protocol itself MUST be extensible.
+
A requesting entity may want to discover information about another entity on the network. The information desired generally is of two kinds:
+-
+
The target entity's identity. In disco, an entity's identity is broken down into its category (server, client, gateway, directory, etc.) and its particular type within that category (IM server, phone vs. handheld client, MSN gateway vs. AIM gateway, user directory vs. chatroom directory, etc.). This information helps requesting entities to determine the group or "bucket" of services into which the entity is most appropriately placed (e.g., perhaps the entity is shown in a GUI with an appropriate icon). An entity MAY have multiple identities. When multiple identity elements are provided, the name attributes for each identity element SHOULD have the same value.
+
+ The features offered and protocols supported by the target entity. This information helps requesting entities determine what actions are possible with regard to this entity (registration, search, join, etc.), what protocols the entity supports, and specific feature types of interest, if any (e.g., for the purpose of feature negotiation).
+
In order to discover such information, the requesting entity MUST send an IQ stanza of type "get", containing an empty <query/> element qualified by the 'http://jabber.org/protocol/disco#info' namespace, to the JID of the target entity (the 'to' address is REQUIRED and MUST contain a valid JID; a 'node' attribute on the &QUERY; element is OPTIONAL as described in the Info Nodes and Items Nodes section of this document):
+The target entity then MUST either return an IQ result, or return an error (see the Error Conditions section of this document). The result MUST contain a <query/> element qualified by the 'http://jabber.org/protocol/disco#info' namespace, which in turn contains one or more <identity/> elements and one or more <feature/> elements. (Note: Every entity MUST have at least one identity, and every entity MUST support at least the 'http://jabber.org/protocol/disco#info' feature; however, an entity is not required to return a result and MAY return an error, most likely &feature; or &unavailable;, although other error conditions may be appropriate.) Each <identity/> element MUST possess 'category' and 'type' attributes specifying the category and type for the entity, and MAY possess a 'name' attribute specifying a natural-language name for the entity. Each <feature/> element MUST possess a 'var' attribute whose value is a protocol namespace or other feature offered by the entity. Preferably, both the category/type values and the feature values will be registered in a public registry, as described in the Jabber Registrar Considerations section of this document.
+If the JID of the specified target entity does not exist, the server or other authoritative entity SHOULD return an ¬found; error, unless doing so would violate the privacy and security considerations specified in XMPP Core and &xmppim; or local privacy and security policies (see also the Security Considerations of this document):
+If privacy and security considerations or policies prevent the server or other authoritative entity from returning an ¬found; error, it SHOULD return a &unavailable; error instead:
+When an entity sends a disco#info request to a bare JID (<account@domain.tld>) hosted by a server, the server itself MUST reply on behalf of the hosted account, either with an IQ-error or an IQ-result. For important rules regarding access to this functionality, see the Security Considerations section of this document. In particular, in response to a disco#info request sent to a bare JID with no node, if access is not denied the server SHOULD return an IQ-result for the bare JID, in which the primary identity SHOULD have a category of "account" with an appropriate type as specified in the Service Discovery Identities registry (most likely, a type of "registered"). Note: This enables authorized or trusted entities to discover whether the account exists and its account type (e.g., in IM systems to determine the existence of an account before adding it to a contact's roster).
+Here we assume that shakespeare.lit is trusted by capulet.com and that the account <juliet@capulet.com> is a registered account:
+A query sent to an associated entity may result in different or more detailed information. One example is sending a query to a particular conference room rather than the parent conference service:
+Another example of this is sending a query to a specific connected resource for an IM user:
+A disco#info query MAY also be directed to a specific node identifier associated with a JID, although the primary use of nodes is as Items Nodes rather than as info nodes:
+In order for the requesting entity to discover the items associated with a Jabber Entity, it MUST send an IQ stanza of type "get" to the target entity, containing an empty <query/> element qualified by the 'http://jabber.org/protocol/disco#items' namespace:
+The target entity then MUST either return its list of publicly-available items, or return an error. The list of items MUST be provided in an IQ stanza of type "result", with each item specified by means of an <item/> child of a <query/> element qualified by the 'http://jabber.org/protocol/disco#items' namespace (the <item/> child MUST possess a 'jid' attribute specifying the JID of the item and MAY possess a 'name' attribute specifying a natural-language name for the item):
+The <item/> element MUST NOT contain XML character data and SHOULD be empty; while it MAY contain XML data in another namespace, such data MUST be ignored if an implementation does not understand it.
+If there are no items associated with an entity (or if those items are not publicly available), the target entity MUST return an empty query element to the requesting entity:
+As with disco#info requests, when an entity sends a disco#items request to a bare JID (<account@domain.tld>) hosted by a server, the server itself MUST reply on behalf of the hosted account. For important rules regarding access to this functionality, see the Security Considerations section of this document. In particular, in response to a disco#items request sent to a bare JID with no node, if access is not denied the server SHOULD return the associated items including connected or available resources as appropriate:
+Here we assume that shakespeare.lit is trusted by capulet.com and that the account <juliet@capulet.com> has two available resources:
+It is possible that an item associated with an entity will not be addressable as a JID; examples might include offline messages stored in an inbox (see &jep0013;), entries in a Jabber-enabled weblog, XML-RPC services associated with a client or component, items available in an online trading system (e.g., a catalog or auction), news postings located at an NNTP gateway, and topics hosted by a &jep0060; component. In order to handle such items, the <item/> element MAY possess an OPTIONAL 'node' attribute that supplements the REQUIRED 'jid' attribute.
+The value of the node attribute may or may not have semantic meaning; from the perspective of Service Discovery, a node is merely something that is associated with an entity. In order to discover more about the node, the requesting entity MUST query the entity's JID while specifying the node. If the value of the 'node' attribute has semantic meaning, that meaning is provided by the using protocol or application, not by the Service Discovery protocol. A node attribute SHOULD NOT be included unless it is necessary to provide or discover information about an entity that cannot be directly addressed as a JID (i.e., if the associated item can be addressed as a JID, do not include a node). The value of the 'node' attribute MUST NOT be null.
+In the following example, a user requests all available items from an online catalog service:
+If there are items associated with the target entity but they are not addressable as JIDs, the service SHOULD then return a list of nodes (where each <item/> element MUST possess a 'jid' attribute, SHOULD possess a 'node' attribute, and MAY possess a 'name' attribute):
+There may be futher nodes associated with the "first-level" nodes returned in the above query (e.g., the nodes may be categories that have associated items). The requesting entity can query a node further by sending a request to the JID and specifying the node of interest in the query.
+The service then returns the further nodes associated with the "parent" node. In the following example, the service itself enforces an alphabetically-ordered hierarchical structure on the nodes that are returned, but such a structure is a matter of implementation rather than protocol.
+The requesting entity can then query further if desired:
+The foregoing examples show a hierarchy of nodes, in which some nodes are branches (i.e., contain further nodes) and some nodes are leaves (i.e., do not contain further nodes). The "hierarchy" category SHOULD be used to identify such nodes, where the "branch" and "leaf" types are exhaustive of the types within this category.
+If the hierarchy category is used, every node in the hierarchy MUST be identified as either a branch or a leaf; however, since a node MAY have multiple identities, any given node MAY also possess an identity other than "hierarchy/branch" or "hierarchy/leaf".
+Therefore, a disco#info request to the "music/D" node shown above would yield <identity category='hierarchy' type='branch'/> while a disco#info request to the "music/D/dowland-firstbooke" node would yield <identity category='hierarchy' type='leaf'/> (and each node could yield additional identities as appropriate).
+This section explains in greater detail the relationship between an entity and its associated items.
+In general, the items returned by an entity in a disco#items result MUST be items over which the entity has some relationship of ownership -- either direct control over the item itself (e.g., Publish-Subscribe nodes owned by the entity) or at least the ability to provide or vouch for the item in a canonical way on the Jabber network (e.g., groupchat rooms directly hosted by a multi-user chat service or IRC channels to which a gateway provides access).
+Such a relationship does not constrain the relationship between the owning entity's address and the address of the associated entity. In particular, any of the following scenarios is perfectly acceptable:
+-
+
Upon querying an entity (JID1) for items, one receives a list of items that can be addressed as JIDs; each associated item has its own JID, but no such JID equals JID1.
+ Upon querying an entity (JID1) for items, one receives a list of items that cannot be addressed as JIDs; each associated item has its own JID+node, where each JID equals JID1 and each NodeID is unique.
+ Upon querying an entity (JID1+NodeID1) for items, one receives a list of items that can be addressed as JIDs; each associated item has its own JID, but no such JID equals JID1.
+ Upon querying an entity (JID1+NodeID1) for items, one receives a list of items that cannot be addressed as JIDs; each associated item has its own JID+node, but no such JID+node equals JID1+NodeID1 and each NodeID is unique in the context of the associated JID.
+
In addition, the results MAY also be mixed, so that a query to a JID or a JID+node could yield both (1) items that are addressed as JIDs and (2) items that are addressed as JID+node combinations.
+Consider the case of an entity that owns multiple publish-subscribe nodes -- for example, a person who owns one such node for each of his music players. The following examples show what the disco#items query and result might look like (using the protocol defined in &jep0118;):
+The queried entity now returns a list of publish-subscribe nodes over which it has control, each of which is hosted on a different pubsub service:
+The server handling rules defined in XMPP IM require that the server itself reply on behalf of the user if the 'to' attribute of an IQ get or set is of the form <user@host>. This functionality is currently employed so that the user can "publish" information (e.g., vCard information as specified in &jep0054;) in a way that makes it possible for other entities to retrieve that information even if the user is unavailable. The service discovery specification defined herein builds on that notion by enabling a user to publish some of its service discovery information to the server, which shall store that information in persistent storage and return that information when other entities request it from the user's "bare JID" (user@host), either alone or in combination with a particular node.
+Implementations of service discovery that are built into instant messaging servers SHOULD allow users to publish items in this fashion, although they are not required to do so in order to conform to the service discovery specification. In order to discover whether his or her server supports this publish functionality, the user SHOULD send a disco#info request to his or her server:
+If the server supports service discovery publishing and the server wishes to disclose that fact to the user, it MUST include a feature of 'http://jabber.org/protocol/disco#publish' in its response.
+In order to publish items, an entity uses an IQ-set transaction to its server, which is responsible for responding to requests on behalf of that entity. Each <item/> child element of the parent query MUST possess the following attributes:
+-
+
- action -- specifies the action to be taken for the item +
- jid -- specifies the Jabber ID of the item "owner" or location +
The <item/> element MAY also possess the following attributes:
+-
+
- name -- specifies a natural-language name for the item. +
- node -- specifies the particular node associated with the JID of the item "owner" or location +
The allowable values for the 'action' attribute are "update" and "remove"). If the action is "update", the server MUST either create a new entry (if the node and jid combination does not already exist) or overwrite an existing entry. If the action is "remove", the item MUST be removed from persistent storage.
+The following example shows a user publishing a list of his biological children to a well-known (but fictitious) service discovery node.
+Subsequent queries to "jid='kinglear@shakespeare.lit'" and "node='jabber:iq:kids'" will yield the list shown above (absent the 'action' attributes).
+ +If the server or service does not support persistent storage, it MUST respond to IQ-set requests with a &feature; error.
+ +In order to retrieve full information about an entity and its associated items, the requesting application needs to "walk the tree" of items. Naturally, this can result in a large number of requests and responses. The requesting application SHOULD NOT send follow-up requests to all items associated with an entity if the list of such items is long (e.g., more than twenty items). Entities that will routinely host a large number of items (e.g., IRC gateways or NNTP services) SHOULD structure nodes into hierarchies and/or provide more robust searching capabilities, for example via &jep0055;; they SHOULD NOT return extremely large result sets via Service Discovery.
+This JEP does not require that a responding entity must return the same results in response to the same request from different requesting entities (e.g., an entity could return a different list of items or features based on the degree to which it trusts the requesting entity, or based on the known capabilities of the requesting entity). However, the responding entity SHOULD return the same <identity/> element (category+type) to all disco#info requests sent to the same JID+node combination.
+If a specific entity (JID or JID+node) does not support the disco namespace, refuses to return disco results to the specific requesting entity, or refuses to return disco results to any requesting entity, it SHOULD return an appropriate error message (such as &unavailable;, &forbidden;, or ¬allowed;, respectively). One example is shown below.
+Other error conditions may be appropriate depending on the application.
+The following table summarizes the common error conditions that can have special meaning in the context of Service Discovery (for information regarding error condition syntax and semantics, see &jep0086;).
+| Condition | +Cause | +
|---|---|
| &feature; | +The sender has attempted to publish items but the server does not support the Publishing Available Items feature. | +
| ¬found; | +The JID or JID+NodeID of the specified target entity does not exist and that fact can be divulged in accordance with privacy and security considerations and policies. | +
| &unavailable; | +The target entity does not support this protocol, or the specified target entity does not exist but that fact cannot be divulged because of pricacy and security considerations. | +
The other error conditions specified in XMPP Core MAY be returned as well (&forbidden;, ¬allowed;, ¬authorized;, etc.), including application-specific conditions.
+As noted above, if an entity has no associated items, it MUST return an empty &QUERY; element (rather than an error) in response to a disco#items request.
+Certain attacks may be made easier when an entity discloses (via disco#info responses) that it supports particular protocols or features; however, in general, service discovery introduces no new vulnerabilities, since a malicious entity could discover that the responding entity supports such protocols and features by sending requests specific to those protocols rather than by sending service discovery requests.
+A responding entity is under no obligation to return the identical service discovery response when replying to service discovery requests received from different requesting entities, and MAY perform authorization checks before responding in order to determine how (or whether) to respond.
+A server MUST carefully control access to any functionality that would enable directory harvesting attacks or that would leak information about connected or available resources; this functionality consists of the server's replies to disco#info and disco#items requests sent to bare JIDs (addresses of the form account@domain.tld) hosted on the server, since the server responds to such requests on behalf of the account. The following rules apply to the handling of service discovery requests sent to bare JIDs:
+-
+
-
+
In response to a disco#info request, the server MUST return a &unavailable; error if one of the following is true:
+-
+
- The target entity does not exist (no matter if the request specifies a node or not). +
- The requesting entity is not authorized to receive presence from the target entity (i.e., via a presence subscription of type "both" or "from") or is not otherwise trusted (e.g., another server in a trusted network). +
+ -
+
In response to a disco#items request, the server MUST return an empty result set if:
+-
+
- The target entity does not exist (no matter if the request specifies a node or not). +
- The request did not specify a node, the only items are available resources (as defined in RFC 3921), and the requesting entity is not authorized to receive presence from the target entity (i.e., via a presence subscription of type "both" or "from") or is not otherwise trusted (e.g., another server in a trusted network).
However, the server MAY return items other than available resources (if any).
+
+
This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes the 'http://jabber.org/protocol/disco#info' and 'http://jabber.org/protocol/disco#items' namespaces in its registry of protocol namespaces.
+The Jabber Registrar shall maintain a registry of values for the 'category' and 'type' attributes of the <identity/> element in the 'http://jabber.org/protocol/disco#info' namespace; see <http://www.jabber.org/registrar/disco-categories.html>.
+
+ the name of the category (all lower-case)
+ a natural-language description of the category
+
+ the name of the specific type (all lower-case)
+ a natural-language description of the type
+ the document (e.g., JEP) in which this type is specified
+
+
+ ]]>
+ The registrant may register more than one category at a time, each contained in a separate <category/> element. The registrant may also register more than one type at a time, each contained in a separate <type/> child element. Registrations of new types within an existing category must include the full XML snippet but should not include the category description (only the name).
+This JEP defines a "hierarchy" category that contains two and only two types: "branch" and "leaf"; the associated registry submission is as follows:
+
+ hierarchy
+
+ An entity that exists in the context of a
+ service discovery node hierarchy.
+
+
+ branch
+
+ A "container node" for other entities in a
+ service discovery node hierarchy.
+
+ JEP-0030
+
+
+ leaf
+
+ A "terminal node" in a service discovery
+ node hierarchy.
+
+ JEP-0030
+
+
+ ]]>
+ The Jabber Registrar shall maintain a registry of features for use as values of the 'var' attribute of the <feature/> element in the 'http://jabber.org/protocol/disco#info' namespace; see <http://www.jabber.org/registrar/disco-vars.html>.
+
+ a natural-language description of the feature
+ the document (e.g., JEP) in which this feature is specified
+]]>
+ The registrant may register more than one feature at a time, each contained in a separate <feature/> element.
+This JEP defines a "publish" feature that is not associated with either of the protocol namespaces listed above; the registry submission for this feature is as follows:
+
+ the service discovery "publish" feature
+ JEP-0030
+
+ ]]>
+ A using protocol may specify one or more service discovery nodes that have a special and well-defined meaning in the context of that protocol. For the purpose of reserving these node names globally across all Jabber protocols, the Jabber Registrar shall maintain a registry of well-known service discovery nodes; see <http://www.jabber.org/registrar/disco-nodes.html>.
+
+ the name of the node
+ a natural-language description of the node
+ the document (e.g., JEP) in which this node is specified
+
+ ]]>
+ The registrant may register more than one node at a time, each contained in a separate <node/> element.
+As authorized by &jep0147;, the Jabber Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).
+The "disco" querytype is defined herein for service discovery interactions, with three keys: (1) "node" (the optional node to query), (2) "request" (with values of "info" to retrieve service discovery information and "items" to retrieve service discovery items), and (3) "type" (with values of "get" for IQ-gets and "set" for IQ-sets).
+The following submission registers the "disco" querytype.
+
+ disco
+ http://jabber.org/protocol/disco
+ enables interaction for the purpose of service discovery
+ JEP-0030
+
+
+ node
+ the (optional) service discovery node
+
+
+ request
+ the service discovery request type
+
+
+ info
+ a service discovery information (disco#info) request
+
+
+ items
+ a service discovery items (disco#items) request
+
+
+
+
+ type
+ the IQ type
+
+
+ get
+ an IQ get
+
+
+ set
+ an IQ set (disco publish)
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0030: http://www.jabber.org/jeps/jep-0030.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0030: http://www.jabber.org/jeps/jep-0030.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+ Peter Millard, a co-author of this specification from version 0.1 through version 2.2, died on April 26, 2006.
++Instant messaging has clearly crossed the chasm from experimental +to mainstream in a short amount of time. It is particularly +interesting to note the extent to which the employees and +affiliates of large enterprises have adopted instant messaging as +part of their daily professional lives. IM is no longer simply +used on Friday evening to select which movie to watch; it's now +used on Monday morning to select which company to acquire. +
+ ++While the benefits of IM are clear and compelling, the risks +associated with sharing sensitive information in an IM +environment are often overlooked. We need a mechanism that +permits communities of users to protect their IM conversations. +This document presents an extension protocol that can be +incorporated into the existing Jabber protocol to provide such a +mechanism. We hope that this protocol spurs both interest +and further investigation into mechanisms to protect Jabber +conversations. We also hope that the Jabber community can +accelerate the adoption of standardized security mechanisms. +
+ ++In addition to its ability to protect traditional messaging data, +the proposed protocol may also serve as a foundation for securing +other data transported via other Jabber extensions. +
+ ++We use the following terms throughout this document to describe +the most relevant aspects of the IM environment that we wish to +address: +
+ +-
+
-
+
+user. A user is simply any Jabber user. Users are uniquely +identified by a JID; they connect to Jabber hosts using a +Jabber node. +
++Users produce and consume information, and we wish to +provide them with mechanisms that can be used to protect +this information. +
+
+ -
+
+community. A community is a collection of users who wish to +communicate via Jabber. No restrictions or assumptions are +made about the size of communities or the geographical, +organizational, or national attributes of the members. +Communities are assumed to be dynamic and ad-hoc. Users +typically join communities by the simple act of invitation. +All members of a community are assumed to be peers. +
++The members of communities share information among +themselves, and we wish to provide them with mechanisms +that can permit information to only be shared by community +members. +
+
+ -
+
+conversation. A conversation is the set of messages +that flows among the members of a community via some +network. Conversations consist of both the actual +conversation data produced and consumed by the various +users as well as the Jabber protocol elements that +transport it. Members participate in a conversation when +they are the source or destination of this traffic. +
++In hostile network environments, like the Internet, +conversation data is vulnerable to a variety of well-known +attacks. +
+
+
+Other Jabber and IM terms are used in a traditional, intuitive +fashion. +
+ ++The proposed protocol is designed to address the specific +requirements and considerations presented in this section. +
+ ++A secure IM system must permit conversation participants to +preserve the following properties of their conversation data: +
+ +-
+
-
+
+confidentiality. Conversation data must only be disclosed +to authorized recipients +
+
+ -
+
+integrity. Conversation data must not be altered +
+
+ -
+
+data origin authentication. Recipients must be able to +determine the identity of the sender and trust that the +message did, in fact, come from the sender. It is important +to note that this requirement does not include the +requirement of a durable digital signature on conversation +data. +
+
+ -
+
+replay protection. Recipients must be able to detect and +ignore duplicate conversation data. +
+
+
+These are established, traditional goals of information security +applied to the conversation data. In the IM environment, these +goals protect against these attacks: +
+ +-
+
-
+
+eavesdropping, snooping, etc. +
+
+ -
+
+masquerading as a conversation participant +
+
+ -
+
+forging messages +
+
+
+Preserving the availability of conversation data is not addressed +by this protocol. +
+ ++Preserving the anonymity of conversation participants is an +interesting topic which we defer for future exploration. +
+ ++Finally, note that this protocol does not concern any authentication +between a Jabber node and a Jabber host. +
+ ++A secure IM system must support a data classification feature through the use +of security labeling. Conversation participants must be +able to associate a security label with each piece of +conversation data. This label may be used to specify a data +classification level for the conversation data. +
+ ++It is easy to imagine Jabber systems in which the servers play +active, fundamental roles in the protection of conversation +data. Such systems could offer many advantages, like: +
+ +-
+
-
+
+allowing the servers to function as credential issuing +authorities, +
+
+ -
+
+allowing the servers to function as policy enforcement +points. +
+
+
+Unfortunately, such systems have significant disadvantages when +one considers the nature of instant messaging: +
+ +-
+
-
+
+Many servers may be untrusted, public servers. +
+
+ -
+
+In many conversation communities, decisions of trust and +membership can only be adequately defined by the members +themselves. +
+
+ -
+
+In many conversation communities, membership in the +community changes in real time based upon the dynamics of +the conversation. +
+
+ -
+
+In many conversation communities, the data classifaction of +the conversation changes in real time based upon the +dynamics of the conversation. +
+
+
+Furthermore, the widespread use of gateways to external IM +systems is a further complication. +
+ ++Based on this analysis, we propose that security be entirely +controlled in an end to end fashion by the conversation +participants themselves via their user agent software. +
+ ++We believe that, ultimately, trust decisions are in the hands of +the conversation participants. A security protocol and +appropriate conforming user agents must provide a mechanism for them to make +informed decisions. +
+ ++One of the accepted axioms of security is that people must avoid +the temptation to start from scratch and produce new, untested +algorithms and protocols. History has demonstrated that such +approaches are likely to contain flaws and that considerable time +and effort are required to identify and address all of these +flaws. Any new security protocol should be based on existing, +established algorithms and protocols. +
+ ++Any new IM security protocol must integrate smoothly into the +existing IM environment, and it must also recognize the nature of +the transactions performed by conversation participants. These +considerations are especially important: +
+ +-
+
-
+
+dynamic communities. The members of a community are defined +in near real time by the existing members. +
+
+ -
+
+dynamic conversations. Conversations may involve any +possible subset of the entire set of community members. +
+
+
+Addressing these considerations becomes especially crucial when +selecting a conference keying mechanism. +
+ ++Given the requirement to place the responsibility for the +protection of conversation data in the hands of the participants, +it is imperative to address some fundamental usability issues: +
+ +-
+
-
+
+First, overall ease of use is a requirement. For protocol +purposes, one implication is that some form of +authentication via passphrases is necessary. While we +recognize that this can have appalling consequences, +especially when we realize that a passphrase may be shared +by all of the community members, we also recognize the +utility. +
+
+ -
+
+PKIs are well established in many large organizations, and +some communities will prefer to rely on credentials issued +from these authorities. To ensure ease of use, we must +strive to allow the use of existing PKI credentials and +trust models rather than impose closed, Jabber-specific +credentials. +
+
+ -
+
+Finally, performance must not be negatively impacted; this +is particularly true if we accept that most communities are +composed of human users conversing in real time. For +protocol purposes, one obvious implication is the desire to +minimize computationally expensive public key operations. +
+
+
+We note that, in practice, the design and construction of user +agents will also have a major impact on ease of use. +
+ ++To successfully integrate into the existing Jabber environment, +an extension protocol for security must satisfy the following: +
+ +-
+
-
+
+It must be an optional extension of the existing Jabber protocol. +
+
+ -
+
+It must be transparent to existing Jabber servers. +
+
+ -
+
+It must function gracefully in cases where some community +members are not running a user agent that supports the +protocol. +
+
+ -
+
+It must make good use of XML. +
+
+ -
+
+It must avoid encumbered algorithms. +
+
+ -
+
+It must be straightforward to implement using widely +available cryptographic toolkits. +
+
+ -
+
+It must not require a PKI. +
+
+
+Failure to accommodate these will impede or prohibit adoption of +any security protocol. +
+ ++Ultimately, conversation data is protected by the application of +keyed cryptographic operations. One operation is used to provide +confidentiality, and a separate operation is used to provide +integrity and data origin authentication. The keys used to +parameterize these operations are called conversation keys. Each +conversation should have its own unique set of conversation keys +shared among the conversation participants. +
+ ++Conversation keys are transported among the conversation +participants within a negotiated security session. A security session allows +pairs of conversation participants to securely share conversation keys +throught all participants in the conversation as required. +
+ ++The following terms are used throughout this specification: +
+ +-
+
-
+
+initiator. The initiator is the user who requested a security session +negotiation. Initiator's are identified by their JID. +
+
+ -
+
+responder. The responder is the user who responded to a security session +negotiation request. Responder's are identified by their JID. +
+
+ -
+
+hmac. This indicates the HMAC algorithm. The notation hmac (key, value) +indicates the HMAC computation of value using key. +
+
+ -
+
+concatentation operator. The '|' character is used in character or octet +string expressions to indicate concatenation. +
+
+ -
+
+security session ID. A character string that uniquely identifies a +security session between two users. Security session IDs MUST only +consist of Letters, Digits, and these characters: '.', '+', '-', +'_', '@'. Security session IDs are case sensitive. +
+
+ -
+
+SS. This term indicates the security session secret that is agreed to +during a security session negotiation. +
+
+ -
+
+SKc. This term indicates the keying material used within a security session +to protect confidentiality. The SKc is derived from the security session secret, SS. +
+
+ -
+
+SKi. This term indicates the keying material used within a security session +to protect integrity and to provide authnetication. The SKi is derived from the +security session secret, SS. +
+
+ -
+
+conversation key ID. A character string that uniquely identifies a +conversation key shared by a community of users. Conversation key IDs MUST only +consist of Letters, Digits, and these characters: '.', '+', '-', +'_', '@'. Conversation key IDs are case sensitive. Conversation key IDs SHOULD +be generated from at least 128 random bits. +
+
+ -
+
+passphrase ID. A character string that uniquely identifies a +passphrase shared by a community of users. Passphrase IDs MUST only +consist of Letters, Digits, and these characters: '.', '+', '-', +'_', '@'. Passphrase IDs are case sensitive. +
+
+
+Since cryptographic operations are applied to data that is +transported within an XML stream, the protocol defines a set of +rules to ensure a consistent interpretation by all conversation +participants. +
+ ++Binary data, such as the result of an HMAC, is always transported +in an encoded form; the two supported encoding schemes are base64 +and hex. +
+ ++Senders MAY include arbitrary white space within the character +stream. Senders SHOULD NOT include any other characters outside +of the encoding set. +
+ ++Receivers MUST ignore all characters not in the encoding set. +
+ ++Encrypted data, including wrapped cryptographic keys, are always +wrapped per XML Encryption. +
+ + ++HMACs are computed over a specific collection of attribute values +and character data; when computing an HMAC the following rules +apply: +
+ +-
+
-
+
+All characters MUST be encoded in UTF-8. +
+
+ -
+
+The octets in each character MUST be processed in network +byte order. +
+
+ -
+
+For a given element, the attribute values that are HMACed +MUST be processed in the specified order regardless of the +order in which they appear in the element tag. +
+
+ -
+
+For each attribute value, the computation MUST only include +characters from the anticipated set defined in this +specification; in particular, white space MUST always be +ignored. +
+
+ -
+
+For character data that is represented in an encoded form, +such as base64 or hex, the computation MUST only include +valid characters from the encoding set. +
+
+
+The following algorithm is used to encrypt a character string, such as +an XML element: +
+ +-
+
-
+
+The character string MUST be encoded in UTF-8. +
+
+ -
+
+The octets in each character MUST be processed in network byte order. +
+
+ -
+
+Appropriate cryptographic algorithm parameters, such as an +IV for a block cipher, are generated. +
+
+
+In order to integrate smoothly with the existing Jabber protocol, +this protocol utilizes a new XML namespace, jabber:security. +
+ ++A security session is a pair-wise relationship between two users +in which the users have achieved the following: +
+ +-
+
-
+
+They have mutually authenticated each other using credentials acceptable to both. +
+
+ -
+
+They have agreed on a set of key material known only to both. +
+
+
+Security sessions are identified by a 3-tuple consisting of the following items: +
+ +-
+
-
+
+initiator. This is the JID of the user who initiated the session. +
+
+ -
+
+responder. This is the JID of the user who responded to the initiator's request. +
+
+ -
+
+sessionId. A label generated by the initiator. +
+
+
+Security sessions are used to transport conversation keys between the conversation participants. +
+ ++Scalabilty is an immediate, obvious concern with such an approach. We expect this +approach to be viable in practice because: +
+ +-
+
-
+
+The number of participants in typical, interactive conversations is generally on the order of 10^1. +
+
+ -
+
+New participants are usually invited to dynamically join a +conversation by being invited by an existing participant; +this existing participant is the only one who needs to +establish a security session with the new participant, +because this single security session can be used to +transport all of the required conversation keys. +
+
+ -
+
+User agents can permit the lifetime of security sessions to +last long enough to allow transport of conversation keys +for a variety of converstions. +
+
+ -
+
+Conversation keys can be established with a suitable lifetime. +
+
+
+Other approaches, including the incorporation of more +sophisticated conference keying algorithms, are a topic for +future exploration. +
+ ++Security sessions are negotiated using an authenticated Diffie-Hellman key agreement +exchange. The two goals of the exchange are to perform the mutual authentication +and to agree to a secret that is know only to each. +
+ ++The exchange also allows the parties to negotiate the various algorithms +and authentication mechanisms that will be used. +
+ ++Once the pair agree on a shared secret, they each derive key material from the +secret; this key material is used to securely transport the conversation keys, +which are used to actually protect conversation data. +
+ ++The protocol data units (PDUs) that comprise the exchange are transported +within existing Jabber protocol elements. +
+ ++The initiator's user agent employs the following algorithm to generate the session1 PDU: +
+ +-
+
-
+
+Appropriate values for the version, initiator, responder, +sessionId, and hmac attributes are assembled. The version of +this specification is '1.0'. The values of initiator and +responder MUST be the JIDs of the two participants, +respectively. +
+
+ -
+
+The nonce is prepared by first generating a string of 20 +random octets (160 random bits). The octets are then +encoded into a string of 40 hex characters representing the +random string. +
+
+ -
+
+A Diffie-Hellman group is selected. The appropriate values +for g and p will be used to generate the initiator's public +key. +
+
+ -
+
+An ephemeral private key, x, is generated using g and p +for the selected group. This key MUST be generated using an +appropriate random number source. The corresponding public +key, g^x, is generated and encoded. +
+
+ -
+
+The desired set of confidentiality and HMAC cryptographic +algorithms is selected. The manner in which these +algorithms are selected and all related policy issues are +outside the scope of this specification. +
+
+ -
+
+The desired set of authentication algorithms is selected. +The manner in which these algorithms are selected and all +related policy issues are outside the scope of this +specification. When the digital signature form of +authentication is selected, the relevant end-entity +certificate and, optionally, a chain of CA certificates +representing a validation path, is assembled and encoded. A +set of trusted CA certificates MAY optionally be included +via caCertificate elements; if so, the set MUST include the +issuer of the initiator's end-entity certificate. +
+
+
+These values are then used to prepare the XML session1 element; +this element is transmitted via the existing Jabber iq mechanism: +
+ ++The responder's user agent employs the following algorithm to process each session1 PDU: +
+ +-
+
-
+
+The version and hmac attributes are checked against the +values supported by the user agent. An unsupported version +results in an error code of 10000, and an unsupported hmac +results in an error code of 10001. The responder attribute MUST +match the JID of the receiver; a mismatch results in an error code of 10009 +
+
+ -
+
+The nonce is decoded, and its length is checked. The nonce +may also be checked to detect replays. An invalid nonce +results in an error code of 10002. +
+
+ -
+
+The Diffie-Hellman group is checked against the values +supported by the user agent. An unsupported group results +in an error code of 10003 +
+
+ -
+
+The desired confidentiality and HMAC cryptographic +algorithms are selected from the proposed set. The manner +in which these algorithms are selected and all related +policy issues are outside the scope of this specification. +If none of the proposed algorithms are supported, an error +code of 10004 occurs. +
+
+ -
+
+The desired authentication algorithm is selected from the +proposed set. The manner in which this algorithm is +selected and all related policy issues are outside the +scope of this specification. In the digital signature case, +the responder's end-entity +certificate MUST be issued by one of the trusted CAs listed +in the session1 PDU or by the same issuer as the +initiator's end-entity certificate. If none of the proposed +algorithms are supported, an error code of 10005 results. +If the responder does not have acceptable credentials, an +error code of 10006 occurs. +
+
+
+If any errors occur during processing, the session negotiation +fails, and the error is communicated via the existing Jabber iq +mechanism: +
+ ++If no errors occur, then the responder's user agent proceeds with +the session2 PDU. +
+ ++The responder's user agent employs the following algorithm to generate the session2 PDU: +
+ +-
+
-
+
+Appropriate values for the version, initiator, responder, +sessionId, and hmac attributes are assembled. The version of +this specification is '1.0'. The values of initiator and +responder MUST be the JIDs of the two participants, +respectively. The sessionId and hmac values MUST match the +sessionId and hmac values contained in the session1 PDU. +
+
+ -
+
+The nonce is prepared by first generating a string of 20 +random octets (160 random bits). The octets are then +encoded into a string of 40 hex characters representing the +random string. +
+
+ -
+
+An ephemeral private key, y, is generated using g and p +for the group indicated by the session1 PDU. This key MUST +be generated using an appropriate random number source. The +corresponding public key, g^y, is generated and encoded. +
+
+ -
+
+The desired pair of confidentiality and HMAC cryptographic +algorithms is selected. The manner in which this pair is +selected and all related policy issues are outside the +scope of this specification. +
+
+ -
+
+The desired authentication algorithm is selected. The +manner in which this algorithm is selected and all related +policy issues are outside the scope of this specification. +When the digital signature form of authentication is +selected, the relevant end-entity certificate and, +optionally, a chain of CA certificates representing a +validation path, is assembled and encoded. +
+
+ -
+
+Based on the selected authentication algorithm, the +responder's authenticator is constructed. A digital signature algorithm +requires calculating: +
+-
+
-
+
+HK = hmac (initiator's nonce | responder's nonce, g^xy) +
+
+ -
+
+HASH_R = hmac (HK, version | sessionId | g^y | g^x | responder's JID) +
+
+
+HASH_R is signed using the responder's private key and encoded in PKCS#1 format. +The PKCS#1 octets are then further encoded in base64 or hex. +
++The passphrase algorithm requires calculating: +
+-
+
-
+
+HK = hmac (hash (passphrase), initiator's nonce | responder's nonce) +
+
+ -
+
+HASH_R = hmac (HK, version | sessionId | g^y | g^x | responder's JID) +
+
+
+The octets of HASH_R are simply encoded in base64 or hex. +
++The manner in which the responder's user agent gains access +to the responder's credentials is outside the scope of this +specification. +
+
+ -
+
+These values are then used to prepare the XML session2 element; +this element is transmitted via the existing Jabber iq mechanism: +
+ ++The initiator's user agent employs the following algorithm to process each session2 PDU: +
+ +-
+
-
+
+The attribute values are checked against the values sent in +the session1 PDU. A mismatch results in an error code of +10008. +
+
+ -
+
+The nonce is decoded, and its length is checked. The nonce +may also be checked to detect replays. An invalid nonce +results in an error code of 10002. +
+
+ -
+
+The Diffie-Hellman group is checked against the value sent +in the session1 PDU. A mismatch results in an error code of 10003 +
+
+ -
+
+The confidentiality and HMAC cryptographic algorithms are +validated against the set proposed in the session1 PDU. A +mismatch results in an error code of 10004. +
+
+ -
+
+The authentication algorithm is validated against the set +proposed in the session1 PDU. A mismatch results in an +error code of 10005. +
+
+ -
+
+The authenticator is verified. A failure results in an error code of 10007. +
+
+
+If any errors occur during processing, the session negotiation +fails, and the error is communicated via the existing Jabber iq +mechanism: +
+ ++If no errors occur, then the initiator's user agent proceeds with the session3 PDU. +
+ ++The initiator's user agent employs the following algorithm to generate the session3 PDU: +
+ +-
+
-
+
+Appropriate values for the version, initiator, responder, +sessionId, and hmac attributes are assembled. The version of +this specification is '1.0'. The values of initiator and +responder MUST be the JIDs of the two participants, +respectively. The sessionId and hmac values MUST match the +sessionId and hmac values contained in both the session1 and +session2 PDUs. +
+
+ -
+
+Based on the selected authentication algorithm, the +initiator's authenticator is constructed. A digital signature algorithm +requires calculating: +
+-
+
-
+
+HK = hmac (initiator's nonce | responder's nonce, g^xy) +
+
+ -
+
+HASH_I = hmac (HK, version | sessionId | g^x | g^y | initiator's JID) +
+
+
+HASH_I is signed using the responder's private key and encoded in PKCS#1 format. +The PKCS#1 octets are then further encoded in base64 or hex. +
++The passphrase algorithm requires calculating: +
+-
+
-
+
+HK = hmac (hash (passphrase), initiator's nonce | responder's nonce) +
+
+ -
+
+HASH_I = hmac (HK, version | sessionId | g^x | g^y | initiator's JID) +
+
+
+The octets of HASH_I are simply encoded in base64 or hex. +
++The manner in which the initiator's user agent gains access +to the initiator's credentials is outside the scope of this +specification. +
+
+ -
+
-
+
+A set of conversation keys may optionally be included in +the response. This should typically be the case since +security sessions are negotiated for the sole purpose of +key transport. +
+
+
+These values are then used to prepare the XML session3 element; +this element is transmitted via the existing Jabber iq mechanism: +
+ ++The responder's user agent employs the following algorithm to process each session3 PDU: +
+ +-
+
-
+
+The attribute values are checked against the values sent in +the session2 PDU. A mismatch results in an error code of +10008. +
+
+ -
+
+The authenticator is verified. A failure results in an error code of 10007. +
+
+ -
+
+Any keys included in the PDU are processed and added to the user agent's key store. +
+
+
+If any errors occur during processing, the session negotiation +fails, and the error is communicated via the existing Jabber iq +mechanism: +
+ ++TBA +
+ ++Conversation keys are used to protect conversation data. +
+ ++Conversation keys are transported using the symmetric key wrap feature of +XML Encryption embedded in the keyTransport PDU. +
+ ++The sender's user agent employs the following algorithm to generate the keyTransport PDU: +
+ +-
+
-
+
+Appropriate values for the version, initiator, responder, and +sessionId attributes are assembled. The version of +this specification is '1.0'. The values of initiator and +responder MUST be the JIDs of the two participants who negotiated the +security session, respectively, and they +MUST correspond to an existing security session. +
+
+ -
+
+The key's identifier, convId, is assembled. +
+
+ -
+
+The payload, which consists of the confidentiality key and the integrity key, is wrapped +in instances of xenc:EncryptedKey as follows: +
+
+ -
+
+The Type attribute of the xenc:EncryptedKey element MUST indicate 'content'. +
+
+ -
+
+The Id, MimeType and Encoding attributes of the xenc:EncryptedKey element MUST NOT +be present. +
+
+ -
+
+The xenc:EncryptionMethod element MUST be present, and the Algorithm attribute +MUST indicate a valid symmetric key wrap algorithm. Furthermore, the +algorithm MUST be the same as was negotiated for the security session. +
+
+ -
+
+The ds:KeyInfo element MUST NOT be present. The key to use is SKc of the +security session. +
+
+ -
+
+The xenc:CipherData element MUST be present, and it MUST use the CipherValue choice. +
+
+ -
+
+The HMAC is computed using SKi of the security session over the following values: +
+-
+
-
+
+the version attribute of the keyTransport element +
+
+ -
+
+the initiator attribute of the keyTransport element +
+
+ -
+
+the responder attribute of the keyTransport element +
+
+ -
+
+the sessionId attribute of the keyTransport element +
+
+ -
+
+the character string used to construct the body of the convId element +
+
+
+ -
+
-
+
+These values are then used to prepare the XML keyTransport element; +this element is transmitted via the existing Jabber iq mechanism: +
+ ++The receiver's user agent employs the following algorithm to process each keyTransport PDU: +
+ +-
+
-
+
+The values of the version, initiator, responder, and sessionId are validated; initiator, +responder, and sessionId MUST indicate an existing security session. +A version mismatch results in an error code of 10000; an invalid security session +results in an error of 10010. +
+
+ -
+
+The payload, which consists of the confidentiality key and the intergrity key, is unwrapped. +Any failures result in an error code of 10012. +
+
+ -
+
+The body of the HMAC element is decoded into the actual HMAC octet string. +
+
+ -
+
+The HMAC is validated. An invalid HMAC results in an error code of 10011. +
+
+ -
+
+The keys are added to the user agent's key store. +
+
+
+If any errors occur during processing, the error is communicated via the existing Jabber iq +mechanism: +
+ ++The ultimate goal is, of course, the protection of conversation data. The protocol exchanges +described above allow the conversation participants to cryptographically protect their conversation data using the conversation keys that they share. +
+ ++A protected message is defined as a traditional Jabber message whose body content +is extended to include the transport of a cryptographically protected message body. +The two key features are +
+ +-
+
-
+
+First, the usual body element contains some arbitrary text. Those familiar with the +evolution of email protocols will recognize this trick as the same one used +when MIME was introduced. +
+
+ -
+
+Second, the message contains a Jabber x element defining the Jabber:security:message +namespace; this element transports the protected message. +
+
+
+This mechanism has the advantages of allowing transparent integration with existing +Jabber servers and existing Jabber clients. +
+ ++The sender's user agent employs the following algorithm to generate the protectedMessage PDU: +
+ +-
+
-
+
+Appropriate values for the version, from, to, convId, and +seqNum attributes are assembled. The version of +this specification is '1.0'. The value of convId MUST correspond to an existing, valid key. +
+
+ -
+
+The actual message body is encoded into a character string corresponding to a Jabber message body element. This character string is then wrapped in an instance of xenc:EncryptedData as follows: +
+
+ -
+
+The Type attribute of the xenc:EncryptedData element MUST indicate 'element'. +
+
+ -
+
+The Id, MimeType and Encoding attributes of the xenc:EncryptedData element MUST NOT +be present. +
+
+ -
+
+The xenc:EncryptionMethod element MUST be present, and the Algorithm attribute +MUST indicate a valid block encryption algorithm. +
+
+ -
+
+The ds:KeyInfo element MUST NOT be present. The key to be used is the confidentiality +key indicated by the convId attribute. +
+
+ -
+
+The xenc:CipherData element MUST be present, and it MUST use the CipherValue choice. +
+
+ -
+
+Using the HMAC key indicated by the convId attribute, the HMAC is computed +over the following values: +
+-
+
-
+
+the version attribute of the protectedMessage element +
+
+ -
+
+the from attribute of the protectedMessage element +
+
+ -
+
+the to attribute of the protectedMessage element +
+
+ -
+
+the convId attribute of the protectedMessage element +
+
+ -
+
+the seqNum attribute of the protectedMessage element +
+
+ -
+
+any securityLabel element +
+
+ -
+
+the character string used to construct the body of the payload element +
+
+
+ -
+
-
+
+These values are then used to prepare the XML protectedMessage element; +this element is transmitted via the existing Jabber message mechanism: +
+ ++The receiver's user agent employs the following algorithm to process each protectedMessage PDU: +
+ +-
+
-
+
+The values of the version, from, to, convId, and seqNum are validated. +A version mismatch results in an error code of 10000. An unknown convId +results in an error code of 10015. If replay protection is utilized, a +duplicate seqNum results in an error code of 10016. +
+
+ -
+
+The body of the HMAC element is decoded into the actual HMAC octet string. +
+
+ -
+
+The payload, which consists of the actual message body, is unwrapped. +Any failures result in an error code of 10012. +
+
+ -
+
+The HMAC is validated. An invalid HMAC results in an error code of 10011. +
+
+
+If any errors occur during processing, the error is communicated via the existing Jabber iq +mechanism: +
+ ++The following block encryption algorithms are required, as +specified by XML Encryption: +
+ +-
+
-
+
+http://www.w3.org/2001/04/xmlenc#tripledes-cbc +
+
+ -
+
+http://www.w3.org/2001/04/xmlenc#aes128-cbc +
+
+ -
+
+http://www.w3.org/2001/04/xmlenc#aes256-cbc +
+
+
+The following symmetric key wrap algorithms are required, as +specified by XML Encryption: +
+ +-
+
-
+
+http://www.w3.org/2001/04/xmlenc#kw-tripledes +
+
+ -
+
+http://www.w3.org/2001/04/xmlenc#kw-aes128 +
+
+ -
+
+http://www.w3.org/2001/04/xmlenc#kw-aes256 +
+
+
+This protocol makes use of the following Diffie-Hellman groups adopted from IKE. +
+ ++The hexidecimal value of the prime, p, is +
+ ++The decimal value of the generator, g, is 2. +
+ ++The hexidecimal value of the prime, p, is +
+ ++The decimal value of the generator, g, is 2. +
+ ++The hexidecimal value of the prime, p, is +
+ ++The decimal value of the generator, g, is 2. +
+ ++The hexidecimal value of the prime, p, is +
+ ++The decimal value of the generator, g, is 2. +
+ ++This entire document is about security. +
+ ++This version of the protocol deliberately incorporates only a minimal amount +of cryptographic choice. Examples of possible choices that can readily +added in future drafts include: +
+ +-
+
-
+
+Support for the Digital Signature Standard +
+
+ -
+
+Support for Elliptic Curve Cryptography +
+
+ -
+
+Additional symmetric algorithms +
+ -
+
+Additional hash algorithms +
+
+
+
+Furthermore, additional credential formats, such as OpenPGP, may be addressed +in future drafts. +
+ ++This version of the protocol includes a mechanism that derives a cryptographic key from a +passphrase shared by a community of users. It is impossible to overstate the security +issues that such a mechanism raises. +
+ ++This version of the protocol does not include a specific rekeying capability. Data volumes +in IM environments are expected to be small, and the protocol prefers to simply instantiate +new conversation keys. It is straightforward to extend the security session protocol to +enable negotiation of a new key. +
+ ++"XML Encryption Syntax and Processing"; http://www.w3.org/TR/xmlenc-core +
+ ++more to be added +
+ +It is widely acknowledged that it would be good to be able to express a Jabber Identifier (JID)
Although XMPP enables a wide range of functionality, the authors propose that a Jabber URI scheme needs to support only a limited subset of the possible Jabber functionality. In particular, we see the following as core functions that need to be supported:
+-
+
- Sending of basic messages +
- Sending of basic presence +
- Sending of subscription requests +
The syntactic components of a Jabber URI are as follows:
+<xmpp>:[<node-identifier>@]<domain-identifier>[?<query>]
+ This scheme is similar to the mailto URI scheme
Per the JID definition in JEP-0029, the node identifier is optional (i.e., a mere domain identifier is a valid JID). However, the proposed Jabber URI scheme forbids the inclusion of a resource identifier in the JID, even though JEP-0029 defines this as valid. This is partly because the authors see no compelling reason to include a resource identifier in the Jabber URI scheme, and also because including a resource would necessitate the inclusion of a slash character in an opaque URI, which is contrary to RFC 3986. Finally, the query component is optional.
+RFC 3986 limits the characters included in a URI to US-ASCII characters, and further defines a number of US-ASCII characters as reserved or otherwise excluded. Reserved characters are special characters used as delimiters withing URIs and whose usage is limited to their reserved purpose as defined in RFC 3986 or a specific URI scheme. Excluded characters are control characters, spaces, and other common (non-URI-specific) delimiters such as angle brackets, double quotes, the number sign, and the percent sign. Reserved characters must be escaped if their usage in a specific context would conflict with their reserved purpose, and excluded characters must always be escaped. The set of disallowed charaacters for any specific URI component consists of the reserved and excluded characters for that component. These are defined below for each component of a Jabber URI.
+The scheme component for a Jabber URI is 'xmpp'. This component is delimited from the remainder of the URI by a colon character (':').
+The node identifier component of a Jabber URI is equivalent to the "userinfo" component of a generic URI. Section 2.3 of JEP-0029 stipulates that a node identifier may contain any Unicode character higher than #x20 with the exception of the following:
+#x22 (") | #x26 (&) | #x27 (') | #x2F (/) |
+#x3A (:) | #x3C (<) | #x3E (>) | #x40 (@) |
+#x7F (del) | #xFFFE (BOM) | #xFFFF (BOM)
+ In addition, Section 2.2 of RFC 3986 stipulates that the following additional characters are reserved:
+#x24 ($) | #x2B (+) | #x2C (,) | #x3B (;) | #x3D (=) | #x3F (?)
+ Section 2.4.3 of RFC 3986 further stipulates that the following characters are excluded from URIs in their unescaped form:
+#x23 (#) | #x25 (%)
+ Finally, because the generic URI syntax does not provide a way to specify a character encoding other than US-ASCII (see Section 2.1 of RFC 3986), the characters in the node identifier component of a Jabber URI must contain only US-ASCII characters.
+Therefore, in order to ensure that a Jabber URI containing a node identifier is a valid URI, the characters disallowed by RFC 3986 (reserved, excluded, and non-ASCII characters) must be escaped in the node identifier component of a Jabber URI.
+A domain identifier is a standard DNS hostname as specified in RFC 952
The query component of a Jabber URI may contain any US-ASCII character higher than #x20 with the exception of the following:
+#x22 (") | #x23 (#) | #x24 ($) | #x25 (%) |
+#x26 (&) | #x27 (') | #x2B (+) | #x2C (,) |
+#x2F (/) | #x3A (:) | #x3B (;) | #x3C (<) |
+#x3D (=) | #x3E (>) | #x3F (?) | #x40 (@) |
+#x7F (del) | #xFFFE (BOM) | #xFFFF (BOM)
+ Thus the most basic Jabber URI is user@host (sometimes referred to as a "bare JID") prepended by 'xmpp:', as shown in the following example.
+
+xmpp:user@host
+
+ A URI containing bare JID and no query component should trigger an application to present a user with an appropriate interface to complete an action such as sending a message, sending presence, or managing a subscription. In order to make this possible, some basic queries must be included in the protocol.
+The authors propose three allowable query types in a Jabber URI: message, presence, and subscribe
If no parameters are passed along with the message query type, an application should present a user with an appropriate interface to complete the sending of a message.
+The query component may include parameters that further specify the message to be sent to the intended recipient. The following parameters are allowed:
+-
+
- body +
- subject +
- thread (for conversation tracking) +
If no parameters are passed along with the presence query type, an application should present a user with an appropriate interface to complete the act of sending presence.
+The query component may include parameters that further specify the presence to be sent to the intended recipient (e.g., a user-defined status message). The following parameters are allowed:
+-
+
- type ('unavailable'; if not specified, the sender is defined to be online and available) +
- show (one of 'away', 'xa', 'dnd', or 'chat') +
- status (user-defined status message) +
- priority (a non-negative integer, with zero as the lowest priority) +
If no parameters are passed along with the subscribe query type, an application should present a user with an appropriate interface to complete the subscription request.
+The query component may include parameters that further specify the subscription request to be sent to the intended recipient. Only the 'type' parameter is deemed useful in the limited Jabber URI spec, with valid values of 'subscribe', 'subscribed', 'unsubscribe', or 'unsubscribed'.
+On the existing Jabber network, there are many opportunities to optimize stanza traffic. For example, clients that want to send the same stanza to multiple recipients currently must send multiple stanzas. Similarly, when a user comes online the server sends many nearly-identical presence stanzas to remote servers.
+ +The 'http://jabber.org/protocol/address' specification provides a method for both clients and servers to send a single stanza and have it be delivered to multiple recipients, similar to that found in &rfc0822;. As a side-effect, it also provides all of the functionality specified by the old 'jabber:x:envelope'
Support for Extended Stanza Addressing in a given server instance SHOULD be determined using &jep0030;. A conforming server MUST respond to disco#info requests.
+ +To determine if a server or service supports Extended Stanza Addressing, the requesting entity SHOULD send a disco#info request to it.
+ +If the server supports Extended Stanza Addressing, it MUST include a "http://jabber.org/protocol/address" feature in the response.
+The IM service MAY implement multicast directly, or it MAY delegate that chore to a separate service. A client can use the following approach to find a multicast-capable service hosted by its domain:
+-
+
- Send a disco#info request to the IM server; if its reply includes the 'http://jabber.org/protocol/address' feature, then it is a multicast-capable service. +
- If the IM server is not a multicast-capable service, send a disco#items request to the IM server; the IM server will then return a list of associated services. +
- Send a disco#info request to each of the services associated with the IM server; if one of the replies includes the 'http://jabber.org/protocol/address' feature, then that service is a multicast-capable service. +
The multicast service MAY choose to limit which local users can use the service. The server MAY choose to limit whether non-local servers can send address headers that require the local server to send to third parties (relaying). In either case, if the server chooses to disallow the request, the server MUST return a Forbidden error (see the Error Conditions section below). In the relaying case, the server SHOULD NOT deliver to any of the addresses (even the local ones) if the sender is disallowed.
+Implementations MAY choose to cache the disco response. + Positive responses MAY be cached differently than negative + responses. The result SHOULD NOT be cached for more than 24 + hours, unless some sort of time-to-live information is + added to the Service Discovery protocol in the future.
+For multicast processing, the stanza containing an address header + (the 'outer stanza') MUST be addressed to the multicast service, + with no username or resource in the 'to' attribute.
+ +When used for additional information in a one-to-one stanza + (e.g. using the 'node' attribute), the outer stanza SHOULD be + addressed directly to the recipient, not to the multicast + service.
+ +A multicast service MUST NOT change the 'from' address on + the outer stanza. Note that this will limit third-party + relaying across server-to-server connections as a side-effect.
+ +Address headers MAY be included in message or presence + stanzas. They MUST NOT be included as the direct child of an + IQ stanza.
+Address values are packaged together into an + <addresses/> element.
+ +Each address to which the sender wants the stanza to be re-sent will show up as an <address/> in the <addresses/> element. There are several different types of address, shown below.
+ +An <address/> element MUST possess a 'type' attribute, and MUST possess at least one of the 'jid', 'uri', 'node', and 'desc' attributes. An <address/> element MUST NOT possess both a 'jid' attribute and a 'uri' attribute. If sending through a multicast service, an address MUST include a 'jid' or a 'uri' attribute, unless it is of type 'noreply'.
+ +The 'jid' attribute is used to specify a simple Jabber ID associated with this address. If the 'jid' attribute is specified, the 'uri' attribute MUST NOT be specified. Support for the 'jid' attribute is REQUIRED.
+The 'uri' attribute is used to specify an external system address, such as a sip:, sips:, or im: URI. If the 'uri' attribute is specified, the 'jid' and 'node' attributes MUST NOT be specified. These URIs MUST be formatted as specified in their respective RFCs, however with the characters & < > ' " replaced by their equivalent XML escapes, & < > ' ". If a receiving entity does not understand the given URI scheme, or if the URI is not formatted correctly, a "JID Malformed" error SHOULD be returned. Support for the 'uri' attribute is OPTIONAL.
+The 'node' attribute is used to specify a sub-addressable unit at a particular JID, corresponding to a Service Discovery node. A node attribute MAY be included if a 'jid' attribute is specified. If a 'uri' attribute is specified, a 'node' attribute MUST NOT be specified. Support for the 'node' attribute is RECOMMENDED.
+The 'desc' attribute is used to specify human-readable information for this address. This data may be used by clients to provide richer address-book integration. This information is in the language of the sender, which MAY be identified using the standard xml:lang rules from &xmppcore;. Support for the 'desc' attribute is RECOMMENDED.
+When a multicast service delivers the stanza to a non-bcc address, it MUST add a delivered='true' attribute to the address element. A multicast service MUST NOT deliver to an address that was marked with a delivered='true' attribute when the service received the stanza. A multicast service SHOULD attempt to deliver to all addresses that are not marked with a delivered='true' attribute. The delivered attribute is used to prevent loops. See the Multicast Usage section below for more details. Support for the 'delivered' attribute is REQUIRED.
+The 'type' attribute is used to specify the semantics of a particular address. Support for the 'type' attribute is REQUIRED.
+ +These addressees are the primary recipients of the stanza.
+These addressees are the secondary recipients of the stanza.
+These addressees should receive 'blind carbon copies' of the stanza. This means that the server MUST remove these addresses before the stanza is delivered to anyone other than the given bcc addressee or the multicast service of the bcc addressee.
+This is the address to which all replies are requested to be sent. Clients SHOULD respect this request unless an explicit override occurs. There MAY be more than one replyto or replyroom on a stanza, in which case the reply stanza MUST be routed to all of the addresses.
+This is the JID of a &jep0045; room to which responses should be sent. When a user wants to reply to this stanza, the client SHOULD join this room first. Clients SHOULD respect this request unless an explicit override occurs. There MAY be more than one replyto or replyroom on a stanza, in which case the reply stanza MUST be routed to all of the addresses.
+This address type contains no actual address information. Instead, it means that the receiver SHOULD NOT reply to the message. This is useful when broadcasting messages to many receivers.
+As specified herein, the <address/> element is empty. Implementations or future protocols MAY extend the <address/> element for additional functionality, but any extensions are out of scope for this JEP. Such extensions SHOULD be appropriately qualified with a new namespace, and any extensions that are not understood by an implementation MUST be ignored.
+ +The following usage scenario shows how messages flow through both address-enabled and non-address-enabled portions of the Jabber network.
+ +Note: the logic associated with how to perform the following tasks is purely informational. A conforming service MUST generate output as if these rules had been followed, but need not (and probably will not) use this algorithm.
+ +-
+
- User desires to send a stanza to more than one + recipient. + +
- Client determines the JID of a multicast service, + using Service Discovery. + +
- If no multicast service is found, the client MAY + choose to deliver each stanza individually, or it MAY + query each of the servers associated with desired + recipients, and batch stanzas to those servers + itself. + +
- If a multicast service is found, the client constructs + a stanza with an address block, and sends it to the + multicast service. (Note: For the following rules, any + address that was marked on the incoming address header + with delivered='true' is never re-delivered.) + +
- The server checks to see if it can deliver to all of + the specified addresses. If not, the stanza is returned + with a "Forbidden" error, and processing stops. + +
- The server adds a delivered='true' attribute to all + addresses. + +
- The server removes all type='bcc' attributes. + +
- The server delivers the stanza to all of the 'to', + 'cc', and 'bcc' addresses from the original address header that + are being handled locally. The server replaces the + 'to' attribute on the outer stanza with the JID of each + addressee. Each 'bcc' recipient MUST receive only the + <address type='bcc'/> associated with that + addressee. + +
- For each non-local server (the 'target server') that + has addresses specified in 'to', 'cc', or 'bcc' addresses + in the original address header, the local server determines + whether the target server supports multicast, using Service + Discovery. + +
- If the target server does not support address headers, the + local server sends a copy of the stanza to each address, + with the 'to' attribute on the outer stanza set to the JID + of the given addressee. + +
- If the target server does support address headers, the server + removes the delivered='true' attributes on each of the + addresses bound for that server, and replaces the 'to' + attribute on the outer stanza with the adress of the + multicast service for the target server. The 'bcc' + addresses for the target server from the original address header + are added back to the address header. A single stanza is sent to + the target server. +
Assume for these examples that header1.org and header2.org + support address headers, and noheader.org does not.
+ +When replying to a message stanza that contains an extended + address, the following rules apply:
+ +-
+
- If more than one replyto or replyroom address is + specified (bad protocol), or if a noreply address is + specified, a reply SHOULD NOT be generated. + +
- If a replyroom address is specified, the client SHOULD + join the specified chat room instead of replying directly + to the specified user. No further extended address + processing is required. + +
- If a replyto address is specified, the reply SHOULD go + to the specified address. No further extended address + processing is required. Any <thread/> element from + the initial message MUST be copied into the reply. + +
- Otherwise, an extended-address aware client MUST copy + the address header from the original message into the reply, + removing any delivered attributes. If the original sender + is not in the copied list, the original sender MUST be + added as a 'to' address. The recipient's address SHOULD + be removed from the list. The client then proceeds with + the rules from the Multicast Usage + section above for delivery of the message. +
The following error conditions are to be used by implementations (for further information regarding error syntax, see &jep0086;):
+| XMPP Condition | +Purpose | +
|---|---|
| <forbidden/> | +The sending user does not have permission to use this multicast service. | +
| <jid-malformed/> | +A URI attribute was invalid or not understood (note that support for the 'uri' attribute is optional). | +
| <not-acceptable/> | +Too many receiver fields were specified. Servers MAY have configurable limits for this, but the limit MUST be at least 50. | +
A recipient SHOULD trust a stanza's extended addressing headers only as much as it trusts the sender of the stanza.
+Furthermore, there exists the potential for abuse related to the 'replyto' and 'replyroom' features (e.g., an entity could send messages with 'replyroom' set to the address of a room that hosts salacious content or with 'replyto' set to the address of a spambot that harvests Jabber addresses). Therefore if a human user's receiving application receives a message with extended stanza addressing that specifies a 'replyto' or 'replyroom' address other than that of the sender, it SHOULD inform the user of that fact. (Naturally, the receiving application MAY also limit the entities to which the recipient can reply using privacy lists as specified in &xmppim;.)
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; shall include 'http://jabber.org/protocol/address' in its registry of protocol namespaces.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0033: http://www.jabber.org/jeps/jep-0033.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+ Sections of this document were inspired by RFC 822.
+The Simple Authentication and Security Layer (SASL) (see &rfc4422;) provides a generalized method for adding authentication support to connection-based protocols. This document describes a generic XML namespace profile for SASL, that conforms to section 4 of RFC 4422, "Profiling requirements".
+ +This profile may be used for both client-to-server and server-to-server connections. For client connections, the service name used is "jabber-client". For server connections, the service name used is "jabber-server". Both these names are registered in the IANA service registry.
+ +The reader is expected to have read and understood the SASL specification before reading this document.
+In these examples, "client" refers to the remote entity that initiated the connection, either a Jabber client or a Jabber server. "Server" refers to the server that the remote entity is attempting to connect and authenticate to.
+ +The steps involved for a SASL negotiation are as follows:
+ +-
+
- Client requests SASL authentication +
- Server responds with list of available SASL authentication mechanisms +
- Client selects mechanism +
- Server sends a challenge +
- Client responds to challenge +
- Server sends more challenges, client sends more responses +
This series of challenge/response pairs continues until one of three things happens:
+ +-
+
- Client aborts the handshake. +
- Server reports failure. +
- Server reports success. +
After authentication has completed, the client sends a packet to begin the session.
+ +The namespace identifier for this protocol is http://www.iana.org/assignments/sasl-mechanisms.
+ +The following examples show the dialogue between a client [C] and a server [S].
+ ++
+The client begins by requesting SASL authentication as part of the normal Jabber stream negotiation.
Next, the client selects an authentication mechanism:
+ +The server responds with a mechanism-specific challenge, which the client must respond to. More than one challenge/response pair can take place; this is mechanism-specific.
+ +Challenges and responses are Base64
For mechanisms that require the client to send data first (ie the first challenge from the server is empty), the client may optionally send its first response as part of the mechanism selection:
+ +The handshake continues until authentication completes successfully, authentication fails, or the client aborts the handshake:
+ +Optionally, the server or client may send an informative message along with the success, failure or abort command:
+ +Following a failure or client abort, the client may start a new handshake. Following a successful authentication, any further attempts by the client to begin a new authentication handshake will automatically result in the server sending a failure.
+Note: that this section only applies to client-to-server connections.
+ +Following successful authentication, the client must send a standard IQ set packet in the jabber:iq:auth namespace to start a session. The client must supply a username and resource for the session along with this packet.
+ +If the client attempts to start a session before authenticating, or the username given in the jabber:iq:auth packet does not match the username given in the authentication credentials (when the SASL mechanism supports it), the server will return a 401 (Unauthorized) error packet.
+Traditionally, Jabber servers have supported two authentication models - jabber:iq:auth for client-to-server authentication, and dialback for server-to-server authentication.
+ +Until SASL authentication is in widespread use, clients and servers may support both SASL and the legacy jabber:iq:auth authentication system for client-to-server connections. Note that neither the client nor the server are required to support legacy authentication; it is simply a courtesy to users until the majority of clients and servers support SASL authentication.
+ +If a client connects and does not request the use of SASL (that is, the SASL profile namespace identifier does not appear in the stream initializer response), then the server should disable SASL for this connection; that is, it should not add the SASL profile namespace identifier to the stream initialization response, nor should it offer any SASL mechanisms.
+ +If a client connects to a server that does not support SASL (identified by the lack of the SASL profile namespace identifier in the stream initializer response, even though the client requested it), the client may choose to fall back to use legacy authentication.
+SASL authentication for server-to-server connections is not intended to replace dialback, as there are uses for both. Dialback is useful in an uncontrolled environment, such as the global Internet, where it is necessary to verify the identity of the remote server. SASL authentication has uses in a more controlled environment, where the administrator wishes to restrict access to a certain number of known remote servers.
+ +To this end, the use of dialback is not deprecated. If a remote server connects and requests the use of dialback (by specifying the "jabber:server:dialback" namespace, the the local server shall not offer SASL authentication. Similarly, if the remote server connects and requests the use of SASL authentication, then the local server shall not offer dialback. In the event that the remote server requests both, the local server should terminate the stream immediately and close the connection. If the remote server requests neither, then the local server may choose to support the pre-dialback server-to-server stream, but it is recommended that the local server terminate the stream and close the connection.
+The TLS protocol
Traditionally, Jabber servers has supported TLS by utilising a "wrapper" around the standard protocol stream. This wrapper usually listens on a port other than those listed in the IANA registry
This document describes an extension to the Jabber XML stream that provides a "STARTTLS" command which clients may invoke on an insecure stream to secure it. This extension is modelled on RFC 2595, which describes the STARTTLS extension for the IMAP
This protocol operates over the standard Jabber client connection on port 5222.
+ +The namespace identifier for this protocol is http://www.ietf.org/rfc/rfc2595.txt.
+ +The following examples show the dialogue between a client [C] and a server [S].
+ ++
+The client begins by requesting the use of STARTTLS as part of the normal Jabber stream negotiation. The server responds by informing the client whether or not it supports STARTTLS. It does this in the normal stream negotiation response:
+ +In the event that a server does not support the STARTTLS extension, it will respond with the normal stream negotiation response:
+ +To begin the TLS negotiation, the client issues the STARTTLS command:
+ +When the server is ready to begin the TLS negotiation, it will close the XML stream, but will keep the underlying connection to the client open:
+ +The client now begins a normal TLS negotiation by sending the TLS ClientHello command. Upon completion of the TLS negotiation, the client reissues the XML stream initialization:
+ +This is necessary, since any information about the stream presented by the server or the client may have been modified by an attacker.
+ +Note that once the secure channel has been established, the server must not advertise or allow the use of the STARTTLS command.
+TLS allows clients to be authenticated by verifying the certificate that they present during the TLS negotiation. This can be done in conjunction with the Jabber SASL profile
If a client authenticates with a certificate using the TLS authentication, and the client requests the use of SASL in the second XML stream negotiation (over the secure channel), servers supporting certificate-based authentication should add the EXTERNAL mechanism to the list of supported authentication mechanisms. If the client then requests this mechanism, the server should automatically inform the user that authentication was successful. See RFC 2222 and JEP-0034 for more information.
+ +Servers implementing STARTTLS functionality are not required to implement certificate-based authentication.
+The Jabber community needs a cohesive standard for publish-subscribe functionality. Certainly there is interest in developing such a standard, as witness the number of JEPs written on this topic.
Traditional pub-sub consists of event notification. This makes it possible for entities to publish data and for other interested entities to receive notification when the data is published. The following are some likely applications of pub-sub functionality within Jabber:
+-
+
- Auction and trading systems +
- Online catalogs +
- Document workflow systems +
- Network management systems +
- NNTP over Jabber +
- Groupchat +
In such systems, a subscriber would request to receive notifications about data the subscriber is interested in. We define a "topic" as an object that defines the relationship between a publisher and its subscribers. Specifically, a topic contains three essential collections of information:
+-
+
- A description of the information that will be provided +
- A list of subscribers to items that fit the description +
- One or more items that fit the description +
We define an "item" as an instance of data published by the publisher that fits the description associated with a topic. Each item MAY possess a unique identifier that enables the data to be tracked. (NOTE: This JEP does not address the durability of items, i.e., data storage.)
+A topic is addressed by means of a unique "topic ID". A topic ID is simply a string with no required semantic meaning. While a topic ID may have semantic meaning (e.g., '/instruments/guitars/electric' or 'rec.music.dylan'), such meaning is not necessary and a topic ID may be any random string (e.g., 'a1gh83jfn342092'). The only requirement is that a topic ID be unique within the context of a specific pub-sub domain (e.g., pubsub.jabber.org).
+Data Stream Proxy Service (DSPS) is designed to be a common stream protocol for multicast (unicast as special case) over P2S2P (P2P as special case) connections.
+ +This document follows DSPS protocol version 0.5. Any XML data not explicitly defined or mentioned will be ignored without error. On startup, full fledged DSPS starts listening on port 5290 (and 80 if HTTP handshake implemented).
+ +(optional) Creating or modifying stream is done like so:
+ +-
+
- "to" with resource implies reconnection to previous relay stream with previously supplied credentials and authentication as per section "DSPS relay setup", otherwise implies creation of new stream where creator is granted "master" rights. +
- "minthroughput" (optional) is minimum 16 second average throughput below which peers will be disconnected (but not dropped). Checked after every unit of outgoing transfer against the fourth value returned by "who" query for each peer. Legal only upon initial creation of stream. If omitted or negative, 0 is assumed. +
- "maxpublic" (optional) is maximum number of peers that can join without invitation. If omitted or negative, 0 is assumed. If positive, DSPS generates globally unique id for public peers to acknowledge, reported within "stats" message. Said id remains constant for life of stream. +
- <peer/> (optional) full JID of stream on another DSPS. Relay stream will be treated using "slave" rights. Legal only upon initial creation of stream. Multiple such blocks tried in series until successful connection. First successful (last if all failed) remembered by DSPS, all successive <peer/> ignored.. On connection, DSPS initiates handshake using peer's full JID and contents of block for destination's full JID to the relay destination as per section "Connecting to DSPS via default method". Authentication is done as per section "DSPS relay setup". Upon successful handshake, DSPS sends presence notification to peer as per section "Acknowledge of DSPS connection". +
- "port" (optional) for connecting to destination DSPS. If omitted, default is assumed. +
- <comment/> (optional) all such blocks reported in "stats" message. Multiple such blocks allowed. Block may contain a full XML stack of elements. No order implied for "stats" message. +
Possible failure messages:
+ +| Code | Message | Description |
|---|---|---|
| 405 | Method Not Allowed | Attempt at reconnect to relay without existing credentials, relay still connected, <peer/> block present in reconnect request, or feature not supported |
| 504 | Gateway Timeout | All destination DSPS are unreachable. |
DSPS creates "id" (empty string is legal), used in "who" replies and notifies client of waiting connection like so:
+ +-
+
- "from" full JID of DSPS, internally globally unique. Used in handshake and every subsequent communication with stream. May differ with the one specified in "invite" message. +
- "wait" amount of time in milliseconds that DSPS will wait for client to initiate handshake. If timeout occurs, DSPS will totally forget prepared connection and act accordingly. +
- "host" (optional) for handshake and data stream. If omitted default from the "from" is assumed. Intended for P2P connections to be able to report alternate hostname or IP for connection. +
- "port" (optional) for handshake and data stream. If omitted default is assumed. +
- "minthroughput" value from "create". +
- "protocol" version this DSPS supports. +
- <feature/> (optional) supported by this DSPS. Type and version are properties and additional data stored in body. HTTP stream will not follow HTTP protocol. SSL handshake performed encrypted. Both HTTP and SSL connections are only between client and DSPS. +
Upon receipt of message as per section "Connection waiting", client can either ignore it and connection will timeout, or connect to the DSPS directly via any supported connection method or via relay. There may be a maximum of 1 (one) established connection to DSPS from any Client_full_JID + DSPS_full_JID pair, deviations are handles as per section "Connecting to DSPS via default method". DSPS will not discriminate method via which direct connection is made, even if prior to "disconnect" a different method was used. Any packet from an unauthorized connection is ignored without reporting an error.
+ +Client may request another DSPS to relay this connection as per section "Stream Creation/Relay", utilizing the "create" body. There is no limit on length of relay chain. Upon initiation of handshake with destination, DSPS reports key like so (message sequence unrelated to current DSPS handshake):
+ +-
+
- "get" denotes request for auth key. +
- "create" body contains key returned by destination. +
Client must send said key to destination as per section "Connecting to DSPS via default method" and send response to DSPS (which will be transmitted to destination) like so:
+ +-
+
- "result" denotes reply with auth key. +
- "create" body contains key returned by destination. +
Client must connect to DSPS on port 80 and initiate handshake. This may be attempted after "create" result received or "disconnect" occurred, and prior to "wait" timeout expiring, then send HTTP request like so:
+ +And will receive reply from DSPS before the start of data stream, like so:
+ +Upon completion, Client must resume DSPS handshake as per either section "Connecting to DSPS via default method" or section "Connecting to DSPS via SSL method" (if applicable). Subsequent data will not follow HTTP protocol. On error connection closed immediately with optional error messages.
+ +Possible failure messages:
+ +| Code | Message | Description |
|---|---|---|
| 401 | Unauthorized | (optional) Returned if any error in HTTP handshake. |
Client must connect to DSPS on specified port and initiate handshake. This may be attempted after "create" result received or "disconnect" occurred, and prior to "wait" timeout expiring, then send following on stream:
+ +Next, regular TLS handshake is initiated. Upon completion, Client must resume DSPS handshake as per section "Connecting to DSPS via default method". On error connection closed immediately with optional error messages.
+ +Possible failure messages:
+ +| Code | Message | Description |
|---|---|---|
| 401 | Unauthorized | (optional) Returned if any error in SSL handshake. |
Client must connect to DSPS on specified port and initiate handshake. May be attempted after "create" result received or "disconnect" occurred, and prior to "wait" timeout expiring. Standard and SSL handshakes are identical in decrypted state and take the form of:
+ +-
+
- "Client_full_JID" client full JID as supplied in either the "create" or "acknowledge" message. +
- "DSPS_full_JID" DSPS full JID as supplied in "from" field of "create" result message from section "Connection waiting" +
- <CR> regular carriage return, commonly referred to as the newline character. +
For example, the appropriate string for the above request would be:
+ +If Client_full_JID and DSPS_full_JID do not have an associated stream, are no longer valid, (e.g. timeout reached or client removed from stream), or connection from said Client_full_JID + DSPS_full_JID pair is in use (i.e. client is still connected to it), connection is closed immediately with possible optional error messages reported. Otherwise DSPS returns uniquely generated key followed by a <CR> like so:
+ +Client must now send key to DSPS via XML stream like so:
+ +-
+
- "get" denotes request for next auth key. +
- "auth" body contains key returned by DSPS. +
DSPS will now check key, if not valid, close connection, report possible optional error message and resume waiting on original key. If valid, generate new key and send to client like so:
+ +-
+
- "result" denotes return of next auth key. +
- "auth" body contains key returned by DSPS. +
Client must now send received key to DSPS via the stream followed by a <CR>. Once received, DSPS checks key, on mismatch connection is closed immediately with possible optional error messages reported, waiting on key is resumed. Upon successful handshake a message is sent to members of the stream in accordance with the following rules; If the client had type "master" connection, all members of the stream get notified. If the client had type "slave" connection, only other type "master" members get notified. The message takes the form of:
+ +-
+
- "presence" denotes presence change. Body may contain multiple <peer/> blocks where same JID peers must be placed in chronological order relative to each other from start to end of message. +
- <peer/> body is full JID of the joined peer unless peer of type "relay", in which case the resource is not reported. +
- "status" is new status of peer. +
Possible failure messages:
+ + +| Code | Message | Description |
|---|---|---|
| 401 | Unauthorized | (optional) Returned if the DSPS is not aware of said Client_full_JID + DSPS_full_JID pair. Where "from" contains DSPS_full_JID that was used in the handshake and "to" contains Client_full_JID that was used in the handshake. |
| 409 | Conflict | (optional) Returned if connection from said full client JID and full DSPS JID is in use (i.e. client is still connected to it). Where "from" contains DSPS_full_JID that was used in the handshake and "to" contains Client_full_JID that was used in the handshake. |
DSPS protocol allows multiple peers to use the same stream. Manipulation of the authorized peer list is done through admin functionality described in next several subsections. DSPS protocol allows for three types of peer connections: "master", "slave", and "relay". "master" peers get full control of the stream, "slave" peers get limited control of the stream, and "relay" are treated similar to "slave" except in reporting of JIDs where the resource must be omitted.
+ +"master" peers are allowed to invite any other user to the stream and drop any peer registered with the stream, including themselves. "slave" peers are only allowed to drop themselves from the stream. Any administrative changes coming from a "slave" peer that are not for the peer's own connection are ignored. Dropping one's own connection is the preferred way of permanently disconnecting from the stream.
+ +Any data received from a "master" gets copied to every other peer on the stream. Any data received from a "slave" peer gets copied to all "master" peers on the stream only.
+ +Stream administration request looks like so:
+ +-
+
- "admin" denotes administrative functions are to follow. Any properties within this block apply to this block alone. Multiple such blocks are allowed. +
- "expire" time DSPS should wait for the "acknowledge" message from any invited peer within block. An "expire" of 0 denotes no time limit. Actual value sent to peer as "expire" is minimum of this value and default value preset for DSPS. If value unparseable or not present, default is used. +
- "wait" time DSPS should wait for invited peer to connect to DSPS after "acknowledge" is received and message from section "Connection waiting". is sent. A "wait" of 0 denotes no time limit. Actual value sent to peer as "wait" is minimum of this value and default value preset for DSPS. If the value unparseable or not present, default is used. +
- <comment/> (optional) block sent to each of the peers. Multiple such blocks are allowed. Block may contain a full XML stack of elements. All such blocks are sent to each of the invited peers as is. No guarantee is made on their order in the <invite/> message. +
- <peer/> JID to execute action upon. If invitation then body will not necessarily be same full JID as one that would respond. Multiple such blocks allowed. +
- "type" type of action to do. "master" denotes invitation, granting master rights. "slave" denotes invitation, granting slave rights. "drop" denotes request to drop peer from stream. "relay" peers may not be invited but may be dropped using this method. +
Possible optional errors include the following:
+ +-
+
- "admin" denotes admin response, sent to sender of "admin" request for every peer in block. Peers may be combined from multiple "admin" requests or peers from single "admin" request may be split over multiple "admin" replies. +
- <peer/> peer in question. For "expire" JID is one from invite request. For "reject" JID is one from which reject received. For "timeout" JID is one from invite request. For "missing" is one from drop request. After this DSPS will totally forget about this peer. +
- "acknowledge" reason for failure. "expire" denotes "expire" timeout sent, has ended. "reject" denotes peer rejected invite. "timeout" denotes "wait" timeout sent, has ended. "missing" denotes peer marked for drop not found registered on tis stream. +
Possible failure messages:
+ +| Code | Message | Description |
|---|---|---|
| 403 | Forbidden | (optional) Returned if peer with "slave" rights attempts to use "master" admin privileges. |
Upon invite DSPS will attempt to invite each of the peers like so:
+ +-
+
- "from" is unique JID/resource pair generated for this JID, not necessarily same as JID/resource pair specified in section "Connection waiting". It is used for identification of the "acknowledge" message. +
- "acknowledge" denotes request for invitation acknowledge. +
- "status" type of connection the client is granted. Same type as tag in invitation request. +
- "expire" time DSPS will wait for the "acknowledge" message. +
- <peer/> peer who initiated this invite. Multiple such blocks may exist if multiple distinct peers sent invitation that have not yet been received by the invitee. +
- <comment/> is <comment/> structure(s) sent in admin request, present if admin request contained it. +
Upon drop DSPS will immediately closes the connection to the dropped peer. It then will totally forget this peer right after sending it a notification message like so:
+ +-
+
- "from" is the DSPS JID/resource pair which DSPS has associated with this connection. +
- "acknowledge" denotes drop notification. Despite the block name, this message does not require a reply. +
- "status" drop denotes a connection drop. +
- <comment/> is <comment/> structure(s) sent in admin request, preset if admin request contained it. +
For every successfully dropped peer a message is sent to all other stream members, following the rules stated for the "presence" message, and takes the form of:
+ +-
+
- "from" is the DSPS JID/resource pair which DSPS has associated with the connection of the recipient of the message. +
- "presence" denotes presence change. Body may contain multiple <peer/> blocks where same JID peers must be placed in chronological order relative to each other from start to end of message. +
- <peer/> body is full JID of the dropped peer registered on the stream, unless peer is of type "relay", in which case the resource is not reported. +
- "status" is new status of peer. +
An invited peer has the option to accept or reject an invitation to a stream.
+ +To accept an invitation to a stream, the peer must reply like so:
+ +-
+
- "from" is the JID/resource pair which will be associated with this connection, only it will be allowed to connect to this stream as this user. A peer may be registered to multiple streams from the same full JID, hence all DSPS full JIDs linked to a given peer must be unique. +
- "to" contains the DSPS JID/resource pair which was the source in the original "acknowledge" message. +
- "acknowledge" denotes acknowledgment to invitation. +
- "status" connect denotes an acceptance of invitation. +
Upon receipt of this reply the DSPS creates a unique resource for this client JID/resource pair. It then prepares the "create" message as described in section "Connection waiting".
+ +Rejecting an invitation can be done in two ways. A peer can forget about the invitation and let the invitation "expire", or preferably a message can be sent like so:
+ +-
+
- "to" contains the DSPS JID/resource pair which was the source in the original "acknowledge" message. +
- "acknowledge" denotes acknowledgment to invitation. +
- "status" drop denotes an rejection of invitation. +
Regardless of the way a rejection was achieved a notification message is sent to the inviting peer, as was described in section "Stream administration". If unknown "type" is sent, it will be interpreted as a reject. A maximum of one "acknowledge" is allowed during the lifetime of an invitation. If multiple such tags are sent, the first tag takes precedence. Any rejection of a public connection will be ignored.
+ +If a peer ever disconnects without first dropping themselves, the following policy applies:
+ +The peer may reconnect within the "wait" timeout provided in the "create" reply in section "Connection waiting". The peer may choose any supported mode of reconnection supplied in "create" reply, regardless of mode previously used. The "wait" timeout is not cumulative over multiple disconnects. After reconnect, peer will not receive any data that exists on the stream while it was disconnected.
+ +Upon such disconnection DSPS notifies all other members of the stream, following the rules stated for the "presence" message, and takes the form of:
+ +-
+
- "from" is the DSPS JID/resource pair which DSPS has associated with the connection of the recipient of the message. +
- "presence" denotes presence change. Body may contain multiple <peer/> blocks where same JID peers must be placed in chronological order relative to each other from start to end of message. +
- <peer/> body is full JID of the disconnected peer registered on the stream, unless peer is of type "relay", in which case the resource is not reported. +
- "status" is new status of peer. +
Upon reaching "wait" timeout the procedure is the same if the peer dropped its own connection.
+ +Permanent termination of connection can be done in two ways: peer may disconnect from the stream and let the "wait" timeout expire, or more preferably the peer will drop itself from the stream via an "admin" message. The "admin" is still allowed to contain multiple "peer" blocks.
+ +The use policy for the stream follows the standard rules described in this document. Type and structure of the data must be negotiated by the peers separately (presumably via the normal XML message stream or within <comment/> blocks). The DSPS stream operates at the speed of the slowest connection (or slower if it is so configured in its internal configuration).
+ +Data read from peer in a unit of transfer (decided by DSPS) is sent to other peers in a format like so:
+ +-
+
- "0" at beginning for checking start of block. +
- <size> length in bytes including id and its trailing CR in form of [1-9][0-9]*[0-9A-Z], where last character is base 36 numerical equivalent power of 1024. +
- <id> id of the sender as per "who" query. +
- <data> data sent. +
- <CR> regular carriage return, commonly referred to as the newline character. +
For example, the appropriate string for the above block would be:
+ +First block received after connection will always be full block. If discrepancy occurs, receiving peer should disconnect and reconnect back to stream.
+ +Two mechanisms exists to gain information about the stream configuration and its members. They are described within next few subsections.
+ +To retrieve listing of all registered peers of this stream and their respective connection status any registered peer sends a message like so:
+ +-
+
- "to" has the usual meaning for this client when referring to this DSPS stream. +
- "who" denotes that this is a listing request. It may not contain a body or attributes, otherwise it will be ignored without error. +
The query follows the standard rules: query originating from a "master" peer will return listing of all registered peers and their associated statuses, query originating from a "slave" peer will only return listing of all registered "master" peers and their associated statuses. Returned results do not have any strict order. If multiple "who" queries were requested by a peer that have not yet received a reply, only one reply need be sent.
+ +The query reply is formatted like so:
+ +-
+
- "from" is unique DSPS JID/resource pair for the peer receiving the result. +
- <peer/> body is full JID of registered peer, unless peer is of type "relay", in which case the resource is not reported. A separate block exists for every viewable peer. +
- "type" the type of connection peer has. May contain value of "master", "slave", or "relay". +
- "id" id prepended to data coming from this peer. +
- "status" current status of peer. "connect" denotes peer able to receive data. "wait" denotes peer registered but not connected. "expire" denotes peer was invited but no reply was received yet. +
- "throughput" shows the average throughput to that peer per second in the units specified after the number (e.g. B, KB, MB, GB, TB, EB) in capital letters. Time is measured only during data transfer. Value contains multiple fields delimited by slash (/). Each field represents time span of power of two (2), relative to its position from start of the string. Each filled-in field contains the average throughput over that timespan. e.g. (1B per sec in last sec)/(1.1B per sec in last 2 sec)/(0.9B per sec in last 4 sec). Only fields representing power of zero (2^0 sec) and power of four (2^4 sec) are required. Last field must be filled-in. +
To retrieve listing of all stream configuration/statistics values or public streams, any registered peer sends a message like so:
+ +-
+
- "to" if contains a resource, will return statistics for specified stream. Otherwise will return listing of public streams, i.e. any stream with "maxpublic" greater then 0. +
- "stats" denotes that this is a configuration/statistics request. It may not contain a body or attributes, otherwise it will be ignored without error. +
The query reply is formatted like so:
+ +-
+
- "from" the DSPS JID/resource pair for the peer receiving the result. +
- "init" UNIX timestamp of the date this stream was initiated. +
- "protocol" protocol version this DSPS supports. +
- "port" default port this DSPS listens for connections on. +
- "minthroughput" as defined in "create". +
- "expiredefault" default time this DSPS will wait for an "acknowledge" response. +
- "waitdefault" default time this DSPS will wait for a connection to its default port after an invitation is accepted. +
- "wait" time this DSPS will wait for this particular client to reconnect if it ever gets disconnected. This is the same value as one sent in the "create" response. +
- "public" number of "slave" peers registered with stream without invitation. +
- "maxpublic" maximum number of "slave"peers allowed without invitation. +
- "mastercount" number of peers with a "master" connection registered on this stream. +
- "slavecount" number of peers with a "slave" connection registered on this stream. +
- "relaycount" number of peers with a "relay" connection registered on this stream. +
- <feature/> (optional) denotes a supported feature. All supported features must be listed. +
- <peer/> (optional) list of public stream connections where all reported statistics match. Present only if "to" in original request contained no resource. Multiple allowed where statistics match for all. +
- <comment/> (optional) parameter(s) with a comments from "create". This block may contain full XML stack of elements. Multiple such blocks are allowed. +
All "status" attributes are required. Any other undefined blocks with any multiplicity, are legal in this block as long as their tags are not identical to any tag within the protocol. Results returned do not have any strict order. If "to" in original request contained no resource, multiple "stats" blocks are allowed, where each contains at least one <peer/> block which has "maxpublic" greater than 0. To join a public stream a client must send message as per section "Accepting an invite".
+ +Stream exists from its "create"ion time to the time when there are no more "master" peers registered with the stream.
+ +When last "master" peer is dropped from the stream, DSPS will make sure that all the data sent by all the "master" peers was actually copied to all the "slave" peers still present. For every remaining "slave" peer DSPS will initiate a drop event. Once stream is void of any peers it will be totally forgotten by the DSPS and all associated data is released.
+ +Error messages look like so:
+ +-
+
- <error/> denotes error block where body is text description. +
- "code" denotes error code. +
File transfer can be easily accomplished over DSPS. Where one user invites another user to a DSPS stream. File details can be transfered in the invitation comment as such: <meta type='file' name='myfile.txt' size='500K' crc32='12345' sha1='23451' mime='application/octet-stream' timestamp='12345' date='20020412T00:00:00'/>. Where the "size" would be in bytes. All properties should reflect their appropriate values for this instance. Once the second peer has accepted, it can simply put a CR on the stream stating that transfer can begin. then the first party simply dumps the contents of file on the stream, closes the stream and "drop"s itself from the stream. DSPS will make sure the second party gets everything that the first party sent before closing the connection. If multiple recipients of the file are required, the sending client can save a lot of bandwidth and transmit only one copy if the file to the DSPS which in term will transmit the data over to all the other connected clients.
+ +Same idea as the file transfer. However if more then two parties are involved, every party must have a "master" connection.
+ +A server has a JID which it registers with a stream. Any client wishing to join the multicast sends an XML message to the server, which then invites the client with a "slave" connection. Thus everything the server sends is received by every client on the stream. If there are multiple back-up servers, they can be invited with a "master" connection, thus if one of them goes down, the others can take over.
+ +It has long been discussed in many Jabber places that a file storage facility is desired. The communication with such a facility can be easily accommodated with DSPS, as such a facility would merely appear as a user to DSPS which can either be "invite"ed or "invite" other users onto personal streams to transfer files as described in 6.1.
+ +PASS has the following design flaws that make it unsuitable for its stated purpose of providing raw data-streams to all classes of users, including those behind firewalls or NAT.
+ +PASS requires the use of a large number of individual ports, which on a heavily loaded server can lead to the number of spare ports dropping to zero, causing connections to be refused.
+ +This is also problematic if PASS is situated behind a firewall. Firewall administrators are typically loathe to allow incoming connections to a large range of ports.
+ +DSPS only uses one port, and so resolves the first problem, while making the second almost a non-issue.
+ +PASS requires the client to have some knowledge of IP, which immediately forces the assumption that the XML stream's underlying protocol is in fact, IP. While at the time of writing this is always the case, it may not always be this way.
+ +DSPS uses the Jabber ID to do its routing, and so avoids these problems. And while DSPS does use the concept of a TCP connection and an IP port, this information is never actually used anywhere on the XML stream, making the actual connection to the DSPS implementation-defined.
+ +PASS makes the IP address of the remote client available to the local client. While it is rare that this is an actual problem, many users and administrators prefer that IP address information is never actually revealed.
+ +DSPS never transmits IP address information across the XML stream, and so does not have this problem.
+ +PASS requires a client to initiate a connection by opening a (proxied) listening socket, and then soliciting connections. However, TCP works by having the client connect to a remote resource directly. This difference can make the operation of PASS difficult to understand. Also, it is left to the client to distribute the information about this listening socket, which places an additional burden on the client.
+ +DSPS, while it uses listening sockets to do its work, does all the work of setting up the connection after a client initiates it. All the initiating client has to do is request a connection, connect to the DSPS, and wait - everything else is handled automatically.
+ +Due to the master/slave design, DSPS is already able to handle multicasts of streams or such, whilst PASS was only designed for simple p2p stream connections. This will becoming increasingly more important as more emphasis is made on streaming capabilities, for technologies such as audio and video conferencing.
+ +Due to DSPS generality, the protocol can be easily used for either P2P or P2S2P needs. This eliminates the need for a separate protocol for each of the tasks.
+ +It is not mandated for DSPS to reside beside a Jabber server. It is entirely possible for any client to implement a stripped down version of such a server. In such a case the only sections that are required are any error reporting, invitation acknowledgment and statistical responses. Any other area of the protocol becomes optional since the recipient peer will not have the ability to use it anyway.
+ +Any client may, but is not required to utilize the striped down functionality. When utilizing such functionality the serving client sends an invitation to the recipient client to join the serving client's DSPS stream. Thus the "create" message would list the serving client as the DSPS and would utilize the "host" attribute to tell the recipient client where to connect to the DSPS.
+ +This ability is advantageous since the recipient client only needs to know one protocol for data transmission over P2P or P2S2P connections, and would not see a difference between the two. The proposed method is for one side to fist try serving a connection to the other. If that fails the other side may attempt to serve the connection. If the second attempt fails the clients may utilize an external DSPS server. The negotiation of who will serve is done outside DSPS protocol. DSPS has no functionality to decide when a P2P connection is possible or desirable, nor does it have enough information to do so reliably.
+ +This proposal standardizes the use of graphical emoticons and "genicons" in Jabber IM clients to prevent confusion and competing conventions that will soon arise, enabling client developers to spend their energy on more important parts of their projects.
+Emoticons are the text string 'smiley' or 'frowny' faces such as :-) and :-( that people often use in email or instant messaging to represent emotions. Genicons are a term being coined here to mean non-emotive text pictures (often called 'ASCII Art') that serve to replace typing the full word or to simply be cute or creative in the conversation.
+Many new Internet users demand graphical emoticon and genicon support in their IM clients. We should satisfy their needs if we ever wish to see them use Jabber instead of another IM system.
+While traditionally emoticons and genicons have been typed and displayed as text, the recent trend of using graphics, and sometimes sounds, instead of text to represent these pictures will be assumed for purposes of this proposal. Also, the term "icon" will be used in place of "emoticon" and "genicon" for purposes of convenience.
+The following issues must be solved for in this specification.
+-
+
- Here and Now: The convention should not rely on technologies such as feature negotiation or generic pub/sub which do not exist yet in Jabber in order to work properly. The convention should be a "here and now" solution, relying only on the current Jabber protocol. +
- Meaningful: The convention for creating the icons must be meaningful to users of clients without icon support, or even users on the other side of transports. Whatever method is used, it should not be cryptic or difficult to understand in text-only mode, in case the user does not have or want the capability to view the icons. +
- Component Friendly: In order for gateways, bots, and other "semi-intelligent" components to be able to convert or otherwise use the specification (such as to and from the MSN icon style, or use icons in conversations with Artificially Intelligent bots), a specific list of icons must be possible. Since these bots do not have an intelligent human behind them deciding their every action, they cannot deal with unlimited possibilities. +
- Protect Privacy: Sender-defined external data must not be required to properly display the icons because it can be used by the sender to track the user, circumventing their privacy. When the sender can define their own graphics or sounds to be used for the icons, they can use unique URLs and monitor when these unique URLs are accessed. External data may be allowed as long as it is not required for proper use of the icons, but it would be best to leave external data completely out of the system. +
- Conserve Bandwidth: The amount of markup used within the messages to define the icons should be kept to a minimum, as well as keeping the media files used for the icons from being transferred over the wire with the messages themselves. These easily consume too much bandwidth, a precious resource to most of the Internet. +
- Be Passive: The convention should not force transports or recipients to take any action to properly display the icons. Not only does it put extra strain on the components, but it would also unnecessarily break old clients. Transports and recieving clients may have the option of taking some actions, but they should not be forced to. +
- Internationalization: The convention must be inherently international in order to ease adoption of Jabber throughout the world and prevent later growing pains. The use of English must be kept to a minimum, restricted to "meta information" about the icons themselves, and must dynamically allow for non-English language sets. +
Because icons in Jabber should be easy to use, extensible, and customizable, they will be created using style definition files which can be exchanged between users and supporting clients. The specification will not allow external data, in order to protect the privacy of users, and will not rely on file transfers or directory services in order to not break old clients or components.
+To find out if an entity supports Jabber Icon Styles, look for the feature category of http://jabber.org/protocol/icon-styles using jabber:iq:browse or http://jabber.org/protocol/disco. The same feature category can be used with feature negotiation.
+Because icons in Jabber should be easy to use, extensible, and customizable, they will be created using style definition files which can be exchanged between users and supporting clients. The specification will not require external data, in order to protect the privacy of users, and will not rely on file transfers or directory services in order to not break old clients or components. How these icon styles are exchanged - as well as advertised - is out of the scope of this specification. The text strings representing the icons will be sent like any other text (this JEP doesn't require extra tags or attributes in the messages being sent).
+All icons are created by defining each icon then grouping them together into "Icon Definition Files". These files, along with the object files associated with the icons, are called "icon styles". Icon styles may be traded and shared among users of all supporting clients like skins or themes, similar to WinAmp, XMMS, GNOME, and other customizable applications. This creates a platform-independent system, providing a great degree of customization for the user, and allowing client developers to focus on other features.
+ +Each icon in a style is defined and grouped together in an XML document, the "Icon Definition File". Each definition file for all styles is named "icondef.xml". There is only one such Icon Definition File per style. The W3C Schema for the Icon Definition File plus an example finished Icon Definition File can be found under Schema, below.
+The meta elements contain information about the Icon Style itself, rather that the individual icons. They are contained within the <meta> element, which is directly under the root element. There is one and only one the <meta> element.
+-
+
- Name: This is an arbitrary text string (spaces allowed) which is the full name of the Icon Style. Only one name can be included. +
- Version: This is an arbitrary text string (no spaces allowed) which is the version number of the Icon Style. Any version format is allowed, but the major.minor or major.minor.trivial formats are recommended. Only one version can be included. +
- Description: This is the full description of the Icon Style. It summarizes the look and types of the icons, and can be used for keywords in searching. This is optional, but recommended. +
- Author: This is the full name of the author. Multiple authors are allowed. +
- Creation: This is the date of the creation of this version of the Icon Style. The date is in the ISO 8601 standard format. +
- Home: This is the full HTTP web address of the Icon Style's homepage. This is optional. +
The <text/> element defines what text string(s) are recognized by the client as an icon. There may be multiple <text/> elements in an <icon/>, such as for different languages or simply for multiple text strings producing the same result (for example: :-) and :))
+ +Each may have an xml:lang attribute, as defined in Section 2.12 in the official XML 1.0 reference document. The xml:lang attribute allows for two-letter language codes, dialects, and custom "languages" to define foreign IM protocols, for example.
+In order to be more accurate in recognizing text strings intended to be icons from those that are just coincidences in normal conversation, the client should follow the "whitespace rule" of making sure there is some form of whitespace on at least one side of the text string. This is only a guideline; individual clients can implement different rules as needed. A newline and tabs count as whitespace in addition to spaces. This is to make sure that chunks of code and URIs are not accidentally converted into graphical pictures. Also, text strings cannot include newlines or tabs. All characters must be on the same line with only spaces within the string, and extra spaces should not be ignored. This is to make it much easier on text parsers looking for these text strings.
+The text strings must be case sensitive. This is a rule that compliant clients must follow. "Cat" cannot be used in place of "cat" or "CAT". All three are separate text strings, and therefore must have separate <text/> elements, although they may of course use the same objects.
+The <object/> element defines what multimedia objects are inserted into the displayed message, replacing the text string(s) defined in <text/>. An object may be a bitmap graphic, vector graphic, audio clip, rich text formatting rules, or any other media that can be stored in a separate file. The <object/> element is identical to the OBJECT element used in XHTML 2.0, and the specification used there should be used to govern the <object/> element here. Note that because the XHTML 2.0 OBJECT specification is quite complex (although very flexible and future-proof), client developers are encouraged to only implement compliant sub-sets of the OBJECT specification for their clients. There may be one or multiple <object/> elements in an <icon/>, such as for alternative file formats (such as + GIF vs. PNG), or multiple objects to use at the same time (such as graphic and sound files).
+The <x/> element allows any type of extensions to the icondef.xml file, such as to specify how the user's nickname can be colored in multi-user chat windows or defining additional data about the style or authors. Each must have an xmlns attribute with a namespace that the extension operates under. Multiple <x/> elements may be in the <icon/> or <icondef/> elements. This functionality is optional for clients to support, and clients should ignore all extensions they do not understand.
+The icondef.xml file must all be located in the root directory, which is named after the style and version (example: ./happy_days-1.2 or ./gold_angelic-1.0.0). There is only one root directory per style. The object files may either be in the root directory as well, or be in sub-directories for categorization and easier maintenance reasons. If sub-directories are used, they must match the URIs used in the <object/> element in the icondef.xml file.
+ +The icondef.xml file and all object files must be packaged in the ZIP format following the above hierarchy (the directory must exist in the package, with all files in it). The package must have the file extension .jisp (Jabber Icon Style Package), and the MIME type application/vnd.jisp as defined in the official IANA registration. This allows Jabber clients to automatically install icon styles through web browsers. When the client installs the package, it should probably be kept in the archived format, instead of unzipped. This not only saves disk space, but also makes the packages easier to manage and exchange.
+Icons styles should be easy to create, distribute, and most importantly, use. The packaging and official MIME type helps with the first steps, but it is ultimately up to the client developers to fully support the specification and make sure it is easy for users to manage.
+ +The procedure for using Jabber icons is simple and straightforward.
+-
+
- The user installs and turns on ("activates") an icon style (using their client's GUI, most likely) they have received off the Internet or somewhere else. +
- The user selects the desired icon they wish to include in their message from their client's GUI (a drop-down list of installed icons, for example). +
- The client translates the selected icon into its main text string equivelent, which is found in the icon's <text> element. If there are multiple <text> elements, follow the procedure under "Text Strings", below. +
- The client sends the message with the text string to the intended recipient. +
- The recipient client receives the message with the text string. +
- If the recipient has an icon style activated that defines that text string, it is converted into the appropriate object. If there are multiple objects files for each icon, follow the procedure under "Object Files", below. If there are multiple icon styles installed which define that text string, follow the procedure under "Combining Styles", below. If the recipient does not have such an icon activated, then they simply see the text string without any changes. +
Because icons may have multiple text strings associated with them, clients need to be able to figure out which one to use when a user selects the desired icon from their GUI. This is ultimately completely up to the implementation, but here is a suggestion:
+-
+
- First look for any text strings that are the same language as what the user is using (if the user is using english, then look for English text strings, ignoring languages like German or Simplified Chinese). Optionally, if the client is smart enough, it can instead look for text strings in the language that the intended recipient is using (using Browse/Disco or simply keeping track of languages used in an ongoing conversation). The language for text strings is found in the xml:lang attribute for <text/> elements. +
- If there are no text strings that match the user's language, then look for one that has no defined language. +
- If there are multiple options even after the above steps, select the one that comes first in the <icon/> element. +
- If there are no text strings that are in the user's language or no language defined at all, then it is probably best for the client to not even display the icon as a choice at all. But if the client still wants to allow it, then simply select the text string of any language that comes first in the <icon/> element. +
Like multiple text strings, icons can have multiple object data files associated with them, and therefore clients also need to be able to figure out which ones to use when a user selects the desired icon from their GUI. Here is a suggestion of how those files can be chosen among multiple options, although this is completely an implementation issue (as with multiple text strings).
+-
+
- First look for any of these objects that are of MIME types the client can understand and use. For example, most clients could only use image/bmp and maybe audio/x-wav, but some newer clients may be able to support image/png, image/svg+xml and audio/x-ogg. +
- If there are still multiple object MIME types which the client can understand and use, then the client should rank the MIME types it can support, choosing its favorite. +
- If there are still multiple objects of the same MIME type, then the client should choose the first one in order in the <icon/> element. +
- If there are no files of any MIME type the client can understand, then it should ignore using any objects or even the entire icon. +
The Rules for processing objects in the XHTML 2.0 OBJECT specification may also be of help in coding the procedure of choosing an object to use, especially when it comes to nested and author-preferred objects.
+The client should also take note of the file sizes. The client should set (possibly as a user-defined option) the maximum file size in kilobytes for object files. Anything above this amount implies the file will be too big to properly render, and the icon style developer is probably being abusive.
+Also, if you are developing an icon style, please make sure the MIME types specified in your icondef.xml file are correct. And also make sure that the files you use are reasonable in any byte, pixel, and timelength size. And although any file format can be supported, try to use BMP, PNG, SVG, WAV, OGG formats because they are open, free, and becoming increasingly supported in developer tools and programming languages.
+A client may permit the user to activate multiple icon styles at one time. This would be useful for styles which make use of different text strings, and the user wants them all. The client should force the user to rank the multiple styles for purposes of conflict resolution between icons. The highest ranking style gets preference over lower ranking styles. This ranking doesn't have to be anything more than simply dragging the style names into top-to-bottom rows, with the styles on top being higher ranked than those below.
+Although any text string can be turned into an icon by defining it in an icondef.xml file, it is highly reccomended they either follow traditional ASCII Art (smileys and frownys, for example) or full keywords in simple markup such as double-colons. If you want to design icons, always keep in mind that not every Jabber user uses graphics to "translate" this to something visual, as explained in the "Meaningful" requirement, above. Here is a short list of recommended "core" icons that should be in most definitions, as well as possibly be used by transports:
+-
+
- :-) and :) - A smiling face. +
- :-( and :( - A frowing face. +
- ;-) and ;) - A winking smiling face. +
- :'-( and :'( - A crying face. +
- >:-( and >:( - An angry face. +
- :yes: - A thumbs-up or checkmark. +
- :no: - A thumbs-down or a crossmark. +
- :wait: - An open hand, palm outstretched. +
- @->-- and :rose: - A rose flower. +
- :telephone: - A telephone. +
- :email: - An electronic-looking envelope. +
- :jabber: - Jabber's lightbulb logo. +
- :cake: - A birthday cake. +
- :kiss: - A pair of puckered lips. +
- :heart: and :love: - A heart. +
- :brokenheart: - A broken heart. +
- :music: - A musical note or instrument. +
- :beer: - A beer mug. +
- :coffee: - A cup of coffee. +
- :money: - A gold coin. +
- :moon: - A moon. +
- :sun: - A sun. +
- :star: - A star. +
There are no security features or concerns related to this proposal.
+The JSF shall register and maintain a MIME type and file extension for icon style packages with the IANA. Ones have already been registered by Sebastiaan Deckers (aka 'CBAS') as application/vnd.jisp and .jisp, respectively. The registration can be found at http://www.iana.org/assignments/media-types/application/vnd.jisp. Sebastiaan's registration shall be considered the official MIME type and file extension of this specification.
+Also, this specification uses other MIME types that are maintained by IANA for the object and xml files that are included in the icon style packages.
+JANA shall register the namespace http://jabber.org/protocol/icon-styles as an official feature category.
+Also, JANA may choose to define IM-specific xml:lang "language codes" for use within Jabber (in addition to those defined in the XML specification). Such language codes would allow Jabber developers to support icons from MSN, Yahoo, and popular web message programs.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+ Gold Angelic
+ 1.0.0
+ Angelic faces and themes with gold highlights.
+ Adam Theo
+ Sebastiaan Deckers
+ Mattias Campe
+ 2002-10-31
+ http://icon-styles.jabberstudio.org/Gold_Angelic
+
+
+ :-)
+ :)
+
+
+
+
+ :-(
+ :(
+
+
+
+
+ :-O
+ :O
+
+
+
+ ::man::
+ ::mann::
+ ::muz::
+ (z)
+
+
+
+ ::woman::
+ (x)
+
+
+
+
+ ::alert::
+
+
+
+
+
+ ]]>
+ -
+
- This proposes a standard, simple, plaintext-based icon convention. It does not attempt to create a powerful XML-based convention wherein XML tags are used to extensibly represent the icons. However, this proposal isn't exclusive, and does not prevent such an XML-based convention from being created at a later date. It may also be possible to build such an extensible XML-based convention on top of this plaintext one. +
- The Icon Styles that the sender used to create the message may be of use to the recipient. A separate specification can be developed for the transferring of the name and version of the Icon Styles used by the sender. The recipient's client may then be smart enough to automatically use the same icons as the sender intended, possibly even fetching and downloading the icon styles as needed. This would likely require directory services, so has not been included in this proposal. +
- The functionality of the icondef.xml files may be useful for variable text strings. Text strings that may change from session to session, such as the user's nickname in a multi-user chat. A set of variables could be defined that represent these variable datas, therefore allowing them to be manipulated in the same way set text strings are. +
- This convention may be adopted beyond the scope of Jabber into web browsers, email clients, and Wiki sites. There is great potential for a generalized, exchangeable convention for emoticons and genicons. +
- A "SVG Transport" may be created to enable clients to send SVG icons to it and get back icons in another format of their choice, such as PNG or JPG. This would speed up the adoption of SVG within Jabber greatly. +
- An online Web- (or even Jabber-) based editor to create icon style packages from the individual components would be a great tool for developers. This would be a great project for JabberStudio or even the Ransom model. +
As things currently stand it is not possible to obtain statistics + from a jabber component or server without resorting to parsing the + various log files. This makes it extremely difficult to obtain statistics + that are of any use in real world situations. This JEP attempts to + rectify this situation by defining a new namespace that would be used + to obtain statistics from a component or server so that they may be + manipulated and used in a useful manner. For the purposes of this namespace + a statistic is anything that maybe expressed in a numeric form, such as the + uptime of a server, the number of registered users and the + number of packets sent. Things such as a list of currently online users or + a list of registered users are beyond the scope of this namespace and + properly belong within browse or disco.
+This is a pretty simple namespace. It consists of a <stat/> tag with + three attributes. name, units and value.
+
+ <query xmlns='http://jabber.org/protocol/stats'>
+ <stat name='' units='' value=''/>
+ </query>
+
+ There is one variation in the case of an error invalidating one or + more errors in a single returned query that does not actually + invalidate the whole query.
+
+ <query xmlns='http://jabber.org/protocol/stats'>
+ <stat name=''><error code=''>...</error></stat>
+ </query>
+
+ The name of the statistic. The format for this attribute is the
+ generic statistic type such as bandwidth, users, time etc. followed by
+ a '/' character and then then the name of the actual statistic. For
+ example bandwidth/packets-in, time/uptime and users/online. This will
+ be assigned and administered by JANA
This is the units type of the statistic. As with the name attribute it
+ will be assigned and administered by JANA
This is the actual returned value of the queried statistic. The value returned is in + multiples of the unit described by the units attribute.
+To query a component or server a client sends an iq packet of + the type 'get' to the component or server. The component or + server responds with the list of statistics that it supports.
+ +Once a client knows which statistics a component or server + supports it may now request the actual statistics by sending an iq + packet of the type 'get' containing a request for the specific + statistics and sending that to the component or server.
+ +If an error occurs with one or more of the requests for + statistics the component or server should return one of the + following error codes.
+| Code | String | Reason |
|---|---|---|
| 401 | Unauthorized | Querying JID is not + authorized to perform that query |
| 404 | Not Found | The statistic was not + found for some reason |
| 501 | Not Implemented | Although statistic + is advertised as available it has not been implemented |
| 503 | Service Unavailable | Statistic is + temporarily unavailable |
Because we wish to be able to collect groups of statistics + within a single returned packet errors must be handled in a two + tier way with authorization and core errors that would render + all the statistics meaningless being indicated + with a type='error' in the returned packet.
+ +Errors in a query that only invalidate one or more of the + requested statistics are indicated with an </error> tag + embedded inside the </stat> tag. +
+ +All statistic names, returned data units types and other + pertinent statistic information will be assigned and registered with + the Jabber Naming Authority in the category stat. + Unfortunately at this time such a body does not exist so we will + have to rely on component and server authors diligently + researching to ensure that their desired name is not already + in use and that they adequately document the returned units + type and anything else that would normally be registered. + Hopefully by the time this JEP is formally adopted + a central naming authority for the Jabber protocol will be in + place and functional and authors will be then able to register + their names. +
+| Stat | Description | Returned Units | +
|---|---|---|
| registered name | description of + statistic/reason | unit type returned by + query | +
+ Although components and servers are free to support whichever statistics they + feel are justified for their particular component or server it is + suggested that the following set of three core statistics are + implemented by all components and servers.
+ +-
+
- <stat name='time/uptime'/> +
- <stat name='bandwidth/packets-in'/> +
- <stat name='bandwidth/packets-out'/> +
| Stat | Description | Returned Units | +
|---|---|---|
| time/uptime | uptime of component or + server | Seconds | +
| bandwidth/packets-in | packets received by component or server | packets | +
| bandwidth/packets-out | packets transmitted by component or server | packets | +
For several reasons the + http://jabber.org/protocol/stats namespace does not + support human readable labels for the returned values. Generally the + application querying the statistic should already know what the + statistic is and in what units the value is returned. However if the + application really wants some form of human readable label for the + returned value although not an optimal solution or even recommended by + the authors of this JEP it should be safe for + it to convert the value of the units attribute into a string and use + that as a label for the returned statistic value.
+In most cases the http://jabber.org/protocol/stats would be tied to the component or + servers admin JID so that only that JID may query the statistics + however there are advantages to having a three tier system where + some statistics are available to all JIDs, some to an arbitrary + JID listed in the configuration file and all available to the + listed admin JID. As the first case can be emulated by the + second I propose that when implemented the http://jabber.org/protocol/stats + namespace is configured to use the three tier method of + authorizing queries.
+Supporting industry accepted standards and procedures
+
Note: This JEP has been superseded by &jep0060;; please refer to that document for the successor protocol.
+This document introduces and lays out a preliminary protocol for a robust form of publish-subscribe over the Jabber messaging environment -- Jabber Robust Publish Subscribe (JRPS).
+Implementation issues in the environment are appended, covering Permissioning and Contributions. Both are likely to require separate JEPs, but need to be constructed sympathetically.
+In creating this addition, I have an underlying philosophy to sustain a "fractal" world of publish-subscribe components, such that a subscriber to a pubsub component may well be a pubsub component in itself, representing its own community of subscribers. This will allow Jabber to support organic scalability found on other platforms.
+Publish-Subscribe and other messaging environments that exist are often classified as providing one or more of the following three levels of service.
+-
+
- Best Try, where data may on rare occasions get lost. Small footprints and ultimate performance are the aim where the impact of occasional data loss in business, legal, confidential or other terms is not significant compared with the core priority of performance. +
- Robust, where non-delivery of data can be detected and recovered by recipients and that the sequence, integrity and completeness of data can be ascertained with a high level of confidence. Non-delivery of data would have a significant and lasting negative impact on the quality and integrity of the data. +
- Transactional, where there is an absolute, mission-critical need to ensure that all communication flow is guaranteed and if problems occur during a set of connected steps, then the situation can be rolled back (reversed) to the state before the operation commenced. +
This document concerns itself with level 2 Publish Subscribe -- "Robust".
+JRPS is required in environments where there is a higher demand for guaranteed delivery in high throughput, low latency environments where data has value and can contain business intelligence, but does not demand a full transactional (e.g. 2-phase commit) strength environment.
+Such environments often exercise business logic upon data received, so the notion of updates to all or part of data, the expression of the definitive, full compliment of a particular set of related data, the correction of data in full or in part and the notification that data is no longer valid needs to be supported. The existing type="set", though very suitable in a wide range of applications, does not provide suitable granularity in all environments.
+Robust environments require that a receiver can tell when data has been lost and that a receiver also has the means to request the repair of any gaps efficiently. This must be done whilst keeping delay or disruption to ongoing data flow to a minimum. Jabber does not provide the means to detect or repair gaps, and traditional ACKing of each packet is slow and costly.
+It would be advantageous to permit forms of permissioning and access control upon data that has value. Such permissioning and control should not be overly burdensome on the rapid transmission of data. It should allow a suitable level of abstraction to keep changes to a data item"s expression of permission coding/level to a minimum, to avoid the need for excessive changes to such codes. Abstraction will also permit permission coding to be kept compact, as it will, in effect, be tokenised.
+JRPS then requires the ability to detect and repair gaps in the stream, to provide a means to convey richer information about the nature of the data in context to what has come before and to enable the publisher to have control over who sees what.
+In addition, a pubsub component should be able to provide information and parameters about its implementation of JRPS to subscribers. Subscribers must inquire about such information from the pubsub component to gain the full benefit of a JRPS service.
+-
+
- Identify the tasks that users can't complete because we are lacking this crucial piece of protocol. (Note: users are not just IM users, but any person, system, or application that could gain value from interacting with Jabber.) +
- Discuss other projects or protocols and how Jabber could interface with them because of your proposed protocol enhancement (e.g., XML-RPC, SOAP, DotGNU). +
- Compare Jabber to "the competition" (other IM systems or other messaging protocols) and point out holes in the Jabber protocol that need to be filled in order to offer similar functionality. +
- Review the relevant history of thinking within the Jabber community. +
JRPS is a layer on Jabber Publish-Subscribe (JEP0024, JEP0036) and should interoperate with them and support namespaces and topics. Included in this document is the capability for permission tokens. It is included as the author believes that such tokens should exist within the <publish> tag, being a means to identify data much as the namespace or topic does.
+JRPS is different from other IM systems in that the publisher and pubsub components send out the data so that downstream entities can detect if problems occur. As a comparison, a sender in, say, MSN is told that the packet they sent cannot be delivered but in JRPS, the receiver knows that a packet or packets have not been delivered and can ask for retransmissions. The sender need not normally know about such events as the intermediate components can usually cater for it. Thus JRPS has a future in areas such as Multicasting, large distributed and proxy-based environments where the end subscribers may be very remote from the publisher.
+Existing commercial middlewares provide such facilities and it is especially necessary when data is pushed between applications and may not have an obvious "context" in the stream to data immediately before or after. Thus, JRPS may seem over-the-top for a chatroom world, but is a basic requirement for, say, distributing real-time process states, events or persistent, mutable data.
+This can be achieved by the use of packet sequence numbering and heartbeats whilst avoiding the necessity to positively ACK each packet.
+Multiple levels of sequence numbers are envisaged and will be used in different circumstances. Multiple levels allow a rapid repair of short "transient" breaks whilst catering for longer breaks, recoveries and resynchronisations without placing too great a burden on either subscriber or pubsub component. This discussion explains the use of a dual sequence number environment: link and source.
+Sequence numbers will be sent in each publish thus:
+The above shows sequence numbers placed in the <publish/> node or element. This is to abstract the publishing from any packet construction algorithms that may occur and thus allow a recovery to make use of network capacity as it sees fit and to interleave recovery and ongoing publishing data.
+The subscriber stub is responsible for ordering information and detecting and repairing any gaps to provide sequential data for consumption by the application, which should not concern itself with such issues.
+The operation of LINK and SOURCE sequence numbers are described below.
+This will concern itself with data sent on each channel. A +channel can be, but is not limited to the following:
+-
+
- Socket connection between Subscriber (and/or resource within same) and the Jabber pubsub component. +
- Multicast datastream sent from a pubsub component but shared amongst 0..n subscribers. +
Each publish received should contain an incremental sequence number to the previous or Zero. Zero is used to reset (or resynchronise) the sequence numbering. Zero should not be used in the situation of sequence number wrapping/rollover, wherein the value1 should be used. Sequence numbering bit resolution should be ascertained by querying the pubsub component in an <iq/> before subscription requests are levied.
+E.g., in a 16-bit sequence number resolution channel, the sequence numbers would run as follows
+1, 2, 3, 65533, 65534, 65535, 1, 2,
+For information on sequence number bit resolution, see section 4, Source Queries.
+This will indicate the sequence number of messages sent from the publisher to the pubsub component. Should a link be lost, timeout or other such eventuality where the context of link sequence number be lost (e.g. the pubsub component decides the subscriber has disappeared and discards context), the pubsub component is still in a position to re-filter and retransmit data cached locally or even refer back to its source to maintain integrity and temporal ordering of data to the subscriber.
+To repair larger gaps, the pubsub component may provide the capability to request upwards to the source using the source sequence number, or the pubsub component may draw upon local or remote journaling services to repair the gap. The source sequence number seen by the subscriber may be the link level sequence number between publisher and pubsub component, may be the ultimate publisher sequence number or even an internal sequence number given to the incoming published data to the pubsub component on a per source basis.
+The subscriber need not know how the source sequencing operates, only notify from when the link last gave a contiguous datastream.
+One can now see that the pubsub component's conversation to the source is akin to that of a subscriber to a pubsub component.
+When a subscriber detects a gap on its link, it can request for the data to be resent thus:
+The values represent the missed link sequence numbers. For a gap of 1, the linkfrom and linkto are the same.
+Should the pubsub have lost the link context and thus is unable to plug the gaps it will return an error <iq/> packet.
+All is not lost. The subscriber has a last-ditch repair scenario by sending last-received source sequence numbers.
+Due to the non-contiguous nature of source sequence numbers from the subscriber point of view, the values sent must represent not the gap, but the last valid sequence number received. Each source may have a separate sequence number stream. This allows the pubsub component to manage and, if necessary, request gaps itself from the publisher to resynchronise the subscriber. The pubsub or publishing source should have the ability to refuse a rebuild/resynchronise.
+It should be possible for the subscriber to send the link and source sequence numbers in the initial request. However, if link information has been discarded by the pubsub component (e.g. the connection was dropped and presence set offline) the link sequence numbers will be reset to zero (re-synchronised) thus:
+During times of low traffic, an active circuit can be provided with regular heartbeat transmissions. Heartbeats will increment the link level sequence numbers. Subscribers missing or detecting overdue heartbeats will thus be able to detect gaps or delays even in low traffic scenarios. If the data is simply delayed, the subscriber stub is in a position to take action (and/or alert the application/user). If data is lost or heartbeats do not arrive in time, the subscriber can decide to request retransmission, disconnect or wait.
+No source sequence numbering exists here, as it is purely a link-level entity.
+To be able to interpret published data in a more logical manner, more meaning needs to be given to data received.
+When a publish packet arrives with a topic or data namespace, there is currently no way of knowing how to interpret the tags therein. Do they replace existing tag values seen? Should previously sent tags that are not in the publish be kept or discarded? Are tag values being updated or was the previous value incorrect?
+To resolve this a type field may be added to the <publish/> tag.
+This option is preferable to extending the <iq/> type field as there will then be no need to split <iq/> packets if <publish/> elements have different types.
+The following extensions would be used in environments where topic/namespaces define discrete sets of data items and/or data items changing over time, as opposed to only referring to a topic datastream consisting of atomic, unrelated data. Other types can be defined as the need arises.
+'update' - partial update of data. Replaces the values of the fields of the topic/namespace it contains. Other fields held/cached downstream for this data item are still valid.
+'correction' - previous data for contained fields was incorrect - e.g. paragraph in a news story, but, as per update, unsent items are still valid.
+'image' - payload contains ALL the data for a data item/topic/namespace. All existing values should be dropped and replaced with the new data. Previously received fields not now contained within the image should be discarded.
+'drop' - namespace/topic item is now dead and all data in it should be deleted and purged from cache.
+'snapshot' - requested by subscriber and is a request for data (an image if empty of granular topics/namespaces) and no further updates, as distinct from a get, which is an on-going subscription in pubsub world.
+'add' - new topic/data item on publisher's feed. Note that an "image" publish for an item can be interpreted in the same way. Previous systems have had the ADD mechanism, but use of "add" has been discontinued, with the role taken up by the "image". (thoughts?)
+The above states (except "add") are very important for downstream caches and for applications that apply business logic to the datastreams.
+As touched on above, subscribers should be able to enquire of the publisher regarding what capabilities it provides and what to expect. Some items of use for JRPS are as follows:
+-
+
- Heartbeat. Integer milliseconds. Represents the interval between heartbeat messages. Useful for rapid detection of link level problems. +
- Link Sequence Resolution. Integer. Allows subscriber to predict link sequence number rollover. Zero would indicate that it is not supported. +
- Source Sequence Resolution. Integer. Allows a subscriber to predict source sequence number rollover. A zero would indicate that it is not supported. +
- Gap Support. Boolean. Used to indicate if the publisher supports gap filling. +
- Permissioning Scheme. There may be some standardisation of permissioning schemes so that common plugins or mechanisms can be adopted. The publisher should be able to define this. +
- Rebuild On Demand. If the pubsub can support a rebuild/refresh of the current values of all subscribed-to data on demand. +
- Refresh Cycle. It has been common practice to transmit a regular refresh cycle for all subscribed data. If a data item does not get an 'image' from the source for a period of time, the cache performs a logical 'drop'. Without this, intermediate caches would very soon balloon with stale data, or publishers would get every cache re-requesting or confirming if data is still alive. Zero would indicate that no refresh cycle exists for the source. +
Permissioning protocols should be open to permit a multitude of permissioning schemas. Data providers may wish to enforce their schemes in ways that suit their particular business models. The protocol should not bind or dictate such mechanisms.
+The implementation of permissioning systems and regimes over time has repeatedly shown that it is especially dangerous to assume the behaviour of data and to disregard how information is used, protected, valued and owned or to force a scheme that is rigid and assumes a narrow problem domain. Thus the scheme should permit explicit and tokenised permissioning mechanisms.
+Tokenised permissioning allows sets of data can be treated en masse. By permitting the concept of "grant" and "deny" permissions simultaneously (settings that define who CAN see something or defining who CANNOT) individual publishers can manage access both broadly and down to very fine granularity.
+Permission tokens, if used, should be sent in-band with the data. This will allow data to change its coding online and thus immediately affect permissioning without a redistribution of the permissioning information.
+This does not prevent namespace/topic permissioning systems from being applied, nor should the permtoken be compulsory1.
+The pubsub systems should be able to <iq/> the publisher for the permissioning regime that applies.
+The definition of the XML carrying permissioning tables/information should be regime specific.
+Further information on why tokenised grant and deny permissioning is advantageous can be provided upon request.
Contributions in this context are when a subscriber publishes to one or more sources for redistribution so that it may reach the communities that subscribe to that source. By doing this, the subscriber reaches large communities, focus on specific communities and can abstract itself from delivery issues. The publisher gains information and broadens its appeal. Delivery abstraction is valuable, as a subscriber can then connect once to the publisher to gain access to all systems, networks, technologies, subscribers and media that the publisher and contributor agree upon. As you may guess, there is a need for content, flow control/throttling and ongoing permissioning to be specified and handled over time.
+Contributions requires a separate JEP, but the issues are important to the implementation of pubsub and of its permissions (Contributors have specific, complex and business-critical reasons to tightly control who sees data -- e.g. only customers, not competition!)
+Reliable Entity Link (or simply 'REL'), is a system for coordinating reliable bytestreams between two Jabber entities for the purpose of keeping applications (and application specifications) simple. However, this proposal does not define any specific bytestream protocol. It is expected that there will be multiple ways to obtain a bytestream between Jabber entities (thru-server and peer-to-peer are two methods that come to mind), but applications can refer to REL instead of some particular stream transport.
+A REL-compatible stream transport must have the following properties:
+-
+
- Provides a reliable bytestream between two Jabber entities, which means that the bytestream transport handles all data delivery issues, such that the application need not worry about them. +
- Has a the following link states:
+
+
++ +Code +Description ++ +INIT +Initiation ++ +GOOD +Successful initiation (connected) ++ +BAD +Unsuccessful initiation (stream is closed, no further state) ++ +CLOS +Successful closure after establishment (stream is closed, no further state) ++ +ERR +Link failure after establishment (stream is closed, no further state) +
+ - Defines a stream identifier, which MUST have a unique ASCII representation. The stream protocol MUST be able to use any ASCII identifier chosen during REL negotiation, as long as the sending party doesn't use the same identifier more than once. +
The following stream transports that meet these guidelines are:
+| Short name | +Protocol | +
|---|---|
| ibb | +&jep0047; | +
| s5b | +&jep0065; | +
Before using REL, ensure it is a supported service of the remote entity by using &jep0030;:
+ +To use REL, the entities must obtain a REL Context ID (or cid) through some action. A cid is simply an opaque alphanumeric string. For example, perhaps the link is needed for a file transfer:
+ +All high-level protocols that use Reliable Entity Link MUST have a way of providing such a cid. The cid must be unique among all other REL cids between the two entities.
+The next step is to ask the remote entity which stream method it would like to use. We will use &jep0020; for this. The streams are listed using the short names from the table of supported streams.
+ +The keepAlive attribute indicates that the initiator is planning on trying another method if the one selected here is to fail. An entity SHOULD use keepAlive for all attempts but the last for a given application. If keepAlive is omitted, then it is considered false.
+ +The remote entity will then agree on a method:
+Or maybe an error:
+If the entity returns error, then the REL cid is invalidated and the application fails. If a stream method has been chosen successfully, then now it must be initiated using the REL cid as the stream's identifier (the stream goes into INIT state).
+ +On GOOD: This indicates the stream is ready for use within the original context, and data exchanged over the stream is to be left up to the application.
+ +On BAD: If the keepAlive="true" attribute was specified, then the initiator MUST repeat this section over again to attempt with a different method. If keepAlive was not specified, then the REL cid is invalidated and the application fails.
+ +On CLOS or ERR, the REL cid is invalidated.
+There are no security considerations.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; shall register the 'http://jabber.org/protocol/rel' namespace as a result of this JEP.
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Distributing data out-of-band (OOB) to one or more end-points is a requirement for many Jabber clients. The Jabber OOB Broadcast Service (JOBS) is a mechanism to allow end-points to open uni-directional data streams between each other, on top of which any number of applications can be built
The aim of this JEP is to define a process of connecting a sender to one or more receivers through a secondary TCP port.
+As the name implies, JOBS is designed to enable multicast, uni-directional OOB connections. These connections are usually between a "sender" client, a JOBS "service", and one or more "receiver" clients. Each such set of connections is collectively called a session. JOBS is designed to allow a single service to handle multiple sessions over a single host/port combination.
+ +To address a large number of typical uses efficiently, JOBS can multicast the data from a sender to multiple receivers. In order to keep the protcol as simple as possible, it only allows data to flow in one direction.
+ +JOBS utilizes a "two-band" authentication mechanism. This allows the end-points to know practically nothing about each other, yet still be assured that the OOB connection is really to/from the Jabber entity its intended to be. The authentication system is then backed-up with explicit authorization requests.
+ +For the OOB portion, clients connect to the host/address and port of the JOBS service for a given session. Once connected, a client-initiated handshake process occurs, and (if successful), then data is routed from the sender's connection to each receiver's connection. The only point at which any error information may be conveyed over the OOB connection is during the handshake process.
+ +| Term | +Description | +
|---|---|
| OOB | +Out-Of-Band. Any network connection that exists outside of the normal Jabber protocol traffic. | +
| session | +A session registered with a "server" for clients to connect to. | +
| client | +An end-point on a JOBS session. | +
| service | +The JOBS Jabber component/server. | +
| server | +A particular host/port of the JOBS service. | +
| sender | +The client sending data. | +
| receiver | +A client receiving data. | +
Discovering support for JOBS involves either "jabber:iq:browse"
To determine support for JOBS via jabber:iq:browse, look for an item with a nested <ns/> with a value of "http://jabber.org/protocol/jobs":
+The JOBS protocol supports various scenarios to create sessions. Most of these scenarios allow an entity to determine the possible parameters to create a session with. To actually create a session, the (would-be) sender sends an "iq-set" with a <session action="create"/>. This returns the details of the newly created session, including the ID and OOB host/port.
+ +This use-case can be completely ignored for true "peer-to-peer" systems.
+ +The simplest create request is:
+ +This creates a session between sender@domain/resource and any one receiver. At this point, the JOBS service is ready to accept connections for this session. The <session/> element describes the details for the session. The value returned in the "id" attribute is the JOBS session ID
When creating a session, parameters to <session/> can be supplied, explicitly requesting that certain parameters be met (such as buffer size, time to expire, and receiver limit). Since these parameters have lower- and upper-bounds specific to the JOBS service, a sender may need to determine these limits.
+ +To determine the limits, the sender sends an "iq-get" with a <session action="create"/>:
+ +The returned <session/> is also prefilled with default values for all known parameters.
+ +To create a session with specific parameters, the sender sends an "iq-set" as in the "simple" use-case, but then specifying the parameter values desired:
+The above example creates a session that does not timeout. A JOBS service uses values from the default information set for any parameters that are missing.
+ +Any parameters that exceed the minimums/maximums causes an error.
+In some cases, the session creation process requires an interface more suitable for human consumption. In such cases the JOBS protocol helps by allowing for contained elements governed by other namespaces. For form-based creation, a "jabber:x:data" form
To create a session using forms, send a <session action="create"/> with an embedded <x xmlns="jabber:x:data"/>:
+ +The exact fields present in the form are dependent upon the JOBS implementation. The form SHOULD allow a user to at least specify the <session/> attributes.
+Using the form-based approach, the session is then created by sending a <session action='create'/> with a form submission (as defined for "jabber:x:data"):
+ +Once the session is created, the sender invites receivers to connect. The sender can invite receivers either directly, or via the JOBS service. Most invitations are distributed via <message/>.
+ +The sender can invite receivers directly. This is done using a <message/>:
+When inviting directly, the <session/> MUST contain enough information for a receiver to connect OOB. The required information is:
+-
+
- host +
- id +
- port +
Alternatively, a sender can invite receivers via the JOBS service. This is also done using a <message/>, with a <session action="notify"/> containing one or more <item action="invite" type="connection"/>:
+This results in the JOBS service sending the <message/> to each <item/>. Any additional elements (such as a <body/>) are passed onto those invited:
+At any time, a client can request information about sessions for a JOBS service. The request can be directed for "all" sessions, or a specific session
A client can request all the sessions for a JOBS service by sending an "iq-get" containing a <session action="info"/> with no ID:
+The JOBS service responds with all the sessions within the "iq-result". This is the only case where a result can have more than one <session/>.
+Alternatively, a client can request the information for a specific session by sending an "iq-get" containing a <session action="info"/> with the ID:
+The service responds with an "iq-result" of just the requested session.
+When a client connects (sender or receivers), a client-initiated handshake takes place. The purpose of this handshake is to authenticate the OOB connection, in relation to the client's JID. This authentication utilizes both in-band and OOB packets.
+ +To start the handshake, the client sends an "init" packet on its established connection:
+ +If the session exists, and the client's JID is not automatically rejected, the JOBS service responds with an auth-challenge packet, containing an unique, arbitrary token:
+ +Once received, the client then sends an "iq-set" containing a <session action="authenticate"/>, which itself contains an <item type='auth' action='confirm'/> with this confirm key:
+ +The service then compares this confirm key to that sent with the "auth-challenge" OOB packet. If this matches correctly, and the service determines this connection is authorized, the session will respond with a <session action="authenticate"/> containing a <item type="auth" action="accept"/> with the accept key:
+ +At this point, the client responds on the OOB data stream with an "auth-response" packet:
+ +If the connection is accepted, the JOBS service sends a "connected" packet:
+ +and after this, the data transfer occurs. If this connection is the sender, they may start sending data now (regardless if receivers are connected). If this connection is a receiver, the sender's data immediately follows the terminating "newline".
+Authenticating ensures the OOB connection matches a particular JID. Authorizing ensures to the service that receiver is allowed to be connected to the session. To determine if the session connection should be accepted or rejected, the JOBS service first checks if the JID matches the sender. This matches against the "full" JID, including node, domain, and resource. If this connection is the sender, it is allowed. Otherwise, the service confirms the connection with the sender.
+ +If a confirmation is required, the service sends an "iq-get" to the sender, with a <session action="authorize"/> containing an <item type"connection" action="confirm"/> with the full JID of the receiver:
+ +One or more <item type="connection" action="confirm/> elements, each specifying a JID to accept/reject. To accept (or reject) a connection, the sender responds with an "iq-result", wrapping each JID in either an <item type="connection" action="accept"/> or <item type="connection" action="reject"/>.
+ +If the connection is rejected, the service drops the connection, and notifies the sender and receiver of the dropped connection.
+The sender may drop a connection at any time. To drop a connection, the sender sends an "iq-set" with the <session/> containing the "connection" to drop:
+ +If the connection is successfully dropped, the service returns an "iq-result":
+ +The service also sends notification messages to the sender and the JID of the dropped connection (detailed in the "Being Notified about Events" section).
+Sessions are deleted either by timeout or explicitly. Sessions are deleted by timeout automatically under certain conditions. Sessions can also be deleted explicity by their senders, at any time. Regardless of the method of deletion, a notice is sent to all connected.
+ +This use-case can be completely ignored for true "peer-to-peer" systems.
+The exact conditions that expire a session are mostly up to the implementation. At a minimum, a session SHOULD be expired when there are less than two connections, and the "expires" time is reached.
+To explictly delete a session, the sender sends an "iq-set" containing a <session action="delete"/>:
+ +When a connection is accepted, the service sends a "notify" message to the sender and (if appropriate) the accepted receiver, with a <item type='connection' action='accept'/>:
+ +If the notification is not about the recipient of the message, then the <item/> contains the JID this notification pertains to.
+When a connection is rejected, the service sends a "notify" message to the sender and (if appropriate) the accepted receiver, with a <item type='connection' action='reject'/>:
+ +If the notification is not about the recipient of the message, then the <item/> contains the JID this notification pertains to.
+When a connection is dropped, the service sends a "notify" message to the sender and (if appropriate) the accepted receiver, with a <item type='connection' action='drop'/>:
+ +If the notification is not about the recipient of the message, then the <item/> contains the JID this notification pertains to.
+When a session is deleted, any clients connected to the session are immediately disconnected. The "notify" message is sent to the sender and any receivers still connected, with the <session action="notify"/> containing an <item type="status"/>:
+ +The reason the session is deleted is specified by the action attribute. A value of "delete" means it was explicitly deleted. A value of "expire" means it timed out.
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+ The <session/> element is the core element to the protocol. This element provides both information about a session and the action applied to it. It has a large number of attributes, and contains zero or more <item/> elements, zero or more <connect/> elements, and zero or three <limit/> elements. It may also contain elements governed by other namespaces.
+The "action" attribute specifies the action to apply or being applied to the session. From clients, this attribute MUST be specified. From the service this attribute MAY be specified (to prevent ambiguity). The value of "action" MUST be one of the following:
+| Value | +Description | +
|---|---|
| authenticate | +Authenticating one or more connections. | +
| authorize | +Authorizing one or more connections. | +
| create | +Create a new session. | +
| delete | +Delete an existing session. | +
| notify | +Notification about the session. | +
The "status" attribute specifies the current status of the session. This attribute MUST NOT be present if the session does not have an identifier (i.e. does not yet exist). Only the service can provide this attribute. The value of "status" MUST be one of the following:
+| Value | +Description | +
|---|---|
| active | +The session is active, but not yet in use. | +
| closed | +The session has closed. | +
| in-use | +The session is in use (e.g. data is being transferred). | +
| pending | +The session is ready, but not yet active (e.g. not enough connections). | +
The "host" attribute specifies the OOB hostname for the session. This attribute SHOULD be specified when possible. The value of this attribute can either be the "raw" dotted-decimal address or a fully-qualified domain name.
+The "id" attribute identifies the session. This attribute is required for all uses of <session/> except the request to create a session. This value is any string that the service and clients can use to uniquely identify it.
+The "port" attribute specifies the OOB port number for the session. This attribute SHOULD be specified when possible.
+The "sender" attribute specifies the JID of the sender. This attribute SHOULD be specified when possible. The value of this attribute MUST be the full JID of the sender, including node and resource (if possible).
+The "buffer" attribute specifies the size of a temporary transfer buffer. This attribute MAY be present at any time, and SHOULD be presented by the service wherever possible. The value of this attribute MUST be a non-negative number. A value of 0 means there is no buffer. This value has limits defined by the "jobs:buffer" parameter statistic.
+The "expires" attribute specifies the number of seconds before this session times out. This attribute MAY be present at any time, and SHOULD be presented by the service wherever possible. The value of this attribute MUST be either a positive number or -1. A value of -1 means this session does not expire. This value has limits defined by the "jobs:expires" parameter statistic.
+The "receivers" attribute specifies the maximum number of receivers this session can have. this attribute MAY be present at any time, and SHOULD be presented by the service wherever possible. The value of this attribute MUST be either a positive number of -1. A value of -1 means this session can (theoretically) have any number of receivers. This value has limits defined by the "jobs:receivers" parameter statistic.
+The <item/> element is used for detailed information about specific items of a session. It is used to contain authentication keys, to define connections, and provide more detailed status for a session. It has attributes for the type of item and the action associated with this item. This element contains only character data.
+The "action" attribute specifies the action to apply or being applied to this item. From clients, this attribute SHOULD be specified. From the service, this attribute MUST be specified (to prevent ambiguity). The value of "action" MUST be one of the following:
+| Value | +Description | +Notes | +
|---|---|---|
| accept | +The item is accepted. | +This value MUST only be used when the type is "auth" or "connection". | +
| confirm | +The item needs confirmation. | +This value MUST only be used when the type is "auth" or "connection". | +
| delete | +The item is deleted. | +This value MUST only be used when the type is "status". | +
| drop | +The item is dropped. | +This value MUST only be used when the type is "connection". | +
| expire | +The item has expired. | +This value MUST only be used when the type is "status". | +
| invite | +The item is invited to the session. | +This value MUST only be used when the type is "connection". | +
| reject | +The item is rejected. | +This value MUST only be used when the type is "auth" or "connection". | +
The "type" attribute specifies the type of item. This attribute MUST be present. The value of "type" MUST be one of the following:
+| Value | +Description | +
|---|---|
| auth | +The item pertains to authentication keys. | +
| connection | +The item details a session connection. The CDATA is the JID that is connected. | +
| status | +The item details a session status event. | +
The <connect/> element specifies a valid host/port combination for a session. An instance of this element MUST be present for each host/port combination possible. This element SHOULD only be present when information on creating sessions is requested. It has attributes to define the OOB hostname and port number. This element is empty.
+The "host" attribute specifies the OOB hostname. This attribute MUST be present. The value is either the "raw" dotted-decimal IP address, or the fully-qualified domain name.
+The "port" attribute specifies the OOB port number. This attribute MUST be present. The value MUST be a positive integer in the range (0 < port <= 1024).
+The <limit/> element specifies a valid host/port combination for a session. An instance of this element MUST be present for each "type". This element SHOULD only be present when information on creating sessions is requested. It has attributes to define the type of limit, the default value, the minimum value, and the maximum value. This element is empty.
+The "type" attribute specifies the type of limit. This attribute MUST be present. Each type corresponds to an attribute of <session/>. The value of "type" MUST be one of the following:
+| Value | +Description | +
|---|---|
| buffer | +The buffer size limits. The units for "default", "max", and "min" are bytes. | +
| expires | +The expires time limits. The units for "default", "max", and "min" are seconds. | +
| receivers | +The receiver count limits. The units for "default", "max", and "min" are number of connections. | +
The "default" attribute specifies the default value for this limit. This attribute MUST be present. The value of "default" MUST be a number.
+The "max" attribute specifies the maximum value for this limit. This attribute MUST be present. The value of "max" MUST be a number. A value of -1 means there is no maximum value.
+The "min" attribute specifies the minimum value for this limit. This attribute MUST be present. The value of "min" MUST be a number. A value of -1 means there is no minimum value.
+| Code | +Message | +Cause | +
|---|---|---|
| 400 | +Bad Request | +The JOBS service did not understand the request. | +
| 403 | +Forbidden | +The JOBS service cannot accept the authentication request from the requesting JID. | +
| 404 | +Not Found | +The JOBS service could not find the given session. | +
| 406 | +Not Acceptable | +The authentication is not valid. | +
| Code | +Message | +Cause | +
|---|---|---|
| 400 | +Bad Request | +The JOBS service did not understand the request. | +
| 403 | +Forbidden | +The JOBS service cannot accept the authorization request from the requesting JID. | +
| 404 | +Not Found | +The JOBS service could not find the given session. | +
| 406 | +Not Acceptable | +The authorization is not valid. | +
| Code | +Message | +Cause | +
|---|---|---|
| 400 | +Bad Request | +The JOBS service did not understand the request. | +
| 403 | +Forbidden | +The JOBS service cannot accept any creation requests from this JID. | +
| 406 | +Server Not Acceptable | +The JOBS service cannot accept any creation requests using the requested <server/> parameters. | +
| 406 | +Restrictions Not Acceptable | +The JOBS service cannot accept any creation requests using the requested <accept/>, <confirm/>, and/or <reject/> parameters. | +
| 503 | +Service Unavailable | +The JOBS service cannot accept any additional sessions at this time. Future requests may be accepted. | +
| Code | +Message | +Cause | +
|---|---|---|
| 400 | +Bad Request | +The JOBS service did not understand the request. | +
| 403 | +Forbidden | +The JOBS service cannot accept deletion requests from the requesting JID. | +
| 404 | +Not Found | +The JOBS service could not find a given session. | +
| Code | +Message | +Cause | +
|---|---|---|
| 400 | +Bad Request | +The JOBS service did not understand the request. | +
| 403 | +Forbidden | +The JOBS service denied the connection for any reason. | +
| 404 | +Not Found | +The JOBS service could not find a given connection and/or JID. | +
| 406 | +Not Acceptable | +The JOBS service denied the notify for some reason. | +
| 504 | +Remote Server Timeout | +The JOBS connection timed out. | +
The OOB protocol consists of a series of hanshaking headers, then the normal data transfer process. The syntax of the hanshake packets is similar to HTTP and SIP, in that it includes a "version and method" line, followed by zero or more "headers". The end of a packet is marked by two adjacent carriage returns (i.e. a single "empty" line). The primary difference is with the first line ("version and method"), where the protocol name and version precede the method.
+
+OCTET :=
+CTL :=
+UALPHA :=
+LALPHA :=
+DIGIT :=
+SP :=
+CR :=
+LF :=
+BINDATA :=
+ ]]> | Comand-line (example) | +jobs/0.4 init |
+
|---|---|
| Expected header-fields | +
|
+
| Comand-line (example) | +jobs/0.4 auth-challenge |
+
|---|---|
| Expected header-fields | +
|
+
| Comand-line (example) | +jobs/0.4 auth-response |
+
|---|---|
| Expected header-fields | +
|
+
| Comand-line (example) | +jobs/0.4 connected |
+
|---|---|
| Expected header-fields | +NONE | +
| Comand-line (example) | +jobs/0.4 error |
+
|---|---|
| Expected header-fields | +
|
+
Accessing a RDBMS in a generic fashion is a complex and difficult + task. Consequently, this will not be an attempt to XMLize a generic + Database API or query language. Instead, it will providing a + simple mechanism for a JID to read/write data that it has access to + and specifying a model for those schemas to use in xml.
+ +This JEP has two aims.
+ +-
+
- Be able to request the available schemas +
- Perform near SQL-like data manipulation +
Although designed for use with an RDBMS this JEP is not + restricted to such uses. It may be used with any data storage + system that can be broken down to a simple table, column/row + format. for example comma delimited files.
+To understand the following sections of this JEP the reader + must be aware of the following.
+ +The current namespace of http://openaether.org/projects/jabber_database.html + will be used until this becomes a jep. Once officially accepted as + a jep and approved as final by the council, it will become + http://www.jabber.org/jeps/jep-0043.html.
+-
+
- version - specify the version of the protocol that the client/server supports +
- database - specify the database/catalog has the following attributes: +
- name - name of the database/catalog +
- sql - embed native SQL queries directly +
- table - the element scopes the children into the table. has the following attributes: +
- name - name of the table +
- permission - what the user can do with the data +
- col - describes the column. has the following attributes +
- name - name of the column +
- type - SQL99 datatype of the column +
- size - size of the datatype if required +
- op - comparison operator, used only if child of where element +
- where - scopes col elements into a 'sql-like' where clause +
- col - see above +
- proc - element scopes the children into a procedure has the following attributes: +
- name - name of the sproc +
- permission - what the user can do with the data +
- col - see above +
- result - indicated return value by running the procedure (restricted to integer) +
-
+
-
+
-
+
-
+
-
+
-
+
There are a limited subset of data types available:
+-
+
- bit - a single 'bit', usually used to represent boolean values +
- tinyint - signed 8bit integer, has a range from -128 to +127 +
- integer - signed 32bit integer, has a range from -2147483648 to +2147483647 +
- utinyint - unsigned 8bit integer, has a range from 0 to +255 +
- uinteger - usigned 32bit integer, has a range from 0 to +4294967296 +
- float - allowed values are -3.402823466E+38 to + -1.175494351E-38, 0, and 1.175494351E-38 to 3.402823466E+38 (can NOT be unsigned) +
- numeric - unlimited size (some databases constrain this though) +
- date - resolution is one day. acceptable ranges vary (TODO: constrain minimal range to something) +
- datetime - a date and time combination (often has range dependencies) +
- timestamp - a datetime used most often to record events +
- time - a time in the format HH:MM:SS (TODO: specify valid range) +
- char - an unsigned byte representing a single character (ASCII) +
- vchar - a variable width char +
- text - an extremely large chunk of text +
- blob - an extremely large chunk of binary data (encode in MIME) +
All SQL/RDBMS units will be scoped in the xml hierarchy:
+ +
+<database>
+ <table>
+ <col/>
+ </table>
+</database>
+
+
+ All examples will assume the existence of the following rdbms setup. A + database named 'testdb' with tables created with following SQL + script:
+ +
+ create table tbl_one
+ (
+ a_int int,
+ a_float float,
+ a_char char(10)
+ )
+ create table tbl_two
+ (
+ a_date datetime,
+ a_numeric numeric(9,3)
+ )
+
+ This is a simple request to discover what tables/procedures + exist on the database testdb. And what permissions are available + to the user. All schema requests will respond within the scope that + was asked for. This is to prevent unnecessary data from flooding + the network. So the response for the above request would look + something like:
+ +The response is scoped to only the 'children' of the request. + Since the request was for the testdb database, only the tables + within that database were returned in the result. The reason for + the limitation is to prevent excessively large packets from filling + the network from large schemas.
+ +The response indicates that the user has both read and write + permissions on the table 'tbl_one' and only read permissions on + the table 'tbl_two'. Consequently, the user may only perform get + requests on 'tbl_two'.
+ +The response would look like:
+ +The schema response for tbl_one is quite intuitive. Three + columns exist, one called a_int of type int (integer), another + a_float of type float and a third called a_char of type char + with a size of ten characters.
+ + +Manipulation of data (select, insert, update, delete) will + definitely not be elegant or easy. SQL allows for some fairly + complex queries on any fully functional RDBMS. Consequently, + the data manipulation will be relatively limited since it is + not a goal to translate SQL into xml.
+ +To indicate a select like query, specify an <iq> of + type get. The table that the query is to be performed against + must be specified. The columns that are to be returned in + the result set must be scoped within the relative table. + Any attribute on the <col> element besides name will be + ignored. e.g. it is not required nor recommended to specify + the data types or the sizes while performing a get.
+ +It is also possible to specify a limit on the number of rows + returned in the result set by specifying a value for the limit + attribute.
+ +In this case a limit of two rows will be returned in the result set.
+ +The result set which is returned will contain all the rows + that met the criteria of the select. There is no schema + information beyond the column names included in the result set. + Each 'row' in the result set is scoped within the corresponding + <table> element. This allows for queries on multiple + tables to be used in one <iq> packet.
+ +It would be impractical to request the entire contents of the + table every time you needed one row or a subset of the data. You + can constrain the result set by specifying a where clause.
+ +Attributes only used in the <col> element within a + <where> element are the op (for operator) and conj for + (conjunction). The op is used for comparison operators such + as <, >, =, <>, <=, >= + +
-
+
- eq - equivalent = +
- neq - not-equivalent <> +
- lt - less than < +
- gt - greater than > +
- let - less than or equivalent <= +
- get - greater than or equivalent >= +
- null - IS NULL (the column is null in the database sense of the word) +
The conjuction attribute is used to combined constraints in the where clause + +
-
+
- not - to negate a result +
- or - logical OR || +
- and - logical AND && +
Result
+ +Inserting or altering the stored data in anyway requires + setting the type attribute to a value of set. This indicates + that the user wants to perform a 'insert/update'. The + differentiating factor between an insert and an update operation + is whether a <where> element is used. If there is no +<where> element then it must be interpreted as an insert. + If a <where> element does exist, then it must be + interpreted as an update.
+ +Result
+ +If there is no result set for the query, as in an update, + insert, delete, then the response must indicate success or + failure within the <table> element scope. An empty +<table> element indicates success, and a <table> + element containing an <error> element indicates a failure.
+ +The insert into tbl_one succeeded since the response has an + empty <table> element. However, the insert into tbl_two + failed with a permission denied error. Which is indicated with a + non-empty <table> element.
+As stated previously, if the type attribute has a value of + set and a <where> element exists, then it must be interpreted as an update.
+ +Result
+ +Again, if there is no result set returned by the query, then + success or failure must be indicated.
+ +If the type attribute has a value of set and there are no + <col> elements scoped within the <table> element, + then the query must be interpreted as a delete.
+ +Result
+ +Again, if a result set is not generated by a query, then + success or failure must be indicated by the <table> element
+ + Procedures, or stored procedures
The <proc> element will be used to indicate a procedure. + It has similar characteristics to the <table> element. The + core differences are that the <col> elements have permissions + and a <result> element can be used to indicate the value + returned by the procedure.
+ +The permission attribute on a <col> element is used to + indicate whether the parameter is in (read), out (write) or in/out (both).
+ +The only result set acceptable from a procedure is that of the + parameters or <col> element. If the procedure produces a + result set outside of the parameters this should be ignored.
+ +The server must be able to let the client know when an error + occurs, instead of just being silent.
+ +| Code | +Message | +Description | +
|---|---|---|
| 399 | +Invalid Database Name | +Returned when the client has requested information from a + database which does not exist according to the component. | +
| 398 | +Invalid Table Name | +Returned when the client has requested information from a + table/procedure which does not exist according to the component. | +
| 397 | +Invalid Column Name | +Returned when the client has requested information from a + column which does not exist according to the component. | +
| 380 | +Permission Denied on Table | +Returned when the requested action is not allowed for the + user on the table | +
| 401 | +Access Denied | +Returned when the user does not have permission to use the + component. | +
If the user requests an action on a table which they do not have + permission to do the following should be returned
+ +If the user is not allowed to access the component the following should be returned
+ +There are requirements which can be provided by other jabber + components/namespaces, namely the jabber:iq:browse namespace + in-place of Version Negotiation. Due to the inherent limitations + of the above data retrieval mechanisms more sophisticated querying + techniques might be desired. The <query> element will extend + the functionality
+ +The abilities described in the Basics section are just that, + basic. To provide more flexibility and allow for the full power + of SQL without xmlifying everything, a <sql> element may + be implemented to provide this feature.
+ +The <sql> element must be scoped within the <database> element.
+ +Result
+ +Since SQL is so flexible, the result set schema is not known + until it is returned as a result of the query. Consequently, it + must be sent as the first 'row' of the returned result. Each + following row will be the actual data queried for.
+ +If multiple tables are used within one SQL statement, then + then name attribute within the <table> element can not be + accurately denoted with a single table name. The best way to deal + with this situation is to simply use a unique identifier within + the scope of the <database> element. This will allow for + multiple <sql> results to be scoped within the same result.
+ +It is expected that this protocol will grow and be extended
+ to meet various demands. Therefore, version
+ negotiation
When the connection initiator, client end-user or + server/transport, starts a session, it must first send + the version number it expects to use, otherwise, behavior + is undefined.
+ +
+<iq id="000" type="get" to="db.host">
+ <database
+ xmlns="http://openaether.org/projects/jabber_database.html">
+ <version>0.1</version>
+ </database>
+</iq>
+
+
+ Three responses are possible from the server.
+-
+
- It supports that version number and responds with:
+
+<iq id="000" type="result" from="db.host"> + <database + xmlns="http://openaether.org/projects/jabber_database.html"> + <version>0.1</version> + </database> +</iq> ++ The type of 'result' indicates that the version request was + successful and if the client is satisfied with the version number, + may continue with schema requests or whatever.
+
+ - It does not support that version number and responds with:
+
+<iq id="000" type="error" from="db.host"> + <database + xmlns="http://openaether.org/projects/jabber_database.html"/> +</iq> ++ The type of 'error' indicates a failure in conforming to the + desired version number. The server may optionally send an + alternative option. ++<iq id="000" type="error" from="db.host"> + <database + xmlns="http://openaether.org/projects/jabber_database.html"> + <version>0.2</version> + </database> +</iq> +
+ - If the server has no idea what the client is talking + about it should send the appropriate Jabber error code. +
-
+
- No joins, roll ups, cubes +
- Views are not differentiated from tables +
- provides basic sql-like functionality only +
- Utilizes lowest common denominator approach +
-
+
- define procedures; what they are and how they work +
- determine value of adding administration features +
Thanks to Russell Davis (ukscone) for fine tuning the layout and wording of this jep. It would probably have been unreadable if it wasn't for him.
+
+<!ELEMENT version (#PCDATA)>
+<!ELEMENT error (#PCDATA)>
+<!ELEMENT sql(#PCDATA)>
+<!ELEMENT database (table | sproc | sql | error)*>
+<!ELEMENT table (col | where | error)*>
+<!ELEMENT where (col+)>
+<!ELEMENT col (#PCDATA)>
+<!ELEMENT proc(col | result | error)*>
+<!ELEMENT result (#PCDATA)>
+<!ATTLIST error code CDATA #IMPLIED>
+<!ATTLIST database name CDATA #IMPLIED>
+<!ATTLIST table
+name CDATA #IMPLIED
+ permission (read | write | both) #IMPLIED
+ limit CDATA #IMPLIED
+>
+<!ATTLIST proc name CDATA #IMPLIED>
+<!ATTLIST col
+ name CDATA #IMPLIED
+ size CDATA #IMPLIED
+ op (eq | neq | lt | gt | let | get | null) #IMPLIED
+ conj (not | or | and ) #IMPLIED
+ permission (read | write | both) #IMPLIED
+ type (bit | tinyint | integer | utinyint | uinteger |
+ float | numeric | date | datetime | timestamp |
+ time | char | vchar | text | blob) #IMPLIED
+>
+
+ Anyone care to do this?
+Jabber has traditionally supported a subset of the XML Namespaces specification
This is convenient for client and server implementors, since they only need to check the element name to determine both the name and the context of the element. However, these restrictions mean that developers are unable to take advantage of some of the features that namespaces provide.
+ +Many developers have expressed an interest in having Jabber fully support namespaces - a desire which is likely to increase as time goes on. This support consists of allowing any namespace prefix to be used with any namespace, and also to allow namespace prefixes to be pre-declared on the stream root.
+ +This document outlines the semantics required for servers and clients to support namespaces fully, and also discusses implementation techniques and methods for providing compatibility with older "fixed-prefix" implementations.
+A typical XML stream is a pair of XML documents, one for each direction of communication between the two peers. An simple example of these might look like this:
+ +Note that there may also be additional namespaces specified in the stream header, to select or inform of various server features:
+ +Currently, the prefix for each namespace is fixed; it cannot vary at all, since implementations use it for matching. The desire is to be able to use arbitrary prefixes:
+ +Also, since there exist streams in both directions, it should be possible for prefixes to differ between the two streams:
+ +Additionally, it should be possible to declare namespaces on the stream header so that they don't need to be declared later:
+ +And of course, any combinations of these should be valid, as long as they conform to the XML Namespaces specification.
+ +In order to implement namespaces correctly, implementations will need to check both the namespace of an element (or attribute), and its namespace, in order to match it. An implementation will need to maintain some sort of mapping between prefixes and namespaces, though some parsers, such as recent versions of Expat, can do this for the implementor.
+ +Implementations should, wherever possible, adhere to the IETF maxim "be liberal in what you accept, and conservative in what you send". This means accepting any valid namespace prefix, but using only the traditional prefixes (i.e. "stream" for "http://etherx.jabber.org/streams", "sasl" for "http://www.iana.org/assignments/sasl-mechanisms", and no prefix for the application namespace). For servers, this has the added benefit of getting compatibility with non-namespace-aware clients for free.
+ +In server components that may have to forward packets received from one stream to another stream, it may be necessary for the application namespace to be rewritten before the packet is forwarded. Examples of this are client-to-server and server-to-server components, which must convert "jabber:client" and "jabber:server" components, respectively, into "jabber:component:accept" packets before they are forwarded to the router.
+ +-
+
- Clarified that inclusion of MUC extension in room join/create request triggers Data Forms flow but that absence of MUC extension leads to automatic room creation for backwards compatibility with older groupchat 1.0 protocol. +
- Specified use of <not-acceptable/> error on nickname change if nicks are locked down. +
- Required clients to discover room configuration prior to entering room and specified related security considerations, including use of privacy-related status codes 170, 171, 172, 173, and 174. +
- Specified use of <not-acceptable/> error if room configuration options cannot be processed or violate service policies. +
- Made explicit that roomnicks must not consist only of spaces. +
- Moved all service discovery use cases into dedicated section. +
- Changed jabber:x:delay support from SHOULD to MUST. +
- Clarified that _whois room configuration option specifies room type. +
- Defined JEP-0128 room information fields for discussion logs, associated pubsub node, and contact JID. +
- Specified that changing role to moderator upon affiliation change to admin or owner is recommended, not required. +
- Added internationalization consideration about localization of field labels for various data forms. +
- Specified that implementations may persist roles across visits and should do so for moderated rooms. +
- Added protocol and service discovery feature for requesting a unique room name prior to room creation. +
- Further clarified nature of reserved room nicknames and nickname lockdown. +
- Defined data forms for requesting voice and approving voice requests. +
- Added multiple invitee example for XMPP URI. +
- Clarified order of presence, discussion history, etc. +
- Added status codes for occupant's own roomnick, service-modified roomnick, and warning that room discussion is publicly logged. +
- Clarified privacy and anonymity considerations regarding room logging and non-anonymous rooms. +
Harmonized ability to kick and ban users, and clarified that a user cannot be kicked or banned by a moderator or admin with a lower affiliation.
Specified how to send multiple invitations simultaneously; corrected some errors regarding consistency of affiliation state changes; changed message events prohibition from MUST NOT to SHOULD NOT; corrected error handling related to the #traffic disco node; allowed <password/> as a child of <destroy/>; changed max users error from ¬allowed; to &unavailable;; specified that the maxchars attribute counts characters in complete XML stanzas; added disco features for FORM_TYPEs; defined registry for status codes; split Create Instant Room into separate use case for protocol compliance purposes; adjusted XML schemas to reflect the foregoing changes; re-wrote the introduction; clarified small textual matters throughout.
Corrected several errors in the affiliation state chart and in the examples (wrong FORM_TYPE values); mentioned /me command.
Added text about allowable extension namespaces and related service discovery mechanisms; specified well-known service discovery nodes; added conformance terms to clarify some descriptions; modified affiliation state chart to allow more flexible state changes; per list dicussion, added ability to convert a one-to-one chat into a conference, including sending of history; specified error to use when max users limit is reached; specified form for admin approval of user registration requests and modified FORM_TYPE from http://jabber.org/protocol/muc#user to http://jabber.org/protocol/muc#register; modified FORM_TYPE for room configuration from http://jabber.org/protocol/muc#owner to http://jabber.org/protocol/muc#roomconfig.
Added example and registry submission for service discovery extension.
Removed jabber:iq:browse references; clarified order of presence stanzas sent to new occupant on entering room; specified format of in-room messages (type='groupchat', from='room@service'); clarified allowable attributes in various list-related operations; made admin/owner revocation text and examples consistent with state chart; clarified ownership revocation conflict scenarios; changed the 'muc#roomconfig_inviteonly' field to 'muc#roomconfig_membersonly'; changed attribute order in examples to match XML canonicalization rules; corrected several errors in the schemas.
Corrected discovery of registered roomnicks; added note about error to return if nicks are locked down.
Fixed an error in the muc#user schema.
Corrected a few errors in the examples; added IQ results in order to clarify workflows.
Clarified JID matching rules (same as for privacy lists in XMPP IM).
Added XMPP error handling; fully specified all conformance terms.
Removed protocol for requesting voice in a moderated room (should be performed using Ad-Hoc Commands).
Added protocol for requesting voice in a moderated room; added (informational) mapping of IRC commands to MUC protocols.
Added room configuration option for restricting presence broadcast to certain roles.
Added history management protocol on entering a room.
Specified that ban occurs by JID, not roomnick; allowed privileged users to send messages to the room even if not present in the room; added note that service should remove occupant if a delivery-related stanza error occurs; enabled user to disco the room in order to discover registered roomnick; specified that "banning" by domain or regex is a service-level configuration matter and therefore out of scope for MUC; specified that role should be decremented as appropriate if affiliation is lowered; added some clarifying text to room creation workflow; added implementation note about sending an out-of-band message if a user's affiliation changes while the user is not in the room; fixed stringprep references (room nicks use Resourceprep); clarified relationship between Room ID (i.e., node identifier of Room JID, which may be opaque) and natural-language Room Name; specified Field Standardization profile per JEP-0068; defined Jabber Registrar submissions; added schema locations.
Added XML schemas.
Added reference to nodeprep Internet-Draft.
Commented out revision history prior to version 1.0 (too long); clarified business rules regarding when nicks, full JIDs, and bare JIDs are used in reference to roles and affiliations; consistently specified that extended presence information in the muc#user namespace must include the full JID as the value of the 'jid' attribute in all cases; cleaned up text and examples throughout; added open issue regarding syntax of room nicknames.
Added protocol for declining an invitation; replaced <created/> element with status code 201; modified the destroy room protocol so that <destroy/> is a child of <query/>; clarified usage of 'nick' attribute when adding members; prohibited use of message events.
Per a vote of the Jabber Council, revision 0.23 was advanced to Draft on 2002-11-21. (For earlier revision history, refer to XML source.)
Added examples for disco#items queries sent to a room; prohibited 'type' attribute on invite messages sent from client to room; added dependencies for JEPs 11 and 30; changed 'room user' to 'occupant'; fixed many small errors throughout.
Added example for disco#items; added support for cancellation of room configuration using type='cancel' from JEP-0004; noted 403 error for invites sent by non-admins in members-only room.
Clarified several small ambiguities; made <body/> optional on invites sent from the service to the invitee; added error scenarios for changing nickname and for destroying the room; specified that the service must return the full member list for a members-only room (not only the members in the room); updated the disco examples to track protocol changes.
Specified that messages sent to change the room subject must be of type "groupchat"; updated the legal notice to conform to the JSF IPR policy.
Added ability to create an instant room within MUC (not by using gc-1.0 protocol); cleaned up disco examples.
Added experimental support for disco; added sections for security, IANA, and JANA considerations; corrected typographical errors; cleaned up some DocBook formatting.
Added the optional <actor/> element (with 'jid' attribute) to <item/> elements inside presence stanzas of type "unavailable" that are sent to users who are kicked or banned, as well as within IQs for tracking purposes; reverted all list editing use cases (ban, voice, member, moderator, admin, owner) to use of MUC format rather than 'jabber:x:data' namespace; added several guidelines regarding generation and handling of XML stanzas; cleaned up the change room subject use case; changed several ambiguous uses of 'would', 'can', and 'will' to 'should', 'may', or 'must'; fixed several small errors in the text, examples, and DTDs.
Added the <item/> element to presence stanzas of type "unavailable" in order to improve the tracking of user states in the room; consolidated <invitee/> and <invitor/> elements into an <invite/> element with 'from' and 'to' attributes; made <reason/> element always a child of <item/> or <invite/> in the muc#user namespace; moved the alternate room location in room destruction to a 'jid' attribute of the <alt/> element; further specified several error messages; disallowed simultaneous modifications of both affiliations and roles by a moderator or admin; added several more rules regarding handling of XML stanzas; added use cases for granting and revoking administrative privileges; adjusted DTD to track all changes.
Fully incorporated the change to affiliations + roles; moved a number of admin use cases to a new section for moderator use cases; added participant use case for requesting membership; added admin use cases for adding members, removing members, granting and revoking moderator privileges, and modifying the moderator list; organized the sections in a more logical manner.
Significantly modified the privileges model by distinguishing between in-room "roles" and long-lived "affiliations"; specified the privileges of the various roles and affiliations; included state transition charts for both roles and affiliations; removed use of MUC protocol for editing ban, voice, and admin lists (but not for the actions of banning users and granting/revoking voice); added delivery rule regarding IQ stanzas; changed kick so that the action is based on changing the role to "none".
Corrected the change nickname examples (newnick sent on unavailable, no nick sent on available).
Removed SHA1 passwords; specified that room shall add passwords on invitations to password-protected rooms (not supplied by invitor).
Changed 'participant' to 'room user' and 'discussant' to 'participant'; clarified presence rule about client generation of extended presence information; added role of 'none'.
Fixed extended presence on entering or creating a room (plain '...muc' with no fragment); harmonized #user with #admin regarding the use of the <item/> element and associated attributes (jid, nick, etc.), and added 'role' attribute; modified management of voice, ban, admin, and member lists to use <query/> wrapper and new <item/> structure; changed the 'member' role to 'discussant', added 'outcast' role for banned users, and added new 'member' role to enable management of member lists; changed invitation-only rooms to members-only rooms and made appropriate adjustments to apply member lists to both members-only rooms and open rooms; modified nickname change protocol slightly to send the old nickname in the unavailable presence and the new nickname in the available presence; removed prohibition on members-only rooms that are password-protected; removed the <query/> wrapper for the <destroy/> element; updated the DTDs.
Added extended presence ('...#user') on entering a room for MUC clients; changed namespace on room creation request to '...#owner'; added a service discovery example using jabber:iq:browse; added information about discussion history; made small fixes to several examples; further defined the presence rules; transferred all implementation notes to a dedicated section; added a Terminology section.
Made further changes to the room creation workflow (finally correct); removed feature discovery use case (this needs to be addressed by a real service discovery protocol!); added ability for room owners to edit the admin list; removed <body/> from invitations generated by the service; removed messages sent to kicked and banned users (handled by unavailable presence with status code); added a number of implementation notes; converted all examples to Shakespeare style.
Fixed the room creation workflow; changed some terminology ("join" to "enter" and "leave" to "exit").
Specified and improved the handling of invitation-only rooms. In particular, added the ability for room admins to edit the invitation list and added a configuration option that limits the ability to send invitations to room admins only.
Changed namespaces from http://jabber.org/protocol/muc/owner etc. to http://jabber.org/protocol/muc#owner etc. per Jabber Council discussion.
Changed namespaces to HTTP URIs; left role handling up to the implementation; further clarified presence rules.
Disallowed kicking, banning, and revoking voice with respect to room admins and room owners; replaced <x/> with <query/> in the Discovering Room Features and Destroying a Room use cases; corrected some small errors and made many clarifications throughout.
Removed <whois/> command (unnecessary since participants with appropriate privileges receive the full JID of all participants in presence stanzas); completed many small fixes throughout.
More clearly delineated participant roles and defined the hierarchy thereof (owner, admin, member, visitor); replaced <voice/> element in extended presence with <item role='member'/>; changed initial room configuration to use IQ rather than message; adjusted presence rules (especially regarding extended presence information); cleaned up examples throughout; updated DTD to track changes.
More clearly defined the scope; removed fully anonymous rooms; changed meaning of semi-anonymous rooms and of non-anonymous rooms; added mechanism for notification of full JIDs in non-anonymous rooms; replaced the <admin/> element in extended presence with a <role/> element (more extensible); changed room passwords to cleartext; added status codes for various messages received from the service; added lists of valid error and status codes associated with the 'http://jabber.org/protocol/muc#user' namespace; added a <reason/> element for invitations; made kick and ban reasons child elements rather than attributes; replaced stopgap feature discovery mechanism with jabber:iq:negotiate; added extended presence element to room creation request and clarified the room creation process; specified presence reflection rules; added method for destroying a room; adjusted DTDs to track all changes.
Added DTDs; changed feature discovery to use <x/> element rather than query and made service response come in IQ result; fixed reference to JEP 29; changed 'grant' to 'add' and 'revoke' to 'remove' for consistency in the item attributes; made several other small changes.
Changed the kick, ban, and voice protocols; added a few more configuration options; specified the restrictions for roomnicks; and added a stopgap service discovery protocol.
Changed all non-GC-1.0 use cases to jabber:gc:* namespaces or jabber:x:data; added use cases for ban list management and room moderation; added protocol for sending notice of admin and voice privileges in presence; cleaned up text and many examples.
Changed admin use cases; cleaned up participant and owner use cases.
Broke content out into three actors (participant, owner, and admin) and added more detail to owner and admin use cases.
Initial version.
Traditionally, instant messaging is thought to consist of one-to-one chat rather than many-to-many chat, which is called variously "groupchat" or "text conferencing". Groupchat functionality is familiar from systems such as Internet Relay Chat (IRC) and the chatroom functionality offered by popular consumer IM services. The Jabber community developed and implemented a basic groupchat protocol as long ago as 1999. This "groupchat 1.0" protocol provided a minimal feature set for chat rooms but was rather limited in scope. This specification builds on the older "groupchat 1.0" protocol in a backwards-compatible manner but provides advanced features such as invitations, room moderation and administration, and specialized room types. These extensions are implemented using protocol elements qualified by the 'http://jabber.org/protocol/muc' namespace (and the #owner, #admin, and #user fragments on the main namespace URI).
+This document addresses common requirements related to configuration of, participation in, and administration of individual text-based conference rooms. All of the requirements addressed herein apply at the level of the individual room and are "common" in the sense that they have been widely discussed within the Jabber community or are familiar from existing text-based conference environments outside of Jabber (e.g., Internet Relay Chat as defined in &rfc1459; and its successors).
+This document explicitly does not address the following:
+-
+
- Relationships between rooms (e.g., hierarchies of rooms) +
- Management of multi-user chat services (e.g., managing permissions across an entire service or registering a global room nickname) +
- Moderation of individual messages +
- Security and encryption at the level of a room or service +
- Advanced features such as attaching files to a room, integrating whiteboards, and interfacing with audio chat services +
- Interaction between MUC deployments and foreign chat systems (e.g., gateways to IRC or to legacy IM systems) +
This limited scope is not meant to disparage such topics, which are of inherent interest; however, it is meant to focus the discussion in this document and to present a comprehensible protocol that can be implemented by Jabber client and component developers alike. Future specifications may of course address the topics mentioned above.
+This document addresses the minimal functionality provided by existing multi-user chat services in Jabber. For the sake of backwards-compatibility, this document uses the original "groupchat 1.0" protocol for this baseline functionality, with the result that:
+-
+
- Each room is identified as &ROOM; (e.g., <jdev@conference.jabber.org>), where "room" is the name of the room and "service" is the hostname at which the multi-user chat service is running. +
- Each occupant in a room is identified as &ROOMJID;, where "nick" is the room nickname of the occupant as specified on entering the room or subsequently changed during the occupant's visit. +
- A user enters a room (i.e., becomes an occupant) by sending presence to &ROOMJID;. +
- Messages sent within multi-user chat rooms are of a special type "groupchat" and are addressed to the room itself (room@service), then reflected to all occupants. +
- An occupant can change his or her room nickname and availability status within the room by sending presence information to <room@service/newnick>. +
- An occupant exits a room by sending presence of type "unavailable" to its current &ROOMJID;. +
The additional features and functionality addressed in this document include the following:
+-
+
- native conversation logging (no in-room bot required) +
- enabling users to request membership in a room +
- enabling occupants to view an occupant's full JID in a non-anonymous room +
- enabling moderators to view an occupant's full JID in a semi-anonymous room +
- allowing only moderators to change the room subject +
- enabling moderators to kick participants and visitors from the room +
- enabling moderators to grant and revoke voice (i.e., the privilege to speak) in a moderated room, and to manage the voice list +
- enabling admins to grant and revoke moderator privileges, and to manage the moderator list +
- enabling admins to ban users from the room, and to manage the ban list +
- enabling admins to grant and revoke membership privileges, and to manage the member list for a members-only room +
- enabling owners to limit the number of occupants +
- enabling owners to specify other owners +
- enabling owners to grant and revoke administrative privileges, and to manage the admin list +
- enabling owners to destroy the room +
In addition, this document provides protocol elements for supporting the following room types:
+-
+
- public or hidden +
- persistent or temporary +
- password-protected or unsecured +
- members-only or open +
- moderated or unmoderated +
- non-anonymous or semi-anonymous +
Affiliation -- a long-lived association or connection with a room; the possible affiliations are "owner", "admin", "member", and "outcast" (naturally it is also possible to have no affiliation); affiliation is distinct from role. An affiliation lasts across a user's visits to a room.
+Ban -- to remove a user from a room such that the user is not allowed to re-enter the room (until and unless the ban has been removed). A banned user has an affiliation of "outcast".
+Bare JID -- the <user@host> by which a user is identified outside the context of any existing session or resource; contrast with Full JID and Room JID.
+Full JID -- the <user@host/resource> by which an online user is identified outside the context of a room; contrast with Bare JID and Room JID.
+GC -- the minimal "groupchat 1.0" protocol
History -- a limited number of message stanzas sent to a new occupant to provide the context of current discussion.
+Invitation -- a special message sent from one user to another asking the recipient to join a room.
+IRC -- Internet Relay Chat.
+Kick -- to temporarily remove a participant or visitor from a room; the user is allowed to re-enter the room at any time. A kicked user has a role of "none".
+Logging -- storage of discussions that occur within a room for public retrieval outside the context of the room.
+Member -- a user who is on the "whitelist" for a members-only room or who is registered with an open room. A member has an affiliation of "member".
+Moderator -- a room role that is usually associated with room admins but that may be granted to non-admins; is allowed to kick users, grant and revoke voice, etc. A moderator has an role of "moderator".
+MUC -- the multi-user chat protocol for text-based conferencing specified in this document.
+Occupant -- any Jabber user who is in a room (this is an "abstract class" and does not correspond to any specific role).
+Outcast -- a user who has been banned from a room. An outcast has an affiliation of "outcast".
+Participant -- an occupant who does not have administrative privileges; in a moderated room, a participant is further defined as having voice (in contrast to a visitor). A participant has a role of "participant".
+Private Message -- a message sent from one occupant directly to another's room JID (not to the room itself for broadcasting to all occupants).
+Role -- a temporary position or privilege level within a room, distinct from a user's long-lived affiliation with the room; the possible roles are "moderator", "participant", and "visitor" (it is also possible to have no defined role). A role lasts only for the duration of an occupant's visit to a room.
+Room -- a virtual space that Jabber users figuratively enter in order to participate in real-time, text-based conferencing with other users.
+Room Administrator -- a user empowered by the room owner to perform administrative functions such as banning users; however, is not allowed to change defining room features. An admin has an affiliation of "admin".
+Room ID -- the node identifier portion of a Room JID, which may be opaque and thus lack meaning for human users (see Business Rules for syntax); contrast with Room Name.
+Room JID -- the &ROOMJID; by which an occupant is identified within the context of a room; contrast with Bare JID and Full JID.
+Room Name -- a user-friendly, natural-language name for a room, configured by the room owner and presented in Service Discovery queries; contrast with Room ID.
+Room Nickname -- the resource identifier portion of a Room JID (see Business Rules for syntax); this is the "friendly name" by which an occupant is known in the room.
+Room Owner -- the Jabber user who created the room or a Jabber user who has been designated by the room creator or owner as someone with owner privileges (if allowed); is allowed to change defining room features as well as perform all administrative functions. An owner has an affiliation of "owner".
+Room Roster -- a Jabber client's representation of the occupants in a room.
+Server -- a Jabber server that may or may not have associated with it a text-based conferencing service.
+Service -- a host that offers text-based conferencing capabilities; often but not necessarily a sub-domain of a Jabber server (e.g., conference.jabber.org).
+Subject -- a temporary discussion topic within a room.
+Visit -- a user's "session" in a room, beginning when the user enters the room (i.e., becomes an occupant) and ending when the user exits the room.
+Visitor -- in a moderated room, an occupant who does not have voice (in contrast to a participant). A visitor has a role of "visitor".
+Voice -- in a moderated room, the privilege to send messages to all occupants.
+Fully-Anonymous Room -- a room in which the full JIDs or bare JIDs of occupants cannot be discovered by anyone, including room admins and room owners; such rooms are NOT RECOMMENDED or explicitly supported by MUC, but are possible using this protocol if a service implementation offers the appropriate configuration options; contrast with Non-Anonymous Room and Semi-Anonymous Room.
+Hidden Room -- a room that cannot be found by any user through normal means such as searching and service discovery; antonym: Public Room.
+Members-Only Room -- a room that a user cannot enter without being on the member list; antonym: Open Room.
+Moderated Room -- a room in which only those with "voice" may send messages to all occupants; antonym: Unmoderated Room.
+Non-Anonymous Room -- a room in which an occupant's full JID is exposed to all other occupants, although the occupant may choose any desired room nickname; contrast with Semi-Anonymous Room and Fully-Anonymous Room.
+Open Room -- a room that anyone may enter without being on the member list; antonym: Members-Only Room.
+Password-Protected Room -- a room that a user cannot enter without first providing the correct password; antonym: Unsecured Room.
+Persistent Room -- a room that is not destroyed if the last occupant exits; antonym: Temporary Room.
+Public Room -- a room that can be found by any user through normal means such as searching and service discovery; antonym: Hidden Room.
+Semi-Anonymous Room -- a room in which an occupant's full JID can be discovered by room admins only; contrast with Fully-Anonymous Room and Non-Anonymous Room.
+Temporary Room -- a room that is destroyed if the last occupant exits; antonym: Persistent Room.
+Unmoderated Room -- a room in which any occupant is allowed to send messages to all occupants; antonym: Moderated Room.
+Unsecured Room -- a room that anyone is allowed to enter without first providing the correct password; antonym: Password-Protected Room.
+Most of the examples in this document use the scenario of the witches' meeting held in a dark cave at the beginning of Act IV, Scene I of Shakespeare's Macbeth, represented here as the "darkcave@macbeth.shakespeare.lit" chatroom. The characters are as follows:
+| Room Nickname | +Full JID | +Affiliation | +
|---|---|---|
| firstwitch | +crone1@shakespeare.lit/desktop | +Owner | +
| secondwitch | +wiccarocks@shakespeare.lit/laptop | +Admin | +
| thirdwitch | +hag66@shakespeare.lit/pda | +None | +
There are two dimensions along which we can measure a user's connection with or position in a room. One is the user's long-lived affiliation with a room -- e.g., a user's status as an owner or an outcast. The other is a user's role while an occupant of a room -- e.g., an occupant's position as a moderator with the ability to kick visitors and participants. These two dimensions are distinct from each other, since an affiliation lasts across visits, while a role lasts only for the duration of a visit. In addition, there is no one-to-one correspondence between roles and affiliations; for example, someone who is not affiliated with a room may be a (temporary) moderator, and a member may be a participant or a visitor in a moderated room. These concepts are explained more fully below.
+There are four defined roles that an occupant may have:
+-
+
- Moderator +
- Participant +
- Visitor +
- None (the absence of a role) +
Roles are temporary in that they do not necessarily persist across a user's visits to the room and MAY change during the course of an occupant's visit to the room. An implementation MAY persist roles across visits and SHOULD do so for moderated rooms (since the distinction between visitor and participant is critical to the functioning of a moderated room).
+There is no one-to-one mapping between roles and affiliations (e.g., a member could be a participant or a visitor).
+A moderator is the most powerful occupant within the context of the room, and can to some extent manage other occupants' roles in the room. A participant has fewer privileges than a moderator, although he or she always has the right to speak. A visitor is a more restricted role within the context of a moderated room, since visitors are not allowed to send messages to all occupants.
+Roles are granted, revoked, and maintained based on the occupant's room nickname or full JID rather than bare JID. The privileges associated with these roles, as well as the actions that trigger changes in roles, are defined below.
+Information about roles MUST be sent in all presence stanzas generated or reflected by the room and thus sent to occupants.
+For the most part, roles exist in a hierarchy. For instance, a participant can do anything a visitor can do, and a moderator can do anything a participant can do. Each role has privileges not possessed by the next-lowest role; these privileges are specified in the following table as defaults (an implementation MAY provide configuration options that override these defaults).
+| Privilege | +None | +Visitor | +Participant | +Moderator | +
|---|---|---|---|---|
| Present in Room | +No | +Yes | +Yes | +Yes | +
| Receive Messages | +No | +Yes | +Yes | +Yes | +
| Change Availability Status | +No | +Yes | +Yes | +Yes | +
| Change Room Nickname | +No | +Yes* | +Yes | +Yes | +
| Send Private Messages | +No | +Yes* | +Yes | +Yes | +
| Invite Other Users | +No | +Yes* | +Yes* | +Yes | +
| Send Messages to All | +No | +No** | +Yes | +Yes | +
| Modify Subject | +No | +No* | +Yes* | +Yes | +
| Kick Participants and Visitors | +No | +No | +No | +Yes | +
| Grant Voice | +No | +No | +No | +Yes | +
| Revoke Voice | +No | +No | +No | +Yes*** | +
* Default; configuration settings MAY modify this privilege.
+** An implementation MAY grant voice by default to visitors in unmoderated rooms.
+*** A moderator MUST NOT be able to revoke voice privileges from an admin or owner.
+The ways in which an occupant's role changes are well-defined. Sometimes the change results from the occupant's own action (e.g., entering or exiting the room), whereas sometimes the change results from an action taken by a moderator, admin, or owner. If an occupant's role changes, a MUC service implementation MUST change the occupant's role to reflect the change and communicate the change to all occupants. Role changes and their triggering actions are specified in the following table.
+| > | +None | +Visitor | +Participant | +Moderator | +
|---|---|---|---|---|
| None | +-- | +Enter moderated room | +Enter unmoderated room | +Admin or owner enters room | +
| Visitor | +Exit room or be kicked by a moderator | +-- | +Moderator grants voice | +Admin or owner grants moderator privileges | +
| Participant | +Exit room or be kicked by a moderator | +Moderator revokes voice | +-- | +Admin or owner grants moderator privileges | +
| Moderator | +Exit room | +Admin or owner changes role to visitor * | +Admin or owner changes role to participant or revokes moderator privileges * | +-- | +
* A moderator MUST NOT be able to revoke moderator privileges from an occupant who is equal to or above the moderator in the hierarchy of affiliations.
+Note: Certain roles are typically implicit in certain privileges. For example, an admin or owner is automatically a moderator, so if an occupant is granted admin status then the occupant will by that fact be granted moderator privileges; similarly, when an occupant is made a member in a moderated room, the occupant automatically has a role of participant. However, the loss of admin status does not necessarily mean that the occupant is no longer a moderator (since a "mere" participant can be a moderator). Therefore, the roles that are gained when an occupant is granted a certain affiliation are stable, whereas the roles that are lost when an occupant loses a certain affilitation are no hardcoded and are left up to the implementation. Since a client cannot predict what the role will be after revoking a certain affiliation, if it wants to remove both admin/owner privileges and the moderator role at the same time then it must specifically request the role change in addition to the affiliation change.
+There are five defined affiliations that a user may have in relation to a room:
+-
+
- Owner +
- Admin +
- Member +
- Outcast +
- None (the absence of an affiliation) +
These affiliations are long-lived in that they persist across a user's visits to the room and are not affected by happenings in the room. In addition, there is no one-to-one mapping between these affiliations and an occupant's role within the room. Affiliations are granted, revoked, and maintained based on the user's bare JID.
+If a user without a defined affiliation enters a room, the user's affiliation is defined as "none"; however, this affiliation does not persist across visits (i.e., a service does not maintain a "none list" across visits).
+The member affiliation provides a way for a room owner or admin to specify a "whitelist" of users who are allowed to enter a members-only room. When a member enters a members-only room, his or her affiliation does not change, no matter what his or her role is. The member affiliation also provides a way for users to effectively register with an open room and thus be lastingly associated with that room in some way (one result may be that the user's nickname is reserved in the room).
+An outcast is a user who has been banned from a room and who is not allowed to enter the room.
+Information about affiliations MUST be sent in all presence stanzas generated or reflected by the room and sent to occupants.
+For the most part, affiliations exist in a hierarchy. For instance, an owner can do anything an admin can do, and an admin can do anything a member can do. Each affiliation has privileges not possessed by the next-lowest affiliation; these privileges are specified in the following table.
+| Privilege | +Outcast | +None | +Member | +Admin | +Owner | +
|---|---|---|---|---|---|
| Enter Open Room | +No | +Yes* | +Yes | +Yes | +Yes | +
| Register with an Open Room | +No | +Yes | +N/A | +N/A | +N/A | +
| Enter Members-Only Room | +No | +No | +Yes* | +Yes | +Yes | +
| Ban Members and Unaffiliated Users | +No | +No | +No | +Yes | +Yes | +
| Edit Member List | +No | +No | +No | +Yes | +Yes | +
| Edit Moderator List | +No | +No | +No | +Yes** | +Yes** | +
| Edit Admin List | +No | +No | +No | +No | +Yes | +
| Edit Owner List | +No | +No | +No | +No | +Yes | +
| Change Room Definition | +No | +No | +No | +No | +Yes | +
| Destroy Room | +No | +No | +No | +No | +Yes | +
* As a default, an unaffiliated user enters a moderated room as a visitor, and enters an open room as a participant. A member enters a room as a participant. An admin or owner enters a room as a moderator.
+** An admin or owner MUST NOT be able to revoke moderation privileges from another admin or owner.
+The ways in which a user's affiliation changes are well-defined. Sometimes the change results from the user's own action (e.g., registering as a member of the room), whereas sometimes the change results from an action taken by an admin or owner. If a user's affiliation changes, a MUC service implementation MUST change the user's affiliation to reflect the change and communicate that to all occupants. Affiliation changes and their triggering actions are specified in the following table.
+| > | +Outcast | +None | +Member | +Admin | +Owner | +
|---|---|---|---|---|---|
| Outcast | +-- | +Admin or owner removes ban | +Admin or owner adds user to member list | +Owner adds user to admin list | +Owner adds user to owner list | +
| None | +Admin or owner applies ban | +-- | +Admin or owner adds user to member list, or user registers as member (if allowed) | +Owner adds user to admin list | +Owner adds user to owner list | +
| Member | +Admin or owner applies ban | +Admin or owner changes affiliation to "none" | +-- | +Owner adds user to admin list | +Owner adds user to owner list | +
| Admin | +Owner applies ban | +Owner changes affiliation to "none" | +Owner changes affiliation to "member" | +-- | +Owner adds user to owner list | +
| Owner | +Owner applies ban | +Owner changes affiliation to "none" | +Owner changes affiliation to "member" | +Owner changes affiliation to "admin" | +-- | +
A MUC implementation MUST support &jep0030;.
+A Jabber entity may wish to discover if a service implements the Multi-User Chat protocol; in order to do so, it sends a service discovery information ("disco#info") query to the component's JID:
+The service MUST return its identity and the features it supports:
+Note: Because MUC is a superset of the old "groupchat 1.0" protocol, a MUC service SHOULD NOT return a <feature var='gc-1.0'/> entry in a disco#info result.
+The service discovery items ("disco#items") protocol enables a user to query a service for a list of associated items, which in the case of a chat service would consist of the specific chat rooms hosted by the service.
+The service SHOULD return a full list of the rooms it hosts.
+If the full list of rooms is large (see JEP-0030 for details), the service MAY return only a partial list of rooms.
+Using the disco#info protocol, a user may also query a specific chat room for more detailed information about the room. A user SHOULD do so before entering a room in order to determine the privacy and security profile of the room configuration (see the Security Considerations for details).
+The room MUST return its identity and SHOULD return the features it supports:
+Note: Because MUC is a superset of the old "groupchat 1.0" protocol, a MUC room SHOULD NOT return a <feature var='gc-1.0'/> entry in a disco#info result. The room SHOULD return the materially-relevant features it supports, such as password protection and room moderation (these are listed fully in the feature registry maintained by the Jabber Registrar; see also the Jabber Registrar section of this document).
+A chatroom MAY return more detailed information in its disco#info response using &jep0128;, identified by inclusion of a hidden FORM_TYPE field whose value is "http://jabber.org/protocol/muc#roominfo". Such information might include a more verbose description of the room, the current room subject, and the current number of occupants in the room:
+Some extended room information may be dynamically generated (e.g., the URL for discussion logs, which may be based on service-wide configuration) whereas other information may be based on the room configuration.
+Note: The foregoing extended service discovery fields for the 'http://jabber.org/protocol/muc#roominfo' FORM_TYPE may be supplemented in the future via the mechanisms described in the Field Standardization section of this document.
+A user MAY also query a specific chat room for its associated items:
+An implementation MAY return a list of existing occupants if that information is publicly available, or return no list at all if this information is kept private.
+Note: These <item/> elements are qualified by the disco#items namespace, not the muc namespace; this means that they cannot possess 'affiliation' or 'role' attributes, for example.
+If a non-occupant attempts to send a disco request to an address of the form &ROOMJID;, a MUC service SHOULD return the request to the entity and specify a &badrequest; error condition. If an occupant sends such a request, the service MAY pass it through the intended recipient; see the Implementation Guidelines section of this document for details.
+A Jabber user may want to discover if one of the user's contacts supports the Multi-User Chat protocol. This is done using Service Discovery.
+The client SHOULD return its identity and the features it supports:
+A user may also query a contact regarding which rooms the contact is in. This is done by querying the contact's full JID (<user@host/resource>) while specifying the well-known Service Discovery node 'http://jabber.org/protocol/muc#rooms':
+Optionally, the contact MAY include its roomnick as the value of the 'name' attribute:
+
+ ...
+ ]]>
+ The main actor in a multi-user chat environment is the occupant, who can be said to be located "in" a multi-user chat room and to participate in the discussions held in that room (for the purposes of this specification, participants and visitors are considered to be "mere" occupants, since they possess no administrative privileges). As will become clear, the protocol elements proposed in this document to fulfill the occupant use cases fall into three categories:
+-
+
existing "groupchat 1.0" protocol for minimal functionality
+ straightforward applications of the "groupchat 1.0" protocol, for example to handle some of the errors related to new room types
+ additional protocol elements to handle functionality not covered by "groupchat 1.0" (room invites, room passwords, extended presence related to room roles and affiliations); these are qualified by the 'http://jabber.org/protocol/muc#user' namespace
+
Note: All client-generated examples herein are presented from the perspective of the service, with the result that all stanzas received by a service contain a 'from' attribute corresponding to the sender's full JID as added by a normal Jabber router or session manager. In addition, normal IQ result stanzas sent upon successful completion of a request (as required by &rfc3920;) are not shown.
+In order to participate in the discussions held in a multi-user chat room, a Jabber user MUST first become an occupant by entering the room. In the old "groupchat 1.0" protocol, this was done by sending presence to &ROOMJID;, where "room" is the room ID, "service" is the hostname of the chat service, and "nick" is the user's desired nickname within the room:
+In this example, a user with a full JID of "hag66@shakespeare.lit/pda" has requested to enter the room "darkcave" on the "macbeth.shakespeare.lit" chat service with a room nickname of "thirdwitch".
+If the user does not specify a room nickname, the service SHOULD return a &badjid; error:
+Compliant multi-user chat services MUST accept the foregoing as a request to enter a room from any Jabber client that knows either the "groupchat 1.0" (GC) protocol or the multi-user chat (MUC) protocol; however, MUC clients SHOULD signal their ability to speak the MUC protocol by including in the initial presence stanza an empty <x/> element qualified by the 'http://jabber.org/protocol/muc' namespace (note the absence of the '#user' fragment):
+Before attempting to enter the room, a MUC-compliant client SHOULD first discover its reserved room nickname (if any) by following the protocol defined in the Discovering Reserved Room Nickname section of this document.
+If the service is able to add the user to the room, it MUST send presence from all the existing occupants' room JIDs to the new occupant's full JID, including extended presence information about roles in an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'role' attribute set to a value of "moderator", "participant", or "visitor", and with the 'affiliation' attribute set to a value of "owner", "admin", "member", or "none" as appropriate:
+In this example, the user from the previous example has entered the room, by which time two other people had already entered the room: a user with a room nickname of "firstwitch" (who is a room owner) and a user with a room nickname of "secondwitch" (who is a room admin).
+The service MUST also send presence from the new occupant's room JID to the full JIDs of all the occupants (including the new occupant):
+In this example, initial room presence is being sent from the new occupant (thirdwitch) to all occupants, including the new occupant. As shown in the last stanza, the presence sent by the room to a user from itself as an occupant SHOULD include a status code of 110 so that the user knows this presence refers to itself as an occupant.
+The service MAY rewrite the new occupant's roomnick (e.g., if roomnicks are locked down). If the service does not accept the new occupant's requested roomnick but instead assigns a new roomnick, it MUST include a status code of "210" in the presence broadcast that it sends to the new occupant.
+Note: The order of the presence stanzas sent to the new occupant is important. The service MUST first send the complete list of the existing occupants to the new occupant and only then send the new occupant's own presence to the new occupant. This helps the client know when it has received the complete "room roster".
+After sending the presence broadcast (and only after doing so), the service may then send discussion history, live messages, presence updates, and other in-room traffic.
+The following table summarizes the initial default roles that a service should set based on the user's affiliation (there is no role associated with the "outcast" affiliation, since such users are not allowed to enter the room).
+| Room Type | +None | +Member | +Admin | +Owner | +
|---|---|---|---|---|
| Moderated | +Visitor | +Participant | +Moderator | +Moderator | +
| Unmoderated | +Participant | +Participant | +Moderator | +Moderator | +
| Members-Only | +N/A * | +Participant | +Moderator | +Moderator | +
| Open | +Participant | +Participant | +Moderator | +Moderator | +
* Entry is not permitted.
+If the room is non-anonymous, the service MUST send the new occupant's full JID to all occupants using extended presence information in an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with a 'jid' attribute specifying the occupant's full JID:
+If the user is entering a room that is non-anonymous (i.e., which informs all occupants of each occupant's full JID as shown above), the service SHOULD allow the user to enter the room but MUST also warn the user that the room is not anonymous. This SHOULD be done by including a status code of "100" in the initial presence that the room sends to the new occupant:
+However, it MAY done by sending a message of type "groupchat" to the new occupant containing an <x/> child with a <status/> element that has the 'code' attribute set to a value of "100":
+The inclusion of the status code assists clients in presenting their own notification messages (e.g., information appropriate to the user's locality).
+If the room is semi-anonymous, the service MUST send the new occupant's full JID in the format shown above only to those occupants with a role of "moderator".
+(Note: All subsequent examples include the 'jid' attribute for each <item/> element, even though this information is not sent to non-moderators in semi-anonymous rooms.)
+If the room requires a password and the user did not supply one (or the password provided is incorrect), the service MUST deny access to the room and inform the user that they are unauthorized; this is done by returning a presence stanza of type "error" specifying a ¬authorized; error:
+Passwords SHOULD be supplied with the presence stanza sent when entering the room, contained within an <x/> element qualified by the 'http://jabber.org/protocol/muc' namespace and containing a <password/> child. Passwords are to be sent as cleartext; no other authentication methods are supported at this time, and any such authentication or authorization methods shall be defined in a separate specification (see the Security Considerations section of this document).
+If the room is members-only but the user is not on the member list, the service MUST deny access to the room and inform the user that they are not allowed to enter the room; this is done by returning a presence stanza of type "error" specifying a ®istration; error condition:
+If the user has been banned from the room (i.e., has an affiliation of "outcast"), the service MUST deny access to the room and inform the user of the fact that he or she is banned; this is done by returning a presence stanza of type "error" specifying a &forbidden; error condition:
+If the room already contains another user with the nickname desired by the user seeking to enter the room (or if the nickname is reserved by another user on the member list), the service MUST deny access to the room and inform the user of the conflict; this is done by returning a presence stanza of type "error" specifying a &conflict; error condition:
+However, if the bare JID (&BAREJID;) of the present occupant matches the bare JID of the user seeking to enter the room, then the service SHOULD allow entry to the user, so that the user has two (or more) in-room "sessions" with the same roomnick, one for each resource. If a service allows more than one occupant with the same bare JID and the same room nickname, it SHOULD route in-room messages to all of the user's resources and allow all of the user's resources to send messages to the room; it is up to the implementation to determine how to appropriately handle presence from the user's resources and how to route private messages to all or only one resource (based on presence priority or some other algorithm).
+If the room has reached its maximum number of users, the service SHOULD deny access to the room and inform the user of the restriction; this is done by returning a presence stanza of type "error" specifying a &unavailable; error condition:
+Alternatively, the room could kick an "idle user" in order to free up space. Also, a room MUST always allow entry by a room admin or owner.
+If a user attempts to enter a room while it is "locked" (i.e., before the room creator provides an initial configuration and therefore before the room officially exists), the service MUST refuse entry and return an ¬found; error to the user:
+If the room does not already exist when the user seeks to enter it, the service SHOULD create it; however, this is not required, since an implementation or deployment MAY choose to restrict the privilege of creating rooms. For details, see the Creating a Room section of this document.
+If the user is entering a room in which the discussions are logged to a public archive (often accessible via HTTP), the service SHOULD allow the user to enter the room but MUST also warn the user that the discussions are logged. This SHOULD be done by including a status code of "170" in the initial presence that the room sends to the new occupant:
+After sending initial presence as shown above, a room MAY send discussion history to the new occupant. (The room MUST NOT send any discussion history before it finishes sending room presence as specified in the Presence Broadcast section of this document.) Whether such history is sent, and how many messages comprise the history, shall be determined by the chat service implementation or specific deployment.
+Discussion history messages MUST be stamped with extended information qualified by the 'jabber:x:delay' namespace (see &jep0091;) to indicate that they are sent with delayed delivery and specify the times at which they were originally sent. The 'from' attribute SHOULD be the full JID of the original sender in non-anonymous rooms, but MUST NOT be in semi-anonymous rooms (the 'from' attribute SHOULD be set to the room JID in semi-anonymous rooms). The service SHOULD send all discussion history messages before delivering any "live" messages sent after the user enters the room.
+A user MAY want to manage the amount of discussion history provided on entering a room (perhaps because the user is on a low-bandwidth connection or is using a small-footprint client). This MUST be accomplished by including a <history/> child in the initial presence stanza sent when joining the room. There are four allowable attributes for this element:
+| Attribute | +Datatype | +Meaning | +
|---|---|---|
| maxchars | +int | +Limit the total number of characters in the history to "X" (where the character count is the characters of the complete XML stanzas, not only their XML character data). | +
| maxstanzas | +int | +Limit the total number of messages in the history to "X". | +
| seconds | +int | +Send only the messages received in the last "X" seconds. | +
| since | +dateTime | +Send only the messages received since the datetime specified (which MUST conform to the DateTime profile specified in &jep0082;). | +
The service MUST send the smallest amount of traffic that meets any combination of the above criteria, taking into account service-level and room-level defaults. The service MUST send complete message stanzas only (i.e., it MUST not literally truncate the history at a certain number of characters, but MUST send the largest number of complete stanzas that results in a number of characters less than or equal to the 'maxchars' value specified). If the client wishes to receive no history, it MUST set the 'maxchars' attribute to a value of "0" (zero).
+The following examples illustrate the use of this protocol.
+Obviously the service SHOULD NOT return all messages sent in the room since the beginning of the Unix era, and SHOULD appropriately limit the amount of history sent to the user based on service or room defaults.
+In order to exit a multi-user chat room, an occupant sends a presence stanza of type "unavailable" to the &ROOMJID; it is currently using in the room.
+The service MUST then send presence stanzas of type "unavailable" from the departing occupant's room JID to the full JIDs of the departing occupant and of the remaining occupants:
+Presence stanzas of type "unavailable" reflected by the room MUST contain extended presence information about roles and affiliations, and MAY also contain normal <status/> information (which enables occupants to provide custom exit messages if desired).
+Normal presence stanza generation rules apply as defined in &xmppim;, so that if the user sends a general unavailable presence stanza, the user's server will broadcast that stanza to the &ROOMJID; to which the user's client has sent directed presence.
+If the room is not persistent and this occupant is the last to exit, the service is responsible for destroying the room.
+A common feature of multi-user chat rooms is the ability for an occupant to change his or her nickname within the room. In MUC this is done by sending updated presence information to the room, specifically by sending presence to a new room JID in the same room (changing only the resource identifier in the room JID).
+The service then sends two presence stanzas to the full JID of each occupant (including the occupant who is changing his or her room nickname), one of type "unavailable" for the old nickname and one indicating availability for the new nickname. The unavailable presence MUST contain the new nickname and an appropriate status code (namely 303) as extended presence information in an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace so that Jabber clients are able to provide relevant hints to occupants regarding the nickname change if desired.
+If the user attempts to change his or her room nickname to a room nickname that is already in use by another user (or that is reserved by another user affiliated with the room, e.g., a member or owner), the service MUST deny the nickname change request and inform the user of the conflict; this is done by returning a presence stanza of type "error" specifying a &conflict; error condition:
+However, if the bare JID (&BAREJID;) of the present occupant matches the bare JID of the user seeking to change his or her nickname, then the service MAY allow the nickname change. See the Nickname Conflict section of this document for details.
+If the user attempts to change his or her room nickname but room nicknames are "locked down", the service MUST deny the nickname change request and return a presence stanza of type "error" specifying a ¬acceptable; error condition:
+The use SHOULD then discover its reserved nickname as specified in the Discovering Reserved Room Nickname section of this document.
+In multi-user chat systems such as IRC, one common use for changing one's room nickname is to indicate a change in one's availability (e.g., changing one's room nickname to "thirdwitch|away"). In Jabber, availability is of course noted by a change in presence (specifically the <show/> and <status/> elements), which can provide important context within a chatroom. An occupant changes availability status within the room by sending the updated presence to its &ROOMJID;.
+The service then sends a presence stanza from the occupant changing his or her presence to the full JID of each occupant, including extended presence information about the occupant's role and full JID to those with privileges to view such information:
+It can be useful to invite another user to a room in which one is an occupant. To do this, a MUC client MUST send XML of the following form to the &ROOM; itself (the reason is OPTIONAL and the message MUST NOT possess a 'type' attribute; the service MAY ignore or reject invites that possess a 'type' attribute):
+The &ROOM; itself MUST then add a 'from' address to the <invite/> element whose value is the bare JID (or, optionally, the room JID) of the invitor and send the invitation to the invitee captured in the 'to' address (the service SHOULD include a message body explaining the invitation or containing the reason, for the sake of older clients; in addition, the room SHOULD add the password if the room is password-protected):
+If the room is members-only, the service MAY also add the invitee to the member list. (Note: Invitation privileges in members-only rooms SHOULD be restricted to room admins; if a member without privileges to edit the member list attempts to invite another user, the service SHOULD return a &forbidden; error to the occupant; for details, see the Modifying the Member List section of this document.)
+If the invitor supplies a non-existent JID, the room SHOULD return an ¬found; error to the invitor.
+The invitee MAY choose to formally decline (as opposed to ignore) the invitation; and this is something that the sender may want to be informed about. In order to decline the invitation, the invitee MUST send a message of the following form to the &ROOM; itself:
+ +It may be wondered why the invitee does not send the decline message directly to the invitor. The main reason is that certain implementations MAY choose to base invitations on room JIDs rather than bare JIDs (so that, for example, an occupant could invite someone from one room to another without knowing that person's bare JID). Thus the service MUST handle both the invites and declines.
+Sometimes it is desirable to convert a one-to-one chat into a multi-user conference. The process flow is shown in the following examples.
+First, two users begin a one-to-one chat.
+Now the first person decides to include a third person in the discussion, so she (or, more precisely, her client) does the following:
+-
+
- Creates a new room +
- Optionally sends history of the one-to-one chat to the room +
- Sends an invitation to the second person and the third person, including a <continue/> flag. +
Note: The new room SHOULD be non-anonymous, MAY be an instant room as specified in the Creating an Instant Room section of this document, and MAY have a unique room name received from the service as specified in the Requesting a Unique Room Name section of this document.
+Note: Use of the Delayed Delivery protocol enables the room creator to specify the datetime of each message from the one-to-one chat history (via the 'stamp' attribute), as well as the JID of the original sender of each message (via the 'from' attribute). The room creator SHOULD send the complete one-to-one chat history before inviting additional users to the room, and SHOULD also send as history any messages appearing in the one-to-one chat interface after joining the room and before the second person joins the room; if the one-to-one history is especially large, the sending client may want to send the history over a few seconds rather than all at once (to avoid triggering rate limits). The service SHOULD NOT add its own delay elements (as described in the Discussion History section of this document) to prior chat history messages received from the room owner.
+Note: Since the invitor's client knows the full JID of the person with whom the invitor was having a one-to-one chat, it SHOULD include the full JID (rather than the bare JID) in the invitation.
+The invitations are delivered to the invitees:
+When the client being used by <wiccarocks@shakespeare.lit/laptop> receives the invitation, it SHOULD auto-join the room or prompt the user whether to join (subject to user preferences) and then seamlessly convert the existing one-to-one chat window into a multi-user conferencing window:
+Note: The fact that the messages come from the &ROOM; itself rather than &ROOMJID; is a clue to the receiving client that these messages are prior chat history, since any message from a room occupant will have a 'from' address equal to the sender's room JID.
+If allowed in accordance with room configuration, a mere occupant MAY be allowed to change the subject in a room. For details, see the Modifying the Room Subject section of this document.
+Since each occupant has a unique room JID, an occupant MAY send a "private message" to a selected occupant via the service by sending a message to the occupant's room JID. The message type SHOULD be "chat" and MUST NOT be "groupchat", but MAY be left unspecified (i.e., a normal message). This privilege SHOULD be allowed to any occupant (even a visitor in a moderated room).
+The service is responsible for changing the 'from' address to the sender's room JID and delivering the message to the intended recipient's full JID.
+If the sender attempts to send a private message of type "groupchat" to a particular occupant, the service MUST refuse to deliver the message (since the recipient's client would expect in-room messages to be of type "groupchat") and return a &badrequest; error to the sender:
+If the sender attempts to send a private message to a room JID that does not exist, the service MUST return an ¬found; error to the sender.
+If the sender is not an occupant of the room in which the intended recipient is visiting, the service MUST return a ¬acceptable; error to the sender.
+An occupant sends a message to all other occupants in the room by sending a message of type "groupchat" to the &ROOM; itself (a service MAY ignore or reject messages that do not have a type of "groupchat"). In a moderated room, this privilege is restricted to occupants with a role of participant or higher.
+If the sender has voice in the room (this is the default except in moderated rooms), the service MUST change the 'from' attribute to the sender's room JID and reflect the message out to the full JID of each occupant.
+If the sender is a visitor (i.e., does not have voice in a moderated room), the service MAY return a &forbidden; error to the sender and MUST NOT reflect the message to all occupants. If the sender is not an occupant of the room, the service SHOULD return a ¬acceptable; error to the sender and SHOULD NOT reflect the message to all occupants; the only exception to this rule is that an implementation MAY allow users with certain privileges (e.g., a room owner, room admin, or service-level admin) to send messages to the room even if those users are not occupants.
+An implementation MAY allow an unaffiliated user (in a moderated room, normally a participant) to register with a room and thus become a member of the room (conversely, an implementation MAY restrict this privilege and allow only room admins to add new members). In particular, it is not possible to join a members-only room without being on the member list, so an entity may need to request membership in order to join such a room.
+If allowed, this functionality SHOULD be implemented by enabling a user to send a request for registration requirements to the room qualified by the 'jabber:iq:register' namespace as described in &jep0077;:
+If the user requesting registration requirements is not allowed to register with the room (e.g., because that privilege has been restricted), the room MUST return a ¬allowed; error to the user. If the user is already registered, the room MUST reply with an IQ stanza of type "result" that contains an empty <register/> element as described in JEP-0077. If the room does not exist, the service MUST return an ¬found; error.
+Otherwise, the room MUST then return a Data Form to the user (as described in &jep0004;). The information required to register MAY vary by implementation or deployment and is not fully specified in this document (e.g., the fields registered by this document for the 'http://jabber.org/protocol/muc#register' FORM_TYPE may be supplemented in the future via the mechanisms described in the Field Standardization section of this document). The following can be taken as a fairly typical example:
+The user SHOULD then submit the form:
+If the desired room nickname is already reserved for that room, the room MUST return a &conflict; error to the user:
+If the room or service does not support registration, it MUST return a &unavailable; error to the user:
+If the user did not include a valid data form, the room MUST return a &badrequest; error to the user:
+Otherwise, the room MUST inform the user that the registration request was successfully received:
+After the user submits the form, the service MAY request that the submission be approved by a room admin/owner (see the Approving Registration Requests section of this document) or MAY immediately add the user to the member list by changing the user's affiliation from "none" to "member". If the service changes the user's affiliation and the user is in the room, it MUST send updated presence from this individual to all occupants, indicating the change in affiliation by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "member".
+If a user has registered with a room, the room MAY choose to restrict the user to use of the registered nickname only in that room. If it does so, it SHOULD return a ¬acceptable; error to the user if the user attempts to join the room with a roomnick other than the user's registered roomnick (this enables a room to "lock down" roomnicks for consistent identification of occupants).
+A user MAY have a reserved room nickname, for example through explicit room registration, database integration, or nickname "lockdown". A user SHOULD discover his or her reserved nickname before attempting to enter the room. This is done by sending a Service Discovery information request to the room JID while specifying a well-known Service Discovery node of "x-roomuser-item".
+It is OPTIONAL for a multi-user chat service to support the foregoing service discovery node. If the room or service does not support the foregoing service discovery node, it MUST return a &feature; error to the user. If it does and the user has a registered nickname, it MUST return the nickname to the user as the value of the 'name' attribute of a Service Discovery <identity/> element (for which the category/type SHOULD be "conference/text"):
+If the user does not have a registered nickname, the room MUST return a service discovery &QUERY; element that is empty (in accordance with JEP-0030).
+Even if a user has registered one room nickname, the service SHOULD allow the user to specify a different nickname on entering the room (e.g., in order to join from different client resources), although the service MAY choose to "lock down" nicknames and therefore deny entry to the user, including a ¬acceptable; error. The service MUST NOT return an error to the user if his or her client sends the foregoing request after having already joined the room, but instead SHOULD reply as described above.
+If another user attempts to join the room with a nickname reserved by the first user, the service MUST deny entry to the second user and return a &conflict; error as previously described.
+It is not possible for a visitor to speak (i.e., send a message to all occupants) in a moderated room. To request voice, a visitor SHOULD send a &MESSAGE; stanza containing a data form to the room itself, where data form contains only a 'muc#role' field with a value of "participant".
+The service then SHOULD forward the request to the room moderator(s) as described in the Approving Voice Requests section of this document.
+A moderator has privileges to perform certain actions within the room (e.g., to change the roles of some occupants) but does not have rights to change persistent information about affiliations (which may be changed only by an admin or owner) or defining information about the room. Exactly which actions may be performed by a moderator is subject to configuration. However, for the purposes of the MUC framework, moderators are stipulated to have privileges to perform the following actions:
+-
+
- discover an occupant's full JID in a semi-anonymous room (occurs by default as shown above) +
- modify the subject +
- kick a participant or visitor from the room +
- grant or revoke voice in a moderated room +
- modify the list of occupants who have voice in a moderated room +
These features shall be implemented with a request/response exchange using <iq/> elements that contain children qualified by the 'http://jabber.org/protocol/muc#admin' namespace. The examples below illustrate the protocol interactions to implement the desired functionality. (Except where explicitly noted below, any of the following administrative requests MUST be denied if the <user@host> of the 'from' address of the request does not match the bare JID portion of one of the moderators; in this case, the service MUST return a &forbidden; error.)
+A common feature of multi-user chat rooms is the ability to change the subject within the room. By default, only users with a role of "moderator" SHOULD be allowed to change the subject in a room (although this SHOULD be configurable, with the result that a mere participant or even visitor may be allowed to change the subject if desired). The subject is changed by sending a message of type "groupchat" to the &ROOM;, containing no body but a <subject/> that specifies the new subject:
+If a MUC service receives such a message, it MUST reflect the message to all other occupants with a 'from' address equal to the room JID that corresponds to the sender of the subject change:
+In addition, the room SHOULD include the last subject change in the discussion history sent when a new occupant joins the room.
+A MUC client that receives such a message MAY choose to display an in-room message, such as the following:
+If someone without appropriate privileges attempts to change the room subject, the service MUST return a message of type "error" specifying a &forbidden; error condition:
+A moderator has permissions kick certain kinds of occupants from a room (which occupants are "kickable" depends on service provisioning, room configuration, and the moderator's affiliation -- see below). The kick is normally performed based on the occupant's room nickname (though it MAY be based on the full JID) and is completed by setting the role of a participant or visitor to a value of "none".
+The service MUST remove the kicked occupant by sending a presence stanza of type "unavailable" to each kicked occupant, including status code 307 in the extended presence information, optionally along with the reason (if provided) and the bare JID of the user who initiated the kick.
+The inclusion of the status code assists clients in presenting their own notification messages (e.g., information appropriate to the user's locality). The optional inclusion of the reason and actor enable the kicked user to understand why he or she was kicked, and by whom if the kicked occupant would like to discuss the matter.
After removing the kicked occupant(s), the service MUST then inform the moderator of success:
+After informing the moderator, the service MUST then inform all of the remaining occupants that the kicked occupant is no longer in the room by sending presence stanzas of type "unavailable" from the individual's roomnick (&ROOMJID;) to all the remaining occupants (just as it does when occupants exit the room of their own volition), including the status code and optionally the reason and actor.
+A user cannot be kicked by a moderator with a lower affiliation. Therefore, if a moderator who is a participant attempts to kick an admin or a moderator who is a participant or admin attempts to kick an owner, the service MUST deny the request and return a ¬allowed; error to the sender:
+If a moderator attempts to kick himself, the service MAY deny the request and return a &conflict; error to the sender. (Although the act of kicking oneself may seem odd, it is common in IRC as a way of apologizing for one's actions in the room.)
+In a moderated room, a moderator may want to manage who does and does not have "voice" in the room (i.e., the ability to send messages to all occupants). Voice is granted based on the visitor's room nickname, which the service will convert into the visitor's full JID internally. The moderator grants voice to a visitor by changing the visitor's role to "participant" (the <reason/> element is optional):
+The service MUST then inform the moderator of success:
+The service MUST then send updated presence from this individual's &ROOMJID; to all occupants, indicating the addition of voice privileges by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'role' attribute set to a value of "participant".
+In a moderated room, a moderator may want to revoke a participant's privileges to speak. The moderator can revoke voice from a participant by changing the participant's role to "visitor":
+The service MUST then inform the moderator of success:
+The service MUST then send updated presence from this individual to all occupants, indicating the removal of voice privileges by sending a presence element that contains an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'role' attribute set to a value of "visitor".
+A moderator MUST NOT be able to revoke voice from a user whose affiliation is at or above the moderator's level. In addition, a service MUST NOT allow the voice privileges of an admin or owner to be removed by anyone. If a moderator attempts to revoke voice privileges from such a user, the service MUST deny the request and return a ¬allowed; error to the sender along with the offending item(s):
+A moderator in a moderated room may want to modify the voice list. To do so, the moderator first requests the voice list by querying the room for all occupants with a role of 'participant'.
+The service MUST then return the voice list to the moderator; each item MUST include the 'nick' and 'role' attributes and SHOULD include the 'affiliation' and 'jid' attributes:
+The moderator MAY then modify the voice list. In order to do so, the moderator MUST send the changed items (i.e., only the "delta") back to the service; each item MUST include the 'nick' attribute and 'role' attribute (normally set to a value of "participant" or "visitor") but SHOULD NOT include the 'jid' attribute and MUST NOT include the 'affiliation' attribute (which is used to manage affiliations such as owner rather than the participant role):
+The service MUST then inform the moderator of success:
+The service MUST then send updated presence for any affected individuals to all occupants, indicating the change in voice privileges by sending the appropriate extended presence stanzas as described in the foregoing use cases.
+As noted, voice privileges cannot be revoked from a room owner or room admin, nor from any user with a higher affiliation than the moderator making the request. If a room admin attempts to revoke voice privileges from such a user by modifying the voice list, the service MUST deny the request and return a ¬allowed; error to the sender:
+As noted in the Requesting Voice section of this document, when a service receives a request for voice from an occupant it SHOULD forward that request to the room moderator(s). To do so, the service SHOULD send a &MESSAGE; stanza to the room moderator(s), where the &MESSAGE; stanza contains a data form asking for approval or denial of the request, as shown below.
+In order to approve the request, a moderator shall submit the form:
+If a moderator approves the voice request, the service shall grant voice to the occupant and send a presence update as described in the Granting Voice to a Visitor section of this document.
+A room administrator has privileges to modify persistent information about user affiliations (e.g., by banning users) and to grant and revoke moderator privileges, but does not have rights to change the defining features of the room, which are the sole province of the room owner(s). Exactly which actions may be performed by a room admin will be subject to configuration. However, for the purposes of the MUC framework, room admins are stipulated to at a minimum have privileges to perform the following actions:
+-
+
- ban a user from the room +
- modify the list of users who are banned from the room +
- grant or revoke membership +
- modify the member list +
- grant or revoke moderator privileges +
- modify the list of moderators +
These features shall be implemented with a request/response exchange using <iq/> elements that contain children qualified by the 'http://jabber.org/protocol/muc#admin' namespace. The examples below illustrate the protocol interactions that implement the desired functionality. (Except where explicitly noted below, any of the following administrative requests MUST be denied if the <user@host> of the 'from' address of the request does not match the bare JID of one of the room admins; in this case, the service MUST return a &forbidden; error.)
+An admin or owner can ban one or more users from a room. The ban MUST be performed based on the occupant's bare JID. In order to ban a user, an admin MUST change the user's affiliation to "outcast".
+The service MUST add that bare JID to the ban list, SHOULD remove the outcast's nickname from the list of registered nicknames, and MUST inform the admin or owner of success:
+The service MUST also remove any banned users who are in the room by sending a presence stanza of type "unavailable" to each banned occupant, including status code 301 in the extended presence information, optionally along with the reason (if provided) and the bare JID of the user who initiated the ban.
+The inclusion of the status code assists clients in presenting their own notification messages (e.g., information appropriate to the user's locality). The optional inclusion of the reason and actor enable the banned user to understand why he or she was banned, and by whom if the banned user would like to discuss the matter.
+The service MUST then inform all of the remaining occupants that the banned user is no longer in the room by sending presence stanzas of type "unavailable" from the banned user to all remaining occupants (just as it does when occupants exit the room of their own volition), including the status code and optionally the reason and actor:
+As with Kicking an Occupant, a user cannot be banned by an admin with a lower affiliation. Therefore, if an admin attempts to ban an owner, the service MUST deny the request and return a ¬allowed; error to the sender:
+If an admin or owner attempts to ban himself, the service MUST deny the request and return a &conflict; error to the sender. (Note: This is different from the recommended service behavior on kicking oneself, which a service may allow.)
+A room admin may want to modify the ban list. Note: The ban list is always based on a user's bare JID, although a nick (perhaps the last room nickname associated with that JID) MAY be included for convenience. To modify the list of banned JIDs, the admin first requests the ban list by querying the room for all users with an affiliation of 'outcast'.
+The service MUST then return the list of banned users to the admin; each item MUST include the 'affiliation' and 'jid' attributes but SHOULD NOT include the 'nick' and 'role' attributes:
+The admin MAY then modify the ban list. In order to do so, the admin MUST send the changed items (i.e., only the "delta") back to the service; each item MUST include the 'affiliation' attribute (normally set to a value of "outcast" to ban or "none" to remove ban) and 'jid' attribute but SHOULD NOT include the 'nick' attribute and MUST NOT include the 'role' attribute (which is used to manage roles such as participant rather than the outcast affiliation); in addition, the reason and actor elements are OPTIONAL:
+After updating the ban list, the service MUST inform the admin of success:
+The service MUST then remove the affected occupants (if they are in the room) and send updated presence (including the appropriate status code) from them to all the remaining occupants as described in the "Banning a User" use case. (The service SHOULD also remove each banned user's reserved nickname from the list of reserved roomnicks, if appropriate.)
+When an entity is banned from a room, an implementation SHOULD match JIDs in the following order (these matching rules are the same as those defined for privacy lists in RFC 3921):
+-
+
- <user@domain/resource> (only that resource matches) +
- <user@domain> (any resource matches) +
- <domain/resource> (only that resource matches) +
- <domain> (the domain itself matches, as does any user@domain, domain/resource, or address containing a subdomain) +
Some administrators may wish to ban all users associated with a specific domain from all rooms hosted by a MUC service. Such functionality is a service-level feature and is therefore out of scope for this document (but see &jep0133;).
+An admin can grant membership to a user; this is done by changing the user's affiliation to "member" (normally based on nick if the user is in the room, or on bare JID if not; in either case, if the nick is provided, that nick becomes the user's default nick in the room if that functionality is supported by the implementation):
+The service MUST add the user to the member list and then inform the admin of success:
+If the user is in the room, the service MUST then send updated presence from this individual to all occupants, indicating the granting of membership by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "member".
+An admin may want to revoke a user's membership; this is done by changing the user's affiliation to "none":
+The service MUST remove the user from the member list and then inform the moderator of success:
+The service MUST then send updated presence from this individual to all occupants, indicating the loss of membership by sending a presence element that contains an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "none".
+If the room is members-only, the service MUST remove the user from the room, including a status code of 321 to indicate that the user was removed because of an affiliation change, and inform all remaining occupants:
+In the context of a members-only room, the member list is essentially a "whitelist" of people who are allowed to enter the room. Anyone who is not a member is effectively banned from entering the room, even if their affiliation is not "outcast".
+In the context of an open room, the member list is simply a list of users (bare JID and reserved nick) who are registered with the room. Such users may appear in a room roster, have their room nickname reserved, be returned in search results or FAQ queries, and the like.
+It is RECOMMENDED that only room admins have the privilege to modify the member list in members-only rooms. To do so, the admin first requests the member list by querying the room for all users with an affiliation of "member":
+(A service SHOULD also return the member list to any occupant in a members-only room; i.e., it SHOULD NOT generate a &forbidden; error when a member in the room requests the member list. This functionality may assist clients in showing all the existing members even if some of them are not in the room, e.g. to help a member determine if another user should be invited.)
+The service MUST then return the full member list to the admin qualified by the 'http://jabber.org/protocol/muc#admin' namespace; each item MUST include the 'affiliation' and 'jid' attributes and MAY include the 'nick' and 'role' attributes for each members that is currently an occupant.
+The admin MAY then modify the member list. In order to do so, the admin MUST send the changed items (i.e., only the "delta") to the service; each item MUST include the 'affiliation' attribute (normally set to a value of "member" or "none") and 'jid' attribute but SHOULD NOT include the 'nick' attribute and MUST NOT include the 'role' attribute (which is used to manage roles such as participant rather than the member affiliation):
+The service MUST modify the member list and then inform the moderator of success:
+The service MUST change the affiliation of any affected user. If the user has been removed from the member list, the service MUST change the user's affiliation from "member" to "none". If the user has been added to the member list, the service MUST change the user's affiliation to "member".
+If a removed member is currently in a members-only room, the service SHOULD kick the occupant by changing the removed member's role to "none" and send appropriate presence to the removed member as previously described. No matter whether the removed member was in or out of a members-only room, the service MUST subsequently refuse entry to the user.
+For all room types, the service MUST send updated presence from this individual to all occupants, indicating the change in affiliation by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "none".
+In addition, the service SHOULD send an invitation to any user who has been added to the member list of a members-only room if the user is not currently affiliated with the room, for example as an admin or owner (such a user would by definition not be in the room; note also that this example includes a password but not a reason -- both child elements are OPTIONAL):
+While only admins and owners SHOULD be allowed to modify the member list, an implementation MAY provide a configuration option that opens invitation privileges to any member of a members-only room. In such a situation, any invitation sent SHOULD automatically trigger the addition of the invitee to the member list. However, if invitation privileges are restricted to admins and a mere member attempts to a send an invitation, the service MUST deny the invitation request and return a &forbidden; error to the sender:
+Invitations sent through an open room MUST NOT trigger the addition of the invitee to the member list.
+If a user is added to the member list of an open room and the user is in the room, the service MUST send updated presence from this individual to all occupants, indicating the change in affiliation by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "member".
+An admin may want to grant moderator privileges to a participant or visitor; this is done by changing the user's role to "moderator":
+The service MUST add the user to the moderator list and then inform the admin of success:
+The service MUST then send updated presence from this individual to all occupants, indicating the addition of moderator privileges by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'role' attribute set to a value of "moderator".
+An admin may want to revoke a user's moderator privileges. An admin MAY revoke moderator privileges only from a user whose affiliation is "member" or "none" (i.e., not from an owner or admin). The privilege is revoked by changing the user's role to "participant":
+The service MUST remove the user from the moderator list and then inform the admin of success:
+The service MUST then send updated presence from this individual to all occupants, indicating the removal of moderator privileges by sending a presence element that contains an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'role' attribute set to a value of "participant".
+As noted, an admin MUST NOT be allowed to revoke moderator privileges from a user whose affiliation is "owner" or "admin". If an admin attempts to revoke moderator privileges from such a user, the service MUST deny the request and return a ¬allowed; error to the sender:
+An admin may want to modify the moderator list. To do so, the admin first requests the moderator list by querying the room for all users with a role of 'moderator'.
+The service MUST then return the moderator list to the admin; each item MUST include the 'jid', 'nick', and 'role' attributes and SHOULD include the 'affiliation' attribute:
+The admin MAY then modify the moderator list. In order to do so, the admin MUST send the changed items (i.e., only the "delta") back to the service; each item MUST include the 'jid' attribute and 'role' attribute (normally set to a value of "member" or "participant") but SHOULD NOT include the 'nick' attribute and MUST NOT include the 'affiliation' attribute (which is used to manage affiliations such as admin rather than the moderator role):
+The service MUST modify the moderator list and then inform the admin of success:
+The service MUST then send updated presence for any affected individuals to all occupants, indicating the change in moderator privileges by sending the appropriate extended presence stanzas as described in the foregoing use cases.
+As noted, moderator privileges cannot be revoked from a room owner or room admin. If a room admin attempts to revoke moderator privileges from such a user by modifying the moderator list, the service MUST deny the request and return a ¬allowed; error to the sender:
+If a service does not automatically accept requests to register with a room, it MAY provide a way for room admins to approve or deny registration requests over Jabber (alternatively, it could provide a web interface or some other admin tool). The simplest way to do so is for the service to send a &MESSAGE; stanza to the room admin(s) when the registration request is received, where the &MESSAGE; stanza contains a Data Form asking for approval or denial of the request. The following Data Form is RECOMMENDED but implementations MAY use a different form entirely, or supplement the following form with additional fields.
+If the admin approves the registration request, the service shall register the user with the room.
+More advanced registration approval mechanisms (e.g., retrieving a list of registration requests using &jep0050; as is done in &jep0060;) are out of scope for this document.
+Every room MUST have at least one owner, and that owner (or a successor) is a long-lived attribute of the room for as long as the room exists (e.g., the owner does not lose ownership on exiting a persistent room). This document assumes that the (initial) room owner is the individual who creates the room and that only a room owner has the right to change defining room configuration settings such as the room type. Ideally, room owners will be able to specify not only the room types (password-protected, members-only, etc.) but also certain attributes of the room as listed in the Requirements section of this document. In addition, it would be good if an owner were able to specify the JIDs of other owners, but that shall be determined by the implementation.
+In order to provide the necessary flexibility for a wide range of configuration options, Data Forms (JEP-0004) shall be used for room configuration, triggered by use of the 'http://jabber.org/protocol/muc' namespace. That is, if an entity does not include the MUC namespace in its room join/create request, then the service shall create the room and not wait for configuration via Data Forms before creating the room (this ensures backwards-compatibility with the old "groupchat 1.0" protocol); however, if the room join/create request includes the MUC extension, then the service shall require configuration via Data Forms before creating and unlocking the room.
+Note: The configuration options shown below address all of the features and room types listed in the requirements section of this document; however, the exact configuration options and form layout shall be determined by the implementation or specific deployment. Also, these are examples only and are not intended to define the only allowed or required configuration options for rooms. A given implementation or deployment MAY choose to provide additional configuration options (profanity filters, setting the default language for a room, message logging, etc.), which is why the use of the 'jabber:x:data' protocol is valuable here.
+The privilege to create rooms MAY be restricted to certain users or MAY be reserved to an administrator of the service. If access is restricted and a user attempts to create a room, the service MUST return a ¬allowed; error:
+If access is not restricted, the service MUST allow the user to create a room as described below.
+From the perspective of room creation, there are in essence two kinds of rooms:
+-
+
"Instant rooms" -- these are available for immediate access and are automatically created based on some default configuration.
+ "Reserved rooms" -- these are manually configured by the room creator before anyone is allowed to enter.
+
The workflow for creating and configuring such rooms is as follows:
+-
+
The user MUST send presence to &ROOMJID; and signal his or her support for the Multi-User Chat protocol by including extended presence information in an empty <x/> child element qualified by the 'http://jabber.org/protocol/muc' namespace (note the lack of an '#owner' or '#user' fragment).
+ If this user is allowed to create a room and the room does not yet exist, the service MUST create the room according to some default configuration, assign the requesting user as the initial room owner, and add the owner to the room but not allow anyone else to enter the room (effectively "locking" the room). The initial presence stanza received by the owner from the room MUST include extended presence information indicating the user's status as an owner and acknowledging that the room has been created (via status code 201) and is awaiting configuration.
+ If the initial room owner would like to create and configure a reserved room, the room owner MUST then request a configuration form by sending an IQ stanza of type "get" to the room containing an empty <query/> element qualified by the 'http://jabber.org/protocol/muc#owner' namespace, then complete Steps 4 and 5. If the room owner would prefer to create an instant room, the room owner MUST send a query element qualified by the 'http://jabber.org/protocol/muc#owner' namespace and containing an empty <x/> element of type "submit" qualified by the 'jabber:x:data' namespace, then skip to Step 6.
+ If the room owner requested a configuration form, the service MUST send an IQ to the room owner containing a configuration form qualified by the 'jabber:x:data' namespace. If there are no configuration options available, the room MUST return an empty query element to the room owner.
+ The initial room owner SHOULD provide a starting configuration for the room (or accept the default configuration) by sending an IQ of type "set" containing the completed configuration form. Alternatively, the room owner MAY cancel the configuration process. (An implementation MAY set a timeout for initial configuration, such that if the room owner does not configure the room within the timeout period, the room owner is assumed to have accepted the default configuration or to have cancelled the configuration process.)
+ Once the service receives the completed configuration form from the initial room owner (or receives a request for an instant room), the service MUST "unlock" the room (i.e., allow other users to enter the room) and send an IQ of type "result" to the room owner. If the service receives a cancellation, it MUST destroy the room.
+
The protocol for this workflow is shown in the examples below.
+First, the Jabber user MUST send presence to the room, including and empty <x/> element qualified by the 'http://jabber.org/protocol/muc' namespace (this is the same stanza sent when seeking to enter a room).
+If the room does not yet exist, the service SHOULD create the room (subject to local policies regarding room creation), assign the bare JID of the requesting user as the owner, add the owner to the room, and acknowledge successful creation of the room by sending a presence stanza of the following form:
+After receiving notification that the room has been created, the room owner needs to decide whether to accept the default room configuration (i.e., create an "instant room") or configure the room to have something other than the default room configuration (i.e., create a "reserved room"). The protocol flows for completing those two use cases are shown in the following sections.
+Note: If the presence stanza sent to a nonexistent room does not include an &X; element qualified by the 'http://jabber.org/protocol/muc' namespace as shown above, the service SHOULD create a default room without delay (i.e., it MUST assume that the client supports "groupchat 1.0" rather than Multi-User Chat and therefore it MUST NOT lock the room while waiting for the room creator to either accept an instant room or configure a reserved room).
+If the initial room owner wants to accept the default room configuration (i.e., create an "instant room"), the room owner MUST decline an initial configuration form by sending an IQ set to the &ROOM; itself containing a &QUERY; element qualified by the 'http://jabber.org/protocol/muc#owner' namespace, where the only child of the &QUERY; is an empty &X; element that is qualified by the 'jabber:x:data' namespace and that possesses a 'type' attribute whose value is "submit":
+The service MUST then unlock the room and allow other entities to join it.
+In some situations (e.g., when Converting a One-to-One Chat Into a Conference), the room creator may want to request a unique room name before attempting to create the room (e.g., to avoid the possibility of a room conflict). In order to facilitate this, a service MAY support the feature described in this section. (If a service does support this feature, it MUST return a feature of "http://jabber.org/protocol/muc#unique" in its response to service discovery information requests.)
+The room creator requests a unique room name by sending an IQ-get to the service itself, containing an empty <unique/> element qualified by the 'http://jabber.org/protocol/muc#unique' namespace:
+If the service supports this feature, it SHOULD return a unique room name as the XML character data of the <unique/> element:
+The service MAY refuse to return a unique room name to entities that are not entitled to create rooms, entities that have sent an excessive number of requests for unique room names, etc.
+The service MAY use any algorithm that ensures the creation of a room name that will be permanently unique in the context of the service (e.g., a SHA-1 hash of the requesting JID, datetime, and random salt).
+The room creator would then use the XML character data of the <unique/> element as the node identifier portion of the room JID it requests:
+If the initial room owner wants to create and configure a reserved room, the room owner MUST request an initial configuration form by sending an IQ get to the &ROOM; itself containing an empty &QUERY; element qualified by the 'http://jabber.org/protocol/muc#owner' namespace:
+If the room does not already exist, the service MUST return an initial room configuration form to the user. (Note: The following example shows a representative sample of configuration options. A full list of x:data fields registered for use in room creation and configuration is maintained by the Jabber Registrar; see the Jabber Registrar Considerations section of this document.)
+Note: The _whois configuration option specifies whether the room is non-anonymous (a value of "anyone"), semi-anonymous (a value of "moderators"), or fully anonmyous (a value of "none", not shown here).
+If there are no configuration options available, the service MUST return an empty query element to the room owner:
+The room owner SHOULD then fill out the form and submit it to the service.
+If room creation is successful, the service MUST inform the new room owner of success:
+If the room creation fails because the specified room configuration options violate one or more service policies (e.g., because the password for a password-protected room is blank), the service MUST return a ¬acceptable; error.
+Alternatively, the room owner MAY cancel the configuration process:
+If the room owner cancels the initial configuration, the service SHOULD destroy the room, making sure to send unavailable presence to the room owner (see the "Destroying a Room" use case for protocol details).
+If the room owner becomes unavailable for any reason before submitting the form (e.g., a lost connection), the service will receive a presence stanza of type "unavailable" from the owner to the owner's &ROOMJID; or to &ROOM; (or both). The service MUST then destroy the room, sending a presence stanza of type "unavailable" from the room to the owner including a <destroy/> element and reason (if provided) as defined in the Destroying a Room section of this document.
+At any time after specifying the initial configuration of the room, a room owner may want to change the configuration. In order to initiate this process, a room owner MUST request a new configuration form from the room by sending an IQ to &ROOM; containing an empty <query/> element qualified by the 'http://jabber.org/protocol/muc#owner' namespace.
+If the <user@host> of the 'from' address does not match the bare JID of a room owner, the service MUST return a &forbidden; error to the sender:
+Otherwise, the service MUST send a configuration form to the room owner with the current options set as defaults:
+If there are no configuration options available, the service MUST return an empty query element to the room owner as shown in the previous use case.
+The room owner SHOULD then submit the form with updated configuration information.
+Alternatively, the room owner MAY cancel the configuration process:
+If the room owner cancels the subsequent configuration, the service MUST leave the configuration of the room as it was before the room owner initiated the subsequent configuration process.
+If as a result of a change in the room configuration a room admin loses administrative privileges while the admin is in the room, the room MUST send updated presence for that individual to all occupants, denoting the change in status by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "member" and the 'role' attribute set to a value of "participant" or "visitor" as appropriate for the affiliation level and the room type:
+If as a result of a change in the room configuration a user gains administrative privileges while the user is in the room, the room MUST send updated presence for that individual to all occupants, denoting the change in status by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "admin" and the 'role' attribute set to a value of "admin":
+If as a result of a change in the room configuration a room owner loses owner privileges while that owner is in the room, the room MUST send updated presence for that individual to all occupants, denoting the change in status by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "admin" and the 'role' attribute set to an appropriate value given the affiliation and room type ("moderator" is recommended).
+A service MUST NOT allow an owner to revoke his or her own ownership privileges if there are no other owners; if an owner attempts to do this, the service MUST return a &conflict; error to the owner. However, a service SHOULD allow an owner to revoke his or her own ownership privileges if there are other owners.
+If as a result of a change in the room configuration a user gains ownership privileges while the user is in the room, the room MUST send updated presence for that individual to all occupants, denoting the change in status by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "owner" and the 'role' attribute set to an appropriate value given the affiliation and room type ("moderator" is recommended).
+If as a result of a change in the room configuration the room type is changed to members-only but there are non-members in the room, the service MUST remove any non-members from the room and include a status code of 322 in the presence unavailable stanzas sent to those users as well as any remaining occupants.
+A room MUST send notification to all occupants when the room configuration changes in a way that has an impact on the privacy or security profile of the room. This notification shall consist of a &MESSAGE; stanza containing an &X; element qualified by the 'http://jabber.org/protocol/muc#user' namespace, which shall contain only a <status/> element with an appropriate value for the 'code' attribute. Here is an example:
+The codes to be generated as a result of a privacy-related change in room configuration are as follows:
+-
+
- If room logging is now enabled, status code 170. +
- If room logging is now disabled, status code 171. +
- If the room is now non-anonymous, status code 172. +
- If the room is now semi-anonymous, status code 173. +
- If the room is now fully-anonymous, status code 174. +
For any other configuration change, the room SHOULD send status code 104 so that interested occupants can retrieve the updated room configuration if desired.
+If allowed by an implementation, an owner MAY grant ownership privileges to another user; this is done by changing the user's affiliation to "owner":
+The service MUST add the user to the owner list and then inform the owner of success:
+If the user is in the room, the service MUST then send updated presence from this individual to all occupants, indicating the granting of ownership privileges by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "owner" and the 'role' attribute set to an appropriate value given the affiliation and room type ("moderator" is recommended).
+An implementation MAY allow an owner to revoke another user's ownership privileges; this is done by changing the user's affiliation to something other than "owner":
+A service MUST NOT allow an owner to revoke his or her own ownership privileges if there are no other owners; if an owner attempts to do this, the service MUST return a &conflict; error to the owner. However, a service SHOULD allow an owner to revoke his or her own ownership privileges if there are other owners.
+If an implementation does not allow one owner to revoke another user's ownership privileges, the implementation MUST return a ¬authorized; error to the owner who made the request.
+In all other cases, the service MUST remove the user from the owner list and then inform the owner of success:
+If the user is in the room, the service MUST then send updated presence from this individual to all occupants, indicating the loss of ownership privileges by sending a presence element that contains an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value other than "owner" and the 'role' attribute set to an appropriate value:
+Note: Allowing an owner to remove another user's ownership privileges can compromise the control model for room management; therefore this feature is OPTIONAL, and implementations are encouraged to support owner removal through an interface that is open only to individuals with service-wide administrative privileges.
+If allowed by an implementation, a room owner may want to modify the owner list. To do so, the owner first requests the owner list by querying the room for all users with an affiliation of 'owner'.
+If the <user@host> of the 'from' address does not match the bare JID of a room owner, the service MUST return a &forbidden; error to the sender.
+Otherwise, the service MUST then return the owner list to the owner; each item MUST include the 'affiliation' and 'jid' attributes and MAY include the 'nick' and 'role' attributes for any owner that is currently an occupant:
+The owner MAY then modify the owner list. In order to do so, the owner MUST send the changed items (i.e., only the "delta") back to the service;
Only owners shall be allowed to modify the owner list. If a non-owner attempts to view or modify the owner list, the service MUST deny the request and return a &forbidden; error to the sender:
+A service MUST NOT allow an owner to revoke his or her own ownership privileges if there are no other owners; if an owner attempts to do this, the service MUST return a &conflict; error to the owner. However, a service SHOULD allow an owner to revoke his or her own ownership privileges if there are other owners.
+In all other cases, the service MUST modify owner list and then inform the owner of success:
+The service MUST also send presence notifications related to any affiliation changes that result from modifying the owner list as previously described.
+An owner can grant administrative privileges to a member or unaffiliated user; this is done by changing the user's affiliation to "admin":
+The service MUST add the user to the admin list and then inform the owner of success:
+If the user is in the room, the service MUST then send updated presence from this individual to all occupants, indicating the granting of administrative privileges by including an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value of "admin" and the 'role' attribute set to an appropriate value given the affiliation and room type.
+An owner may want to revoke a user's administrative privileges; this is done by changing the user's affiliation to something other than "admin" or "owner":
+The service MUST remove the user from the admin list and then inform the owner of success:
+The service MUST then send updated presence from this individual to all occupants, indicating the loss of administrative privileges by sending a presence element that contains an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child with the 'affiliation' attribute set to a value other than "admin" or "owner" and the 'role' attribute set to an appropriate value given the affiliation level and the room type:
+A room owner may want to modify the admin list. To do so, the owner first requests the admin list by querying the room for all users with an affiliation of 'admin'.
+If the <user@host> of the 'from' address does not match the bare JID of a room owner, the service MUST return a &forbidden; error to the sender.
+Otherwise, the service MUST then return the admin list to the owner; each item MUST include the 'affiliation' and 'jid' attributes and MAY include the 'nick' and 'role' attributes for any admin that is currently an occupant:
+The owner MAY then modify the admin list. In order to do so, the owner MUST send the changed items (i.e., only the "delta") back to the service;
Only owners shall be allowed to modify the admin list. If a non-owner attempts to view or modify the admin list, the service MUST deny the request and return a &forbidden; error to the sender:
+Otherwise, the service MUST modify the admin list and then inform the owner of success:
+The service MUST also send presence notifications related to any affiliation changes that result from modifying the admin list as previously described.
+A room owner MUST be able to destroy a room, especially if the room is persistent. The workflow is as follows:
+-
+
The room owner requests that the room be destroyed, specifying a reason and an alternate venue if desired.
+ The room removes all users from the room (including appropriate information about the alternate location and the reason for being removed) and destroys the room, even if it was defined as persistent.
+
Other than the foregoing, this document does not specify what (if anything) a MUC service implementation shall do as a result of a room destruction request. For example, if the room was defined as persistent, an implementation MAY choose to lock the room ID so that it cannot be re-used, redirect enter requests to the alternate venue, or invite the current participants to the new room; however, such behavior is OPTIONAL.
+In order to destroy a room, the room owner MUST send an IQ set to the address of the room to be destroyed. The &IQ; stanza shall contain a &QUERY; element qualified by the 'http://jabber.org/protocol/muc#owner' namespace, which in turn shall contain a <destroy/> element. The address of the alternate venue MAY be provided as the value of the <destroy/> element's 'jid' attribute. A password for the alternate venue MAY be provided as the XML character data of a <password/> child element of the <destroy/> element. The reason for the room destruction MAY be provided as the XML character data of a <reason/> child element of the <destroy/> element.
+The following examples illustrate the protocol elements to be sent and received:
+The service is responsible for removing all the occupants. It SHOULD NOT broadcast presence stanzas of type "unavailable" from all occupants, instead sending only one presence stanza of type "unavailable" to each occupant so that the user knows he or she has been removed from the room. If extended presence information specifying the JID of an alternate location and the reason for the room destruction was provided by the room owner, the presence stanza MUST include that information.
+If the <user@host> of the 'from' address received on a destroy request does not match the bare JID of a room owner, the service MUST return a &forbidden; error to the sender:
+The error codes associated with the 'http://jabber.org/protocol/muc#user' namespace are fairly straightforward, as summarized in the following table. For detailed information about mapping legacy error codes to XMPP-style error types and conditions, refer to &jep0086;; implementations SHOULD support both legacy and XMPP error handling.
+| Code | +Type | +Element | +Context | +Purpose | +
|---|---|---|---|---|
| 401 | +Error | +Presence | +Entering a room | +Inform user that a password is required | +
| 403 | +Error | +Presence | +Entering a room | +Inform user that he or she is banned from the room | +
| 404 | +Error | +Presence | +Entering a room | +Inform user that the room does not exist | +
| 405 | +Error | +Presence | +Entering a room | +Inform user that room creation is restricted | +
| 406 | +Error | +Presence | +Entering a room | +Inform user that the reserved roomnick must be used | +
| 407 | +Error | +Presence | +Entering a room | +Inform user that he or she is not on the member list | +
| 409 | +Error | +Presence | +Entering a room | +Inform user that his or her desired room nickname is in use or registered by another user | +
| 503 | +Error | +Presence | +Entering a room | +Inform user that the maximum number of users has been reached | +
This document does not stipulate text strings (i.e., values of the XMPP <text/> element) associated with the foregoing error conditions.
+Multi-User Chat uses a <status/> element (specifically, the 'code' attribute of the <status/> element) to communicate information about a user's status in a room. Over time, the number of status codes has grown quite large, and new status codes continue to be requested of the JEP author. Therefore, these codes are now documented in a registry maintained by the Jabber Registrar. For details, refer to the Status Codes Registry section of this document.
+Note: In general, MUC status codes tend to follow the "philosophy" of status codes that is implicit in &rfc2616; and &rfc1893; (1xx codes are informational, 2xx codes specify that it is fine to continue, 3xx codes specify redirects such as being kicked or banned, x3x codes refer to system status, x7x codes refer to security or policy matters, etc.).
+Note: If the MUC protocol were being designed today, it would specify a more flexible, XML-friendly approach rather than hardcoded status numbers; however, at this point the pain of changing the status reporting system would be greater than the benefit of doing so, which is why the status code numbers remain in use. A future version of this document may define a more XMPP-like approach to status conditions, retaining the code numbers but supplementing them with more descriptive child elements as is done in RFC 3920.
+As specified in RFC 3920, XMPP entities (including MUC rooms and MUC services) SHOULD respect the value of the 'xml:lang' attribute provided with any given stanza. However, simultaneous translation of groupchat messages is out of scope for this document.
+The status and error codes defined herein enable a client implementation to present a localized interface; however, definition of the localized text strings for any given language community is out of scope for this document.
+Although the labels for various data form fields are shown here in English, MUC clients SHOULD present localized text for these fields rather than the English text.
+No room entrance authentication or authorization method more secure than cleartext passwords is defined or required by this document. However, the risks involved can mitigated by the use of channel encryption and strong authentication via TLS and SASL as described in RFC 3920.
+No end-to-end message or session encryption method is specified herein. Users SHOULD NOT trust a service to keep secret any text sent through a room.
+Depending on room configuration, a room may publicly log all discussions held in the room. A service MUST warn the user that the room is publicly logged by returning a status code of "170" with the user's initial presence, and user's the client MUST so warn the user if the room discussion is logged (a user's client SHOULD also query the room for its configuration prior to allowing the user to enter in order to "pre-discover" whether the room is logged). A client MUST also warn the user if the room's configuration is subsequently modified to allow room logging (which the client will discover when the room sends status code 170). Note: In-room history is different from public room logging, and naturally a room cannot effectively prevent occupants from separately maintaining their own room logs, which may become public; users SHOULD exercise due caution and consider any room discussions to be effectively public.
+Depending on room configuration, a room MAY expose each occupant's real JID to other occupants (if the room is non-anonymous) and will almost certainly expose each occupant's real JID to the room owners and administrators (if the room is not fully-anonymous). A service MUST warn the user that real JIDs are exposed in the room by returning a status code of "100" with the user's initial presence, and the user's client MUST so warn the user (a user's client SHOULD also query the room for its configuration prior to allowing the user to enter in order to "pre-discover" whether real JIDs are exposed in the room). A client MUST also warn the user if the room's configuration is subsequently modified from semi-anonymous or fully-anonymous to non-anonymous (which the client will discover when the room sends status code 172) and SHOULD warn the user if the room's configuration is subsequently modified from fully-anonymous to semi-anonymous (which the client will discover when the room sends status code 173).
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes the following information in its registries.
+The Jabber Registrar includes the following MUC-related namespaces in its registry of protocol namespaces:
+-
+
- http://jabber.org/protocol/muc +
- http://jabber.org/protocol/muc#admin +
- http://jabber.org/protocol/muc#owner +
- http://jabber.org/protocol/muc#unique +
- http://jabber.org/protocol/muc#user +
A Multi-User Chat service or room is identified by the "conference" category and the "text" type within Service Discovery.
+There are many features related to a MUC service or room that can be discovered by means of Service Discovery. The most fundamental of these is the 'http://jabber.org/protocol/muc' namespace. In addition, a MUC room SHOULD provide information about the specific room features it implements, such as password protection and room moderation.
+
+ http://jabber.org/protocol/muc#register
+ Support for the muc#register FORM_TYPE
+ JEP-0045
+
+
+ http://jabber.org/protocol/muc#roomconfig
+ Support for the muc#roomconfig FORM_TYPE
+ JEP-0045
+
+
+ http://jabber.org/protocol/muc#roominfo
+ Support for the muc#roominfo FORM_TYPE
+ JEP-0045
+
+
+ muc_hidden
+ Hidden room in Multi-User Chat (MUC)
+ JEP-0045
+
+
+ muc_membersonly
+ Members-only room in Multi-User Chat (MUC)
+ JEP-0045
+
+
+ muc_moderated
+ Moderated room in Multi-User Chat (MUC)
+ JEP-0045
+
+
+ muc_nonanonymous
+ Non-anonymous room in Multi-User Chat (MUC)
+ JEP-0045
+
+
+ muc_open
+ Open room in Multi-User Chat (MUC)
+ JEP-0045
+
+
+ muc_passwordprotected
+ Password-protected room in Multi-User Chat (MUC)
+ JEP-0045
+
+
+ muc_persistent
+ Persistent room in Multi-User Chat (MUC)
+ JEP-0045
+
+
+ muc_public
+ Public room in Multi-User Chat (MUC)
+ JEP-0045
+
+
+ muc_rooms
+ List of MUC rooms (each as a separate item)
+ JEP-0045
+
+
+ muc_semianonymous
+ Semi-anonymous room in Multi-User Chat (MUC)
+ JEP-0045
+
+
+ muc_temporary
+ Temporary room in Multi-User Chat (MUC)
+ JEP-0045
+
+
+ muc_unmoderated
+ Unmoderated room in Multi-User Chat (MUC)
+ JEP-0045
+
+
+ muc_unsecured
+ Unsecured room in Multi-User Chat (MUC)
+ JEP-0045
+
+ ]]>
+ The well-known Service Discovery node 'http://jabber.org/protocol/muc#rooms' enables discovery of the rooms in which a user is an occupant.
+The well-known Service Discovery node 'x-roomuser-item' enables a user to discover his or registered roomnick from outside the room.
+The well-known Service Discovery node 'http://jabber.org/protocol/muc#traffic' enables discovery of the namespaces that are allowed in traffic sent through a room (see the Allowable Traffic section of this document).
+&jep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace. Within MUC, there are three uses of such forms: room registration within muc#user, room configuration within muc#owner, and service discovery extensions for room information. The reserved fields are defined below.
+
+ http://jabber.org/protocol/muc#register
+ JEP-0045
+
+ Forms enabling user registration with a
+ Multi-User Chat (MUC) room or admin approval
+ of user registration requests.
+
+
+
+ http://jabber.org/protocol/muc#roomconfig
+ JEP-0045
+
+ Forms enabling creation and configuration of
+ a Multi-User Chat (MUC) room.
+
+
+
+ http://jabber.org/protocol/muc#roominfo
+ JEP-0045
+
+ Forms enabling the communication of extended service discovery
+ information about a Multi-User Chat (MUC) room.
+
+
+ The Jabber Registrar maintains a registry of values for the 'code' attribute of the <status/> element when qualified by the 'http://jabber.org/protocol/muc#user' namespace.
+ ®PROCESS; +
+ the three-digit code number
+ the stanza type of which it is a child (message or presence)
+ the use case or situation in which the status is used
+ a natural-language description of the meaning
+ the descriptive child element (reserved for future use)
+
+ ]]>
+ The registrant may register more than one status code at a time, each contained in a separate <statuscode/> element.
+As part of this document, the following status codes are registered:
+
+ 100
+ message
+ Entering a room
+ Inform user that any occupant is allowed to see the user's full JID
+
+
+ 101
+ message (out of band)
+ Affiliation change
+ Inform user that his or her affiliation changed while not in the room
+
+
+ 102
+ message
+ Configuration change
+ Inform occupants that room now shows unavailable members
+
+
+ 103
+ message
+ Configuration change
+ Inform occupants that room now does not show unavailable members
+
+
+ 104
+ message
+ Configuration change
+ Inform occupants that a non-privacy-related room configuration change has occurred
+
+
+ 110
+ presence
+ Any room presence
+ Inform user that presence refers to one of its own room occupants
+
+
+ 170
+ message or initial presence
+ Configuration change
+ Inform occupants that room logging is now enabled
+
+
+ 171
+ message
+ Configuration change
+ Inform occupants that room logging is now disabled
+
+
+ 172
+ message
+ Configuration change
+ Inform occupants that the room is now non-anonymous
+
+
+ 173
+ message
+ Configuration change
+ Inform occupants that the room is now semi-anonymous
+
+
+ 174
+ message
+ Configuration change
+ Inform occupants that the room is now fully-anonymous
+
+
+ 201
+ presence
+ Entering a room
+ Inform user that a new room has been created
+
+
+ 210
+ presence
+ Entering a room
+ Inform user that the service has assigned or modified the occupant's roomnick
+
+
+ 301
+ presence
+ Removal from room
+ Inform user that he or she has been banned from the room
+
+
+ 303
+ presence
+ Exiting a room
+ Inform all occupants of new room nickname
+
+
+ 307
+ presence
+ Removal from room
+ Inform user that he or she has been kicked from the room
+
+
+ 321
+ presence
+ Removal from room
+ Inform user that he or she is being removed from the room
+ because of an affiliation change
+
+
+ 322
+ presence
+ Removal from room
+ Inform user that he or she is being removed from the room
+ because the room has been changed to members-only and the user
+ is not a member
+
+
+ 332
+ presence
+ Removal from room
+ Inform user that he or she is being removed from the room
+ because of a system shutdown
+
+ ]]>
+ As authorized by &jep0147;, the Jabber Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).
+The "join" querytype is registered as a MUC-related action, with an optional key of "password".
+The application MUST either present an interface enabling the user to provide a room nickname or populate the room nickname based on configured preferences or nickname discovery.
+The join action MAY include a password for the room. Naturally, access to a URI that includes a room password MUST be appropriately controlled.
+The following submission registers the "join" querytype.
+
+ join
+ http://jabber.org/protocol/muc
+ enables joining a multi-user chat room
+ JEP-0045
+
+
+ password
+ the password required to enter a multi-user chat room
+
+
+
+ ]]>
+ The "invite" querytype is registered as a MUC-related action, with an optional key of "jid".
+If the joining user is not yet in the room, the application MUST send two stanzas: the first to join the room and the second to invite the other individual. If the joining user is in the room already, the application shall send only the invitation stanza.
+The URI may include multiple invitees:
+The URI may also include a password:
+If the joining user is not yet in the room, the application MUST send two stanzas: the first to join the room and the second to invite the other individual. If the joining user is in the room already, the application shall send only the invitation stanza.
+The following submission registers the "invite" querytype.
+
+ invite
+ http://jabber.org/protocol/muc
+ enables simultaneously joining a groupchat room and inviting others
+ JEP-0045
+
+
+ jid
+ the Jabber ID of the invitee
+
+
+ password
+ the password required to enter a multi-user chat room
+
+
+
+ ]]>
+ In order to provide consistency regarding the addresses captured in room JIDs, Room IDs MUST match the Nodeprep profile of Stringprep and Room Nicknames MUST match the Resourceprep profile of Stringprep (both of these are defined in RFC 3920). Although not explicitly stated in RFC 3920, both the Room ID (node) and Room Nickname (resource) portions of a Room JID MUST be of non-zero length. In addition, a MUC service MUST NOT allow empty or invisible Room Nicknames (i.e., Room Nicknames that consist only of one or more space characters).
+-
+
If an occupant wants to send a message to all other occupants, a MUC client MUST set the 'type' attribute to a value of "groupchat". A service MAY ignore messages that are improperly typed, or reject them with a &badrequest; error.
+ If a MUC service receives a message directed to the room or to a single occupant from a Jabber user who has a role of "none", the service MUST NOT deliver the message and SHOULD return the message to the sender with a &forbidden; error.
+ If a MUC service receives a message directed to a room that does not exist or is not yet unlocked, the service SHOULD return the message to the sender with an ¬found; error.
+ A MUC service SHOULD pass extended information (e.g., an XHTML version of the message body) through to occupants unchanged; however, a MUC service MAY disallow message specific extensions (see the Allowable Traffic section of this document).
+ A MUC client MAY generate extensions that conform to the &jep0022; or &jep0085; specification; however, a MUC service MAY disallow these extensions (see the Allowable Traffic section of this document).
+
-
+
A room MUST silently ignore unavailable presence received from a user who has a role of "none".
+ Only the MUC service itself SHOULD generate extended presence information about roles, affiliations, full JIDs, or status codes qualified by the 'http://jabber.org/protocol/muc#user' namespace (based on information the service knows about occupants, e.g., roles, or as a result of actions taken by a moderator or room administrator). A client SHOULD NOT presume to generate such information. If a MUC service receives such extended presence information from an occupant, it MUST NOT reflect it to other occupants. (A client MAY generate extended presence information qualified by the 'http://jabber.org/protocol/muc#user' namespace in order to supply a password, but naturally this is not reflected to other occupants.)
+ A MUC service SHOULD allow all other presence information to pass through, although it MAY choose to block extended presence information; see the Allowable Traffic section of this document.
+ In order to appropriately inform occupants of room roles and affiliations, and to make it easier for Jabber clients to track the current state of all users in the room, MUC service implementations MUST provide extended presence information about roles and affiliations in all presence stanzas, including presence stanzas of type "unavailable" sent when a user exits the room for any reason.
+ If a privilege is revoked, the service MUST note that by sending an <x/> element qualified by the 'http://jabber.org/protocol/muc#user' namespace and containing an <item/> child element with the 'role' and/or 'affiliation' attributes set to a value that indicates the loss of the relevant privilege. All future presence stanzas for the occupant MUST include the updated role and affiliation, until and unless they change again.
+ A MUC service MUST send extended presence to a client even if the client did not send an empty <x/> element qualified by the 'http://jabber.org/protocol/muc' namespace on entering the room; naturally, a client MUST ignore such information if it does not understand it (in accordance with RFC 3920).
+ Extended presence about roles and affiliations sent in the muc#user namespace MUST include the full JID (not the bare JID) as the value of the 'jid' attribute.
+ A client MAY send a custom exit message if desired (as is often done in IRC channels) by including a <status/> element in the presence stanza of type "unavailable" sent when exiting a room.
+
-
+
If an occupant wants to send an IQ stanza to another user in a non-anonymous room, the sender SHOULD send the request directly to the recipient's bare JID or full JID, rather than attempting to send the request through the room (i.e., via the recipient's room JID).
+ If an occupant wants to send an IQ stanza to another user in a semi-anonymous room, the sender can direct the stanza to the recipient's room JID and the service MAY forward the stanza to the recipient's real JID. However, a MUC service MUST NOT reveal the sender's real JID to the recipient at any time, nor reveal the recipient's real JID to the sender.
+ A MUC client MUST send only the 'affiliation' attribute or the 'role' attribute in the <item/> element contained within an IQ set qualified by the 'http://jabber.org/protocol/muc#admin' namespace; if a moderator, admin, or owner attempts to modify both the affiliation and role of the same item in the same IQ set, the service MUST return a &badrequest; error to the sender. However, a MUC service MAY modify a role based on a change to an affiliation and thus MAY send presence updates that include both a modified role and a modified affiliation.
+ In IQ sets regarding roles, a MUC client MUST include the 'nick' attribute only; in IQ results regarding roles, a MUC service MUST include the 'nick', 'role', 'affiliation', and 'jid' attributes (with the value of the latter set to the user's full JID).
+ In IQ sets regarding affiliations, a MUC client MUST include the 'jid' attribute only (with the value set to the bare JID); in IQ results regarding affiliations, a MUC service MUST NOT include the 'role' attribute, MUST include the 'affiliation' attribute and the 'jid' attribute (with the value set to the bare JID), and SHOULD include the 'nick' attribute (except if the affiliation is "outcast", since outcasts SHOULD NOT have reserved nicknames).
+
The following guidelines may assist client and component developers in creating MUC implementations.
+-
+
In handling messages sent by visitors in a moderated room, a MUC service MAY queue each message for approval by a moderator and MAY inform the sender that the message is being held for approval; however, such behavior is OPTIONAL, and definition of a message approval protocol (e.g., using Data Forms as defined in JEP-0004) is out of scope for this document.
+ It is common for MUC services to provide in-room messages when certain events occur, such as when the subject changes, when an occupant enters or exits, or when a room is destroyed. Such messages are entirely OPTIONAL and are left up to the implementation or deployment, but if used MUST be messages of type "groupchat" sent from the room JID itself (&ROOM;) rather than a specific occupant (&ROOMJID;). However, in general it is preferable for the receiving client to generate such messages based on events in the room (e.g., user entrances and exits) as well as specific status codes provided in MUC; this will help ensure correct localization of such messages.
+ Out of courtesy, a MUC service MAY send an out-of-room <message/> to an occupant who is kicked or banned, and MAY broadcast an in-room <message/> to all remaining occupants informing them that the occupant has been kicked or banned from the room. However, such messages are OPTIONAL, and indeed are unnecessary since the information required for a receiving client to generate such messages is communicated in the presence stanzas (specifically the status codes) sent by a MUC service.
+ Out of courtesy, a MUC service MAY send an out-of-room <message/> if a user's affiliation changes while the user is not in the room; the message SHOULD be sent from the room to the user's bare JID, MAY contain a <body/> element describing the affiliation change, and MUST contain a status code of 101.
+ There is no requirement that a MUC service shall provide special treatment for users of the older "groupchat 1.0" protocol, such as messages that contain equivalents to the extended presence information that is qualified by the 'http://jabber.org/protocol/muc#user' namespace.
+ Room types MAY be configured in any combination. A MUC service MAY support or allow any desired room types or combinations thereof.
+ A MUC service MAY limit the number of configuration options presented to an owner after initial configuration has been completed, e.g. because certain options cannot take effect without restarting the service.
+ A MUC service MAY provide an interface to room creation and configuration (e.g., in the form of a special Jabber user or a Web page), so that the ostensible room owner is actually the application instead of a human user.
+ A MUC service MAY choose to make available a special in-room resource that provides an interface to administrative functionality (e.g., a "user" named "ChatBot"), which occupants could interact with directly, thus enabling admins to type '/command parameter' in a private message to that "user". Obviously this kind of implementation would require the service to add a 'ChatBot' user to the room when it is created, and to prevent any occupant from having the nickname 'ChatBot' in the room. This might be difficult to ensure in some implementations or deployments. In any case, any such interface is OPTIONAL.
+ A MUC service SHOULD remove a user if the service receives a delivery-related error in relation to a stanza it has previously sent to the user (remote server unreachable, user not found, etc.).
+ A MUC service MAY choose to discard extended presence information that is attached to a &PRESENCE; stanza before reflecting the presence change to the occupants of a room. That is, an implementation MAY choose to reflect only the <show/>, <status/>, and <priority/> child elements of the presence element as specified in the XML schema for the 'jabber:client' namespace, with the result that presence "changes" in extended namespaces (e.g., gabber:x:music:info) are not passed through to occupants. If a service prohibits certain extended namespaces, it SHOULD provide a description of allowable traffic at the well-known Service Discovery node 'http://jabber.org/protocol/muc#traffic' as described in the Allowable Traffic section of this document.
+ A MUC service MAY choose to discard extended information attached to &MESSAGE; stanzas before reflecting the message to the occupants of a room. An example of such extended information is the lightweight text markup specified by &jep0071;. If a service prohibits certain extended namespaces, it SHOULD provide a description of allowable traffic at the well-known Service Discovery node 'http://jabber.org/protocol/muc#traffic' as described in the Allowable Traffic section of this document.
+ A MUC service MAY choose to "lock down" room nicknames (e.g., hardcoding the room nickname to the bare JID of the occupant). If so, the service MUST treat the locked down nickname as a reserved room nickname and MUST support the protocol specified in the Discovering Reserved Room Nickname section of this document.
+
As noted, a service (more precisely, a properly-configured room) MAY discard some or all extended namespaces attached to &MESSAGE; and &PRESENCE; stanzas that are intended for reflection from the sender through the room to all of the room occupants. If the room does so, it SHOULD enable senders to discover the list of allowable extensions by sending a disco#info query to the well-known Service Discovery node 'http://jabber.org/protocol/muc#traffic', returning one <feature/> element for each namespace supported in the result. If the room does not allow any extended namespaces, it MUST return an empty query as specified in JEP-0030. If the room does not support the "#traffic" node, it MUST return a &feature; error in response to queries sent to the 'http://jabber.org/protocol/muc#traffic' node.
+The following example shows a room that allows the 'http://jabber.org/protocol/xhtml-im' and 'http://jabber.org/protocol/rosterx' namespaces only, but no other extended namespaces.
+If a service does not discard any namespaces or does not implement this feature, it MUST return a &unavailable; error:
+-
+
Jabber clients MAY present room roles by showing ad-hoc groups for each role within a room roster. This will enable occupants to clearly visualize which occupants are moderators, participants, and visitors. However, such a representation is OPTIONAL.
+ Jabber clients MAY implement a variety of interface styles that provide "shortcuts" to functionality such as changing one's nickname, kicking or banning users, discovering an occupant's full JID, or changing the subject. One option consists of IRC-style commands such as '/nick', '/kick', '/ban', and '/whois'; another is to enable a user to right-click items in a room roster. All such interface styles are OPTIONAL. However, for convenience, a mapping of IRC commands to MUC protocols is provided below.
+
Internet Relay Chat clients use a number of common "shortcut" commands that begin with a forward slash, such as '/nick' and '/ban'. The following table provides a mapping of IRC-style commands to MUC protocols, for use by Jabber clients that wish to support such functionality.
+| Command | +Function | +MUC protocol | +
|---|---|---|
| /ban <roomnick> [comment] | +bans user with that roomnick from this room (client translates roomnick to bare JID) | +
+ |
+
| /invite <jid> [comment] | +invites user with that JID to this room | +
+ |
+
| /join <roomname> [pass] | +joins room on this service (roomnick is same as nick in this room) | +
+ |
+
| /kick <roomnick> [comment] | +kicks user with that roomnick from this room | +
+ |
+
| /msg <roomnick> <foo> | +sends private message "foo" to roomnick | +
+ foo
+
+ ]]> |
+
| /nick <newnick> | +changes nick in this room to "newnick" | +
+ ]]> |
+
| /part [comment] | +exits this room (some IRC clients also support /leave) | +
+ |
+
| /topic <foo> | +changes subject of this room to "foo" | +
+ |
+
Note: Because MUC roomnicks follow the Resourceprep profile of stringprep, they are allowed to contain a space character, whereas IRC nicknames do not. Although a given client MAY support quotation characters for this purpose (resulting in commands such as '/ban "king lear" insanity is no defense'), most common quotation characters (such as " and ') are also allowed by Resourceprep, thus leading to added complexity and potential problems with quotation of roomnicks that contain both spaces and quotation characters. Therefore it is NOT RECOMMENDED for Jabber clients to support IRC-style shortcut commands with roomnicks that contain space characters.
+Note: Many Jabber clients also implement a '/me ' command, where the command is followed by a verb or verb phrase (e.g., '/me laughs'). This command does not result in any MUC or IRC protocol action and is therefore not shown in the foregoing table. Instead, the message is sent as-is (e.g., <body>/me laughs</body>) and the receiving client performs string-matching on the character data of the &BODY; element to determine if the message begins with the string '/me '; if it does the receiving client will show the message in a special format, usually italicized text sometimes prepended by the "*" character:
+* stpeter laughs
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0045: http://www.jabber.org/jeps/jep-0045.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0045: http://www.jabber.org/jeps/jep-0045.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0045: http://www.jabber.org/jeps/jep-0045.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0045: http://www.jabber.org/jeps/jep-0045.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0045: http://www.jabber.org/jeps/jep-0045.html
+
+
+
+
+ ]]>
+ The author would like to thank the following individuals for their many helpful comments on various drafts of this proposal: David Sutton, Peter Millard, Joe Hildebrand, Craig Kaes, Alexey Shchepin, David Waite, Jean-Louis Seguineau, Jacek Konieczny, Gaston Dombiak, and many others in the jdev@conference.jabber.org conference room and on the Standards-JIG mailing list.
+There are cases where it would be more optimal for clients to exchange data directly with each other rather than through the server. DTCP specifies a method for establishing a direct TCP socket connection between two entities, so that a reliable bytestream can be created out-of-band.
+ +The following design goals are considered:
+ +-
+
- The protocol should be reasonably effective in scenarios involving NAT and/or firewalls.
DTCP works in situations where at least one client can accept incoming connections.
+ - It should be reasonably secure. +
- Establishing a connection should be fast. +
- The protocol should be simple. +
Say you wish to initiate a DTCP session with Joe:
+ +The 'key' given is a unique key for Joe to use when referencing this session with you. If a 'host' element is present, then you are indicating that you can be reached at the given "host:port". Multiple hosts may be specified, but Joe cannot be expected to act on more than three of them.
+ +The success response is in exactly the same format as the request. As before, Joe cannot expect you to act on more than three hosts. The 'key' is a unique key from Joe that you will use when referring to the session with him.
+ +Or he may send an error.
+ +If you received a success response, then the next step is to form the TCP connection. Each entity should have a list of hosts (between 0-3 inclusive) and key of the other. With this information, they should each try to establish a direct connection with the hosts provided. When these connections take place is implementation dependent. Clients may choose to connect to all provided hosts at once, and both clients may even end up connecting to each other simultaneously. Clients may delay between connections, etc. As such, clients that are listening for connections should be prepared for anything.
+ +The procedure ends when either a successful DTCP connection is formed (and all other TCP connections discarded), or when both entities have given up. An entity gives up when it is no longer trying to connect to any hosts. This is done by sending an additional iq-error packet, with the key of the other entity:
+ +If an entity was not provided any hosts, then it is assumed that he has given up and this packet need not be sent.
+ +For a given host, a TCP socket connection is established. Once connected, the connecting client must send a command across the channel. Each command is a line of text terminated by the ASCII linefeed character (0x0A).
+ +Some commands may have an argument, which is placed on the same line and separated by a colon character. If there is no argument, then the colon need not be present.
+ +The serving client should keep the connection open after responding to a command, even if it resulted in an error, in case the connecting client wishes to try another command.
+ +If you want an encrypted channel, then it must be requested using the 'starttls' command
+ +If successful, the serving client should send back:
+ +This means that the serving client supports SSL and the connecting client should begin the SSL/TLS negotiation. After this, further data sent/received over the channel should be in encrypted form.
+ +Or the serving client might report an error:
+This means SSL is not supported by the serving client.
+To complete the DTCP connection, the connecting client must authenticate with the serving client. This is done by exchanging keys. First, the connecting client sends the serving client's key:
+ +If the serving client recognizes the key, then it should respond by sending the connecting client's key:
+Or the serving client might report an error:
+On success, there may be one more step necessary. If the connecting client is also the original requestor of the DTCP connection (ie, he did the iq-set), then he must send the following "ack":
+This gives the final say to the requestor, to prevent any sort of race-condition due to the clients contacting each other at the same time. If the serving client is the requestor, then this extra "ack" is NOT needed and must NOT be sent.
+ +At this point, the channel is established. No further commands may be issued, as the TCP connection is now for application data only.
+ +This document describes In-Band Bytestreams (or IBB), a reliable bytestream protocol between two Jabber entities over a Jabber XML stream. The basic idea is that binary data is encoded as Base64 and transferred over the Jabber network.
+IBB is a generic bytestream, and so its usage is left open-ended. It is likely to be useful for sending small payloads, such as files that would otherwise be too cumbersome to send as an instant message (such as a text file) or impossible to send (such as a small binary image file). It could also be useful for any kind of low-bandwidth activity, such as a chess game or a shell session. And, while it is mostly intended as a fallback in situations where a &jep0065; is unavailable, IBB could be more desirable for many of the simple bytestream use-cases that do not have high bandwidth requirements.
+This asks Juliet if she would like to form an In-Band Bytestreams connection, using the session ID 'mySID' (generated by the initiator here) to uniquely reference the bytestream. The 'block-size' attribute specifies the maximum amount of data (in bytes) that an IBB packet may contain.
+ +This is a success response from juliet@capulet.com/balcony, saying that the bytestream is active.
+ +This is an error response from juliet@capulet.com/balcony saying that an In-Band Bytestreams is not possible.
+ +Data is sent using message stanzas. Either participant in the bytestream may send such packets. The data to be sent, prior to any encoding or wrapping in the message stanza, must be no larger than the 'block-size' determined in the stream negotiation. All packets are to be addressed to the FULL JID of the bytestream peer. In order to keep track of stanzas sent and any errors received, the sender SHOULD include the 'id' attribute on stanzas sent to the recipient. Note that &jep0079; SHOULD be used to ensure that the data packet is not spooled or sent to the wrong resource.
+The data to send is included as XML character data of the <data/> element after being encoded as Base64 as specified in Section 3 of &rfc3548;. The 'seq' attribute is a 16-bit integer counter starting at 0, and MUST be incremented for each packet sent. Thus, the next packet sent should have a 'seq' of 1, the one after that with a 'seq' of 2, and so on. The counter loops at maximum, so after value 65535, 'seq' MUST start again at 0.
+ +It is possible that the message may fail to be delivered:
+ +Upon delivery failure, the sender MUST consider the bytestream to be closed and invalid.
+ +To close the bytestream, send the following:
+ +This is a success response from juliet@capulet.com/balcony, saying that the bytestream is now closed.
+ +Upon error, the bytestream MUST be considered closed and invalid.
+ +Data packets MUST be processed in the order they are received. If an out-of-sequence packet is received for a particular bytestream (determined by checking the 'seq' attribute), then this indicates that a packet has been lost. The recipient MUST NOT process the data of such an out-of-sequence packet, nor any that follow it within the same bytestream, and at this point MUST consider the bytestream closed and invalid.
+-
+
- Generally, IBB should be used as a last resort. SOCKS5 Bytestreams will almost always be preferable. +
- A server MAY rate limit a connection, depending on the size and frequency of data packets. +
- A server MAY disconnect a connection that sends overly large packets as defined by server policy. +
- It is RECOMMENDED to use a 'block-size' of 4096. +
- For proper tracking of message delivery errors, the use of the stanza 'id' attribute is RECOMMENDED. +
In-Band Bytestreams is as secure as the underlying Jabber transport. The bytestream application could have its own security layer, but this is outside of the scope of IBB.
+An entity MUST verify any Base64 data received. An implementation MUST reject (not ignore) any characters that are not explicitly allowed by the Base64 alphabet; this helps to guard against creation of a covert channel that could be used to "leak" information. An implementation MUST NOT break on invalid input and MUST reject any sequence of Base64 characters containing the pad ('=') character if that character is included as something other than the last character of the data (e.g. "=AAA" or "BBBB=CCC"); this helps to guard against buffer overflow attacks and other attacks on the implementation. Base encoding visually hides otherwise easily recognized information, such as passwords, but does not provide any computational confidentiality. Base64 encoding MUST follow the definition in Section 3 of RFC 3548.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; shall register the 'http://jabber.org/protocol/ibb' namespace as a result of this JEP.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0047: http://www.jabber.org/jeps/jep-0047.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+For ease-of-use in a Jabber client, it is desirable to have a way to store shortcuts to various services and resources (such as conference rooms and webpages) as 'bookmarks' which can be displayed in the user's client. Several Jabber clients have already agreed on and implemented a method to provide this service; that informal agreement is documented and expanded upon in this JEP.
+&jep0049; provides us with a convenient method for storing user data on the server using jabber:iq:private; all we need to do is define a namespace and schema for storing this sort of information. To this end, we introduce the 'storage' element, and the 'storage:bookmarks' to handle this data.
+A storage element marked by the storage:bookmarks namespace will contain a collection of child elements, each representing a 'bookmark' to be displayed in the client. At present, only two sub-elements are defined, 'conference' for conference rooms and 'url' for normal URLs.
+All elements under storage MUST allow a 'name' tag, which is the friendly name by which they will be displayed in the client. If an element lacks a 'name' tag, the client SHOULD generate an appropriate substitution based on the other available data.
+URLs are fairly simple, as they only need to store a URL and a title, and the client then can simply launch the appropriate browser.
+A URL element therefore only needs a 'url' tag in addition to the required 'name', like so:
+This bookmark would be displayed in the client as 'Complete Works of Shakespeare' and would take the user to http://the-tech.mit.edu/Shakespeare/ if activated. A bookmark set can contain any number of urls.
+One of the most common uses of bookmarks will likely be to bookmark conference rooms on various Jabber servers. It is this aspect of the bookmark system which is used today by existing clients such as Exodus
The conference element MAY also contain 'nick' and 'password' sub-elements; the XML character data from these elements should be used when joining the room from the bookmark. Password is, of course, important for joining potentially password-protected &jep0045; rooms.
+This bookmark would be displayed as 'Council of Oberon' and, if activated, would attempt to join the conference room 'council@conference.underhill.org' with nickname 'Puck' and password 'titania'. A bookmark set may contain any number of conference rooms.
+Security considerations related to private XML storage are described in JEP-0049.
+This JEP requires no interaction with &IANA;.
+No namespaces or parameters need to be registered with the ®ISTRAR; as a result of this JEP.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0048: http://www.jabber.org/jeps/jep-0048.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Peter Millard, a co-author of this specification from version 0.1 through version 1.0, died on April 26, 2006.
+The 'jabber:iq:private' namespace has previously been documented in the Jabber Programmers Guide, but not in a canonical form such as the Internet-Drafts or a JEP. This JEP documents the existing usage of jabber:iq:private.
+A Jabber client can store any arbitrary XML on the server side by sending an &IQ; stanza of type "set" to the server with a &QUERY; child scoped by the 'jabber:iq:private' namespace. The &QUERY; element MAY contain any arbitrary XML fragment as long as the root element of that fragment is scoped by its own namespace. The data can then be retrieved by sending an &IQ; stanza of type "get" with a &QUERY; child scoped by the 'jabber:iq:private' namespace, which in turn contains a child element scoped by the namespace used for storage of that fragment. Using this method, Jabber entities can store private data on the server and retrieve it whenever necessary. The data stored might be anything, as long as it is valid XML. One typical usage for this namespace is the server-side storage of client-specific preferences; another is &jep0048;.
+| get | Sent with a blank query to retrieve the private data from the server. |
| set | Sent with the private XML data contained inside of a query. |
| result | Returns the private data from the server. |
| error | There was an error processing the request. The exact error can be found in the child error element. |
The root element of this namespace is query. At least one child element with a proper namespace MUST be included; otherwise the server MUST respond with a "Not Acceptable" error (see &jep0086; for information about error conditions). A client MUST NOT query for more than namespace in a single IQ get request. However, an IQ set or result MAY contain multiple elements qualified by the same namespace.
+ +If a user attempts to get or set jabber:iq:private data that belongs to another user, the server MUST return a "Forbidden" or "Service Unavailable" error to the sender (the latter condition is in common use by existing implementations, although the former is preferable).
+If a user attempts to perform an IQ get without providing a child element, the server SHOULD return a "Bad Format" error (however, some existing implementations return a "Not Acceptable" error in such circumstances):
+Certain namespaces are reserved in Jabber (namespaces beginning with 'jabber:' or 'http://jabber.org/', as well as 'vcard-temp'). If a user attempts to get or set jabber:iq:private data in a reserved namespace, historically some server implementations have chosen to return an error (commonly "Not Acceptable") to the sender. Such behavior is OPTIONAL, but may be encountered by clients when interacting with some existing server implementations.
+| Condition | Description |
|---|---|
| Bad Format | The IQ get does not contain a child element. |
| Forbidden | The IQ get or set is sent to a JID other than that of the sender. |
| Not Acceptable | The IQ get or set is qualified by a reserved namespace. |
A server MUST NOT allow any entity other than an authorized resource of the user to create, update, or delete private XML stored on behalf of that user.
+This JEP requires no interaction with &IANA;.
+No action on the part of the ®ISTRAR; is necessary as a result of this JEP, since 'jabber:iq:private' is already a registered namespace.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0049: http://www.jabber.org/jeps/jep-0049.html
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+This JEP specifies a protocol for an entity to initiate a command session, where there is no preferred namespace. It also specifies a protocol for describing the types of ad hoc sessions, similar in concept to a menu.
+The motivation for such a protocol comes from the desire to expand Jabber outside the domain of instant messaging. Similar to web applications, these "Jabber applications" are systems in which, via a compliant Jabber client, a user (or automated process) can interact with the application. The client need not be specially-written in order to take advantage of this Jabber application.
+This mechanism allows for a larger base of Jabber entities to participate as part of larger application architectures. Although specialized clients would be preferred in many environments, this protocol allows for applications to have a wider audience (i.e., any compliant Jabber client).
+The namespace governing this protocol is "http://jabber.org/protocol/commands" (hereafter referred to as x-commands). This namespace relies on the &IQ; element for execution, and can use the &MESSAGE; element for announcing command lists. This protocol depends on &jep0030; for reporting and announcing command lists. This namespace is intended to complement &jep0004; (jabber:x:data), but is not necessarily dependent upon it.
+Support of x-commands implies support for "jabber:x:data" (although this requirement may be replaced and/or amended with a requirement to support &jep0020; by performing the appropriate negotations before executing commands). x-commands provides a bootstrap for performing ad-hoc "jabber:x:data" processes, while the data itself is conveyed using "jabber:x:data".
+The x-commands namespace is not designed to replace machine-to-machine oriented RPC systems such as &jep0009;, where the two entities fully understand the command's purpose and behavior prior to execution. x-commands is oriented more for human interaction, where the user agent (such as a compliant Jabber client) most likely has no prior knowledge of the command's purpose and behavior.
+To determine if an entity supports x-commands, the requester uses Service Discovery. The requester makes an "#info" query to the responder. If supported, the responder includes a <feature/> with the "var" of "http://jabber.org/protocol/commands".
+To find what commands an entity provides, the requester uses Service Discovery. Each command is a node of the responder, under the fixed node "http://jabber.org/protocol/commands" (for which the service discovery identity category is "automation" and type is "command-list"). Use of a fixed node for all commands of an entity allows for immediate retrieval of commands.
+Each command is a disco item. The node attribute of <item/> identifies the command, and the name attribute is the label for the command.
+The requester retrieves the list of commands by querying for the responder's items for the node "http://jabber.org/protocol/commands":
+The result can then be used by the client to populate a menu, a dialog of buttons, or whatever is appropriate to the current user interface. The responder is not required to send the same list of commands to all requesters.
+If additional information about a command is desired, the requester queries for disco information on the command node:
+A responder MUST at least provide <identity category='automation' type='command-node'/> and <feature var='http://jabber.org/protocol/commands'/>, and SHOULD include <feature var='jabber:x:data'/>. It is not required to support additional information about a command. If the command is not available to the requester, the responder SHOULD respond with a 403 "Forbidden" error.
+In some cases, a responder entity may find it appropriate to automatically push this information (e.g. a subscribed entity becomes available). In this case, the entity sends a &MESSAGE; containing the proper disco#items &QUERY;:
+The only portion required is <query xmlns='http://jabber.org/protocol/disco#items'/>. Any other information (such as the <subject/> in the foregoing example) is OPTIONAL.
+To execute a command, the requester sends an &IQ; containing the command to execute:
+The requester MAY include the "action='execute'", although this is implied.
+If the command does not require any user interaction (returns results only), the responder sends a packet similar to the following:
+The above example shows the command execution resulting in a "jabber:x:data" form. It is also possible that one or more URLs (specified via &jep0066;) could be returned.
+If the command requires more interaction, the responder sends a result &IQ; that contains the command information and the form to be filled out:
+The <command/> SHOULD include an <actions/> element, which specifies the details of what the allowed actions are for this stage of execution. Each element within <action/> matches a possible value for the <command/> element's "action" attribute. The "execute" attribute defines which of the included actions is considered the equivalent to "execute" for this stage. In the above example, the only allowed action is to progress to the next stage, which is also the default.
+The requester then submits the form, maintaining the command node and sessionid:
+The responder then provides the next stage's form in the result
The requester then submits the second stage's form, again maintaining the node and sessionid:
+If the requester wishes to revert to the previous stage, it sends an &IQ; with the command's node and sessionid, and "action='prev'":
+If the responder accepts this, it responds with the previous stage's command
In the case where a command has multiple stages, the requester may wish to cancel at some point. To cancel, the requester sends the continuing command request with an "action='cancel'":
+This enables the responder to free any resources allocated during the process. The responder MUST reply with the success of the command:
+All commands used in the above examples are for illustrative purposes only. There are no predefined or required commands.
+Each command is identified by its 'node' attribute. This matches the 'node' attribute from the service discovery <item/> element. Service Discovery requires that all 'node' values be unique within a given JID. This JEP requires that the 'node' value used in <command/> exactly match the value used in the <item/> element. It is the responsibility of the responder implementation to ensure each command's node is unique for their JID.
+The execution of a command exists within the concept of a session. Each session is identified by the 'sessionid' attribute, and SHOULD be valid only between one requester/responder pair. The responder is responsible for determining the session lifetime, with some help from the requester.
+The requester starts a new session for a command by simply sending a <command/> with the 'node' attribute (and optionally the 'status' attribute with a value of "execute"). Once the 'sessionid' attribute is given to the requester, it is the requester's responsibility to maintain it for the session's lifetime. A session ends when the responder sends a <command status='completed'/> or the requester sends a <command action='cancel'/> with the provided 'sessionid' value.
+Once a session has ended, its 'sessionid' value SHOULD NOT be used again. It is the responder's responsibility to ensure that each 'sessionid' value is unique.
+It may be possible for a requester to be executing more than one session of the same command with a given responder. If the responder does not allow more than one session of the same command with the same requester, the responder MUST return a ¬allowed; error (see &jep0086;).
+The result for each stage (other than the last) of a command's execution SHOULD include an <actions/> element. The user-agent can use this information to present a more-intelligent user interface, such as a "druid" or "wizard".
+For a user-agent, a typical interpretation of the <actions/> information (or lack thereof) would be the following:
+-
+
- The action "cancel" is always allowed. +
- If there is no <actions/> element, the user-agent can use a single-stage dialog or view.
+
-
+
- The action "execute" is equivalent to the action "complete". +
+ - If there is an <actions/> element, the user-agent usually uses a multi-stage dialog or view, such as a wizard.
+
-
+
- The action "execute" is always allowed, and is equivalent to the action "next". +
- The "prev" action is typically the "back" or "previous" button or option in a wizard. If <prev/> is not contained by the <actions/>, it is disabled. +
- The "next" action is typically the "next" button or option in a wizard. If <next/> is not contained by the <actions/>, it is disabled. +
- The "complete" action is typically the "finish" or "done" button or option in a wizard. If <complete/> is not contained by the <actions/>, it is disabled. +
- If the <actions/> possesses the "execute" attribute, that value is the default button or option. If the <actions/> does not possess the "execute" attribute, there is no default button or option. +
+
Responders SHOULD use the following guidelines when providing <actions/>:
+-
+
- The "execute" attribute SHOULD NOT specify a value that does not match one of the allowed actions. +
On its own, the <command/> has very little usefulness. It relies on its payload to give full meaning to its use. The payload can be elements in any namespace that makes sense and is understood (such as "jabber:x:data"), and/or one or more <note/> elements. Any namespaced elements can be used within a <command/>. The only limitations are that the elements not require certain parent elements (such as &IQ;), or specifically allow for <command/> qualified by the "http://jabber.org/protocol/commands" namespace as a possible parent element.
+As a general rule, the payload is provided only by the responder. The primary exception to this rule is with the "jabber:x:data" extension (and other namespaces with similar semantics). In this case, if the responder provides a form to submit, the requester SHOULD respond with the submitted data (using the semantics from JEP-0004).
+When the precedence of these payload elements becomes important (such as when both "jabber:x:data" and "jabber:x:oob" elements are present), the order of the elements SHOULD be used. Those elements that come earlier in the child list take precedence over those later in the child list. The requester SHOULD consider those elements qualified by the same namespace as having an equivalent precedence (such as if multiple "jabber:x:oob" elements are included).
+When the payload is "jabber:x:data", there are certain conditions applied. The requester SHOULD NOT use a "jabber:x:data" type other than "submit". Responders SHOULD consider any <x type='cancel'/> to be <x type='submit'/>.
+The status of command execution signals only if the command is executing, has been completed, or been canceled. If completed, the "status" attribute does not specify if it completed successfully or not. If a command completes but fails, the responder MUST include at least one <note type='error'/> with the <command status='completed'/> it returns.
+The requester SHOULD provide its locale information using the "xml:lang" attribute on either the &IQ; (RECOMMENDED) or <command/> element. Each execution session (identified by the "sessionid" attribute) SHOULD use only one language/locale, and requesters and responders SHOULD assume the first language/locale specified applies. The responder SHOULD specify the language/locale with the every command session's response.
+Within the "http://jabber.org/protocol/commands" schema, the language/locale applies only to the human-readable character data for <info/> elements. It SHOULD also apply to all payload elements, appropriate to their respective specifications.
+Responders MUST take this into consideration, and properly account for the language/locale settings within payloads. If the responder cannot accomodate the requested language/locale, it SHOULD respond with a <bad-request/> (<bad-locale/>) error condition.
+The focal element in x-commands is <command/>. It is the element used to guide the process, and the element used to report command options.
+Each <command/> contains attributes for a node, a "session id", an action type, a status type, and a language/locale specifier. A command MAY contain zero or more <note/> elements and MAY contain other namespaced elements as payload. Elements qualified by the "jabber:x:data" and "jabber:x:oob" namespaces are the typical payload.
+The "node" attribute uniquely identifies the command. This attribute MUST be present.
+The "sessionid" attribute helps to track a command execution across multiple stages. This attribute MUST be present for subsequent stages, and the responder SHOULD initialize (if not provided) or maintain this attribute. The value of this attribute MUST NOT be empty or null, but otherwise can be any string value. This value MUST be maintained by a requester while executing a command.
+The "status" attribute describes the current status of this command. This value SHOULD be set only by the responder. If specified by the requester, the responder MUST ignore it. The value of "status" MUST be one of the following:
+| Status | +Description | +
|---|---|
| executing | +The command is being executed. | +
| completed | +The command has completed. The command session has ended. | +
| canceled | +The command has been canceled. The command session has ended. | +
The "action" attribute specifies the action to undertake with the given command. This value SHOULD be set only by the requester. If specified by the responder, the requester MUST ignore it. The value of "action" MUST be one of the following:
+| Action | +Description | +
|---|---|
| execute | +The command should be executed or continue to be executed. This is the default value. | +
| cancel | +The command should be canceled. | +
| prev | +The command should be digress to the previous stage of execution. | +
| next | +The command should progress to the next stage of execution. | +
| complete | +The command should be completed (if possible). | +
The "xml:lang" attribute specifies the language/locale this <command/> is intended for. This element MAY be specified by the requester to request a specific language/locale, and SHOULD be included by the responder to indicate the language/locale in use.
+The children of a <command/> element (other than <actions/> and <note/>) pertain to the command's execution. The order of these elements denote their precedence, so that those elements earlier in the list have higher precedence.
+The allowed actions for a particular stage of execution are provided by the <actions/> element. This element SHOULD be provided by the responder if the command's execution is not complete, and SHOULD NOT ever be provided by the requester. It contains a single attribute to specify what the "execute" action equals. It contains child elements to specify what the allowed actions are.
+The "execute" attribute specifies what the action "execute" is equivalent to. In user-agent interfaces, this represents the default behavior. This attribute MAY be specified by the responder, and MUST equal one of the "action" attribute values for <command/>. The value of this attribute SHOULD match the local name of one of the contained child elements.
+The child elements contained by <action/> specify the allowed actions. The name of each child element MUST be one of the following:
+-
+
- prev +
- next +
- complete +
Notes about the current status of commands are provided by <note/> elements. This element contains information about current conditions in a command sequence. This element has an attribute that defines the type of note. The body of a <note/> should contain a user-readable text message.
+The "type" attribute specifies the severity of the note. This attribute is OPTIONAL, and implies "info" if not present. The value of this attribute MUST be one of the following:
+| Type | +Description | +
|---|---|
| info | +The note is informational only. This is not really an exceptional condition. | +
| warn | +The note indicates a warning. Possibly due to illogical (yet valid) data. | +
| error | +The note indicates an error. The text should indicate the reason for the error. | +
To simplify the discussion on error conditions, this document uses the following mapping between namespace URIs and namespace prefixes
| Prefix | +URI | +
|---|---|
| xmpp | +urn:ietf:params:xml:ns:xmpp-stanzas | +
| cmd | +http://jabber.org/protocol/commands | +
Below are the possible errors that can occur during execution.
+| Error Type | +General Condition | +Specific Condition | +Description | +
|---|---|---|---|
| modify | +<xmpp:bad-request/> | +<cmd:malformed-action/> | +The responding JID does not understand the specified action. | +
| modify | +<xmpp:bad-request/> | +<cmd:bad-action/> | +The responding JID cannot accept the specified action. | +
| modify | +<xmpp:bad-request/> | +<cmd:bad-locale/> | +The responding JID cannot accept the specified language/locale. | +
| modify | +<xmpp:bad-request/> | +<cmd:bad-payload/> | +The responding JID cannot accept the specified payload (e.g. the data form did not provide one or more required fields). | +
| modify | +<xmpp:bad-request/> | +<cmd:bad-sessionid/> | +The responding JID cannot accept the specified sessionid. | +
| cancel | +<xmpp:not-allowed/> | +<cmd:session-expired/> | +The requesting JID specified a sessionid that is no longer active (either because it was completed, canceled, or timed out). | +
| cancel | +<xmpp:forbidden/> | +NONE | +The requesting JID is not allowed to execute the command. | +
| cancel | +<xmpp:item-not-found/> | +NONE | +The responding JID cannot find the requested command node. | +
| cancel | +<xmpp:feature-not-implemented/> | +NONE | +The responding JID does not support "http://jabber.org/protocol/commands". | +
Determining when a command can be executed based on permissions or rights is considered outside the scope of this JEP. Although such mechanisms are considered specific to the application and/or implementation of this JEP, future JEPs may address these concerns.
+When processing reported commands, the requester SHOULD consider any command node that does not match the JID of the responder to be suspicious, and ignore those command nodes. Responders MUST report their own command nodes only, and not the command nodes of other entities. This can help prevent limited cases of spoofing and "social engineering".
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'http://jabber.org/protocol/commands' in its registry of protocol namespaces.
+The Jabber Registrar includes "automation" in its registry of Service Discovery categories for use for any entities and nodes that provide automated or programmed interaction. This category has the following types:
+| Type | +Description | +
|---|---|
| command-list | +The node for a list of commands; valid only for the node "http://jabber.org/protocol/commands". | +
| command-node | +A node for a specific command; the 'node' attribute uniquely identifies the command. | +
The registry submission is as follows:
+
+ automation
+ The "automation" category consists of entities and nodes that provide automated or programmed interaction.
+
+ command-list
+ The node for a list of commands; valid only for the node "http://jabber.org/protocol/commands"
+ JEP-0050
+
+
+ command-node
+ A node for a specific command; the 'node' attribute uniquely identifies the command
+ JEP-0050
+
+
+ ]]>
+ The Jabber Registrar includes "http://jabber.org/protocol/commands" in its registry of well-known Service Discovery nodes.
+As authorized by &jep0147;, the Jabber Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).
+The "command" querytype is defined herein for interaction with entities that support the ad-hoc command protocol, with keys of "action" and "node".
+The following submission registers the "command" querytype.
+
+ command
+ http://jabber.org/protocol/commands
+ enables completion of ad-hoc commands
+ JEP-0050
+
+
+ action
+ the ad-hoc commands action type
+
+
+ cancel
+ a request to cancel processing of the command
+
+
+ complete
+ a request to complete processing of the command
+
+
+ execute
+ a request to execute the command (the default implied action)
+
+
+ next
+ a request to move to the next command in a series
+
+
+ complete
+ a request to move to the previous command in a series
+
+
+
+
+ node
+ the command node
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0050: http://www.jabber.org/jeps/jep-0050.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
++To be written. +
++ This document describes a general request redirection mechanism for Jabber queries. +
++ There are cases where only the receiver of a query, e.g. the receiver of <iq type='get'/> requests, knows the real location of the targeted data object. Reasons might be load balancing, changes in the protocol and/or usage patterns, or an additional level of indirection for improved flexibility. The possible reasons are very similar to reasons for (temporary) HTTP redirection. +
++ Redirection adds an additional feature to the protocol. But it also adds also a small amount of complexity to implementations. The mechanism has been designed in a way such that it affects implementations only minimally while providing maximum flexibility. +
++ For security reasons the redirection mechanism is only valid for <iq type='get'/> packets. +
++ A client sends a query to a server. The server may well be an other client acting as a server for this transaction. The server decides that it can not serve the original request. It redirects the request to an other server. In order to do so, it sends a redirection query to the client. The redirection query informs the client about the modified query including the new destination. The client then repeats the request by sending the redirected query to other server. +
++ The meaning of <iq/> queries is specified by multiple parameters, i.e. JID, <query/> namespace, and namespace specific tags and attributes. Many of these parameters may change during the redirection. To allow for maximum flexibility, the redirection query contains the complete redirected query. +
++ The redirection query is identified by the "type" attribute and by the code of an embedded <error/> tag. The code is "302". The redirection is meant to be temporary, not permanent. +
++ The original query is returned as a child of the <iq type='error'/>.
++ The redirected query sent from the server back to the client is embedded into the <error/> tag. +
++ The envelope of the redirected query must preserve all attributes of the initial query except for the destination JID ("to" attribute). In particular, it must preserve the "id" attribute. +
++ The must not redirect any query other than <iq type='get'/>. +
++ The redirected query may target a different entity than the original query and it may have different parameters. But the redirected query must be manufactured in such a way that the result returned from the redirected query is compatible with the original query.
+The client must check the redirected query. The redirected query is valid only if all three of the following conditions are met:
+-
+
- the original query is <iq type='get'/> +
- the redirected query is <iq type='get'/> +
- the <iq/> envelope of the redirected query has all attributes of the original query except for the "to" attribute +
+ If redirections are cascaded then the client should stop the sequence after a reasonable number of redirections. Three consecutive redirects, which make a total of four trials, should be enough. +
++ Applications must not rely on more than three consecutive redirections for a single query. +
++ The redirection mechanism can be implemented transparently for the protocol engine. The client should unwrap the redirected query, check for validity, and send the data to the connection.
+Protocol implementations do not have to create a new request context. The request context of the original query will still be valid since the redirector must preserve the query id.
++ The query id is often used by the protocol engine to relate queries sent and queries received in order to form request-response pairs. Using the query id the client can find the related original query when the result of the redirected query returns. +
++ However, the client must check the validity before re-sending the redirected query. +
++ This document describes a connection transfer mechanism for telling clients (or others) to reconnect to a different address. +
++ This is useful for transfering people to a different server in a cluster if it is going down for maintenance or during login to transfer the person to a certain server in a cluster. +
++ The transfer packet is addressed to the user from the domain they are logged into, it contains the server address to connect to which can be domain name or ip address, it can also contain an optional port number. There is also the domain specified just in case they have to use a different domain name when they log in or to maintain the original domain. +
++ This document describes the http://www.jabber.org/protocol/filexfer + namespace, which is used for offering and transferring files from one Jabber + ID to another. It tries to expand the basic method (iq:oob) that currently + exists to allow for numerous stream methods, and more detailed file + information before accepting an offer. This JEP only describes the + negotiation method and suggests how streams could link back to the + negotiated information. +
++ This JEP covers one use case of sending a file to another user. Future JEPs + may enhance this to include searching and offering. +
+ +Primary Flow:
+-
+
- Determine if the receiver supports FT through disco/browse. [E1] +
- Sender sends meta-data and available methods to receiver +
- Receiver sends the accepted method to Sender and any range/offset + information. [E2],[E3] +
- Sender and Receiver establish the negotiated method[E4] +
- Sender sends data as described by method +
- After the stream closes the Receiver notifies the Sender of + completion. [E5] +
- END +
Errors Conditions:
+-
+
- User does not support filetransfer. END +
- Receiver rejects send. END +
- Receiver does not have any methods shared with the sender. END +
- The stream is unable to be started. END +
- The Receiver notifies sender of an error transferring. END +
+ In order to send a file, the sender must first tell the receiver a little + bit about the file to make sure they will accept it. At the same time they + list the stream methods they support in the order they wish to use them. + This is done by sending the information in the http://www.jabber.org/protocol/filexfer namespace. +
+ ++ That is the basic request, a more complete requeset with range support is + shown below. +
+ +If a receiver decides to accept an offered file they request it from the sending with an <iq/> type result. The receiver sends back the id of the file being sent, the method they wish to use, and the range they wish to download (if the sender announced support). When range support is being used the receiver MUST specify the length and MAY specify a beginning offset with the acceptance.
+ ++ If the receiver decides to not accept the file they SHOULD send back an + error 403 to the sender. +
+ ++ If the receiver does not support any of the offered stream methods they + SHOULD send back an error 406 to the sender. +
+ ++ At this point the sender will setup the stream method and begin to transfer + data. The stream itself can use the file transfer namespace to tie the + meta-data to the actual data sent, this is illustrated below using iq:oob. +
+ ++ If the receiver is unable to start the negotiated stream for any reason they + should send an <error/> with a 502 code to the sender. +
+ ++ Once the data has been transferred the receiver SHOULD send the sender a + notification that the transfer completed. This is done by sending an + <iq/> type set with the file id and a completed action. +
+ ++ If the transfer does not complete, for any reason after the meta-data + negotiation, the party that has the error SHOULD send an error 500 and + the file id to the other party. +
+ +By staying in just the realm of negotiating the meta-data to a file, we allow for multiple transport layers, or streams, to be used. Some streams will need to tie the meta-data to the actual data transfer, to help accomodate this the stream may use the <file/> with an action of start and the correct id. The <file/> could be transported in the stream negotiations, or along side it. Although this spec does not mandate any specific methods to new stream authors, it does provide the syntax for the currently existing "iq:oob" system.
+For an "iq:oob" transfer to be related to it's meta-data, a <file/> is transported along side the <query/>. The id used on the <file/> is the id for the meta-data of the actual data that is being sent. The action on the <file/> is "start". An example of this can be found in the Basic Usage section.
+
+
+
+
+
+ mime-type CDATA #OPTIONAL
+ date CDATA #OPTIONAL
+ hash CDATA #OPTIONAL
+
+ ]]>
+ The <file/> element is the "workhorse" element. This element is used to convey meta-data and report file transfer actions. This elemnt contains attributes for file meta-data and actions, and MAY contain a <desc/>, a <range/>, and zero or more <feature xmlns='jabber:iq:negotiate'/>
The "id" attribute specifies the identifier for this particular file transfer. This attribute MUST be present at all times. There are no value requirements other than it MUST be unique between the sender and receiver.
+The "action" attribute specifies the action to undertake with the given file. This attribute SHOULD be present in most cases. If not present, the value "offer" is implied. The value of "action" MUST be one of the following:
+| Value | +Description | +
|---|---|
| complete | +The file transfer is complete. | +
| get | +The file transfer should start. | +
| offer | +The file transfer is offered (meta-data MUST be present) | +
| start | +The file transfer is starting. | +
| error | +The file transfer has failed. The outlying error tag has more + information. + | +
The "name" attribute specifies the file name. This attribute MUST be present if the action is "offer", otherwise it SHOULD NOT be present.
+The "size" attribute specifies the file size, in bytes. This attribute MUST be present if the action is "offer", otherwise it SHOULD NOT be present.
+The "mime-type" attribute specifies the MIME-type for the file. This attribute SHOULD be present if the action is "offer", otherwise it SHOULD NOT be present. The value of this attribute MUST follow the specification for MIME-types from RFC-2046
The "date" attribute specifies the file date. This attribute MAY be present if the action is "offer", otherwise it SHOULD NOT be present. The value MUST follow the specification for ISO 8601 date/time formats
The "hash" attribute specifies the hash of the file contents. This attribute MAY be present if the action is "offer", otherwise it SHOULD NOT be present. The value MUST be an SHA1 hash of the file contents.
+The <desc/> element contains a human-readable description of the file. This element has no attributes, and contains character data content.
+The <range/> element describes range information for a partial transfer. This element has attributes to define the range length and range offset. This element contains no content.
+The "length" attribute defines the range length, in bytes. This attribute MUST be present if the containing <file/> has an action value of "get", otherwise it SHOULD NOT be present. The value of this attribute MUST be an integer value and MUST be less than or equal to the (size + offset) of the file.
+The "offset" attribute defines the range offset, in bytes. This attribute MAY be present if the containing <file/> has an action value of "get", otherwise it SHOULD NOT be present. If this attribute is not present, a value of 0 is implied. The value of this attribute MUST be an integer, MUST NOT be less than 0, and MUST be less than (size - length).
++ There are three main error conditions in file transfer. Following are the + conditions, error codes and descriptions: +
-
+
- + Declining Transfer (403): During the meta-data negotiation + the receiver may decline the transfer by sending the 403 error. The + <error/> CDATA MAY contain a descriptive reason why, but is not + necessary. + +
- + No Available Methods (406): When the sender presents the + available stream methods, and the receiver can not use any of them, + they send a 406 error. The <error/> CDATA is not important. + +
- + Transfer Failed (500): If the file transfer fails for any + reason after negotiation, the error generator SHOULD send a 500 error + to the other party. This is the only error message that both the + sender and reciever may send. The <error/> CDATA MAY contain + information about the failure. + +
- + Unable to Start Stream (502): When the receiver is unable to + start the negotiated stream method they send a 502 error to the + sender. The <error/> CDATA is not important. + +
+ Data integrity can be checked with the sha1 of the file that is sent. This + could be attacked via a man in the middle attack, but much more embarrasing + things could result from that than a bad file. The wire integrity is left + to the stream method. +
++ The mime-type attribute on <file/> is a valid MIME type as controlled + by the IANA. +
++ The "http://jabber.org/protocol/filexfer" is the only namespace that needs + to be registered with the JANA. +
+As the &JSF; publishes more protocol specifications (see &jep0001;), it becomes necessary to keep better track of the namespaces defined by those specifications as well as the parameters used in the context of the relevant protocols. (Examples of such parameters include the features and options used in &jep0020; and the identities and features used in &jep0030;.) In particular, the common use of protocols published by the JSF requires that namespaces and particular parameter values be assigned uniquely. It is the role of the Jabber Registrar to make those unique assignments and to maintain registries of the currently assigned values. The Jabber Registrar shall also function as a single point of contact between the Jabber community and &IANA;.
+Until there is a perceived need for a more formal governing body, the functions of the Jabber Registrar shall be managed by the &EDITOR;. In the future, the &COUNCIL; and/or the &BOARD; may decide to create a more formal panel to oversee the functions of the Jabber Registrar; if they do, this JEP shall be updated to reflect the change.
+Every Jabber Enhancement Proposal (JEP) must contain a section devoted to "Jabber Registrar Considerations", detailing the namespaces and parameters to be registered with the Jabber Registrar, as well as any new registries to be created as a result of the JEP.
+The registry additions or creations specified in a JEP shall not take effect until the JEP advances to a status of Draft (Standards-Track JEPs) or Active (Informational and Historical JEPs). Registration of namespaces shall be initiated by the JEP Editor when a JEP advances to Draft or Active and shall not require the involvement of the JEP author. Registration of particular parameters used within a specification shall be initiated by the JEP Editor if specified in the JEP, and may also be initiated by implementers of the JEP after it has advanced to Active, Draft, or Final. Creation of new registries shall be initiated by the Jabber Registrar; if a JEP specifies the creation of a new registry, the JEP author is strongly encouraged to consult with the Jabber Registrar before seeking a Last Call on the JEP.
+Requests for namespace and parameter assignments must be sent to the Jabber Registrar in accordance with the process specified in the document (usually a JEP) that defines the relevant registry, normally by sending an appropriately formatted email message to <registrar@jabber.org>. If, in the Registrar's judgment, discussion of a request is required, the Registrar shall initiate such discussion within the &SJIG;. The Registrar shall add registry items at his discretion based on discussion within the Standards JIG if necessary, but shall not unduly restrict registration of parameter values. If a JEP author or implementer thinks that a request was unfairly denied by the Registrar, an appeal of the decision may be directed to the Jabber Council.
+The Jabber Registrar shall maintain registries of assigned namespaces and parameters at <http://www.jabber.org/registrar/> and shall update those registries in a timely fashion. Changes to JSF registries shall be announced on the Standards-JIG mailing list.
+Security considerations are primarily the responsibility of the protocols in which specific parameters are used. The Jabber Registrar shall respect the security considerations defined in JSF protocol specifications, and shall endeavor to ensure that registered parameter values do not compromise privacy or security in any way.
+The Jabber Registrar shall be responsible for interacting with the IANA on behalf of the Jabber community. If a JEP requires interaction with the IANA, that fact shall be noted by the JEP author in the JEP and discussed on the Standards-JIG mailing list along with normal discussion of the JEP. The Jabber Registrar shall collaborate with the JEP author to present an appropriate request to the IANA.
+This entire document defines the processes and procedures of the Jabber Registrar.
+This JEP documents the vCard-XML format currently in use within the Jabber community. A future JEP will recommend a standards-track protocol to supersede this informational document.
+The basic functionality is for a user to store and retrieve an XML representation of his or her vCard using the data storage capabilities native to all existing Jabber server implementations. This is done by by sending an <iq/> of type "set" (storage) or "get" (retrieval) to one's Jabber server containing a <vCard/> child scoped by the 'vcard-temp' namespace, with the <vCard/> element containing the actual vCard-XML elements as defined by the vCard-XML DTD. Other users may then view one's vCard information.
+vCards are an existing and widely-used standard for personal user information storage, somewhat like an electronic business card. The vCard format is defined in &rfc2426;.
+In 1998 and 1999, Frank Dawson submitted four revisions of an Internet-Draft proposing to represent the standard vCard format in XML. When the Jabber project was originally looking for a method to store personal user information, the most recent revision was draft-dawson-vcard-xml-dtd-01
Unfortunately, Dawson's proposal did not move forward within the IETF's standards process. For reasons now lost in the mists of time, the Jabber project continued to use the DTD from draft-dawson-vcard-xml-dtd-01, making two small modifications to adapt it for use within Jabber (adding the JABBERID and DESC elements) but also specifying element names in all caps rather than lowercase as defined in draft-dawson-vcard-xml-dtd-01. In addition, the Jabber community followed the usage (but not DTD) in that draft regarding version information, including it as an attribute of the vCard element rather than as a child element. This format was implemented within Jabber under the 'vcard-temp' namespace.
+A user may retrieve his or her own vCard by sending XML of the following form to his or her own JID (the 'to' attibute SHOULD NOT be included):
+The server should then return the vCard to the user:
+A user may update his or her vCard by sending an IQ of type "set" to the server, following the format in the previous use case.
+If a user attempts to perform an IQ set on another user's vCard, the server MUST return a 403 "Forbidden" error.
+A user may view another user's vCard by sending an IQ of type "get" to the other user's bare JID. A compliant server MUST return the vCard to the requestor and not forward the IQ to the requestee's connected resource.
+The server should then return the other user's vCard to the requestor:
+There are no security features or concerns related to this proposal.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes the 'vcard-temp' namespace in its registry of official namespaces (see &NAMESPACES;).
+As authorized by &jep0147;, the Jabber Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).
+The "vcard" querytype is registered as a vCard-related action.
+The following submission registers the "vcard" querytype.
+
+ vcard
+ vcard-temp
+ enables retrieval of an entity's vCard data
+ JEP-0054
+
+ ]]>
+ Note the following:
+-
+
- The correct capitalization of the wrapper element is <vCard/> (and XML element names are case-sensitive). +
- All elements within the <vCard/> element MUST be in ALL CAPS (even though this is at odds with draft-dawson-vcard-xml-dtd-01). +
- The country abbreviation is contained in a <CTRY/> element, not a <COUNTRY/> element (even though this is at odds with draft-dawson-vcard-xml-dtd-01). +
- Phone numbers MUST be contained in a <NUMBER> element, not included as CDATA within the <TEL/> element. +
- If no telephone number is included in a <TEL/> element, an empty <NUMBER/> child MUST be included. +
- Email addresses MUST be contained in a <USERID> element, not included as CDATA within the <EMAIL/> element. +
- Some Jabber implementations add a 'version' attribute to the <vCard/> element, with the value set at "2.0" or "3.0". The DTD is incorrect, and the examples in draft-dawson-vard-xml-dtd-01 clearly show that version information is to be included by means of a 'version' attribute, not the <VERSION/> element as defined in the DTD. However, to conform to draft-dawson-vard-xml-dtd-01, the value should be "3.0", not "2.0". +
The following DTD is a slightly modified version of that contained in draft-dawson-vcard-xml-dtd-01. The only modifications were to add the JABBERID and DESC elements.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+This JEP documents a protocol currently used to search information repositories on the Jabber network. To date, the jabber:iq:search protocol has been used mainly to search for people who have registered with user directories (e.g., the "Jabber User Directory" hosted at users.jabber.org). However, the jabber:iq:search protocol is not limited to user directories, and could be used to search other Jabber information repositories (such as chatroom directories) or even to provide a Jabber interface to conventional search engines.
+The basic functionality is to query an information repository regarding the possible search fields, to send a search query, and to receive search results. Note well that there is currently no mechanism for paging through results or limiting the number of "hits", and that the allowable search fields are limited to those defined in the XML schema; however, extensibility MAY be provided via the &jep0004; protocol, as described below.
+In order to search an information respository, a user first needs to discover what search fields are supported by the service:
+The service MUST then return the possible search fields to the user, and MAY include instructions:
+The user MAY then submit a search request, specifying values for any desired fields:
+The service SHOULD then return a list of search results that match the values provided:
+If there are no matching directory entries, the service MUST return an empty <query/> element:
+The fields defined in the 'jabber:iq:search' namespace are strictly limited to those specified in the schema. If a host needs to gather additional information, Data Forms SHOULD be used; a host MUST NOT add new fields to the 'jabber:iq:search' namespace. Support for extensibility via Data Forms is RECOMMENDED, but is not required for compliance with this JEP.
+The extensibility mechanism for searching makes use of a hidden FORM_TYPE field for the purpose of standardizing field names within the form, as defined in &jep0068;. Implementations supporting this extensibility mechanism SHOULD support field standardization as well.
+There are no security features or concerns related to this proposal.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; shall include the following information in its registries.
+The Jabber Registrar includes the 'jabber:iq:search' namespace in its registry of protocol namespaces.
+The following fields are reserved for use within jabber:x:data forms scoped by a FORM_TYPE of 'jabber:iq:search'; additional fields MAY be added via the Jabber Registrar's normal registration process but are outside the scope of this JEP.
+
+ jabber:iq:search
+ JEP-0055
+ Forms enabling directory searches.
+
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0055: http://www.jabber.org/jeps/jep-0055.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
++ANSI X.12, EDIFACT/UN and ebXML are all standards. This JEP describes a fundamental approach to transmit messages that conform to these standards. +
+ +EbXML
+ebXML Messages SHALL be transmitted within Jabber IQ chunks. The value of the 'type' attribute SHALL be 'set' and the chunk SHALL contain a <query/> child element with the namespace declaration set to 'http://jabber.org/protocol/ebxml'. The query element MUST contain the pure ebXML message. No SOAP envelope SHALL exist around the ebXML message. Reception of an ebXML iqed message must be acknowledged with an iq chunk including an empty query tag of the same namespace, the iq tag SHALL have the same ID. +
+ ++EbXML information is always transmitted in this envelope. No transformation of native ebXML tags into native Jabber tags is performed (e.g., ebXML reception receipt into Jabber reception receipt). The business logic, on top of Jabber transport logic, has to parse incoming IQ chunks and forward received ebXML information to the ebXML Messaging Service. The business logic has as well to pack the ebXML messages into IQ chunks and invoke the message delivery. +
+
+Although a complex business transaction between two or more Trading Partners might require a payload that contains an array of business documents, binary images, or other related Business Information'
It has to be noted: The karma restriction of XMPP, implied on clients, makes transmission of large amounts of payload (at the moment) to services or other clients from client side nearly impossible. However, components' karma is not restrained. +
+ ++The previous example transmits a query to a database with an ebXML interface. A requester searches for all companies dealing with 'Integrated curcuit components', here with UNSPSC code '321118'. +
+ + ++This prior xml code is the result which every recieving unit has to send, after successfully recieving the iq chunk. Note, that this does not mean, the ebxml chunk has been accepted, parsed, or whatever, this is only on jabber level. +
+ +ANSI X.12 is a character oriented protocol. X.12 is separated into segments. Segments are separated by an asterisk
ANSI X.12 messages SHALL be delivered in a query tag of an IQ chunk. The IQ chunk's type attribute SHALL be set to 'set'. The query's namespace attribute SHALL be set to 'http://jabber.org/protocol/ansi_x.12'. The query tag shall contain the ANSI X.12 message. The ANSI X.12 message SHALL NOT be Base64 encoded, but SHALL be XML aware.
++EDIFACT/UN is very similar to X.12 and differs only in the meaning of tags and in some syntactical details. +
+EDIFACT/UN messages SHALL be delivered in a query tag of an IQ chunk. The IQ chunk's type attribute SHALL be set to 'set'. The query's namespace attribute SHALL be set to 'http://jabber.org/protocol/edifact'. The query tag SHALL contain the UN/EDIFACT message. The UN/EDIFACT message SHALL NOT be Base64 encoded.
+SAP IDocs SHALL be transmitted in a query tag of an IQ chunk. The IQ chunk's type attribute SHALL be 'set. The query's namespace attribute SHALL be set to 'http://jabber.org/protocol/sap_idoc'. The query tag SHALL contain the iDoc, XML aware. +
+The main purpose of this JEP is to make roster not only a "contact list", but also a "list of useful items". This means that the user has the ability to store not only users' JIDs, but any JID that he wants to quickly access with more information than just the name, subscription and roster groups.
+All information, that can be stored for each item can be divided into three categories:
+-
+
- Information necessary only for server-side. E.g. we can have a server module that can process "visibility" to each user in roster (by sending custom presence to this user automatically, without special client-side support of this). +
- Information, neccessary only for client-side. E.g. user description of this item. +
- Information for both sides. This is at least the JID, category and type. +
Using jabber:iq:private as in JEP-0048
But we have a place where this problem does not exist: jabber:iq:roster. We can store it in <item/> subtags. Existing server implementation MUST NOT remove <x/> tags from it. In this case all information always relates to its JID and disappears when this JID removed.
+JID, category and type are stored as attributes of <item/> tag. Categories and types are the same as in disco. Official categories and types associated with disco are administered by the Jabber Assigned Names Authority (JANA); for details, see http://www.jabber.org/jana/disco.php.
+This information is implementation-dependent, so to provide flexibility for it, the jabber:x:data namespace defined in JEP-0004
This information stored in <x/> tag with namespace jabber:x:roster:item. Following subtags can be used for diferent types of JIDs, however client applications can make this set bigger, to implement more functions.
++ For all categories and types of JID allowed following subtag: +
+-
+
- + desc: A description or note describing the JID. + +
-
+
- + always-visible, always-invisible: + The client should send custom presence to this JID to be always + visible or invisible to it. + +
+ For all JIDs with category=conference allowed following subtags: +
+-
+
- + nick: The nickname to be used when joining the + room. If few such tags in one item, then first is used by default, + and others used if first not available. + +
- + password: The password to be used to joing the + room. + +
- + auto-join: The client should automatically join + this room once the user has been authenticated, and the roster have + been fetched. + +
+ To start editing a file, the user must subscribe to it on special "server" + The server stores text files. A User first can ask for list of these documents. +
++ After that the server returns a list of the documents. For each list + item an ID and description is given. +
+-
+
- +
- +
+ Then the user can send a subscribe request to the server by sending the documents ID. + Attribute type can be rdwr for full access or + rdonly for read-only access. +
++ After successful subscription, the server sends the full contents of the document to + the new editor. +
++ If an editor wants to commit the changes he made, then he sends a patch file to this text + in GNU diff(1) unified format without first two lines (they specify file + names and modification dates, that is not needed). +
++ If server accepts the patch, then it resends it to all subscribed text editors and readers. +
++ If server receives an error IQ reply from one of the editors/readers on any of + above requests, then it must remove him from subscribers list and may + send a message to him about this. +
+ +Per a vote of the Jabber Council, advanced status to Draft.
Clarified terminology regarding pages and result sets.
Reverted to v0.11 with slight wording changes.
Added index attribute to before element; removed index element (use after or before instead).
Made count and index optional, changed protocol for getting count, more clarifications and examples.
Added before and first elements, specified how to return an empty page and how to request the last page, removed reverse order sets, added out-of-order page access.
Eliminated static result sets, justified expanded and clarified dynamic result sets, added page-not-found error, described when minimal state is necessary, added reverse order sets.
Added optional method for handling dynamic result sets.
Updated implementation note to clarify handling of result sets (static vs. dynamic).
Updated implementation note to clarify handling of result sets (static vs. dynamic).
Clarified error handling, determination of support in the context of using protocols, and security considerations.
Specified that an item count may be approximate; specified that an item count may be returned with a page of results.
Added <end/> element to specify last result set; added service discovery information; added more examples.
Revived and renamed the JEP; modified syntax; added use case for getting number of items; defined XML schema.
Initial version.
In &jep0055;, &jep0030;, &jep0060;, &jep0136;, and probably other future XMPP extensions, it is possible to receive large dynamic result sets in response to information requests (e.g., a user directory search on a common first name or a service discovery items request sent to a &jep0045; service). This XMPP protocol extension enables the following functionality for use by other XMPP protocols:
+-
+
- Limit the number of items returned. +
- Page forwards or backwards through a result set by retrieving the items in smaller subsets. +
- Discover the size of a result set without retrieving the items themselves. +
- Retrieve a page (subset) of items starting at any point in a result set. +
In order to limit the number of items of a result set to be returned, the requesting entity specifies a request type of "set" and the maximum size of the desired subset (via the XML character data of the <max/> element):
+The responding entity then returns the first items of the result set in order. The number of items is limited to the requested size:
+An entity often needs to retrieve a page of items adjacent to a page it has already received. For examples, when retrieving a complete result set in order page by page, or when a user 'scrolls' forwards one page.
+The set of items that match a query MAY change over time, even during the time that a requesting entity pages through the result set (e.g., a set of chatrooms, since rooms can be created and destroyed at any time). The paging protocol outlined in this section is designed so that entities MAY provide the following features:
+-
+
- Each page of the result set is up-to-date at the time it is sent (not just at the time the first page was sent). +
- No items will be omitted from pages not yet sent (even if, after earlier pages were sent, some of the items they contained were removed from the set). +
- When paging through the list in order, duplicate items are never received. +
- The responding entity maintains no state (or a single minimal state for all requesting entities containing the positions of all recently deleted items). +
- Rapid calculation of which items should appear on a requested page by responding entity (even for large result sets). +
Note: If a responding entity implements dynamic result sets then receiving entities paging through the complete result set should be aware that it may not correspond to the result set as it existed at any one point in time.
+The request for the first page is the same as when Limiting the Number of Items:
+Responding entity support for paging through a result set is optional. If it does support paging (not just Limiting the Number of Items), then in each page it returns, the responding entity MUST include <first/> and <last/> elements that specify the unique ID (UID) for the first and last items in the page. If there is only one item in the page, then the first and last UIDs MUST be the same. If there are no items in the page, then the <first/> and <last/> elements MUST NOT be included.
+The responding entity may generate these UIDs in any way, as long as the UIDs are unique in the context of all possible members of the full result set. Each UID MAY be based on part of the content of its associated item, as shown below, or on an internal table index. Another possible method is to serialize the XML of the item and then hash it to generate the UID. Note: The requesting entity MUST treat all UIDs as opaque.
+The responding entity SHOULD also include the number of items in the full result set (which MAY be approximate) encapsulated in a <count/> element. The <first/> element SHOULD include an 'index' attribute. This integer specifies the position within the full set (which MAY be approximate) of the first item in the page. If that item is the first in the full set, then the index SHOULD be '0'. If the last item in the page is the last item in the full set, then the value of the <first/> element's 'index' attribute SHOULD be the specified count minus the number of items in the last page.
+Note: The <count/> element and 'index' attribute enable important functionality for requesting entities (for example, a scroll-bar user-interface component). They MAY be omitted, but only if it would be either impossible or exceptionally resource intensive to calculate reasonably accurate values.
+The requesting entity can then ask for the next page in the result set by including in its request the UID of the last item from the previous page (encapsulated in an <after/> element), along with the maximum number of items to return. Note: If no <after/> element is specified, then the UID defaults to "before the first item in the result set" (i.e., effectively an index of negative one).
+The first item in the page returned by the responding entity MUST be the item that immediately follows the item that the requesting entity indicated in the <after/> element:
+It may sometimes be necessary to return an empty page to the requesting entity. For example, with dynamic result sets the responding entity MAY delete some items from the full result set between requests. Another example occurs when the requesting entity specifies "0" for the maximum number items to return (see Getting the Item Count).
+If there are no items whatsoever in the full result set, the responding entity MUST return a response that adheres to the definition of the wrapper protocol (e.g., "jabber:iq:search", "http://jabber.org/protocol/disco#items", or "http://jabber.org/protocol/pubsub"). For both JEP-0055 and JEP-0030, that means the responding entity shall return an empty &QUERY; element; for JEP-0060, that means the responding entity shall return an empty <pubsub/> element; for JEP-0136, that means the responding entity shall return an empty <list/> or <store/> element.
+The requesting entity MAY ask for the previous page in a result set by including in its request the UID of the first item from the page that has already been received (encapsulated in a <before/> element), along with the maximum number of items to return.
+The last item in the page returned by the responding entity MUST be the item that immediately preceeds the item that the requesting entity indicated it has already received:
+The responding entity MUST reply with an 'item-not-found' error if all the following circumstances apply:
+-
+
The item specified by the requesting entity via the UID in the <after/> or <before/> element no longer exists (it was deleted after the previous page was sent).
+ The UID itself cannot be used to derive directly the next item within the set (e.g. the alphabetical or numerical order of the UIDs do not specify the order of the items).
+ The responding entity does not remember the position of the deleted item within the full list. (Even if the responding entity bothers to remember the position of each deleted item, it will typically be necessary to expire that 'state' after an implementation-specific period of time.)
+
The requesting entity MAY ask for the last page in a result set by including in its request an empty <before/> element, and the maximum number of items to return.
+The requesting entity MAY choose not to retrieve pages from the result set in order. (For example, when its user drags a user-interface slider to a radically new position within a very large result set.)
+Only if the UID before the start (or after the end) of a desired result set page is not known, then the requesting entity MAY request the page that starts at a particular index within the result set. It does that by including in its request the index of the first item to be returned (encapsulated in an <index/> element), as well as the maximum number of items to return. Note: For reasons mentioned in Paging Forwards Through a Result Set requesting entities SHOULD, where possible, specify pages using a UID instead of an index.
+Note: If the responding entity omitted the <count/> element from previous responses for this result set, then the requesting entity SHOULD assume that the responding entity does not support page retrieval by index for this result set (see error below).
+The responding entity SHOULD derive the first UID from the specified index (the method used MAY be approximate) before returning the requested result set page in the normal way. If the specified index was "0" then the responding entity SHOULD derive the UID that is the first in the full result set.
+Note: The 'index' attribute of the <first/> element MUST be the same as the index specified in the request. If the index specified by the requesting entity is greater than or equal to the number of items in the full set then the responding entity MUST return an empty page (see Paging Forwards Through a Result Set).
+If it would be either impossible or exceptionally resource intensive for the responding entity to derive the first UID from the specified index with reasonable accuracy then the responding entity MAY return a &e501; error.
+In order to get the item count of a result set without retrieving the items themselves, the requesting entity simply specifies zero for the maximum size of the result set page:
+The responding entity then returns the item count, which MAY be approximate rather than precise if determining the exact number of items would be resource-intensive:
+Note: The <count/> element MAY be omitted, but only if it would be either impossible or exceptionally resource intensive to calculate reasonably accurate values.
+Note: If there are no items in the full result set then the responding entity MUST return a response that adheres to the definition of the wrapper protocol (see Paging Forwards Through a Result Set).
+The foregoing examples show the use of result set management in the context of Jabber Search. In the following examples we show the use of this protocol in the context of Service Discovery. JEP-0136 ("Message Archiving") includes more examples. A future version of this document may also include examples from Publish-Subscribe and other XMPP protocol extensions.
+In order for a requesting entity to determine if a responding entity supports result set management, it SHOULD send a Service Discovery information request to the responding entity:
+An entity SHOULD NOT include the result set management extensions defined in this document in its requests if it does not have positive knowledge that the responding entity supports the protocol defined herein. If the responding entity does not understand result set management, it MUST ignore such extensions.
+Note: Even if a responding entity understands the result set management protocol, its support for result set management in the context of any given using protocol is OPTIONAL (e.g., an implementation could support it in the context of the 'jabber:iq:search' namespace but not in the context of the 'http://jabber.org/protocol/disco#items' namespace). Currently the only way for a requesting entity to determine if a responding entity supports result set management in the context of a given using protocol is to include result set management extensions in its request. If the responding entity does not include result set management extensions in its response, then the requesting entity SHOULD NOT include such extensions in future requests wrapped by the using protocol namespace.
+Security considerations are the responsibility of the using ("wrapper") protocol, such as JEP-0030 for the 'http://jabber.org/protocol/disco#items' namespace, JEP-0055 for the 'jabber:iq:search' namespace, and JEP-0136 for the 'http://jabber.org/protocol/archive' namespace.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'http://jabber.org/protocol/rsm' in its registry of protocol namespaces.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0059: http://www.jabber.org/jeps/jep-0059.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Thanks to Olivier Goffart, Jon Perlow, and Andrew Plotkin for their feedback.
+-
+
- Replaced boolean send_item_subscribe node configuration option with more comprehensive send_last_published_item option per list discussion +
- Added deliver_notifications node configuration option to enable quiet nodes without notifications, if desired enabling pull-model item retrieval only. +
- Modified subscription and affiliation retrieval to return empty element if no results. +
-
+
- Defined five access models: open, presence, roster, authorize, and whitelist +
- Renamed pubsub#subscription_model feature to pubsub#access_model +
- Separated affiliations retrieval from subscriptions retrieval +
- Removed subscription information from affiliations management +
- Changed <entity/> element to <subscription/> element in response to subscription request +
- Clarified batch processing of item publication and item deletion +
- Added basic example to introduction +
- More fully specified node creation flows +
- More fully specified recommended behavior for caching last published item, including use of jabber:x:delay protocol +
- Specified that semantic meaning of NodeIDs must not be used to encapsulate hierarchy +
- More fully specified error conditions +
- Changed some feature-related conditions to <unsupported/> plus feature attribute +
- Changed some error conditions from <not-authorized/> to <forbidden/> +
- Harmonized error conditions for unsubscribe if entity is not subscribed (unexpected-request rather than not-found) +
- Further defined error conditions related to item publication +
- Specified structure of <affiliations/>, <delete/>, <purge/>, and <subscriptions/> elements qualified by pubsub#owner namespace +
- Changed retrieval of default configuration options to use <default/> element, not <configure/> element +
- Allowed caching of last published item +
- Added pubsub#deliver subscription option +
- Added meta-data fields for pubsub#owners and pubsub#contact +
- Changed element for retrieval of default node configuration options from <configure/> to <default/> to prevent ambiguity related to configuration of root collection node +
- Specified pubsub#node_type configuration field +
- Specified pubsub#collection SHIM header +
- Specified conformance with Resourceprep for nodes addressable as JIDs +
- Added pubsub#modify-affiliations feature +
- Added pubsub#digest_frequency field to subscribe_options FORM_TYPE +
- Added pubsub#roster_groups_allowed field to node_config FORM_TYPE +
- More clearly specified the requirements level (MUST, SHOULD, MAY) for each service discovery feature +
- Defined pubsub#include_body subscription option and the pubsub#body_xslt node configuration option to transform payload format into an XMPP message body, and clarified rules for inclusion of message bodies +
- Clarified nature of collections and association of a node to a collection +
- Specified that simultaneous subscriptions of type nodes and items are allowed to collection nodes +
- Added examples and further explanation of time-based and content-based subscriptions +
- Added Internationalization Considerations +
- Clarified terminology +
- Corrected and updated the schemas +
-
+
- Reinstated pubsub#subscribe feature (deleted in error) +
- Added type attribute for the <create/> and <configure/> elements to differentiate between leaf nodes and collection nodes +
- In Section 8.1.7, changed affiliations retrieval support to SHOULD and added pubsub#retrieve-affiliations feature +
- In Section 8.1.10, removed two duplicate examples +
- In Section 8.1.12, clarified relationship between normal disco#info data and node meta-data (which uses a service discovery extension) +
- In Section 8.2.4, specified that node purgation MUST result in one event notification, not a notification per item +
- In Section 8.1.8, further specified handling of SubIDs +
- Clarified nature of the pubsub#type field +
- Mentioned that the forbidden error should be returned in response to certain operations requested by an outcast +
- Corrected datatype of max_items attribute from xs:string to xs:positiveInteger +
- Corrected <requesting-entity-not-subscribed/> error to <not-subscribed/> since the subscribed JID need not be that of the requesting entity +
- Added service discovery features for more optional use cases: retracting items, purging nodes, deleting nodes +
- Updated relevant registries +
Added service discovery features for pubsub#meta-data, and pubsub#retrieve-items. Added pubsub#subscription_depth configuration option. Specified pubsub-specific error condition elements qualified by pubsub#errors namespace.
Fixed typos. Added more details to the section on collections. Added paragraph to create node use case to allow the service to change the requested node-id to something which it creates. Added text about bouncing publish requests when the request does not match the event-type for that node. Added disco features for the jabber registrar. Changed affiliation verbiage to allow publishers to remove any item. Tweaked verbiage for create node, eliminated extra example. Fully defined Jabber Registrar submissions. Corrected schemas.
Added subid syntax in a variety of places. Added more information about disco#info and disco#items support. Added more info about subscription options. Added collection information. Added implementation notes about subscription leases, and content-based pubsub services.
Editorial review; added one implementation note.
Added XMPP error handling.
Added Jabber Registrar Considerations subsection for Service Discovery category/type registration.
Per a vote of the Jabber Council, advanced status to Draft.
Clarified JID addressing usage for nodes. Added specific MAY requirement for disco usage. Added sentence about implementations verifying that an entity has a subscription before getting the current items.
Fixed invalid XML in examples for subscription deny/allow.
Clarified restrictions on addressing nodes by JID. Added section on Approving and Denying Subscription Requests. Changed get-pending to use Ad-Hoc Commands. Changed semantics when sending in a form type='cancel' for pending subscriptions.
Removed item as a possible child of subscribe and unsubscribe and pubsub in the schemas. Removed retract as a possible child of item in the pubsub#event schema. Added verbiage to requirements for addressing nodes either via JIDs or disco nodes.
Defined public vs. private nodes; described how changes to existing nodes might trigger meta-node events (e.g., configuration changes); changed <x/> to <event/> for #events namespace; added meta-data about meta-nodes; fully defined Jabber Registrar considerations.
Removed subscription notifications since they have inherent issues. Removed empty implementation note sub-section.
Fixed error example when returning 501 from an items-get request. Added note about receiving subscription requests when an entity is already subscribed. Fixed some entity elements in various subscription examples. Many were missing the node attribute. Added subscription change notification verbiage and example. Added verbiage and example of subscription state notification being sent to the requesting entity. Added disco#items information for getting a list of item identifiers for a single node. Added verbiage for returning the current entity element when a curent subscriber attempts to subscribe again.
Include JID attributes in the entity elements when receiving your affiliations. Changed error code 406 (which was wrong) to 404, which is correct. Changed many 405 errors to 401, and modified the error table to make it more implementable (rules are more concrete). Added subscribe-options element for indicating subscriptions may be configured.
Clarified the affiliations table and the semantics around subscribing and unsubscribing. Added protocol to get all of your affiliations in the service. Added protocol for services informing subscribers that configurable subscription options are available. Added protocol for obtaining existing node configuration settings and for concatenating configuration and node creation requests into a single stanza. Added meta-node implementation notes and specified the interaction with the Jabber Registrar and the meta NodeIDs. Added authorization notes to subscription options.
Clarified requirements around what affiliations must be supported. Moved requirements about specifying entities which can subscribe and publish out of the MUSTs to MAYs. Changed SHOULD to MAY when talking about allowing entities to create nodes. Added ability to send configuration requests in the same stanza as a creation request.
Added more details and an example about publishing without NodeID. Added more implementation notes about NodeIDs and persistent storage.
Fixed header for delete item example. Added examples showing subscribers being notified of deleted items. Added examples for notification of node deletion, and configuration for node deletion. Added Subscriber option semantics and examples. Added examples for 402 and 407 errors on subscribe and create respectively. Added clarification about ItemID handling to impl notes.
Clarified in-band and out-of-band configuration requirement. Added Delete Item privilege for all affiliations to the table. Added Delete item protocol for publishers and owners. Added 401 error case for subscribing to an illegal jid. Changed subscription request form. Added defaults to configuration form, and clarified role of the Jabber Registrar for the features show. Added text explaining the max_items attribute. Changed "last items" to "most recent items". Removed default configuration acceptance -- owners should just cancel. Added the notify_retract configuration option. Clarified error handling for affiliation modifications.
Added subscription attribute for entities. Removed subscriber from the affiliations table. Clarified configuration details. Clarified JabberID usages. Added Jabber Registrar Considerations. Added link to JEP-0068 about the FORM_TYPE element in subscription request notifications. Fixed some typos in examples. Added unsupported configuration namespace to example. Added a default configuration example.
Added numerous implementation notes; added get-pending action with regard to subscriptions; added error table; changed purge and delete to use IQ type='set'.
Initial version.
As Jabber/XMPP technologies have matured, the need for a generic publish-subscribe ("pubsub") mechanism has arisen in a number of problem spaces. These include (but are not limited to): news feeds and content syndication, extended presence, avatar management, shared bookmarks, auction and trading systems, online catalogs, workflow systems, network management systems, NNTP gateways, profile management, and event notification.
+In all of these domains, it is desirable for data communication to follow the classic "publish-subscribe" or "observer" design pattern: a person or application publishes information, and an event notification or the data itself is broadcasted to all authorized subscribers. In general, the relationship between the publisher and subscriber is mediated by a service that receives publication requests, broadcasts event notifications and/or the data itself to subscribers, and enables privileged entities to manage lists of people or applications that are authorized to publish or subscribe. In most pubsub services, the focal point for publication and subscription is a "topic" or "node" to which publishers send data and from which subscribers receive notifications and/or data. Additionally, some nodes may also maintain a history of events and provide other services that supplement the pure pubsub model.
+This document defines a single, cohesive, generic protocol which all forms of pubsub can utilize. While compliant implementations are not required to implement all of the features defined herein, this document addresses most usages that may be requested of a pubsub service. Other specifications may define subsets of publish-subscribe for use in specialized contexts, but such profiles are out of scope for this document.
+In order to motivate the discussion, we provide a simple, introductory example of a pubsub protocol flow.
+Perhaps the most popular application of pubsub-like functionality is content syndication, which has become familiar from the RSS and Atom (&rfc4287;) feeds associated with weblogs, news sites, and other frequently-updated information available on the Internet. Consider the example of a weblog published by one of the Shakespearean characters typical of Jabber/XMPP protocol documentation. When this character authors a new weblog entry, his blogging software publishes the entry to a pubsub node hosted at a pubsub service:
+Naturally, many other protocol flows may be required in order to enable publication of items to a node (e.g., the publisher first needs to create the node and subscribers need to sign up for notifications). These protocol flows are fully described in the remainder of this document.
+An even simpler example is that of a transient node that sends only notifications, which is the pure pubsub model:
+The following terms are used throughout this document to refer to elements, objects, or actions that occur in the context of a pubsub service. (Note: Some of these terms are specified in greater detail within the body of this document.)
+| Authorize Access Model | A node access model under which an entity can subscribe only through having a subscription request approved by a node owner (subscription requests are accepted but only provisionally) and only subscribers may retrieve items. |
| Address | (1) A JID as defined in &xmppcore;, or (2) the combination of a JID and a &jep0030; node. |
| Collection Node | A type of node that contains nodes and/or other collections but no published items. Collections make it possible to represent hierarchial node structures. |
| Entity | A JID-addressable Jabber entity (client, service, application, etc.). |
| Event | A change in the state of a node. |
| Instant Node | A node whose NodeID is automatically generated by a pubsub service. |
| Item | An XML fragment which is published to a node, thereby generating an event. |
| ItemID | A unique identifier for an item in the context of a specific node. |
| Leaf Node | A type of node that contains published items only. It is NOT a container for other nodes. |
| Node | A virtual location to which information can be published and from which event notifications and/or payloads can be received (in other pubsub systems, this may be labelled a "topic"). |
| NodeID | The unique identifier for a node within the context of a pubsub service. The NodeID is either supplied by the node creator or generated by the pubsub service (if the node creator requests an Instant Node). The NodeID MAY have semantic meaning, but such meaning is OPTIONAL. |
| Notification | A message sent to a subscriber informing them of an event. |
| Outcast | An entity that is disallowed from subscribing or publishing to a node. |
| Owner | The manager of a node, of which there may be more than one; often but not necessarily the node creator. |
| Payload | The full data associated with an event rather than just the event notification itself. |
| Open Access Model | A node access model under which any entity may subscribe and retrieve items without approval. |
| Personal Eventing | A simplified subset of Publish-Subscribe for use in the context of instant messaging and presence applications, whereby each IM user's JID is a virtual pubsub service; for details, see &jep0163;. |
| Presence Access Model | A node access model under which any entity that is subscribed to the owner's presence with a subscription of type "from" or "both" (see &rfc3921;) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems. |
| Publisher | An entity that is allowed to publish items to a node. |
| Pubsub Service | An XMPP server or component that adheres to the protocol defined herein. |
| Roster Access Model | A node access model under which any entity that is subscribed to the owner's presence and in the specified roster group(s) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems. |
| Subscriber | An entity that is subscribed to a node. |
| Whitelist Access Model | A node access model under which an entity can subscribe only through being added by a node owner (subscription requests are rejected) and only subscribers may retrieve items. |
Requirements for a pubsub service can be driven by end-user needs as well as the needs of other components and services which can use the service. First, a pubsub service implemented using Jabber MUST provide the basic features which implement a pure publish-subscribe pattern:
+ +-
+
- An entity MUST be able to publish events to a service such that all subscribers to a node receive notification of the event. +
- An entity MUST be allowed to be affiliated with a node. Allowable affiliations are owner, publisher, none, and outcast. Implementations MUST support affiliations of owner and none, and MAY support affiliations of outcast and publisher. +
- An entity MUST be allowed to query the pubsub service (or a specific node) to determine what optional features of this specification the service (or node) implements. This query MUST use the Service Discovery (disco#info) protocol. +
- An entity MUST be allowed to query a node to determine non-feature-related information about that node (e.g., the service discovery category+type). This query MUST use the Service Discovery (disco#info) protocol. +
Some of the possible uses of a Jabber-based pubsub service will require other features, but these features are OPTIONAL and therefore not mandatory for compliance with this specification. However, if these features are implemented, they MUST adhere to the protocol described herein in to be compliant. These features include:
+-
+
- A service MAY cache the last item published to a node (even if the "persistent-items" option is not set to true); if it does so default "cache-last-item" to true, it SHOULD send the last published item (or notification thereof) to subscribed entities based on configuration of the "send_last_published_item" field. +
- A node owner SHOULD be able to specify who may subscribe to a node. +
- A node owner SHOULD be able to specify who may publish to a node. +
- A node MAY be configured to deliver the published payload inside the event notification. +
- A node MAY be configured to persist published items to some persistent storage mechanism. +
- A node MAY be configured to persist only a limited number of items. +
- A service MAY support collections. +
- A service or node MAY support extended service discovery information (meta-data). +
To manage permissions, the protocol defined herein uses a hierarchy of affiliations, similiar to those introduced in &jep0045;.
+Support for the "owner" and "none" affiliations is REQUIRED. Support for all other affiliations is RECOMMENDED. Particular kinds of pubsub services MAY enforce additional requirements.
+| Affiliation | +Subscribe | +Publish Items | +Purge Items | +Configure Node | +Delete Node | +Delete Item | +
|---|---|---|---|---|---|---|
| Owner | +Yes | +Yes | +Yes | +Yes | +Yes | +Yes | +
| Publisher | +Yes | +Yes | +No | +No | +No | +Yes/No * | +
| None | +Yes | +No | +No | +No | +No | +No | +
| Outcast | +No | +No | +No | +No | +No | +No | +
* Note: A service MAY allow any publisher to delete any item once it has been published to that node instead of allowing only the original publisher to remove it (this is discoverable via the "pubsub#delete-any" feature).
+The ways in which an entity changes its affiliation with a node are well-defined. Typically, an owner action is required to make an affiliation state transition. Affiliation changes and their triggering actions are specified in the following table.
+| --> | +Outcast | +None | +Publisher | +Owner | +
|---|---|---|---|---|
| Outcast | +-- | +Owner removes ban | +Owner adds entity to publisher list | +Owner adds entity to owner list | +
| None | +Owner bans entity | +-- | +Owner adds entity to publisher list | +Owner adds entity to owner list | +
| Publisher | +Owner bans entity | +Owner removes entity from publisher list | +-- | +Owner adds entity to owner list | +
| Owner | +n/a | +Owner resigns | +n/a | +-- | +
Subscriptions to a node may exist in several states.
+| Subscription State | +Description | +
|---|---|
| None | +The node MUST NOT send event notifications or payloads to the Entity. | +
| Pending | +An entity has requested to subscribe to a node and the request has not yet been approved by a node owner. The node MUST NOT send event notifications or payloads to the entity while it is in this state. | +
| Unconfigured | +An entity has subscribed but its subscription options have not yet been configured. The node MAY send event notifications or payloads to the entity while it is in this state. The service MAY timeout unconfigured subscriptions. | +
| Subscribed | +An entity is subscribed to a node. The node MUST send all event notifications (and, if configured, payloads) to the entity while it is in this state. | +
The requirements for the publish-subscribe protocol imply that there are two major dimensions along which we can measure events: persistent vs. transient, and pure notification vs. inclusion of payload. An implementation SHOULD enable an owner to configure a node along both of these dimensions.
+No matter whether a node is configured for persistent or transient events, a service MAY cache the last item published to the node, in which case it SHOULD send that item to subscribers based on configuration of the "send_last_published_item" option (see the Item Caching section of this document).
+A pubsub service MUST validate publish requests against the configuration of the node along both of these dimensions (see the Publish An Item to a Node section of this document for the relevant error conditions).
+Whether an item must be provided by the publisher, and whether an item ID is provided by the publisher or generated by the pubsub service, depends on the type of event being published. We can summarize the relevant rules as follows:
+| --> | Notification | Payload |
|---|---|---|
| Persistent | +Publisher MUST include an &ITEM; element, which MAY be empty or contain a payload; if item ID is not provided by publisher, it MUST be generated by pubsub service | +Publisher MUST include an &ITEM; element that contains the payload; if item ID is not provided by publisher, it MUST be generated by pubsub service | +
| Transient | +Publisher MUST NOT include an &ITEM; element (therefore item ID is neither provided nor generated) but the notification will include an empty &ITEMS; element | +Publisher MUST include an &ITEM; element that contains the payload, but the item ID is OPTIONAL | +
There are two types of nodes:
+| Node Type | +Description | +
|---|---|
| Leaf | +A node that contains published items only. It is NOT a container for other nodes. This is the most common node type. | +
| Collection | +A node that contains nodes and/or other collections but no published items. Collections make it possible to represent hierarchial node structures. | +
In order to make node creation simpler for clients, we define the following node access models (in order of openness):
+| Access Model | +Description | +
|---|---|
| Open | +Any entity may subscribe to the node (i.e., without the necessity for subscription approval) and any entity may retrieve items from the node (i.e., without being subscribed); this SHOULD be the default access model for generic pubsub services. | +
| Presence | +Any entity with a subscription of type "from" or "both" may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems (see RFC 3921). | +
| Roster | +Any entity in the specified roster group(s) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems (see RFC 3921). | +
| Authorize | +The node owner must approve all subscription requests, and only subscribers may retrieve items from the node. | +
| Whitelist | +An entity may be subscribed only through being added to a whitelist by the node owner (unsolicited subscription requests are rejected), and only subscribers may retrieve items from the node. In effect, the default affiliation is outcast. The node owner MUST automatically be on the whitelist. In order to add entities to the whitelist, the node owner SHOULD use the protocol specified in the Manage Affiliated Entities section of this document. | +
A generic publish-subscribe implementation SHOULD support all of the defined access models, although specialized publish-subscribe implementations MAY support only a subset of the access models. Which access models are provided in a particular deployment is a matter of service provisioning (e.g., some restricted deployments may wish to lock down permissions so that only the "authorize" and "whitelist" access models are provided, or even only the "whitelist" access model).
+In order for a node creator or owner to specify the access model (see the Create a Node With Default Configuration and Configure a Node sections of this document), the 'pubsub#access_model' configuration field is used.
+If a pubsub node is addressable, it MUST be addressable either (1) as a JID or (2) as the combination of a JID and a node.
If a pubsub node is addressable as a JID, the NodeID MUST be the resource identifier, and MUST NOT be specified by the "user" portion (node identifier) of the JID (e.g. "domain.tld/NodeID" and "user@domain.tld/NodeID" are allowed; "NodeID@domain.tld" is not allowed). JID addressing SHOULD be used when interacting with a pubsub node using a protocol that does not support the node attribute. For example, when a service makes it possible for entities to subscribe to nodes via presence, it would address nodes as JIDs. If a pubsub node is addressable as a JID, the pubsub service MUST ensure that the NodeID conforms to the Resourceprep profile of Stringprep as described in RFC 3920.
+Consider the following example, in which the pubsub service is located at the hostname pubsub.shakespeare.lit.
+Now consider the following example, in which the pubsub service is located at pubsub@shakespeare.lit.
+If a pubsub node is addressable as a JID plus node, the NodeID MUST be the value of both the Service Discovery 'node' attribute and the pubsub 'node' attribute; i.e., for discovery purposes, a pubsub node is equivalent to a Service Discovery node. If a pubsub node is addressable as a JID plus node, the pubsub service SHOULD ensure that the NodeID conforms to the Resourceprep profile of Stringprep as described in RFC 3920.
+Consider the following example, in which the (virtual) pubsub service is located at hamlet@denmark.lit.
+This section defines the use cases for and protocols to be used by any entity that wishes to interact with a publish-subscribe service, mainly focused on Service Discovery use cases.
+ +A service MUST respond to service discovery information requests qualified by the 'http://jabber.org/protocol/disco#info' namespace. The "disco#info" result returned by a pubsub service MUST indicate the identity of the service and indicate which pubsub features are supported.
+The possible pubsub features are noted throughout this document and have been registered as described in the Jabber Registrar Considerations section of this document. For information regarding which features are required, recommended, and optional, see the Feature Summary section of this document.
+If a service implements a hierarchy of nodes (by means of Collection Nodes), it MUST also enable entities to discover the nodes in that hierarchy by means of the Service Discovery protocol, subject to the recommendations in JEP-0030 regarding large result sets (for which &jep0055; or some other protocol SHOULD be used). The following examples show the use of service discovery in discovering the nodes available at a hierarchical pubsub service.
+Note: Node hierarchies and collection nodes are OPTIONAL. For details, refer to the NodeID Semantics and Collection Nodes sections of this document.
+In the first example, an entity sends a service discovery items ("disco#items") request to the root node (i.e., the service itself), which is a Collection Node:
+In the second example, an entity sends a disco#items request to one of the first-level nodes, which is also a collection node:
+If a node is a leaf node rather than a collection node and items have been published to the node, the service MAY return one &ITEM; element for each published item as described in the Discover Items for a Node section of this document, however such items MUST NOT include a 'node' attribute (since they are published items, not nodes).
+A pubsub service MUST allow entities to query individual nodes for the information associated with that node. The Service Discovery protocol MUST be used to discover this information. The "disco#info" result MUST include an identity with a category of "pubsub" and a type of either "leaf" or "collection".
+Note: If a node has an identity type of "leaf", then it MUST NOT contain other nodes or collections (only items); if a node has an identity type of "collection", then it MUST NOT contain items (only other nodes or collections).
+The "disco#info" result MAY include detailed meta-data about the node, encapsulated in the &jep0004; format as described in &jep0128;, where the data form context is specified by including a FORM_TYPE of "http://jabber.org/protocol/pubsub#meta-data" in accordance with &jep0068;. If meta-data is provided, it SHOULD include values for all configured options as well as "automatic" information such as the node creation date, a list of publishers, and the like.
+Note: Node meta-data can be set in many ways. Some of it is based on node configuration (e.g., the owner's JID) whereas some of it may be dynamic (e.g., the number of subscribers). Any static information to be provided in the node meta-data SHOULD be provided as fields in the node configuration form.
+Much of the meta-data provided about a node maps directly to selected &DUBLINCORE; meta-data attributes; specifically:
+| Pubsub Field | Dublin Core Meta-Data Attribute |
|---|---|
| pubsub#creation_date | Date |
| pubsub#creator | Creator |
| pubsub#description | Description |
| pubsub#language | Language |
| pubsub#publisher | Publisher |
| pubsub#title | Title |
| pubsub#type | Type |
To discover the published items which exist on the service for a specific node, an entity MAY send a "disco#items" request to the node itself, and the service MAY return each item as a Service Discovery &ITEM; element. The 'name' attribute of each Service Discovery item MUST contain its ItemID and the item MUST NOT possess a 'node' attribute. This ItemID MAY then be used to retrieve the item using the protocol defined in the Retrieve Items from a Node section of this document.
+A service SHOULD allow an entity to query the service to retrieve its subscriptions for all nodes at the service. In order to make the request, the requesting entity MUST send an IQ-get whose &PUBSUB; child contains an empty <subscriptions/> element with no attributes.
+If the service returns a list of subscriptions, it MUST return all subscriptions for all JIDs that match the bare JID (&BAREJID;) portion of the 'from' attribute on the request.
+For each subscription, a <subscription/> element is returned specifying the NodeID, the JID that is affiliated (which MAY include a resource, depending on how the entity subscribed), and the current subscription state. If subscription identifiers are supported by the service, the 'subid' attribute MUST be present as well.
+If the requesting entity has no subscriptions, the pubsub service MUST return an empty <subscriptions/> element.
+If the service does not support subscriptions retrieval, the service MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-subscriptions".
+A service SHOULD allow an entity to query the service to retrieve its affiliations for all nodes at the service. In order to make the request, the requesting entity includes an empty <affiliations/> element with no attributes.
+If the service returns a list of affiliations, it MUST return all affiliations for all JIDs that match the bare JID (&BAREJID;) portion of the 'from' attribute on the request.
+For each affiliation, an <affiliation/> element is returned containing the NodeID and the affiliation state (owner, publisher, or outcast).
+If the requesting entity has no affiliations, the pubsub service MUST return an empty <affiliations/> element.
+If the service does not support affiliations retrieval, the service MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-affiliations".
+This section defines the use cases for and protocols to be used by potential and actual subscribers. (Note: The Implementation Notes section of this document describes many important factors and business rules which a pubsub service MUST observe. In addition, the examples throughout assume the existence of a separate pubsub component and include any relevant 'from' addresses as stamped by a server or network edge.)
+ +When a Jabber entity wishes to subscribe to a node, it sends a subscription request to the pubsub service. The subscription request is an IQ-set where the <pubsub/> element contains one and only one <subscribe/> element. The <subscribe/> element MUST possess a 'node' attribute specifying the node to which the entity wishes to subscribe. The <subscribe/> element MUST also possess a 'jid' attribute specifying the exact XMPP address to be used as the subscribed JID -- often a bare JID (&BAREJID;) or full JID (&FULLJID;), although JIDs of the form &DOMAIN; or &DOMAINRES; may subscribe as well.
+If the specified JID is a bare JID or full JID, the service MUST at a minimum check the bare JID portion against the bare JID portion of the 'from' attribute on the received IQ request to make sure that the requesting entity has the same identity as the JID which is being requested to be added to the subscriber list. However, some implementations MAY enable the service administrator to configure a list of entities that are excluded from this check; those entities may be considered "trusted proxies" that are allowed to subscribe on behalf of other entities. In the same way, implementations MAY enable blacklisting of entities that are not allowed to perform specific operations (such as subscribing or creating nodes).
+A service MAY allow entities to subscribe multiple times to the same node. This enables an entity to subscribe using different subscription options. If multiple subscriptions for the same JID are allowed, the service MUST use the 'subid' attribute to differentiate between subscriptions for the same entity (therefore the SubID MUST be unique for each node+JID combination and the SubID MUST be present on the entity element any time it is sent to the subscriber). It is NOT RECOMMENDED for clients to generate SubIDs, since collisions might result; therefore a service SHOULD generate the SubID on behalf of the subscriber and MAY overwrite SubIDs if they are provided by subscribers. If the service does not allow multiple subscriptions for the same entity and it receives an additional subscription request, the service MUST return the current subscription state (as if the subscription was just approved).
+Here is an example of a subscription request.
+If the subscription request is successfully processed, the server MUST inform the requesting entity that it is now subscribed (which MAY include a service-generated SubID).
+The service MAY also send the last published item to the new subscriber. The message containing this item SHOULD be stamped with extended information qualified by the 'jabber:x:delay' namespace (see &jep0091;) to indicate it is are sent with delayed delivery. (Note that in this example the message notification is sent to the bare JID since that is the subscribed JID.)
+There are several reasons why the subscription request might fail:
+-
+
- The bare JID portions of the JIDs do not match. +
- The node has an access model of "presence" and the requesting entity is not subscribed to the owner's presence. +
- The node has an access model of "roster" and the requesting entity is not in one of the authorized roster groups. +
- The node has an access model of "whitelist" and the requesting entity is not on the whitelist. +
- The service requires payment for subscriptions to the node. +
- The requesting entity is anonymous and the service does not allow anonymous entities to subscribe. +
- The requesting entity has a pending subscription. +
- The requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast). +
- The node does not support subscriptions. +
- The node does not exist. +
These error cases are described more fully below.
+If the bare JID portions of the JIDs do not match as described above and the requesting entity does not have some kind of admin or proxy privilege as defined by the implementation, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <invalid-jid/>.
+For nodes with an access model of "presence", if the requesting entity is not subscribed to the owner's presence then the pubsub service MUST respond with a ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <presence-subscription-required/>.
+For nodes with an access model of "roster", if the requesting entity is not in one of the authorized roster groups then the pubsub service MUST respond with a ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <not-in-roster-group/>.
+For nodes with a node access model of "whitelist", if the requesting entity is not on the whitelist then the service MUST return a ¬allowed; error, specifying a pubsub-specific error condition of <closed-node/>.
+Commercial deployments may wish to link subscribers to a database of paying customers. If the subscriber needs to provide payment in order to subscribe to the node (e.g., if the subscriber is not in the customer database or the customer's account is not paid up), the service SHOULD return a &payment; error to the subscriber.
+Some XMPP servers may allow authentication using SASL ANONYMOUS; however, because the resulting entity is unstable (the assigned JID may not be owned by the same principal in a persistent manner), a service MAY prevent anonymous entities from subscribing to nodes and SHOULD use service discovery to determine if an entity has an identity of "account/anonymous". If a requesting entity is anonymous but the service does not allow anonymous entities to subscribe, the service SHOULD return a &forbidden; error to the subscriber.
+If the requesting entity has a pending subscription, the service MUST return a ¬authorized; error to the subscriber, specifying a pubsub-specific error condition of <pending-subscription/>.
+If the requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast), the service MUST return a &forbidden; error to the subscriber.
+If the node does not allow entities to subscribe, the service SHOULD return a &feature; error to the subscriber, specifying a pubsub-specific error condition of <unsupported/> and a feature of "subscribe".
+If the node does not exist, the service SHOULD return an ¬found; error to the subscriber.
+For nodes with an access model of "authorize", subscription requests MUST be approved by one of the node owners; therefore the pubsub service sends a message to the node owner(s) requesting authorization (see the Manage Subscription Requests section of this document). Because the subscription request may or may not be approved, the service MUST return a pending notification to the subscriber.
+If the entity must configure its subscription options (see the Configure Subscription Options section of this document) before receiving notifications, the service MUST so inform the entity. It SHOULD do so by returning an IQ-result to the requesting entity with a notation that configuration of subscription options is required.
+Note: The node shall include the <required/> child element only if the subscriber must configure the subscription before receiving any notifications. A service MAY time out subscription requests if configuration is required and a configuration request is not submitted within a reasonable amount of time (which shall be determined by the service or node configuration).
+Alternatively, if the service is unable to create the subscription without simultaneous configuration, the service MAY return a ¬acceptable; error, specifying a pubsub-specific error condition of <configuration-required/>.
+If the <required/> element is not included and no error is returned, the subscription takes effect immediately and the entity may configure the subscription at any time (the service MAY indicate that subscription options are supported by including an empty <subscribe-options/> element in the IQ-result, as shown in the following example).
+To unsubscribe from a node, the subscriber sends an IQ-set whose &PUBSUB; child contains an <unsubscribe/> element that specifies the node and the subscribed JID.
+If the request can be successfully processed, the service MUST return an IQ result.
+There are several reasons why the unsubscribe request might fail:
+-
+
- The requesting entity has multiple subscriptions to the node but does not specify a subscription ID. +
- The request does not specify an existing subscriber. +
- The requesting entity does not have sufficient privileges to unsubscribe the specified JID. +
- The node does not exist. +
- The request specifies a subscription ID that is not valid or current. +
These error cases are described more fully below.
+If the requesting entity has multiple subscriptions to the node but does not specify a subscription ID, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <subid-required/>.
+If the value of the 'jid' attribute does not specify an existing subscriber, the pubsub service MUST return an error stanza, which SHOULD be &unexpected; and which SHOULD also include a pubsub-specific error condition of <not-subscribed/>.
+If the requesting entity is prohibited from unsubscribing the specified JID, the service MUST return a &forbidden; error. The service MUST validate that the entity making the request is authorized to unsubscribe the entity. If the subscriber's JID is of the form &FULLJID;, a service MUST perform this check by comparing the &BAREJID; part of the two JIDs to ensure that they match. If the bare JID portions of the JIDs do not match and the requesting entity is not authorized to unsubscribe the JID (e.g., because it is not a service-wide admin or authorized proxy), the service MUST return a &forbidden; error.
+If the node does not exist, the pubsub service MUST return an ¬found; error.
+If a subscription identifier is associated with the subscription, the unsubscribe request MUST include an appropriate 'subid' attribute. If the unsubscribe request includes a SubID but SubIDs are not supported for the node (or the subscriber did not subscribe using a SubID in the first place), the service SHOULD ignore the SubID and simply unsubscribe the entity. If the subscriber originally subscribed with a SubID but the unsubscribe request includes a SubID that is not valid or current for the subscriber, the service MUST return a ¬acceptable; error, which SHOULD also include a pubsub-specific error condition of <invalid-subid/>.
+Implementations MAY allow subscribers to configure subscription options. Implementations SHOULD use the Data Forms protocol to accomplish this configuration (however, an out-of-band mechanism such as a web interface could be offered as well).
+If a service supports subscription options it MUST advertise that fact in its response to a "disco#info" query by including a feature whose 'var' attribute is "pubsub#subscription-options".
+A subscriber requests the subscription options by including an <options/> element inside an IQ-get stanza.
+If the request can be successfully processed, the service MUST respond with the options.
+Note: The foregoing example shows some (but by no means all) of the possible configuration options that MAY be provided. If an implementation provides these options using the Data Forms protocol, it MUST use the field variables that are registered with the Jabber Registrar in association with the 'http://jabber.org/protocol/pubsub' namespace (a preliminary representation of those field variables is shown above and in the pubsub#subscribe_options FORM_TYPE section of this document, but MUST NOT be construed as canonical since the Jabber Registrar may standardize additional fields at a later date without changes to this document).
+Note: Many of the relevant data form fields are of type "boolean" and MUST be handled accordingly. &BOOLEANNOTE;
+There are several reasons why the options request might fail:
+-
+
- The requesting entity does not have sufficient privileges to modify subscription options for the specified JID. +
- The requesting entity (or specified subscriber) is not subscribed. +
- The request does not specify both the NodeID and the subscriber's JID. +
- The request does not specify a subscription ID but one is required. +
- The request specifies a subscription ID that is not valid or current. +
- Subscription options are not supported. +
- The node does not exist. +
These error cases are described more fully below.
+When requesting subscription options, the subscriber MUST specify the JID that is subscribed to the node and SHOULD specify a node (if no node is specified, the service MUST assume that the requesting entity wishes to request subscription options for its subscription to the root collection node; see the Root Collection Node section of this document for details).
+The service MUST validate that the entity making the request is authorized to set the subscription options for the subscribed entity. If the subscriber's JID is of the form &FULLJID;, a service MUST perform this check by comparing the &BAREJID; part of the two JIDs to ensure that they match. If the bare JID portions of the JIDs do not match and the requesting entity is not authorized to modify subscription options for the JID (e.g., because it is not a service-wide admin or authorized proxy), the service MUST return a &forbidden; error.
+If the requesting entity (or specified subscriber, if different) is not subscribed, the service MUST return an &unexpected; error, which SHOULD also include a pubsub-specific error condition of <not-subscribed/>.
+If the subscriber does not specify a JID, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <jid-required/>.
+If a subscription identifier is associated with the subscription, the 'subid' attribute MUST be present on the request in order for the service to differentiate subscriptions for the same entity. If the 'subid' is required but not provided, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <subid-required/>.
+If a subscription identifier is associated with the subscription but the request includes a SubID that is not valid or current for the subscriber, the service MUST return a ¬acceptable; error, which SHOULD also include a pubsub-specific error condition of <invalid-subid/>.
+If the node or service does not support subscription options, the service MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "subscription-options".
+If the node does not exist, the pubsub service MUST return an ¬found; error.
+After receiving the configuration form, the requesting entity SHOULD submit the form in order to update the entity's subscription options for that node.
+If the service can successfully process the submission, it MUST respond with success.
+If the subscriber attempts to set an invalid group of options, the service MUST respond with a &badrequest; error.
+The other errors already mentioned for getting subscription options also apply to setting subscription options.
+As noted, if a service supports subscription options, an entity MAY subscribe and provide the subscription options in the same stanza.
+Note: The <options/> element MUST follow the <subscribe/> element and MUST NOT possess a 'node' attribute or 'jid' attribute, since the value of the <subscribe/> element's 'node' attribute specifies the desired NodeID and the value of the <subscribe/> element's 'jid' attribute specifies the subscriber's JID; if any of these rules are violated, the service MUST return a &badrequest; error.
+Implementations of pubsub that choose to persist items MAY allow entities to request existing items from a node (e.g., an entity may wish to do this after successfully subscribing in order to receive all the items in the publishing history for the node). The service MUST conform to the node's access model in determining whether to return items to the entity that requests them. Specifically:
+-
+
If the access model is "open", the service SHOULD allow any entity (whether or not it is subscribed) to retrieve items.
+ If the access model is "presence", the service SHOULD allow any entity that is subscribed to the owner's presence to retrieve items.
+ If the access model is "roster", the service SHOULD allow any entity that is subscribed to the owner's presence and contained in the relevant roster group(s) to retrieve items.
+ If the access model is "authorize" or "whitelist", the service MUST allow only subscribed entities to retrieve items.
+
The only exception foreseen to the SHOULD requirements for the foregoing access models is the enforcement of local privacy and security policies as specified more fully in the Security Considerations section of this document. (In addition, a service MUST always allow the node owner to retrieve items from a node and SHOULD always allow a publisher to do so.)
+The subscriber may request all items by specifying only the Node ID without restrictions.
+The service then SHOULD return all items published to the node, although it MAY truncate the result set if a large number of items has been published.
+Even if the service or node does not support persistent items, it MAY return the last published item.
+There are several reasons why the items retrieval request might fail:
+-
+
- The requesting entity has multiple subscriptions to the node but does not specify a subscription ID. +
- The requesting entity is subscribed but specifies an invalid subscription ID. +
- The node does not return items to unsubscribed entities and the requesting entity is not subscribed. +
- The service or node does not support persistent items and does not return the last published item. +
- The service or node does not support item retrieval. +
- The node has an access model of "presence" and the requesting entity is not subscribed to the owner's presence. +
- The node has an access model of "roster" and the requesting entity is not in one of the authorized roster groups. +
- The node has an access model of "whitelist" and the requesting entity is not on the whitelist. +
- The service or node requires payment for item retrieval. +
- The requesting entity is blocked from retrieving items from the node (e.g., because having an affiliation of outcast). +
- The node does not exist. +
These error cases are described more fully below.
+If the requesting entity has multiple subscriptions to the node but does not specify a subscription ID, the service MUST return a &badrequest; error to the subscriber, which SHOULD also include a pubsub-specific error condition of <subid-required/>.
+If the requesting entity is subscribed but specifies an invalid subscription ID, the service MUST return a ¬acceptable; error to the subscriber, which SHOULD also include a pubsub-specific error condition of <invalid-subid/>.
+If the node does not return items to unsubscribed entities and the requesting entity is not subscribed (which includes having a pending subscription), the service MUST return a ¬authorized; error to the subscriber, which SHOULD also include a pubsub-specific error condition of <not-subscribed/>.
+If the service or node does not support persistent items and does not return the last published item, the service MUST return a &feature; error to the subscriber, specifying a pubsub-specific error condition of <unsupported/> and a feature of "persistent-items".
+If the service or node does not support item retrieval (e.g., because the node is a collection node), the service MUST return a &feature; error to the subscriber, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-items".
+For nodes with an access model of "presence", if the requesting entity is not subscribed to the owner's presence then the pubsub service MUST respond with a ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <presence-subscription-required/>.
+For nodes with an access model of "roster", if the requesting entity is not in one of the authorized roster groups then the pubsub service MUST respond with a ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <not-in-roster-group/>.
+For nodes with a node access model of "whitelist", if the requesting entity is not on the whitelist then the service MUST return a ¬allowed; error, specifying a pubsub-specific error condition of <closed-node/>.
+Commercial deployments may wish to link subscribers to a database of paying customers. If the subscriber needs to provide payment in order to retrieve items from the node (e.g., if the subscriber is not in the customer database or the customer's account is not paid up), the service SHOULD return a &payment; error to the subscriber.
+If the requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast), the service MUST return a &forbidden; error to the subscriber.
+If the node does not exist, the service SHOULD return an ¬found; error to the subscriber.
+A service MAY allow entities to request the most recent N items by using the 'max_items' attribute. When max_items is used, implementations SHOULD return the N most recent (as opposed to the N oldest) items. (Note: A future version of this specification may recommend the use of &jep0059; instead of the 'max_items' attribute.)
+The service MAY return event notifications without payloads (e.g., to conserve bandwidth). If so, the client MAY request a specific item (using the ItemID) in order to retrieve the payload. When an entity requests items by ItemID, implementations MUST allow multiple items to be specified in the request.
+If a subscription identifier is associated with a specific subscription, the service MUST require it so that it can generate different sets of items based on the subscription options associated with a specific subscription. Therefore the entity MUST include the 'subid' attribute with the items element when making the request; if it does not, the service MUST return a ¬acceptable; error, specifying a pubsub-specific error condition of <subid-required/>.
+Any entity which is allowed to publish items to a node (i.e., a publisher or an owner) may do so at any time by sending an IQ-set to the service containing a pubsub element with a <publish/> child; the <publish/> element MUST possess a 'node' attribute and depending on the node configuration MAY contain no &ITEM; elements, one &ITEM; element, or (for Batch Processing) more than one &ITEM; element.
+Note: It is not necessary for a publication request to include a payload or even an &ITEM; element in order to trigger a notification. For example, the result of publishing to a transient, notification-only node will be a notification that does not include even an &ITEM; element (as shown in the Motivating Example section of this document). However, for the sake of convenience we refer to the act of publication as "publishing an item" (rather than, say, "triggering a notification") even though a publication request will not always contain an &ITEM; element.
+If the pubsub service can successfully process the request, it MUST inform the publisher of success.
+If the pubsub service can successfully process the request, it MUST send then one &MESSAGE; stanza containing a pubsub event notification to each approved subscriber. Each &MESSAGE; stanza generated by a pubsub service SHOULD possess an 'id' attribute with a unique value so that the service can properly track any notification-related errors that may occur (see the Handling Notification-Related Errors section of this document).
+Depending on the node configuration, the event notification either will or will not contain the payload, as shown in the following examples.
+If the node is configured to include payloads, the subscribers will receive payloads with the event notifications.
+If the node is configured to not include payloads, the subscribers will receive event notifications only. (If payloads are not included, subscribers may request the published item via the protocol defined in the Retrieve Items from a Node section of this document.)
+If a single entity is subscribed to a node multiple times, the service SHOULD notate the event notification so that the entity can determine which subscription identifier(s) generated this event. If these notations are included, they MUST use the &jep0131; format and SHOULD be included after the event notification information (i.e., as the last child of the &MESSAGE; stanza).
+There are several reasons why the publish request might fail:
+-
+
- The requesting entity does not have sufficient privileges to publish. +
- The node does not support item publication. +
- The node does not exist. +
- The payload size exceeds a service-defined limit. +
- The item contains more than one payload element or the namespace of the root payload element does not match the configured namespace for the node. +
- The request does not match the node configuration. +
These error cases are described more fully below.
+Note: If a publisher publishes an item with an Item ID and the ItemID matches that of an existing item, the pubsub service MUST NOT fail the publication but instead MUST overwrite the existing item and generate a new event notification (i.e., re-publication is equivalent to modification).
+If the requesting entity does not have sufficient privileges to publish, the service MUST return a &forbidden; error.
+If the node does not support item publication (because it is a Collection Node), the service MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "publish".
+If the requesting entity attempts to publish an item to a node that does not exist, the service MUST return an ¬found; error.
+If the payload size exceeds a service-defined limit, the service MUST return a ¬acceptable; error, which SHOULD also include a pubsub-specific error condition of <payload-too-big/>.
+If the &ITEM; element contains more than one payload element or the namespace of the root payload element does not match the configured namespace for the node, the service MUST bounce the request with a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <invalid-payload/>.
+If the request does not conform to the configured event type for the node, the service MAY bounce the request with a &badrequest; error, which SHOULD also include a pubsub-specific error condition. The following rules apply:
+-
+
- If the event type is persistent (either notification or payload) and the publisher does not specify an ItemID, the service MUST generate the ItemID and MUST NOT bounce the publication request. +
- If the event type is persistent (either notification or payload) and the publisher does not include an item, the service MUST bounce the publication request with a &badrequest; error and a pubsub-specific error condition of <item-required/>. +
- If the event type is payload (either persistent or transient) and the publisher does not include a payload, the service SHOULD bounce the publication request with a &badrequest; error and a pubsub-specific error condition of <payload-required/>. +
- If the event type is notification + transient and the publisher provides an item, the service MUST bounce the publication request with a &badrequest; error and a pubsub-specific error condition of <item-forbidden/>. +
Examples of these errors are shown below.
+Finally, in order to facilitate authorization for item removal as described in the Delete an Item from a Node section of this document, implementations that support persistent items SHOULD store the item (if the node is so configured) and maintain a record of the publisher.
+A service SHOULD allow a publisher to delete an item once it has been published to a node that supports persistent items. To delete an item, the publisher sends a retract request as shown in the following examples. The <retract/> element MUST possess a 'node' attribute, MAY possess a 'notify' attribute, and SHOULD contain one &ITEM; element (but MAY contain more than one &ITEM; element for Batch Processing of item retractions); the &ITEM; element MUST be empty and MUST possess an 'id' attribute.
+There are several reasons why the item retraction request might fail:
+-
+
- The publisher does not have sufficient privileges to delete the requested item. +
- The node or item does not exist. +
- The request does not specify a node. +
- The request does not include an &ITEM; element or the &ITEM; element does not specify an ItemID. +
- The node does not support persistent items. +
- The service does not support the deletion of items. +
These error cases are described more fully below.
+If the requesting entity does not have sufficient privileges to delete the item, the service MUST return a &forbidden; error.
+If the node or item does not exist, the service MUST return an ¬found; error.
+If the request does not specify a node, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <node-required/>.
+If the request does not include an &ITEM; element or the &ITEM; element does not specify an ItemID, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <item-required/>.
+If the node does not support persistent items (e.g., because it is a collection node or a transient node that does not deliver payloads), the service MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "persistent-items".
+If the service does not support item deletion, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "delete-nodes".
+If none of the foregoing errors occurred, then the service MUST delete the item.
+If none of the foregoing errors occurred and the <retract/> element included a 'notify' attribute with a value of "true" or "1" &BOOLEANNOTE;, then the service MUST delete the item and MUST send message notifications to all subscribers as shown below. The syntax is identical to publish notifications except that instead of an &ITEM; element, the notification includes a <retract/> element.
+If a single entity is subscribed to the node multiple times, the service SHOULD notate the notification of item deletion so that the entity can determine which subscription identifier(s) generated this event. As above, if these notations are included, they MUST use the Stanza Headers and Internet Metadata (SHIM) protocol and SHOULD be included after the event notification information (i.e., as the last child of the &MESSAGE; stanza).
+A service SHOULD allow entities to create new nodes. However, a service MAY disallow creation of nodes based on the identity of the requesting entity, or MAY disallow node creation altogether (e.g., reserving that privilege to a service-wide administrator).
+There are two ways to create a node:
+-
+
- Create a node with default configuration for the specified node type. +
- Create and configure a node simultaneously. +
These methods, along with method-specific error conditions, are explained more fully in the following sections.
+In addition to method-specific error conditions, there are several general reasons why the node creation request might fail:
+-
+
- The service does not support node creation. +
- Only entities that are registered with the service are allowed to create nodes but the requesting entity is not registered. +
- The requesting entity does not have sufficient privileges to create nodes. +
- The requested NodeID already exists. +
- The request did not include a NodeID and "instant nodes" are not supported. +
These general error cases are described more fully below.
+If the service does not support node creation, it MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "create-nodes".
+If only entities that are registered with the service may create nodes but the requesting entity has not yet registered, the service MUST respond with a ®istration; error.
+If the requesting entity does not have sufficient privileges to create nodes, the service MUST respond with a &forbidden; error.
+If the requested NodeID already exists, the service MUST respond with a &conflict; error.
+If the node creator does not specify a NodeID but the service does not support instant nodes, the service MUST return a ¬acceptable; error, specifying a pubsub-specific error condition of <nodeid-required/>.
+If the node creator does not specify a NodeID but the service supports instant nodes, the service SHOULD generate a NodeID that is unique within the context of the service on behalf of the node creator.
+If no error occurs, the pubsub service SHOULD create the node, generate a NodeID that is unique within the context of that service, and inform the user of success (including the NodeID in the response).
+Note: When a service successfully creates a node on behalf of the requesting entity, it MUST return an IQ result. If the node creation request did not specify a NodeID and the service supports creation of instant nodes, the service MUST specify the created NodeID in the IQ result. Similarly, if the node creation request specified a NodeID but the service modified the NodeID before creating the node as described in the Collection Nodes section of this document, the service MUST also specify the modified node in the IQ result. In all other cases, the service MUST NOT specify the NodeID in the IQ result (since the node creator can determine which node was created by tracking the 'id' attribute that it specified for the IQ-set).
+As explained above, each node type has its own default configuration. By asking the service to create a node with default configuration, the node creator accepts the default configuration. If the service allows node configuration, the owner may reconfigure the node after creating the node (as described in the Configure a Node section of this document). In addition, a service MAY allow entities to determine the default configuration options for a given node type before creating a node (as described in the Request Default Configurations section of this document).
+In order to create a node with default configuration, the node creator MUST include an empty <configure/> child element in the creation request. The node creator MAY specify values for the 'pubsub#node_type' and 'pubsub#access_model' configuration fields or MAY accept the defaults, which are "leaf" for the 'pubsub#node_type' field and the value represented by the 'pubsub#access_model' field (i.e., "authorize", "open", "presence", "roster", or "whitelist").
+In the following example, the node creator requests a leaf node (the default type) with an open access model (assumed to be the default type for this service).
+In order to request an access model other than the default for the service, the node creator MUST include a Data Form in the node creation request that specifies a non-default value for the 'pubsub#node_type' field.
+If the access model is supported and none of the general or method-specific errors has occurred, the service SHOULD create the node and inform the requesting entity of success.
+If service does not support the specified access model, it MUST return a ¬acceptable; error, specifying a pubsub-specific error condition of <unsupported-access-model/>.
+(For error handling if the service does not support the specified node type, see the Collection Node section of this document.)
+If an implementation allows node configuration (see the Configure a Node section of this document), it SHOULD allow node creation requests to contain the desired node configuration in the node creation request.
+Note: The <configure/> element MUST follow the <create/> element and MUST NOT possess a 'node' attribute, since the value of the <create/> element's 'node' attribute specifies the desired NodeID; if any of these rules are violated, the service MUST return a &badrequest; error.
+If a service supports this "create-and-configure" feature, it MUST advertise that fact by returning a feature of "http://jabber.org/protocol/pubsub#create-and-configure" in response to service discovery information requests. If the create-and-configure option is not supported but the requesting entity sends such a request anyway, the service SHOULD ignore the configuration part of the request and proceed as if it had not been included.
+After creating a new node, the node owner may want to modify the node configuration. The process for doing so is shown below.
+Note: The following example shows some of the possible configuration options that MAY be provided. If an implementation implements these features using the Data Forms protocol, that implementation MUST use the fields that are registered with the Jabber Registrar in association with the 'http://jabber.org/protocol/pubsub' namespace (a preliminary representation of those field variables is shown below and in the pubsub#node_config FORM_TYPE section of this document, but MUST NOT be construed as canonical, since the Jabber Registrar may standardize additional fields at a later date without changes to this document). An implementation MAY choose to specify different labels, values, and even field types, but MUST conform to the defined variable naming scheme.
+There are several reasons why the node configuration request might fail:
+-
+
- The service does not support node configuration. +
- The requesting entity does not have sufficient privileges to configure the node. +
- The request did not specify a node. +
- The node has no configuration options. +
- The specified node does not exist. +
These error cases are described more fully below.
+If the service does not support node configuration, the service MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "config-node".
+If the requesting entity does not have sufficient privileges to configure the node, the service MUST respond with a &forbidden; error.
+If the request did not specify a node, the service SHOULD return a &badrequest; error. It is possible that by not including a NodeID, the requesting entity is asking to configure the root node; however, if the requesting entity is not a service-level admin, it makes sense to return &badrequest; instead of &forbidden;.
+If no configuration options are available (e.g., because node configuration is "locked down"), the service MUST return a ¬allowed; error to the owner.
+If the node does not exist, the service MUST return an ¬found; error.
+After receiving the configuration form, the owner SHOULD submit a completed configuration form.
+Alternatively, the owner MAY cancel the configuration process, in which case the existing configuration MUST be applied.
+If the requested node configuration change cannot be processed (e.g., because the node owner has attempted to change the configuration so that there are no node owners), the service MUST return a ¬acceptable; error to the owner.
+If the "pubsub#notify_config" option is set to true, the service MUST send a notification of configuration change to all subscribers. (A service SHOULD support this option for leaf nodes and MUST support it for Collection Nodes.) If the node configuration is set to event notifications only, the notification MUST consist of an empty <configuration/> element whose 'node' attribute is set to the NodeID of the node; if the node configuration is set to full payloads, the <configuration/> element MUST in addition contain the node configuration as represented via the Data Forms protocol.
+A service MAY allow entities to determine the default node configuration for new nodes created on the service, in order to help entities determine whether they want to perform create-and-configure as previously described. To get the options, the entity MUST send an empty <default/> element to the service with no NodeID; in response, the service SHOULD return the default node options.
+There are several reasons why the default node configuration options request might fail:
+-
+
- The service does not support node configuration. +
- The service does not support retrieval of default node configuration. +
These error cases are described more fully below.
+If the service does not support node configuration, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "config-node".
+If the service does not support retrieval of default node configuration options, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-default".
+The default configuration options may be different for a collection node vs. a leaf node. In order to specifically request the default configuration options for collection nodes, an entity MUST include a Data Form with a 'pubsub#node_type' field whose value is "collection" in the request (since the default value for the 'pubsub#node_type' field is "leaf").
+If the service does not support collection nodes, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "collections".
+If a service supports node creation, it MUST support node deletion. If an implementation persists items, it MUST remove all items from persistent storage before the node itself is deleted.
+In order to delete a node, a node owner MUST send a node deletion request, consisting of a <delete/> element whose 'node' attribute specifies the NodeID of the node to be deleted.
+If no error occurs, the service MUST inform the owner of success.
+In addition, the service MUST also send notification of node deletion to all subscribers (which SHOULD include pending and unconfigured subscriptions).
+There are several reasons why the node deletion request might fail:
+-
+
- The requesting entity does not have sufficient privileges to delete the node. +
- The node is the root collection node, which cannot be deleted. +
- The specified node does not exist. +
These error cases are described more fully below.
+If the requesting entity does not have sufficient privileges to delete the node (e.g., is not an owner), the service MUST return a &forbidden; error.
+If the requesting entity attempts to delete the root collection node, the service MUST return a ¬allowed; error.
+If the requesting entity attempts to delete a node that does not exist, the service MUST return an ¬found; error.
+If the deleted node is a Collection Node, the implementation MAY associate the "orphaned" leaf nodes with the root collection node or associate them with no collection node.
+If a service persists published items, it MAY enable node owners to purge the node of all published items (thus removing all items from the persistent store, with the exception of the last published item, which MAY be cached). In order to purge a node of all items, a node owner MUST send a node purge request, consisting of a <purge/> element whose 'node' attribute specifies the NodeID of the node to be purged.
+If no error occurs, the service MUST purge the node and inform the owner of success.
+If the node or service has been configured to notify subscribers on deletion of items, a purge request MUST NOT result in sending the same notifications as are sent when deleting items (since purging a node with many persisted items could result in a large number of notifications); instead, the node MUST send a single notification to each subscriber, containing an empty <purge/> child element.
+There are several reasons why the node purge request might fail:
+-
+
- The node or service does not support node purging. +
- The requesting entity does not have sufficient privileges to purge the node. +
- The node is not configured to persist items. +
- The specified node does not exist. +
These error cases are described more fully below.
+If the node or service does not support node purging, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "purge-nodes".
+If the requesting entity does not have sufficient privileges to purge the node (e.g., because it is not a node owner), the service MUST return a &forbidden; error.
+If the service or node does not persist items (e.g., because the node is a collection node), it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "persistent-items".
+If the node does not exist, the service MUST return an ¬found; error.
+A service MAY send subscription approval requests to the node owner(s) at any time. An approval request consists of a message stanza containing a Data Form scoped by the "http://jabber.org/protocol/pubsub#subscribe_authorization" FORM_TYPE. The form MUST contain a boolean field that has a 'var' attribute of "pubsub#allow", which is the field that designates whether or not to allow the subscription request. The form SHOULD include fields that specify the node identifier, the subscription id (if applicable), and the JID of the pending subscriber. The message MAY include a &BODY; element that contains natural-language text explaining that the message contains a pending subscription form.
+In order to approve the request, the owner shall submit the form and set the "pubsub#allow" field to a value of "1" or "true"; for tracking purposes the message MUST reflect the 'id' attribute originally provided.
+The service then SHOULD send notification to the approved subscriber (see the Notification of Subscription State Changes section of this document).
+In order to deny the request, the owner shall submit the form and set the "pubsub#allow" field to a value of "0" or "false"; as above, the message MUST reflect the 'id' attribute originally provided.
+The service then SHOULD send notification to the denied subscriber (see the Notification of Subscription State Changes section of this document).
+In order to cancel the form submission, the owner shall reply with the form's 'type' attribute set to "cancel".
+The service MUST check the "pubsub#allow" field to see if the subscription should be allowed or denied. If the owner cancels the Data Form, then the subscription request MUST remain in the pending state.
+A service MAY allow owners to request all the current pending subscription requests for all of their nodes at the service. Implementations MUST use the &jep0050; protocol to provide this functionality. The command name ('node' attribute of the command element) MUST have a value of "http://jabber.org/protocol/pubsub#get-pending".
+If no error occurs, the service SHOULD return a data form for managing subscription requests, which MUST contain a single field with a 'var' attribute value of "node" whose <option/> elements specify the nodes for which the requesting entity has subscription approval privileges (as an optimization, the service MAY specify only the nodes that have subscription requests pending).
+There are several reasons why the pending subscription approval request might fail:
+-
+
- The service does not support the ad-hoc commands protocol. +
- The service supports ad-hoc commands but does not support the "get-pending" feature. +
- The requesting entity does not have sufficient privileges to approve subscription requests. +
- The specified node does not exist. +
These error cases are described more fully below.
+If the service does not support the ad-hoc commands protocol, it MUST respond with a &unavailable; error.
+If the service does not support the "get-pending" feature, it MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "get-pending".
+If the requesting entity does not have sufficient privileges to approve subscription requests, the service MUST respond with a &forbidden; error.
+If the requested node does not exist, the service MUST respond with an ¬found; error.
+Upon receiving the data form for managing subscription requests, the owner then MAY request pending subscription approval requests for a given node.
+If no error occurs, the service shall respond with success.
+The service shall then send one subscription approval message for each pending subscription request, as shown above for a single pending subscription request.
+Note: A service SHOULD conform to its affiliation policies in maintaining the list of pending subscriptions. In particular, if the affiliation of an entity with a pending subscription is modified to owner or publisher, the service SHOULD automatically approve the subscription request and remove the entity's previous request from the pending list. Similarly, if the affiliation of an entity with a pending subscription is modified to outcast, the service SHOULD automatically reject the subscription request and remove the entity's previous request from the pending list.
+If an entity's subscription request is denied, the service SHOULD send a &MESSAGE; to the entity, where the message conforms to the format described in the Notification of Subscription Denial or Cancellation section of this document.
+A service MAY allow a node owner to edit the list of subscriptions associated with a given node and to set subscriptions for new entities (for nodes of type "whitelist", this enables the node owner to add subscribers); if so, it MUST advertise support for the "pubsub#manage-subscriptions" feature.
+In order to request a list of all subscriptions, a node owner MUST send a subscriptions request, consisting of a <subscriptions/> element whose 'node' attribute specifies the NodeID of the relevant node.
+If no error occurs, the service MUST return the list of subscriptions for entities whose subscription state is "subscribed" or "unconfigured" (it MUST NOT return entities whose subscription state is "none" and SHOULD NOT return entities whose subscription state is "pending"). The result MAY specify multiple <subscription/> elements for the same entity (JID), but each element MUST possess a distinct value of the 'subid' attribute (as shown below).
+There are several reasons why the manage subscriptions request might fail:
+-
+
- The service does not support subscription management. +
- The requesting entity does not have sufficient privileges to manage subscriptions. +
- The specified node does not exist. +
These error cases are described more fully below.
+If an implementation does not support subscription management, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "manage-subscriptions".
+If the requesting entity is not a node owner, the service MUST return a &forbidden; error.
+If the node does not exist, the service MUST return an ¬found; error.
+Upon receiving the subscriptions list, the node owner MAY modify subscription states. The owner MUST send only modified subscription states (i.e., a "delta"), not the complete list. (Note: If the 'subscription' attribute is not specified in a modification request, then the value MUST NOT be changed.)
+In order to remove an entity from the subscriptions list, the owner MUST set the value of the 'subscription' attribute to "none" and the service MUST remove that entity from the subscriptions list and not return it in response to future list requests.
+The owner MAY change multiple subscriptions in a single request. If one of the entity elements specified is invalid, the service MUST return an IQ error (which SHOULD be ¬acceptable;) with the invalid entries, where the subscription returned is the original, un-altered subscription.
+If errors occur during a modification request for multiple entities, the pubsub service MUST return any <subscription/> element(s) which caused the error. Returned entities which failed to be modified MUST include the existing 'subscription' attribute. Any entity elements which are not returned in an IQ error case MUST be treated as successful modifications. The owner MAY specify multiple <subscription/> elements for the same entity, but each element MUST possess a distinct value of the 'subid' attribute.
+An implementation SHOULD send notification to an entity whose subscription has changed (see the Notification of Subscription State Changes section of this document).
+A service MAY allow a node owner to edit the affiliations of entities associated with a given node and to set affiliations for new entities; if so, it MUST advertise support for the "pubsub#modify-affiliations" feature.
+In order to request a list of all affiliated entities, a node owner MUST send an affiliations request, consisting of an <affiliations/> element whose 'node' attribute specifies the NodeID of the relevant node.
+If no error occurs, the service MUST return the list of entities whose affiliation is "owner", "publisher", or "outcast" (it MUST NOT return entities whose affiliation is "none").
+There are several reasons why the affiliated entities request might fail:
+-
+
- The service does not support modification of affiliations. +
- The requesting entity does not have sufficient privileges to modify affiliations. +
- The specified node does not exist. +
These error cases are described more fully below.
+If an implementation does not support modification of affiliations, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "modify-affiliations".
+If the requesting entity is not a node owner, the service MUST return a &forbidden; error.
+If the node does not exist, the service MUST return an ¬found; error.
+Upon receiving the affiliations list, the node owner MAY modify affiliations. The owner MUST send only modified affiliations (i.e., a "delta"), not the complete list. (Note: If the 'affiliation' attribute is not specified in a modification request, then the value MUST NOT be changed.)
+In order to remove an entity from the affiliations list, the owner MUST set the value of the 'affiliation' attribute to "none" and the service MUST remove that entity from the affiliations list and not return it in response to future list requests.
+The owner MAY change multiple affiliations in a single request. If one of the entity elements specified is invalid, the service MUST return an IQ error (which SHOULD be ¬acceptable;) with the invalid entries, where the affiliation returned is the original, un-altered affiliation.
+The following example shows an entity attempting to make the owner something other than an affiliation of "owner", an action which MUST NOT be allowed if there is only one owner.
+The state chart at the beginning of this document is a MUST-IMPLEMENT set of rules for checking possible state transitions. Implementations MAY enforce other (more strict) rules. If errors occur during a modification request for multiple entities, the pubsub service MUST return any <affiliation/> element(s) which caused the error. Returned entities which failed to be modified MUST include the existing 'affiliation' attribute. Any entity elements which are not returned in an IQ error case MUST be treated as successful modifications. The owner MUST NOT specify multiple <affiliation/> elements for the same entity; otherwise the service MUST return a &badrequest; error.
+An implementation MAY send a message to an entity whose affiliation has changed, which MAY contain a &BODY; element specifying natural-language text regarding the affiliation change and which SHOULD contain the modified affiliation data.
+A pubsub service MAY support collection nodes as well as leaf nodes. Collections enable nodes to be grouped together in any way, including hierarchies and directed acyclic graphs. Collections MUST contain only leaf nodes and/or other collections. Collections MUST NOT contain published items, since only leaf nodes are allowed to contain items (therefore a collection MUST NOT support the "publish" feature or related features such as "persistent-items"). If collections are supported, a service MUST advertise that fact in its "disco#info" responses by including a feature of "pubsub#collections" and MUST support service discovery of child nodes as described in the Discover Nodes section of this document.
+ +A service that implements collection nodes SHOULD allow entities to subscribe to collection nodes (subject to access models and local security policies).
+In addition to the subscription configuration options already defined, there are two subscription configuration options specific to collection nodes:
+-
+
-
+
pubsub#subscription_type
+This subscription option enables the subscriber to subscribe either to items or to nodes.
+If the subscription type is "items", the subscriber shall be notified whenever any node contained in the collection generates a notification (e.g., when an item is published or deleted), as modified by the value of the "pubsub#subscription_depth" option.
+If the subscription type is "nodes", the subscriber shall be notified whenever a new node is added to the collection, as modified by the value of the "pubsub#subscription_depth" option.
+The default value of this subscription option MUST be "nodes".
+
+ -
+
pubsub#subscription_depth
+This subscription option enables the subscriber to specify whether it wants to receive notifications only from first-level children of the collection (a value of "1") or from all descendents (a value of "all").
+For subscriptions of type "items", this enables the subscriber to be informed only when an item is published to a leaf node that is a direct child of the collection node to which it has subscribed, or to be informed whenever an item is published to any leaf node in the "tree" that begins at the level of the collection to which it has subscribed.
+For subscriptions of type "nodes", this enables the subscriber to be informed only when a new node is added in the specific collection to which it has subscribed, or to be informed whenever a node is added anywhere in the "tree" that begins at the level of the collection to which it has subscribed.
+The default value of this subscription option MUST be "1".
+
+
In order to subscribe to a collection node, an entity MUST send a subscription request to the node; the subscription request MAY include subscription options, but this is not strictly necessary (especially if the entity does not wish to override the default settings for the "pubsub#subscription_type" and "pubsub#subscription_depth" options).
+The subscriber will now receive notification of new first-level nodes created within the "blogs" collection.
+The subscriber will now receive item notifications from nodes at any depth within the "blogs" collection.
+Depending on the nature of the node "tree", a subscription type of "items" and depth of "all" may result in an extremely large number of notifications. Therefore, a service MAY disallow such a combination of subscription options, in which case it MUST return a ¬allowed; error to the requesting entity.
+A service MAY allow an entity to subscribe to a collection node in two ways, once with a subscription of type "nodes" (to receive notification of any new nodes added to the collection or the entire tree) and once with a subscription of type "items" (to receive all items published within the tree). However, a service SHOULD NOT allow an entity to subscribe twice to a collection node (once with a subscription depth of "1" and once with a subscription depth of "all") for the same subscription type, since two such subscriptions are unnecessary (a depth of "all" includes by definition a depth of "1"); in this case the service SHOULD return a &conflict; error to the requesting entity.
+A service that implements collections SHOULD support a root collection. The root collection shall be identified by the lack of a node identifier (i.e., the address of the pubsub service itself, such as "pubsub.shakespeare.lit").
+Subscribing to this node with a subscription of type "nodes" and a depth of "1" enables an entity to be notified whenever a new first-level node is created at the pubsub service. Subscribing to this node with a subscription of type "nodes" and a depth of "all" enables an entity to be notified whenever a new node is created anywhere at the pubsub service.
+In order to send notification of new nodes, the service shall send an event that contains a <collection/> element that in turns contains a <node/> element whose 'id' attribute specifies the NodeID of the new node.
+The notification event MAY also include the node meta-data, formatted using the Data Forms protocol.
+To create a new collection node, the requesting entity MUST include a Data Form containing a 'pubsub#node_type' field whose <value/> is "collection".
+In addition to the errors already defined for leaf node creation, there are several reasons why the collection node creation request might fail:
+-
+
- The service does not support collection nodes. +
- The service does not support creation of collection nodes. +
- The requesting entity does not have sufficient privileges to create collection nodes. +
These error cases are described more fully below.
+If the service does not support collection nodes, it MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "collections".
+If the service supports collection nodes but does not allow new collection nodes to be created, it MUST respond with a ¬allowed; error.
+If the requesting entity has insufficient privileges to create new collections, the service MUST respond with a &forbidden; error.
+A service MAY offer some node configuration options that are specific to collection nodes and not provided in configuration forms related to leaf nodes. The following are RECOMMENDED:
+-
+
- pubsub#children_association_policy -- the policy regarding who may associate child nodes with the collection (values: all, owner, whitelist). +
- pubsub#children_association_whitelist -- the whitelist of entities that may associate child nodes with the collection. +
- pubsub#children_max -- the maximum number of child nodes that may be associated with a collection. +
To create a new node and associate it with an existing collection, the node configuration protocol MUST be used in the node creation request (see the Create and Configure a Node section of this document). In order to specify the associated collection(s), the form MUST include a 'pubsub#collection' field.
+Note: Inclusion of the node configuration form is not necessary if the node is being created as a first-level child of the root collection node, since every such child is automatically affiliated with the root collection node (if any).
+Note: For the protocol used to associate an existing node with a collection, refer to the Associate an Existing Node with a Collection section of this document.
+The service then creates the node and associates it with the collection.
+Note: If the node is a collection node and the requesting entity wishes to request the default configuration, the requesting entity MUST include only the "pubsub#collection" and "pubsub#node_type" fields in the configuration form.
+There are several reasons why the request might fail:
+-
+
- The request specified more than one collection node, but the service allows a node to be associated with only one collection node. +
- The requesting entity does not have sufficient privileges to associate a node with the specified collection node. +
- No additional nodes can be associated with the collection node. +
- The specified collection node is actually a leaf node. +
- The specified collection node does not exist. +
These error cases are described more fully below.
+An implementation MAY allow a node to be associated with more than one collection node and therefore MAY specify a type of "text-multi" for the "pubsub#collection" field. However, in order to reduce the complexity of implementation, it is RECOMMENDED to allow only one parent collection node for each node and therefore it is RECOMMENDED to specify a type of "text-single" for the "pubsub#collection" field. If a service supports associating a node with multiple collections, it MUST advertise support for the "multi-collection" feature (if that feature is not advertised, entities SHOULD assume that the service allows a node to be associated with only one collection). If the request specifies more than one collection node but the service allows a node to be associated with only one collection node, the service MUST return a &badrequest; error.
+If the requesting entity does not have sufficient privileges to associate a node with the specified collection node, the service MUST return a &forbidden; error.
+If no additional nodes can be associated with the collection node because a configurable limit of associated nodes has been reached, the service MUST return a &conflict; error, which SHOULD also include a pubsub-specific error condition of <max-nodes-exceeded/>.
+If the specified collection node is actually a leaf node, the service MUST return an ¬allowed; error.
+If the specified collection node does not exist, the service MUST return an ¬found; error.
+Although a node can be associated with a collection when it is created (as described above), it can also be associated with a collection after it has been created. This can be done in two ways:
+-
+
- By modifying the node's "pubsub#collection" configuration field. +
- By modifying the collection node's "pubsub#children" configuration field. +
These methods are described below.
+In order to modify the (child) node's "pubsub#collection" configuration field, the owner of the node shall submit a request to edit the node's configuration, receive a configuration form from the service, and then submit a modified configuration form:
+In order to modify the (parent) node's "pubsub#children" configuration field, the owner of the node shall submit a request to edit the node's configuration, receive a configuration form from the service, and then submit a modified configuration form:
+A node can be disassociated from a collection after it has been associated (whether at creation time or afterward). This can be done in two ways:
+-
+
- By modifying the node's "pubsub#collection" configuration field. +
- By modifying the collection node's "pubsub#children" configuration field. +
These methods are described below.
+In order to modify the (child) node's "pubsub#collection" configuration field, the owner of the node shall submit a request to edit the node's configuration, receive a configuration form from the service, and then submit a modified configuration form:
+Note: To disassociate the node from all collection nodes, the node owner MUST submit an empty <value/> element within the 'pubsub#collection' field as shown in the foregoing example.
+In order to modify the (parent) node's "pubsub#children" configuration field, the owner of the node shall submit a request to edit the node's configuration, receive a configuration form from the service, and then submit a modified configuration form:
+If a node is disassociated from a collection node and a new association is not formed, the implementation MAY associate the node with the root collection node or associate it with no collection node.
+Note: The combination of associating and disassociating a node with a collection can be used to move a node from one collection to another.
+If an item is published to a node which is also included by a collection, and an entity is subscribed to that collection with a subscription type of "items", then the notifications generated by the service MUST contain additional information. The &ITEMS; element contained in the notification message MUST specify the node identifier of the node that generated the notification (not the collection) and the &ITEM; element MUST contain a SHIM header that specifies the node identifier of the collection.
+This section summarizes the features described herein, specifies the appropriate requirements level for each feature (REQUIRED, RECOMMENDED, or OPTIONAL), and provides cross-references to the section of this document in which each feature is described.
+Note: The feature names are all of the form "http://jabber.org/protocol/pubsub#name", where "name" is the text specified in the first column below.
+| Name | +Description | +Support | +Section | +
|---|---|---|---|
| collections | +Collection nodes are supported. | +RECOMMENDED | +Collection Nodes | +
| config-node | +Configuration of node options is supported. | +RECOMMENDED | +Configure a Node | +
| create-and-configure | +Simultaneous creation and configuration of nodes is supported. | +RECOMMENDED | +Create and Configure a Node | +
| create-nodes | +Creation of nodes is supported. | +RECOMMENDED | +Create a Node | +
| delete-any | +Any publisher may delete an item (not only the originating publisher). | +OPTIONAL | +Delete an Item from a Node | +
| delete-nodes | +Deletion of nodes is supported. | +RECOMMENDED | +Delete a Node | +
| get-pending | +Retrieval of pending subscription approvals is supported. | +OPTIONAL | +Manage Subscription Requests | +
| instant-nodes | +Creation of instant nodes is supported. | +RECOMMENDED | +Create a Node | +
| item-ids | +Publishers may specify item identifiers. | +RECOMMENDED | ++ |
| leased-subscription | +Time-based subscriptions are supported. | +OPTIONAL | +Time-Based Subscriptions (Leases) | +
| manage-subscriptions | +Node owners may manage subscriptions. | +OPTIONAL | +Manage Subscribers | +
| meta-data | +Node meta-data is supported. | +RECOMMENDED | ++ |
| modify-affiliations | +Node owners may modify affiliations. | +OPTIONAL | +Manage Affiliations | +
| multi-collection | +A single leaf node may be associated with multiple collections. | +OPTIONAL | +Create a Node Associated with a Collection and Associate an Existing Node with a Collection | +
| multi-subscribe | +A single entity may subscribe to a node multiple times. | +OPTIONAL | ++ |
| outcast-affiliation | +The outcast affiliation is supported. | +RECOMMENDED | +Affiliations | +
| persistent-items | +Persistent items are supported. | +RECOMMENDED | ++ |
| presence-notifications | +Presence-based delivery of event notifications is supported. | +OPTIONAL | ++ |
| publish | +Publishing items is supported (note: not valid for collection nodes). | +REQUIRED | +Publish an Item to a Node | +
| publisher-affiliation | +The publisher affiliation is supported. | +OPTIONAL | ++ |
| purge-nodes | +Purging of nodes is supported. | +OPTIONAL | +Purge All Node Items | +
| retract-items | +Item retraction is supported. | +OPTIONAL | +Delete an Item from a Node | +
| retrieve-affiliations | +Retrieval of current affiliations is supported. | +RECOMMENDED | +Retrieve Affiliations | +
| retrieve-default | +Retrieval of default node configuration is supported. | +RECOMMENDED | +Request Default Configuration Options | +
| retrieve-items | +Item retrieval is supported. | +RECOMMENDED | +Retrieve Items from a Node | +
| retrieve-subscriptions | +Retrieval of current subscriptions is supported. | +RECOMMENDED | +Retrieve Subscriptions | +
| subscribe | +Subscribing and unsubscribing are supported. | +REQUIRED | +Subscribe to a Node and Unsubscribe from a Node | +
| subscription-options | +Configuration of subscription options is supported. | +OPTIONAL | +Configure Subscription Options | +
| subscription-notifications | +Notification of subscription state changes is supported. | +OPTIONAL | +Notification of Subscription State Changes | +
| Condition | +Description | +
|---|---|
| &conflict; | +The node already exists. | +
| &feature; | +The operation being attempted on a node (or the system) has failed because the service or node does not support the operation; the error SHOULD also specify which feature is unsupported. | +
| &forbidden; | +An entity does not have sufficient privileges to perform the action, is requesting an operation for another Jabber ID (e.g., francisco@denmark.lit attempts to subscribe bernardo@denmark.lit to a node), or the requesting entity has an affiliation of "outcast". | +
| ¬found; | +The node or item specified for some operation does not exist. | +
| ¬allowed; | +An entity has attempted to perform an action which the service implements; however the service-wide admin or the node owner has disabled the action for that service or node. | +
| ¬authorized; | +An entity has attempted to subscribe to or retrieve items from a node but is not authorized to see the account owner's presence, is not in the appropriate roster group, or is not on the whitelist for subscriptions. | +
| &payment; | +Subscriptions and item retrieval are based on some kind payment service. Payments would be done out-of-band using some agreed-upon method (not defined herein). | +
| ®istration; | +Entities are required to register before node creation is allowed. | +
Note: Refer to &jep0086; for more information regarding error syntax.
+When a pubsub service generates notifications, it MUST adhere to the delivery rules implicit in the subscription option configuration for each subscriber. In particular, the 'to' address SHOULD be that of the subscribed JID only. The service SHOULD NOT attempt to guess at the most available resource associated with the subscribed JID (e.g., in the context of instant messaging systems).
+As noted above, a pubsub service SHOULD ensure that the &MESSAGE; stanza for each event notification it generates possesses an 'id' attribute with a unique value. (This notification ID is not to be confused with either the node ID or the item ID.) This ID MUST be unique within the context of the pubsub service in order to ensure proper tracking of any delivery-related errors.
+Exactly how a service shall handle delivery-related errors is a matter of implementation. In general, such handling is effectively similar to the bounce processing performed by other message delivery systems, such as mail transfer agents and mailing list software. The following are some suggested guidelines regarding the handling of XMPP-specific error conditions in relation to pubsub event notifications (see RFC 3920 and JEP-0086 regarding XMPP error condition semantics):
+-
+
- If the XMPP error is of type "cancel" (e.g., ¬found;), or the error condition is &gone;, the pubsub service SHOULD terminate the subscription of the entity to that node and MAY terminate the subscription of that entity to all nodes hosted at the service. +
- If the XMPP error is of type "auth" (e.g., ®istration;) or "wait" (e.g., &timeout;), or the error condition is &badrequest;, &redirect;, or ¬acceptable;, the pubsub service SHOULD increment a bounce counter for that entity and MAY attempt to resend the event notification after some configurable amount of time. The service MAY terminate the subscription of the entity to that node if the bounce counter has reached some configurable limit. +
Implementations of pubsub MAY deliver event notifications only when the subscriber is online. In these cases, the option may be a node configuration option as shown in the examples above. To facilitate this, the pubsub service needs to subscribe to the subscriber's presence and check the subscriber's current presence information before sending any event notifications (as described in RFC 3921). Presence subscriptions MUST be based on the subscribed JID.
+Sending events to users of existing Jabber servers may force event notifications to be routed to offline storage for later delivery (as described in &jep0160;). This may not always be desirable. The possible ways of preventing this behavior include:
+-
+
- Use presence-based subscription options as described above. +
- Use delivery semantics as defined by &jep0079;. +
- Specify a message type of "headline", which in most existing server implementations will prevent offline storage. +
If a service understands the semantics for a particular payload type and an entity's subscription is so configured (via the "pubsub#include_body" option), the service SHOULD include an appropriate XMPP &BODY; child element along with the payloads it sends in event notifications for a given node, where the body's XML character data summarizes or represents the information contained in the payload (this enables clients that do not understand the payload format to present the appropriate information to an end user). For example, the Atom <summary/> element (see RFC 4287) could be mapped to the XMPP &BODY; element. A service MUST NOT provide the "pubsub#include_body" subscription option for a node if it does not have a defined way to transform part or all of the payload format into a sensible message body. A node owner MAY define an XSLT for transforming the payload format into a message body, via the "pubsub#body_xslt" node configuration option.
+If the service does not understand the semantics for a particular payload type, it MAY include a <body/> child whose XML character data informs the subscriber that the message contains an event notification (e.g., text such as "This message contains an event notification" would be appropriate).
+NodeIDs MUST be treated as unique identifiers within the context of a particular pubsub service.
+If item identifiers are used, they MUST be treated as unique within the scope of the node. The combination of the NodeID + ItemID MUST be unique within a given service, and MUST specify a single published item at a single node.
+If a publisher publishes an item and the ItemID matches that of an existing item, the pubsub service MUST overwrite the existing item and generate a new event notification.
+Because it is possible for a node's configuration to change such that ItemIDs are required (e.g., a change from transient to persistent), a service SHOULD use ItemIDs for internal tracking purposes even if it does not include them with the notifications it generates prior to the configuration change.
+A service MAY cache the last item published to a node, even if the node is configured for transient publication (i.e., configured to not persist items). The last published item SHOULD be sent to new subscribers upon successful processing of a subscription request or approval by a node owner.
+Note: If a publisher requests Batch Processing of item publications, the concept of "last published item" is undefined; therefore, if information coherence is needed, a publisher SHOULD publish items in separate requests rather than in batch mode.
+Note: Particular profiles of the generic publish-subscribe protocol MAY define more stringent requirements regarding the "cache-last-item" feature.
+A publisher MAY include multiple &ITEM; elements in a publish request and MAY include multiple &ITEM; elements in a retract request. This results in "batch processing" of publications or retractions. If the service cannot process any one of the items to be published or retracted, the entire batch MUST fail. Also note that batch publication renders the concept of "last published item" problematic; therefore, if information coherence is needed, a publisher SHOULD publish items in separate requests rather than in batch mode.
+A service MUST allow owners and publishers to subscribe to a node, and to retrieve items from a node even if they are not subscribed. A service MAY auto-subscribe owners and publishers if they are not already subscribed, in which case it SHOULD generate a subscription ID if necessary for the subscription and SHOULD send a notification of successful subscription as described in the Notification of Subscription State Changes section of this document.
+How subscription requests are sent to node owners is a matter of implementation. Possibilities include:
+-
+
- Send requests to all owners (these may be placed in offline storage as described in JEP-0160) and first approval wins. +
- The service could subscribe to owner presence, and send only to the owners that are online. +
- All owners vote on the new subscriber. +
- Any owner is allowed to veto the subscriber. +
An implementation MAY use any of these methods, or some other method not defined herein.
+Various actions and events may result in changes to a subscription state:
+-
+
Approval or denial of a subscription request as described in the Manage Subscription Requests use case
+ Cancellation of an existing subscription, for which many "triggers" are possible:
+-
+
- The entity simply unsubscribes from the node +
- The node is of type "presence" and the underlying presence subscription is cancelled +
- The node is of type "roster" and the entity is moved to an unauthorized roster group +
+
When a subscription state change occurs, a service SHOULD send a message to the (new, former, or denied) subscriber informing it of the change, where the message contains an <event/> element with a single <subscription/> child that specifies the node, JID, and subscription state. The notification MAY contain a &BODY; element specifying natural-language text regarding the subscription change. Examples are shown below.
+If the service has knowledge of the (former or denied) subscriber's presence, it SHOULD send the message to all of the subscriber's resources; if not, it MUST send the message to the subscriber's affiliated JID.
+If a service or node supports this feature, it MUST return a feature of "subscription-notifications" in its response to service discovery information requests.
+NodeIDs MAY have semantic meaning in particular profiles, implementations, or deployments of pubsub. However, it is STRONGLY RECOMMENDED that such semantic meaning not be used to encapsulate the hierarchical structure of nodes; instead, node hierarchy SHOULD be encapsulated using collections and their associated child nodes.
+A user may publish information that adheres to a certain profile at multiple pubsub nodes, and a potential subscriber may want to discover all of these pubsub nodes. The user may make a list of pubsub nodes publicly available for querying even when the user is offline by using the Service Discovery mechanism for "publishing" items (see Section 4 of JEP-0030). The potential subscriber may then send a "disco#items" request to the user's bare JID (<user@host>), including the 'node' attribute set to the value of the namespace to which the desired information adheres. The user's server then returns a list of pubsub nodes that meet that criterion (with each pubsub node being a separate Service Discovery item). Here is an example.
+Alternatively, a user may be registered with a server that offers personal eventing services, in which case the user will have one node per namespace as described in JEP-0163.
+When SubIDs are used, Stanza Headers and Internet Metadata (SHIM) headers are to be included in order to differentiate notifications sent regarding a particular subscription. The relevant use cases and scenarios are:
+-
+
- Sending notifications regarding newly-published items as described in the Publish an Item to a Node use case. +
- Sending notifications regarding deleted items as described in the Delete an Item from a Node use case. +
The SHIM headers are generated by the node to which the subscriber has a subscription, which may be either a leaf node or a collection node.
+SHIM headers are not to be included when the content does not differ based on subscription ID, e.g., when a node sends notification of a configuration change to the node itself, notification that the node has been purged, or notification that the node has been deleted.
+An implementation MAY enable the node configuration to specify an association between the event notification and the entity to which the published information pertains, but such a feature is OPTIONAL. Here are some possible examples:
+-
+
- In the context of a geolocation notification service using &jep0080;, the user may generate the geolocation information or the information may be generated by an automated service (e.g., a service offered by a mobile telephony provider), but in either case the information is about the user's geolocation and therefore all replies should go to the user (who is probably the node owner). +
- In the context of a group weblog, different users might publish to the weblog and replies might go to the publisher of an entry rather than to the weblog owner. +
- In the context of an integrated pubsub and multi-user chat system, the node owner might be the room owner but all replies need to be sent to the room rather than to the owner. +
Therefore we define three node configuration options:
+-
+
- pubsub#itemreply -- the per-item policy for replies (the value is "owner" or "publisher"). +
- pubsub#replyto -- the specific user JID(s) to which replies should be sent. +
- pubsub#replyroom -- the multi-user chat room to which replies should be sent. +
A node owner MUST NOT define more than one of these options.
+An example is shown below.
+Alternatively, if a service implements the personal eventing subset of this protocol, the virtual pubsub service is the account owner's bare JID and notifications are sent from that JID; for details, refer to JEP-0163.
+The word "chaining" refers to the practice of subscribing one node to another node. For instance, consider a scenario in which the node <pubsub@example.net/NewsBroadcaster> wants to distribute information received from the node "NewsFeed" at <pubsub.example.com>. While it is theoretically possible for <pubsub@example.net/NewsBroadcaster> to directly subscribe to the NewsFeed node (since the former node is directly addressable as a JID), implementations MUST NOT chain nodes in this fashion. Instead, implementations MUST subscribe from the address of the pubsub service rather than the node (in the example shown here, the subscription would be sent from <pubsub@example.net> rather than <pubsub@example.net/NewsBroadcaster>).
+ +In some systems it may be desirable to provide a subscription "leasing" feature in order to expire old or stale subscriptions. Leases can be implemented using configurable subscription options; specifically, when an entity subscribes, the service would require configuration of subscription options and the configuration form would contain a field of "pubsub#expire". This field MUST contain a dateTime (as specified in &jep0082;).
+The leasing process is shown below.
+The service MAY send a message to the subscriber when the lease is almost over (e.g., 24 hours before the end of the lease term). This SHOULD be done by sending a &MESSAGE; containing an empty pubsub <event/> element and a SHIM header named "pubsub#expire".
+When the subscriber wants to renew the lease, it would get the current subscription options, change the value of the "pubsub#expire" field, and submit the new subscription options back to the service. If the new expire value exceeds the maximum value allowed for subscription leases, the service MUST change the value of the field to be the current date/time plus the maximum allowed lease period.
+A service MAY enable entities to subscribe to nodes and apply a filter to notifications (e.g., keyword matching such as "send me all news entries from Slashdot that match the term 'Jabber'"). Such a content-based service SHOULD allow an entity to subscribe more than once to the same node and, if so, MUST use subscription identifiers (SubIDs) to distinguish between multiple subscriptions. In order to prevent collisions, a service that supports content-based subscriptions using SubIDs SHOULD generate SubIDs on behalf of subscribers rather than allowing subscribers to set their own SubIDs.
Content-based services SHOULD use subscription options to specify the filter(s) to be applied. Because there many possible filtering mechanisms (many of which may be application-specific), this JEP does not define any such method. However, filtering mechanisms may be defined in separate specifications.
+A fictional example of the subscription options configuration process for content-based pubsub is shown below.
+The subscriber will then be notified about events that match the keyword.
+The Data Forms shown in this specification include English-language labels for various fields; implementations that will display such forms to human users SHOULD provide localized label text for fields that are defined for the registered FORM_TYPEs.
+Because the data published to a pubsub node may contain sensitive information (e.g., a user's geolocation), node owners SHOULD exercise care in approving subscription requests. Security considerations regarding particular kinds of information are the responsbility of the using protocol.
+A service MUST NOT allow non-owners or other unauthorized entities to complete any actions defined under the Owner Use Cases section of this document.
+A service MUST adhere to the defined access model in determining whether to send event notifications or payloads to an entity, or allow an entity to retrieve items from a node. A service MAY enforce additional privacy and security policies when determining whether an entity is allowed to subscribe to a node or retrieve items from a node; however, any such policies shall be considered specific to an implementation or deployment and are out of scope for this document.
+This JEP does not require interaction with &IANA;.
+The ®ISTRAR; includes the following namespaces in its registry of protocol namespaces (see &NAMESPACES;):
+-
+
- http://jabber.org/protocol/pubsub +
- http://jabber.org/protocol/pubsub#errors +
- http://jabber.org/protocol/pubsub#event +
- http://jabber.org/protocol/pubsub#owner +
The Jabber Registrar includes a category of "pubsub" in its registry of Service Discovery identities (see &DISCOCATEGORIES;), as well as three specific types within that category:
+| collection | +A pubsub node of the "collection" type. | +
| leaf | +A pubsub node of the "leaf" type. | +
| service | +A pubsub service that supports the functionality defined in JEP-0060. |
+
The registry submission is as follows:
+
+ pubsub
+ Services and nodes that adhere to JEP-0060.
+
+ collection
+ A pubsub node of the "collection" type.
+ JEP-0060
+
+
+ leaf
+ A pubsub node of the "leaf" type.
+ JEP-0060
+
+
+ service
+ A pubsub service that supports the functionality defined in JEP-0060.
+ JEP-0060
+
+
+ ]]>
+ Future submissions to the Jabber Registrar may register additional types.
+The Jabber Registrar maintains a registry of service discovery features (see &DISCOFEATURES;), which includes a number of features that may be returned by pubsub services. The following registry submission has been provided to the Jabber Registrar for that purpose.
+
+ http://jabber.org/protocol/pubsub#collections
+ Collection nodes are supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#config-node
+ Configuration of node options is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#create-and-configure
+ Simultaneous creation and configuration of nodes is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#create-nodes
+ Creation of nodes is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#delete-any
+ Any publisher may delete an item (not only the originating publisher).
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#delete-nodes
+ Deletion of nodes is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#get-pending
+ Retrieval of pending subscription approvals is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#instant-nodes
+ Creation of instant nodes is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#item-ids
+ Publishers may specify item identifiers.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#leased-subscription
+ Time-based subscriptions are supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#meta-data
+ Node meta-data is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#manage-subscription
+ Node owners may manage subscriptions.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#modify-affiliations
+ Node owners may modify affiliations.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#multi-collection
+ A single leaf node may be associated with multiple collections.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#multi-subscribe
+ A single entity may subscribe to a node multiple times.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#outcast-affiliation
+ The outcast affiliation is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#persistent-items
+ Persistent items are supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#presence-notifications
+ Presence-based delivery of event notifications is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#publish
+ Publishing items is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#publisher-affiliation
+ The publisher affiliation is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#purge-nodes
+ Purging of nodes is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#retract-items
+ Item retraction is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#retrieve-affiliations
+ Retrieval of current affiliations is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#retrieve-default
+ Retrieval of default node configuration is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#retrieve-items
+ Item retrieval is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#retrieve-subscriptions
+ Retrieval of current subscriptions is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#subscribe
+ Subscribing and unsubscribing are supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#subscription-options
+ Configuration of subscription options is supported.
+ JEP-0060
+
+
+ http://jabber.org/protocol/pubsub#subscription-notifications
+ Notification of subscription state changes is supported.
+ JEP-0060
+
+ ]]>
+ JEP-0068 defines a process for standardizing the fields used within Data Forms scoped by a particular namespace, and the Jabber Registrar maintains a registry of such FORM_TYPES (see &FORMTYPES;). Within pubsub, there are four uses of such forms:
+-
+
- Authorization of subscriptions using the 'http://jabber.org/protocol/pubsub#subscribe_authorization' namespace. +
- Configuration of subscription options using the 'http://jabber.org/protocol/pubsub#subscribe_options' namespace. +
- Configuration of a node using the 'http://jabber.org/protocol/pubsub#node_config' namespace. +
- Setting of meta-data information using the 'http://jabber.org/protocol/pubsub#meta-data' namespace. +
The registry submissions associated with these namespaces are defined below.
+Note: There is no requirement that configuration fields need to be registered with the Jabber Registrar. However, as specified in Section 3.4 of JEP-0068, names of custom (unregistered) fields MUST begin with the characters "x-" if the form itself is scoped by a registered FORM_TYPE.
+ +
+ http://jabber.org/protocol/pubsub#subscribe_authorization
+ JEP-0060
+ Forms enabling authorization of subscriptions to pubsub nodes
+
+
+ http://jabber.org/protocol/pubsub#subscribe_options
+ JEP-0060
+ Forms enabling configuration of subscription options for pubsub nodes
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+ http://jabber.org/protocol/pubsub#node_config
+ JEP-0060
+ Forms enabling configuration of pubsub nodes
+
+
+
+
+
+
+
+
+ true
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 1
+
+
+
+ http://jabber.org/protocol/pubsub#meta-data
+ JEP-0060
+ Forms enabling setting of meta-data information about pubsub nodes
+
+ The Jabber Registrar includes "pubsub#collection", "pubsub#expire", and "pubsub#subid" in its registry of SHIM headers (see &SHIMHEADERS;). The registry submission is as follows:
+
+ pubsub#collection
+ The collection via which a notification was received from the originating node.
+ JEP-0060
+
+
+ pubsub#expire
+ The DateTime at which a pubsub leased subscription will end or has ended.
+ JEP-0060
+
+
+ pubsub#subid
+ A subscription identifer within the pubsub protocol.
+ JEP-0060
+
+ ]]>
+ Future submissions to the Jabber Registrar may register additional SHIM headers that can be used in relation to the pubsub protocol, and such submission may occur without updating this specification.
+As authorized by &jep0147;, the Jabber Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).
+The "pubsub" querytype is defined herein for interaction with pubsub services, with two keys: (1) "action" (whose defined values are "subscribe" and "unsubscribe") and (2) "node" (to specify a pubsub node).
+The following submission registers the "pubsub" querytype.
+
+ pubsub
+ http://jabber.org/protocol/pubsub
+ enables interaction with a publish-subscribe service
+ JEP-0060
+
+
+ action
+ the pubsub action
+
+
+ subscribe
+ enables subscribing to a pubsub node
+
+
+ unsubscribe
+ enables unsubscribing from a pubsub node
+
+
+
+
+ node
+ the pubsub node
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0060: http://www.jabber.org/jeps/jep-0060.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ This namespace is used for error reporting only, as
+ defined in JEP-0060:
+
+ http://www.jabber.org/jeps/jep-0060.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0060: http://www.jabber.org/jeps/jep-0060.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0060: http://www.jabber.org/jeps/jep-0060.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+ Thanks to Bob Wyman, Gaston Dombiak, and Matt Tucker for their feedback.
+Peter Millard, primary author of this specification from version 0.1 through version 1.7, died on April 26, 2006. The remaining co-authors are indebted to him for his many years of work on publish-subscribe technologies.
+A very simple namespace contaning display hints for the content in a message. Can be used for +person-person collaboration, or by a service managing notes.
+Normal messages are sent, with a sharednote namespace extending them hinting to any supporting client on +how to display the message as a note instead. Any changes to the note within that client should then be sent +back to the sender, either automatically or when the user saves the note (depending on the update element, by +default on a save action by the user).
+ +Any element not specified in the note should use the last known setting or client defaults, so that when a +change is sent, only the changed elements are returned.
+ +Each thread is a different shared note. Auto updates should use an internal client timer and batch large +changes into chunks, when the user is typing every 5-10 seconds or so. When the user has made changes that +haven't been sent and an update comes in on the same thread the client should prompt the user with the +changes offering to replace or save their changes.
+ +Traditionally, the &jabberd; server included an internal server module called "mod_filter", which provided a packet filtering facility for users. That service had the following problems:
+ +-
+
- The service and protocol were undocumented, apart from some documentation reverse-engineered from the source code. +
- The processing requirements that the service required made it unusable for large installations. +
- Bugs in the service often caused the Jabber server to crash. +
The most common use for this service was to provide server-side blacklists. Unforuntately, mod_filter was overpowered even by this relatively simple form of packet filtering (matching the sending JID and dropping the packet if necessary), so this need has been neatly filled by &jep0016;.
+ +However, packet filtering (as opposed to the subset of JID blacklisting) is still of use, for the following tasks:
+ +-
+
- Setting up automatic responses to messages (e.g., "vacation" messages). +
- Redirecting packets to another JID. +
- Modifying the contents of a packet in-transit (e.g., language translation, adding <x/> data). +
- Force incoming messages to be stored offline (e.g., for low-bandwidth clients). +
This document proposes a modular, extensible framework for specifying packet filtering rules. This document does not, however, propose any specific filter conditions or actions - that is left to other proposals.
+ +The framework itself operates in the "http://jabber.org/protocol/filter" namespace.
+ +The following definitions are used throughout this document:
+ +-
+
- ruleset - a set of filtering rules. +
- rule - a set of conditions with an associated action. +
- condition - an expression (or set of expressions) that, when applied to a packet, is either true or false. +
- action - a task that may be performed on a packet. +
A single rule is be expressed in XML like so:
+ +A rule is processed by applying its condition to the packet. If the condition is true, then the action is taken. The "description" attribute is provided so a rule generator can assign a meaningful and user-readable description of a rule.
+ +A ruleset is be expressed in XML like so:
+ +A ruleset is processed by applying each rule to the packet, one at a time. Processing of the ruleset stops after the first matching rule is found and its action taken,
If the <condition/> element contains no condition expression, then the rule matches all packets.
+ +A ruleset does not have to contain any rules:
+ +Conditions may be aggregated using AND or OR modifiers, like so:
+ +The above example is equivalent to "conditionexpr1 AND conditionexpr2 AND (conditionexpr3 OR conditionexpr4)".
+ +No such aggregation exists for actions - only a single action expression may be included within an <action/> element.
+ +A filter module is a document that defines conditions and/or actions that can be use by this framework. Each module should have its own namespace, and should clearly define the effect of each condition and action it defines.
+ +Consider a hypothetical module that defines conditions that match packets based on their header information. It might use the namespace "http://jabber.org/protocol/filter/header" and might define the following conditions:
+ +-
+
- <to/> - true when the CDATA of this element matches the "to" attribute of the packet. +
- <from/> - true when the CDATA of this element matches the "from" attribute of the packet. +
- <type/> - true when the CDATA of this element matches the "type" attribute of the packet. +
Equally, consider a hypothetical module that defines actions for redirecting messages. It might use the namespace "http://jabber.org/protocol/filter/redirect" and might define the following conditions:
+ +-
+
- <redirect/> - redirects the packet to the JID specified in the CDATA of this element. +
- <copy/> - sends a copy of the packet to the JID specified in the CDATA of this element, while giving the original packet to the user. +
These two modules might be combined to produce a ruleset like the following:
+ +Using modules in this way enables this framework to be easily extended to support new types of filtering, as well as enabling site administrators to select the types of functionallity that are best suited to their site.
+ +It will not always be appropriate for a service to provide a Jabber-based interface to its filter settings (e.g., in the case of an XML router, it will almost always be more appropriate to limit the specification of rules and rulesets to the router configuration). However, this will be appropriate sometimes (e.g., a session manager providing per-user packet filtering). In these cases, the following protocol should be used. +
+ +An entity may find out if a service supports filtering, and the modules its supports, by issuing a discovery request to the service:
+ +An entity may set the filter ruleset for an entity (which may be itself) like so:
+ +On success, the service returns:
+ +On error, the server returns the original packet with an appropriate error:
+ +An entity may retrieve the filter ruleset for an entity (which may be itself) like so:
+ +If the requesting entity has permissions to view the ruleset, the server must return the ruleset to the entity:
+ +On error, the server returns the original packet with an appropriate error:
+ +Possible errors are:
+ +| Code | Text | Description | +
|---|---|---|
| 403 | Forbidden | The sender does not have permission to modify the ruleset for this entity. | +
| 404 | Not Found | The entity does not exist. | +
Ruleset processing should be the first thing that a service does when it receives a packet - even before processing privacy rules per JEP-0016.
+ +Rules must be processed in the order they are given, and must be returned to a requesting entity in the same order.
+There are no security features or concerns related to this proposal.
+This JEP requires no interaction with the IANA.
+No namespaces or parameters need to be registered with JANA as a result of this JEP.
+This document defines a module for &jep0062; that provides some basic conditions and actions to perform common packet filtering tasks.
+ +This module operates in the "http://jabber.org/protocol/filter/basic" namespace.
+This module defines the fullowing conditions:
+ +-
+
- <message/> - true if the packet is a <message/> packet. +
- <presence/> - true if the packet is a <presence/> packet. +
- <iq/> - true if the packet is a <iq/> packet. If this element contains CDATA, then it must match the namespace of the first element inside the packet (typically <query/>) in order to be true. +
- <to/> - true when the CDATA of this element matches the "to" attribute of the packet. +
- <from/> - true when the CDATA of this element matches the "from" attribute of the packet. +
- <type/> - true when the CDATA of this element matches the "type" attribute of the packet. +
This module defines the fullowing actions:
+ +-
+
- <drop/> - drops the packet +
- <bounce/> - bounces the packet with the error specified in the "code" attribute of this element. +
- <redirect/> - redirects the packet to the JID specified in the CDATA of this element. +
- <copy/> - sends a copy of the packet to the JID specified in the CDATA of this element, while giving the original packet to the user. +
There are no security features or concerns related to this proposal.
+This JEP requires no interaction with the IANA.
+No namespaces or parameters need to be registered with JANA as a result of this JEP.
+This document defines a module for &jep0062; that provides an XPath matching condition for packet filtering.
+ +This module operates in the "http://jabber.org/protocol/filter/xpath" namespace.
+This module defines the fullowing conditions:
+ +-
+
- <xpath/> - true if the XPath expression contained in the CDATA of this element, when applied to the packet, returns one or more nodes. +
There are no security features or concerns related to this proposal.
+This JEP requires no interaction with the IANA.
+No namespaces or parameters need to be registered with JANA as a result of this JEP.
+XMPP is designed for sending relatively small fragments of XML between network entities (see &xmppcore;) and is not designed for sending binary data. However, sometimes it is desirable to send binary data to another entity that one has discovered on the XMPP network (e.g., to send a file). Therefore it is widely recognized within the Jabber community that it would be valuable to have a generic protocol for streaming binary data between any two entities on the network. The main application for such a bytestreaming technology would be file transfer, for which there are currently a number of incompatible protocols (resulting in a lack of interoperability). However, other applications are possible, which is why it is important to develop a generic protocol rather than one that is specialized for a particular application such as file transfer. This JEP proposes a protocol that meets the following conditions:
+-
+
- Bytestreams are established over standard TCP connections (&rfc0793;) or UDP associations (&rfc0768;), where TCP support is REQUIRED and UDP support is OPTIONAL +
- Sockets may be direct (peer-to-peer) or mediated (established through a bytestreaming service) +
- Where possible, standard wire protocols are used +
Specifically, this JEP proposes that the Jabber community make use of the SOCKS 5 protocol, which is an IETF-approved, IPv6-ready technology for bytestreams. (Note: Because this proposal uses a subset of the SOCKS5 protocol that is specially adapted for Jabber bytestreams, existing SOCKS5 proxies cannot be used to implement this proposal without modifications.)
+The following terms are used throughout this JEP.
+| Term | Description | +
|---|---|
| Initiator | +A Jabber Entity that wishes to establish a bytestream with another Entity | +
| Target | +The Entity with which the Initiator is attempting to establish a bytestream | +
| Proxy | +A Jabber entity which is not NAT/Firewalled and is willing to be a middleman for the bytestream between the Initiator and the Target | +
| StreamHost | +The system that the Target connects to and that is "hosting" the bytestream -- may be either the Initiator or a Proxy | +
| StreamID | +A relatively unique Stream ID for this connection; this is generated by the Initiator for tracking purposes and MUST be less than 128 characters in length | +
There are two scenarios addressed by this protocol:
+-
+
- direct connection (i.e., the StreamHost is the Initiator) +
- mediated connection (i.e., the StreamHost is a Proxy) +
The "happy paths" for these scenarios are described separately below for ease of understanding. A full description of these scenarios is captured in the Formal Use Case. This narrative describes TCP connections only; UDP associations are described in the Optional UDP Support section of this document.
+Direct connection is the simpler case. In this situation, the StreamHost is the Initiator (StreamHost/Initiator), which means that the Initiator knows the network address of the StreamHost and knows when to activate the bytestream. The process for establishing bytestreams in this case is as follows:
+-
+
Initiator sends IQ-set to Target specifying the full JID and network address of StreamHost/Initiator as well as the StreamID (SID) of the proposed bytestream.
+ Target opens a TCP socket to the specified network address.
+ Target requests connection + via SOCKS5, with the DST.ADDR and DST.PORT parameters set to the values defined below.
+ StreamHost/Initiator sends acknowledgement of successful connection to Target via SOCKS5.
+ Target sends IQ-result to Initiator, preserving the 'id' of the initial IQ-set.
+ StreamHost/Initiator activates the bytestream.
+ Initiator and Target may begin using the bytestream.
+
Mediated connection is slightly more complicated. In this situation, the StreamHost is not the Initiator but a Proxy, which means that the Initiator must discover the network address of the StreamHost before sending the initial IQ-set, must negotiate a connection with the StreamHost in the same way that the Target does, and must request that the StreamHost activate the bytestream before it can be used. The process for establishing bytestreams in this case is as follows:
+-
+
Optionally, Initiator discovers the network address of StreamHost in-band.
+ Initiator sends IQ-set to Target specifying the full JID and network address of StreamHost as well as the StreamID (SID) of the proposed bytestream.
+ Target opens a TCP socket to the selected StreamHost.
+ Target establishes connection via SOCKS5, with the DST.ADDR and DST.PORT parameters set to the values defined below.
+ StreamHost sends acknowledgement of successful connection to Target via SOCKS5.
+ Target sends IQ-result to Initiator, preserving the 'id' of the initial IQ-set.
+ Initiator opens a TCP socket at the StreamHost.
+ Initiator establishes connection via SOCKS5, with the DST.ADDR and DST.PORT parameters set to the values defined below.
+ StreamHost sends acknowledgement of successful connection to Initiator via SOCKS5.
+ Initiator sends IQ-set to StreamHost requesting that StreamHost activate the bytestream associated with the StreamID.
+ StreamHost activates the bytestream. (Data is now relayed between the two SOCKS5 connections by the proxy.)
+ StreamHost sends IQ-result to Initiator acknowledging that the bytestream has been activated (or specifying an error).
+ Initiator and Target may begin using the bytestream.
+
Before attempting to initiate a bytestream, the Initiator may want to know if the Target supports the bytestream protocol. It may do so using &jep0030; as follows:
+If the Target supports bytestreams, it MUST answer to that effect in the service discovery result.
+Before attempting to initiate a bytestream, the Initiator needs to find a proxy. It may do so using Service Discovery as follows:
+The server will return all of the known JIDs in its disco list.
+For each item in the disco#items result, the Initiator must query to determine if it is a bytestreams proxy. It may do so using Service Discovery as follows:
+The proxy will return its information. The Initiator SHOULD inspect each identity to see if it contains an identity of category "proxy" and type "bytestreams".
+If the StreamHost is a Proxy, the Initiator must first request the full network address used for bytestreaming (obviously this is not required if the StreamHost is the Initiator). This is done by sending an IQ-get to the proxy in the bytestreams namespace, as follows:
+The <streamhost/> element specifying a network address MUST possess the following attributes:
+-
+
- jid = the JID of the StreamHost for communications over Jabber +
In addition, the <streamhost/> element MUST include:
+EITHER
+-
+
- host = the hostname or IP address of the StreamHost for SOCKS5 communications over TCP +
- port = a port associated with the hostname or IP address for + SOCKS5 communications over TCP +
OR
+-
+
- zeroconf = a zeroconf
Zeroconf is a set of protocols that enable IP networking without the need for configuration. For further information, refer to <http://www.zeroconf.org/>. identifier to which an entity may connect, for which the service identifier and protocol name SHOULD be "_jabber.bytestreams".
+
If the Initiator does not have permissions to initiate bytestreams on the Proxy for whatever reason (e.g., a proxy implementation may enable administrators to ban JIDs or domains from using the Proxy), the Proxy MUST return a &forbidden; error to the Initiator (for information about error syntax, refer to &jep0086;):
+If the Proxy is unable to act as a StreamHost, the Proxy SHOULD return a ¬allowed; error to the Initiator:
+In order to establish a bytestream between the Initiator and the Target, the Initiator must provide network address information for the StreamHost(s) to the Target. This happens in-band via a single IQ-set, which must contain the following information:
+-
+
- The network address of at least one StreamHost to which the Target may attempt to connect +
- The Stream ID for this connection +
- The "mode" to use, normally "tcp" but optionally "udp" (see the Optional UDP Support section of this document) +
The protocol format is shown below.
+If the Target is unwilling to accept the bytestream, it MUST return a ¬acceptable; error to the Initiator.
+If the Target is willing to accept the bytestream, it MUST attempt to open a standard TCP socket on the network address of the StreamHost communicated by the Initiator. If the Initiator provides more than one StreamHost, the Target SHOULD try to connect to them in the order they occur.
+If the Target tries but is unable to connect to any of the StreamHosts and it does not wish to attempt a connection from its side, it MUST return a ¬found; error to the Initiator.
+If the Target is able to open a TCP socket on a StreamHost, it MUST utilize the SOCKS5 protocol specified in &rfc1928; to establish the connection with the StreamHost. In accordance with the SOCKS5 RFC, the Target MAY have to authenticate in order to use the proxy. However, any authentication required is beyond the scope of this JEP.
+Once the Target has successfully authenticated with the Proxy (even anonymously), it SHOULD send a CONNECT request to a host named: SHA1(SID + Initiator JID + Target JID), port 0, where the SHA1 hashing algorithm is specified by &rfc3174;. The JIDs provided MUST be full JIDs (i.e., <user@host/resource>); furthermore, in order to ensure proper results, the appropriate stringprep profiles (as specified in &xmppcore;) MUST be applied to the JIDs before application of the SHA1 hashing algorithm.
+After the Target has authenticated with the StreamHost, it MUST send an IQ-result to the Initiator indicating which StreamHost was used.
+At this point, the Initiator knows which StreamHost was used by + the Target.
+If the StreamHost used is a Proxy, the Initiator MUST authenticate and establish a connection with the StreamHost before requesting that the StreamHost activate bytestream. The Initiator will establish a connection to the SOCKS5 proxy in the same way the Target did, passing the same value for the CONNECT request.
+In order for the bytestream to be used, it MUST first be activated by the StreamHost. If the StreamHost is the Initiator, this is straightforward and does not require any in-band protocol. However, if the StreamHost is a Proxy, the Initiator MUST send an in-band request to the StreamHost. This is done by sending an IQ-set to the Proxy, including an <activate/> element whose XML character data specifies the full JID of the Target.
+Using this information, with the SID and from address on the packet, the Proxy is able to activate the stream by hashing the SID + Initiator JID + Target JID. This provides a reasonable level of trust that the activation request came from the Initiator.
+If the Proxy can fulfill the request, it MUST then respond to the Initiator with an IQ-result.
+The Proxy MUST then send SOCKS5 acknowledgement of the connection to the Target.
+If the Proxy cannot fulfill the request, it MUST return an IQ-error to the Initiator; the following conditions are defined:
+-
+
- ¬found; error if the from address does not match that of the Initiator's full JID +
- ¬allowed; error if only one party (either Initiator or Recipient, but not both) is connected to the Proxy +
- &internalserver; error if the proxy cannot activate the bytestream because of some internal malfunction +
This is a formal representation of the narrative information provided above. The primary actor is the Initiator and the goal is to establish a bytestream between the Initiator and the Target. (Note: "UCE" stands for "Use Case Ends" (success is assumed unless otherwise specified), "P" stands for "Primary Flow", and "A" stands for "Alternate Flow".)
+-
+
- Initiator wishes to establish a bytestream with Target +
- Initiator sends an IQ-set to Target specifying a StreamID and the network addresses of one or more StreamHosts [A1] +
- Target wishes to establish a bytestream with Initiator [A2] +
- Target requests TCP connection with a StreamHost [A3] +
- Target receives TCP acknowledgement from StreamHost [A4] +
- Target provides authentication credentials to StreamHost via SOCKS5 +
- Target receives acknowledgement of authentication with StreamHost via SOCKS5 [A5] +
- Target requests connection with StreamHost via SOCKS5 +
- Target receives acknowledgement of successful connection with StreamHost via SOCKS5 [A7] +
- Target sends IQ-result to Initiator announcing successful connection to StreamHost [A6] +
- Use Case Ends (bytestream is established and ready for use) +
A1. Initiator does not know the full network address of a StreamHost (i.e., Proxy)
+-
+
- Initiator sends IQ-get to Proxy +
- Initiator receives IQ-result from Proxy containing network address [A9][A10] +
- Return to P2 +
A2. Target does not wish to establish a bytestream with Initiator
+-
+
- Initiator receives ¬acceptable; error from Target +
- UCE unsuccessfully +
A3. No more StreamHosts in list (Target is unable to reach any of the provided StreamHosts)
+-
+
- Target returns &remoteserver; error to Initiator +
- UCE unsuccessfully +
A4. Target cannot reach StreamHost
+-
+
- Return to P4 +
A5. Target authentication with StreamHost fails
+-
+
- Return to P4 +
A6. Proxy is unwilling to act as a StreamHost for Initiator
+-
+
- Initiator receives &forbidden; error from Proxy +
- Return to P2 +
A7. Proxy is unable to act as a StreamHost for Initiator
+-
+
- Initiator receives ¬allowed; error from Proxy +
- Return to P2 +
A8. Target connects to a Proxy
+-
+
- Initiator reaches Proxy [A9] +
- Target receives TCP acknowledgement from StreamHost [A9] +
- Initiator authenticates with Proxy via SOCKS5 +
- Initiator receives acknowledgement of authentication with Proxy via SOCKS5 [A10] +
- Initiator requests connection with Proxy via SOCKS5 +
- Initiator receives acknowledgement of successful connection with Proxy via SOCKS5 [A11] +
- Initiator sends IQ-set to Proxy requesting activation of bytestream +
- Initiator receives IQ-result from Proxy acknowledging activation of bytestream [A12] +
- Return to P9 +
A9. Initiator is unable to reach Proxy
+-
+
- UCE unsuccessfully +
A10. Initiator is unable to authenticate with Proxy
+-
+
- UCE unsuccessfully +
A11. Initiator is unable to connect to Proxy
+-
+
- UCE unsuccessfully +
A12. Proxy is unable to activate bytestream
+-
+
- Initiator receives &internalserver; error from Proxy +
- UCE unsuccessfully +
The <query/> element is the container for all in-band communications. This element MUST be in the namespace "http://jabber.org/protocol/bytestreams". This element has a single attribute for the stream session identifier, and contains multiple <streamhost/> elements, a single <streamhost-used/> element, or a single <activate/> element.
+The "sid" specifies the bytestream session identifier. This attribute MUST be present. The value of this attribute is any character data.
+The "mode" specifies the mode to use, either 'tcp' or 'udp'. If this attribute is missing, the default value of "tcp" MUST be assumed.
+The <streamhost/> element conveys the network connection information. At least one instance MUST be present in the initial IQ-set from the Initiator to the Target. If multiple instances of this element are present, each one MUST be a separate host/port combination.
+The <streamhost-used/> element transports the out-of-band token. It MUST be present in the IQ-set from the Target to the Initiator, and there MUST be only one instance.
+The <activate/> element is used to request activation of a unidirectional or bidirectional bytestream. It MUST be present in the IQ-set sent from the Initiator to the StreamHost after the Initiator receives an IQ-result from the Target, and there MUST be only one instance.
+The <streamhost/> element contains the bytestream connection information. This element has attributes for the StreamHost's JID, network host/address, and network port. This element MUST NOT contain any content nodes.
+The "jid" attribute specifies the StreamHost's JID. This attribute MUST be present, and MUST be a valid JID for use with an <iq/>.
+The "host" attribute specifies the host to connect to. This attribute MUST be present. The value MUST be either a resolvable domain name or the "dotted decimal" IP address (e.g. "1.2.3.4").
+The "port" attribute specifies the port to connect to. This attribute MAY be present. The value MUST be a valid port number in decimal form.
+The "zeroconf" attribute specifies the zero-configuration service available for bytestreaming. This attribute SHOULD be present. The value SHOULD be '_jabber.bytestreams'.
+When communicating the available hosts, the Initiator MUST include EITHER the host and port OR the zeroconf information.
+The <streamhost-used/> element indicates the StreamHost connected to. This element has a single attribute for the JID of the StreamHost to which the Target connected. This element MUST NOT contain any content node.
+The "jid" attribute specifies the full JID of the StreamHost. This attribute MUST be present, and MUST be a valid JID for use with an <iq/>.
+The <activate/> element is a flag to trigger a Proxy to complete a connection.
+Support for UDP associations is strictly OPTIONAL. However, implementations that support UDP associations MUST adhere to the profile described in this section.
+If an implementation supports UDP associations, it MUST advertise that separately by returning a feature of 'http://jabber.org/protocol/bytestreams#udp' in response to Service Discovery information requests.
+If the Target supports UDP associations, it MUST answer to that effect in the service discovery result.
+UDP associations are requested by setting the 'mode' attribute to a value of "udp" rather than "tcp".
+There is one main difference between UDP mode and TCP mode: rather than simply establishing a TCP connection, the Target and/or Initiator MUST (1) establish a UDP association and then (2) initialize the UDP channel. In particular:
+-
+
- If direct connection is followed, Target MUST complete UDP association and initialization of the UDP channel before informing Initiator of success via the <streamhost-used/> element. +
- If mediated connection is followed, (1) Target MUST complete UDP association and initialization of the UDP channel before informing Initiator of success via the <streamhost-used/> element, and (2) Initiator MUST complete UDP association and initialization of the UDP channel before asking StreamHost to activate the bytestream. +
The processes for establishing the UDP association and for initializing the UDP channel are described below.
+Once the Target has successfully authenticated with the Proxy (as described under Target Establishes SOCKS5 Connection with StreamHost), it MUST send a UDP ASSOCIATE (rather than CONNECT) request to the host identified by the algorithm defined above.
+The StreamHost then acknowledges this request:
+After connecting to the StreamHost, the Target (direct connection) or both Target and Initiator (mediated connection) MUST initialize the UDP channel. In order to do so, each sending entity MUST send a SOCKS5 UDP packet to the StreamHost on the same port used for the initial TCP connection (in the foregeoing example, a host of 192.168.4.1 and port of 5086), with DST.PORT set to '1' and DATA containing the sending entity's JID (i.e, the JID of either the Target or Initiator).
+Upon successful receipt by the StreamHost, the StreamHost MUST reply with a message notification indicating success:
+The <udpsuccess/> element indicates that the StreamHost has received a UDP initialization packet. This element has a single attribute containing the DST.ADDR that was used in the UDP packet.
+If Target is unable to initialize the UDP channel, it MUST return a &remoteserver; error to Initiator.
+Note: Since UDP is not reliable, the Target SHOULD resend the UDP packet if the reply notification is not received within a short time (a 5-second retry is RECOMMENDED). The StreamHost SHOULD ignore duplicate UDP initialization packets once it has replied with a notification.
+Once the UDP association is established, UDP packets can be exchanged with the StreamHost. When a UDP packet is sent by either party, it MUST contain a 4-byte header (in addition to other possible headers, such as that of SOCKS5), which consists of the source virtual port and then the destination virtual port of the packet, both 16-bit values in network byte order. This allows the peers to multiplex many packets for different purposes over one session. The actual application data should follow this header, and thus the payload size will always be "Application Data Size + 4".
+For all packets sent to the StreamHost, DST.PORT is set to 0, and DATA contains the payload.
+UDP packets sent from the StreamHost do not have any SOCKS5 headers, and so the payload should be delivered as-is.
+The programming interface for a SOCKS5 Bytestreams-aware UDP MUST report an available buffer space for UDP datagrams that is smaller than the actual space provided by the operating system and SOCKS5 layer if applicable. In other words, 4 more octets smaller.
+A StreamHost MUST support TCP connections.
+A StreamHost SHOULD:
+-
+
- Allow bi-directional bytestreaming between the Initiator and Target. +
- Allow only one Target to connect to a bytestream (i.e., disallow multicasting). +
- Track sessions based on a combination of the StreamID and the Initiator's full JID, thus allowing an Initiator to create more than one simultaneous session. +
- Ignore but not drop any bytes sent before the bytestream is activated. +
- Prefer to use zero-configuration IP networking if supported. +
A StreamHost MAY:
+-
+
- Support UDP associations in addition TCP connections. +
- Ignore the DST.ADDR and DST.PORT parameters if desired. +
To facilitate the usage of SOCKS5, command parameters MUST be mapped to the appropriate values. Parameters not specified in the table below SHOULD be used as defined in RFC 1928.
+| Parameter | Value |
|---|---|
| CMD | 1 (CONNECT) |
| ATYP | 1 (IP V4), 3 (DOMAINNAME), or 4 (IP V6) |
| DST.ADDR | SHA1 Hash of: (SID + Initiator JID + Target JID) |
| DST.PORT | 0 |
| Parameter | Value |
|---|---|
| CMD | 3 (UDP ASSOCIATE) |
| ATYP | 1 (IP V4), 3 (DOMAINNAME), or 4 (IP V6) |
| DST.ADDR | SHA1 Hash of: (SID + Initiator JID + Target JID) |
| DST.PORT | 0 |
| Parameter | Value |
|---|---|
| ATYP | 1 (IP V4), 3 (DOMAINNAME), or 4 (IP V6) |
| DST.ADDR | SHA1 Hash of: (SID + Initiator JID + Target JID) |
| DST.PORT | 0 or 1, for payload or initialization packets, respectively. |
This proposal does not include a method for securing or encrypting SOCKS5 bytetreams. If such security is desired, it MUST be negotiated over the bytestream (once established) using standard protocols such as SSL or TLS. Negotiation of such security methods is outside the scope of this JEP.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'http://jabber.org/protocol/bytestreams' in its registry of protocol namespaces.
+The Jabber Registrar shall includes 'http://jabber.org/protocol/bytestreams#udp' in its registry of service discovery features.
+The Jabber Registrar includes the "proxy" category and associated "bytestreams" type in the Service Discovery registry. The registry submission is as follows:
+
+ proxy
+ Proxy servers or services
+
+ bytestreams
+ A proxy for SOCKS5 bytestreams
+ JEP-0065
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0065: http://www.jabber.org/jeps/jep-0065.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Per a vote of the Jabber Council, converted to Standards Track.
Removed example of including URL in presence stanza.
Added non-normative section on integration with stream initiation (JEP-0095); added optional sid attribute to jabber:iq:oob schema.
Clarified that IQ use is for basic file transfer whereas message and presence use is for communication of URIs; added presence example; added references to file transfer JEPs as well as related open issue.
Editorial adjustments and clarifications; added references to relevant RFCs.
Per a vote of the Jabber Council, changed status to Active.
Made several small editorial changes; added XML schemas.
Added information about non-HTTP URIs.
Initial version.
This document defines two XMPP protocol extensions for communicating URIs between Jabber entities, where the data formats are qualified by the 'jabber:iq:oob' and 'jabber:x:oob' namespaces. Although these mechanisms were originally used for out-of-band (OOB) data transfer, they are also used more generally to exchange or communicate URIs.
+The intent of the 'jabber:iq:oob' was to provide a "least common denominator" mechanism for basic file transfers. Although &jep0096; defines a more generic method for communicating file exchange options, the 'jabber:iq:oob' namespace can be included as one option therein since it provides a fallback mechanism when clients do not support file transfer options such as those defined in &jep0065; and &jep0047;.
+To initiate an out-of-band file transfer with an intended recipient using the 'jabber:iq:oob' namespace (whether or not negotiated via JEP-0096), the sending application sends an &IQ; of type 'set' to the recipient containing a &QUERY; child element qualified by the 'jabber:iq:oob' namespace; the &QUERY; MUST in turn contain a <url/> child specifying the URL of the file to be transferred, and MAY contain an optional <desc/> child describing the file. This usage is shown in the following example.
+The expected result is for the recipient to retrieve the file via an HTTP GET request and to then inform the sender of successful receipt of the file. The receiving application MUST NOT send the IQ result until it has retrieved the complete file (e.g., it MUST NOT send the IQ result if it has merely attempted to retrieve the file or the URL provided seems to be valid):
+If the recipient attempts to retrieve the file but is unable to do so, the receiving application MUST return an &IQ; of type 'error' to the sender specifying a Not Found condition:
+If the recipient rejects the request outright, the receiving application MUST return an &IQ; of type 'error' to the sender specifying a Not Acceptable condition:
+The 'jabber:x:oob' namespace is used to communicate a URI to another user or application. This is done by including an &X; child element qualified by the 'jabber:x:oob' namespace in either a &MESSAGE; and &PRESENCE; stanza; the &X; child MUST contain a <url/> child specifying the URL of the resource, and MAY contain an optional <desc/> child describing the resource.
+The value of the <url/> element is not limited to URIs that conform to the http: URI scheme (as specified by &rfc2616;). For example, file transfers could also be effected using ftp: URIs as (specified by &rfc0959;). Going further afield, several existing Jabber clients use the callto: URI scheme to initiate voice conferencing via NetMeeting or GnomeMeeting. Other out-of-band communications could be initiated in a similar way via URI schemes such as sip: (as specified by &rfc3261;). All of these usages are allowed by the existing OOB namespaces, as long as the value of the <url/> element is a valid URI (as specified by &rfc3986;).
+This section is non-normative.
+&jep0095; defines methods for negotiating content streams between any two entities, and JEP-0096 defines a profile of stream initiation for file transfer. Although the use of jabber:iq:oob is not recommended by JEP-0096, it could be offered as one option (e.g., a fallback if SOCKS5 Bytestreams and In-Band Bytestreams are not available). If so, the value of the feature negotiation option MUST be "jabber:iq:oob" and the &QUERY; element within the &IQ; stanza qualified by the 'jabber:iq:oob' namespace MUST possess a 'sid' attribute whose value is the StreamID negotiated by stream initiation.
+A sample protocol flow is shown below.
+As with any mechanism that communicates a URI, care must be taken by the receiving application to ensure that the resource retrieved does not contain harmful or malicious data (e.g., a virus-infected file).
+This document requires no interaction with &IANA;.
+The 'jabber:iq:oob' and 'jabber:x:oob' namespaces are included in the protocol namespaces registry maintained by the ®ISTRAR; (see &NAMESPACES;).
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0066: http://www.jabber.org/jeps/jep-0066.html
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0066: http://www.jabber.org/jeps/jep-0066.html
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+ +Usage of jabber/xmpp for stock data transmission would be a nice-to-have. This jep defines transmission of stock ticker values via XMPP based on publish/subscribe. A component, client or alike may publish stock data in this specified way, after creating a node. However, first of all a node on the pub/sub server must be created, this jep recommends creation of the node in the domain 'stocks/', with specific stock value published in the ticker name domain space, i.e. 'stocks/CATG.DE' or 'stocks/602345'. This jep uses the domain 'stocks/' for example data. +
++So, what this JEP comes down to: it defines the data architecture for stock data and it specifies, that a 'stocks/' node is recommended to exist, which again holds all symbols as subnodes, which again hold either '/realtime', '/bar' or '/news' as subnodes. The 'bar' subnode contains a 'time descriptor' subnode. The sort of the symbols is defined through the service provider, who can i.e. support Y!ahoo finance symbols, (german) WKNs or official stock symbols. +
+In a non pubsub environment stock data SHALL be transmitted in the x-chunk, identified with the namespace 'http://www.jabber.org/jeps/jep-0067.html', embedded into a message chunk. +
+Realtime (or close-to-realtime) full stock value data is distributed to a ticker symbol pub/sub location, in the stocks domain. The share data SHALL contain name, time of last trade, most recent stock value, last trade volume, bid, ask, bid size, ask size of the share. If a value is not available, the value MUST be set to '-1'. Each of the values is transmitted in a corresponding xml element, as seen below. The data is published to a pub/sub position. Realtime share value SHALL be published to a position 'realtime' in the ticker symbol domain. +
+Time framed, suitable for barcharts/candle sticks/line diagram, stock value data is distributed to a pub/sub location, the ticker symbol domain in the stocks domain. The share data SHALL contain name, validity time of this data set, open, hi, low, close for this time frame, traded volume in this time span of a share.
+If a value is not available, the value MUST be set to '-1'.
+Each of the values is transmitted in a corresponding xml element, as seen below. The data is published to a pub/sub position. Time framed, barcharted share data SHALL be published to a position 'bar' in the ticker symbol domain, the subdomain of this position SHALL be the time span information, time span as stated below. It is up to a component, how to to react on subscriptions in various time spans. Implementations are advised to generate data as according to subscribers demands (subscriptions). Values lower than 0:0:0:0:5:0 are not suitable for most implementations. +
++The time span SHALL be represented as a string, composed of the amount of years, months, days, hours, minutes, seconds covered by this barchart data set. Time span values SHALL be separated from each other through ':'. A leading zero MAY be attached to digits lower than ten. +
+0.8+
+Similar to section 2, timeframed data MAY be transmitted in a message element. +
++Another important part in a stock system is distribution of stock/share specific news. +
++Stock news are distributed to the pub/sub gateway, to the 'news' location in the ticker symbol subdomain. The stock news are packed in a 'stocknews' chunk. The stocknews chunk contains time, subject, body and source of these news. +
++Greenthumb (http://greenthumb.jabberstudio.org) supports reception of stock ticker data. +
++The 'StockComponent' (http://www.die-horde.de) is a partial component implementation. +
+Now that &jep0004; has been finalized, several uses of jabber:x:data forms have been put on the standards track, including &jep0045;. These protocols typically need a way to gather data from both humans (using a GUI format) and computer processes (using a pre-defined but flexible format).
+The 'jabber:x:data' namespace provides an adequate mechanism for both of these uses, as long as computer processes can rely on the var="" names on a particular type of form.
+This JEP proposes a specific mechanism for the ®ISTRAR; to standardize these form field variable names. Thus this JEP enables existing clients to process forms as they have to this point, but enables JEP authors to specify a mechanism for non-GUI processors of those forms to determine the semantic meanings of those forms.
+-
+
- Forms must continue to be presentable to humans for data entry. +
- Jabber clients that know how to process generic jabber:x:data messages must be supported; the basic format of jabber:x:data must not change. +
- If a form type is used in the context of a standards-track protocol, it should be standardized and registered; however, there is no requirement that all form types must be registered (e.g., form types used in custom applications). +
- If a form type is standardized and registered, field names used in the context of that form type must either be standardized as well or else be clearly labeled as unregistered. +
- Forms that are not directed to an entity must be able to traverse the entity (e.g., a form sent to a MUC room, intended for the participants of the room, and not the room itself). +
- Forms must continue to be flexible for implementations; unknown future expansion fields must not be limited. +
- The chosen approach must work for forms embedded in messages as well as in IQs. +
Within Jabber, namespaces are used to scope data that conforms to a schema (often data that extends the core protocol in some fashion). In addition, namespaces can also provide context for the field variable names used in jabber:x:data forms and reports. This proposal makes that link explicit by defining a mechanism for linking a namespace name with a form and the field names and types used in that form. Specifically, the namespace name is specified in the form as the value of a hidden variable called "FORM_TYPE".
+The first decision-point is whether a FORM_TYPE needs to be registered with the Jabber Registrar. The following rules apply:
+-
+
- If the FORM_TYPE is used in the context of a form defined in a JEP, it MUST be registered. +
- If the FORM_TYPE is used in the context of a JSF-managed protocol but the form is not defined in a JEP, it MAY be registered. +
- If the FORM_TYPE is used in the context of a custom protocol, it MAY be registered. +
While the value of the FORM_TYPE attribute SHOULD be considered an opaque string from the application perspective, the following rules apply:
+-
+
- For custom protocols, the name SHOULD be an HTTP URI that is managed by the namespace "owner". +
- For all new protocols approved by the JSF, the name MUST be an HTTP URI or IETF-style URN. +
- For "legacy" protocols managed by the JSF, the name SHOULD use the old-style "jabber:*:*" format. +
For FORM_TYPEs that are registered with the Jabber Registrar, the field names MUST conform to one of the following two conditions:
+-
+
- If the field name is defined by the relevant JEP or by registration, the field name MUST be registered with the Jabber Registrar and MAY have any name (except a name that begins with "x-"), subject to approval by the Jabber Registrar. +
- If the field name is unregistered, the field name MUST begin with "x-". +
If the FORM_TYPE is not registered, the field name MAY have any name (presumably managed by the namespace "owner").
+Field values may also be registered; refer to the Jabber Registrar section of this document.
+These are forms that do not have a hidden field of name FORM_TYPE. + Existing processing rules still apply.
+In the following example, the FORM_TYPE is 'http://jabber.org/protocol/pubsub', and all of the fields whose var names start with pubsub_ would be registered with the Jabber Registrar, associated with that namespace.
+ +If the FORM_TYPE field is not hidden, it MUST be ignored as a + context indicator.
+ +When a FORM_TYPE is specified correctly, and an unknown field is found whose name does not start with "x-", a receiver MAY respond with an "Not Acceptable" error.
+The following example shows a user's interaction with a Multi-User Chat room in order to register with the room.
+If the FORM_TYPE field is not type="hidden", it does not have the special meaning defined herein.
+If the form is used in an IQ, the namespace of the <query/> element SHOULD match the base namespace of the FORM_TYPE. (One possible way of solving this problem would have been to reuse the <query/> tag from the IQ form of jabber:x:data within messages, but that would have meant that existing clients would not have been able to participate in these exchanges.)
+If the receiving entity believes that a specified field is invalid for the given FORM_TYPE, the receiver MAY respond to the sender with a "Not Acceptable" error; alternatively, the receiver MAY choose to ignore unknown fields.
+Security-conscious programs that are using this approach should be careful to process only agreed-upon fields, with agreed-upon types, or "x-" fields that are understood by a particular implementation and a user of that implementation.
+This JEP requires no interaction with &IANA; for now. However, if this JEP is submitted to the IETF later, IANA should be used to standardize the field names rather than the Jabber Registrar.
+The Jabber Registrar shall maintain a registry of information about submitted FORM_TYPEs.
+
+ FORM_TYPE namespace or namespace derivative
+ associated JEP or other document
+ natural-language description of form type
+
+ The registrant MAY register more than one FORM_TYPE at a time, each contained in a separate <form_type/> element. The registrant MAY also register more than one field at a time, each contained in a separate <field/> child element. Registrations of new fields within an existing FORM_TYPE MUST include the full XML snippet but SHOULD NOT include the FORM_TYPE description (only the name and the JEP number or other document identifier). Note that for ease of use the format for the <field/> element in the registry submission is the same as that defined in JEP-0004; in addition, the value of the 'type' attribute MUST be one of those defined in that JEP-0004.
+In addition, a registrant MAY also register particular field option values for fields of type 'list-single' and 'list-multi'. The format for such submissions is as follows:
+
+ FORM_TYPE namespace or namespace derivative
+ associated JEP or other document
+ natural-language description of form type
+
+
+
+
+ ]]>
+ The Jabber Software Foundation has an initiative underway to define and implement compliance testing of software that is based on XMPP and JSF-approved protocols. To date, participation in this compliance program has been limited to elected members of the JSF. However, not all matters related to the compliance program need to be limited to JSF members. In particular, it would be valuable to receive community feedback and input regarding test plans, testing software, and the like. In order to broaden participation, we propose that the JSF form a standing Jabber Interest Group devoted to compliance.
+The Compliance JIG shall provide a public forum for discussion and development of systems for testing compliance with the protocols defined and accepted by the JSF. It shall not have ultimate accountability for the JSF compliance program; rather, that accountability shall rest with the members-only Compliance Team. The Compliance JIG shall act in an advisory capacity in relation to the Compliance Team. In essence, the relationship between the Compliance JIG and the Compliance Team is analagous to the relationship between the Standards JIG and the Jabber Council.
+In particular, the Compliance JIG shall work with the Compliance Team to define the processes, standards, test cases, and testing software required by the compliance program. However, the Compliance JIG shall not be privy to actual testing results, which shall be available only to the Compliance Team.
+The Compliance JIG shall be open to the public and shall not be limited to elected members of the Jabber Software Foundation. Compliance JIG discussions shall be conducted on a dedicated mailing list <compliance-jig@jabber.org> as well as in the <foundation@conference.jabber.org> chatroom.
+The Compliance JIG shall be a standing JIG, and shall exist as long as the JSF compliance program is in operation.
+The Compliance JIG shall produce at least the following deliverables:
+-
+
- Documentation of the testing process +
- Compliance test plans +
- Compliance testing software +
- Logo requirements +
HTTP (see &rfc2616;) is a nearly-ubiquitous mechanism for the publication and retrieval of information over the Internet. Sometimes it is appropriate for an HTTP Server to allow access to that information only if the HTTP Client first provides authentication credentials. While there exist several standardized HTTP authentication schemes (see &rfc2617;), it may be useful in some applications to enforce verification of an HTTP request by requiring an XMPP entity (normally an IM user) to confirm that it made the request. This request verification can be combined with native HTTP authentication to provide a stronger association between the request and a particular user, as well as to take advantage of the strong user authentication provided in XMPP (see &rfc3920;).
+This document inherits terminology about the HyperText Transfer Protocol from RFC 2616 and RFC 2617.
+| Term | +Definition | +
|---|---|
| HTTP Client | +A client that implements the HyperText Transfer Protocol (HTTP) | +
| HTTP Server | +A server that implements the HyperText Transfer Protocol (HTTP) | +
| XMPP Client | +A client that implements the Extensible Messaging and Presence Protocol (XMPP) or its antecedents | +
| XMPP Server | +A server that implements the Extensible Messaging and Presence Protocol (XMPP) or its antecedents | +
Note well that an XMPP Client can simultaneously be an HTTP Client (or vice-versa), and that an XMPP Server can simultaneously be an HTTP Server (or vice-versa). However, for the purposes of this discussion, we assume that these entities are logically if not physically separate and distinct.
+The motivations for this document are to:
+-
+
- Use an existing XMPP connection to associate an HTTP request with an XMPP entity. +
- Require confirmation of the request by the XMPP entity before allowing access. +
- Ensure that the HTTP request was generated by the principal controlling the XMPP entity. +
The process flow for this protocol is as follows:
+-
+
- HTTP Client requests object via HTTP. +
- HTTP Server sends Authenticate Response via HTTP. +
- HTTP Client sends Authorization Request via HTTP (E1). +
- HTPP Server processes request and forwards it to XMPP Server. +
- XMPP Server requests confirmation via XMPP (E2). +
- XMPP Client confirms request via XMPP. +
- XMPP Server delivers confirmation to HTTP Server. +
- HTTP Server allows HTTP Client to access object (E3). +
Error cases:
+-
+
- E1: HTTP Client does not understand the presented authentication scheme. +
- E2: HTTP Server does not recognize or understand the request. +
- E3: HTTP Server denies access. +
This process flow is described in more detail in the following sections.
+Let us stipulate that an XMPP user (say, <juliet@capulet.com>) learns of an HTTP URL (e.g., <https://files.shakespeare.lit:9345/missive.html>). The user then attempts to retrieve the URL using her HTTP Client, which opens a TCP connection to the appropriate port of the host and sends an HTTP request as defined in RFC 2616. The request method MAY be any valid HTTP request method, including user-defined methods.
+An example is provided below:
+In order to avoid a round trip, the initial request MAY contain HTTP authorization credentials as described below.
+If the user did not provide authorization credentials in the initial request, the HTTP Server then MUST respond with a (401) Authenticate response as defined in RFC 2616. The response MUST contain an HTTP 401 error and one WWW-Authenticate header for each authentication scheme recognized by the HTTP Server. In order to provide verification via XMPP, at least one of these headers MUST specify a realm of "xmpp" (case-sensitive).
+The HTTP Client responds with an Authorization Request as defined in RFC 2616. The following rules apply:
+-
+
- The request MUST include the Jabber Identifier (JID) of the user making the request. This SHOULD be the full JID (<user@host/resource>) of a client that supports the protocol defined herein, although it MAY be the user's bare JID (<user@host>) instead. +
- The request MUST include a transaction identifier for the request. This identifier MUST be unique within the context of the HTTP Client's interaction with the HTTP Server. If the HTTP request is generated by the XMPP Client (e.g., because the HTTP URL was discovered via &jep0066;) then the transaction identifier SHOULD be generated by the client; if not, the transaction identifier SHOULD be provided by the human user who controls the HTTP Client. +
The Authorization Request process is described in the following subsections.
+The Basic Access Authentication scheme is defined in RFC 2617. This scheme specifies that the authorization information shall consist of a userid and password, separated by a ':' character and then encoded using Base64. When the realm is "xmpp", the profile defined herein further specifies that the userid MUST be a valid JID as described above, that the password entity MUST be a transaction identifier as described above, that any character in the JID or transaction identifier that is outside the range of the US-ASCII coded character set MUST be transformed into a percent-encoded octet as specified in Section 2.1 of &rfc3986; prior to Base64 encoding, and that Base64 encoding MUST adhere to Section 3 of &rfc3548;.
+(Refer to RFC 2617 for specification of the syntax of the Basic Access Authentication scheme; that information is not duplicated here.)
+The Digest Access Authentication scheme is defined in RFC 2617. This scheme specifies that the authorization information shall consist of the MD5 checksum of the username, a cnonce generated by the client, a nonce value provided in the challenge, the HTTP method, and the requested URL. When the realm is "xmpp", the profile defined herein further specifies that prior to creating the MD5 checksum the username MUST be a valid JID as described above, that the cnonce MUST be a transaction identifier as described above, and that any character in the JID or transaction identifier that is outside the range of the US-ASCII coded character set MUST be transformed into a percent-encoded octet as specified in Section 2.1 of RFC 3986.
+(Refer to RFC 2617 for specification of the syntax of the Digest Access Authentication scheme; that information is not duplicated here.)
+The HTTP Server MAY offer any other valid authentication scheme, instead of or in addition to the Basic and Digest schemes mentioned above, as long as the scheme makes it possible to specify a userid (JID) and transaction identifier as described above. However, it is RECOMMENDED to implement both the Basic and Digest authentication schemes.
+Once the HTTP Client has communicated the JID and transaction identifier to the HTTP Server, the HTTP Server MUST verify that the JID is authorized to access the HTTP resource. This may involve JID-level or domain-level access checks, or (depending on local service policies) potentially no access checks at all if only verification is required.
+If the JID is authorized to access the HTTP resource, the HTTP Server MUST pass the URL, method, JID, and transaction identifier to the XMPP Server for confirmation. Exactly how this is done is up to the implementation. It is RECOMMENDED for the HTTP Server to connect to the XMPP Server as a trusted server component and to itself generate the confirmation request as described below.
+Upon receiving the JID and transaction identifier from the HTTP Server, the XMPP Server MUST send a confirmation request (via XMPP) to the XMPP Client (or route the confirmation request generated by the HTTP Server acting as a trusted XMPP server component).
+The confirmation request shall consist of an empty <confirm/> element qualified by the ''http://jabber.org/protocol/http-auth' namespace. This element MUST possess a 'method' attribute whose value is the method of the HTTP request, MUST possess a 'url' attribute whose value is the full HTTP URL that was requested, and MUST possess an 'id' attribute whose value is the transaction identifier provided in the HTTP Authorization Request.
+If the JID provided was a full JID, the confirmation request SHOULD be sent in an &IQ; stanza of type "get" whose 'to' attribute is set to the full JID, but MAY be sent in a &MESSAGE; stanza.
+If the JID provided was a bare JID, the confirmation request MUST be sent in a &MESSAGE; stanza whose 'to' attribute is set to the bare JID; this enables delivery to the "most available" resource for the user (however "most available" is determined by the XMPP Server). The &MESSAGE; stanza SHOULD include a &THREAD; element for tracking purposes and MAY include a &BODY; element that provides human-readable information or instructions.
+If the confirmation request was provided via an &IQ; stanza, the XMPP Client MUST respond to the request by sending an &IQ; stanza back to the XMPP Server. If the user wishes to confirm the request, the &IQ; response stanza MUST be of type "result" and MAY contain the original <confirm/> child element (although this is not necessary since the XMPP 'id' attribute can be used for tracking purposes):
+If the user wishes to deny the request, the &IQ; response stanza MUST be of type "error", MAY contain the original <confirm/> child element (although this is not necessary since the XMPP 'id' attribute can be used for tracking purposes), and MUST specify an error, which SHOULD be ¬authorized;:
+If the confirmation request was provided via a &MESSAGE; stanza and the &MESSAGE; contains a human-readable &BODY; or does not contain a &BODY; but the XMPP Client understands the 'http://jabber.org/protocol/http-auth' namespace, the XMPP Client SHOULD respond to the request by sending a &MESSAGE; stanza back to the XMPP Server. If the user wishes to confirm the request, the &MESSAGE; response stanza SHOULD be of type "normal", MUST mirror the <thread/> ID (if provided by the XMPP Server), and MUST contain the original <confirm/> child element:
+If the user wishes to deny the request, the &MESSAGE; response stanza MUST be of type "error", MUST mirror the <thread/> ID (if provided by the XMPP Server), MUST contain the original <confirm/> child element, and MUST specify an error, which SHOULD be ¬authorized;:
+Once the XMPP Client has successfully confirmed the request, the XMPP Server forwards that confirmation to the HTTP Server, which allows access:
+If the XMPP Client denied the request, the HTTP Server MUST return a Forbidden error:
+For the HEAD and OPTIONS methods, the credentials SHOULD be usable for a subsequent request from the same entity. This enables an entity to both determine support for the mechanism defined herein and start the authentication process.
+For the POST and PUT methods (or any method containing a message body), clients MUST send all data with each request (if needed, the client should obtain credentials with a previous HEAD or OPTIONS method).
+In order to associate the HTTP request with the XMPP confirmation, a transaction identifier MUST be provided by the user in the HTTP Authorization Request, then passed unchanged to the XMPP Client as the value of the <confirm/> element's 'id' attribute. If the XMPP Client generated the HTTP request, it MUST check the transaction identifier against the requests it has made to verify that the request has not yet been confirmed. If the XMPP Client did not generate the HTTP request, it MUST present the transaction identifier to the user for confirmation. If the XMPP Client or User confirms the request, the XMPP Client MUST then return a confirmation to the XMPP Server for delivery to the HTTP Server.
+To reduce the likelihood of man-in-the-middle attacks, channel encryption SHOULD be used for both the XMPP channel and the HTTP channel. In particular:
+-
+
- The channel used for HTTP requests and responses SHOULD be encrypted via SSL (secure HTTP via https: URLs) or TLS (&rfc2817;). +
- If the standard binding of XMPP to TCP is used, TLS SHOULD be negotiated for the XMPP channel in accordance with RFC 3920. +
- If a binding of XMPP to HTTP is used (e.g., as specified in JEP-0124), exchanges between the XMPP Client and XMPP Server (connection manager) SHOULD be sent over a channel that is encrypted using SSL or TLS. +
For added security, the XMPP Server and XMPP Client may wish to communicate using end-to-end encryption. Methods for doing so are outside the scope of this proposal.
+This document requires no interaction with &IANA;.
+The ®ISTRAR; includes "http://jabber.org/protocol/http-auth" in its registry of protocol namespaces.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0070: http://www.jabber.org/jeps/jep-0070.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+This JEP defines methods for exchanging instant messages that contain lightweight text markup. In the context of this JEP, "lightweight text markup" is to be understood as a combination of minimal structural elements and presentational styles that can easily be rendered on a wide variety of devices without requiring a full rich-text rendering engine such as a web browser. Examples of lightweight text markup include basic text blocks (e.g., paragraphs), lists, hyperlinks, image references, and font styles (e.g., sizes and colors).
+In the past, there have existed several incompatible methods within the Jabber community for exchanging instant messages that contain lightweight text markup. The most notable such methods have included derivatives of &w3xhtml; as well as of &rtf;.
+Although it is sometimes easier for client developers to implement RTF support (this is especially true on certain Microsoft Windows operating systems), there are several reasons (consistent with the &jep0134;) for the &JSF; to avoid the use of RTF in developing a protocol for lightweight text markup. Specifically:
+-
+
- RTF is not a structured vocabulary derived from SGML (as is &w3html;) or, more relevantly, from XML (as is XHTML 1.0). +
- RTF is under the control of the Microsoft Corporation and thus is not an open standard maintained by a recognized standards development organization; therefore the JSF is unable to contribute to or influence its development if necessary, and any protocol the JSF developed using RTF would introduce unwanted dependencies. +
Conversely, there are several reasons to prefer XHTML for lightweight text markup:
+-
+
- XHTML is a structured format that is defined as an application of &w3xml;, making it especially appropriate for sending over Jabber/XMPP, which is at root a technology for streaming XML (see &xmppcore;). +
- XHTML is an open standard developed by the &W3C;, a recognized standards development organization. +
Therefore, this JEP defines support for lightweight text markup in the form of an XMPP extension that encapsulates content defined by an XHTML 1.0 Integration Set that we label "XHTML-IM". The remainder of this JEP discusses lightweight text markup in terms of XHTML 1.0 only and does not further consider RTF or other technologies.
+HTML was originally designed for authoring and presenting stuctured documents on the World Wide Web, and was subsequently extended to handle more advanced functionality such as image maps and interactive forms. However, the requirements for publishing documents (or developing transactional websites) for presentation by dedicated XHTML clients on traditional computers or small-screen devices are fundamentally different from the requirements for lightweight text markup of instant messages; for this reason, only a reduced set of XHTML features is needed for XHTML-IM. In particular:
+-
+
IM clients are not XHTML clients: their primary purpose is not to read pre-existing XHTML documents, but to read and generate relatively large numbers of fairly small instant messages.
+ The underlying context for XHTML content in Jabber/XMPP instant messaging is provided not by a full XHTML document, but by an XML stream, and specifically by a message stanza within that stream. Thus the <head/> element and all its children are unnecessary. Only the <body/> element and some of its children are appropriate for use in instant messaging.
+ The XHTML content that is read by one's IM client is normally generated on the fly by one's conversation partner (or, to be precise, by his or her IM client). Thus there is an inherent limit to the sophistication of the XHTML markup involved. Even in normal XHTML documents, fairly basic structural and rendering elements such as definition lists, abbreviations, addresses, and computer input handling (e.g., <kbd/> and <var/>) are relatively rare. There is little or no foreseeable need for such elements within the context of instant messaging.
+ The foregoing is doubly true of more advanced markup such as tables, frames, and forms (however, there exists an XMPP extension that provides an instant messaging equivalent of the latter, as defined in &jep0004;).
+ Although ad-hoc styles are useful for messaging (by means of the 'style' attribute), full support for &w3css; (defined by the <style/> element or a standalone .css file, and implemented via the 'class' attribute) would be overkill since many CSS1 properties (e.g., box, classification, and text properties) were developed especially for sophisticated page layout.
+ Background images, audio, animated text, layers, applets, scripts, and other multimedia content types are unnecessary, especially given the existence of XMPP extensions such as &jep0096;.
+ Content transformations such as those defined by &w3xslt; must not be necessary in order for an instant messaging application to present lightweight text markup to an end user.
+
As explained below, some of these requirements are addressed by the definition of the XHTML-IM Integration Set itself, while others are addressed by a recommended "profile" for that Integration Set in the context of instant messaging applications.
+This document defines an adaptation of XHTML 1.0 (specifically, an XHTML 1.0 Integration Set) that makes it possible to provide lightweight text markup of instant messages (mainly for Jabber/XMPP instant messages, although the Integration Set defined herein could be used by other protocols). This pattern is familiar from email, wherein the HTML-formatted version of the message supplements but does not supersede the text-only version of the message.
In Jabber/XMPP communications, the meaning (as opposed to markup) of the message MUST always be represented as best as possible in the normal <body/> child element or elements of the &MESSAGE; stanza qualified by the 'jabber:client' (or 'jabber:server') namespace. Lightweight text markup is then provided within an <html/> element qualified by the 'http://jabber.org/protocol/xhtml-im' namespace.
The following example illustrates this approach.
+hi!
+ + + + ]]>Technically speaking, there are three aspects to the approach taken herein:
+-
+
- Definition of the <html/> "wrapper" element, which functions as an XMPP extension within XMPP <message/> stanzas. +
- Definition of the XHTML-IM Integration Set itself in terms of supported XHTML 1.0 modules, using the concepts defined in &w3xhtmlmod;. +
- A recommended "profile" regarding the specific XHTML 1.0 elements and attributes to be supported from each XHTML 1.0 module. +
These three aspects are defined in the three document sections that follow.
+The root element for including XHTML content within XMPP stanzas is <html/>. This element is qualified by the 'http://jabber.org/protocol/xhtml-im' namespace. From the perspective of XMPP, it functions as an XMPP extension element; from the perspective of XHTML, it functions as a wrapper for XHTML 1.0 content qualified by the 'http://www.w3.org/1999/xhtml' namespace. Such XHTML content MUST be contained in one or more <body/> elements qualified by the 'http://www.w3.org/1999/xhtml' namespace and MUST conform to the XHTML-IM Integration Set defined in the following section. If more than one <body/> element is included in the <html/> wrapper element, each <body/> element MUST possess an 'xml:lang' attribute with a distinct value, where the value of that attribute MUST adhere to the rules defined in &rfc3066;. A formal definition of the <html/> element is provided in the XHTML-IM Wrapper Schema.
+Note: The XHTML <body/> element is not to be confused with the XMPP <body/> element, which is a child of a &MESSAGE; stanza and is qualified by the 'jabber:client' or 'jabber:server' namespace as described in &xmppim;. The <html/> wrapper element is intended for inclusion only as a direct child element of the XMPP &MESSAGE; stanza and only in order to specify a marked-up version of the message &BODY; element or elements, but MAY be included elsewhere in accordance with the "extended namespace" rules defined in the XMPP IM specification.
+Until and unless (1) additional integration sets are defined and (2) mechanisms are specified for discovering or negotiating which integration sets are supported, the XHTML markup contained within the <html/> wrapper element MUST NOT include elements and attributes that are not part of the XHTML-IM Integration Set defined in the following section, and any such elements and attributes MUST be ignored if received (where the meaning of "ignore" is defined by the conformance requirements of Modularization of XHTML, as summarized in the User Agent Conformance section of this document).
+This section defines an XHTML 1.0 Integration Set for use in the context of instant messaging. Given its intended usage, we label it "XHTML-IM".
+Modularization of XHTML provides the ability to formally define subsets of XHTML 1.0 via the concept of "modularization" (which may be familiar from &w3xhtmlbasic;). Many of the defined modules are not necessary or useful in the context of instant messaging, and in the context of Jabber/XMPP instant messaging specifically some modules have been superseded by well-defined XMPP extensions. This JEP specifies that XHTML-IM shall be based on the following XHTML 1.0 modules:
+-
+
- Core Modules
+
-
+
- Structure Module +
- Text Module +
- Hypertext Module +
- List Module +
+ - Image Module +
- Style Attribute Module +
Modularization of XHTML defines many additional modules, such as Table Modules, Form Modules, Object Modules, and Frame Modules. None of these modules is part of the XHTML-IM Integration Set. If support for such modules is desired, it MUST be defined in a separate and distinct integration set.
+The Structure Module is defined as including the following elements and attributes:
| Element | Attributes |
|---|---|
| <body/> | class, id, title; style |
| <head/> | profile |
| <html/> | version |
| <title/> |
The Text Module is defined as including the following elements and attributes:
+| Element | Attributes |
|---|---|
| <abbr/> | class, id, title; style |
| <acronym/> | class, id, title; style |
| <address/> | class, id, title; style |
| <blockquote/> | class, id, title; style; cite |
| <br/> | class, id, title; style |
| <cite/> | class, id, title; style |
| <code/> | class, id, title; style |
| <dfn/> | class, id, title; style |
| <div/> | class, id, title; style |
| <em/> | class, id, title; style |
| <h1/> | class, id, title; style |
| <h2/> | class, id, title; style |
| <h3/> | class, id, title; style |
| <h4/> | class, id, title; style |
| <h5/> | class, id, title; style |
| <h6/> | class, id, title; style |
| <kbd/> | class, id, title; style |
| <p/> | class, id, title; style |
| <pre/> | class, id, title; style |
| <q/> | class, id, title; style; cite |
| <samp/> | class, id, title; style |
| <span/> | class, id, title; style |
| <strong/> | class, id, title; style |
| <var/> | class, id, title; style |
The Hypertext Module is defined as including the <a/> element only:
+| Element | Attributes |
|---|---|
| <a/> | class, id, title; style; accesskey, charset, href, hreflang, rel, rev, tabindex, type |
The List Module is defined as including the following elements and attributes:
+| Element | Attributes |
|---|---|
| <dl/> | class, id, title; style |
| <dt/> | class, id, title; style |
| <dd/> | class, id, title; style |
| <ol/> | class, id, title; style |
| <ul/> | class, id, title; style |
| <li/> | class, id, title; style |
The Image Module is defined as including the <img/> element only:
+| Element | Attributes |
|---|---|
| <img/> | class, id, title; style; alt, height, longdesc, src, width |
The Style Attribute Module is defined as including the style attribute only, as included in the preceding definition tables.
+Even within the restricted set of modules specified as defining the XHTML-IM Integration Set (see preceding section), some elements and attributes are inappropriate or unnecessary for the purpose of instant messaging; although such elements and attributes MAY be included in accordance with the XHTML-IM Integration Set, further recommended restrictions regarding which elements and attributes to include in XHTML content are specified below.
+The intent of the protocol defined herein is to support lightweight text markup of XMPP message bodies only. Therefore the <head/>, <html/>, and <title/> elements are NOT RECOMMENDED to be generated by a compliant implementation, and SHOULD be ignored if received (where the meaning of "ignore" is defined by the conformance requirements of Modularization of XHTML, as summarized in the User Agent Conformance section of this document). However, the <body/> element is REQUIRED, since it is the root element for all XHTML content.
+Not all of the Text Module elements are appropriate in the context of instant messaging, since the XHTML content that one views is generated by one's conversation partner in what is often a rapid-fire conversation thread. Only the following elements are RECOMMENDED in XHTML-IM:
+-
+
- <br/> +
- <p/> +
- <span/> +
The other Text Module elements SHOULD NOT be generated by a compliant implementation, and MAY be ignored if received (where the meaning of "ignore" is defined by the conformance requirements of Modularization of XHTML, as summarized in the User Agent Conformance section of this document).
+The only recommended attributes of the <a/> element are specified in the Recommended Attributes section of this document.
+Because it is unlikely that an instant messaging user would generate a definition list, only ordered and unordered lists are RECOMMENDED. Definition lists SHOULD NOT be generated by a compliant implementation, and MAY be ignored if received (where the meaning of "ignore" is defined by the conformance requirements of Modularization of XHTML, as summarized in the User Agent Conformance section of this document).
+The only recommended attributes of the <img/> element are specified in the Recommended Attributes section of this document. In addition, for security reasons or because of display constraints, a compliant client MAY choose to display 'alt' text only, not the image itself.
+This module MUST be supported in XHTML-IM if possible; although clients written for certain platforms (e.g., console clients, mobile phones, and handheld computers) or for certain classes of users (e.g., text-to-speech clients) may not be able to support all of the recommended styles directly, they SHOULD attempt to emulate or translate the defined style properties into text or other presentation styles that are appropriate for the platform or user base in question.
+A full list of recommended style properties is provided below.
+CSS1 defines 42 "atomic" style properties (which are categorized into font, color and background, text, box, and classification properties) as well as 11 "shorthand" properties ("font", "background", "margin", "padding", "border-width", "border-top", "border-right", "border-bottom", "border-left", "border", and "list-style"). Many of these properties are not appropriate for use in text-based instant messaging, for one or more of the following reasons:
+-
+
- The property applies to or depends on the inclusion of images other than those handled by the XHTML Image Module (e.g., the "background-image", "background-repeat", "background-attachment", "background-position", and "list-style-image" properties). +
- The property is intended for advanced document layout (e.g., the "line-height" property and most of the box properties, with the exception of "margin-left", which is useful for indenting text, and "margin-right", which can be useful when dealing with images). +
- The property is unnecessary since it can be emulated via user input or recommended XHTML stuctural elements (e.g., the "text-transform" property can be emulated by the user's keystrokes or use of the caps lock key) +
- The property is otherwise unlikely to ever be used in the context of rapid-fire conversations (e.g., the "font-variant", "word-spacing", "letter-spacing", and "list-style-position" properties). +
- The property is a shorthand property but some of the properties it includes are not appropriate for instant messaging applications according to the foregoing considerations (in fact this applies to all of the shorthand properties). +
Unfortunately, CSS1 does not include mechanisms for defining profiles thereof (as does XHTML 1.0 in the form of XHTML Modularization). While there exist reduced sets of CSS2, these introduce more complexity than is desirable in the context of XHTML-IM. Therefore we simply provide a list of recommended CSS1 style properties.
+XHTML-IM stipulates that only the following style properties are RECOMMENDED:
+-
+
- background-color +
- color +
- font-family +
- font-size +
- font-style +
- font-weight +
- margin-left +
- margin-right +
- text-align +
- text-decoration +
Although a compliant implementation MAY generate or process other style properties defined in CSS1, such behavior is NOT RECOMMENDED by this JEP.
+Section 5.1 of Modularization of XHTML describes several "common" attribute collections: a "Core" collection ('class', 'id', 'title'), an "I18N" collection ('xml:lang', not shown below since it is implied in XML), an "Events" collection (not included in the XHTML-IM Integration Set because the Intrinsic Events Module is not selected), and a "Style" collection ('style'). The following table summarizes the recommended profile of these common attributes within the XHTML 1.0 content itself:
+| Attribute | Usage | Reason |
|---|---|---|
| class | +NOT RECOMMENDED | +External stylesheets (which 'class' would typically reference) are not recommended. | +
| id | +NOT RECOMMENDED | +Internal links and message fragments are not recommended in IM content, nor are external stylesheets (which also make use of the 'id' attribute). | +
| title | +NOT RECOMMENDED | +Granting of titles to elements in IM content seems unnecessary. | +
| style | +REQUIRED | +The 'style' attribute is required since it is the vehicle for presentational styles. | +
| xml:lang | +NOT RECOMMENDED | +Differentiation of language identification should occur at the level of the <body/> element only. | +
Beyond the "common" attributes, certain elements within the modules selected for the XHTML-IM Integration Set are allowed to possess other attributes, such as eight attributes for the <a/> element and five attributes for the <img/> element. The recommended profile for such attributes is provided in the following table:
+| Element Scope | Attribute | Usage |
|---|---|---|
| <a/> | +accesskey | +NOT RECOMMENDED | +
| <a/> | +charset | +NOT RECOMMENDED | +
| <a/> | +href | +REQUIRED | +
| <a/> | +hreflang | +NOT RECOMMENDED | +
| <a/> | +rel | +NOT RECOMMENDED | +
| <a/> | +rev | +NOT RECOMMENDED | +
| <a/> | +tabindex | +NOT RECOMMENDED | +
| <a/> | +type | +RECOMMENDED | +
| <img/> | +alt | +REQUIRED | +
| <img/> | +height | +RECOMMENDED | +
| <img/> | +longdesc | +NOT RECOMMENDED | +
| <img/> | +src | +REQUIRED | +
| <img/> | +width | +RECOMMENDED | +
Other XHTML 1.0 attributes SHOULD NOT be generated by a compliant implementation, and SHOULD be ignored if received (where the meaning of "ignore" is defined by the conformance requirements of Modularization of XHTML, as summarized in the User Agent Conformance section of this document).
+The following table summarizes the elements and attributes that are recommended within the XHTML-IM Integration Set.
+| Element | +Attributes | +
|---|---|
| <a/> | +href, style, type | +
| <body/> | +style, xml:lang |
+
| <br/> | +-none- | +
| <img/> | +alt, height, src, style, width | +
| <li/> | +style | +
| <ol/> | +style | +
| <p/> | +style | +
| <span/> | +style | +
| <ul/> | +style | +
Any other elements and attributes defined in the XHTML 1.0 modules that are included in the XHTML-IM Integration Set SHOULD NOT be generated by a compliant implementation, and SHOULD be ignored if received (where the meaning of "ignore" is defined by the conformance requirements of Modularization of XHTML, as summarized in the User Agent Conformance section of this document).
+The following rules apply to the generation and processing of XHTML content by Jabber clients or other XMPP entities.
+-
+
XHTML-IM content is designed to provide a formatted version of the XML character data provided in the &BODY; of an XMPP &MESSAGE; stanza; if such content is included in an XMPP message, the <html/> element MUST be a direct child of the &MESSAGE; stanza and the XHTML-IM content MUST be understood as a formatted version of the message body. XHTML-IM content MAY be included within XMPP &IQ; stanzas (or children thereof), but any such usage is undefined. In order to preserve bandwidth, XHTML-IM content SHOULD NOT be included within XMPP &PRESENCE; stanzas; however, if it is so included, the <html/> element MUST be a direct child of the &PRESENCE; stanza and the XHTML-IM content MUST be understood as a formatted version of the XML character data provided in the &STATUS; element.
+ The sending client MUST ensure that, if XHTML content is sent, its meaning is the same as that of the plaintext version, and that the two versions differ only in markup rather than meaning.
+ XHTML-IM is a reduced set of XHTML 1.0 and thus also of XML 1.0. Therefore all opening tags MUST be completed by inclusion of an appropriate closing tag.
+ XMPP Core specifies that an XMPP &MESSAGE; MAY contain more than one <body/> child as long as each <body/> possesses an 'xml:lang' attribute with a distinct value. In order to ensure correct internationalization, if an XMPP &MESSAGE; stanza contains more than one <body/> child and is also sent as XHTML-IM, the <html/> element SHOULD also contain more than one <body/> child, with one such element for each <body/> child of the &MESSAGE; stanza (distinguished by an appropriate 'xml:lang' attribute).
+ Section 11.1 of XMPP Core stipulates that character entities other than the five general entities defined in Section 4.6 of the XML specification (i.e., <, >, &, ', and ") MUST NOT be sent over an XML stream. Therefore implementations of XHTML-IM MUST NOT include predefined XHTML 1.0 entities such as -- instead, implementations MUST use the equivalent character references as specified in Section 4.1 of the XML specification (even in non-obvious places such as URIs that are included in the 'href' attribute).
+ For elements and attributes qualified by the 'http://www.w3.org/1999/xhtml' namespace, user agent conformance is guided by the requirements defined in Modularization of XHTML; for details, refer to the User Agent Conformance section of this document.
+ The use of structural elements is NOT RECOMMENDED where presentational styles are desired, which is why very few structural elements are specified herein. Implementations SHOULD use appropriate 'style' attributes (e.g., <span style='font-weight: bold'>this is bold</span> and <p style='margin-left: 5%'>this is indented</p>) rather than XHTML structural elements (e.g., <strong/> and <blockquote/>) wherever possible.
+ Nesting of block structural elements (<p/>) and list elements (<dl/>, <ol/>, <ul/>) is NOT RECOMMENDED, except within <div/> elements.
+ It is RECOMMENDED for implementations to replace line breaks with the <br/> element and to replace significant whitepace with the appropriate number of non-breaking spaces (via the NO-BREAK SPACE character or its equivalent), where "significant whitespace" means whitespace that makes some material difference (e.g., one or more spaces at the beginning of a line or more than one space anywhere else within a line), not "normal" whitespace separating words or punctuation.
+
The following examples provide an insight into the inclusion of XHTML content in XMPP &MESSAGE; stanzas but are by no means exhaustive or definitive.
+(Note: The examples may not render correctly in all web browsers, since not all web browsers comply fully with the XHTML 1.0 and CSS1 standards. Markup in the examples may include line breaks for readability. Example renderings are shown with a colored background to set them off from the rest of the text.)
++ OMG, + I'm green + with envy! +
+ + + + ]]>This could be rendered as follows:
+OMG, I'm green with envy!
+As Emerson said in his essay Self-Reliance:
++ "A foolish consistency is the hobgoblin of little minds." +
+ + + + ]]>This could be rendered as follows:
+As Emerson said in his essay Self-Reliance:
++ "A foolish consistency is the hobgoblin of little minds." +
+Hey, are you licensed to Jabber?
+
This could be rendered as follows:
+Hey, are you licensed to Jabber?
+
Note the large size of the image. Including the 'height' and 'width' attributes is therefore quite friendly, since it gives the receiving application hints as to whether the image is too large to fit into the current interface (naturally, these are hints only and cannot necessarily be relied upon in determining the size of the image).
+Rendering the 'alt' value rather than the image would yield something like the following:
+Hey, are you licensed to Jabber?
+IMG: "A License to Jabber"
+Here's my .plan for today:
+-
+
- Add the following examples to JEP-0071:
+
-
+
- ordered and unordered lists +
- more styles (e.g., indentation) +
+ - Kick back and relax +
This could be rendered as follows:
+Here's my .plan for today:
+-
+
- Add the following examples to JEP-0071:
+
-
+
- ordered and unordered lists +
- more styles (e.g., indentation) +
+ - Kick back and relax +
You wrote:
+I think we have consensus on the following:
+-
+
- Remove <div/> +
- Nesting is not recommended +
- Don't preserve whitespace +
Yes, no, maybe?
+That seems fine to me.
+ + + + ]]>Although quoting received messages is relatively uncommon in IM, it does happen. This could be rendered as follows:
+You wrote:
+I think we have consensus on the following:
+-
+
- Remove <div/> +
- Nesting is not recommended +
- Don't preserve whitespace +
Yes, no, maybe?
+That seems fine to me.
+awesome!
+ + +ausgezeichnet!
+ + + + ]]>How multiple bodies would best be rendered will depend on the user agent and relevant application. For example, a specialized Jabber client that is used in foreign language instruction might show two languages side by side, whereas a dedicated IM client might show content only in a human user's preferred language as captured in the client configuration.
+The XHTML user agent conformance + requirements say to ignore elements and attributes + you don't understand, to wit:
+-
+
+ If a user agent encounters an element it does + not recognize, it must continue to process the + children of that element. If the content is text, + the text must be presented to the user. +
+ + If a user agent encounters an attribute it does + not recognize, it must ignore the entire attribute + specification (i.e., the attribute and its value). +
+
Let us assume that the recipient's user agent recognizes neither the <acronym/> element (which is discouraged in XHTML-IM) nor the 'type' and 'start' attributes of the <ol/> element (which, after all, were deprecated in HTML 4.0), and that it does not render nested elements (e.g., the <p/> elements within the <li/> elements); in this case, it could render the content as follows (note that the element value is shown as text and the attribute value is not rendered):
+The XHTML user agent conformance requirements say to ignore elements and attributes you don't understand, to wit:
+-
+
- If a user agent encounters an element it does not recognize, it must continue to process the children of that element. If the content is text, the text must be presented to the user. +
- If a user agent encounters an attribute it does not recognize, it must ignore the entire attribute specification (i.e., the attribute and its value). +
This section describes methods for discovering whether a Jabber client or other XMPP entity supports the protocol defined herein.
+The primary means of discovering support for XHTML-IM is &jep0030;.
+If the queried entity supports XHTML-IM, it MUST return a <feature/> element with a 'var' attribute set to a value of "http://jabber.org/protocol/xhtml-im" in the IQ result.
+A Jabber user's client MAY send XML &MESSAGE; stanzas containing XHTML-IM extensions without first discovering if the conversation partner's client supports XHTML-IM. If the user's client sends a message that includes XHTML-IM markup and the conversation partner's client replies to that message but does not include XHTML-IM markup, the user's client SHOULD NOT continue sending XHTML-IM markup.
+The exclusion of scripts, applets, and other multimedia elements reduces the risk of exposure to harmful or malicious objects caused by inclusion of XHTML content. Because of security concerns related to images, an implementation MAY choose not to show images but instead show only the 'alt' text. Because of security concerns related to hyperlinks, an implementation MAY choose not to make them clickable.
+The usage of XHTML 1.0 defined herein meets the requirements for XHTML 1.0 Integration Set document type conformance as defined in Section 3 ("Conformance Definition") of Modularization of XHTML.
+The Formal Public Identifier (FPI) for the XHTML-IM document type definition is:
+The fields of this FPI are as follows:
+-
+
- The leading field is "-", which indicates that this is a privately-defined resource. +
- The second field is "JSF" (an abbreviation for Jabber Software Foundation), which identifies the organization that maintains the named item. +
- The third field contains two constructs:
+
-
+
- The public text class is "DTD", which adheres to ISO 8879 Clause 10.2.2.1. +
- The public text description is "Instant Messaging with XHTML", which contains but does not begin with the string "XHTML" (as recommended for an XHTML 1.0 Integration Set). +
+ - The fourth field is "EN", which identifies the language (English) in which the item is defined. +
A user agent that implements this specification MUST conform to Section 3.5 ("XHTML Family User Agent Conformance") of Modularization of XHTML. Many of the requirements defined therein are already met by Jabber clients simply because they already include XML parsers.
+However, "ignore" has a special meaning in XHTML modularization (different from its meaning in XMPP). Specifically, criteria 4 through 6 of Section 3.5 of Modularization of XHTML state:
+-
+
-
+
W3C TEXT: If a user agent encounters an element it does not recognize, it must continue to process the children of that element. If the content is text, the text must be presented to the user.
+JSF COMMENT: This behavior is different from that defined by XMPP Core, and in the context of XHTML-IM implementations applies only to XML elements qualified by the 'http://www.w3.org/1999/xhtml' namespace as defined herein. This criterion MUST be applied to all XHTML 1.0 elements except those explicitly included in XHTML-IM as described in the XHTML-IM Integration Set and Recommended Profile sections of this document. Therefore, an XHTML-IM implementation MUST process all XHTML 1.0 child elements of the XHTML-IM <html/> element even if such child elements are not included in the XHTML 1.0 Integration Set defined herein, and MUST present to the recipient the XML character data contained in such child elements.
+
+ -
+
W3C TEXT: If a user agent encounters an attribute it does not recognize, it must ignore the entire attribute specification (i.e., the attribute and its value).
+JSF COMMENT: This criterion MUST be applied to all XHTML 1.0 attributes except those explicitly included in XHTML-IM as described in the XHTML-IM Integration Set and Recommended Profile sections of this document. Therefore, an XHTML-IM implementation MUST ignore all attributes of elements qualified by the 'http://www.w3.org/1999/xhtml' namespace if such attributes are not explicitly included in the XHTML 1.0 Integration Set defined herein.
+
+ -
+
W3C TEXT: If a user agent encounters an attribute value it doesn't recognize, it must use the default attribute value.
+JSF COMMENT: Since not one of the attributes included in XHTML-IM has a default value defined for it in XHTML 1.0, in practice this criterion does not apply to XHTML-IM implementations.
+
+
For information regarding XHTML modularization in XML schema for the XHTML 1.0 Integration Set defined in this specification, refer to the Schema Driver section of this document.
+The XHTML 1.0 Integration Set defined herein has been reviewed informally by an editor of the XHTML Modularization in XML Schema specification but has not undergone formal review by the W3C; before this specification proceeds to a status of Final within the Jabber Software Foundation's standards process, it should undergo a formal review through communication with the Hypertext Coordination Group within the W3C.
+The W3C is actively working on &w3xhtml2; and may produce additional versions of XHTML in the future. This specification addresses XHTML 1.0 only, but it may be superseded or supplemented in the future by a Jabber Enhancement Proposal that defines methods for encapsulating XHTML 2.0 content in XMPP.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'http://jabber.org/protocol/xhtml-im' in its registry of protocol namespaces.
+The following schema defines the XMPP extension element that serves as a wrapper for XHTML content.
+
+
+
+
+
+
+
+ This schema defines the element qualified by
+ the 'http://jabber.org/protocol/xhtml-im' namespace.
+ The only allowable child is a element qualified
+ by the 'http://www.w3.org/1999/xhtml' namespace. Refer
+ to the XHTML-IM schema driver for the definition of the
+ XHTML 1.0 Integration Set.
+
+ Full documentation of this Integration Set is contained in
+ "JEP-0071: XHTML-IM", a specification published by the
+ Jabber Software Foundation.
+
+ http://www.jabber.org/jeps/jep-0071.html
+
+
+
+
+
+
+
+
+
+
+ ]]>
+ The following schema defines the modularization schema driver for XHTML-IM.
+
+
+
+
+
+
+
+ This is the XML Schema driver for XHTML-IM, an XHTML 1.0
+ Integration Set for use in exchanging marked-up instant
+ messages between entities that conform to the Extensible
+ Messaging and Presence Protocol (XMPP). This Integration
+ Set includes a subset of the modules defined for XHTML 1.0
+ but does not redefine any existing modules, nor does it
+ define any new modules. Specifically, it includes the
+ following modules only:
+
+ - Structure
+ - Text
+ - Hypertext
+ - List
+ - Image
+ - Style Attribute
+
+ The Formal Public Identifier (FPI) for this Integration
+ Set is:
+
+ -//JSF//DTD Instant Messaging with XHTML//EN
+
+ Full documentation of this Integration Set is contained in
+ "JEP-0071: XHTML-IM", a specification published by the
+ Jabber Software Foundation, which is available at the
+ following URL:
+
+ http://www.jabber.org/jeps/jep-0071.html
+
+
+
+
+
+ ]]>
+ The following schema defines the content model for XHTML-IM.
+
+
+
+
+
+
+ This is the XML Schema module of named XHTML 1.0 content models
+ for XHTML-IM, an XHTML 1.0 Integration Set for use in exchanging
+ marked-up instant messages between entities that conform to
+ the Extensible Messaging and Presence Protocol (XMPP). This
+ Integration Set includes a subset of the modules defined for
+ XHTML 1.0 but does not redefine any existing modules, nor
+ does it define any new modules. Specifically, it includes the
+ following modules only:
+
+ - Structure
+ - Text
+ - Hypertext
+ - List
+ - Image
+ - Style Attribute
+
+ Therefore XHTML-IM uses the following content models:
+
+ Block.mix; Block-like elements, e.g., paragraphs
+ Flow.mix; Any block or inline elements
+ Inline.mix; Character-level elements
+ InlineNoAnchor.class; Anchor element
+ InlinePre.mix; Pre element
+
+ XHTML-IM also uses the following Attribute Groups:
+
+ Core.extra.attrib
+ I18n.extra.attrib
+ Common.extra
+
+ Full documentation of this Integration Set is contained in
+ "JEP-0071: XHTML-IM", a specification published by the
+ Jabber Software Foundation.
+
+ http://www.jabber.org/jeps/jep-0071.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+ This specification formalizes and extends earlier work by Jeremie Miller and Julian Missig on XHTML formatting of Jabber messages. Many thanks to Shane McCarron for his assistance regarding XHTML modularization and conformance issues. Thanks also to contributors on the Standards-JIG list for their feedback and suggestions.
+&w3soap; is a lightweight protocol that defines a method for the exchange of messages independently from the programming language and platform. For interoperability, the SOAP specification is also agnostic about possible transport protocols, though almost all existing implementations use mainly HTTP.
+The primary limitation of HTTP consists in the fact that HTTP-based message exchanges allow only synchronous request-response semantics. To overcome this limitation, SMTP is often used to carry asynchronous messages, but it is a complex protocol and inefficient for passing short and frequent messages that should be delivered in close to real time.
+Thus XMPP (see &rfc3920;) can be the ideal transport protocol for many of the application fields of web services, since it can carry efficiently and reliably both types of messages, synchronous and asynchronous. Moreover, XMPP-based web services will not need complex support protocols, such as WS-Routing
(Note: The main body of this document provides descriptive text suitable for use by XMPP developers. A formal description of the SOAP XMPP Binding itself is provided in the section of this document entitled SOAP XMPP Binding.)
+The usual architecture of XMPP is described in Section 2 of RFC 3920. In essence, XMPP is most commonly deployed using a client-server (or logical peer-to-peer) architecture quite similar to that of the email system, except that XMPP does not have multiple hops between servers, enforces domain names to prevent address spoofing, and enables channel encryption (via TLS) and authentication (via SASL) between client and server as well as among servers.
+The binding of SOAP to XMPP assumes that most SOAP-enabled XMPP entities will be implemented as XMPP clients that communicate with other entities as logical peers. However, in order to deploy more scalable services, such entities could also be implemented as server-side components (see &jep0114;) or even as special-purpose XMPP servers.
+The SOAP specification defines the concepts of "SOAP intermediary" and "ultimate SOAP receiver" (see Section 1.5.3 of SOAP Version 1.2 Part 1). In general, this specification assumes that XMPP entities that support the SOAP XMPP Binding will be ultimate SOAP receivers, since SOAP intermediaries tend to be artifacts of the existing SOAP bindings (HTTP and SMTP) rather than applicable to all possible bindings. SOAP intermediaries are usually deployed in order to (1) cross trust boundaries in protocols that do not enforce domain names or authenticate end-points, (2) ensure scalability, (3) secure messages sent over unencrypted channels, and (4) provide message tracing. However, these issues are addressed natively in XMPP (e.g., channel encryption is defined in RFC 3920), in XMPP extensions (e.g., message tracing is defined in &jep0079;), or in deployment decisions such as business level agreements between XMPP domains. One final justification for SOAP intermediaries is to act as gateways between different transport mechanisms (e.g., between HTTP and SMTP), and XMPP entities may well be SOAP intermediaries for that reason. For further details about gateways between XMPP and other SOAP bindings, refer to the Implementation Notes section of this document.
+In order to determine whether a potential responding entity supports the SOAP XMPP Binding, a requesting entity SHOULD send a &jep0030; information request to the potential responding entity:
+If the responding entity supports the SOAP XMPP Binding and the requesting entity is not blocked from communicating with the responding entity, the responding entity MUST include a feature of "http://jabber.org/protocol/soap" in its reply and SHOULD specify a service discovery identity of "automation/soap".
+When a requesting entity wants to interact with a responding entity via the SOAP XMPP Binding, it faces a fundamental choice: to use &IQ; stanzas or to use &MESSAGE; stanzas. The following guidelines may prove useful:
+-
+
- &IQ; stanzas SHOULD be used when more formal request-response semantics are needed or when an immediate answer is required. +
- &MESSAGE; stanzas SHOULD be used when less formal request-response semantics are acceptable or when store-and-forward ("offline message") delivery is needed (e.g., because the intended recipient may be temporarily unavailable). +
Examples of both approaches are provided below, encapsulating the SOAP message examples (a travel reservation flow) to be found in &w3soap0;.
+The transport with &IQ; stanzas is performed in a way similar to that described for XML-RPC in &jep0009;. Request envelopes are carried by &IQ; stanzas of type "set", and answer envelopes by &IQ; stanzas of type "result". SOAP errors are encoded with standard SOAP envelopes, and returned in stanzas of type "error" with appropriate codes in order to distinguish them from errors specific to the XMPP transport layer (see Error Handling for details).
+Each &IQ; stanza of type "set" MUST contain a SOAP envelope as the first-level child element, since it already represents a properly namespaced XML subtree qualified by the 'http://www.w3.org/2003/05/soap-envelope' namespace.
+If the responding entity does not support the SOAP XMPP Binding, it SHOULD return a &unavailable; error:
+If a SOAP-related fault occurs, the mappings in Error Handling SHOULD be used.
+If the responding entity does not return an error, it MUST respond with an IQ of type "result":
+At this point the requesting entity could send another IQ-set:
+The process for exchanging SOAP messages using the XMPP &MESSAGE; stanza type is effectively no different from the use with &IQ; stanzas, except that message stanzas may be sent to bare JIDs (user@host) rather than full JIDs (user@host/resource), message stanzas may be stored for later delivery, etc. The following business rules apply:
+-
+
- The message stanza containing a request MUST carry one SOAP envelope as a first-level child element. +
- The 'id' attribute MUST be used to track the XMPP messages and eventually associate errors or answers with the related requests (this is for tracking at the XMPP level, not the SOAP level). +
SOAP messages may contain associated (usually binary) data, and XMPP stanzas that encapsulate such SOAP messages could invoke bandwidth restriction settings (commonly called "karma" in XMPP) tuned for normal text chats. The problem could be bypassed by servers having special karma settings for larger messages, or by SOAP-enabled entities being implemented as components rather than XMPP nodes; however, server-to-server communications risk becoming a serious bottleneck, especially in terms of latency and responsiveness when too many large messages are sent. Therefore, it is desirable to support the sending of attachments or files in order to exchange large amounts of binary data associated with SOAP requests and responses. As summarized in the following table, here are four possible methods:
+| Method | +Description | +Recommendation | +Reasoning | +
|---|---|---|---|
| File Transfer | +Negotiate file transfer using &jep0096; and &jep0137;. | +SHOULD | +Recommended approach for file transfer over XMPP (e.g., see &jep0117;). | +
| Include Link | +Represent the binary data as a file, publish it to an accessible file server (e.g., HTTP or FTP URL), and insert a link to the file directly into the XMPP message stanza (via &jep0066;) or into the SOAP envelope (via &w3soaprep;). | +MAY | +Fallback if file transfer is not possible (not all clients can publish to file servers). | +
| Alternate Transports | +Send SOAP XML plus binary data over alternate transports such as WS-Attachments |
+ SHOULD NOT | +These methods are just other transport protocols and would needlessly complicate implementations of SOAP over XMPP. | +
| MIME | +Encode SOAP envelopes and attachments as MIME multipart messages using &w3soapaf; (or, more recently, &w3soapmtom; and &w3xop;). | +MUST NOT | +XML streams are pure XML and are not MIME-aware. | +
The recommended approaches (file transfer and including a link) are described more fully below.
+The recommended method for sending associated data is to use the file transfer protocol described in JEP-0096. Because this is the common and standardized method for XMPP entities to transfer large or binary files outside the XMPP band, it SHOULD be used.
+In particular, the entity that has the file SHOULD advertise the availability of the associated stream using JEP-0137 by including the SI-pub data extension along with the XMPP &MESSAGE; stanza with which the data is associated:
The entity that is to receive the file SHOULD initiate the file transfer process sending an IQ-get to the sender, using the <start xmlns='http://jabber.org/protocol/sipub'/> element. This element contains the 'id' attribute to specify which published stream to retrieve:
+If the sender accepts the request, it responds with an IQ-result containing a <starting/> element. This element indicates the stream initiation identifier to be used:
+Then the sender begins the stream initiation negotiation:
+For details regarding file transfer and advertising of file transfer stream initiation requests, refer to JEP-0096 and JEP-0137.
+If the file transfer method is not possible (e.g., because file transfer is not implemented or transfer attempts fails), the entity that is sending the associated data MAY as a fallback publish the associated data as a file (e.g., at an HTTP or FTP URL) and include a link to the file as out-of-band content by including the out-of-band data extension along with the XMPP &MESSAGE; stanza with which the data is associated:
Alternatively, if all else fails, the file may be included as a SOAP representation header:
+Naturally, in order to maximize the likelihood that the receiver will be able to retrieve the file, the sender MAY include the SI-pub extension, out-of-band-data extension, and SOAP representation header in the message stanza:
+&w3wsdl; provides a machine-readable, formal description of web services operations, protocol bindings, and end points (i.e., network addresses). WSDL definitions attempt to specify a loose coupling of SOAP envelopes and their transports in order to maintain their independence and flexibility.
+The definition of an XMPP SOAP transport in WSDL is straightforward. The following rules apply:
+-
+
- The 'transport' attribute of the <soap:binding> element MUST be set to "http://jabber.org/protocol/soap". +
- The 'style' attribute of the <soap:binding> element SHOULD be set to "document". +
- The 'soapAction' attribute of the <soap:operation> element MAY be used; if so, it SHOULD be transported in an appropriate env:Header element for compatibility with the HTTP transport. +
- A valid XMPP URI/IRI (see &rfc4622;) MUST be used for the 'location' attribute in the <soap:address> element. +
The following is an example of a WSDL definition for an endpoint that supports the SOAP XMPP binding: a mythical service that translates Shakespearean English into selected modern languages and dialects.
+Although there is no standard procedure for publishing WSDL documents, usually they are made available through HTTP at some URL discoverable with public registries such as UDDI servers. WSDL descriptions for XMPP bindings MAY follow the same publishing process, or MAY be discoverable through Jabber/XMPP specific mechanisms such as &jep0030; or &jep0060;.
+Section 4 of &w3soap1; defines a SOAP Protocol Binding Framework; two instantiations of that framework are the SOAP HTTP Binding (specified in Section 7 of &w3soap2;) and the &w3soapemail;. (Additionally, a binding to BEEP is described in RFC 3288.) As an alternative to the HTTP and Email bindings, this section formally defines the SOAP XMPP Binding in accordance with the SOAP Protocol Binding Framework.
+Note: The SOAP XMPP Binding is optional, and SOAP nodes are not required to implement it. A SOAP node that correctly and completely implements the SOAP XMPP Binding as described herein may be said to "conform to the SOAP 1.2 XMPP Binding".
+The SOAP XMPP Binding is identified by the following URI:
+-
+
- http://jabber.org/protocol/soap +
XMPP is a pure XML streaming protocol used to exchange snippets of structured data called "XML stanzas" (see Section 4.1 of RFC 3920) between any two network endpoints.
+Because XMPP is a direct messaging protocol, it does not possess the equivalent of web methods such as the HTTP GET, PUT, POST, and DELETE methods. Therefore, it is NOT RECOMMENDED for a SOAP node that supports only the SOAP XMPP Binding to provide the "SOAP Web Method Feature" described in Section 6.4 of SOAP Version 1.2 Part 2. (A SOAP gateway between XMPP and HTTP should support the SOAP Web Method Feature in order to ensure interoperability; however, description of such gateways is outside the scope of this document.)
+Because XMPP is a pure XML protocol, it does not use MIME types (&rfc2045;) or XML media types (&rfc3023;), but rather sends XML directly over the wire. Therefore, it is NOT RECOMMENDED for a SOAP node that supports only the SOAP XMPP Binding to provide the "SOAP Action Feature" described in Section 6.5 of SOAP Version 1.2 Part 2. (A SOAP gateway between XMPP and HTTP should support the SOAP Action Feature in order to ensure interoperability; however, description of such gateways is outside the scope of this document.)
+XMPP inherently provides request-response semantics via the &IQ; stanza type and &MESSAGE; stanza type, where the &IQ; stanza type requires more formality regarding preservation of request-response semantics in the context of synchronous communications, whereas the &MESSAGE; stanza provides a looser mapping to request-response semantics as well as the ability to ensure store-and-forward capabilities similar to those provided by email (see the Implementation Notes section of this document). Because both stanza types support request-response semantics, an implementation of the SOAP XMPP Binding MUST support only the following message exchange pattern (MEP) defined in the core SOAP 1.2 specification:
+-
+
- http://www.w3.org/2003/05/soap/mep/request-response/ +
The request-response message exchange pattern is described in Section 6.2 of SOAP Version 1.1 Part 2. For binding instances conforming to the specification of the SOAP XMPP Binding:
+-
+
- A SOAP node instantiated at an XMPP entity may assume the role (i.e., the http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role property) of "RequestingSOAPNode". +
- A SOAP node instantiated at an XMPP entity may assume the role (i.e., the http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role property) of "RespondingSOAPNode". +
The remainder of this section describes the message exchange pattern (MEP) state machine and its relation to XMPP as described in RFC 3920. For the sake of brevity, relative URIs are used (the base URI being http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role), the string "fail:" is used as a conventional prefix for the namespace http://www.example.org/2001/12/soap/mep/FailureReasons/, and the string "reqresp:" is used as a conventional prefix for the namespace http://www.example.org/2001/12/soap/mep/request-response/. In the state tables below, the states are defined as values of the http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State property (see Section 6.2 of SOAP Version 1.2 Part 2) and are of type xs:anyURI.
+The overall flow of the behavior of a Requesting SOAP Node follows the outline state machine description contained in Section 6.2 of SOAP Version 1.2 Part 2. The following subsections describe each state in more detail, where "Requesting SOAP Node" is to be understood as a logical entity made up of the binding and the local SOAP node associated with the XMPP entity that generates a SOAP request.
+The following table formally describes the "Init" state of the Requesting SOAP Node in the SOAP XMPP Binding:
+| Feature | +Value / Description | +
|---|---|
| State Name | +Init | +
| Description | +Formulate and send request message | +
| Pre-Conditions | +Control of the outbound transport message exchange context is transferred from the local SOAP node to the binding | +
| Actions | +Formulate and send XMPP &IQ; or &MESSAGE; request stanza (see table "Init: XMPP Fields (Requesting)") that encappsulates SOAP envelope transferred from local SOAP node to binding | +
| Post-Conditions | +None | +
| Transitions | +See table "Init: Transitions (Requesting)" | +
In the "Init" state, an XMPP stanza (either &IQ; or &MESSAGE;) is formulated by the Requesting SOAP Node according to the following table:
+| Field | +Value / Description | +
|---|---|
| XMPP Method | +For XMPP &IQ; stanzas, the value of the XMPP 'type' attribute MUST be "set"; does not apply to XMPP &MESSAGE; stanzas | +
| Originator | +The XMPP address (JID) carried in the reqresp:ImmediateSender property of the message exchange context is encapsulated as the value of the XMPP 'from' attribute; normally this is set by the XMPP server to which the originator connects | +
| Destination | +The XMPP address (JID) carried in the reqresp:ImmediateDestination property of the message exchange context is encapsulated as the value of the XMPP 'to' attribute | +
| Correlation Request Message ID | +As required for XMPP &IQ; stanzas in general and required for XMPP &MESSAGE; stanzas sent in the context of the SOAP XMPP Binding, a correlation request message ID is generated by the sender and encapsulated as the value of the XMPP 'id' attribute | +
| XMPP Stanza Contents | +The XML of the SOAP envelope carried in the reqresp:OutboundMessage property of the transport message exchange context is encapsulated as a direct child element of the XMPP &IQ; or &MESSAGE; stanza | +
The following table summarizes the transitions from the "Init" state of the Requesting SOAP Node:
+| Event / Condition | +Next State | +Failure Reason | +
|---|---|---|
| Request Successfully Sent | +Requesting | +N/A | +
| Failure to Send Request | +Fail | +fail:TransmissionFailure | +
The following table formally describes the "Requesting" state of the Requesting SOAP Node in the SOAP XMPP Binding:
+| Feature | +Value / Description | +
|---|---|
| State Name | +Requesting | +
| Description | +Waiting for correlated XMPP response (Request Message completely sent on exit from Init state) | +
| Pre-Conditions | +Completion of Init state | +
| Actions | +Wait for a receive XMPP response stanza | +
| Post-Conditions | +Instantiate or replace the reqresp:ImmediateSender property with an XMPP address (JID) that denotes the sender of the XMPP response stanza | +
| Transitions | +See table "Requesting: Transitions" | +
The following table summarizes the transitions from the "Requesting" state of the Requesting SOAP Node:
+| Event / Condition | +Next State | +Failure Reason | +
|---|---|---|
| Received Correlated XMPP Response | +Sending+Receiving | +N/A | +
| Reception Failure (various XMPP errors) | +Fail | +fail:ReceptionFailure | +
For a listing of relevant XMPP error conditions, refer to Sections 9.3.3 and 4.7.3 of RFC 3920.
+The following table formally describes the "Sending+Receiving" state of the Requesting SOAP Node in the SOAP XMPP Binding:
+| Feature | +Value / Description | +
|---|---|
| State Name | +Sending+Receiving | +
| Description | +Receive correlated XMPP response including SOAP envelope | +
| Pre-Conditions | +Completion of Receiving state | +
| Actions | +Process XMPP &IQ; or &MESSAGE; response stanza and included SOAP envelope, instantiating or replacing the reqresp:InboundMessage property with an infoset representation of the SOAP envelope contained in the XMPP response stanza | +
| Post-Conditions | +Control of the inbound transport message exchange context is transferred from the binding to the local SOAP node | +
| Transitions | +See table "Sending+Receiving: Transitions" | +
The following table summarizes the transitions from the "Sending+Receiving" state of the Requesting SOAP Node:
+| Event / Condition | +Next State | +Failure Reason | +
|---|---|---|
| Received Well-Formed Response Message | +Success | +N/A | +
| Reception Failure (various XMPP errors) | +Fail | +fail:ReceptionFailure | +
| Malformed Response Message (invalid SOAP envelope) | +Fail | +fail:BadRequestMessage | +
For a listing of relevant XMPP error conditions, refer to Sections 9.3.3 and 4.7.3 of RFC 3920.
+A given instance of a request-response transport message exchange terminates when the state "Success" or "Fail" is reached; control over the transport message exchange context returns to the Requesting SOAP Node.
+The overall flow of the behavior of a Responding SOAP Node follows the outline state machine description contained in Section 6.2 of SOAP Version 1.2 Part 2. The following subsections describe each state in more detail, where "Responding SOAP Node" is to be understood as a logical entity made up of the binding and the local SOAP node associated with the XMPP entity that responds to a SOAP request.
+The following table formally describes the "Init" state of the Responding SOAP Node in the SOAP XMPP Binding:
+| Feature | +Value / Description | +
|---|---|
| State Name | +Init | +
| Description | +Receive request message | +
| Pre-Conditions | +None | +
| Actions | +Receive and validate inbound XMPP &IQ; or &MESSAGE; request stanza; instantiate or replace the reqresp:ImmediateSender property with an XMPP address (JID) that denotes the sender of the XMPP request; instantiate or replace the reqresp:InboundMessage property with an infoset representation of the included SOAP envelope | +
| Post-Conditions | +Control of the inbound transport message exchange context is transferred from the binding to the local SOAP node | +
| Transitions | +See table "Init: Transitions (Responding)" | +
The following table summarizes the transitions from the "Init" state of the Responding SOAP Node:
+| Event / Condition | +Next State | +Failure Reason | +
|---|---|---|
| Received Well-Formed Request Message | +Receiving | +N/A | +
| Reception Failure (various XMPP errors) | +Fail | +fail:ReceptionFailure | +
| Malformed Response Message (invalid SOAP envelope) | +Fail | +fail:BadRequestMessage | +
For a listing of relevant XMPP error conditions, refer to Section 9.3.3 of RFC 3920.
+The following table formally describes the "Receiving" state of the Responding SOAP Node in the SOAP XMPP Binding:
+| Feature | +Value / Description | +
|---|---|
| State Name | +Receiving | +
| Description | +Waiting for local SOAP node to return response message | +
| Pre-Conditions | +Completion of Init state | +
| Actions | +None | +
| Post-Conditions | +Control of the outbound transport message exchange context is transferred from the local SOAP node to the binding | +
| Transitions | +See table "Receiving: Transitions" | +
The following table summarizes the transitions from the "Receiving" state of the Responding SOAP Node:
+| Event / Condition | +Next State | +Failure Reason | +
|---|---|---|
| Response Message Becomes Available | +Receiving+Sending | +N/A | +
The following table formally describes the "Receiving+Sending" state of the Responding SOAP Node in the SOAP XMPP Binding:
+| Feature | +Value / Description | +
|---|---|
| State Name | +Receiving+Sending | +
| Description | +Waiting for local SOAP node to return response message | +
| Pre-Conditions | +Completion of Receiving state | +
| Actions | +Formulate and send XMPP &IQ; or &MESSAGE; response stanza (see table "Receiving+Sending: XMPP Fields") | +
| Post-Conditions | +None | +
| Transitions | +See table "Receiving+Sending: Transitions" | +
In the "Receiving+Sending" state, an XMPP stanza (either &IQ; or &MESSAGE;) is formulated by the Responding SOAP Node according to the following table:
+| Field | +Value / Description | +
|---|---|
| XMPP Method | +For XMPP &IQ; stanzas, the value of the XMPP 'type' attribute MUST be "result"; does not apply to XMPP &MESSAGE; stanzas | +
| Originator | +The XMPP address (JID) carried in the reqresp:ImmediateSender property of the message exchange context is encapsulated as the value of the XMPP 'from' attribute; normally set by the XMPP server to which the originator connects | +
| Destination | +The XMPP address (JID) carried in the reqresp:ImmediateDestination property of the message exchange context is encapsulated as the value of the XMPP 'to' attribute | +
| Correlation Request Message ID | +As required for XMPP &IQ; stanzas in general and required for XMPP &MESSAGE; stanzas sent in the context of the SOAP XMPP Binding, the correlation request message ID is copied from the ID of the request and encapsulated as the value of the XMPP 'id' attribute | +
| XMPP Stanza Contents | +The XML of the SOAP envelope carried in the reqresp:OutboundMessage property of the transport message exchange context is encapsulated as a direct child element of the XMPP &IQ; or &MESSAGE; stanza | +
The following table summarizes the transitions from the "Receiving+Sending" state of the Responding SOAP Node:
+| Event / Condition | +Next State | +Failure Reason | +
|---|---|---|
| Response Message Successfully Sent | +Success | +N/A | +
| Failure to Send Response Message | +Fail | +fail:TransmissionFailure | +
A given instance of a request-response transport message exchange terminates when the state "Success" or "Fail" is reached; from the perspective of the Responding SOAP Node, the transport message exchange has completed.
+The main body of text that addresses the requirements of the W3C with regard to SOAP bindings is provided in the SOAP XMPP Binding section of this document. The current section addresses only the topic of organizational interaction between the W3C and the &JSF; regarding the SOAP XMPP Binding.
+As was done with &jep0071;, the SOAP XMPP Binding defined herein has been reviewed informally by one or more appropriate experts from the W3C before the &COUNCIL; advanced it to a status of Draft within the JSF's standards process. Before this specification proceeds to a status of Final within the JSF's standards process, it should undergo a formal review through communication with the W3C's XML Protocol Working Group. To that end, revised versions of this specification will be announced on the W3C's public xml-dist-app@w3.org mailing list.
+This specification addresses SOAP 1.2 only. This specification may be superseded or supplemented in the future by a Jabber Enhancement Proposal that defines methods for encapsulating content defined by future versions of SOAP as published by the W3C.
+Per RFC 3920, XMPP supports XML 1.0 only. If future versions of XMPP support XML 1.1 or subsequent versions, this specification may be modified to address handling of SOAP messages that are encoded in versions other than XML 1.0.
+SOAP provides its own encoding scheme for errors due to message processing or application execution, and it uses SOAP envelopes for reporting. In the SOAP HTTP Binding, these errors are mapped to corresponding HTTP status codes. In the SOAP XMPP Binding, they are mapped to the catch-all XMPP error of &undefined; along with application-specific error condition elements qualified by the 'http://jabber.org/protocol/soap#fault' namespace (this is consistent with Section 9.3.3 of RFC 3920, see also &jep0086;). The element names of these application-specific error conditions map directly to the SOAP fault codes specified in Section 5.4.6 of SOAP Version 1.2 Part 1.
+The following table provides a mapping between SOAP, HTTP, and application-specific XMPP errors.
+| SOAP Fault | +HTTP Status Code | +XMPP Application Error | +
|---|---|---|
| env:DataEncodingUnknown | +500 | +<DataEncodingUnknown/> | +
| env:MustUnderstand | +500 | +<MustUnderstand/> | +
| env:Receiver | +500 | +<Receiver/> | +
| env:Sender | +400 | +<Sender/> | +
| env:VersionMismatch | +500 | +<VersionMismatch/> | +
Note: When errors are due to the XMPP transport protocol alone and not to the application layer defined by SOAP, errors MUST be reported with standard XMPP error codes only instead of the XMPP &undefined; condition plus application-specific condition.
+Because XMPP does not require the parsing of arbitrary and complete XML documents and does not require implementations to support the full XML specification, transported SOAP envelopes MUST comply with the XML restrictions specified in Section 11 ("XML Usage Within XMPP") of RFC 3920. In particular, all envelope elements MUST be properly namespaced (SOAP allows elements within the default namespace, but they are deprecated since SOAP 1.2).
+SOAP envelopes may contain arbitrary data encoded in valid XML as well as byte arrays encoded with SOAP-specific elements. The SOAP specification recommends to encode byte arrays in Base 64 (see &rfc3548;), with the result that envelopes with binary data can be transported within regular XMPP stanzas. All the remaining PCDATA MUST be encoded as UTF-8 in order to match the XML stream encoding.
+SOAP has been supplemented by several support protocols that help ensure message integrity and confidentiality (WS-Security
No interaction with &IANA; is required by this document.
+The ®ISTRAR; includes 'http://jabber.org/protocol/soap' and 'http://jabber.org/protocol/soap#fault' in its registry of protocol namespaces.
+The Jabber Registrar includes a Service Discovery type of "soap" within the "automation" category.
+The registry submission is as follows:
+
+ automation
+
+ soap
+ A SOAP receiver (either intermediate or ultimate).
+ JEP-0072
+
+
+ ]]>
+ Because the SOAP envelope is included as a first-level child element of an &IQ; or &MESSAGE; stanza via standard XMPP extension mechanisms, an XML schema is not required for this document. An XML schema for the SOAP envelope element is provided at <http://www.w3.org/2003/05/soap-envelope/>.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0072: http://www.jabber.org/jeps/jep-0072.html
+
+
+
+
+
+
+
+
+
+ ]]>
+ This section is non-normative.
+An XMPP entity that supports the SOAP XMPP binding could function as a "SOAP intermediary" that hands a SOAP message off to some other deployment for subsequent processing (HTTP, email, a specialized enterprise messaging platform, etc.) rather than functioning as the "ultimate SOAP receiver" for the message (as these terms are defined in Section 1.5.3 of SOAP Version 1.2 Part 1). If the intended recipient functions as a SOAP intermediary, implementations should be aware that subsequent processing may alter the representation of SOAP messages.
+As an example, consider a component that functions as a gateway between XMPP-based and HTTP-based web services. Its purpose might be to mix HTTP and XMPP for web services and to invoke any web services already accessible through HTTP from XMPP clients.
+WS-Routing, whose aim is to dynamically compose SOAP message paths and processing sequences, can be used in order to reference web services outside of an XMPP network from within it. WS-Routing extends SOAP Envelope Headers with the <path/> element, which specifies the following for the message: the sender's URL (<from/>), the final destination's URL (<to/>), a forward (<forward/>) path with an arbitrary number of intermediaries (<via/>), and an optional return path (<reverse/>). Each intermediary MUST process the <path/> header and update it accordingly to the already performed path; moreover it MAY process the Body of the message.
+A SOAP message originated by an XMPP entity ('xmpp:orig@A.example.com/soap'), and directed to an end point accessible through HTTP ('http://C.example.net/some/endpoint'), could be built using a <path/> header having:
+-
+
- the <to/> element set to 'http://C.example.net/some/endpoint' +
- one <via/> element set to an HTTP<->XMPP gateway, such as 'xmpp:soapgw@B.example.org/soap', in the forward path +
- an appropriate SOAP action in the <action> element of the <path/> header (this may be required by the HTTP end point) +
- a blank return path +
Then the SOAP message can be sent within an &IQ; stanza to the gateway's JID. The gateway processes the SOAP headers, and looking through the headers it discovers that it must act only as intermediary. From the <to/> element it reads the URL of the final end point, extracts the SOAP action, changes the path removing the step already performed, and issues an HTTP request with the modified envelope and appropriate HTTP headers. Once it has received a response, it prepares a new &IQ; stanza of type "result" or "error" and sends its reply to the original requester. The following example shows the possible SOAP headers of the described process.
+Generic XMPP routers that conform to RFC 3920 may also "store and forward" Jabber messages. This feature is usually called "offline message handling": the router makes a decision as to whether to deliver the message to the local intended recipient based on the recipient's presence, and if the recipient is offline when the router processes the message then it may store the message for delivery when the recipient next comes online (rather than returning an error to the sender). Although it is possible to write an XMPP router that directly supports the SOAP XMPP binding and implements the SOAP processing model, generic XMPP routers do not contain such support. Accordingly, generic XMPP routers will not forward an XMPP message to an alternate SOAP transport such as HTTP or SMTP, or provide other functions of a SOAP intermediary or ultimate receiver. When a generic XMPP router delivers a message to the intended recipient (whether immediately or as delayed in "offline storage") and the intended recipient supports the SOAP XMPP binding, SOAP processing is performed; such an intended recipient MAY act either as a SOAP intermediary or as an ultimate SOAP receiver.
+With regarding to exchange of associated data, an XMPP entity that functions as a gateway to other SOAP bindings it SHOULD use W3C-recommended protocols for transporting SOAP attachments over non-XMPP SOAP bindings (e.g., HTTP and SMTP) when communicating with non-XMPP entities.
+Many thanks to Noah Mendelsohn for his assistance regarding SOAP binding definitions and conformance issues. Thanks also to Michael Mahan and Rich Salz for their comments.
+Some text in the SOAP XMPP Binding section of this document is closely modelled on Section 7 of SOAP Version 1.2 Part 2 and on SOAP Version 1.2 Email Binding.
+Given the large number of Jabber/XMPP protocols,
+
Defining a protocol suite provides a high-level "bucket" into which we can place specific functionality areas for development and compliance testing. A baseline is provided by RFCs 3920 and 3921, which define XML streams, JID processing, channel encryption, authentication, the three primary XML stanza types (&MESSAGE;, &PRESENCE;, and &IQ;), namespace handling, presence subscriptions, roster management, and privacy lists (whitelisting/blacklisting). However, basic Jabber instant messaging and presence applications should support several additional protocols that were not included in the XMPP specifications for either of the following reasons:
+-
+
- They were not required to meet the requirements of &rfc2779; (e.g, service discovery) +
- They were and remain in common use within the Jabber community but did not meet the more stringent requirements of the IETF (e.g., old-style, non-SASL authentication) +
The Basic IM Protocol Suite does not include more advanced IM functionality, such as groupchat or HTML message formatting; see &jep0117; for such features.
+The software developed in the Jabber community is built on the foundation of XML streams, a consistent addressing scheme (JIDs), channel encryption, authentication of an entity (client or server) with a server, three core data elements (&MESSAGE;, &PRESENCE;, and &IQ;), and proper handling of XML namespaces. These foundational building blocks have been formalized within RFC 3920, support for which is REQUIRED by this protocol suite. However, XMPP Core is not fully congruent with the core of what has traditionally been known as "Jabber", and this divergence needs to be captured in the Basic IM Protocol Suite. In particular, the following are REQUIRED herein in order to ensure compatibility with the large deployed base of older Jabber software:
+
-
+
- Support for &jep0078; as a fallback method for authentication. +
- Support for the error 'code' attribute specified in &jep0086;. +
RFC 3920 does not define everything that is normally expected of even a minimal instant messaging and presence application (in effect, it defines the transport layer rather than the IM and presence application layer). Much of this IM and presence functionality is defined in RFC 3921 in order to meet the requirements of RFC 2779. In particular, RFC 3921 defines roster management, presence subscriptions, privacy lists (whitelisting/blacklisting), and routing and delivery guidelines for clients and servers.
+However, Jabber instant messaging and presence applications have traditionally also included the ability to discover information about other entities on the network, and to reply to queries for information. This behavior is extremely helpful because it ensures that entities on the network can determine each other's capabilities and thus understand how to communicate together. (The original such protocol was &jep0094;, but that protocol has been superseded by &jep0030;.) Support for Service Discovery is therefore REQUIRED by this protocol suite, as well.
+Traditionally, Jabber servers (and some services) have also offered the ability for clients to register accounts "in-band" (i.e., over Jabber/XMPP) in order to bootstrap participation on the network; this protocol is defined in &jep0077; and support for it is REQUIRED for servers but RECOMMENDED for clients (however, any given server deployment MAY disable in-band registration as a matter of service provisioning).
+Thus we define the Basic IM Protocol Suite as follows:
+| Specification | +Requirement Level | +
|---|---|
| RFC 3920: XMPP Core | +REQUIRED | +
| RFC 3921: XMPP IM | +REQUIRED | +
| JEP-0078: Non-SASL Authentication | +REQUIRED | +
| JEP-0086: Error Condition Mappings | +REQUIRED for servers; RECOMMENDED for clients | +
| JEP-0030: Service Discovery | +REQUIRED | +
| JEP-0077: In-Band Registration | +REQUIRED for servers; RECOMMENDED for clients | +
RFC 3920 requires support for SASL and TLS as must-implement protocols, and that support is not modified herein. Refer to JEP-0078: Non-SASL Authentication for an explanation of the older authentication method still in use by various existing client and server implementations and deployments, as well as the proper order of precedence between SASL authentication (RFC 3920) and non-SASL authentication (JEP-0078).
+This JEP requires no interaction with &IANA;.
+No namespaces or parameters need to be registered with the ®ISTRAR; as a result of this JEP.
+A Jabber travels further into the Jabber-as-Middleware world, it needs a protocol to determine "who can do what to whom". This proposal defines a protocol that enables any Jabber entity to determine the permissions of another Jabber entity, whether the context is a user JID querying a component for access, a client-to-client conversation, or a component asking another component about a request from a user.
+All access control lists (ACLs) boil down to three aspects: Actor, Operation, and Target/Sink. With this in mind it becomes almost trivial to implement the basic query/response mechanism.
+Here we have the inventory.capulet.com component querying the security component as to whether juliet@ may obtain the requested poison.
+Unfortunately, the response is in the affirmative and the romantic tragedy follows.
+The <acl> element provides the container for the query. It MUST have the three attributes: actor, oper, and target.
+The actor attribute is set to the Jabber ID which is attempting to perform an operation. This need not be the JID sending the acl, although it may be. Remember this is to allow for the question, "Can X do Y to Z?", which is a question anyone can ask.
+The oper attribute is application-specific and refers to the operation for which a permission check is required (e.g., read/write operations). This also defines the scope of the ACL check, so the implementation is responsible for interpreting the actor and target values based on the value of the 'oper' attribute.
+The target is the object which the actor is trying to perform the operation on. This MUST be a node queryable via &jep0030;.
+Requests MUST be in the form of an empty <acl/> element with ALL the attributes specified. If not all attributes are specified, the request is incomplete and ambiguities arise; therefore the entity receving the request MUST return a "bad request" error to the sender.
+Responses MUST be in one of three forms: allowed, denied, error.
+The response is inserted into the <acl/> as a child element. If the response is allowed, then <allowed/> is inserted. If the JID is denied then <denied/> is returned. If there is inadequate information then <error/> is used following the standard Jabber error scheme.
+To obtain a list of acl operations that a jid supports, you must send an empty <query/>
+The to jid must then respond with a list of operations, if the jid supports SAC.
+To follow.
+To follow.
+This JEP requires no interaction with &IANA;.
+As a result of this JEP, the ®ISTRAR; will need to register the 'http://jabber.org/protocol/sac' namespace.
+-
+
- Add disco integration section. +
- Fill out error codes. +
- Add DTD and Schema. +
- Allow for query of all allowable operations for actor in relation to a target. +
- Investigate possible integration with pubsub. +
This document defines the Jabber Object Access Protocol (JOAP) + as an extension to the Jabber protocol. It outlines the + addressing scheme and IQ stanzas that comprise the protocol as + well as the data types that the protocol models. Example + applications are discussed, as well as security + considerations.
+Jabber has a number of attractive features that give it an + advantage over existing frameworks for building multi-tier + applications, such as the Simple Object Access Protocol (SOAP) + or Java 2, Enterprise Edition (J2EE). Among these are:
+-
+
- Built-in authentication. All clients in the + Jabber network must be authenticated with their server before + sending messages to other Jabber entities. Inter-server + communication requires additional authentication, in the form + of dialback connections or other trust mechanisms. This + ensures that, when a message is delivered to a JOAP object + server, there is little doubt as to the authenticity of its + originator. +
- Global namespace. Jabber allows namespacing + of addresses according to domain names. This allows objects to + be accessed globally, according to authorization rules. +
- An asynchronous messaging model. Jabber is + built on a store-and-forward mechanism that allows a single + client to send messages to multiple servers concurrently. Of + course, synchronous messaging can be simulated on the client + side. +
- Cross-enterprise messaging. Jabber is + designed to allow cross-enterprise messaging. Using Jabber for + multitier applications makes development of cross-enterprise + systems as easy as intra-enterprise development. +
- Message routing. The architecture of Jabber + is based on clients that connect to a local server, and then + can send messages through that server to other clients, + servers, or components. Topographically, this contrasts well + with the one-to-one connections required with, for example, + HTTP. +
- Factoring network connections out of + scalability. Because messages in Jabber are routed, + components need to maintain only one connection -- to their + upstream Jabber server. This removes the number of network + connections from the scalability equation for object + servers. +
- Language independence. Jabber protocol + implementations exist for Java, C, and C++ as well as a number + of scripting languages such as Perl and Python. +
- Platform independence. The Jabber protocol + is implemented on most major modern platforms. +
For existing Jabber development efforts, there are significant + advantages to building applications within a JOAP + framework. It should go without saying that, for developers creating + business applications on top of Jabber, a uniform object access + protocol provides significant advantage for cross-product + integration.
+In addition, implementers of special-purpose components, such as + multi-user chat servers or whiteboarding components, can use an + object-server interface to allow fine-grained control of the + implementations, especially where such control is not specified + by the applicable Jabber protocol.
+JOAP has the following design goals:
+-
+
- Create a protocol for client programs to access object + server components. +
- Create a model for addressing object servers, classes, and + instances. +
- Define a language for manipulating data. +
- Define a language for describing data structures. +
- Maintain compatibility with &jep0009;. +
- Make classes and instances directly addressable. +
- Allow human- and programming-language independence. +
- Allow easy dynamic mapping of JOAP classes to local classes + in Perl, Python, and other dynamic languages. +
The following are non-goals:
+-
+
- Enable object-oriented access to all parts of the Jabber + network (e.g., clients, other components). +
- Define a language for creating or altering classes on an + object server. +
- Define a language for describing or defining the + authorization of given users for given objects. +
- Define a programming interface between object servers and + classes in those servers (like Enterprise Java Beans). +
The JOAP interface is made up of three key parts:
+-
+
- A scheme for defining the addresses of object servers, + classes, and instances (collectively known as + "objects"). +
- A set of message stanzas in the jabber:iq:joap + namespace for manipulating data in object servers, classes, + and instances. The stanzas allow client programs to analyze + the structure of objects, to read object attributes, to edit + object attributes, to add new instances, to delete instances, + and to search classes. +
- An application of JEP-0009 for calling methods on + objects. +
This section describes the various entities in the JOAP + universe. Some entities are directly addressable with Jabber IDs + (JIDs), as described below. Others are not considered outside of + their enclosing entities.
+An object server component is a Jabber component that + provides object services. It is addressed like any other + Jabber component, i.e., with a DNS hostname or + pseudo-hostname. Some examples would be:
+-
+
- payroll.example.com - A payroll application + server. +
- jukebox.example.com - An MP3 jukebox server. +
An object server has zero or more attributes, methods, and + classes.
+A class is a category of object instances. It defines the + structure and interface of these instances. Each class is + addressed using the class name as the node identifier, and the + object server as the domain identifier. Class names must + conform to the node identifier restrictions defined for + XMPP. Class names must also be unique, regardless of case, + within an object server.
+For example:
+-
+
- Employee@payroll.example.com - An employee class + at the payroll.example.com server. +
- Song@jukebox.example.net - A song class on the + jukebox server. +
- Board@circuit-design.example.com - A class for + circuit boards. +
- Board@surf-shop.example.net - A class for + surfboards -- distinct from above class! +
Beside uniqueness and XMPP compliance, no further requirements are + made on class names. However, good design suggests mnemonic names.
+Classes define the attributes and methods of their instances. In + addition, they can have attributes and methods of their own. Finally, + classes can have superclasses, which indicate an inheritance structure + as well as implementation of a defined interface.
+JOAP allows for no relative addressing of classes. Classes + are always referred to by their full address (node identifier + plus domain identifier).
+An instance is a collection of data with identity, state, and + behavior. Each instance is a member of a class, which defines the + attributes (data) and methods (behavior) of the instance + itself.
+An instance is addressed using the node plus server that identifies + its class, as well as a unique string that occupies the resource + identifier section of the Jabber ID. The resource is only unique over + the space of the corresponding class. Some example instance addresses:
+-
+
- Room@hotel.example.com/103 - Room 103 in the + Example Hotel. +
- Element@periodic-table.example.net/103 - Element + 103 (rutherfordium) in the periodic table. +
- Employee@payroll.example.com/JohnSmith - An + employee named "John Smith". +
- Customer@videorental.example.net/JohnSmith - A + customer named "John Smith" (not necessarily the + same person as the above employee!). +
Besides uniqueness within a class, and compliance with the + rules for resource identifiers in the XMPP standard, there are + no further requirements on instance identifiers in JOAP. In + particular, the instance identifier is opaque -- that is, no + further information about the state of the object can or + should be discerned from the identifier. What visible part of + the instance, if any, makes up the unique resource identifier + is implementation dependent.
+That said, it is recommended that the instance identifier be + persistent through the life of the instance. In addition, using + mnemonic identifiers can greatly enhance the usability of JOAP + objects.
+As with other resource identifiers, instance identifiers are + case-sensitive.
+The instance identifier roughly corresponds to a primary key in a + relational database, and for object servers that provide access to + relational databases, it is recommended to use the primary key of a + table as the instance identifier. For tables with a compound key, a + comma (',') dash ('-'), or other non-alphanumeric character can be + used to separate parts of the key for better readability. For + example:
+-
+
- Date@calendar.example.net/2003-01-26 -- The date + January 26th, 2003. +
- City@canada.example.com/Montréal,QC -- The city + of Montréal, in the province of Québec. +
JOAP allows for no relative addressing of + instances. Instances are always referred to using their full + address (node identifier plus domain identifier plus resource + identifier).
+An attribute is a unit of state that makes up part of an object + server, instance, or class. Each attribute has a name and a + type.
+Attribute names must be strings of characters containing only
+ the characters [a-zA-Z0-9_]. The first character must be an
+ underscore or alphabetic character.
Attributes cannot be addressed individually. Attributes are + manipulated by sending JOAP messages to the object that owns + them.
+A method is a unit of behavior that makes up part of an + object. Methods in JOAP are compatible with &xmlrpc;, as + specified in &jep0009;. In particular, methods have a name, a + return type, and 0 or more parameters, each of which has a + type.
+The one exception to XML-RPC compatibility is that method
+ names for JOAP are restricted to the characters
+ [a-zA-z0-9_].
Methods cannot be directly addressed using JOAP. Methods are + described and executed by sending messages to the object + server, class, or instance that owns them.
+The range of JOAP data types is borrowed directly from + XML-RPC.
+The scalar types include the following:
+-
+
- int or i4: a 32-bit + signed integer +
- boolean: a one-digit integer representing + "true" (1) or "false" (0) +
- string: a string of characters +
- double: double-precision signed + floating-point number +
- datetime.iso8601: a date value, in ISO + 8601 format +
- base64: binary data, base64-encoded for + transmission +
Instance addresses are a special type of string used for + referring to instance objects. They can be passed as + parameters to methods, or set as attribute values.
+If a value can contain an object instance, its type is the + address of a class. The address of any object instance that is + an instance of that class, or any of its subclasses, can be + used in that value.
+For example, if Boxcar@trainset.example.com is a + subclass of Car@trainset.example.com, then + Boxcar@trainset.example.com/569 can be used as a + method parameter, or set as an attribute, where + Car@trainset.example.com is the defined type.
+Because addresses are used for instance values, all methods + involving instances are implicitly pass-by-reference. If a + pass-by-value functionality is needed, a struct (see below) + should be used instead.
+Note that attribute and method param types can use classes + and instances from other object servers (that is, with + different domain identifiers). For instance, an + Employee@payroll.example.com class could have an + attribute of type Job@hr.example.com.
+There are two compound types defined in XML-RPC.
+An array is an ordered list of values. An array + can contain values of any type, including other compound + types.
+In JOAP, as with XML-RPC, it is not possible to address, + set, or delete elements of an array. To set values in an + array, the entire new array must be specified.
+A struct is a set of name-value pairs organized into + a logical grouping. A struct can contain values of any type, + including other compound types.
+In JOAP, as with XML-RPC, it is not possible to address, + set, or delete elements of a struct. To set values in an + struct, the entire new struct must be specified.
+Structs are useful mainly for groupings of data that do not + have independent identity or behavior. Where an object + needs identity or behavior, an instance should be used + instead of a struct.
+Types are specified by a string name of the type. This can be
+ one of the XML-RPC types described above, or a class
+ address.
This section defines the Jabber stanzas that make up the JOAP + protocol.
+Each stanza is an information query (IQ). Except for method + calls, the stanzas are all in the 'jabber:iq:joap' namespace. Each + of the following sections describes a stanza in that namespace, + herein called a "verb". The verbs allow basic access + to object servers, classes, and instances.
+Not all verbs can be sent to all JOAP entities. The appropriate JOAP + entity a verb should be addressed to is noted under the description of + the verb.
+The <describe> verb requests the interface -- that is, methods, + attributes, and classes -- of a given object server or class. The IQ + type is "get".
+The <describe> verb is useful for creating wrapper + classes in JOAP clients, either at runtime or at compile + time. It can also be used for object browsers, or for client + programs to ascertain that the interface they assume for an + object is still valid.
+<describe> verbs can be sent to object servers, classes, and + instances. Each will return different data.
+-
+
- Object servers return zero or more descriptive texts, + zero or more attribute definitions, zero or more method + definitions, zero or more class names, and a + timestamp. +
- Classes return zero or more descriptive texts, zero or + more attribute definitions, zero or more method + definitions, and a timestamp. +
- Instances return the exact results of sending the + <describe> method to their class. This is for convenience + only; it is preferable to send <describe> to the class + directly. +
Each object description can contain one or more strings of + descriptive text. This is to indicate the + purpose and usage of the object in human-readable form.
+Multiple descriptions are allowed in the hope that they + will be used to describe the attribute in multiple + languages (differentiated using the xml:lang + attribute).
+Attribute definitions have the following parts:
+-
+
- A name, which is a legal attribute name as described + above. +
- A type, which is a legal JOAP type as described + above. +
- A flag indicating if the attribute is an attribute of the + class itself, or of individual instances. +
- A flag indicating if the attribute is writable. +
- A flag indicating if the attribute is required. +
- One or more strings of descriptive text, to indicate the + purpose and usage of this attribute. Multiple + descriptions are allowed in the hope that they will be + used to describe the attribute in multiple languages + (differentiated using the 'xml:lang' attribute). +
The attribute definitions returned to a client should + include only attributes the user is authorized to access.
+Method definitions have the following parts:
+-
+
- A name, which is a legal method name as described + above. +
- A return type, which is a legal JOAP type as described + above. +
- A flag indicating if the method is a method of the class + itself, or of individual instances. +
- Zero or more parameters, each of which has a name, a + type, and one or more strings of descriptive text. +
- One or more strings of descriptive text, indicating the + use and behavior of this method. +
The method definitions returned to a client should + include only methods the user is authorized to access.
+Classes, in superclass definitions and object server + interfaces, are always referred to by their full + address.
+The timestamp is a date-time value in ISO 8601 format, + UTC. The timestamp indicates the last time an interface was + changed, if that information is available.
+The main point of describing the superclasses a class has + is to allow clients to make typing distinctions: that is, to + determine if a class presents a given interface, or may be + provided as a parameter or attribute in another JOAP + call.
+The list of superclasses given in a class description is + flat, not hierarchical. No provision is made to + indicate which of a class's superclasses are superclasses of + each other, nor is there any implied precedence order in the + order of the classes in the returned description.
+In addition, no provision is made to define which + superclass actually implements any methods or attributes + defined.
+When a class receives a <describe> verb, it must
+ return all its superclasses, including multiple
+ ancestors. It must as well return all the attributes and
+ methods that it responds to, including those defined in
+ its superclasses. This is called a "flattened"
+ description of the class.
The following examples illustrate the use of the <describe>
+ verb.
To describe a server, the JOAP client sends this + stanza.
+The object server returns this response:
+To describe the Car@trainset.example.com class, + the JOAP client sends this stanza to the class for + boxcars.
+The class returns this stanza to the JOAP client.
+To describe an instance, the JOAP client sends this stanza + to a particular track segment.
+The instance returns this stanza to the JOAP client.
+The <read> verb allows clients to retrieve the values
+ of attributes of an object server, class, or instance. The
+ client can specify which attributes to return; if no
+ attributes are specified, then all attributes are
+ returned.
The <read> verb uses the "get" IQ type.
+A timestamp, in ISO 8601 format, UTC, can be added to the + results of a <read>. The timestamp indicates the last + time any of an object's attribute values have changed (not + just the requested ones). The timestamp can be used, for + example, to implement object caching on the client side.
+The following are some common error codes may be generated + in response to a <read> verb.
+-
+
- 404 (Not Found): The object addressed + does not exists. +
- 403 (Forbidden): The user is not + authorized to read attributes of this object, or not + authorized to read the specified attributes of this + object. +
- 406 (Not Acceptable): The client sent + an <read> verb specifying attributes that are not + defined for the class. +
This section gives some examples of using the <read> + verb.
+A client would send the following stanza to an instance to + read its attributes:
+In return, the instance would send this stanza to the + client:
+To read only specified attributes of an instance, the + client would send this stanza:
+In return, the instance would send this stanza to the + client:
+The <add> verb is used to create a new instance of a + JOAP class. The verb is sent to the JOAP class, which returns + the address of the newly-created instance.
+Within each <add> verb the client must include + attribute values for each required, writable attribute of the + class.
+The IQ is of type "set".
+The following are some common error codes may be generated + in response to an <add> verb.
+-
+
- 404 (Not Found): The class for which an + instance is to be instantiated does not exists. +
- 403 (Forbidden): The user is not + authorized to instantiate an instance of this class. +
- 405 (Not Allowed): The client sent an + <add> verb to something that isn't a class. +
- 406 (Not Acceptable): The client sent an + <add> verb containing attributes that are not + writable, or without all required, writable attributes, + or with attributes that are not defined for the class, or + with attribute values that are of the wrong type. +
To create a new PassengerCar, the client would send the + following stanza to the PassengerCar class:
+The class would return the following response:
+Note that the class created a new instance identifier, 866, + for the new instance. Further communications from the client + would use the full instance address returned.
+The <edit> verb is used to update the attributes of an + object. The name and new value of each attribute that is to be + updated is listed in the <edit> verb.
+The IQ is of type "set".
+Leaving a given attribute out of an <edit> verb does + not indicate that the attribute should be set to an undefined + or default value. The new values of attributes that are left + out is implementation-dependent; in general, though, they + should remain unchanged, if possible.
+If the results of an <edit> verb have content, it
+ will contain the new address of the instance that was
+ updated. The new address should be used henceforth by the
+ client.
The following error codes may be generated in response to a + <edit> verb.
+-
+
- 404 (Not Found): The object to be + edited does not exists. +
- 403 (Forbidden): The user is not + authorized to edit this object, or to change one of the + attributes specified in the <edit> request. +
- 406 (Not Acceptable): The client sent + an <edit> verb containing attributes that are not + defined for the class, or with attribute values that are + of the wrong type, or with attribute values that are + outside the range for the attribute. +
To change the number of passengers in a PassengerCar, the + client would send the following stanza to the instance:
+The client would return the following stanza:
+If a client wanted to change the name of a Building, it + would send the following stanza to the instance:
+The results would be as follows:
+Note that the instance indentifier, and thus the instance + address, of the instance has changed. The from part + of the IQ, however, contains the old address.
+The <delete> verb is used to delete an instance. The IQ + is of type "set". The <delete> stanza has no + sub-elements.
+Only instances can be deleted. Classes and object servers + cannot be deleted. After an instance is deleted, it is no + longer addressable.
+A given user may not be able to delete a particular + instance.
+The following error codes may be generated in response to a + <delete> verb.
+-
+
- 404 (Not Found): The instance to be + deleted does not exists. +
- 403 (Forbidden): The user is not + authorized to delete this instance. +
- 405 (Not Allowed): The client sent a + <delete> verb to an object server or class. +
To delete an instance, a client would send the following + stanza:
+The instance would return this stanza:
+If the user is not authorized to delete the instance, it + would return this error:
+The <search> verb allows rudimentary searching and + listing of instances in a class. The IQ is of type + "get".
+The client sends a <search> verb to the class, + specifying the attributes that are search criteria and values + to search for. The class returns a list of the addresses of + matching instances.
+Multiple attributes are logically AND'd; that + is, resulting instances must match all of the + attribute values.
+How attribute values are specified for matching depends on + the type of the attribute.
+-
+
- For numeric types (<int>, <double>), + <boolean>, and <dateTime.iso8601>, values match + if they are exactly equal. +
- For <string> types, a search value matches an + attribute value if it is a case-dependent substring of + that value. For example, "hat" will match + "hat", "that", and "real-time + chat server". +
- For the <base64> type, a search value matches + an attribute value if the base64-decoded value of the + search value is an 8-bit clean substring of the + base64-decoded attribute value. For example, + "aGF0Cg==" ("hat") will match + "cmVhbC10aW1lIGNoYXQK" ("real-time + chat"). +
- For instance addresses, a search value matches an + attribute value if they are exactly equal. +
- For <struct> types, a search value matches an + attribute value if each of its named members matches the + corresponding named members in the attribute value, and + has the same type. +
- For <array> types, a search value matches an + attribute value if each of its members matches the + corresponding members in the attribute value, in order, + and has the same type. +
Classes should return all instances of the class that are + on the same object server (that is, which have the same + domain identifier in their address) and that match the search + criteria. This includes instances of subclasses of the + class.
+Whether a class returns instances of subclasses that reside
+ on other object servers is implementation-dependent.
+
Classes cannot be searched on attributes that are defined + only in subclasses; for example, a search for the attribute + "contents" sent to the + Car@trainset.example.com class should result in a + 406 (Not Acceptable) error.
+The semantics of an empty <search> verb is to request + all instances of a class. This provides a listing + or browsing functionality.
+The following error codes may be generated in response to a + <search> verb.
+-
+
- 404 (Not Found): The class to be + searched does not exists. +
- 403 (Forbidden): The user is not + authorized to search this class. +
- 405 (Not Allowed): The client sent a + <search> verb to an object server or instance. +
- 406 (Not Acceptable): The client sent + an <search> verb containing attributes that are not + defined for the class, or with attribute values that are + of the wrong type. +
To search for Boxcar instances carrying coal, the client + would send the following stanza to the Boxcar class:
+The Boxcar class would return a list of all matching + instances:
+To get a list of all Building instances, the client would + send an empty <search> verb, as follows:
+The Building class would return the following stanza:
+Note that the class returns instances of subclasses, as + well as direct instances of the class.
+Method calls in JOAP are simply XML-RPC calls, as defined in
+ JEP-0009.
Method names must be the exact method name as returned by + <describe>. No class or instance identifier prefix (with + "." or ":") is used.
+Note, also, that the addressee of the method call, that is, + the object that defines the method, is not specified as a + parameter of the method, as it is in some programming + languages. The addressee of the method is implicit in the + address to which the method was sent.
+To start the event log on the train set server, the client + would send the following stanza:
+The object server would respond with the following results:
+To retrieve the next available Car tracking number, the + client would send the following stanza to the Car class:
+The class would respond with the following results:
+To make a Switch change to a different track segment, the + client would send the following stanza to the instance:
+The instance would respond with the following results:
+A simple application server can be provided using JOAP. This is merely + the degenerate case of an object server that provides only methods and + attributes, with no classes.
+A more complex example would be an interface to a relational database + server, such as Oracle, PostgreSQL, or mySQL. The object server would + represent a single database within the database server. Each table in + the database would be represented by a class with no class attributes + or methods. Each row in the database would be an instance of its + table's class, with attributes but no methods.
+A distributed n-tier application can be built fairly directly + with JOAP. N-tier applications are usually defined as having + three main segments:
+-
+
- A user-interface segment +
- A business-object segment, defining objects with business + rules encoded into their behavior +
- A data-storage segment, handling basic storage of + relatively unintelligent objects +
With JOAP, application developers can create the last two + segments with a JOAP interface. User-interface clients can use + JOAP to access and manipulate the business objects in a + business object server. In turn, the business objects can use + JOAP to manipulate underlying database objects in the data + storage layer (perhaps implemented using a relational database + interface, as defined above).
+Jabber protocols typically define a base set of functionality
+ for a component to provide. Implementers often want to provide
+ specialized, fine-grained control of the component that is not
+ part of the core functionality of a component. For example,
+ the implementer may wish to allow administrators to get
+ metrics on a component, enable or review logs, note error
+ situations, or configure the component remotely.
A component can provide an additional JOAP interface, along + with its regular protocol-specific interface, to enable this + kind of control functionality. Implementers can in this way + provide implementation-specific functionality in an open + way.
+For example, if conference.example.com is + a MUC component, control.conference.example.com might + be a JOAP component with access to the internal data + structures of the MUC component. A conference room addressed + in the MUC component as + ModelTrains@conference.example.com might be addressed + in the JOAP component as + Room@control.conference.example.com/ModelTrains.
+There are a number of existing distributed object systems, + such as SOAP, CORBA, distributed OLE, Enterprise Java Beans, + etc.
+It would be reasonable to create gateways for these object + systems or object servers implementing their protocols using + JOAP. JOAP could also be used to allow disparate object + systems to communicate through a common protocol.
+To follow.
+This section describes some security considerations for + implementers of JOAP.
+No provision is made for authentication of users to the + object server. Jabber users authenticate to a login server + before they are able to send any Jabber stanzas.
+Authorization for users to access and manipulate objects and + attributes in JOAP is fine-grained; object servers can return + error codes to indicate a lack of authorization for any given + attribute, object, or method.
+No provision is made to define a user's authorization for an + object, attribute, or method. Implicit authorization is + outlined with the results of the <describe> verb.
+-
+
- For attributes, if a user is unauthorized to <read> the + attribute, the object server should not return a definition of + the attribute in the <describe> results. +
- If a user is unauthorized to <edit> an attribute, the + object server should note that the the attribute is not + writable in the <describe> results. +
- If a user is unauthorized to execute a method, the object + server should not return a definition of the attribute in + the <describe> results. +
- For classes that the user is not allowed to access at all, + the object server should not return a reference to that + class in the <describe> results for the object + server. +
- For instances that the user is not allowed to access at + all, the object server should not return references to that + instance in <search> results. +
No provision is made in the JOAP protocol for providing + privacy and confidentiality in JOAP conversations. This is + left up to existing, more general Jabber protocols and + extensions.
+Confidentiality from external, non-Jabber observers can be + obtained using transport-layer security (TLS) in all legs of + the Jabber path -- from client to server to (potentially) + another server to the object server component.
+Maintaining confidentiality against observers in the Jabber + pathway -- for example, servers relaying JOAP stanzas -- + requires using end-to-end encryption.
+Due to the nature of the JOAP addressing scheme, however, + perfect confidentiality cannot be preserved. Even if the + contents of an IQ packet are encrypted, the address of the + object the packet is sent to -- e.g., + Tips@whistleblower.example.org/NuclearRegulatoryInfractions + -- will reveal some information about the JOAP + conversation which could be harmful to the user.
+This JEP requires no interaction with the IANA.
+This protocol defines one new namespace, 'jabber:iq:joap'.
+Experimental implementations of this protocol should use the + namespace 'http://www.jabber.org/jeps/jep-0075.html#0.3' to + avoid conflicts with future versions.
+-
+
- The presence mechanism provided by Jabber is currently not + integrated into the JOAP protocol. It would be relatively + easy to incorporate an observation mechanism, based on + presence, that would enable JOAP clients to request state + updates on JOAP instances. It is currently an open question + as to whether this would be genuinely useful, or merely a + "gee-whiz" add-on that needlessly complicates + implementation of the JOAP protocol. +
- More sophisticated distributed object protocol mechanisms, + such as transactions, are not addressed in this + specification. +
- The JOAP addressing mechanism restricts the type of Jabber + entity that can act as an object server. A Jabber instant + messaging client, for example, is normally addressed with + username and resource, such as + 'AJabberUser@example.com/Home'. This address has no place + to hang the class and instance identifiers to allow + JOAP interactions. +
- Additionally, the JOAP addressing mechanism inhibits + letting components that already use the node and resource + identifier parts of their addresses, such as multi-user + chat (MUC) services. This restriction can be worked around by + providing corresponding JOAP components for existing Jabber + components. +
- An additional type for object references may be called + for. +
- The addition of the widely used <nil> XML-RPC data + type may be called for. +
- Searching is fairly rudimentary; a full boolean logic (and, + or, not) may be necessary to provide rich searching. +
- There is no indication in class descriptions of the + inheritance hierarchy of the class, or which superclass's + implementation of a method the class may use. This is an + implementation decision, and it seems counterproductive to + force any given inheritance method on the implementer. +
- Some functionality will be expensive using JOAP. An example + might be finding all Cars in a Train and adding them to + another Train. In our example, this would require one IQ to + get the train's cars, and N many other IQs to update each + Car. A batching mechanism -- being able to send multiple + updates in one IQ message -- would make this somewhat less + chatty. However, this functionality may be better addressed by + a global Jabber batching mechanism, rather than + special-purpose batching just for JOAP. +
- A more appropriate term than <verb> may be necessary + to describe the different types of IQs that make up the JOAP + namespace. +
- The names of the verbs come from the so-called basic READ + data-manipulation functions: read, edit, add, delete. A more + SQL-oriented set of names might be SELECT, UPDATE, INSERT, + DELETE. A set of names from C-related object languages would + be get, set, new, destroy or delete. +
- No mechanism is provided to describe the range of an + attribute. For example, if an attribute can only be an integer + less than 10, or a string in the set {'open', 'closed'}, there + is no allowance for describing this in JOAP. +
- Currently, struct and array attributes and + parameters are described just with the "struct" and + "array" types, and no definition is given of their + parts' types, names, or semantics. It may be valuable to + expand JOAP type descriptions to also describe the members of + a struct or array. +
The following glossary collects some definitions of terms used + in this document.
+-
+
- Object services: Modelling an object or + collection of objects, and providing an interface to + manipulate those objects to other entities. +
- Object server: A Jabber component that + provides object services. +
- Class: A category of object + instances that defines their structure and interface. +
- Instance: A collection of + data with identity (address), state (attributes), and + behavior (methods). +
- Attribute: A unit of state that makes up + part of an object server, instance, or class. +
- Method: A unit of behavior. +
- Object: An object server, class, or + instance. +
- User: A person or process that accesses + object services through JOAP. +
- Client: The software or agent a user + employs to access object services through JOAP. +
- Instance address - The full JID of an + instance, e.g., + Train@trainset.example.com/OrangeBlossomSpecial. +
- Instance identifier - The resource + identifier part of an instance address. For example, in + Train@trainset.example.com/OrangeBlossomSpecial, the + instance identifier is OrangeBlossomSpecial. +
- Class address - The full JID of a class, + e.g., Switch@trainset.example.com. +
- Class identifier - The node identifier part + of a class address. For example, in + Switch@trainset.example.com, the class identifier is + Switch. +
- Authentication - The act of determining + that a user is who they say they are. In the Jabber world, this + is done at login time. +
- Authorization - The act of determining + whether a given user has the right to execute a particular + action. +
The following is an XML Schema for JOAP.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+ The following is a document-type description (DTD) for JOAP.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+ Because JOAP requires some significant examples to define the + protocol, an example domain was developed to provide + consistency. Readers familiar with UML may find the following diagram + useful to illustrate some of the fine points of JOAP listed + above.
+&rfc3514;, published just today (2003-04-01), defines a mechanism for specifying the "evil bit" in IPv4 in order to determine if a packet was sent with malicious intent. In Section 5 ("Related Work") of that RFC, reference is made to complementary mechanisms for other forms of evil such as IPv6 support and the application/evil MIME type. Because the &JSF; desires to maintain compliance with protocols developed by core Internet standards bodies, the current document defines a complementary mechanism for Jabber support of evil.
+There are three basic Jabber stanza types that may be sent within XML streams:
+-
+
- <message/> -- a "push" medium for sending information to other entities. +
- <presence/> -- a "broadcast" medium for publishing information to entities that have subscribed to an entity's availability status. +
- <iq/> -- a "request-response" medium for executing basic but structured transactions with other entities. +
Any one of the foregoing data elements can be used with malicious intent. Therefore a generalized mechanism is needed. Because XML namespaces are used within Jabber to properly scope data, this document proposes a new namespace ('http://jabber.org/protocol/evil') to implement the desired functionality.
+If a Jabber entity sends an evil message, it MUST include an appropriately namespaced extension in the message stanza:
+If a Jabber entity sends evil presence information, it MUST include an appropriately namespaced extension in the presence stanza:
+If a Jabber entity provides evil information in an IQ exchange, it MUST include an appropriately namespaced extension in the IQ stanza:
+Because the 'http://jabber.org/protocol/evil' namespace flags an XML stanza as malicious, it is critically important that an entity appropriately process an XML stanza that contains the evil extension. Mission-critical applications SHOULD ignore any stanzas tagged with the evil extension. Evil servers MAY pass through evil stanzas unmodified. Really evil servers MAY silently delete the evil extension. Jabber entities that are evil to the core SHOULD support channel-level evil as defined in RFC 3514, since this JEP defines per-stanza evil only.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; shall register the 'http://jabber.org/protocol/evil' namespace as a result of this JEP.
+The Jabber protocols have long included a method for in-band registration with instant messaging servers and associated services. This method makes use of the 'jabber:iq:register' namespace and has been documented variously in Internet-Drafts and elsewhere. Because in-band registration is not required by &rfc2779;, documentation of the 'jabber:iq:register' namespace was removed from &xmppim;. This JEP fills the void for canonical documentation.
+In-band registration must make it possible for an entity to register with a host, cancel an existing registration with a host, or change a password with a host. By "host" is meant either of the following:
+-
+
- an instant messaging server, such as described in XMPP IM and identified by the "server/im" &jep0030; category+type +
- an add-on service, such as a gateway (see &jep0100;) or a &jep0045; service +
If needed, extensibility with regard to information gathered should be done using &jep0004;.
+In order to determine which fields are required for registration with a host, an entity SHOULD first send an IQ get to the host. The entity SHOULD NOT attempt to guess at the required fields by first sending an IQ set, since the nature of the required data is subject to service provisioning.
+If the entity is not already registered and the host supports In-Band Registration, the host MUST inform the entity of the required registration fields. If the host does not support In-Band Registration, it MUST return a &unavailable; error. If the host is redirecting registration requests to some other medium (e.g., a website), it MAY return an <instructions/> element only, as shown in the Redirection section of this document.
+If the host determines (based on the 'from' address) that the entity is already registered, the IQ result that it sends in response to the IQ get MUST contain an empty <registered/> element (indicating that the entity is already registered), SHOULD contain the registration information currently on file for the entity (although the <password/> element MAY be empty), and SHOULD contain an <instructions/> element (whose XML character data MAY be modified to reflect the fact that the entity is currently registered).
+If the host is an instant messaging server, it SHOULD assume that the requesting entity is unregistered at this stage unless the entity has already authenticated (for details, see the Registration with a Server section below).
+If the entity is not already registered, the entity SHOULD provide the required information.
+Note: The requesting entity MUST provide information for all of the elements (other than <instructions/>) contained in the IQ result.
+Alternatively, registration may fail. Possible causes of failure include a username conflict (the desired username is already in use by another entity) and the fact that the requesting entity neglected to provide all of the required information.
+If the requesting entity does not provide all of the requested information during registration
If the host requires additional information above and beyond the data elements specified in the schema, it SHOULD use Data Forms as described in the Extensibility section of this document.
+The user then SHOULD return the form:
+Special care must be taken when an unregistered entity interacts with a server rather than a service. Normally, a server enables in-band registration so that entities can "bootstrap" their participation in the Jabber network; this bootstrapping happens when an unregistered and unauthenticated entity opens a TCP connection to a server and immediately completes the registration use case with the server, then authenticates using the newly-registered identity. As noted, when a server receives an IQ-get for registration information, it SHOULD assume that the requesting entity is unregistered unless the entity has already authenticated.
+Depending on local service provisioning, a server MAY return a ¬acceptable; stanza error if an unregistered entity attempts to register too many times before authenticating or if an entity attempts to register a second identity after successfully completing the registration use case; a server MAY also return a <not-authorized/> stream error if the unregistered entity waits too long before authenticating or attempts to complete a task other than authentication after successfully completing the registration use case.
+The 'jabber:iq:register' namespace also makes it possible for an entity to cancel a registration with a host by sending a <remove/> element in an IQ set. The host MUST determine the identity of the requesting entity based on the 'from' address of the IQ get.
+The host MUST perform the remove based on the 'from' address of the IQ set, usually matching based on bare JID (<user@domain>). If the entity cancels its registration with a server (not a service), the server SHOULD then return a <not-authorized/> stream error and terminate all active sessions for the entity. If the server is an instant messaging and presence server that conforms to &rfc3921;, the server SHOULD also cancel all existing presence subscriptions related to that entity (as stored in the entity's roster).
+Several error cases are possible:
+| Condition | Description |
|---|---|
| &badrequest; | The <remove/> element was not the only child element of the <query/> element. |
| &forbidden; | The sender does not have sufficient permissions to cancel the registration. |
| ¬allowed; | No sender is allowed to cancel registrations in-band. |
| ®istration; | The entity sending the remove request was not previously registered. |
| &unexpected; | The host is an instant messaging server and the IQ get does not contain a 'from' address because the entity is not registered with the server. |
A given deployment MAY choose to require additional information (such as the old password or previously-gathered personal information) before cancelling the registration. In order to do so, the server or service SHOULD return a Data Form in the error stanza:
+The user then SHOULD return the form:
+The 'jabber:iq:register' namespace enables a user to change his or her password with a server or service. Once registered, the user can change passwords by sending an XML stanza of the following form:
+Because the password change request contains the password in plain text, a client SHOULD NOT send such a request unless the underlying stream is encrypted (using SSL or TLS) and the client has verified that the server certificate is signed by a trusted certificate authority. A given deployment MAY choose to disable password changes if the stream is not properly encrypted, to disable in-band password changes, or to require additional information (such as the old password or previously-gathered personal information) before changing the password.
+If the user provides an empty password element or a password element that contains no XML character data (i.e., either <password/> or <password></password>), the server or service MUST NOT change the password to a null value, but instead MUST maintain the existing password.
+Several error conditions are possible:
+| Condition | Description |
|---|---|
| &badrequest; | The password change request does not contain complete information (both <username/> and <password/> are required). |
| ¬authorized; | The server or service does not consider the channel safe enough to enable a password change. |
| ¬allowed; | The server or service does not allow password changes. |
| &unexpected; | The host is an instant messaging server and the IQ set does not contain a 'from' address because the entity is not registered with the server. |
The server or service SHOULD NOT return the original XML sent in IQ error stanzas related to password changes.
+In order to require additional information before changing the password, the server or service SHOULD return a Data Form in the error stanza:
+The user then SHOULD return the form:
+The fields defined for the 'jabber:iq:register' namespace are strictly limited to those specified in the schema. If a host needs to gather additional information, JEP-0004: Data Forms ("x:data") SHOULD be used according to the following rules:
+-
+
- A host MUST NOT add new fields to the 'jabber:iq:register' namespace; instead, extensibility SHOULD be pursued via the Data Forms protocol as specified herein. +
- The x:data form shall be contained as a child element of the <query xmlns='jabber:iq:register'/> element (it cannot be a child of the &IQ; stanza and comply with Section 9.2.3 of &rfc3920;). +
- The x:data form SHOULD contain x:data fields that correspond to all of the iq:register fields (e.g., username and password). +
- The x:data form SHOULD use a hidden FORM_TYPE field for the purpose of standardizing field names within the form, as defined in &jep0068;. +
- The x:data form shall take precedence over the iq:register fields; if the submitting entity supports the Data Forms protocol, it SHOULD submit the data form rather than the predefined 'jabber:iq:register' fields, and MUST NOT submit both the data form and the predefined fields (see the Precedence Order section of this document). +
Support for extensibility via Data Forms is RECOMMENDED but is not required for compliance with this JEP.
+A given deployment MAY wish to redirect users to another medium (e.g., a website) for registration, rather than allowing in-band registration. The recommended approach is to include only the <instructions/> element rather than the required fields or a data form in the IQ result, as well as a URL encoded using &jep0066; (see the Precedence Order section below for further details).
+Given the foregoing discussion, it is evident that an entity could receive any combination of iq:register, x:data, and x:oob namespaces from a service in response to a request for information. The precedence order is as follows:
+-
+
- x:data +
- iq:register +
- x:oob +
(Naturally, if the receiving application does not understand any of the foregoing namespaces, it MUST ignore the data qualified by that namespace.)
+Thus it is possible that the host may return any of the following combinations, in which case the submitting application MUST proceed as defined in the table below (it is assumed that "iq:register fields" means instructions plus fields, whereas "iq:register instructions" means the <instructions/> element only):
+| Included Data | +Recommended Processing | +Notes | +
|---|---|---|
| iq:register fields | +Submit the completed iq:register fields. | +This is the normal processing model for "legacy" services and clients. | +
| x:data form + iq:register fields | +Submit the completed x:data form if understood, otherwise submit the completed iq:register fields; however, an application MUST NOT submit both. | +The iq:register fields would be included for "legacy" clients; this combination SHOULD NOT be used if the x:data form includes required fields (e.g., a public key) that are not equivalent to defined iq:register fields (the next combination SHOULD be used instead). | +
| x:data form + iq:register instructions | +Submit the completed x:data form if understood, otherwise present the iq:register instructions to the user. | +This combination SHOULD be used if the x:data form includes required fields (e.g., a public key) that are not equivalent to defined iq:register fields and an alternate URL is not available. | +
| x:data form + x:oob URL | +Submit the completed x:data form if understood, otherwise present the provided URL as an alternative. | +This combination MAY be returned by a host, but a host SHOULD return the next combination instead in order to support the full range of legacy clients. | +
| x:data form + iq:register instructions + x:oob URL | +Submit the completed x:data form if understood, otherwise present the iq:register instructions and provided URL as an alternative. | +This combination SHOULD be used if the x:data form includes required fields (e.g., a public key) that are not equivalent to defined iq:register fields and an alternate URL is available. | +
| iq:register instructions + x:oob URL | +Present the iq:register instructions and provided URL as a redirect. | +This combination MAY be returned by a host that wishes to redirect registration to a URL. | +
| iq:register fields + x:oob URL | +Submit the completed iq:register fields but optionally present the provided URL as an alternative. | +This combination is NOT RECOMMENDED. | +
This element is obsolete, but is documented here for historical completeness.
+The <key/> element was used as a "transaction key" in certain IQ interactions in order to verify the identity of the sender. In particular, it was used by servers (but generally not services) during in-band registration, since normally a user does not yet have a 'from' address before registering. The flow is as follows:
+-
+
- Client sends IQ-get request to server. +
- Server returns required elements to client, including <key/> element containing a random string (often a SHA-1 hash). +
- Client sends registration information to server, including <key/> element with the same value provided by the server. +
- Server checks key information and processes registration request; if key is missing or the key value does not match the transaction key provided, the server returns an error. +
The <key/> element was also used during registration removal.
+RFC 3920 defines methods for advertising feature support during stream negotiation. For the sake of efficiency, it may be desirable for a server to advertise support for in-band registration as a stream feature. The namespace for reporting support within <stream:features/> is "http://jabber.org/features/iq-register". Upon receiving a stream header qualified by the 'jabber:client' namespace, a server returns a stream header to the client and MAY announce support for in-band registration by including the relevant stream feature:
+A server SHOULD NOT advertise in-band registration to another server (i.e., if the initial stream header was qualified by the 'jabber:server' namespace).
+As defined herein, the 'jabber:iq:register' namespace supports both the old (HTTP-style) error codes and the extensible error classes and conditions specified in XMPP Core. A compliant server or service implementation MUST support both old-style and new-style error handling. A compliant client implementation SHOULD support both. For mappings of HTTP-style errors to XMPP-style conditions, refer to &jep0086;.
+In-band registration is usually not included in other messaging protocols (for example, SMTP does not include a method for registering with an email server), often for reasons of security. The registration methods defined herein are known to be insecure and SHOULD NOT be used unless the channel between the registrant and the entity that accepts registration has been secured. For these reasons, the deployment of in-band registration is a policy matter and a given deployment MAY choose to disable in-band registration and password changes. Furthermore, this JEP should be deprecated as soon as a successor protocol is defined and implemented.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes the 'jabber:iq:register' namespace in its registry of protocol namespaces.
+The Jabber Registrar includes the 'http://jabber.org/features/iq-register' namespace in its registry of stream feature namespaces.
+As authorized by &jep0147;, the Jabber Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).
+As described below, the registered querytypes for registration management are "register" and "unregister".
+The 'jabber:iq:register' namespace include a mechanism for creating a registration. The registered querytype for doing so is "register".
+Because registration is a two-step process, the application MUST then send an IQ-get to the entity in order to retrieve the required registration fields:
+The application MUST then present an appropriate interface that enables the user to complete the registration form. Once the user provides the information, the application MUST send an IQ-set to the entity.
+The following submission registers the "register" querytype.
+
+ register
+ jabber:iq:register
+ enables registering with a server or service
+ JEP-0077
+
+ ]]>
+ The 'jabber:iq:register' namespace include a mechanism for cancelling an existing registration. The registered querytype for doing so is "unregister".
+The following submission registers the "unregister" querytype.
+
+ unregister
+ jabber:iq:register
+ enables cancellation of a registration with a server or service
+ JEP-0077
+
+ ]]>
+ There is one FORM_TYPE and set of associated field types and names for field standardization in relation to each major use case for the 'jabber:iq:register' namespace: registration, cancellation of registration, and change of password. The initial submissions for these FORM_TYPES are provided below (additional fields may be provided in future submissions).
+
+ jabber:iq:register
+ JEP-0077
+ Standardization of fields related to registration use case.
+
+
+ jabber:iq:register:cancel
+ JEP-0077
+ Standardization of fields related to cancellation use case.
+
+
+ jabber:iq:register:cancel
+ JEP-0077
+ Standardization of fields related to change password use case.
+
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0077: http://www.jabber.org/jeps/jep-0077.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0077: http://www.jabber.org/jeps/jep-0077.html
+
+
+
+
+
+
+
+
+
+ ]]>
+ Per a vote of the Jabber Council, changed status to Deprecated.
Corrected error in schema and example (username is not required in IQ-get).
Changed SHOULD to MUST regarding priority of SASL (RFC 3920) over jabber:iq:auth (JEP-0078).
Per a vote of the Jabber Council, advanced status to Final.
Specified advertising iq-auth stream feature is implementation-specific; clarified several small matters in the text.
Added reference to character escaping in digest authentication; required inclusion of stream feature when server supports stream features and it is safe to advertise non-SASL authentication.
Removed reference to UTF-16, which is disallowed by XMPP Core; removed reference to character escaping in digest authentication pending list discussion.
Added optional stream feature.
Clarified that username and resource are required for authentication.
Added XMPP error handling.
Addressed case of attempting jabber:iq:auth after SASL failure.
Moved change password use case to JEP-0077.
Per a vote of the Jabber Council, advanced status to Draft.
Changes to address Council concerns.
Added change password use case; added more details to security considerations.
Added digest example; clarified escaping requirements; further specified error conditions; added more details to security considerations.
Removed XMPP-style error conditions until formats are stable.
Removed "enhanced digest" content, added information about expiration date.
Added "enhanced digest" method.
Slight editorial revisions.
Initial version.
Note Well: The protocol specified herein has been deprecated in favor of SASL authentication as specified in &rfc3920;.
+Jabber technologies have long included a wire protocol that enables a client to authenticate with a server.
The 'jabber:iq:auth' method specified herein has been deprecated. However, because it will take some time for existing implementations and deployments to be upgraded to SASL, client and server software implementations still need to include support for 'jabber:iq:auth' in order to interoperate, and this document provides canonical documentation of the 'jabber:iq:auth' method. Nevertheless, implementation and deployment of SASL authentication is strongly recommended, since the 'jabber:iq:auth' method will eventually be obsoleted entirely.
+The 'jabber:iq:auth' namespace must make it possible for a Jabber client to authenticate with a server. In particular, the client must provide a username and appropriate credentials for the specific authentication method used. The methods defined herein are:
+-
+
- plaintext +
- digest (using the SHA1 algorithm specified in &rfc3174;) +
Note: This JEP does not include the so-called "zero-knowledge" method; that method did not provide stronger security than digest authentication and thus is unnecessary.
+In order to determine which fields are required for authentication with a server, a client SHOULD first send an IQ get to the server. A client SHOULD NOT attempt to guess at the required fields, since the nature of the required data is subject to service provisioning.
+If the client included a username with the IQ-get but there is no such username, the server SHOULD NOT return an error, but instead SHOULD return the normal authentication fields (this helps to prevent unknown users from discovering which usernames are in use). If the server does not support non-SASL authentication (e.g., because it supports only SASL authentication as defined in RFC 3920), it MUST return a &unavailable; error. If the client previously attempted SASL authentication but that attempt failed, the server MUST return a <policy-violation/> stream error (see RFC 3920 regarding stream error syntax).
+Both the username and the resource are REQUIRED for client authentication using the 'jabber:iq:auth' namespace; if more flexible authentication and resource provisioning are desired, a server SHOULD implement SASL authentication and resource binding as defined in RFC 3920 (e.g., to enable the server to provide the resource). The <username/> and <resource/> elements MUST be included in the IQ result returned by the server in response to the initial IQ get, and also MUST be included in the IQ set sent by the client when providing authentication credentials.
+The foregoing stanza shows that the server supports both plaintext authentication (via the <password/> element) and digest authentication with SHA1-encrypted passwords (via the <digest/> element).
+Therefore, in order to successfully authenticate with the server in this example, a client MUST provide a username, a resource, and one of password or digest.
+Plaintext passwords are straightforward (obviously, characters that map to predefined XML entities MUST be escaped according to the rules defined in section 4.6 of the XML specification, and any non-US-ASCII characters MUST be encoded according to the encoding of XML streams as specified in RFC 3920, i.e., UTF-8 as defined in &rfc3269;).
+The value of the <digest/> element MUST be computed according to the following algorithm:
+-
+
- Concatenate the Stream ID received from the server with the password.
In Digest authentication, password characters that map to predefined XML entities SHOULD NOT be escaped as they are for plaintext passwords, but non-US-ASCII characters MUST be encoded as UTF-8 since the SHA-1 hashing algorithm operates on byte arrays.
+ - Hash the concatenated string according to the SHA1 algorithm, i.e., SHA1(concat(sid, password)). +
- Ensure that the hash output is in hexidecimal format, not binary or base64. +
- Convert the hash output to all lowercase characters. +
The character data shown in the <digest/> element is the output produced as a result of following the algorithm defined above when the stream ID is '3EE948B0' and the password is 'Calli0pe'.
+If the credentials provided match those known by the server, the client will be successfully authenticated.
+Alternatively, authentication may fail. Possible causes of failure include:
+-
+
- The user provided incorrect credentials. +
- There is a resource conflict (i.e., there is already an active session with that resource identifier associated with the same username). The RECOMMENDED behavior is for the server to terminate the existing session and create the new one; however, the server MAY provide the opposite behavior if desired, leading to a conflict error for the newly requested login. +
- The user did not provide all of the required information (e.g., did not provide a username or resource). +
Although RFC 3920 specifies that error stanzas SHOULD include the original XML sent, error stanzas qualified by the 'jabber:iq:auth' namespace SHOULD NOT do so given the sensitive nature of the information being exchanged.
+RFC 3920 defines methods for advertising feature support during stream negotiation. It may be desirable for a server to advertise support for non-SASL authentication as a stream feature. The namespace for reporting support within <stream:features/> is "http://jabber.org/features/iq-auth". Upon receiving a stream header qualified by the 'jabber:client' namespace, a server that returns stream features SHOULD also announce support for non-SASL authentication by including the relevant stream feature. Exactly when a server advertises the iq-auth stream feature is up to the implementation or deployment (e.g., a server MAY advertise this feature only after successful TLS negotiation or if the channel is encrypted via the older SSL method). Obviously, this does not apply to servers that do not support stream features (e.g., older servers that do not comply with XMPP 1.0).
+A server SHOULD NOT advertise non-SASL authentication to another server (i.e., if the initial stream header was qualified by the 'jabber:server' namespace).
+As defined herein, the 'jabber:iq:auth' namespace supports both the old (HTTP-style) error codes and the extensible error classes and conditions specified in RFC 3920. A compliant server or service implementation MUST support both old-style and new-style error handling. A compliant client implementation SHOULD support both.
+In accordance with Section 8 of &jep0001;, on 2004-10-20 this JEP was advanced to a status of Final with the understanding that it would expire in six months. On 2006-09-13, the Jabber Council changed the status of this JEP to Deprecated. The Jabber Council will review this JEP every six months to determine whether to change its status to Obsolete or to extend the expiration date for an additional six months; this process will continue until the JEP is obsoleted. For the latest expiration date, refer to the JEP Information block at the beginning of this document.
+Use of the 'jabber:iq:auth' method for client-server authentication is not as secure as SASL authentication (defined in RFC 3920). If both client and server implement SASL, they MUST use SASL. If a client attempts to authenticate using the 'jabber:iq:auth' namespace after an attempt at SASL authentication fails, the server MUST refuse the 'jabber:iq:auth' attempt by returning a <policy-violation/> stream error to the client.
+Client implementations MUST NOT make plaintext the default mechanism, and SHOULD warn the user that the plaintext mechanism is insecure. The plaintext mechanism SHOULD NOT be used unless the underlying stream is encrypted (using SSL or TLS) and the client has verified that the server certificate is signed by a trusted certificate authority. A given domain MAY choose to disable plaintext logins if the stream is not properly encrypted, or disable them entirely. If a client implements the plaintext mechanism and a server allows both the digest mechanism and the plaintext mechanism when channel encryption is not in use, a downgrade attack is possible, in which a man-in-the-middle tricks the client into revealing the user's plaintext password.
+Authentication using the 'jabber:iq:auth' method is known to be less secure than SASL authentication, which is one reason why the 'jabber:iq:auth' method has been deprecated.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes the 'jabber:iq:auth' namespace in its registry of protocol namespaces.
+The Jabber Registrar includes the 'http://jabber.org/features/iq-auth' namespace in its registry of stream feature namespaces.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0078: http://www.jabber.org/jeps/jep-0078.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0078: http://www.jabber.org/jeps/jep-0078.html
+
+
+
+
+
+
+
+
+
+ ]]>
+ This JEP defines a protocol that enables an end-point entity to specify additional delivery semantics for an XMPP <message/> stanza. This protocol is typically used by clients to inform the receiving server how to deliver a particular stanza, such as providing an expiration time or a resource-matching strategy.
+The built-in delivery semantics for <message/> stanzas (defined in &xmppcore; and, for instant messaging applications, also in &xmppim;) are adequate for most current applications. However, there are various cases where more stringent delivery semantics are necessary. The most common cases discussed in this JEP are:
+-
+
- Reliable data transport -- the sender requires notification (positive and/or negative) of message delivery. +
- Time-sensitive messages -- the message is valid only until a certain date and time. +
- Transient messages -- the message should not be stored offline for later delivery. +
This protocol is mostly handled by the server or servers processing the <message/>. The protocol consists of a list of rules, with conditions and actions for each rule. Upon receipt of an appropriately marked message, the server interprets the rules in the order they are received, looking for met conditions. When a condition is met, the action for that rule is executed, and message processing stops.
+Each rule is flagged for the scope it applies to, whether it be the overall route, or for each hop in the route. Additionally, while this JEP defines a default set of conditions and actions, the protocol is extensible enough to allow for more to be defined in the future.
+The namespace for the protocol is "http://jabber.org/protocol/amp".
+In order for this protocol to function properly, the containing &MESSAGE; stanza MUST possess an 'id' attribute, and the value of the 'id' attribute MUST NOT be an empty string. The server MUST include this 'id' attribute value with any response back to the sender; this enables servers and clients to properly relate the initial request with any subsequent alert, error, or notification.
+The following use case flow describes the interaction between the sender and a server. As illustrated below, this interaction is actually rather simple:
+-
+
- Sender determines support (E1) +
- Sender specifies appropriate rules and sends message to server (E1,E2) +
- Sender awaits any protocol-specific responses (UCE) +
-
+
- E1: The server does not support this protocol (UCE unsuccessfully) +
- E2: The server does not support one or more specified rule conditions/actions (UCE unsuccessfully) +
Sending entities that wish to use AMP SHOULD discover support for this protocol (using &jep0030;) along the intended path. Typically, this would involve sending disco#info queries to the sending entity's own server and the server of the intended recipient. The results of these queries MAY be cached for up to 24 hours, unless otherwise expired.
+If a server supports Advanced Message Processing, it MUST report that by including a service discovery feature of "http://jabber.org/protocol/amp" in the service discovery information result that it returns to the requesting entity.
+A server SHOULD also maintain a service discovery node named "http://jabber.org/protocol/amp", at which it advertises the individual actions and conditions it supports. If an entity needs to determine whether the server supports individual actions and conditions, it SHOULD send a service discovery information request to that node; the server then MUST either return the list of supported actions and conditions or return an error such as &feature;. (Note: If the server does not provide information for this disco node, the requesting entity MUST assume that all actions and conditons are supported for each reported action set or condition set.)
+Each supported action shall be reported as a feature using the following format:
+http://jabber.org/protocol/amp?action={action}
+ Each supported condition shall be reported as a feature using the following format:
+http://jabber.org/protocol/amp?condition={condition}
+ The following examples show the request-response flow for information about individual actions and conditions (note the inclusion of the 'node' attribute).
+Once support is determined, the sender can attach the desired delivery semantics to the message:
+The semantics are defined as a set of <rule/> elements within the <amp/> root element. Each <rule/> declares the condition to trigger on and the action to execute if triggered.
+By default, the ruleset applies only to the "edge servers": those servers to which the sending and receiving entities are connected. (Note: For the purposes of Advanced Message Processing, "server" is defined as in XMPP Core and does not include any internal components, such as connection managers, that may provide functionality within a server implementation or installation.)
+The ruleset MAY be applied to all server-to-server "hops" along the route from the sending and receiving entities by adding the "per-hop' attribute to the <amp/> element. The value of this attribute is either "true" (apply rules to all hops) or "false" (follow default behavior, i.e., apply rules at the edge servers only).
+For examples of validation failure, refer to the Error Handling section of this document.
+Note: Even if "per-hop" processing is requested, each server in the route MUST ignore rules that cannot apply to it; the Defined Conditions outline if they can be applied per-hop.
+Server operation is where the bulk of the work is performed. Upon receiving a message with an AMP extension, the server performs the following flow:
+-
+
- Validate the semantics (E1, E2). +
- Determine the default behavior. +
- Process rules until condition is met.
+
-
+
- If a condition is met, execute that rule's action +
- If no conditions are met, perform "default" behavior for message +
+ - Execute determined action (UCE) (E3). +
-
+
- E1: The provided semantics (condition and/or action) are not supported or valid (UCE unsuccessfully) +
- E2: The requested semantics are not acceptable (UCE unsuccessfully) +
- E3: The next server does not support this protocol (UCE unsuccessfully) +
Validation can take many forms, but at the very least the server MUST verify that it understands each of the rule conditions and actions, and that the condition contents are appropriate. The server MAY also refuse to accept certain combinations of conditions and actions, for example if they present a risk of violating security policies. If the semantics are not valid, supported, or acceptable, the server MUST reply with an error specifying the rule(s) that are at issue. The server SHOULD validate all the semantics before returning an error. For syntax and examples of error handling related to validation failure, refer to the Error Handling section of this document.
+This step is essentially what a server normally does, except that it does not actually perform the action. This determines what would happen to the message if there were no semantics attached (such as dispatch to another server or store offline). At this point, the server SHOULD also calculate any timing or calendar requirements (if applicable).
+At this step, the server processes the attached semantics. The server MUST process the rules serially, and in the order they are presented within the <amp/> element. As soon as a rule's condition is met, processing ends with that action overriding the default action determined earlier (unless the action permits continued processing).
+Once all rules have been processed or otherwise accounted for, the server executes the action determined at this point.
+A server SHOULD NOT dispatch a &MESSAGE; stanza with AMP semantics to another server unless it knows that the next server supports AMP (this SHOULD be discovered via Service Discovery and MAY be cached to avoid delivery delays). If the next server does not support AMP, the current server replies to the original sender with a &e503; error condition. Otherwise this flow starts again for the server to which the message has been dispatched.
+If the determined action involves returning an event (alert, error, or notification) to the sender, a server MUST send a &MESSAGE; stanza to the sender containing the rule that was met. This &MESSAGE; stanza MUST include the original value of the 'id' attribute and SHOULD NOT contain the non-AMP contents (e.g., &BODY; child) originally included by the sender.
+The preceding sections of this JEP define the general behavior regarding AMP. This section outlines how <rule/> action and condition sets are specified. It also provides defined action and condition sets; these action and condition sets SHOULD be supported by any implementation of Advanced Message Processing, but support for any given action or condition set it not required. (Note: The action and condition sets defined herein may be supplemented in the future via registration of additional action and condition sets with the Jabber Registrar.)
+The definition of a <rule/> condition MUST provide the following information:
+-
+
- Define a namespace governing the condition set +
- Define the condition:
+
-
+
- Define the 'condition' attribute value +
- Specify if the "per-hop" flag applies +
- Define the syntax/format of the 'value' attribute value +
- Define how the "value" is interpreted to meet a condition +
+
The definition of a <rule/> action MUST provide the following information:
+-
+
- Define a namespace governing the action set +
- Define the action:
+
-
+
- Define each 'action' attribute value +
- Define the expected behavior if the <rule/> is triggered +
+
The condition defines how or when a particular rule is triggered. The value of the condition attribute determines what the contents of the <rule/> mean.
+The following conditions are defined by this JEP and SHOULD be supported by any implementation.
+In the following sections, the terms "content" and "contents" refers to the XML character data contained by the <rule/> element.
+The "deliver" condition is used to ensure delivery (or non-delivery) in one of five ways:
+-
+
- Directly to the specified address or account over XMPP +
- Delayed to offline storage (for later delivery via XMPP) +
- Forwarded to an alternate address or account over XMPP +
- Indirectly to an alternate address or account through a gateway to a non-XMPP system +
This condition is met based on what the processor would do with the message at the moment of receipt, as follows:
+| Value | +Description | +
|---|---|
| direct | +The message would be immediately delivered to the intended recipient or routed to the next hop. | +
| forward | +The message would be forwarded to another XMPP address or account. | +
| gateway | +The message would be sent through a gateway to an address or account on a non-XMPP system. | +
| none | +The message would not be delivered at all (e.g., because the intended recipient is offline and message storage is not enabled). | +
| stored | +The message would be stored offline for later delivery to the intended recipient. | +
This condition MAY be applied to each "hop" in the server route.
+The "expire-at" condition is used to ensure delivery before an absolute point in time. Naturally, this does not guarantee
The content of the 'value' attribute specifies some point after the exact moment the message is sent; the content MUST be a DateTime as specified in &jep0082;, and the timezone MUST be UTC.
+The condition is met if the message would be delivered to the recipient after the specified datetime. To determine the datetime to compare to, the processor first determines if and when a message can be dispatched (e.g. not stored offline). The processor then records this datetime, and compares it with the specified datetime. If the current datetime is on or after that specified, the condition is met.
+This condition MAY be applied to each "hop" in the server route.
+The "match-resource" condition is used to restrict delivery based on the resource identifier of the recipient JID.
+The defined values for this condition are:
+| Value | +Description | +Example | +
|---|---|---|
| any | +Destination resource matches any value, effectively ignoring the intended resource. | +"home/laptop" matches "home", "home/desktop" or "work/desktop" | +
| exact | +Destination resource exactly matches the intended resource. | +"home/laptop" only matches "home/laptop" and not "home/desktop" or "work/desktop" | +
| other | +Destination resource matches any value except for the intended resource. | +"home/laptop" matches "work/desktop", "home" or "home/desktop", but not "home/laptop" | +
The condition is met if the resource for the actual destination JID matches the intended JID using the above rules. For instance, if a message is intended for "romeo@montague.net/work" with the "match-resource" condition of "exact", the condition is met if the message can be immediately delivered only to "romeo@montague.net/work".
+For purposes of this condition, an intended JID with no resource has the following behavior:
+-
+
- If the value is "exact", the condition is met only if the server would deliver to a destination JID without a resource identifier (e.g., a &jep0045; room or offline storage). +
- If the value is "other", the condition is met only if the server would not deliver to a destination JID without a resource identifier. +
This condition MUST NOT be applied to each "hop" in the server route, only at the edge servers. If an <amp/> element includes this condition and also indicates that it should be processed per hop, this <rule/> shall be ignored.
+Note: By design, this protocol does not include support for partial resource matching (which would stipulate, for example, that the resource identifiers "home/laptop" and "homeboy" both match "home").
+The action defines what occurs when a particular rule is triggered. The value of the action attribute determines the behavior if the rule's condition is met.
+The following actions are defined by this JEP.
+The "alert" action triggers a reply &MESSAGE; stanza to the sending entity. This &MESSAGE; stanza MUST contain the element <amp status='alert'/>, which itself contains the <rule/> that triggered this action. In all other respects, this action behaves as "drop".
+
+
+
+
+ ]]>The "drop" action silently discards the message from any further delivery attempts and ensures that it is not placed into offline storage. The drop MUST NOT result in other responses.
+The "error" action triggers a reply &MESSAGE; stanza of type "error" to the sending entity. The &MESSAGE; stanza's <error/> child MUST contain a <failed-rules xmlns='http://jabber.org/protocol/amp#errors'/> error condition, which itself contains the rules that triggered this action.
+
+
+
+
+
+
+
+
+ ]]>Note that the error SHOULD be of type "modify", and the general error condition SHOULD be <undefined-condition xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>.
+The "notify" action triggers a reply &MESSAGE; stanza to the sending entity. This &MESSAGE; stanza MUST contain the element <amp status='notify'/>, which itself contains the <rule/> that triggered this action. Unlike the other actions, this action does not override the default behavior for a server. Instead, the server then executes its default behavior after sending the notify.
+
+
+
+
+ ]]>In general, a rule can be read as "do {action} if {condition} is true for {value}"; however, to facilitate understanding, this section describes the various condition/action combinations in plain English.
+When the condition is "deliver", the rules can be described as follows:
+| Action | +Value | +Description | +
|---|---|---|
| alert | +direct | +Return an alert if the message would be delivered directly. | +
| alert | +forward | +Return an alert if the message would be forwarded to another XMPP address. | +
| alert | +gateway | +Return an alert if the message would be delivered to a non-XMPP address through a gateway. | +
| alert | +none | +Return an alert if no delivery is possible. | +
| alert | +stored | +Return an alert if the message would be stored offline for later delivery via XMPP. | +
| drop | +direct | +Drop the message if it would be delivered directly. | +
| drop | +forward | +Drop the message if it would be forwarded to another XMPP address. | +
| drop | +gateway | +Drop the message if it would be delivered to a non-XMPP address through a gateway. | +
| drop | +none | +Drop the message if no delivery is possible. | +
| drop | +stored | +Drop the message if it would be stored offline for later delivery via XMPP. | +
| error | +direct | +Return an error if the message would be delivered directly. | +
| error | +forward | +Return an error if the message would be forwarded to another XMPP address. | +
| error | +gateway | +Return an error if the message would be delivered to a non-XMPP address through a gateway. | +
| error | +none | +Return an error if no delivery is possible. | +
| error | +stored | +Return an error if the message would be stored offline for later delivery via XMPP. | +
| notify | +direct | +Return a notification if the message would be delivered directly. | +
| notify | +forward | +Return a notification if the message would be forwarded to another XMPP address. | +
| notify | +gateway | +Return a notification if the message would be delivered to a non-XMPP address through a gateway. | +
| notify | +none | +Return a notification if no delivery is possible. | +
| notify | +stored | +Return a notification if the message would be stored offline for later delivery via XMPP. | +
When the condition is "expire-at", the rules can be described as follows:
+| Action | +Description | +
|---|---|
| alert | +Return an alert if the message would be delivered after the specified timestamp. | +
| drop | +Drop the message if it would be delivered after the specified timestamp. | +
| error | +Return an error if the message would be delivered after the specified timestamp. | +
| notify | +Return a notification if the message would be delivered after the specified timestamp. | +
When the condition is "match-resource", the rules can be described as follows:
+| Action | +Value | +Description | +
|---|---|---|
| alert | +any | +Return an alert if the message would be delivered to any resource. | +
| alert | +exact | +Return an alert if the message would be delivered to the exact resource. | +
| alert | +other | +Return an alert if the message would be delivered to a resource other than that specified. | +
| drop | +any | +Drop the message if it would be delivered to any resource. | +
| drop | +exact | +Drop the message if it would be delivered to the exact resource. | +
| drop | +other | +Drop the message if it would be delivered to a resource other than that specified. | +
| error | +any | +Return an error if the message would be delivered to any resource. | +
| error | +exact | +Return an error if the message would be delivered to the exact resource. | +
| error | +other | +Return an error if the message would be delivered to a resource other than that specified. | +
| notify | +any | +Return a notification if the message would be delivered to any resource. | +
| notify | +exact | +Return a notification if the message would be delivered to the exact resource. | +
| notify | +other | +Return a notification if the message would be delivered to a resource other than that specified. | +
All delivery semantics are encapsulated in the <amp/> element. This element contains one or more <rule/> elements specifying the specific rules to process. It can optionally possess attributes about the current status, the original sender and recipient, and route applicability.
+The 'status' attribute specifies the reason for this <amp/> element. When specifying semantics to be applied (client to server), this attribute MUST NOT be present. When replying to a sending entity regarding a met condition, this attribute MUST be present and SHOULD be the value of the 'action' attribute for the triggered rule. (Note: Individual action definitions MAY provide their own requirements.)
+The 'from' attribute specifies the original sender of the containing &MESSAGE; stanza. This attribute MUST be specified for any &MESSAGE; stanza sent from a supporting server, regardless of the recipient. It SHOULD NOT be specified otherwise. The value of the 'from' attribute MUST be the full JID (node@domain/resource) of the sender for the original &MESSAGE; stanza.
+The 'to' attribute specifies the original (intended) recipient of the containing &MESSAGE; stanza. This attribute MUST be specified for any &MESSAGE; stanza sent from a supporting server, regardless of the recipient. It SHOULD NOT be specified otherwise. The value of the 'to' attribute MUST be the full JID (node@domain/resource) of the intended recipient for the original &MESSAGE; stanza.
+The 'per-hop' attribute flags the contained ruleset for processing at each server in the route between the original sender and original intended recipient. This attribute MAY be present, and MUST be either "true" or "false". If not present, the default is "false".
+Each semantic rule is specified with a <rule/> element. This element possesses attributes for the condition, value, and action.
+The 'action' attribute defines the result for this rule. This attribute MUST be present, and MUST be either a value defined in the Defined Actions section, or one registered with the Jabber Registrar.
+The 'condition' attribute defines the overall condition this rule applies to. This attribute MUST be present, and MUST be either a value defined in the Defined Conditions section, or one registered with the Jabber Registrar.
+The 'value' attribute defines how the condition is matched. This attribute MUST be present, and MUST NOT be an empty string (""). The interpretation of this attribute's value is determined by the 'condition' attribute.
+The &MESSAGE; stanza is nearly ideal for data transport, but to ensure reliability it is often desirable that such messages not be delivered to any resource but that specified. To facilitate this, the sending entity includes a <rule action='drop' condition='match-resource' value='other'/> (if failure notification is unnecessary) or <rule action='error' condition='match-resource' value='other'/> (if failure notification is required). The following example illustrates this using &jep0047;:
+In the above case, the sender would receive an error reply if the message could not be delivered specifically to "francisco@hamlet.lit/pda" by the specified time. For example, if the intended resource went offline before the message could be delivered, the processing server would return the following error:
+Time-sensitive messages are a frequent occurrence in some environments (e.g., front-office personnel routinely notify others of "events" such as guests, unexpected refreshments, and ad-hoc gatherings). To send a time-sensitive message, the sending entity includes a <rule action='drop' condition='expire-at'/> with the time when the event is to occur:
+In the above case, the server for "linuxwolf@outer-planes.net" would not deliver the message once 23:00 UTC (3:00 PM Pacific Daylight Time) has passed.
+Transient messages are messages that should never be stored offline. To send a transient message, the sending entity includes a <rule action='drop' condition='deliver' value='stored'/>:
+Alternatively, the sending entity includes a <rule action='alert' condition='deliver' value='stored'/> to be alerted instead of having the message silently dropped:
+To simplify the discussion of error conditions, this document uses the following mappings between namespace URIs and namespace prefixes (note: this mapping is provided only for the purpose of simplifying the discussion and is not intended for use within the protocol itself).
+| Prefix | +URI | +
|---|---|
| xmpp | +urn:ietf:params:xml:ns:xmpp-stanzas | +
| msg | +http://jabber.org/protocol/amp | +
| err | +http://jabber.org/protocol/amp#errors | +
The following table shows the possible error conditions in relation to general AMP rules and conditions as well as the Defined Actions.
+| General Condition | +Error Type | +Specific Condition | +Description | +
|---|---|---|---|
| <xmpp:bad-request/> | +modify | +<msg:unsupported-actions/> | +One or more rule's specified actions are not supported. The element <msg:unsupported-actions/> contains the <rule/> elements that specify the unsupported actions. | +
| <xmpp:bad-request/> | +modify | +<msg:unsupported-conditions/> | +One or more rule's specified conditions are not supported. The element <msg:unsupported-conditions/> contains the <rule/> elements that specify the unsupported conditions. | +
| <xmpp:not-acceptable/> | +modify | +<msg:invalid-rules/> | +One or more rules are not acceptable by this server, usually because the condition/action combination is restricted. The element <msg:invalid-rules/> contains the <rule/> elements that are not acceptable. | +
| <xmpp:service-unavailable/> | +cancel | +NONE | +This protocol is not supported. This error is returned to the sending entity if a server along the route to the recipient does not implement this protocol. | +
| <xmpp:undefined-condition/> | +modify | +<err:failed-rules/> | +One or more <rule/> elements triggered the "error" action. This condition contains the triggered <rule/> elements. | +
This section shows examples of the error conditions described in the previous section (for information regarding mapping of XMPP error conditions to Jabber error codes, refer to &jep0086;).
+If the recipient's server implements "offline storage", it will need to keep track of which offline messages are subject to expiration and not deliver those which have expired. Exactly how to do so is a matter of implementation. One possible implementation is for the server to maintain a separate database of expirable messages and periodically scan it; upon discovering an expired message, it could flag the message as eligible for discarding and inform the sender, but not discard the message until the intended recipient next becomes available.
+&xmppcore; defines methods for advertising feature support during stream negotiation. For the sake of efficiency, it may be desirable for a server to advertise support for Advanced Message Processing as a stream feature. The namespace for reporting support within <stream:features/> is "http://jabber.org/features/amp". Upon receiving a stream header from the initiating entity, the receiving entity (usually a server) returns a stream header to initiating entity and MAY announce support for Advanced Message Processing registration by including the relevant stream feature:
+Most AMP conditions could be used by unauthorized individuals to gain access to presence information about users of IM servers and other presence-based messaging systems. For example, consider the following scenario: the user <romeo@montague.net> is not an authorized subscriber to the presence of the user <nurse@capulet.com>, but sends a &MESSAGE; stanza with a "deliver" rule of "stored" and an action of "alert" to that address; if the Nurse is not online, Romeo would receive an AMP alert that the message has been stored offline, in the process discovering that the Nurse is offline. Similar scenarios are possible with the "match-resource" rule (send to the user's usual resource) and the "expire-at" rule (send messages every minute to poll for presence). If a server implements presence subscriptions as specified in &rfc3921;, it SHOULD NOT return alerts, errors, or other AMP notifications to senders who are not authorized to view the recipient's presence information (via a subscription of "both" or "from") if the notification would reveal the recipient's status as online or offline.
There are several directions server implementors can follow in this regard:
+-
+
Do not implement the relevant condition, as a result of which the server MUST reply with a &feature; error condition if the condition is specified; however, this is unduly restricts the supported conditions and effectively cripples the AMP functionality, so is NOT RECOMMENDED.
+ Accept the relevant condition only if the action is "drop", as a result of which the server MUST reply with a ¬acceptable; error condition if the action is "alert", "error", or "notify"; this is slightly less restrictive but still unnecessarily restricts the functionality of the system, so is NOT RECOMMENDED.
+ Accept the relevant condition only if the sender is authorized to receive the receiver's presence, as a result of which the server MUST reply with a ¬acceptable; error condition if the sender is not so authorized; this is the RECOMMENDED behavior.
+
No interaction with &IANA; is necessary as a result of this JEP.
+The ®ISTRAR; includes 'http://jabber.org/protocol/amp' and 'http://jabber.org/protocol/amp#errors' in its registry of protocol namespaces.
+The Jabber Registrar includes the 'http://jabber.org/features/amp' namespace in its registry of stream feature namespaces.
+The Jabber Registrar includes 'http://jabber.org/protocol/amp' in its registry of well-known Service Discovery nodes.
+The Jabber Registrar maintains a registry of AMP <rule/> conditions (see <http://www.jabber.org/registrar/amp-conditions.html>).
+
+ the value of the 'condition' attribute
+ the namespace to be used as a service discovery feature
+ does the "per-hop" flag apply? [true|false]
+
+ The syntax (e.g., datatype or allowable values) of the
+ 'value' attribute.
+
+ values that result in message processing
+ the document (e.g., JEP) in which this condition is specified
+
+ ]]>
+ The registrant may register more than one condition at a time, each contained in a separate <condition/> element.
+Note: The namespace for the condition set shall be included in the Service Discovery features registry.
+
+ deliver
+ http://jabber.org/protocol/amp?condition=deliver
+ true
+ [direct|forward|gateway|none|stored]
+
+ The condition is met if (1) the value is "direct" and the message
+ can be immediately delivered or further dispatched, (2) the value
+ is "forward" and the message can be forwarded to another XMPP
+ address, (3) the value is "gateway" and the message can be sent
+ to a non-XMPP address via a gateway, (4) the value is "none" and
+ the message cannot be delivered at all, or (5) the value is
+ "stored" and the message can be stored for later delivery.
+
+ JEP-0079
+
+
+
+ expire-at
+ http://jabber.org/protocol/amp?condition=expire-at
+ true
+ DateTime per JEP-0082
+
+ The condition is met if the message would be delivered after
+ the specified DateTime.
+
+ JEP-0079
+
+
+
+ match-resource
+ http://jabber.org/protocol/amp?condition=match-resource
+ false
+ [any|exact|other]
+
+ The condition is met if (1) the value is "any" and the intended
+ recipient has at least one available resource (as defined in the
+ XMPP IM specification); (2) the value "exact" and the intended
+ recipient has an available resource that exactly matches the JID
+ specified in the 'to' address; (3) the value is "other" and the
+ intended recipient has an available resource whose full JID is
+ other than that specified in the 'to' address.
+
+ JEP-0079
+
+ ]]>
+ The Jabber Registrar maintains a registry of AMP <rule/> actions (see <http://www.jabber.org/registrar/amp-actions.html>).
+
+ the value of the 'action' attribute
+ the namespace to be used as a service discovery feature
+ the expected behavior if the rule is triggered
+ the document (e.g., JEP) in which this action is specified
+
+ ]]>
+ The registrant may register more than one action at a time, each contained in a separate <action/> element.
+Note: The namespace for the action set shall be included in the Service Discovery features registry.
+
+ alert
+ http://jabber.org/protocol/amp?action=drop
+
+ The message is silently discarded but an alert is returned to the
+ sender.
+
+ JEP-0079
+
+
+
+ drop
+ http://jabber.org/protocol/amp?action=drop
+
+ The message is silently discarded.
+
+ JEP-0079
+
+
+
+ error
+ http://jabber.org/protocol/amp?action=error
+
+ The message is not processed and an error is returned to the sender,
+ specifying which rule resulted in failed processing.
+
+ JEP-0079
+
+
+
+ notify
+ http://jabber.org/protocol/amp?action=notify
+
+ The message is processed and a notification message is returned to
+ the sender, specifying which rule was processed.
+
+ JEP-0079
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0079: http://www.jabber.org/jeps/jep-0079.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0079: http://www.jabber.org/jeps/jep-0079.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0079: http://www.jabber.org/jeps/jep-0079.html
+
+
+
+
+
+
+
+
+
+ ]]>
+ Thanks to Marshall Rose and Craig Kaes for their comments.
+Folded in civil location from JEP-0112.
Changed xs:string to xs:decimal for bearing and specified that bearing is to be interpreted as decimal degrees relative to true north.
Changed xs:int to xs:decimal for altitude; changed MUST NOT to SHOULD NOT regarding inferences about accuracy.
Per a vote of the Jabber Council, advanced status to Draft; also added internationalization considerations and linked to an archived version of the GPS datum example.
Clarified several points in the implementation notes.
Specified error flow for IQ example.
Corrected several errors; added reference to JEP-0033.
Reverted from infobits to geoloc elements; moved physical address protocol back to JEP-0112.
Converted to use of infobits.
Merged in contents of JEP-0112.
Changed protocol name from 'location' to 'geoloc'.
Incorporated Standards JIG feedback; changed JEP type to Informational.
Initial version.
This document defines a format for capturing data about an entity's geographical location (geoloc). The format defined herein can describe most earthbound geographical locations, especially locations that may change fairly frequently. Potential uses for this approach include:
+-
+
- Publishing location information to a set of subscribers. +
- Querying another entity for its location. +
- Sending location information to another entity. +
- Attaching location information to presence. +
Geographical location is captured in terms of Global Positioning System (GPS) coordinates as well as civil location (city, street, building, etc.).
+The format defined herein was designed to address the following requirements:
+-
+
- It shall be possible to encapsulate location in terms of Global Positioning System (GPS) coordinates as well as civil location (city, street, building, etc.). +
- The GPS encoding mechanism shall have a single set of units, so that receivers do not need to use heuristics to determine an entity's position. +
- It shall be possible to specify the known amount of error in the GPS coordinates. +
- It shall be possible to include a natural-language description of the location. +
Information about the entity's location is provided by the entity and propagated on the network by the entity's associated application (usually a client). The information is structured by means of a <geoloc/> element that is qualified by the 'http://jabber.org/protocol/geoloc' namespace; the geolocation information itself is provided as the XML character data of the following child elements:
+| Element Name | +Datatype | +Definition | +Example | +
|---|---|---|---|
| alt | +xs:decimal | +Altitude in meters above or below sea level | +1609 | +
| area | +xs:string | +A named area such as a campus or neighborhood | +Central Park | +
| bearing | +xs:decimal | +GPS bearing (direction in which the entity is heading to reach its next waypoint), measured in decimal degrees relative to true north |
+ + |
| building | +xs:string | +A specific building on a street or in an area | +The Empire State Building | +
| country | +xs:string | +The nation where the user is located | +USA | +
| datum | +xs:string | +GPS datum |
+ + |
| description | +xs:string | +A natural-language name for or description of the location | +Bill's house | +
| error | +xs:decimal | +Horizontal GPS error in arc minutes | +10 | +
| floor | +xs:string | +A particular floor in a building | +102 | +
| lat | +xs:decimal | +Latitude in decimal degrees North | +39.75 | +
| locality | +xs:string | +A locality within the administrative region, such as a town or city | +New York City | +
| lon | +xs:decimal | +Longitude in decimal degrees East | +-104.99 | +
| postalcode | +xs:string | +A code used for postal delivery | +10027 | +
| region | +xs:string | +An administrative region of the nation, such as a state or province | +New York | +
| room | +xs:string | +A particular room in a building | +Observatory | +
| street | +xs:string | +A thoroughfare within the locality, or a crossing of two thoroughfares | +34th and Broadway | +
| text | +xs:string | +A catch-all element that captures any other information about the location | +Northwest corner of the lobby | +
| timestamp | +xs:datetime | +UTC timestamp specifying the moment when the reading was taken (MUST conform to the DateTime profile of &jep0082;) | +2004-02-19T21:12Z | +
NOTE: The datatypes specified above are defined in &w3xmlschema2;.
+The location information SHOULD be communicated by means of &jep0060; or the subset of pubsub defined in &jep0163;. Because location information is not pure presence information and can change independently of the user's availability, it SHOULD NOT be provided as an extension to &PRESENCE;, although an application MAY do so if necessary.
+In order to provide information about one's location, the publishing entity should use the pubsub protocol (the following examples show use of the publish-subscribe subset specified in JEP-0163).
+If an entity wishes to request the location of another entity but the requestee does not publish that information via pubsub (including PEP), the requestor MAY send an IQ to the requestee:
+The receiving entity SHOULD make a careful access control decision before returning the actual location.
+If the receiving entity decides not to return the actual location, it MUST return an IQ error, which SHOULD be &forbidden; but MAY be some other appropriate error, such as ¬allowed;:
+If an entity wants to send another entity its postition but it does not publish that information via pubsub, it MAY do so in a message. There SHOULD be a body element so that receiving entities that do not support the geolocation protocol can present a message to the recipient.
+If an entity wishes all of the entities on its roster to be informed of a new location, the entity MAY publish a presence stanza that includes a location, although this is NOT RECOMMENDED (since location SHOULD be published using pubsub instead in order to ensure appropriate access control):
+Avoid "Mars probe" issues: as specified in Table 1, the units for <lat/> and <lon/> MUST be decimal degrees (where South and West are negative, North and East are positive), the units for <alt/> MUST be meters above or below sea level, and the units for <error/> MUST be arc minutes.
+In applications where updates are sent whenever there is a certain distance change in location, those applications SHOULD account for time as well, to avoid rate-limiting when the user is (for example) on a jet plane. One possible way to do this would be to send updates at most once per minute of time (every time 60 seconds have elapsed).
+Inferences SHOULD NOT be made about accuracy from the number of digits specified in the location or altitude.
+Why the datum madness? See <http://www.jabber.org/protocol/geoloc/gps_datum.html> for an example.
+An entity can provide a GPS path by publishing a series of items (i.e., multiple pubsub events) with appropriate values of the <timestamp/> element.
+There are many XML data formats for physical location or address information. It is beyond the scope of this document to provide a mapping from the extension defined herein to every such format. However, it would be valuable to provide a mapping from the XMPP format to the formats used in other presence or extended presence protocols. The two main protocols of interest are:
+-
+
The Wireless Village (now "IMPS") specifications for mobile instant messaging; these specifications define a presence attribute for address information as encapsulated in the IMPS "Address" element
The Wireless Village Initiative: Presence Attributes v1.1 (WV-029); for further information, visit <http://www.openmobilealliance.org/tech/affiliates/wv/wvindex.html>. .
+ The SIP-based SIMPLE specifications; in particular, the IETF's GEOPRIV Working Group has defined an extension to the IETF's &pidf; for location information, as specified in &rfc4119; (also known as "PIDF-LO").
+
The following table also maps the format defined herein to the vCard XML format specified in &jep0054;.
+| XMPP | +Wireless Village / IMPS | +SIMPLE (PIDF-LO) | +vCard XML | +
|---|---|---|---|
| <country/> | +<Country/> | +<country/> | +<CTRY/>
+ |
+
| <region/> | +-- | +<A1/> and/or <A2/> | +<REGION/> | +
| <locality/> | +<City/> | +<A3/> | +<LOCALITY/> | +
| <area/> | +<NamedArea/> | +<A4/> and/or <A5/> | +-- | +
| <street/> | +<Street/>
+ |
+ <A6/>
+ |
+ <STREET/> | +
| <building/> | +<Building/> | +<LMK/> | +-- | +
| <floor/> | +-- | +<FLR/> | +-- | +
| <room/> | +-- | +-- | +-- | +
| <postalcode/> | +-- | +<PC/> | +<PCODE/> | +
| <text/> | +<FreeTextLocation/> | +<LOC/> | +<EXTADR/> | +
| -- | +<Accuracy/>
+ |
+ -- | +-- | +
| -- | +-- | +<NAM/>
+ |
+ -- | +
Because the character data contained in <geoloc/> child elements of type 'xs:string' is intended to be readable by humans, the <geoloc/> element SHOULD possess an 'xml:lang' attribute specifying the natural language of such character data.
+It is imperative to control access to location information, at least by default. Imagine that a stalker got unauthorized access to this information, with enough accuracy and timeliness to be able to find the target person. This scenario could lead to loss of life, so please take access control checks seriously. If an error is deliberately added to a location, the error SHOULD be the same for all receivers, to minimize the likelihood of triangulation. In the case of deliberate error, the <error/> element SHOULD NOT be included.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'http://jabber.org/protocol/geoloc' to its registry of protocol namespaces.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0080: http://www.jabber.org/jeps/jep-0080.html
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+The value of a URI scheme (see &rfc3986;) for Jabber/XMPP communications has long been recognized within the Jabber community, and such a scheme has been formally defined in &xmppuri; as a way of identifying entities that adhere to &xmppcore; or its antecedents. Unfortunately, URI schemes are slow to be accepted on the Internet, such that it might be years (if ever) before widely deployed software such as web browsers will support addresses of the form <xmpp:user@domain>.
+Thankfully, it is not necessary for the large existing base of deployed software to support the xmpp: URI scheme in order to integrate Jabber/XMPP support. A well-accepted alternative approach
+
Therefore, this JEP defines a MIME type of "application/jabber+xml" (in particular, an XML media type in accordance with &rfc3023;). Files of this MIME type would commonly be accessed with a web browser via HTTP, although other access methods are possible (e.g., attachment of the MIME type to an email message). On opening a file of this type, a browser would (by configuration) invoke an appropriate "helper" application (i.e., an external Jabber client, plugin, or internal module) that would enable the user to interact with a Jabber/XMPP server. If the user is not currently connected to a server, the invoked program would be responsible for connecting the user with appropriate prompting for authentication credentials. The file passed to the helper application would define parameters needed to complete a certain use case, such as sending a message to another user.
+Note: The "application/jabber+xml" MIME type defined herein is not to be confused with the "application/xmpp+xml" MIME type defined in &rfc3923;; the two MIME types address different requirements and do not overlap or conflict.
+The solution MUST enable a user to complete the following use cases, support for which is REQUIRED:
+-
+
- Send a single message to another user. +
- Initiate a one-to-one chat session with another user. +
- Subscribe to another user's presence. +
In addition, the solution SHOULD enable a user to complete the following use cases, support for which is RECOMMENDED:
+-
+
- Join a groupchat room. +
- Register with a service. + +
These use cases are defined below.
+In order to send a message to a contact, the user opens an XMPP file of the following form:
+
+
+
+ ]]>
+ The browser passes this file to the helper application, which shall instantiate an appropriate interface for sending a single message to the JID defined in the file. If the user completes the interface, the helper application shall then send a message stanza of type='normal' as specified in &xmppim;, first authenticating with the user's Jabber/XMPP server if necessary.
+
+
+
+ ]]>
+ The browser passes this file to the helper application, which shall instantiate an appropriate interface for chatting with the JID defined in the file. If the user completes the interface, the helper application shall then send a message stanza of type='chat' as specified in XMPP IM, first authenticating with the user's Jabber/XMPP server if necessary.
+
+
+
+ ]]>
+ The browser passes this file to the helper application, which shall instantiate an appropriate interface for sending a presence subscription request to the JID defined in the file (e.g., specifying a name and/or group for the contact). If the user completes the interface, the helper application shall then send a presence stanza of type='subscribe' as specified in XMPP IM, first authenticating with the user's Jabber/XMPP server if necessary. The helper application SHOULD perform a "roster set" before sending the presence subscription request, as described in XMPP IM.
+
+
+
+ ]]>
+ The browser passes this file to the helper application, which shall instantiate an appropriate interface for joining the conference room associated with the JID defined in the file. If the user completes the interface, the helper application shall then send a directed presence stanza to the JID (appending a room nickname to the JID as the resource identifier) as described in &jep0045;, first authenticating with the user's Jabber/XMPP server if necessary.
+
+
+
+ ]]>
+ The browser passes this file to the helper application, which shall send an IQ stanza of type='get' to the service associated with the JID defined in the file in order to determine the registration requirements (first authenticating with the user's Jabber/XMPP server if necessary), as described in &jep0077;. The helper application shall then instantiate an appropriate interface for registering with the service. If the user completes the interface, the helper application shall then send an IQ stanza of type='set' to the JID as described in JEP-0077.
+Detailed security considerations for instant messaging and presence protocols are given in &rfc2779; (Sections 5.1 through 5.4), and for XMPP in particular are given in RFC 3920 (Sections 12.1 through 12.6). In addition, all of the security considerations specified in RFC 3023 apply to the "application/jabber+xml" media type.
+When a helper application has finished processing a file of type "application/jabber+xml", it SHOULD discard the file; this helps to prevent security-related problems that may result from HTTP caching.
+This JEP requires registration of the "application/jabber+xml" content type with &IANA;. The registration is as follows:
+
+Intended usage: COMMON
+Author/Change controller: JSF, Jabber Registrar
+ ]]>
+The ®ISTRAR; shall include 'http://jabber.org/protocol/mimetype' in its registry of protocol namespaces.
+The Jabber Registrar shall interact with the IANA in order to register the media type defined herein.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+-
+
- Add implementation notes for server MIME type registration and HTTP Content-Type output. +
- Add implementation notes for client handling on various platforms (e.g., DDE messages in Windows). +
A number of Jabber protocols specify that dates and times should follow the format defined in &iso8601;. Unfortunately, ISO 8601 provides a great deal of flexibility with regard to the possible date and time "profiles"
The following acronyms and characters are used herein to represent time-related concepts:
+| Term | Definition |
|---|---|
| CCYY | four-digit year portion of Date |
| MM | two-digit month portion of Date |
| DD | two-digit day portion of Date |
| - | ISO 8601 separator among Date portions |
| T | ISO 8601 separator between Date and Time |
| hh | two-digit hour portion of Time (00 through 23) |
| mm | two-digit minutes portion of Time (00 through 59) |
| ss | two-digit seconds portion of Time (00 through 59) |
| : | ISO 8601 separator among Time portions |
| . | ISO 8601 separator between seconds and milliseconds |
| sss | fractional second addendum to Time (MAY contain any number of digits) |
| TZD | Time Zone Definition (either "Z" for UTC or "[+|-]hh:mm" for a specific time zone) |
Three profiles are defined herein.
+The Date profile defines a date without including the time of day. The lexical representation is as follows:
+
+ CCYY-MM-DD
+
+ This profile is equivalent to the 'date' datatype defined in XML Schema
The DateTime profile is used to specify a non-recurring moment in time to an accuracy of seconds (or, optionally, fractions of a second). The format is as follows:
+
+ CCYY-MM-DDThh:mm:ss[.sss]TZD
+
+ The Time Zone Definition is mandatory and MUST be either UTC (denoted by addition of the character 'Z' to the end of the string) or some offset from UTC (denoted by addition of '[+|-]' and 'hh:mm' to the end of the string). The fractions of a second are optional and MAY be ignored if included (although a Jabber protocol using the DateTime profile MAY require the fractions of a second).
+This profile is equivalent to the 'dateTime' datatype defined in XML Schema
The Time profile is used to specify an instant of time that recurs (e.g., every day). The lexical representation is as follows:
+
+ hh:mm:ss[.sss][TZD]
+
+ The Time Zone Definition is optional; if included, it MUST be either UTC (denoted by addition of the character 'Z' to the end of the string) or some offset from UTC (denoted by addition of '[+|-]' and 'hh:mm' to the end of the string). The fractions of a second are optional and MAY be ignored if included (although a Jabber protocol using the DateTime profile MAY require the fractions of a second).
+This profile is equivalent to the 'time' datatype defined in XML Schema
Some existing Jabber protocols use a different lexical representation for datetimes than the representation defined in XML Schema and specified by this JEP. These are &jep0090;, &jep0091;, and &jep0009;. (The representation of dates in &jep0054; matches that specified herein.) These older protocols represent datetimes as follows:
+
+ CCYYMMDDThh:mm:ss
+
+ The primary standard notation recommended by ISO 8601 includes the separators ("-" for dates and ":" for times), although ISO 8601 allows omission of the separators for applications in which compactness is more important than human readability. It is arguable whether Jabber applications using 'jabber:iq:time' and 'jabber:x:delay' require such compactness, but these protocols are in wide use today and have been implemented using the format shown above. Therefore, applications receiving data in those namespaces SHOULD be liberal in what they accept by handling datetimes either in the "CCYYMMDDThh:mm:ss" format or in the lexical representation defined in XML Schema and specified by this JEP. Applications generating data in those namespaces SHOULD use the existing format ("CCYYMMDDThh:mm:ss"), and are effectively "grandfathered" with respect to the date and time formats defined herein. While eventually it would be good to deprecate the older datetime representation for these protocols, the schedule for such deprecation (if any) shall be specified in official JEPs for these older protocols.
+Jabber-RPC is a special case, since the specification for &xmlrpc; includes only one example for datetimes, which is of the format "CCYYMMDDThh:mm:ss". Apparently many implementations of XML-RPC have taken this lexical representation as canonical, and do not support any other representation; because Jabber-RPC normally provides an interface to software that is outside the Jabber network, it is prudent for Jabber-RPC implementations to generate dates in the format shown in the XML-RPC specification, not that defined in this JEP.
+New protocols approved by the Jabber Software Foundation MUST use the lexical representations defined in this JEP.
+The 'date', 'dateTime', and 'time' datatypes defined in XML Schema address several "edge cases" such as dates before the year 0000 and after the year 9999, as well as odd timezones no longer in use; most Jabber applications can safely ignore these edge cases, since it is highly unlikely that a Jabber entity will generate such representations.
+There are no security features or concerns related to this proposal.
+This JEP requires no interaction with &IANA;.
+This JEP requires no interaction with the ®ISTRAR;.
+In many modern instant messaging clients, client authors implement a way to nest contact groups within other contact groups. Usually this is implemented on the client side, since many instant messaging networks do not support nesting contact groups in this manner. The limitation of this system is that if the user changes from one client to another, or even a second installation of the same client, the user loses all of his or her sub-group information. This JEP aims to solve that problem within Jabber, by providing for a way to store sub-groups on the Jabber roster without breaking existing clients.
+Jabber already provides a useful method for storing client data on the server using &jep0049;. All we need to do is create a new roster element and a namespace to store the delimiter for nested groups, roster:delimiter. This element MUST contain XML character data that defines a string to be used as a delimiter in the roster groups.
A single-character roster delimiter (e.g., "/") would make client implementation easier, but be more limiting to the end-user in terms of choices for naming roster groups, so a string is ideal. Therefore, the delimiter SHOULD contain multiple characters in order to avoid inconveniencing the user, but single-character delimiters MUST be honored by the client. The exception is if the delimiter is a single alphanumeric character (a-z, A-Z, 0-9); in this case compliant clients MUST treat the situation as if nesting were disabled, to avoid malicious use of this element by setting 'e' or 'm' or some other common single character as a delimiter.
+A compliant client SHOULD ask for the nested delimiter before requesting the user's roster, in order to know whether or not to parse the roster 'group' fields accordingly. If there is no delimiter stored, a client MAY set a delimiter but MUST either prompt the user for a delimiter, or use a user-configurable default.
+Use cases for this extension are straightforward, and are shown below as examples.
+All compliant clients SHOULD query for an existing delimiter at login.
+Now that the client has a delimiter, we can retrieve and parse the roster properly.
+Bottom, Quince and Snug should be grouped together in a group 'Actors' underneath the group 'Midsummer'. Theseus and Hippolyta should be grouped together in a group 'Royalty' under 'Midsummer'. Robin Goodfellow, meanwhile, being in a class unto himself, is a plain contact under the 'Midsummer' group rather than in an actual sub-group. The group Hamlet, containing only one melancholy prince and his mother, contains no sub-groups at all.
+As should be apparent, a client which does not support the delimiter will instead create a separate group -- such as 'Midsummer::Actors' -- and thus will still have each set of contacts grouped with the other appropriate contacts.
+There are no security features or concerns related to this proposal above and beyond those specified for roster management in &xmppim; and for private XML storage in JEP-0049.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'roster:delimiter' in its registry of protocol namespaces.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0083: http://www.jabber.org/jeps/jep-0083.html
+
+
+
+
+Updated to reflect pubsub and PEP changes; added implementation notes about multiple resources and avatar synchronization.
Updated to use PEP.
Major modification per list discussion: specified that metadata may include the same avatar in multiple alternate formats; allowed pointers to third-party avatars not available via pubsub or HTTP; changed pixel size restrictions; specified that bytes, content-type, height, id, and width are required metadata; changed type attribute to content-type; made explicit that URLs can be http: or https: URIs; more fully specified protocol, updated the examples, updated the schemas.
Friendly fork per Council discussion: allowed data to be stored in a pubsub data repository or at a URL accessible via HTTP; also split text into publisher and subscriber use cases, specified requirements, added more examples, etc.
Lessen the image requirements. Include the content type in info.
Drastic change to use two nodes on pubsub, allowing for hash updates independently of the data. This makes client caching much easier. Allow only PNG and MNG currently.
Clarified the use of "current" as the item id. Fixed some example errors. Made the interaction with disco more clear. The reason to use pubsub is made more clear as well.
Initial version.
Many communication applications allow for the association of a small image or icon with a user of that application. Usually, such an "avatar" is not intended to be an accurate picture of the user's actual physical appearance, but rather a representation (often fanciful) of the user's desired self-image or a transient state of the user (such as a mood or activity). This document outlines a way to incorporate avatars into current Jabber/XMPP systems by layering this functionality on top of the XMPP &jep0060; extension ("pubsub"), specifically the &jep0163; subset ("PEP"), which is designed for use in the context of XMPP instant messaging and presence systems that conform to &rfc3921;.
+The protocol defined herein uses two pubsub nodes: one node for "metadata" about the avatar state (called the "metadata node") and one for the avatar data itself (called the "data node"). This separation of metadata from data conserves bandwidth and enables both the publisher and the subscriber to cache the avatar data. (For example, a user might toggle between two or three avatars, in which case the user's contacts can display a locally cached version of the images without having to retrieve or receive the full image each time.)
+This protocol also allows storage of avatar data at a URL accessible via HTTP (see &rfc2616;).
Finally, this protocol also enables XMPP applications to optionally integrate with third-party services that host user avatars (e.g., online gaming systems and virtual worlds).
+This document addresses the following use cases for avatar publishers:
+-
+
- Publishing avatar data +
- Updating metadata about the current avatar +
- Disabling avatars +
This document addresses the following use cases for avatar subscribers:
+-
+
- Discovering avatar availability +
- Receiving notification of avatar changes +
- Retrieving avatar data via pubsub +
- Retrieving avatar data via HTTP +
The process for publishing and updating user avatars is as follows:
+-
+
- User creates metadata node +
- User creates data node for "image/png" content-type +
- User publishes avatar data for "image/png" content-type to data node and optionally publishes other content-types to HTTP URLs +
- User publishes notification of updated avatar to metadata node, with ItemID that matches SHA1 hash of image data for "image/png" content-type (note: this is a hash of the image data itself, not the base64-encoded version) +
- Subscribers receive notification +
- Optionally (and if necessary), subscribers retrieve avatar data identified by ItemID from data node using pubsub get-items feature (or via HTTP) +
- Optionally, user disables avatar display. +
This process flow is described more fully in the following sections.
+Note: Before publishing avatar data and metadata, the user MUST determine if his or her server supports the PEP subset of pubsub by following the procedures specified in JEP-0163.
+In order to publish notifications related to its avatar, the user MUST first create a node for his or her avatar metadata:
+The NodeID MUST be "http://jabber.org/protocol/avatar#metadata" and the access model SHOULD be "presence". Note: If the default access model (see JEP-0163) is the same as the desired access model, the user can send an empty <configure/> element rather than including a data form as shown above.
+Next, the user SHOULD create a node for his or her avatar data (however, note that data publication via XMPP is not required since the data could be made available at an HTTP URL):
+If the user creates a data note, the NodeID MUST be "http://jabber.org/protocol/avatar#data" and the access model SHOULD be "presence".
+Before updating the avatar metadata node, the publisher MUST make sure that the avatar data is available at the data node or URL. When publishing the avatar data to the data node, the publisher MUST ensure that the value of the pubsub ItemID is the SHA1 hash of the data for the "image/png" content-type (this is used by the subscriber to determine if a locally cached copy can be displayed).
+The following example illustrates the XML structure to be sent when publishing avatar data to the data node.
+Whenever the publisher wishes to change its current avatar, it MUST update the metadata node.
+The following example shows metadata specifying avatar data that is available in only one format ("image/png") and accessible only at the data node:
+Subscribers to the metadata node would then receive the notification:
+Note the inclusion of &jep0033; information about the publishing resource (see JEP-0163 and JEP-0060 for details).
+Upon receiving the notification, each subscriber SHOULD determine if it has a locally cached copy of that avatar (which it can determine by searching for an image identified by the ItemID). If the subscriber already has a locally cached copy of the avatar image, it MUST NOT retrieve the image data.
+If the subscriber does not have a locally cached copy of the avatar image, it SHOULD retrieve the data. It can do this by sending a pubsub get-items request to the data node, specifying the appropriate ItemID:
+The PEP service running at the user's server then SHOULD return the avatar data:
+If the <info/> element sent to the metadata node possesses a 'url' attribute, the avatar data is hosted at a URL. Therefore, in order to retrieve the avatar image data for that content-type, the requesting entity MUST send an HTTP request to the specified URL. Methods for doing so are out of scope for this document.
+In order to temporarily disable any avatar, the user publishes an empty <stop/> element to the metadata node (this item SHOULD NOT possess an ItemID):
+As before, subscribers to the metadata node would then receive the notification:
+The PEP subset of pubsub requires that there shall exist a one-to-one relationship between namespaces and nodes. Because the protocol defined herein stipulates the use of two nodes (one for avatar data and one for avatar metadata), we define two namespaces, each with a corresponding root element:
+-
+
- <data xmlns='http://jabber.org/protocol/avatar#data'/> +
- <metadata xmlns='http://jabber.org/protocol/avatar#metadata'/> +
These are further specified below.
+The <data/> element is used to communicate the avatar data itself, and only for the "image/png" content-type (support for which is REQUIRED):
+
+ IMAGE DATA
+
+ ]]>
+ The XML character data MUST represent the image data for the avatar with a content-type of "image/png", Base64-encoded in accordance with Section 3 of &rfc3548;. (Note: Line feeds SHOULD NOT be added but MUST be accepted.)
+Support for the <data/> element is REQUIRED.
+The <metadata/> element is used to communicate information about the avatar. There are three allowable children of the <metadata/> element:
+-
+
- <info/> +
- <pointer/> +
- <stop/> +
These are further specified below.
+The <info/> child element is used to communicate avatar metadata:
+
+
+ ]]>
+ The <info/> child element MUST be empty.
+The <info/> child element MUST possess the following attributes:
+-
+
- bytes -- The size of the image data in bytes. +
- height -- The height of the image in pixels. +
- id -- The SHA1 hash of the image data for the specified content-type. +
- type -- The IANA-registered content type of the image data. +
- width -- The width of the image in pixels. +
The <info/> element MAY possess the following attribute:
+-
+
- url -- An http: or https: URI at which the image data file may be found. +
If the <info/> element element does not possess a 'url' attribute, then it is assumed that the data is available at the data node rather than an HTTP URL.
+The <metadata/> root element MAY contain more than one <info/> element. Each <info/> element MUST specify metadata for the same avatar image but in alternate content-types (e.g., "image/png", "image/gif", and "image/jpeg"), and one of the formats MUST be "image/png" to ensure interoperability. The value of the 'type' attribute MUST be an IANA-registered content type of type "image" or "video".
The value of the 'id' attribute MUST be the SHA1 (&rfc3174;) hash of the image data for the specified content-type.
+Support for the <info/> element is REQUIRED.
+The <pointer/> child element is used to point to an avatar that is not published via pubsub or HTTP, but rather is provided by a third-party service such as an online gaming system or virtual world:
+
+
+ ... APPLICATION-SPECIFIC DATA ...
+
+
+ ]]>
+ The <pointer/> element MAY possess the following attributes if the publishing application has the relevant information:
+-
+
- bytes -- The size of the image data in bytes. +
- height -- The height of the image in pixels. +
- id -- The SHA1 hash of the image data for the specified content-type. +
- type -- The IANA-registered content type of the image data. +
- width -- The width of the image in pixels. +
The content of the <pointer/> element MUST be a properly-namespaced child element that specifies information about how to retrieve the avatar from the third-party service. The structure for any such child element is out of scope for this document.
+Even if the <pointer> element is included, it MUST be preceded by at least one instance of the <info/> element so that implementations that do not support the <pointer/> element can display a "fallback" format of the avatar (at a minimum, "image/png").
+Support for the <pointer/> element is OPTIONAL.
+The <stop/> child element is used to signal that avatar publishing has been disabled:
+
+
+ The <stop/> element MUST be empty and MUST NOT possess any attributes.
+Support for the <stop/> element is REQUIRED.
+The following example shows metadata specifying avatar data that is available in multiple formats ("image/png", "image/gif", and "image/mng"), where the "image/png" content-type is available only at the data node and the other content-types are available HTTP URLs:
+The following example shows metadata specifying avatar data that is available in "image/png" at the data node and also with a pointer to an external service.
+A contact can determine if another user publishes avatars using this protocol by sending a &jep0030; items ("disco#items") request to the user's bare JID (&BAREJID;):
+If the user publishes avatar data to an PEP node, the result MUST contain the appropriate items:
+The contact then MAY subscribe to the metadata node following the protocol specified in JEP-0060. However, the contact SHOULD NOT subscribe to the data node (instead, it SHOULD simply retrieve items from that node when needed, as described above).
+Certain restrictions are placed upon the image. First, the image height and width SHOULD be between thirty-two (32) and ninety-six (96) pixels. The suggested size is sixty-four (64) pixels high and sixty-four (64) pixels wide. Images SHOULD be square, but this is not required. Finally, images SHOULD use less than eight (8) kilobytes of data.
+If a user has multiple online resources at the same time, each resource MAY publish a different avatar. A user SHOULD subscribe to his or her own metadata in order to know the avatars that are being published to all resources. The PEP service SHOULD include the replyto address of the publishing resource as shown above in order to facilitate differentiation between per-resource avatars.
+When a user logs in with a new resource and before publishing an avatar, its client SHOULD retrieve its last published avatar using the "get-items" method described in JEP-0060.
+It is the responsibility of the receiving application to determine which avatar format to retrieve (e.g., "image/gif" rather than "image/png") and to determine the appropriate method for retrieval (e.g., HTTP rather than pubsub).
+The receiving application SHOULD NOT scale up an image when displaying it.
+If an avatar is not available for a contact, the receiving MAY display the contact's photo, e.g., as provided in the contact's vCard (see &jep0054;) or other profile information.
+There are no security features or concerns related to this proposal.
+This document makes use of IANA-registered content types, but requires no interaction with &IANA;.
+The ®ISTRAR; shall include 'http://jabber.org/protocol/avatar#data' and 'http://jabber.org/protocol/avatar#metadata' in its registry of protocol namespaces.
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+ Peter Millard, a co-author of this specification from version 0.1 through version 0.7, died on April 26, 2006. The remaining authors are thankful for his work on this specification.
+Added service discovery use case.
Clarified suggested triggers to discourage prospective notifications.
Per a vote of the Jabber Council, advanced status to Draft.
Clarified terminology; specified suggested state changes; removed section on superseding JEP-0022.
Further clarified business rules regarding generation of notifications.
Clarified business rules regarding generation of notifications; added reference to JEP-0155; rewrote introduction; moved previous introductory text to section on superseding JEP-0022.
Removed <initial/> state.
Added optional <initial/> state; added business rule on repetition of notifications; added implementation note.
Made <inactive/> state definition consistent with <paused/> per list discussion; made slight adjustments to wording throughout.
Further clarified state definitions and adjusted suggested event timing.
Clarified the meaning of the <gone/> state; adjusted suggested timing for events.
Added <paused/> state; defined the chat states; clarified the state chart; simplified the business rules.
Clarified that 'type' must be "chat" or "groupchat" for chat state notification messages.
Made Thread IDs optional; made <inactive/> and <gone/> states optional if Thread IDs are not used; removed requirement for explicit service discovery in favor of implicit discovery.
Clarified terminology; added support for groupchat; added several implementation notes.
General cleanup; added schema.
Initial version.
Many instant messaging systems include notifications about the state of one's conversation partner in a one-to-one chat (or, sometimes, in a many-to-many chat). Usually these are limited to notification that one's partner is currently typing -- e.g., the Composing event in JEP-0022 (see &jep0022;). However, a composing event is essentially information about a person's participation in or involvement with the chat "session" and therefore is really a session-level state rather than a per-message event -- e.g., the Delivered and Displayed events in JEP-0022. While the composing event is interesting, the concept of a session-level state can be extended to answer a variety of questions about the participation of a person in a real-time chat conversation, such as:
+-
+
- Has this person paused the composition? +
- Is this person actively paying attention to the chat? +
- Is this person temporarily inactive (i.e., not paying attention right now)? +
- Is this person simply gone (i.e., no longer participating in the chat)? +
To answer such questions, this JEP supplements the traditional composing state by defining four additional chat states (paused, active, inactive, gone), for a total of five states that (it is hoped) together fully describe the possible states of a person's participation in or involvement with a chat conversation.
In essence, chat state notifications can be thought of as a form of chat-specific presence. For example, consider what might happen if a user "loses" a chat window on his desktop; the user might still be interacting with his messaging client (thus never automatically changing his basic presence to "away"), but the user's state with regard to the chat session might change progressively from active to inactive to gone. This information would help the user's conversation partner understand why she has not received a response to her messages in the chat session.
+Chat state notifications can appear in two kinds of &MESSAGE; stanzas:
+-
+
- A "content message" -- that is, a message stanza that contains standard messaging content such as the <body/>, <subject/>, and <thread/> child elements defined in &xmppim; and/or any other properly-namespaced child element(s). +
- A "standalone notification" -- that is, a message stanza that does not contain standard messaging content but instead is intended to specify only the chat state since it contains only a child element qualified by the "http://jabber.org/protocol/chatstates" namespace (or possibly also the XMPP <thread/> element; see the Threads section below). +
The five chat states specified in this document are described below. The suggested triggers and state changes are simply that: suggestions. It is up to the implementation to determine when to generate chat state notifications and which notifications to generate.
+| State | +Definition | +Suggested Triggers | +Suggested State Changes | +
|---|---|---|---|
| <active/> | +User is actively participating in the chat session. | +User accepts an initial content message, sends a content message, gives focus to the chat interface, or is otherwise paying attention to the conversation. | +<inactive/>, <composing/> | +
| <composing/> | +User is composing a message. | +User is interacting with a message input interface specific to this chat session (e.g., by typing in the input area of a chat window). | +<active/>, <paused/> | +
| <paused/> | +User had been composing but now has stopped. | +User was composing but has not interacted with the message input interface for a short period of time (e.g., 5 seconds). |
+ <active/>, <composing/>, <inactive/> | +
| <inactive/> | +User has not been actively participating in the chat session. | +User has not interacted with the chat interface for an intermediate period of time (e.g., 30 seconds). | +<active/>, <gone/> | +
| <gone/> | +User has effectively ended their participation in the chat session. | +User has not interacted with the chat interface, system, or device for a relatively long period of time (e.g., 2 minutes), or has terminated the chat interface (e.g., by closing the chat window). | +<active/> | +
The following figure attempts to capture the possible state transitions in visual form.
+ ACTIVE <--> COMPOSING
+ | ^ |
+ | | |
+ + <------ PAUSED <-----> +
+ ]]>
+ Note: All four of the states shown may transition to the GONE state.
+If an entity supports the Chat State Notifications protocol, it MUST advertise that fact in its responses to &jep0030; information ("diso#info") requests by returning a feature of "http://jabber.org/protocol/chatstates":
+In addition, support for the Chat States Notification protocol can be determined through the dynamic profile of Service Discovery defined in &jep0115;.
+Before generating chat state notifications, a User SHOULD explicitly discover whether the Contact supports the protocol defined herein (as described in the Discovering Support section of this document) or explicitly negotiate the use of chat state notifications with the Contact (via &jep0155;).
+In the absence of explicit discovery or negotiation, the User MAY implicitly request and discover the use of chat state notifications in a one-to-one chat session by adhering to the following business rules:
+-
+
- If the User desires chat state notifications, the initial content message sent to the Contact MUST contain a chat state notification extension, which SHOULD be <active/>. +
- Until receiving a reply to the initial content message (or a standalone notification) from the Contact, the User MUST NOT send subsequent chat state notifications to the Contact. +
- If the Contact replies to the initial content message but does not include a chat state notification extension, the User MUST NOT send subsequent chat state notifications to the Contact. +
- If the Contact replies to the initial content message and includes an <active/> notification (or sends a standalone notification to the User), the User and Contact SHOULD send subsequent notifications for supported chat states (as specified in the next subsection) by including an <active/> notification in each content message and sending standalone notifications for the chat states they support (at a minimum, the <composing/> state). +
The foregoing rules imply that the sending of chat state notifications is bidirectional (i.e., both User and Contact will either send or not send chat state notifications) rather than unidirectional (i.e., one of the conversation partners will send chat state notifications but the other will not); this is intentional.
+| Chat State | +Requirement | +
|---|---|
| <active/> | +MUST | +
| <composing/> | +MUST | +
| <paused/> | +SHOULD | +
| <inactive/> | +SHOULD | +
| <gone/> | +SHOULD | +
A client MUST allow the user to configure whether he or she wants to send chat state notifications.
+Note: Support for only <active/> and <composing/> is functionally equivalent to supporting the Composing event from JEP-0022.
+Even if the user types continuously for a long time (e.g., while composing a lengthy reply), the client MUST NOT send more than one standalone <composing/> notification in a row. More generally, a client MUST NOT send a second instance of any given standalone notification (i.e., a standalone notification MUST be followed by a different state, not repetition of the same state). However, every content message SHOULD contain an <active/> notification.
+-
+
- This protocol MUST NOT be used with stanzas other than &MESSAGE;. +
- This protocol SHOULD NOT be used with message types other than "chat" or "groupchat". +
- The 'type' attribute for content messages and standalone notifications SHOULD be set to a value of "chat" (for one-to-one sessions) or "groupchat" (for many-to-many sessions). +
- A chat session MAY span multiple user sessions (i.e., chat state is orthogonal to the availability and presence of one's conversation partner), although this is unlikely given the suggested timing of event triggers. +
Chat state notifications MAY be sent in the context of groupchat rooms (e.g., as defined in &jep0045;). The following business rules apply:
+-
+
- A client MAY send chat state notifications even if not all room occupants do so. +
- A client SHOULD NOT generate <gone/> notifications. +
- A client SHOULD ignore <gone/> notifications received from other room occupants. +
Note: Use of chat state notifications in the context of groupchat may result in multicasting of such notifications. Forewarned is forearmed.
+-
+
- A message stanza MUST NOT contain more than one child element qualified by the 'http://jabber.org/protocol/chatstates' namespace. +
- A message stanza that contains standard messaging content -- i.e., the <body/>, <subject/>, and <thread/> child elements defined in &xmppim; and/or any other properly-namespaced child element(s) -- SHOULD NOT contain a chat state notification extension other than <active/>. +
- A message stanza that does not contain standard messaging content and is intended to specify only the chat state MUST NOT contain any child elements other than the chat state notification extension, which SHOULD be a state other than <active/>; however, if threads are used (see below) then the standalone notification MUST also contain the <thread/> element. +
While chat state notifications provide a mechanism for managing chat threads (i.e., the <thread/> element), support for threads is OPTIONAL. However, if all of the clients participating in a chat both support and use threads, the following additional business rules apply:
+-
+
- Clients MUST copy back Thread IDs (i.e., the value of the <thread/> element) in any replies. +
- When a client terminates a one-to-one chat session (e.g., when a user closes the chat session interface), it MUST generate a <gone/> event. +
- Upon receiving a <gone/> event, a client MUST NOT re-use the same Thread ID and MUST generate a new Thread ID for any subsequent chat messages sent to the conversation partner. +
Servers in constrained network environments (e.g., serving small-footprint clients via &jep0025; or &jep0124;) and services that rebroadcast message stanzas (e.g., Multi-User Chat services) MAY process standalone notifications differently from other messages. In particular, a server or service MAY refuse to deliver standalone notifications to its users, and SHOULD NOT store them offline. In contrast to JEP-0022, chat state notifications are completely the responsibility of the client, and MUST NOT be generated by a server or service.
+In the following conversation, both User and Contact support chat state notifications.
+Because the User now knows that the Contact supports chat state notifications, the User can send other notification types.
+And so forth.
+The following conversation flow illustrates in more detail the workings of chat state notifications (in this case also using threads).
+At this point Juliet's client knows that Romeo's client supports chat state notifications. Thus she replies to the initial content message and her client includes a notification that her state is <active/>:
+And so the conversation continues. After a while, Juliet asks a question that brings Romeo up short. Romeo begins composing a reply to Juliet's heartfelt question, and his Jabber client notifies Juliet that he is composing a reply.
+Romeo realizes his reply is too rash and pauses to choose the right words; after some (configurable) time period, his Jabber client senses the delay and sends a state of <paused/>.
+Romeo starts composing again, and his Jabber client sends a <composing/> notification to Juliet's client.
+Romeo finally sends his reply.
+The conversation ebbs and flows, waxes and wanes, until Juliet is called away by her Nurse...
+We suppose that Juliet minimizes the chat window, so her client generates an <inactive/> notification:
+When she returns and brings the window up again, her client generates an <active/> notification:
+The conversation continues, but Juliet is called away again by that nagging Nurse:
+We suppose that Juliet closes the chat window, so her client generates a <gone/> notification:
+Romeo's client now considers the chat thread to be over and generates a new Thread ID when he sends a new message:
+When Juliet returns to her computer on the balcony, she finds the new message from Romeo. When she finishes her reply, her client includes both an <active/> notification and the new Thread ID with the body of her reply:
+And so forth.
+My, these star-crossed lovers do go on, don't they?
+A client that receives a chat state notification should expect that it may never receive another message or chat state notification from the other entity (e.g., because the other entity crashes or goes offline) and should plan accordingly.
+The states of a chat thread may reveal information about a user's interaction with his or her computer, including his or her physical presence; such information SHOULD NOT be revealed to conversation partners who are not trusted to know such information. Client implementations MUST provide a mechanism that enables the user to disable chat state notifications if desired.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'http://jabber.org/protocol/chatstates' in its registry of protocol namespaces.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0085: http://www.jabber.org/jeps/jep-0085.html
+
+
+
+
+
+
+
+
+
+ ]]>
+&xmppcore; documents formats and semantics for stanza error responses. The XML of these errors is different from that of errors that have been traditionally used on the Jabber network.
+Until such time that all entities support these new XMPP-style errors, there is a need for entities to issue errors that are understandable by both legacy and XMPP-compliant entities. This document outlines an appropriate mapping to allow this to occur.
+This document can also be used by implementers of legacy protocols to determine which XMPP-style error should be used when only a legacy error code is documented.
+XMPP-compliant entities can issue errors to legacy clients and servers by adding a "code" attribute to the <error/> element it sends.
+Legacy entities receiving this error will use the "404" to determine what happened, while XMPP-compliant entities will use the error type and the child element that specifies the condition.
+ +XMPP-compliant entities should add the following error codes to errors if they want them to be understood by legacy entities:
+ +| XMPP error condition | +XMPP error type | +Legacy error code | +
|---|---|---|
| <bad-request/> | +modify | +400 | +
| <conflict/> | +cancel | +409 | +
| <feature-not-implemented/> | +cancel | +501 | +
| <forbidden/> | +auth | +403 | +
| <gone/> | +modify | +302 (permanent) | +
| <internal-server-error/> | +wait | +500 | +
| <item-not-found/> | +cancel | +404 | +
| <jid-malformed/> | +modify | +400 | +
| <not-acceptable/> | +modify | +406 | +
| <not-allowed/> | +cancel | +405 | +
| <not-authorized/> | +auth | +401 | +
| <payment-required/> | +auth | +402 | +
| <recipient-unavailable/> | +wait | +404 | +
| <redirect/> | +modify | +302 (temporary) | +
| <registration-required/> | +auth | +407 | +
| <remote-server-not-found/> | +cancel | +404 | +
| <remote-server-timeout/> | +wait | +504 | +
| <resource-constraint/> | +wait | +500 | +
| <service-unavailable/> | +cancel | +503 | +
| <subscription-required/> | +auth | +407 | +
| <undefined-condition/> | +[any] | +500 | +
| <unexpected-request/> | +wait | +400 | +
Implementors of legacy protocols should use the appropriate XMPP-style error alongside a legacy error code as specified in the following table:
+ +| Legacy error code | +Meaning | +XMPP error condition | +XMPP error type | +
|---|---|---|---|
| 302 | +Redirect | +<redirect/> (temporary) or <gone/> (permanent) | +modify | +
| 400 | +Bad Request | +<bad-request/>
+ |
+ modify | +
| 401 | +Not Authorized | +<not-authorized/>
+ |
+ auth | +
| 402 | +Payment Required | +<payment-required/> | +auth | +
| 403 | +Forbidden | +<forbidden/> | +auth | +
| 404 | +Not Found | +<item-not-found/>
+ |
+ cancel | +
| 405 | +Not Allowed | +<not-allowed/> | +cancel | +
| 406 | +Not Acceptable | +<not-acceptable/>
+ |
+ modify | +
| 407 | +Registration Required | +<registration-required/> | +auth | +
| 408 | +Request Timeout | +<remote-server-timeout/> | +wait | +
| 409 | +Conflict | +<conflict/> | +cancel | +
| 500 | +Internal Server Error | +<internal-server-error/>
+ |
+ wait | +
| 501 | +Not Implemented | +<feature-not-implemented/> | +cancel | +
| 502 | +Remote Server Error | +<service-unavailable/> | +wait | +
| 503 | +Service Unavailable | +<service-unavailable/> | +cancel | +
| 504 | +Remote Server Timeout | +<remote-server-timeout/> | +wait | +
| 510 | +Disconnected | +<service-unavailable/> | +cancel | +
Mapping legacy error codes to XMPP-style errors is an inexact science, and there are likely to be inconsistencies in some places. However, it is the authors' belief that the mapping presented in this document will be adequate for the majority of cases, and will help smooth the migration to XMPP-compliant implementations.
++ As more people begin to make use of streams in Jabber, there becomes a need + for more descriptive negotiation of which stream to use. This JEP provides + a method to negotiate a stream and provide some meta-information about the + streams usage. +
+-
+
- + The defined protocol will allow for negotiation of a common stream. + +
- + The defined protocol will allow for meta-information to be sent about the + stream usage. + +
- + The defined protocol will not be required for stream usage. + +
+ Sender wishes to interact with another user, using a method that requires + streams. +
++ Primary Flow: +
+-
+
- + Sender discovers if Receiver implements the desired profile. [E1] + +
- + Sender offers a stream initiation. [E2] + +
- + Receiver accepts stream initiation. + +
- + Sender uses the negotiated stream and profile to send the information. + +
+ Error Conditions: +
+-
+
- + The Receiver does not support the desired profile, EUC + +
- + Receiver rejects the stream initiation, EUC + +
+ Before a Stream Initiation is attempted the Sender should be sure that the + Receiver supports both Stream Initiation and the specific profile that they + wish to use. This is discovered by using &jep0030;: +
++ The Receiver will advertise the "http://jabber.org/protocol/si" namespace as + a feature to represent they implement this JEP. The specific profiles can + be found by looking for + "http://jabber.org/protocol/si/profile/profile-name". Shown in the result + is a potential file transfer profile: +
++ Now that the Sender is sure that the Receiver support Stream Initiation they + send the offer: +
++ At this point the Receiver can view the headers and other information to + decide if they wish to accept the Stream Initiation. If they accept they + MUST select one of the presented stream types to use. If none of the stream + types are acceptable the Receiver MUST reply with an error: +
++ If the Receiver has accepted the Stream Initiation the Sender may then used + the semantics defined by the selected stream and start the usage. +
+ ++ While Stream Initiation itself is helpful, it makes much more sense when + what is being transported over the stream is known. Knowing this + allows the Receiver to make a more educated choice about whether or not to + accept the stream. This information is transported in Stream Initiation + through a profile. A profile is a series of required and + optional headers that describe the stream data or how the stream is to be + used. Each Stream Initiation MUST have only one profile, so the stream + usage is kept clear. +
+
+ Creating a profile is fairly simple. First, a name is chosen, the
+ complete name is formatted like:
+
+ http://jabber.org/protocol/si/profile/profile-name
+
+ The complete name is what is presented in information discovery requests
+ in order to show that the profile is supported. It is also used for the
+ <si> profile attribute. Next, the information for the headers is
+ decided upon. Each piece of information will be transported in a
+ <header> tag. The name attribute is a descriptive key that can be
+ looked up at the Jabber Registrar or JEP describing the profile. The
+ actual data in the <header> is the fact related to the name
+ attribute. It must also be stated whether the header is required or
+ optional.
+
+ This JEP does not define any profiles, nor does it place any restrictions + on what type of information a profile should detail. This JEP also does + not place restrictions on what may be placed in a <header>. Other + JEPs will define profiles to be used with Stream Initiation. +
++ While Stream Initiation is not directly required for stream usage, it does + provide many benefits. In order to fully appreciate these benefits, + streams must link the Stream Initiation to the stream. The id + attribute of the <si> node is intended to provide this link. It is + out of scope of this JEP to define how streams will make use of this + facility, but it does suggest some methods: +
-
+
-
+ Transport the Stream Initiation id with the stream negotitation as a
+ namespaced attribute, such as:
+
+ +++ + ]]> +
+ -
+ Transport the Stream Initiation id in a namespaced tag, such as:
+
+ +++ + + ]]> +
+
+ The attributes and data of <si> are fairly simple: +
-
+
- + id - An opaque identifier generated by the Sender. + +
- + mime-type - The mime-type of the data being negotiated, + selected by Sender. + +
- + profile - The profile's fulle name, selected by Sender. + +
+ When the Sender is offering a Stream Initiation all of the attributes must + be present. The data MUST contain the required profile headers and the + feature negotiation for the stream MUST be present with at least one + option. The optional profile headers MAY also be in the node data. +
++ When the Receiver accepts a Stream Initiation the id attribute MUST be + present, all other attributes MUST NOT be present. The selected stream + MUST be in the feature negotiation for the stream. There MUST only be one + selected stream. +
++ There are two error codes that are used. Following are the conditions, + meanings and data: +
-
+
- + Declining Transfer (403): During the Stream Initiation + the Receiver may decline the transfer by sending the 403 error. The + <error/> CDATA MAY contain a descriptive reason why, but is not + necessary. + +
- + No Available Methods (406): When the Sender presents the + available stream methods, and the Receiver can not use any of them, + they send a 406 error. The <error/> CDATA is not important. + +
+ Data security concerns are left to the profiles to define. Wire security + concerns are left to the stream definitions. +
++ This JEP uses the MIME types as recorded by IANA, but no other direct + interaction is necessary. +
++ The "http://jabber.org/protocol/si" namespace will be registered. + The registrar will track header profiles for different stream initiation + uses. +
+To follow.
+To follow.
+Webtabs are a way for servers to specify a number to web pages which can be used in clients and displayed like the web-based services in Yahoo Messenger, MSN Messenger and JIM. This enables a server administrator to easily create services for Jabber clients and also help to integrate Jabber clients with existing web-based applications.
+The motivations for this JEP are:
+-
+
- To enable servers to specify a selection of web-based services for use in a client. +
- To allow easy integration with existing web-based systems. +
- To give more value to people's Jabber services over another's. +
- To allow the creation of virtually limitless web-based services for Jabber clients without clients needing to be specifically coded to support that service. +
&jep0030; SHALL be used for discovering support for webtabs on servers.
+It is RECOMMENDED that the jabber server itself (JSM in jabberd) serves the webtab list, but if desired by the server implementor they MAY be served by a separate host/component.
+The list of available web tabs is retrieved using the following protocol:
+The webtab contains CDATA which is the URL of the webtab, the webtab is an HTML page retrieved from an HTTP server using a standard browser which you embed into your client UI using a technique such as the IWebBrowser2 control interface on windows which allows you to embed either the IE or Gecko engines depending on what you have installed, this data is REQUIRED.
+The "type" attribute tells the client what the service being provided is, this allows a client to display icons on the tabs to represent them, handling of the type in clients is OPTIONAL, inclusion of this attribute is REQUIRED (See "Jabber Registrar Considerations" for examples of values for this attribute).
+The "name" attribute is the offical name of a particular service this can be displayed as the tab name, this attribute is REQUIRED.
+The "id" attribute is a unique identifier for a service which you can use to refer to it later, used for when using private storage to store a preference to which tabs should be visible, this attribute is REQUIRED.
+&jep0049; SHALL be used for storing webtab preferences.
+The "id" attribute matches the "id" attribute from the list of webtabs, this attribute is used to match these preferences to the webtab in question, this attribute is REQUIRED.
+The "visible" attribute tells the client that a tab SHOULD or SHOULD NOT be hidden, a client SHOULD provide an interface for managing the visibility of the tabs and updating the preferences appropriately, this attribute is REQUIRED.
+It is RECOMMENDED that a mechanism such as &jep0101; be used for automatic service authentication.
+The following guidelines may assist client developers.
+-
+
- Use the "type" attribute as a way of determining what services a webtab provides, you can then use this to possibly display appropriate icons to represent the webtab in the client UI. +
- MUST use the "name" attribute when you have to refer to a webtab by name. +
- MUST use the private storage specification provided to store information about which tabs SHOULD be visible. +
It is recommended that JEP-0101 be used to provide transparent authentication of the webtabs.
+No IANA interaction required.
+The ®ISTRAR; will need to register the new namespace of "http://jabber.org/protocol/webtab" and possibly the list of offical types will need to be managed too.
+| Type | +Purpose | +
|---|---|
| Web based email | +|
| calendar | +Web based calendar | +
| bookmark | +Web based bookmark management service | +
| news | +General news headlines | +
| news/sport | +Sport headlines | +
Generic Alerts is a way to extend headlines to allow functionality similar to .NET Alerts.
+The motivations for this JEP are:
+-
+
- To allow services to send alerts to users, e.g. like an auction notifying you when you are outbid or that you have won +
Generic Alerts extend headline messages to specify such things as a logo (32x32 png) and url to goto when the alert is clicked:
+The following guidelines may assist client developers.
+-
+
- The existance of an alert element of the namespace 'http://jabber.org/protocol/alert' means this is an alert and not a normal headline. +
- Alerts should be displayed differently, possibly in toast popups. +
- The logo is an optional graphic to display representing the service being alerted on, e.g. ebay logo. +
- When clicked on the users web browser will be opened to the specified url. +
None.
+No IANA interaction required.
+The ®ISTRAR; will need to register the new namespace of "http://jabber.org/protocol/alert".
+The Jabber protocols have long included a method for discovering the time at another entity's location. This method makes use of the 'jabber:iq:time' namespace and has been documented variously in Internet-Drafts and elsewhere. Because this protocol is not required by &rfc2779;, the 'jabber:iq:time' namespace was removed from &xmppim;. This JEP fills the void for canonical documentation.
+The 'jabber:iq:time' namespace provides a standard way for Jabber entities to exchange information about the local time (e.g., to "ping" another entity or check network latency). The information is communicated in a request/response pair using an &IQ; element that contains a &QUERY; scoped by the 'jabber:iq:time' namespace. The following children of the &QUERY; element are allowed in an IQ result:
+-
+
- <utc/> -- The time (in UTC) according to the responding entity. The format SHOULD be "CCYYMMDDThh:mm:ss" (see below). This element is REQUIRED in an IQ result. +
- <tz/> -- The time zone in which the responding entity is located. This can be either a three-letter acronym or the full natural-language name of the timezone.
A list of time zone names and abbreviations is located at <http://www.timeanddate.com/library/abbreviations/timezones/>. This element is OPTIONAL in an IQ result.
+ - <display/> -- The time in a human-readable format. This element is OPTIONAL in an IQ result. +
The standard error conditions described in &jep0086; apply (e.g., service unavailable if the entity does not support the namespace).
+&jep0082; defines the lexical representation of dates, times, and datetimes in Jabber protocols. Unfortunately, the 'jabber:iq:time' namespace predates that definition, and uses a datetime format ("CCYYMMDDThh:mm:ss") that is inconsistent with JEP-0082 and &w3xmlschema2;. Because a large base of deployed software uses the old format, this JEP specifies that applications using 'jabber:iq:time' SHOULD use the old format, not the format defined in JEP-0082. In addition, note well that the datetime provided in the <utc/> element is explicitly UTC and therefore SHOULD NOT include the ending 'Z' character required by &iso8601;.
+There are no security features or concerns related to this proposal.
+This JEP requires no interaction with &IANA;.
+The 'jabber:iq:time' namespace is registered in the protocol namespaces registry maintained by the ®ISTRAR;.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0090: http://www.jabber.org/jeps/jep-0090.html
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+The Jabber protocols have long included a method for indicating that a message or presence stanza was delayed in being delivered (e.g., because it was stored offline). This method makes use of the 'jabber:x:delay' namespace and has been documented variously in Internet-Drafts and elsewhere. Because this protocol is not required by &rfc2779;, the 'jabber:x:delay' namespace was removed from &xmppim;. This JEP fills the void for canonical documentation.
+The 'jabber:x:delay' namespace is used to provide timestamp information about data stored for later delivery. The most common uses of this namespace are to stamp:
+-
+
- A message that is sent to an offline entity and stored for later delivery. +
- The last presence update sent by a connected node to a host. +
- Messages cached by a multi-user chat room for delivery to new participants when they join the room. +
Information about the delivery delay is communicated by adding to the <message/> or <presence/> stanza one and only one <x/> child qualified by the 'jabber:x:delay' namespace. This information is added by the server or component that delivers the information. The following attributes are allowed on the <x/> element:
+-
+
- from -- The Jabber ID of the entity that originally sent the XML stanza or that delayed the delivery of the stanza (for example, the address of a multi-user chat room). This attribute is RECOMMENDED. +
- stamp -- The time when the XML stanza was originally sent. The format SHOULD be "CCYYMMDDThh:mm:ss" (see A Note on Time Formats below). This attribute is REQUIRED. +
In addition, the <x/> element MAY contain XML character data that provides a natural-language description of the reason for the delay.
+&jep0082; defines the lexical representation of dates, times, and datetimes in Jabber protocols. Unfortunately, the 'jabber:x:delay' namespace predates that definition, and uses a datetime format ("CCYYMMDDThh:mm:ss") that is inconsistent with JEP-0082 and &w3xmlschema2;. Because a large base of deployed software uses the old format, this JEP specifies that applications using 'jabber:x:delay' SHOULD use the old format, not the format defined in JEP-0082. The timezone is be understood as UTC.
+Data qualified by the 'jabber:x:delay' can expose information about the sender's presence on the network at some time in the past. However, this introduces no new vulnerabilities, since the same information would have been available in real time.
+This JEP requires no interaction with &IANA;.
+The 'jabber:x:delay' namespace is included in the protocol namespaces registry maintained by the ®ISTRAR;.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0091: http://www.jabber.org/jeps/jep-0091.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+The Jabber protocols have long included a method for discovering version information about the software running at another entity's JID. This method makes use of the 'jabber:iq:version' namespace and has been documented variously in Internet-Drafts and elsewhere. Because this protocol is not required by &rfc2779;, the 'jabber:iq:version' namespace was removed from &xmppim;. This JEP fills the void for canonical documentation.
+The 'jabber:iq:version' namespace provides a standard way for Jabber entities to exchange information about the software version used by the entities. The information is communicated in a request/response pair using an <iq/> element that contains a <query/> scoped by the 'jabber:iq:version' namespace. The following children of the <query/> are allowed in an IQ result:
+-
+
- <name/> -- The natural-language name of the software. This element is REQUIRED in a result. +
- <version/> -- The specific version of the software. This element is REQUIRED in a result. +
- <os/> -- The operating system of the queried entity. This element is OPTIONAL in a result. +
The standard error conditions described in &jep0086; apply (e.g., service unavailable if the entity does not support the namespace).
+There are no security features or concerns related to this proposal.
+This JEP requires no interaction with &IANA;.
+The 'jabber:iq:version' namespace is registered in the protocol namespaces registry maintained by the ®ISTRAR;.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0092: http://www.jabber.org/jeps/jep-0092.html
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+The Jabber protocols have long included a method for sending roster items to another entity. This method makes use of the 'jabber:x:roster' namespace and has been documented variously in Internet-Drafts and elsewhere. Because this protocol is not required by &rfc2779;, the 'jabber:x:roster' namespace was removed from &xmppim;. This JEP fills the void for canonical documentation.
+NOTE WELL: This JEP has been superseded by &jep0144;.
+The 'jabber:x:roster' namespace (which is not to be confused with the 'jabber:iq:roster' namespace) is used to send roster items from one Jabber entity to another. A roster item is sent by adding to the <message/> element an <x/> child scoped by the 'jabber:x:roster' namespace. This <x/> element MUST contain at least one <item/> child elements (one for each roster item to be sent).
+Each <item/> element may possess the following attributes:
+-
+
- jid -- The Jabber Identifier of the contact being sent. This attribute is REQUIRED. +
- name -- A natural-language nickname for the contact. This attribute is OPTIONAL. +
Each <item/> element MAY also contain one or more <group/> children specifying the natural-language name of a user-specified group, for the purpose of categorizing this contact into one or more roster groups.
+There are no security features or concerns related to this proposal.
+This JEP requires no interaction with &IANA;.
+The 'jabber:x:roster' namespace is registered in the protocol namespaces registry maintained by the ®ISTRAR;.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0093: http://www.jabber.org/jeps/jep-0093.html
+
+ NOTE WELL: This protocol has been superseded by JEP-0144
+ http://www.jabber.org/jeps/jep-0144.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Over the years there have been three different protocols used in the Jabber community to discover information about other entities on the network. The most recent protocol, and the only one that is standards-track, is &jep0030;. The protocol prior to Service Discovery was &jep0011;. Before Jabber Browsing, there was the 'jabber:iq:agents' namespace. This JEP provides historical documentation for the Agent Information protocol.
+Note well that the Agent Information protocol is deprecated; applications desiring such functionality SHOULD implement Service Discovery. This JEP is provided only in order to ensure complete documentation of earlier protocols.
+The 'jabber:iq:agents' namespace was used to obtain a list of entities associated with another Jabber Entity; most commonly, the list of trusted services associated with a specific host.
+When 'jabber:iq:agents' is used, information about available agents properties is contained within a <query/> element that is scoped by the 'jabber:iq:agents' namespace. The reply to a request of type "get" in the 'jabber:iq:agents' namespace contains zero or more <agent/> elements. The <agent/> element has a required 'jid' attribute that contains the Jabber Identifier of each agent. The <agent/> element in turn may contain the following children:
+-
+
- name - a natural-language name for the service +
- description - a short phrase describing the service +
- transport - inclusion of this empty element signals that the service is a gateway to a non-Jabber instant messaging system +
- groupchat - inclusion of this empty element signals that the service is multi-user chat service +
- service - the CDATA of this element specifies the type of gateway (aim, icq, irc, msn, yahoo), the type of conferencing service (public or private), or user directory (jud); these values were never standardized and are not registered with the Jabber Registrar +
- register - inclusion of this empty element signals that the service supports registration +
- search - inclusion of this empty element signals that the service supports searching +
There are no security features or concerns related to this proposal.
+This JEP requires no interaction with &IANA;.
+No action on the part of the ®ISTRAR; is necessary as a result of this JEP, since 'jabber:iq:agents' is already a registered namespace.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+As the Jabber protocols are extended beyond basic messaging and presence, the need has arisen for a generic protocol that can be used to negotiate content streams between any two entities. Such streams might be in-band, but more likely will be out-of-band, binary streams used in applications such as file transfer, voice chat, and video conferencing. This JEP provides a method for negotiating such streams, including meta-information about the intended usage of the stream.
+-
+
- The defined protocol will allow for negotiation of a common stream. +
- The defined protocol will allow for meta-information to be sent about the stream usage. +
- The defined protocol will not be required for stream usage. +
The process for stream negotiation is as follows:
+-
+
- Sender discovers if Receiver implements the desired profile. [E1] +
- Sender offers a stream initiation. [E2] +
- Receiver accepts stream initiation. +
- Sender and receiver prepare for using negotiated profile and stream, EUC +
Error Conditions:
+-
+
- The Receiver does not support the desired profile, EUC +
- Receiver rejects the stream initiation, EUC +
Before a Stream Initiation is attempted the Sender should be sure that the Receiver supports both Stream Initiation and the specific profile that they wish to use. This is typically accomplished using &jep0030;:
+The Receiver advertises the "http://jabber.org/protocol/si" namespace as a feature to represent that they implement this JEP. The specific profiles are also announced this way; they can be found by looking for "http://jabber.org/protocol/si/profile/profile-name". Shown in the result is a potential file transfer profile:
+Once support is determined, the Sender starts the negotiation with the Receiver by sending an &IQ; stanza of type "set", such as in the following example from &jep0096;:
+At this point the Receiver can view the profile and other information to decide if they wish to accept the Stream Initiation. If acceptable the Receiver MUST select one of the presented stream types to use.
+If the profile describes data to be sent back in the result it MUST be present as described in the profile's JEP.
+If none of the stream types are acceptable, or if the profile is not understood, the Receiver MUST reply with a "bad request" error:
+If the Receiver rejects the request, they reply with a "forbidden" error:
+At this point, the Sender and Receiver make any preparations necessary for the stream to be used. The exact process is specific to each protocol, and is beyond the scope of this JEP. This step now marks the end of SI's responsibilities.
+The <si/> element is the root element for this protocol. It is an identifiable container for all the information necessary for negotiation and signalling. It contains attributes for the identifier, intended MIME-type, and profile. The contents convey stream-negotation and profile information.
+The "id" attribute is an opaque identifier. This attribute MUST be present on type='set', and MUST be a valid string. This SHOULD NOT be sent back on type='result', since the <iq/> "id" attribute provides the only context needed. This value is generated by the Sender, and the same value MUST be used throughout a session when talking to the Receiver.
+The "mime-type" attribute identifies the MIME-type for the data across the stream. This attribute MUST be a valid MIME-type as registered with &IANA; (specifically, as listed at <http://www.iana.org/assignments/media-types>). During negotiation, this attribute SHOULD be present, and is otherwise not required. If not included during negotiation, its value is assumed to be "binary/octect-stream".
+The "profile" attribute defines the SI profile in use. This value MUST be present during negotiation, and is the namespace of the profile to use.
+When the Sender first negotiates a Stream Initiation, all of the attributes SHOULD be present, and the id" and "profile" MUST be present. The contents MUST contain one profile, in the namespace declared in the "profile" attribute, and the feature negotiation for the stream. The feature negotiation MUST contain at least one option and use the field var "stream-method".
+When the Receiver accepts a Stream Initiation, the <si/> element SHOULD NOT possess any attributes. The selected stream MUST be in the feature negotiation for the stream. There MUST only be one selected stream.
+To simplify the discussion on error conditions, this document uses the following mapping between namespace URIs and namespace prefixes
| Prefix | +URI | +
|---|---|
| xmpp | +urn:ietf:params:xml:ns:xmpp-stanzas | +
| si | +http://jabber.org/protocol/si | +
Below are the most common errors that can result.
+| Error Code | +Error Type | +General Condition | +Specific Condition | +Description | +
|---|---|---|---|---|
| 400 | +cancel | +<xmpp:bad-request/> | +<si:no-valid-streams/> | +None of the available streams are acceptable. | +
| 400 | +modify | +<xmpp:bad-request/> | +<si:bad-profile/> | +The profile is not understood or invalid. The profile MAY supply a profile-specific error condition. | +
| 403 | +cancel | +<xmpp:forbidden/> | +NONE | +The stream is rejected. | +
For further information about the relationship between XMPP error handling and "legacy" (HTTP-style) error codes, refer to &jep0086;.
+Stream Initiation on its own is of limited use; the Receiver almost always requires some reason for SI. Knowing this allows the Receiver to make a more educated choice about whether or not to accept the stream. This information is provided in Stream Initiation via a profile. A profile is a collection of information that describes the reason for and structure of the stream data, including what the data represents and what stream protocols are expected to be supported.
+The initial request for Stream Initiation MUST have only one profile, and this profile is in its own namespace. The profile is indicated not only by the presence of a "root" element in that particular namespace, but also be the "profile" attribute in <si/> The SUGGESTED format for profile namespaces is:
+http://jabber.org/protocol/si/profile/profile-name
+ The information that the profile presents SHOULD be defined in an official JEP. The JEP defining the profile SHOULD contain explanations of what the profile consists of and MUST define the profile in a complete manner using DTD, Schema or another appropiate definition language.
+A profile SHOULD define what stream protocols MUST be supported, and MUST define what stream protocols MAY be supported. If a profile specifies only a single stream protocol that MUST be supported (even if others MAY also be supported), the "fneg" for the stream protocol may be omitted from the initial <si/>; the receiving entity then assumes the stream protocol that MUST be supported is the one to use.
+This JEP does not define any profiles, nor does it place any restrictions on what type of information a profile should detail. Other JEPs will define profiles to be used with Stream Initiation.
+While Stream Initiation is not directly required for stream usage, it does provide many benefits. In order to fully appreciate these benefits, streams must link the Stream Initiation to the stream. The "id" attribute transported on the <si/> element is intended to do this. Once a session is fully negotiated, the value of the <si/> "id" attribute is used during the actual stream negotiation as the protocol's stream identifier attribute.
+To be compatible to this JEP, a stream protocol MUST define a stream identifier (typically "sid"), which MUST have a unique string representation. The stream protocol MUST be able to use any string identifier chosen during Stream Initiation, as long as the sending party does not use the same identifier more than once.
++ Data security concerns are left to the profiles to define. Wire security + concerns are left to the stream definitions. +
++ This JEP uses the MIME types as recorded by the IANA, but no direct + interaction with the IANA is necessary. +
+The ®ISTRAR; includes the 'http://jabber.org/protocol/si' namespace in its registry of protocol namespaces.
+The Jabber Registrar shall maintain a registry of stream initiation profiles, located at <http://www.jabber.org/registrar/si-profiles.html>. Any such profile defined in a Jabber Enhancement Proposal MUST be submitted to the Jabber Registrar; profiles defined in non-standard protocol extensions SHOULD be submitted to the Jabber Registrar.
+
+ The profile name
+ The JEP or other document that defines the profile
+ A natural-language description of the profile
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0095: http://www.jabber.org/jeps/jep-0095.html
+
+
+
+
+
+
+ This is the root content element. All other elements in
+ this namespace are for communicating error information.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+The traditional mechanism for transferring files in the Jabber community is the &jep0066; protocol. That protocol has several drawbacks:
+-
+
- It is not reliable. +
- It does not work when one of the parties is behind a firewall. +
- It provides limited metadata about files to be exchanged. +
The current document defines a profile of &jep0095; that solves the problems with out-of-band data, thus providing a robust, reliable mechanism for file transfers over the Jabber network. Implementors are referred to JEP-0095 regarding the underlying concepts of stream initiation.
+-
+
- Enable seamless file transfer, including fall-back mechanisms as appropriate. +
- Ensure that the profile will work even when one or both parties are behind a firewall. +
- Define a full-featured set of metadata for file transfers, including the following:
+
-
+
- description +
- size +
- name +
- date +
- hash +
+ - Optionally support ranged transfers. +
+ The file transfer profile is in the + "http://jabber.org/protocol/si/profile/file-transfer" namespace. + The profile is fairly simple: it consists of the root element + with the possibility of one child describing the optional ranged transfers. +
++ The root element is <file> and has four attributes. The attributes + are used only during the offer stage of stream initiation: +
-
+
- size - The size, in bytes, of the data to be sent. +
- name - The name of the file that the Sender wishes to send. +
- date - The last modification time of the file. This is + specified using the DateTime profile as described in &jep0082;. +
- hash - The MD5 sum of the file contents. +
+ There are two possible child elements of the root: <desc> and + <range>. Both are OPTIONAL. +
++ <desc> is used to provide a sender-generated description of the file so + the receiver can better understand what is being sent. It MUST NOT be sent in + the result. +
++ When <range> is sent in the offer, it should have no + attributes. This signifies that the + sender can do ranged transfers. When a Stream Initiation result is sent + with the <range> element, it uses these attributes: +
-
+
- + offset - Specifies the position, in bytes, to start + transferring the file data from. This defaults to zero (0) if not + specified. + +
- + length - Specifies the number of bytes to retrieve starting + at offset. This defaults to the length of the file from offset to the + end. + +
In order to enable seamless file transfer and appropriate fall-back mechanisms, implementations of this profile MUST support both &jep0065; and &jep0047;, to be preferred in that order. The associated namespaces are to be included as option values for the "stream-method" variable as shown in the examples below.
+Additionally, implementations MAY support other mechanisms.
+No interaction with &IANA; is required as a result of this JEP.
+The profile described in this JEP is included in the stream initiation profiles registry maintained by the ®ISTRAR; (see &SIPROFILES;). The registry submission is as follows:
+
+ http://jabber.org/protocol/si/profile/file-transfer
+ JEP-0096
+ A profile for file transfer between any two entities.
+
+ ]]>
+ As authorized by &jep0147;, the Jabber Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).
+As described below, the registered querytypes for file transfer actions are "sendfile" and "recvfile". Note well that "sendfile" means a second entity will send a file to the XMPP entity that controls the IRI/URI and that "recvfile" means a second entity will receive a file from the XMPP entity that controls the IRI/URI.
+To enable a second entity to send a file, the IRI/URI is of the following form:
+The application SHOULD then present an interface enabling the user to provide information about the file to be sent (e.g., by "browsing" the file system of the user's computer in order to choose a file). As a result, the application SHOULD then send a &jep0137; message to the XMPP address encapsulated in the IRI/URI:
+The following submission registers the "sendfile" querytype.
+
+ sendfile
+ http://jabber.org/protocol/si/profile/file-transfer
+ enables initiation of an inbound file transfer to XMPP entity
+ JEP-0096
+
+ ]]>
+ To enable a second entity to receive a file, the IRI/URI is of the following form:
+That IRI/URI is equivalent to the following XML stanza:
+In accordance with JEP-0137, the application SHOULD then initiate a file transfer exchange with by sending a stanza of the following form:
+Note well that the request to begin the stream is sent to the full JID (user@host/resource) of the XMPP entity identified by the XMPP IRI/URI. Therefore, the IRI/URI SHOULD include a full JID. If it does not, the receiver MUST discover a full JID via presence or service discovery. If the receiver cannot discover a full JID for the sender (e.g., in the last resort through sending a presence subscription request to the sender and receiving presence from the sender's resources), then it SHOULD abort the file transfer exchange.
+The following submission registers the "recvfile" querytype.
+
+ recvfile
+ http://jabber.org/protocol/si/profile/file-transfer
+ enables initiation of an outbound file transfer from XMPP entity
+ JEP-0096
+
+
+ mime-type
+ the MIME type of the file being offered
+
+
+ name
+ the name of the file being offered
+
+
+ sid
+ the session ID associated with the file being offered
+
+
+ size
+ the size in bytes of the file being offered
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0096: http://www.jabber.org/jeps/jep-0096.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+This will be the first, in a series (hopefully), of JEPs which will define how to utilize GroupWare over jabber. While GroupWare is extremely broad subject, this jep will focus on iCal
What this JEP will cover:
+-
+
- Sending iCal data +
- Receiving iCal data +
Before sending iCal messages to a jabber entity, a disco query should be performed in order to discover whether or not that entity supports iCal Envelopes.
+If the jabber entity supports iCal Envelopes, then it MUST respond with http://jabber.org/protocol/gw/ical as a feature.
+To send iCal, all that needs to be done is wrap the iCal data in a ical element. All iCal data sent MUST be in the ical element in the http://jabber.org/protocol/gw/ical namespace. The CDATA section is optional and is used here simply to make it readable.
+Other than wrapping iCal in XML, the data itself MUST follow the ietf 2445 RFC
As a convenience for users which do not have ical support the sender may want to place human readable information in the <body/> for the receiver to read.
+When a client receives a message containing iCal data there are a few options which are considered reasonable.
+-
+
- Ignore the message +
- Display the ical data in the message +
- Hand the ical data off to the user's calendaring application +
Per the jabber standard, any message received which the entity does not understand CAN be ignored. This behavior is expected of clients which have not implemenred this jep.
+The entity may display the ical data as text to the user, this is not recommended for obvious reasons. However, some data is better than no data, so this is considered preferable to just dropping the message stanza.
+Most users today have some form of calendaring functionality available to them which supports the iCal standard. Simply redirecting the received ical to the user's preferred calendaring application would be the ideal scenario.
+This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA)
+The 'http://jabber.org/protocol/gw/ical' namespace is registered with the Jabber Registrar as a result of this JEP.
+TBD
+TBD
+The following are issues that need to be resolved
+-
+
- Does scheduling negotiation need to be defined? +
- How should attachments to ical be handled? +
The 'jabber:iq:private' namespace has been +documented in &jep0049; according to the historical behavior +of current implementations. However there are two backward compatible +improvements to the protocol introduced in this standard +that increase the future useability of the protocol: matching on the fully +qualified name of the XML fragment root, and the introduction of a standard +mechanism of removing stored data. Because the protocol defined herein is not identical to 'jabber:iq:private', a new namespace name is used: 'http://jabber.org/protocol/private-xml'.
+This protocol is designed to provide a simple interface to XML data storage +on XMPP servers. The simple interface eases the implementation burden for the most +basic data storage use-cases (e.g. storing simple client preferences on the server). +More sophisticated XML data storage protocols should be built on top of, or compatible +with this standard.
+A Jabber client can store any arbitrary XML on the server side by sending an +&IQ; chunk of type "set" to the server with a &QUERY; child scoped by the +'http://jabber.org/protocol/private-xml' namespace. The &QUERY; element MUST contain a single, arbitrary +XML fragment. That fragment MUST be scoped by its +own namespace. Any existing data stored on the server with the same fully qualified +element name (tag name + namespace) is replaced by the new data.
+The data can then be retrieved by sending an &IQ; +of type "get" with a &QUERY; child scoped by the 'http://jabber.org/protocol/private-xml' namespace, +which in turn MUST contain a single child element scoped by the namespace used +for storage of that fragment. The fully qualified element name is used to locate +matching XML data on the server. If no matching data is found, the server will +respond with the empty query child element and not an error.
+Finally, existing data on the server can be removed by sending an &IQ; +of type "set" with a &QUERY; child scoped by the 'http://jabber.org/protocol/private-xml' namespace and +containing an 'action' attribute with value 'delete', +which in turn MUST contain a single child element scoped by the namespace used +for storage of that fragment. The fully qualified element name is used to locate +matching XML data on the server. The server responds with a successful result +whether a matching data fragment was found or not (it's successful because the +provided data no longer exits on the server). Deleting data using this method is +indistinguishable from setting an empty XML fragment as far as the behavior this +protoco is concerned. However, deleting data MUST remove the data from the server +which may be implemented differently than the case of setting the data to an empty +element. This may have significance in the context of future advanced XML storage protocols. +Using the basic private XML data storage protocol, Jabber entities can create, read, update, and delete +private data on the server. The data stored might be +anything, as long as it is valid XML. One typical usage for this namespace is the +server-side storage of client preferences.
+| get | Sent with a blank query to retrieve the private data from the server. |
| set | Sent with the private XML data contained inside of a query. |
| set action='delete' | Sent with a blank query to delete private data from the server. |
| result | Returns the private data from the server. |
| error | There was an error processing the request. The exact error can be found in the child error element. |
The root element of this namespace is query. A single child +element with a proper namespace must be included otherwise the server will +respond with error code 406. Only one element can be queried or set in a +single IQ request. However, multiple elements, each containing data, +can be stored independently on the server using separate set queries.
+ +If a user attempts to get or set http://jabber.org/protocol/private-xml data that belongs to another user, the server must return an error to the sender. The error commonly used is 503 (Service Unavailable).
+If a user attempts to perform a get without providing a child element, the server should return a 406 (Not Acceptable) error:
+Certain namespaces are reserved in Jabber (namespaces beginning with 'jabber:' or 'http://jabber.org/', as well as 'vcard-temp'). If a user attempts to get or set http://jabber.org/protocol/private-xml data in a reserved namespace, historically some server implementations have chosen to return an error (commonly 406 [Not Acceptable]) to the sender. Such behavior is not required in order to comply with this JEP, but may be encountered by clients when interacting with some current server implementations.
+The server always replies to a properly formatted get query with +a result response rather than some form of 'not found' error. +for exmple, the following shows the response from a server that does not have XML +data under the 'data' name and 'imaginary' namespace.
+Finally, the client can delete data from the server using the delete query action.
+| Code | Text | Description | +
|---|---|---|
| 406 | Not Acceptable | The IQ get does not contain a child element or (optionally) the IQ get or set is in a reserved namespace. | +
| 503 | Service Unavailable | The IQ get or set is sent to a JID other than that of the sender. | +
+
+ ]]>
+ There is a need for consistent query behavior amongst XMPP &IQ; protocols. Currently +each protocol invents it's own, slightly different behavior for conducting +query behavior to create, read, update, and delete (CRUD) recipient node data. This JEP defines a generic +query acton protocol to standardize behavior across &IQ; protocols. In addition, we hope +this standard will make other protocols easier to understand and implement by using a common +core protocol.
+The existing XMPP core protocol defines +four &IQ; types (get, set, result, and error). Unfortunately, these +four types don't include a 'delete' type, and the 'set' type must do double duty for +'create' and 'update'. Many protocols can benefit from a clear separation of create +and update paralleling other query languages such as SQL.
+Protocols complying with the &QUERY; action protocol use &IQ; 'set' to initiate +all request-response interactions. The particular action to be taken MUST be set as an "action" attribute +in the &IQ; &QUERY; sub-element. The action attribute MUST have a value of 'create', 'read', +'update', or 'delete'. Responses use the standard &IQ; 'result' and 'error' types. +For backward compatibility, an &IQ; 'get' query is treated as equivalent to an &IQ; 'set' +query with action of 'read'. Action protocols may require all or just a subset of these +actions depending on the desired outcome.
+In addition to the action attribute an optional "strict" attribute may be set in the &IQ; &QUERY; +sub-element. The only valid values for strict is "true" or "false" (case sensitive). +The strict behavior of actions causes more errors to be returned which tends to make +protocols more robust but also more complex. Action protocols MUST define the default value of +the "strict" attribute in the context of that protocol. In addition, some protocols may +not wish to allow changing the strict default, so action protocols MUST declare +whether the strict behavior of the protocol may be set in the &IQ; &QUERY; sub-element.
+| create | Creates/inserts new data on the recipient node. |
| read | Retrieves data from the recipient node. |
| update | Updates existing data on the recipient node. |
| delete | Deletes existing data on the recipient node. |
The root element is query which is in a namespace defining the +protocol in use. The query element MUST have +an attribute named 'action' with values given in the previous table.
+The following error codes apply to all action codes.
+| Code | Text | Description | +
|---|---|---|
| 406 | Not Acceptable | The IQ query contents are not properly formatted for the action protocol. | +
| 503 | Service Unavailable | The IQ query is sent to a JID that cannot handle the query. | +
The create action inserts new data on the recipient node. If the strict attribute is +'true' the create action fails if colliding data already exists on the recipient node. If the strict +attribute is false, the create action will insert new data on the recipient node overwriting +existing colliding data if it exists (e.g. equivalent to update).
+| Code | Text | Description | +
|---|---|---|
| 409 | Conflict | The strict attribute is set to 'true' and colliding data exists on the recipient node. | +
Creating new data on the server using iq:private, and strict actions when no existing data is on the server.
+With strict actions enabled, conflict data will cause the create action +to fail when existing data is on the recipient node. Here we show iq:private, and strict actions with existing data on the server.
+The read action retrieves data on the recipient node. If the strict attribute is +'true' the read action fails if no appropriate data exists on the recipient node. If the strict +attribute is false, the read action will always return with a 'result', sending an empty +result in place of a 'not found' error.
+| Code | Text | Description | +
|---|---|---|
| 404 | Not found | The strict attribute is set to 'true' and no matching data exists on the recipient node. | +
Reading data on the server using iq:private, and strict actions when data is on the server.
+With strict actions enabled, the absence of matching data will cause the read action +to fail. Here we show iq:private, and strict actions with no matching data on the server.
+With strict actions disabled, the absence of matching data will cause the read action +to return an 'empty' result. Here we show iq:private, and strict actions disabled with no matching data +on the server.
+The update action edits existing data on the recipient node. If the strict attribute is +'true' the update action fails if matching data does not already exists on the recipient node. If the strict +attribute is false, the update action will edit existing data, inserting the data on the recipient node +if necessary.
+| Code | Text | Description | +
|---|---|---|
| 404 | Not Found | The strict attribute is set to 'true' and matching data does NOT already exist on the recipient node. | +
Updating existing new data on the server using iq:private, and strict actions when existing data is on the server.
+With strict actions enabled, the absence of existing data will cause the update action +to fail. Here we show iq:private, and strict actions with no existing data on the server.
+The delete action deletes existing data on the recipient node. If the strict attribute is +'true' the delete action fails if matching data does not already exists on the recipient node. If the strict +attribute is false, the delete action will delete any existing data on the recipient node (if any) and return +successful..
+| Code | Text | Description | +
|---|---|---|
| 404 | Not Found | The strict attribute is set to 'true' and matching data does NOT already exist on the recipient node. | +
Deleting existing new data on the server using iq:private, and strict actions when existing data is on the server.
+With strict actions enabled, the absence of existing data will cause the delete action +to fail. Here we show iq:private, and strict actions with no existing data on the server.
+With strict actions disabled, the absence of existing data will not cause the delete action +to fail. Here we show iq:private, and strict actions with no existing data on the server.
+In order to define an action protocol that uses the &QUERY; behavior defined in +this JEP, you must specify the following:
+-
+
- The actions (create, read, update, delete) supported in the action protocol. +
- The matching semantics for determing if data exists/collides. +
- The default "strict" attribute ('true' or 'false'). This may be defined for each action + supported or for all actions supported. +
- Whether the "strict" attribute may be set by the user. If the attribute may not be set, + the strict attribute will always hold the default value. +
One distinguishing characteristic of Jabber technologies from their earliest days has been the existence of gateways (also called "transports") between the Jabber network and legacy instant messaging services such as AOL Instant Messenger (AIM), ICQ, MSN Messenger, and Yahoo! Messenger. Surprisingly, the recommended behavior of such gateways, including the protocol elements used by a client to interact with a gateway, has never been fully documented. This JEP attempts to fill that void by codifying best practices for gateway interaction.
+Note well that this JEP defines protocol usage with regard to client proxy gateways, i.e., gateways that "masquerade" as a client on a non-Jabber IM service. Gateways that perform direct protocol translation without proxying for an account on a non-Jabber service are not addressed in this JEP. Furthermore, this JEP does not define any interaction between a gateway and the non-Jabber service, only interactions between a Jabber client and the gateway. Although what happens on the other side of the gateway is highly dependent on the nature of the legacy service, gateways should at least provide a common interface on the Jabber side of the gateway so that Jabber clients can be written in a consistent fashion.
+| Term | +Definition | +
|---|---|
| Gateway | +A service on the Jabber network that translates between the Jabber/XMPP protocols and the protocol used by a Legacy Service; in the context of this JEP, by "gateway" we mean a "client proxy service" that acts as a client with regard to a Legacy Service and thereby "masquerades" as a user on such a service. | +
| Jabber User | +A human user who has registered an account with a Jabber server; a Jabber User who wants to use a Gateway must first have also registered an account with a Legacy Service. | +
| Legacy Service | +A non-XMPP instant messaging service. | +
| Legacy User | +A human user who has registered an account with a Legacy Service. | +
| Server | +An instant messaging server as defined in RFC 3921. | +
The requirements defined by this JEP are captured in two sets of use cases: one set from the perspective of the Jabber User, and a smaller set from the perspective of the Legacy User who wants to interact with the Jabber User.
+The Jabber User use cases are:
+-
+
- Register +
- Edit Registration +
- Unregister +
- Log In +
- Log Out +
- Add Contact +
- Delete Contact +
- Send Message +
The Legacy User use cases are:
+-
+
- Add Contact +
- Delete Contact +
- Send Message +
While more advanced use cases (e.g., sending files and joining chat rooms) are of inherent interest, they are not covered in this JEP because registration, contact list management, and message exchange define the baseline functionality included in all gateway implementations; future JEPs may address the more advanced use cases.
+All existing client proxy gateways require a Jabber User to register with the Gateway before sending messages or presence through the gateway. Although strictly speaking registration is not required (e.g., a Gateway could prompt the Jabber User for credentials every time the user attempted to communicate through the gateway, or once per "session"), in practice this step is required.
+-
+
-
+
Jabber User sends IQ-get qualified by the &jep0030; information namespace to the Gateway, and/or IQ-get qualified by the &jep0094; namespace to the Gateway's parent (the latter method is deprecated but still in use).
++ ++ + ]]> + ++ + ]]> Note: Although many existing gateway implementations support only the older Agent Information protocol, it is RECOMMENDED that gateways support the Service Discovery protocol, since the former protocol is deprecated in favor of the latter. Until existing gateways are upgraded, clients SHOULD support both.
+
+ -
+
Gateway and/or parent returns identity information to Jabber User's Client.
++ ++ + + ]]>+ + + + + + ++ + + ]]>+ +AIM Gateway +aim ++ + Note: Given the foregoing, a client can determine the identity of the gateway, specifically (1) that it is a gateway and (2) to which legacy service it provides a gateway.
+
+ -
+
Jabber User sends IQ-get qualified by the &jep0077; (jabber:iq:register) namespace to Gateway.
++ ++ + ]]>
+ -
+
Gateway returns IQ-result to Jabber User, specifying information that is required in order to register.
++ ++ + + ]]>+ Please provide your AIM screen name and password. + ++ +
+ -
+
Jabber User sends IQ-set qualified by the 'jabber:iq:register' namespace to Gateway, containing information required to register.
++ ++ + + ]]>RomeoMyRomeo +ILoveJuliet +
+ -
+
Gateway verifies that registration information provided by Jabber User is valid (using whatever means appropriate for the Legacy Service) and informs Jabber User of success [A1].
++ ]]> +
+ If Gateway logged into Legacy Service in preceding step, Gateway buffers any translatable events (e.g., messages and presence) queued up for Jabber User on Legacy Service.
+ -
+
Optionally, Jabber User sends IQ-set qualified by the 'jabber:iq:roster' namespace to its server (see &rfc3921;), containing a roster item for Gateway.
++ ++ + + ]]>- +
+ ]]> +
+ -
+
Gateway sends subscription request to Jabber User (i.e., by sending a presence stanza of type "subscribe" to Jabber User's bare JID).
++ ]]> +
+ -
+
Jabber User's client SHOULD approve the subscription request (i.e., by sending a presence stanza of type "subscribed" to Gateway).
++ ]]> +Note: As specified in RFC 3921, Jabber User's server will generate a "roster push" at this point if client did not previously perform a roster set to add Gateway to user's roster (as mentioned above).
+
+ -
+
Jabber User sends subscription request to Gateway (i.e., by sending a presence stanza of type "subscribe" to Gateway).
++ ]]> +
+ -
+
Gateway sends approves subscription request (i.e., by sending a presence stanza of type "subscribed" to Jabber User's bare JID).
++ ]]> +
+ Execute "Log In" use case.
+ Gateway sends any buffered messages to Jabber User.
+ Use Case Ends.
+
-
+
User information not verified: +
-
+
-
+
Gateway returns ¬acceptable; error to Jabber User. (For detailed information regarding error conditions, refer to &jep0086;.)
++ ++ +RomeoMyRomeo +ILoveJuliet ++ + + ]]>+
+ Use Case Ends unsuccessfully.
+
+ -
+
After a Jabber User has registered with a Gateway, the user may wish to modify his or her existing registration information (e.g., because the user has changed his or her password on the legacy IM service).
+-
+
-
+
Jabber User sends IQ-get qualified by the 'jabber:iq:register' namespace to Gateway.
++ ++ + ]]>
+ -
+
Gateway returns IQ-result to Jabber User, specifying registration information on record and including empty <registered/> element to signify that user is already registered.
+The fact that the Gateway can determine the Jabber User's legacy username based on the JID of the 'from' address indicates that the client proxy model assumes one registration per Jabber User. + ++ + + ]]>+ RomeoMyRomeo +ILoveJuliet +
+ -
+
Jabber User sends IQ-set qualified by the 'jabber:iq:register' namespace to Gateway, containing all information (i.e., not just the "delta").
++ ++ + + ]]>RomeoMyRomeo +B4lc0ny +
+ -
+
Gateway verifies that, if changed, information provided by Jabber User is still valid (using whatever means appropriate for the Legacy Service) and informs Jabber User of success [A1].
++ ]]> +
+
-
+
Edit unsuccessful: +
-
+
-
+
Gateway returns ¬acceptable; error to Jabber User.
++ ++ +RomeoMyRomeo +B4lc0ny ++ + + ]]>+
+ Use Case Ends unsuccessfully.
+
+ -
+
After a Jabber User has registered with a Gateway, the user may choose to unregister with the Gateway, effectively ending his or her relationship with the Gateway (e.g., the user will no longer be allowed to communicate through the gateway with legacy users).
+-
+
-
+
Jabber User sends IQ-set in 'jabber:iq:register' namespace to Gateway, containing empty <remove/> element.
++ ++ + + ]]>+
+ Gateway sends unavailable presence from Jabber User to Legacy Users and logs Jabber User out of Legacy Service.
+ Gateway deletes Jabber User's information.
+ -
+
Gateway sends IQ-result to Jabber User.
++ ]]> +
+ -
+
Gateway cancels subscriptions.
++ + ++ ]]>
+ -
+
Gateway sends unavailable presence to Jabber User.
++ ]]> +
+ Jabber User's client SHOULD delete from the user's roster (1) the gateway itself, and (2) all legacy Contacts associated with the gateway.
+ Use Case Ends.
+
None.
+After a Jabber User has registered with a Gateway, the Jabber User may subsequently log in to the Gateway, effectively creating a "session" with the Gateway and enabling the Gateway to log into the Legacy Service on behalf of the user by sending the user's legacy credentials to the Legacy Service.
+-
+
-
+
Jabber User sends available presence broadcast to Server or sends directed presence to Gateway or a Legacy User.
++ ]]> ++ ++... + ]]>
+ Upon receiving the first presence notification stanza from Jabber User to Gateway or Legacy User, Gateway logs Jabber User into Legacy Service [A1].
+ -
+
Gateway sends presence stanza to Jabber User expressing availability.
++ ]]> +
+ Optionally, Gateway handles Legacy Service contact list; see the Contact Lists section of this document.
+ -
+
Gateway forwards current presence information from Legacy Users to Jabber User, if possible mapping availability status (e.g., "away").
++ +away + + ]]>Note: If the Legacy Service to which the Gateway connects does not support the concept of "resources", the 'from' address of presence notification stanzas generated by a gateway SHOULD NOT include a resource identifier (i.e., they SHOULD be of the form <user@host> rather than <user@host/resource>). However, the 'from' address MAY include a resource if the Gateway determines that this is appropriate in the context of its communications with the Legacy Service.
+
+ -
+
Gateway forwards all subsequent presence stanzas to Legacy Users (except those of type "probe" and those addressed to the Gateway itself).
++ +dnd +Wooing Juliet + + ]]>
+ Use Case Ends.
+
-
+
Login fails: +
-
+
-
+
Gateway sends appropriate presence error to Jabber User (¬authorized; if password is bad, &timeout; if Legacy Service is down, etc.).
++ ++ + + ]]>+
+ Use Case Ends unsuccessfully.
+
+ -
+
At any time after logging in to the Gateway, the Jabber User may log out of the Gateway and thereby end his or her session on the Legacy Service. This may happen automatically when the Jabber User terminates his or her session with a Jabber server, or independently of any session on the Jabber network by manually logging out of the Gateway.
+-
+
-
+
Jabber User sends unavailable presence broadcast to Server or sends directed presence stanza of type "unavailable" to Gateway or (if Gateway does not support directed presence) Legacy User.
++ ]]> ++ ]]> +
+ Gateway transforms unavailable presence stanzas received from the Jabber User's server and routes them to all of the Jabber User's contacts on Legacy Service.
+ Gateway logs Jabber User out of Legacy Service [A1].
+ -
+
Gateway sends presence stanza of type "unavailable" to Jabber User.
++ ]]> +
+ Use Case Ends.
+
-
+
Legacy Service supports directed presence and Gateway receives presence stanza of type "unavailable" directed to a Legacy User: +
-
+
-
+
Gateway passes through directed unavailable presence to Legacy User.
++ ]]> +
+ Use Case Ends.
+
+ -
+
After registering with the Gateway, the Jabber User may want to add Legacy Users to his or her Jabber roster.
+-
+
-
+
Jabber User sends presence stanza of type "subscribe" to Legacy User.
++ ]]> +Note: As specified in RFC 3921, sending this packet will result in a "roster push" from the Server to all of the Jabber User's available resources.
+
+ Gateway transforms subscription request and routes it to Legacy User.
+ -
+
If Legacy User approves subscription request, Gateway sends presence stanza of type "subscribed" to Jabber User on behalf of Legacy User. [A1]
++ ]]> +
+ -
+
Gateway sends available presence stanza to Jabber User on behalf of Legacy User.
++ ]]> +
+ -
+
Gateway sends presence stanza of type "subscribe" to Jabber User on behalf of Legacy User.
++ ]]> +
+ -
+
Jabber User sends presence stanza of type "subscribed" to Legacy User.
++ ]]> +
+ Use Case Ends.
+
-
+
-
+
Legacy User denies subscription request:
+-
+
-
+
Gateway transforms subscription denial and routes it to Jabber User.
++ ]]> +
+ Use Case Ends unsuccessfully.
+
+ -
+
After adding a Legacy User to his or her Jabber roster, the Jabber User may want to delete that contact.
+-
+
-
+
Jabber User sends IQ-set qualified by the 'jabber:iq:roster' namespace, containing subscription attribute with value of "remove".
++ ++ + + ]]>- +
+ -
+
Server sends normal "roster push" to Jabber User (see RFC 3921) and sends presence stanzas of type "unsubscribe", "unsubscribed", and "unavailable" to Legacy User.
++ + ++ + + ]]>
+ Gateway cleans up subscription state, informs Legacy User that Jabber User is unavailable, and MUST NOT send future changes in Jabber User's presence to Legacy User.
+ Use Case Ends.
+
None.
+Naturally, the Jabber User may want to exchange messages with a Legacy User. For the purposes of this JEP, we discuss one-to-one messaging only (i.e., groupchat messages, such as those defined in &jep0045;, are out of scope).
+-
+
-
+
Jabber User sends message stanza to Legacy User.
++ Neither, fair saint, if either thee dislike. + + ]]> +
+ Gateway transforms message to legacy protocol and sends to Legacy User [A1].
+ Use Case Ends.
+
-
+
Legacy Service reports error.
+ -
+
Gateway sends appropriate error to Jabber User:
+-
+
¬found; -- Legacy User address is not valid.
+ ®istration; -- Jabber User is not registered with Gateway.
+ &unavailable; -- Legacy User is offline and Legacy Service (or Gateway) does not provide offline message storage.
+ &timeout; -- Legacy Service cannot be reached.
+
+ Use Case Ends unsuccessfully.
+
The Legacy User may want to add the Jabber User to his or her contact list on the Legacy Service. Because the Jabber User has an account on the Legacy Service by definition, the Legacy User will actually add the Jabber User's legacy address to his or her contact list, not the Jabber User's address on the Jabber/XMPP network.
+-
+
Legacy User requests subscription to Jabber User's legacy address (using legacy protocol).
+ -
+
Gateway sends presence stanza of type "subscribe" to Jabber User on behalf of Legacy User. (Note: Gateway MUST NOT send presence stanza of type "subscribed".)
++ ]]> +
+ -
+
Jabber User approves subscription request by sending presence stanza of type "subscribed" to Legacy User [A1].
++ ]]> +
+ Gateway sends Jabber User's presence information to Legacy User.
+ -
+
Jabber User's Client sends presence stanza of type "subscribe" to Legacy User.
++ ]]> +
+ -
+
Gateway sends presence stanza of type "subscribed" to Jabber User on behalf of Legacy User.
++ ]]> +
+ -
+
Gateway sends Legacy User's presence information to Jabber User.
++ ]]> +
+ Use Case Ends.
+
-
+
Jabber User denies subscription request: +
-
+
-
+
Jabber User sends presence stanza of type "unsubscribed" to Legacy User.
++ ]]> +
+ Gateway cleans up subscription state and MUST NOT send Jabber User's presence to Legacy User.
+ Use Case Ends unsuccessfully.
+
+ -
+
After adding the Jabber User to his or her legacy contact list, the Legacy User may want to delete the Jabber User.
+-
+
Legacy User deletes Jabber User's legacy address (using legacy protocol).
+ -
+
Gateway sends presence stanzas of type "unsubscribe", "unsubscribed", and "unavailable" to Jabber User on behalf of Legacy User.
++ + ++ + + ]]>
+ Jabber User's server performs defined functionality for handling presence stanzas of type "unsubscribe" and "unsubscribed" (see RFC 3921).
+ Use Case Ends.
+
None.
+Naturally, the Legacy User may want to exchange messages with the Jabber User. (Here again, groupchat messages are out of scope.)
+-
+
Legacy User sends message to Jabber User using legacy protocol.
+ -
+
Gateway transforms message and routes to Jabber User.
++ Art thou not Romeo, and a Montague? + + ]]> +Note: If the Legacy Service to which the Gateway connects does not support a concept equivalent to that of Jabber "resources" as described in &rfc3920;, the 'from' address of message stanzas generated by a gateway SHOULD NOT include a resource identifier (i.e., they SHOULD be of the form <user@host> rather than <user@host/resource>). However, the 'from' address MAY include a resource if the Gateway determines that this is appropriate in the context of its communications with the Legacy Service.
+
+ Jabber User's Server delivers message or (optionally) stores it for later retrieval.
+ Use Case Ends.
+
None.
+The address of a gateway itself SHOULD be a hostname only, and that hostname SHOULD NOT be supplemented with a resource identifier when referring to the gateway's address (e.g., when storing the gateway in a roster). The hostname SHOULD be a subdomain of a primary Jabber host (e.g., icq.jabber.org might be the ICQ gateway run by the jabber.org server).
+The Jabber Identifier corresponding to a Legacy User's address is typically of the form <LegacyUserAddress@gateway.example.com>, where LegacyUserAddress is the Legacy User's address on the Legacy Service and where gateway.example.com is the Jabber address of the gateway.
+Unfortunately, usernames on some Legacy Services may allow characters that are disallowed in Jabber usernames as specified by the Nodeprep profile of stringprep defined in RFC 3920. For example, the usernames for a Legacy Service may be of the form <user@domain>, which would result in an illegal JID such as <user@domain@gateway.example.com>.
+There are two possible ways to solve this problem:
+-
+
- Use &jep0106;. +
- Use the older 'jabber:iq:gateway' protocol (as documented in the following section). +
Gateways and clients SHOULD implement at least one of these protocols; at a minimum, it is RECOMMENDED for gateways and clients to implement the 'jabber:iq:gateway' protocol.
+The 'jabber:iq:gateway' protocol performs two functions:
+-
+
It enables a client to determine the text for the "prompt" to show to a Jabber User when the user wants to add a legacy contact to the user's roster (e.g., "Please enter the AOL Screen Name of the person you would like to contact"), as well as the preferred name for the prompted item (e.g., "Screen Name"). To do so, the client sends an empty <query/> element and the gateway returns a <prompt/> element (the name for the prompted item) and optionally a <desc/> element (the text of the prompt itself).
+ It enables a client to send a legacy username to the gateway and receive a properly-formatted JID in return. To do so, the client sends the legacy address to the gateway as the character data of the <prompt/> element and the gateway returns a valid JID as the character data of the <jid/> element.
+
Both uses are illustrated below.
+The following table is intended to assist implementors with mapping of gateway identities to English-language prompt names and text.
+| Legacy Service | +Service Discovery Identity | +Prompt Name | +Prompt Text | +
|---|---|---|---|
| AOL Instant Messenger | +gateway/aim | +AOL Screen Name | +Please enter the AOL Screen Name of the person you would like to contact. | +
| ICQ | +gateway/icq | +ICQ Number | +Please enter the ICQ Number of the person you would like to contact. | +
| MSN Messenger | +gateway/msn | +MSN Address | +Please enter the MSN Address of the person you would like to contact. | +
| Yahoo! Messenger | +gateway/yahoo | +Yahoo ID | +Please enter the Yahoo ID of the person you would like to contact. | +
If the client provides an 'xml:lang' attribute with the IQ-get, the gateway SHOULD return localized prompt names and text if available, or default to English if not available.
+Once the user enters a legacy username or address, the client MUST send it to the gateway as the character data of the <prompt/> element in an IQ-set; the gateway MUST then return a properly-formed JID based on the provided by the client.
+Some legacy services maintain server-side contact lists, which are sent to the gateway when it logs in to the legacy service on behalf of the user. The gateway MAY initiate adding of the legacy contact list items to the user's Jabber roster. Some existing gateways do this by sending a presence stanza of type "subscribed" from the legacy contact's JID (e.g., <LegacyUser@gateway.jabberserver.com>) to the Jabber user; unfortunately, this behavior violates the presence stanza handling rules specified in RFC 3921. Therefore, a gateway SHOULD instead send the legacy contact list items to the Jabber User via the &jep0144; protocol.
+The following business rules apply:
+-
+
A client SHOULD send a Service Discovery request to the gateway (and/or an Agent Information request to the gateway's parent) before requesting registration information.
+ A gateway SHOULD support the Service Discovery protocol.
+ A gateway SHOULD support the Agent Information protocol, although it is deprecated.
+ A gateway SHOULD map, as best it can, the legacy registration fields onto the fields defined for the 'jabber:iq:register' namespace.
+ A gateway SHOULD NOT attempt to emulate offline message storage functionality for legacy services that lack such functionality.
+ -
+
Existing gateway implementations do not strictly adhere to the bi-directional nature of Jabber presence notifications, since they do not broadcast presence from the gateway itself to registered users of the gateway, but rather wait for a registered user to send presence to the gateway before sending presence to the user. This sidesteps scalability challenges but may be sub-optimal; while this JEP does not require existing gateways to change their current behavior, it does RECOMMEND that they broadcast presence notifications to registered users in accordance with the standard Jabber presence model. Specifically:
+-
+
On startup, a gateway (1) SHOULD send presence to all registered users of that gateway but (2) MAY wait to receive presence changes from each registered user.
+ On shutdown, a gateway SHOULD send unavailable presence to all registered users of the gateway.
+
+
As defined herein, a gateway is a client proxy, since it "masquerades" as a user on a legacy instant messaging service. In order to act as a client proxy, the gateway logs into the user's account on the legacy service. This implies two things:
+-
+
- The gateway must gather the legacy credentials from the user, and perhaps store them on the user's behalf. +
- The gateway must provide the user's credentials to the legacy service. +
There are obvious security concerns with this approach. The concerns include:
+-
+
- The user's credentials on the legacy service may be sent in the clear from the gateway to the legacy service if the legacy service does not support channel encryption or strong authentication. +
- When the user informs the gateway of the user's legacy credentials, the credentials may be sent in the clear between the user's Jabber client and the user's Jabber server (if client-to-server channel encryption is not enabled) or between the user's Jabber server and the gateway (if the gateway is not in the user's "home" domain and server-to-server channel encryption is not enabled). +
- If the gateway stores the user's legacy credentials after registration (this is the default behavior of most or all existing gateway implementations), the user's credentials could be acquired by a malicious user if the server hosting the gateway is compromised. +
There is no foreseeable solution to these concerns, since they are instrinsic to the client proxy model. Some assurance regarding the second and third concerns can be achieved if the user runs his or her own Jabber server and gateways. However, the only true solution is to move beyond the client proxy model, either by using Jabber for all IM communications or to convince legacy IM services to allow federated server-to-server communications using open protocols such as Jabber/XMPP, thus obviating the need for client proxy gateways entirely.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'jabber:iq:gateway' in its registry of protocol namespaces.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0100: http://www.jabber.org/jeps/jep-0100.html
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Jabber Ticket Authentication is a method of authenticating with HTTP servers using your jabber identification.
+This allows you to login to websites using your jabber address in a single sign-on fashion similar to .NET Passport, but unlike .NET Passport is not locked into a single authentication provider.
+Tickets also mean the jabber ticket provider and the web server do not need to be tightly integrated for authentication to work, also because its not tightly integrated it means webmasters do not need to setup their own jabber server to provide tickets, they can use a third party provider even a central "tickets.jabber.org". Also because tickets are not tightly integrated it makes it far easier for webmasters to integrate with Jabber, it also makes web farms far more scalable and reliable.
+The motivations for this JEP are:
+-
+
- To provide a method of using a jabber connections authenticated stream to provide a method of authenticating with an HTTP server. +
- To provide this authentication without needing the jabber ticket component and the webserver to be tightly coupled, this is essential in a web farm environment for scalability. +
- To make the communication between the jabber client and the server(s) as simple as possible. +
The realm is the JID you need to request your JabberTicket from.
+The ticket is encrypted data represented as a string, the client does not need to decode it since it is passed to the webserver unaltered.
+The following guidelines may assist developers.
+-
+
- The ticket can be encrypted however the provider likes since only they will need to understand it. +
- The ticket must somewhere contain in it the JID of the end user (or some method of knowing who the user is), so that the webserver knows who it is. +
- It is recommended that your tickets also use an extra level of authentication such as ensuring the User-Agent is the same across requests, that the ip address is the same across requests. +
This form of HTTP authentication is susceptable to man in the middle attack where the ticket could be captured and retransmitted by someone else, but this can be solved by using an encrypted jabber connection (e.g. HTTPS) and an HTTPS connection to the webserver.
+It is recommended the encryption key length for the ticket be long enough to make it hard to crack the ticket.
+It is recommended the ticket has an expiration and that it be between a few minutes and a few hours, e.g. 60 minutes.
+The HTTP authentication scheme "JabberTicket" may need to be registered with IANA.
+The ®ISTRAR; will need to register the new namespace of "http://jabber.org/protocol/ticket".
+While the benefits of IM are clear and compelling, the risks associated with sharing sensitive information in an IM environment are often overlooked. We need a mechanism that permits communities of users to protect their IM conversations. This document presents an extension protocol that can be incorporated into the existing XMPP protocol to provide such a mechanism.
+In addition to its ability to protect instant message data, the proposed protocol may also serve as a foundation for securing other data transported via XMPP extensions.
+| Term | Definition |
| User | A user is simply any XMPP user. Users are uniquely identified by a JID; they connect to XMPP hosts using a XMPP node. Users produce and consume information, and we wish to provide them with mechanisms that can be used to protect this information. |
| Community | A community is a collection of users who wish to communicate via XMPP. No restrictions or assumptions are made about the size of communities or the geographical, organizational, or national attributes of the members. Communities are assumed to be dynamic and ad-hoc. Users typically join communities by the simple act of invitation. All members of a community are assumed to be peers. The members of communities share information among themselves, and we wish to provide them with mechanisms that can permit information to only be shared by community members. |
| Conversation | A conversation is the set of messages that flows among the members of a community via some network. Conversations consist of both the actual conversation data produced and consumed by the various users as well as the XMPP protocol elements that transport it. Members participate in a conversation when they are the source or destination of this traffic. |
| Initiator | The initiator is the user who requested a security session negotiation. Initiator's are identified by their JID. |
| Responder | The responder is the user who responded to a security session negotiation request. Responder's are identified by their JID. |
| Concatentation operator | The '|' character is used in character or octet string expressions to indicate concatenation. |
| PFS | Perfect Forward Secrecy. In cryptography, is said of a key-establishment protocol in which the compromise of a session key or long-term private key after a given session does not cause the compromise of any earlier session. |
| GRP | The definition of a Diffie-Hellman group length |
| DHx | The Diffie-Hellman ephemeral public keys for the initiator (x=i) and the responder (x=r) |
| KEY | The Diffie-Hellman ephemeral session secret that is agreed to during a key exchange negotiation. |
| CKYx | A 64 bits pseudo-random number or cookie generated by the initiator (x=i) and responder (x=r) in the authenticated key exchange. |
| KEYID | The concatenation of CKI-I and CKI-r and the domain of interpretation. It is the name of the keying material. |
| sKEYID | This is the keying material named by KEYID. It is never transmitted but is used in the various calculations made by the exchanging parties. |
| EHAo | A list of encryption/hash/authentication algorithms choices. |
| EHAs | The selected reference encryption/hash/authentication choice. |
| Nx | The nonces selected by the initiator (x=i) and the responder (x=r) |
| JIDx | The identities of the initiator (x=i) and the responder (x=r) |
| E{value}Kx | The encryption of value with the public key of the initiator (x=i) and the responder (x=r). Encryption is done using the algorithm associated with the authentication method. Usually this will be RSA |
| D{value}Kx | The decryption of value with the public key of the initiator (x=i) and the responder (x=r). Decryption is done using the algorithm associated with the authentication method. Usually this will be RSA |
| S{value}Kx | The signature of value with the private key of the initiator (x=i) and the responder (x=r). Signing is done using the algorithm associated with the authentication method. Usually this will be RSA or DSS |
| prf(a, b) | The result of applying pseudo-random function "a" to data "b". One may think of "a" as a key or as a value that characterizes the function prf; in the latter case it is the index into a family of functions. Each function in the family provides a "hash" or one-way mixing of the input. |
| prf(0, b) | The application of a one-way function to data "b". The similarity with the previous notation is deliberate and indicates that a single algorithm, e.g. MD5, might will used for both purposes. In the first case a "keyed" MD5 transform would be used with key "a"; in the second case the transform would have the fixed key value zero, resulting in a one-way function. |
| hmac(a, b) | This indicates the HMAC algorithm. pseudo-random function "a" to data "b". |
The proposed protocol is designed to address the specific requirements and considerations presented in this section.
+A secure IM system must permit conversation participants to preserve the following properties of their conversation data:
+| Property | Description |
| confidentiality | Conversation data must only be disclosed to authorized recipients |
| integrity | Conversation data must not be altered |
| data origin authentication | Recipients must be able to determine the identity of the sender and trust that the message did, in fact, come from the sender. It is important to note that this requirement does not include the requirement of a durable digital signature on conversation data. |
| replay protection | Recipients must be able to detect and ignore duplicate conversation data. |
These are established, traditional goals of information security applied to the conversation data. In the IM environment, these goals protect against the following attacks:
+-
+
- eavesdropping, snooping, etc. +
- masquerading as a conversation participant +
- forging messages +
Preserving the availability of conversation data is not addressed by this protocol.
+Finally, note that this protocol does not concern any authentication between an XMPP node and an XMPP host.
+A secure IM system must support a data classification feature through the use of security labeling. Conversation participants must be able to associate a security label with each piece of conversation data. This label may be used to specify a data classification level for the conversation data.
+It is easy to imagine XMPP systems in which the servers play active, fundamental roles in the protection of conversation data. Such systems could offer many advantages, like:
+-
+
- allowing the servers to function as credential issuing authorities, + +
- allowing the servers to function as policy enforcement points. +
Unfortunately, such systems have significant disadvantages when one considers the nature of instant messaging:
+-
+
- Many servers may be un-trusted, public servers. + +
- In many conversation communities, decisions of trust and membership can only be adequately defined by the members themselves. + +
- In many conversation communities, membership in the community changes in real time based upon the dynamics of the conversation. + +
- In many conversation communities, the data classification of the conversation changes in real time based upon the dynamics of the conversation. +
Furthermore, the use of gateways to external IM systems is a further complication.
+Based on this analysis, we propose that security be entirely controlled in an end to end fashion by the conversation participants themselves via their user agent software.
+Similarly, we believe that trust decisions are in the hands of the conversation participants. A security protocol and appropriate user agents must provide a mechanism for them to make informed decisions.
+One of the accepted axioms of security is that people must avoid the temptation to start from scratch and produce new, untested algorithms and protocols. History has demonstrated that such approaches are likely to contain flaws and that considerable time and effort are required to identify and address all of these flaws. Any new security protocol should be based on existing, established algorithms and protocols.
+Any new IM security protocol must integrate smoothly into the existing IM environment, and it must also recognize the nature of the transactions performed by conversation participants. These considerations are especially important:
+-
+
- dynamic communities. The members of a community are defined in near real time by the existing members. + +
- dynamic conversations. Conversations may involve any possible subset of the entire set of community members. +
Addressing these considerations becomes especially crucial when selecting a conference keying mechanism.
+Given the requirement to place the responsibility for the protection of conversation data in the hands of the participants, it is imperative to address some fundamental usability issues:
+-
+
- Overall ease of use is a requirement. For protocol purposes, one implication is that some form of authentication via passphrases is necessary. While we recognize that this can have appalling consequences, especially when we realize that a passphrase may be shared by all of the community members, we also recognize its utility. + +
- PKIs are well established in many large organizations, and some communities will prefer to rely on credentials issued from these authorities. We must allow the use of existing PKI credentials and trust models rather than impose closed, XMPP-specific credentials. + +
- Performance must not be negatively impacted. This is particularly true if we consider that most communities are composed of human users conversing in real time. For protocol purposes, one obvious implication is the desire to minimize computationally expensive public key operations. +
To successfully integrate into the existing XMPP environment, an extension protocol for security must satisfy the following:
+-
+
- It must be an optional extension of the existing XMPP protocol. + +
- It must be transparent to existing XMPP servers. + +
- It must function gracefully in cases where some community members are not running a user agent that supports the protocol. + +
- It must make good use of XML. + +
- It must avoid encumbered algorithms. + +
- It must be straightforward to implement using widely available cryptographic toolkits. + +
- It must not require a PKI. +
Since cryptographic operations are applied to data that is transported within an XML stream, the protocol defines a set of rules to ensure a consistent interpretation by all conversation participants.
+Binary data, such as the result of an HMAC, is always transported in an encoded form; the only supported encoding scheme is base64.
+Senders MAY include arbitrary white space within the character stream. Senders SHOULD NOT include any other characters outside of the encoding set.
+Receivers MUST ignore all characters not in the encoding set.
+Encrypted data is always transported in an encoded form; the only supported encoding scheme is base64.
+Senders MAY include arbitrary white space within the character stream. Senders SHOULD NOT include any other characters outside of the encoding set.
+Receivers MUST ignore all characters not in the encoding set.
+HMACs are computed over a specific collection of attribute values and character data; when computing an HMAC the following rules apply:
+-
+
- All characters MUST be HMACed in their pure Unicode form encoded in UTF-16. +
-
+
- The octets in each character MUST be processed in network byte order. +
-
+
- For a given element, the attribute values that are HMACed MUST be processed in the specified order regardless of the order in which they appear in the element tag. +
-
+
- For each attribute value, the computation MUST only include characters from the anticipated set defined in this specification; in particular, white space MUST always be ignored. +
-
+
- For character data that is represented in a base64 encoded form, the computation MUST only include valid characters from the encoding set. +
The following algorithm is used to encrypt a character string:
+-
+
- The character string MUST be represented in Unicode encoded in UTF-16. +
-
+
- The octets in each character MUST be processed in network byte order. +
-
+
- Appropriate cryptographic algorithm parameters, such as an IV for a block cipher, are generated. +
-
+
- The octet string derived from the character string is padded with up to 256 octets of arbitrary padding data. There MUST be at least one padding octet. The last octet of the padding MUST indicate the number of preceeding octets in the stream. All padding octets except the last octet SHOULD be randomly generated. When block ciphers are used, the padding MUST result in a stream of octets that is a multiple of the cipher's block size. +
When used to extend existing XMPP construct, the container element is an <x/> element. Each <x/> element could have one <SecurityAssociation/> to refer to a particular security session, one <KeyAgreement/> element which would contain the information for an an exchange of keys. The <x/> element could have its content authenticated by one <Signature/> element which contains the information about signature of information exchanged between two nodes. The <x/> element may contains one <KeyTransport/> element which contains the information about keys to be securely exchanged between two nodes.
+When used in an IQ XMPP construct, the container element is a <query/> element. Each <query/> element could have one <SecurityAssociation/> to refer to a particular security session, one <KeyAgreement/> element which would contain the information for an an exchange of keys. The <query/> element could have its content authenticated by one <Signature/> element which contains the information about signature of information exchanged between two nodes. The <query/> element may contains one <KeyTransport/> element which contains the information about keys to be securely exchanged between two nodes.
+Each <SecurityAssociation/> element may have <DigestMethod/>, <EncryptionMethod/> and <SignatureMethod/> elements to specify the actual algorithms set that will be used in a key exchange.
+Each <KeyAgreement/> element may have a <DHKeyValue/> and a < DHParamters/> elements to specify the actual data and parameters used in the key exchange. It may also contain a <KA-Nonce/> element to specify a nonce to be used in a key exchange.
+| Attribute | Meaning |
| id | The id attribute hold the agreement or security association ID, when present. |
| length | The length attribute hold the require number of bits in the prime number used to generate the DH key pair. |
| Element | Meaning |
| SecurityAssociation | The <SecurityAssociation/> tag is used to encapsulate EncryptionMethod, DigestMethod, SignatureMethod data. It is used as a container for the different algorithm definition that are negotiated for the session. |
| AgreementMethod | The <AgreementMethod/> tag is an optional element that identifies the key agreement algorithm to be applied to an object. |
| DigestMethod | The <DigestMethod/> tag is an optional element that identifies the digest algorithm to be applied to an object. |
| DigestValue | The <DigestValue/> tag is an optional element that contains the encoded value of a digest. |
| EncryptionMethod | The <EncryptionMethod/> tag is an optional element that describes the encryption algorithm applied to the cipher data. If the element is absent, the encryption algorithm must be known by the recipient or the decryption will fail. |
| Signature | The <Signature/> tag is used to encapsulate signature data. It is used as a container of other XML structures that could come from any namespace. |
| SignatureMethod | The <SignatureMethod/> tag is an optional element that specifies the algorithm used for signature generation and validation. |
| SignatureValue | The <SignatureValue/> tag is an optional element that contains the encoded value of a signature. |
| SignedInfo | The <SignedInfo/> tag includes the canonicalization algorithm, a signature algorithm, and one or more references. The SignedInfo element may contain an optional ID attribute that will allow it to be referenced by other signatures and objects. It is in the http://www.w3.org/2000/09/xmldsig# namespace. |
| KA-Nonce | The <KA-Nonce/> tag is an optional element under <KeyAgreement/> to assure that different keying material is generated even for repeated agreements using the same sender and recipient public keys. |
| KeyAgreement | The <KeyAgreement/> tag is used to encapsulate key agreement data. It is used as a container of other XML structures that could come from external namespace. |
| KeyInfo | The <KeyInfo/> tag is used to encapsulate key information data. It enables the recipient to obtain the key needed to validate a signature. <KeyInfo/> may contain keys, names, certificates and other public key management information, such as in-band key distribution or key agreement data. It is used as a container of other XML structures that could come from external namespace. |
| OriginatorKeyInfo | The <OriginatorKeyInfo/> tag is used to encapsulate originator key information data in a key agreement. It is of type <KeyInfo/> and used as a container of other XML structures that could come from external namespace. |
| RecipientKeyInfo | The <RecipientKeyInfo/> tag is used to encapsulate recipient key information data in a key agreement. It is It is of type <KeyInfo/> and used as a container of other XML structures that could come from external namespace. |
| KeyName | The <KeyName/> tag is an optional element of <KeyInfo/> and contains a string value (in which white space is significant) which may be used to communicate a key identifiert to the recipient. |
| KeyValue | The <KeyValue/> tag contains a single public key that may be useful in validating a signature. The KeyValue element may include externally defined public keys values represented as PCDATA or element types from an external namespace |
| KeyTransport | The <KeyTransport/> tag is used to encapsulate transported key data. It is used as a container of other XML structures that could come from any namespace. |
| CarriedKeyName | The <CarriedKeyName/> tag is optional and used to specified the name of the transported key. |
| DHKeyValue | The <DHKeyValue/> tag is used to encapsulate a Diffie-Hellman key agreement content. It is designed to follow the XML digital signature standard. |
| DHParameters | The <DHParameters/> tag is used to to encapsulate a Diffie-Hellman key exchange parameters. |
| Public | The <Public/> tag is holding the actual content of a Diffie-Hellman public key. |
| X509Data | The <X509Data/> tag is an optional element holding one or more identifiers of keys or X509 certificates, or certificates' identifiers or a revocation list. It is in the http://www.w3.org/2000/09/xmldsig# namespace. |
| PGPData | The <PGPData/> tag is an optional element used to convey information related to PGP public key pairs and signatures on such keys. It is in the http://www.w3.org/2000/09/xmldsig# namespace. |
| DSAKeyValue | The <DSAKeyValue/> tag is optional and defines a DSA public key inside a <KeyInfo/> element. It is in the http://www.w3.org/2000/09/xmldsig# namespace. |
| RSAKeyValue | The <RSAKeyValue/> tag is optional and defines a RSA public key inside a <KeyInfo/> element. It is in the http://www.w3.org/2000/09/xmldsig# namespace. |
| Element | Attribute | Value | Meaning |
| KeyAgreement | id | CDATA | The agreement ID |
| length | null | CDATA | The length of the prime number to be used by default is 768 bits. The length of the prime number to be usedas defined in the IKE Diffie-Hellman groups. |
| SecurityAssocitation | id | CDATA | The security association ID or cookie for a party in the negotiation. |
| AgreementMethod | Algorithm | CDATA | The algorythm URI for the key agreement. |
| DigestMethod | Algorithm | CDATA | The algorythm URI for the digest. |
| EncryptionMethod | Algorithm | CDATA | The algorythm URI for the encryption. |
| SignatureMethod | Algorithm | CDATA | The algorythm URI for the signature. |
The base key agreement (BKE) is an implementation of the "Diffie-Hellman Method For Key Agreement" (DH). It allows two nodes to create and share a secret key.
+DH is not an encryption mechanism as we normally think of them, in that we do not typically use it to encrypt data. Instead, it is a method to securely exchange the keys that encrypt data. DH accomplishes this secure exchange by creating a "shared secret", sometimes called a "key encryption key", between two nodes. The shared secret then encrypts the symmetric key, or "data encryption key" - DES, Triple DES, CAST, IDEA, Blowfish, etc, for secure transmission.
+Two nodes intending to agree on a secret key shall employ the first phase of the agreement independently to produce the public values outputs PV and PV'. The nodes shall exchange the outputs.
+The nodes shall then employ the second phase independently with the other nodes's public value as input. The mathematics of Diffie-Hellman key agreement ensure that the resulting outputs SK of the second phase are the same for both entities.
+1) First the nodes must get the "Diffie-Hellman parameters". A prime number, 'p' (larger than 2) and "base", 'g', an integer that is smaller than 'p'. They can either be hard coded or fetched from a server.
+Diffie-Hellman groups are used to determine the length of the base prime numbers used during the key exchange. The strength of any key derived depends in part on the strength of the Diffie-Hellman group the prime numbers are based on:
+-
+
- Group 2 (medium) is stronger than Group 1 (low). Group 1 will provide 768 bits of keying material, while Group 2 will provide 1,024 bits. If mismatched groups specified on each peer, negotiation will fail. The group cannot be switched during the negotiation. + +
- A larger group results in more entropy and therefore a key which is harder to break. +
2) The nodes each secretly generate a private number called 'x', which is less than "p - 1".
+3) The nodes next generate the ephemeral public keys, 'y'. They are created with the function:
+y = g^x mod p
+4) The two nodes now exchange the public keys ('y') and the exchanged numbers are converted into a secret key, 'z'.
+z = y^x mod p
+'z' can now be used as the key for whatever encryption method is used to transfer information between the two nodes. Mathematically, the two nodes should have generated the same value for 'z'.
+z = (g^x mod p)^x' mod p = (g^x' mod p)^x mod p
+All of these numbers are positve integers
+x^y means: x is raised to the y power
+xmody means: x is divided by y and the remainder is returned
+Suppose two nodes want to agree on a shared secret key to exchange information securely, they will exchange their public keys in order to encrypt that information. To this goal, the transport XMPP packet SHOULD include an extension of the form:
+
+
+
+
+
+
+
+]]>
+In this extension, the only negotiable parameter is the key length that is passed in the length attribute of the <KeyAgreement/> tag. The length attribute is used to retrieve the DH parameter group and the associated prime and generator values. We are using DH groups derived from the Internet Key Exchange protocol (IKE) which is used by IPSec. A summary of these groups and the associated parameters are described later in this document.
+An example of using this agreement is to send encrypted password on the wire when registering a new user. Registration is the only time a password needs to be exchanged between an XMPP server and a client. Once that has been carried out, then every authentication can be done through digest.
+The client uses an empty <x/> element in the request to signal that it supports the XMPP security extension.
+The flow between client and server will look like:
+
+
+
+
+
+
+]]>
+The server will reply to the request by sending out its own ephemeral public key inside the <x/> extension.
+
+
+
+
+
+encoded server public key
+
+
+
+
+
+]]>
+The client then generate its own public key, calcultate the shared secret according to the DH method and uses it to encrypt the password accordingly. It includes its own ephemeral public key into the reply to the server inside the <x/> extension.
+
+
+username
+encrypted password
+
+
+
+encoded client public key
+
+
+
+
+
+]]>
+
+The server now calculates the shared secret according to the DH method and uses its private key to decrypt the password.
+
+]]>
+The Diffie-Hellman key agreement algorithm
This AKE uses a hybrid protocol derived from the Internet Key Exchange (IKE)
-
+
- it uses weak address validation mechanism (cookies) to avoid denial of service attacks. + +
- it provides negotiation of mutually agreeable supporting algorithm for the protocol, such as the encryption method, the key derivation method and the authentication method. + +
- the authentication does not depend on encryption using the DH exponentials, but instead validates the binding of the exponential to the identities of the parties. + +
- it does not require the computation of the shared exponential before the authentication. + +
- it provides additional security to the derivation of encryption keys, as it is made to depend not only of the DH algorithm but also on the cryptographic method used to securely authenticate the parties to each other. + +
This key agreement protocol is used to establish a shared key with an assigned identifier and associated identities for two parties. The resulting common keying information state comprise a key name, secret keying material, the identification of the two parties, and three algorithms for use during authentication:
+-
+
- encryption for privacy, + +
- hashing for protecting the integrity of message and for authentication of message fields + +
- authentication to mutually authenticate the parties +
The anti clogging tokens, or cookies, provide a weak form of source address identification for both parties. The cookies exchange can be completed before they perform the expensive computations later in the protocol. The cookies are used also for key naming.
+-
+
- The construction of the cookies is implementation dependent. It is recommended to make them the result of a one-way function applied to a secret value (changed periodically), and the local and remote addresses. In this way, the cookies remain stateless and expire periodically. Note that this would cause the KEYID's derived from the secret value to also expire, necessitating the removal of any state information associated with it. +
- The encryption functions must be cryptographic transforms which guarantee privacy and integrity for the message data. They include any that satisfy this criteria and are defined for use with RFC2406
[3] .
+ - The one-way hash functions must be cryptographic transform which can be used as either keyed hash (pseudo-random) or non keyed transforms. They include any that are defined for use with RFC2406
[3] .
+ - Where nonces are indicated they will be variable precision integers with an entropy value that match the strength attribute of the DH group used in the exchange. +
The main exchange has three optional features:
+-
+
- stateless cookie exchange, +
- perfect forward secrecy for the keying material, +
- use of signatures (for non-repudiation). +
The two parties can use any combination of these features. The general outline of processing is that the Initiator of the exchange begins by specifying as much information as he wishes in his first message. The Responder replies, supplying as much information as he wishes. The two sides exchange messages, supplying more information each time, until their requirements are satisfied.
+The choice of how much information to include in each message depends on which options are desirable. For example, if stateless cookies are not a requirement, and perfect forward secrecy for the keying material are not requirements, and if non- repudiatable signatures are acceptable, then the exchange can be completed in three messages. Additional features may increase the number of roundtrips needed for the keying material determination.
+The three components of the key determination are:
+-
+
- Cookies exchange +
- DH half key exchange +
- Authentication +
The initiator can supply as little information as a bare exchange request, carrying no additional information. On the other hand the initiator can begin by supplying all the necessary information for the responder to authenticate the request and complete the key determination quickly, if the responder choose to accept this method. If not the responder can reply with a minimum amount of information.
+The following example indicates how two parties can complete a key exchange in three messages. The identities are not secret, the derived keying material is protected by PFS.
+By using digital signatures, the two parties will have a proof of communication that can be recorded and presented later to a third party.
+The keying material implied by the group exponentials is not needed for completing the exchange. If it is desirable to defer the computation, the implementation can save the "x" and "g^y" values and mark the keying material as "uncomputed". It can be computed from this information later.
+| Initiator | Message content | Responder |
| | GRP, CKYi, DHi, EHAo, JIDi, JIDr, Ni, S{JIDi | JIDr | CKYi | 0 | Ni | 0 | GRP | DHi | 0 | EHAo}Ki | |
| | GRP, CKYr, DHr, EHAs, JIDi, JIDr, Nr, S{JIDr | JIDi| | CKYr | CKYi | Nr | Ni | GRP | DHr | DHi | EHAs}Kr | |
| | GRP, CKYi, CKYr, DHi, EHAs, JIDi, JIDr, Ni, Nr, S{JIDi | JIDr | CKYr | CKYi | Ni | Nr | GRP | DHi | DHr | EHAs}KEY | |
The result of this exchange is a key with :
+-
+
- KEYID = CKYi | CKYr +
- sKEYID = prf(Ni | Nr, KEY | CKYi | CKYr). +
The Aggressive Mode example is written to suggest that public key technology is used for the signatures. However, a pseudorandom function can be used, if the parties have previously agreed to such a scheme and have a shared key.
+If the first proposal in the EHAo list is an "existing key" method, then the KEYID named in that proposal will supply the keying material for the "signature" which is computed using the "H" algorithm associated with the KEYID.
+In this exchage the two parties are minimally aggressive; they use the cookie exchange to delay creation of state, and they use perfect forward secrecy to protect the identities.
+They use public key encryption for authentication; digital signatures or pre-shared keys can also be used. The Main mode does not change the use of nonces, prf's, etc., but it does change how much information is transmitted in each message.
+The responder considers the ability of the initiator to repeat CKYr as weak evidence that the message originates from a "live" correspondent on the network and the correspondent is associated with the initiator's network address.
+The initiator makes similar assumptions when CKYi is repeated to the initiator. All messages must have valid cookies or at least one zero cookie. If both cookies are zero, this indicates a request for a cookie; if only the initiator cookie is zero, it is a response to a cookie request.
+Information in messages violating the cookie rules cannot be used for any operations. Note that the Initiator and Responder must agree on one set of EHA algorithms; there is not one set for the Responder and one for the Initiator. The Initiator must include at least MD5 and DES in the initial offer.
+| Initiator | Message content | Responder |
| | CKYi, DHi, EHAo, JIDi, JIDr | |
| | CKYr, DHr, EHAs, JIDi, JIDr | |
| | GRP, CKYi, CKYr, DHi, EHAs, JIDi, JIDr, E{Ni}KEY | |
| | GRP, CKYi, CKYr, DHr, JIDi, JIDr, E{Ni | Nr}KEY, prf(Kir, JIDr | JIDi | GRP | DHr | DHi | EHAs ) | |
| | GRP, CKYi, CKYr, DHi, JIDi, JIDr, prf(Kir, JIDi | JIDr | GRP | DHi | DHr | EHAs ) | |
Where Kir = prf(0, Ni | Nr)
+The result of this exchange is a key with :
+-
+
- KEYID = CKYi | CKYr +
- sKEYID = prf(Kir, KEY | CKYi | CKYr). +
The keying material computed by the key exchange should have at least 90 bits of entropy, which means that it must be at least 90 bits in length. This may be more or less than is required for keying the encryption and/or pseudorandom function transforms.
+The transforms used should have auxiliary algorithms which take a variable precision integer and turn it into keying material of the appropriate length. The result of either Main Mode or Aggressive Mode is three groups of authenticated keying material:
+| Context | Keying Material |
| Digest | sKEYID_d = prf(sKEYID, KEY | CKYi | CKYi | 0) |
| Authentication | sKEYID_a = prf(sKEYID, SKEYID_d | KEY | CKYi | CKYr | 1) |
| Encryption | sKEYID_e = prf(sKEYID, SKEYID_a | KEY | CKYi | CKYr | 2) |
and agreed upon policy to protect further communications. The values of 0, 1, and 2 above are represented by a single octet. The key used for encryption is derived from sKEYID_e in an algorithm-specific manner.
+Encryption keys used to protect the SA are derived from sKEYID_e in an algorithm-specific manner. When SKEYID_e is not long enough to supply all the necessary keying material an algorithm requires, the key is derived from feeding the results of a pseudo-random function into itself, concatenating the results, and taking the highest necessary bits.
+For example, if the (ficticious) algorithm MYALGO requires 320-bits of key, and the prf used to generate sKEYID_e only generates 120 bits of material, the key for MYALGO, would be the first 320-bits of Ka, where:
+Ka = K1 | K2 | K3 | ...
++
And
+-
+
- K1 = prf(sKEYID_e, 0) +
- K2 = prf(sKEYID_e, K1) +
- K3 = prf(sKEYID_e, K2) +
- ... +
prf is the HMAC version of the negotiated hash function and 0 is represented by a single octet. Each result of the prf provides 120 bits of material for a total of 360 bits. MYALGO would use the first 320 bits of that 360 bit string.
+The intitiator uses a <SecurityAssociation/> element in the request to list all the EHA algorithms that it supports. In addition it provides its own DH ephemeral public key.
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants, respectively. + +
- The initiator cookie is prepared by generating a string of 32 random octets (64 random bits). The cookie resulting octets are then encoded into a string of hex characters. The generated value is used as the originator key name for the security association. +
-
+
- The available set of confidentiality and HMAC cryptographic algorithms is selected. The manner in which these algorithms are selected and all related policy issues are outside the scope of this specification. + +
- The available set of authentication algorithms is selected. The manner in which these algorithms are selected and all related policy issues are outside the scope of this specification. When the digital signature form of authentication is selected, the relevant end-entity certificate and, optionally, a chain of CA certificates representing a validation path, is assembled and encoded. A set of trusted CA certificates MAY optionally be included via caCertificate elements; if so, the set MUST include the issuer of the initiator's end-entity certificate. + +
These values are then used to prepare the XML element; this element is transmitted via the existing XMPP iq mechanism:
+ +
+
+
+
+A32F...245A
+
+
+
+
+]]>
+The responder will reply to the request by sending out its own selcted EHA algorithms that will be used in the remainign transaction.
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants, respectively. + +
- The responder cookie is prepared by generating a string of 32 random octets (64 random bits). The cookie resulting octets are then encoded into a string of hex characters. The generated value is used as the recipient key name for the security association.. + +
- The algorithms attributes are checked against the values supported by the user agent. If the receiver is not able to select one set out of the proposed algorithms, an error code 406-Unacceptable is returned. + +
- The desired confidentiality and HMAC cryptographic algorithms are selected from the proposed set. The manner in which these algorithms are selected and all related policy issues are outside the scope of this specification. + +
- The desired authentication algorithm is selected from the proposed set. The manner in which this algorithm is selected and all related policy issues are outside the scope of this specification. In the digital signature case, the responder's end-entity certificate MUST be issued by one of the trusted CAs listed in the session1 PDU or by the same issuer as the initiator's end-entity certificate. If the responder does not have acceptable credentials, an error code of 401-Unuthorized occurs. + +
+
+
+
+A32F...245A
+
+
+324A...BF24
+
+
+
+
+]]>
+The intitiator provides its own DH ephemeral public key.
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants, respectively. + +
- The initator and responder cookies are used as the originator key name and the recipient key name for the security association.. + +
- A Diffie-Hellman group is selected. The appropriate values for g and p will be used to generate the initiator's public key. + +
- An ephemeral private key, x, is generated using g and p for the selected group. This key MUST be generated using an appropriate random number source. The corresponding public key, g^x, is generated and encoded. +
+
+
+
+A32F...245A
+
+
+324A...BF24
+
+
+
+
+
+... encoded initiator public key
+
+
+
+
+
+]]>
+The responder check the validity of the parameters and eventualy replies with its own DH ephemeral public key.
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants, respectively. + +
- The initator and responder cookies are checked; a mismatch results in an error code of 406 - Unacceptable . + +
- The Diffie-Hellman group is checked against the values supported by the user agent. An unsupported group results in an error code of 406 - Unacceptable + +
- An ephemeral private key, y, is generated using g and p for the group indicated by the PDU. This key MUST be generated using an appropriate random number source. The corresponding public key, g^y, is generated and encoded. +
+
+
+
+A32F...245A
+
+
+324A...BF24
+
+
+
+
+
+... encoded initiator public key
+
+
+
+
+
+]]>
+The intitiator provides its nonce encrypted with the agreed algorithm and the public key of the responder.
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants, respectively. + +
- The initator and responder cookies are checked; a mismatch results in the procedure being aborted. + +
- The initiator nonce is prepared by first generating a string of 20 random octets (160 random bits). The nonce is then encrypted using the selected encryption algorithm and the shared secret key. The resulting octets are then encoded into a string of base64 characters. +
+
+
+
+A32F...245A
+
+
+324A...BF24
+
+
+
+
+
+
+
+... encoded encrypted initiator nonce
+
+
+
+
+
+
+
+]]>
+The responder replies with the concatenation of its own nonce and the initiator nonce encrypted with the agreed algorithm and the public key of the initiator. The packet is authenticated using the agreed signature algorithm.
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants, respectively. + +
- The initator and responder cookies are checked; a mismatch results in an error code of 401 - Unauthorized. + +
- The initiator nonce is decrypted using the responder private key. + +
- The responder nonce is prepared by first generating a string of 20 random octets (160 random bits). It is then apended to the initiator nonce and the result encrypted using the selected encryption algorithm and the shared secret key. The resulting octets are then encoded into a string of base64 characters. + +
- Based on the selected authentication algorithm, the responder's authenticator is constructed. A digital signature requires calculating: + +
-
+
- Kir = hmac (0, initiator's nonce | responder's nonce) + +
- EHAs = (Encryption algorithm URI | Digest algorithm URI | Signature algorithm URI) + +
- HASH_R = hmac (Kir, JID responder | JID initiator | length of DH group | responder DH public key | initiator DH public key | EHAs) + +
-
+
- HASH_R is encoded in base64. +
+
+
+
+A32F...245A
+
+
+324A...BF24
+
+
+
+
+
+
+
+... encoded encrypted responder nonce
+
+
+
+
+
+
+
+... encoded signature value
+
+
+
+
+]]>
+The initiator authenticate the keying material using the agreed signature algorithm.
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants, respectively. + +
- The initator and responder cookies are checked; a mismatch results in the procedure being aborted. + +
- The concatenation of the responder and initiator nonce is decrypted using the initiator private key. The original initiator nonce is compared to the result. An invalid nonce results in aborting the procedure. Otherwise the result is used to generate Kir + +
- Based on the selected authentication algorithm, the responder's authenticator is constructed. A digital signature requires calculating: + +
-
+
- Kir = hmac (0, initiator's nonce | responder's nonce) + +
- EHAs = (Encryption algorithm URI | Digest algorithm URI | Signature algorithm URI) + +
- HASH_R = hmac (Kir, JID responder | JID initiator | length of DH group | responder DH public key | initiator DH public key | EHAs) + +
-
+
- The authenticator is verified. A failure results in aborting the procedure. + +
- Based on the selected authentication algorithm, the initiator’s authenticator is constructed. A digital signature requires calculating: + +
-
+
- HASH_I = hmac (Kir, JID initiator | JID responder | length of DH group | initiator DH public key | responder DH public key | EHAs) + +
+
+
+
+A32F...245A
+
+
+324A...BF24
+
+
+
+
+... encoded signature value
+
+
+
+
+]]>
+The responder acknowledge the keying material.
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants, respectively. + +
- The initator and responder cookies are checked; a mismatch results in an error code of 401 - Unauthorized. + +
- Based on the selected authentication algorithm, the initiator's authenticator is constructed. A digital signature requires calculating: + +
-
+
- HASH_I = hmac (Kir, JID initiator | JID responder | length of DH group | initiator DH public key | responder DH public key | EHAs) + +
-
+
- The authenticator is verified. A failure results in an error code of 406 - Unacceptable. + +
+]]>
+The intitiator uses <SecurityAssociation/> element in the request to list all the EHA algorithms that it supports. In addition it provides its own DH ephemeral public key. The message is signed with its own private key.
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants, respectively. + +
- The initiator cookie is prepared by generating a string of 32 random octets (64 random bits). The cookie resulting octets are then encoded into a string of hex characters. The generated value will be used as identifier for the initiator leg of the security association. + +
- The available set of confidentiality and HMAC cryptographic algorithms is selected. The manner in which these algorithms are selected and all related policy issues are outside the scope of this specification. + +
- The available set of authentication algorithms is selected. The manner in which these algorithms are selected and all related policy issues are outside the scope of this specification. When the digital signature form of authentication is selected, the relevant end-entity certificate and, optionally, a chain of CA certificates representing a validation path, is assembled and encoded. A set of trusted CA certificates MAY optionally be included via caCertificate elements; if so, the set MUST include the issuer of the initiator's end-entity certificate. + +
- A Diffie-Hellman group is selected. The appropriate values for g and p will be used to generate the initiator's public key. + +
- An ephemeral private key, x, is generated using g and p for the selected group. This key MUST be generated using an appropriate random number source. The corresponding public key, g^x, is generated and encoded. + +
- The initiator nonce is prepared by first generating a string of 20 random octets (160 random bits). The resulting octets are then encoded into a string of base64 characters. + +
- Based on the selected authentication algorithm, the initiator's authenticator is constructed. A digital signature requires calculating: + +
-
+
- EHAs = (Encryption algorithm URI | Digest algorithm URI | Signature algorithm URI) + +
- SIGN_I = S (JID initiator | JID responder | initiator cookie | 0 | initiator nonce | 0 | length of DH group | initiator DH public key | 0 | EHAs) initiator private key + +
-
+
- SIGN_I is encoded in base64. +
+
+
+
+A32F...245A
+
+... encoded initiator public key value
+
+
+
+
+
+
+... encoded initiator public key
+
+
+
+... encoded initiator nonce value>
+
+
+
+
+... encoded initiator signature value
+
+
+
+
+]]>
+The responder will reply to the request by acknowledging the selected EHA algorithms. In addition, it provides its own DH ephemeral public key. The message is signed with its own private key.
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants, respectively. + +
- The Diffie-Hellman group is checked against the values supported by the user agent. An unsupported group results in an error code of 406 - Unacceptable + +
- Based on the selected authentication algorithm, the initiator's authenticator is constructed. A digital signature requires calculating: + +
-
+
- EHAs = (Encryption algorithm URI | Digest algorithm URI | Signature algorithm URI) + +
- SIGN_I = S (JID initiator | JID responder | initiator cookie | 0 | initiator nonce | 0 | length of DH group | initiator DH public key | 0 | EHAs) initiator public key + +
-
+
- The authenticator is verified. A failure results in an error code of 401 - Unauthorized. + +
- The responder cookie is prepared by generating a string of 32 random octets (64 random bits). The cookie resulting octets are then encoded into a string of hex characters. The generated value will be used as identifier for the responder leg of the security association. + +
- An ephemeral private key, y, is generated using g and p for the group indicated by the PDU. This key MUST be generated using an appropriate random number source. The corresponding public key, g^y, is generated and encoded. + +
- The responder nonce is prepared by first generating a string of 20 random octets (160 random bits). The resulting octets are then encoded into a string of base64 characters. + +
- Based on the selected authentication algorithm, the responder's authenticator is constructed. A digital signature requires calculating: + +
-
+
- SIGN_R = S (JID responder | JID initiator | responder cookie | initiator cookie | responder nonce | initiator nonce | length of DH group | responder DH public key | initiator DH public key | EHAs) responder private key + +
-
+
- SIGN_R is encoded in base64. +
+
+
+
+A32F...245A
+
+
+324A...BF24
+
+... encoded responder public key value
+
+
+
+
+
+
+... encoded responder public key
+
+
+
+... encoded responder nonce value>
+
+
+
+
+... encoded responder signature value
+
+
+
+
+]]>
+The initiator authenticate the keying material using the agreed signature algorithm.
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants, respectively. + +
- Based on the selected authentication algorithm, the initiator's authenticator is constructed. A digital signature requires calculating: + +
-
+
- EHAs = (Encryption algorithm URI | Digest algorithm URI | Signature algorithm URI) + +
- SIGN_R = S (JID responder | JID initiator | responder cookie | initiator cookie | responder nonce | initiator nonce | length of DH group | responder DH public key | initiator DH public key | EHAs) responder public key + +
-
+
- The authenticator is verified. A failure results in the procedure being aborted. + +
- Based on the selected authentication algorithm, the authenticator is constructed. A digital signature requires calculating: + +
-
+
- SIGN_I = S (JID initiator | JID responder | initiator cookie | responder cookie | initiator nonce | responder nonce | length of DH group | initiator DH public key | responder DH public key | EHAs) shared secret key + +
-
+
- SIGN_I is encoded in base64. +
+
+
+
+A32F...245A
+
+
+324A...BF24
+
+
+
+
+... encoded signature value
+
+
+
+]]>
+The responder acknowledge the keying material.
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants, respectively. + +
- Based on the selected authentication algorithm, the initiator's authenticator is constructed. A digital signature requires calculating: + +
-
+
- EHAs = (Encryption algorithm URI | Digest algorithm URI | Signature algorithm URI) + +
- SIGN_I = S (JID initiator | JID responder | initiator cookie | responder cookie | initiator nonce | responder nonce | length of DH group | initiator DH public key | responder DH public key | EHAs) shared secret key + +
-
+
- The authenticator is verified. A failure results in an error code of 406 - Unacceptable. + +
+]]>
+
+Conversation keys are transported using the symmetric key wrap feature of XML Encryption embedded in the KeyTransport PDU.
+Key transport follow a previous Security Association establishment and the generation of a shared secret key through a key agreement.
+| Initiator | Message content | Responder |
| | JIDi, JIDr, CKYe, sKEYID_e, CKYa, sKEYID_a, CKYd, sKEYID_d, S{JIDi | JIDr | Ni | Nr | CKYe | sKEYID_e | CKYa | sKEYID_a | CKYd | sKEYID_d }KEY | |
The Key Transport assumes that a security association be negotiated for the purpose of securely transporting conversation keys. The sender's user agent employs the following algorithm to generate the keyTransport PDU:
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants who negotiated the security association, respectively. + +
- The security association identifier is assembled. + +
- The payload, which consists of the confidentiality key sKEYID_e, digest key sKEYID_d and the integrity key sKEYID_a , is wrapped in instances of xenc:EncryptedKey as follows: + +
-
+
- The Type attribute of the xenc:EncryptedKey element MUST indicate 'content'. + +
- The Id, MimeType and Encoding attributes of the xenc:EncryptedKey element MUST NOT be present. + +
- The xenc:EncryptionMethod element MUST be present, and the Algorithm attribute MUST indicate a valid symmetric key wrap algorithm. Furthermore, the algorithm MUST be the same as was negotiated for the security association. + +
- The ds:KeyInfo element MUST NOT be present. The key to use is the shared secret KEY of the negotiated security association. + +
- The xenc:ContainedKeyName element MUST be present. + +
- The xenc:CipherData element MUST be present, and it MUST use the CipherValue choice. +
-
+
- The HMAC is computed using KEY of the negotiated security association. A digital signature requires calculating: + +
-
+
- HMAC = prf(KEY, JIDi | JIDr | Ni | Nr | sKEYID_e | key name | sKEYID_e | sKEYID_a key name | sKEYID_a | sKEYID_d key name | sKEYID_d) + +
These values are then used to prepare the XML KeyTransport element; this element is transmitted via the existing XMPP iq mechanism. The order in which the keys are in the payload is significant. The first mandatory key is sKEYID_e. The second optional key is sKEYID_a. And the last optional key is sKEYID_d.
+ +
+
+
+
+A32F...245A324A...BF24-enc</ContainedKeyName>
+
+
+... encoded encrypted confidentiality key
+
+
+
+
+A32F...245A324A...BF24-auth</ContainedKeyName>
+
+
+... encoded encrypted confidentiality key
+
+
+
+
+A32F...245A324A...BF24-dig</ContainedKeyName>
+
+
+... encoded encrypted confidentiality key
+
+
+
+
+
+
+
+
+... encoded signature value
+
+
+
+
+]]>
+The receiver's user agent employs the following algorithm to process each KeyTransport PDU:
+-
+
- The values of initiator, responder, and security association id MUST indicate an existing security association. An invalid security association results in an error of 401 - Unauthorized. + +
- The payload, which consists of the confidentiality key sKEYID_e, digest key sKEYID_d and the intergrity key sKEYID_a, is unwrapped. Any failures result in an error code of 406-Unacceptable. + +
- The body of the HMAC element is decoded into the actual HMAC octet string. + +
- The HMAC is computed using KEY of the security association. A digital signature requires calculating: + +
-
+
- HMAC = prf(KEY, JIDi | JIDr | Ni | Nr | sKEYID_e key name | sKEYID_e | sKEYID_a key name | sKEYID_a | sKEYID_d key name | sKEYID_d) + +
-
+
- The HMAC is validated. An invalid HMAC results in an error code of 406-Unacceptable. + +
- The keys are added to the user agent's key store. +
If any errors occur during processing, the error is communicated via the existing XMPP mechanism:
+ +
+]]>
+
+Public keys are transported embedded in the KeyTransport PDU.
+X509 certificates can also be transported in existing XMPP message. The following example uses a presence subscription packet as the vehicle PDU. The subscribee public key and certificate are sent to the initiator of a presence subscription.
+ +
+
+
+
+
+
+
+ CN=TAMURA Kent, OU=TRL, O=IBM, L=Yamato-shi, ST=Kanagawa, C=JP
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+-
+
- The values of initiator and responder MUST be the JIDs of the two participants in the exchange, respectively. + +
- The payload, which consists of the public key of the responder is assembled. +
-
+
- The SIGN is computed using the private key of the responder. A digital signature requires calculating: + +
-
+
- SIGN = S (JIRi | JIDR | Kr name | Kr) responder private key + +
These values are then used to prepare the XML KeyTransport element; this element is transmitted via an existing XMPP mechanism. In the following example, the responder public key is sent to the initiator of a presence subscription.
+ +
+
+
+
+responder@domain key name
+
+... encoded responder public key value
+
+
+
+
+
+
+
+... encoded signature value
+
+
+
+
+]]>
+The ultimate goal is the protection of conversation data. The protocol exchanges described above allow the conversation participants to cryptographically protect their conversation data using the conversation keys that they share.
+A protected message is defined as a traditional XMPP message whose body content is extended to include the transport of a cryptographically protected message body. The two key features are:
+-
+
- the usual body element contains some arbitrary text. + +
- the message contains a XMPP x element defining the xmpp:sec namespace; this element transports the protected message. +
This mechanism has the advantages of allowing transparent integration with existing XMPP servers and existing XMPP clients.
+The sender's user agent employs the following algorithm to generate the protected Message PDU:
+-
+
- The security association identifier is assembled. + +
- The actual message body is encoded into a character string corresponding to a XMPP message body element. This character string is then wrapped in an instance of xenc:EncryptedData as follows: +
-
+
- The Type attribute of the xenc:EncryptedData element MUST indicate 'element'. + +
- The Id, MimeType and Encoding attributes of the xenc:EncryptedData element MUST NOT be present. + +
- The xenc:EncryptionMethod element MUST be present, and the Algorithm attribute MUST indicate a valid block encryption algorithm. + +
- The ds:KeyInfo element MUST NOT be present. The key to be used is the confidentiality key indicated by the convId attribute. + +
- The xenc:CipherData element MUST be present, and it MUST use the CipherValue choice. +
-
+
- Using the HMAC key indicated by the security association, the HMAC is computed. A digital signature requires calculating: + +
-
+
- HMAC = prf(sKEYID_d, key name | JID from | JID to | message id | message type | message thread | message subject | message body) + +
These values are then used to prepare the XML protected element; this element is transmitted via the existing XMPP message mechanism:
+ +
+
+The real body is protected.
+
+
+
+
+A32F2...45A324A...BF24-enc
+
+
+
+... encoded encrypted message content
+
+
+
+
+
+
+
+A32F2...45A324A...BF24-auth
+
+
+... encoded signature value
+
+
+
+
+]]>
+The receiver's user agent employs the following algorithm to process each protectedMessage PDU:
+-
+
- The values of initiator, responder, and key name MUST indicate an existing security association. An invalid security association results in an error of 406-Unacceptable. + +
- The payload, which consists of the actual message body, is unwrapped. Any failures result in an error code of 406-Unacceptable. + +
- The body of the HMAC element is decoded into the actual HMAC octet string. + +
- Using the HMAC key indicated by the security association, the HMAC is computed. A digital signature requires calculating: + +
-
+
- HMAC = prf(sKEYID_d, key name | JID from | JID to | message id | message type | message thread | message subject | message body) + +
-
+
- The HMAC is validated. An invalid HMAC results in an error code of 406-Unacceptable. +
If any errors occur during processing, the error is communicated via the existing XMPP mechanism:
+This section discusses algorithms used with the XMPP security specification. Entries contain the identifier to be used as the value of the Algorithm attribute of the EncryptionMethod element or other element representing the role of the algorithm, a reference to the formal specification, definitions for the representation of keys and the results of cryptographic operations where applicable, and general applicability comments.
+The table below lists the categories of algorithms. Within each category, a brief name, the level of implementation requirement, and an identifying URI are given for each algorithm.
+| Category | Algorithm | URI |
| Block Encryption | TRIPLEDES | tripledes-cbc |
| AES-128 | aes128-cbc | |
| AES-192 | aes192-cbc | |
| AES-256 | aes256-cbc | |
| Key Transport | RSA-v1.5 | rsa-1_5 |
| RSA-OAEP | rsa-oaep-mgf1p | |
| Symmetric Key Wrap | TRIPLEDES KeyWrap | kw-tripledes |
| AES-128 KeyWrap | kw-aes128 | |
| AES-256 KeyWrap | kw-aes256 | |
| AES-192 KeyWrap | kw-aes192 | |
| Message Digest | MD5 | md5 |
| SHA1 | sha1 | |
| SHA256 | sha256 | |
| SHA512 | sha512 | |
| RIPEMD-160 | ripemd160 | |
| HMAC-MD5 | hmac-md5 | |
| HMAC-SHA1 | hmac-sha1 | |
| HMAC-SHA128 | hmac-sha128 | |
| HMAC-SHA256 | hmac-sha256 | |
| Signature | DSAwithSHA1 (DSS) | dsa-sha1 |
| RSAwithSHA1 | rsa-sha1 | |
An RSA Laboratories Technical Note
+Version 1.4
+Revised November 1, 1993 Supersedes June 3, 1991 version, which was also published as NIST/OSI Implementors' Workshop document SEC-SIG-91-19. PKCS documents are available by electronic mail to <pkcs@rsa.com>.
This standard describes a method for implementing Diffie-Hellman key agreement, whereby two parties, without any prior arrangements, can agree upon a secret key that is known only to them (and, in particular, is not known to an eavesdropper listening to the dialogue by which the parties agree on the key). This secret key can then be used, for example, to encrypt further communications between the parties.
+The intended application of this standard is in protocols for establishing secure connections, such as those proposed for OSI's transport and network layers [ISO90a][ISO90b].
+Details on the interpretation of the agreed-upon secret key are outside the scope of this standard, as are details on sources of the pseudorandom bits required by this standard.
+X.208 CCITT. Recommendation X.208: Specification of Abstract Syntax Notation One (ASN.1). 1988.
+X.509 CCITT. Recommendation X.509: The Directory—Authentication Framework. 1988.
+[DH76] W. Diffie and M.E. Hellman. New directions in cryptography. IEEE Transactions on Information Theory, IT-22:644-654, 1976.
+[Sch90] C.P. Schnorr. Efficient identification and signatures for smart cards. In G. Brassard, editor, Advances in Cryptology—CRYPTO '89 Proceedings, volume 435 of Lecture Notes in Computer Science, pages 239-251. Springer-Verlag, New York, 1990.
+[ISO90a] ISO. JTC1/SC6/N6285: Draft Transport Layer Security Protocol. Draft, November 1990.
+[ISO90b] ISO. JTC1/SC6/N2559: Draft Network Layer Security Protocol. Draft, September 1990.
+For the purposes of this standard, the following definitions apply.
+AlgorithmIdentifier: A type that identifies an algorithm (by object identifier) and any associated parameters. This type is defined in X.509.
+ASN.1: Abstract Syntax Notation One, as defined in X.208.
+Diffie-Hellman parameters: Prime and base.
+Diffie-Hellman: The Diffie-Hellman key-agreement protocol, elsewhere called "exponential key agreement," as defined in [DH76].
+Upper-case italic symbols (e.g., PV) denote octet strings; lower-case italic symbols (e.g., g) denote integers.
+| PV public value | p prime |
| PV' other's public value | x private value |
| SK secret key | x' other's private value |
| G base | y integer public value |
| K length of prime in octets | y' other's integer public value |
| L length of private value in bits | z integer secret key |
| mod n modulo n |
The next four sections specify parameter generation, two phases of Diffie-Hellman key agreement, and an object identifier.
+A central authority shall generate Diffie-Hellman parameters, and the two phases of key agreement shall be performed with these parameters. It is possible that more than one instance of parameters may be generated by a given central authority, and that there may be more than one central authority. Indeed, each entity may be its own central authority, with different entities having different parameters. The algorithm identifier for Diffie-Hellman key agreement specifies which Diffie-Hellman parameters are employed.
+Two entities intending to agree on a secret key shall employ the first phase independently to produce outputs PV and PV', the public values. The entities shall exchange the outputs.
+The entities shall then employ the second phase independently with the other entity's public value as input. The mathematics of Diffie-Hellman key agreement ensure that the outputs SK of the second phase are the same for both entities.
+This section describes Diffie-Hellman parameter generation.
+A central authority shall select an odd prime p. The central authority shall also select an integer g, the base, that satisfies 0 < g < p. The central authority may optionally select an integer l, the private-value length in bits, that satisfies 2l-1 ≤ p.
+The length of the prime p in octets is the integer k satisfying
+28(k−1) ≤ p < 28k .
+1. The cost of some methods for computing discrete logarithms depends on the the length of the prime, while the cost of others depends on the length of the private value. The intention of selecting a private-value length is to reduce the computation time for key agreement, while maintaining a given level of security. A similar optimization is suggested by Schnorr [Sch90].
+2. Some additional conditions on the choice of prime, base, and private-value length may well be taken into account in order to deter discrete logarithm computation. These security conditions fall outside the scope of this standard.
+This section describes the first phase of Diffie-Hellman key agreement.
+The first phase consists of three steps: private-value generation, exponentiation, and integer-to-octet-string conversion. The input to the first phase shall be the Diffie-Hellman parameters. The output from the first phase shall be an octet string PV, the public value; and an integer x, the private value.
+This phase is performed independently by the two parties intending to agree on a secret key.
+An integer x, the private value, shall be generated privately and randomly. This integer shall satisfy 0 < x < p−1, unless the central authority specifies a private-value length l, in which case the integer shall satisfy 2l-1 ≤ x < 2l.
+The base g shall be raised to the private value x modulo p to give an integer y, the integer public value.
+y = gx mod p, 0 < y < p .
+This is the classic discrete-exponentiation computation.
+The integer public value y shall be converted to an octet string PV of length k, the public value. The public value PV shall satisfy
+y = , (1)
+where PV1, ..., PVk are the octets of PV from first to last.
+In other words, the first octet of PV has the most significance in the integer and the last octet of PV has the least significance.
+This section describes the second phase of Diffie-Hellman key agreement.
+The second phase consists of three steps: octet-string-to-integer conversion, exponentiation, and integer-to-octet-string conversion. The input to the second phase shall be the Diffie-Hellman parameters; an octet string PV', the other entity's public value; and the private value x. The output from the second phase shall be an octet string SK, the agreed-upon secret key.
+This phase is performed independently by the two parties intending to agree on a secret key, after the parties have exchanged public values resulting from the first phase.
+The other entity's public value PV' shall be converted to an integer y', the other entity's integer public value. Let PV'1, ..., PV'k be the octets of PV' from first to last. Then the other entity's integer public value y' shall satisfy
+y' = .
+In other words, the first octet of PV' has the most significance in the integer and the last octet of PV' has the least significance.
+The other entity's integer public value y' shall be raised to the private integer x modulo p to give an integer z, the integer secret key.
+z = (y')x mod p, 0 < z < p .
+This is the classic discrete-exponentiation computation.
+Note. The integer secret key z satisfies
+z = (y')x = (gx')x = (gx)x' = yx' mod p ,
+where x' is the other entity's private value. This mathematical relationship is the reason the two entities arrive at the same key.
+The integer secret key z shall be converted to an octet string SK, the secret key, of length k. The secret key SK shall satisfy
+z = ,
+where SK1, ..., SKk are the octets of SK from first to last.
+In other words, the first octet of SK has the most significance in the integer and the last octet of SK has the least significance.
+This standard defines two object identifiers: pkcs-3 and DHKeyValue.
+The object identifier pkcs-3 identifies this standard.
+pkcs-3 OBJECT IDENTIFIER ::= + { iso(1) member-body(2) US(840) rsadsi(113549) + pkcs(1) 3 }
+The object identifier DHKeyValue identifies the Diffie-Hellman key agreement method defined in Sections 7 and 8.
+DHKeyValue OBJECT IDENTIFIER ::= { pkcs-3 1 }
+The DHKeyValue object identifier is intended to be used in the algorithm field of a value of type AlgorithmIdentifier. The parameters field of that type, which has the algorithm-specific syntax ANY DEFINED BY algorithm, would have ASN.1 type DHParameter for this algorithm.
+DHParameter ::= SEQUENCE { + prime INTEGER, - p + base INTEGER, - g + privateValueLength INTEGER OPTIONAL }
+The fields of type DHParameter have the following meanings:
+-
+
- prime is the prime p. +
- base is the base g. +
- privateValueLength is the optional private-value length l. +
Versions 1.0-1.2 were distributed to participants in RSA Data Security, Inc.'s Public-Key Cryptography Standards meetings in February and March 1991.
+Version 1.3 is part of the June 3, 1991 initial public release of PKCS. Version 1.3 was published as NIST/OSI Implementors' Workshop document SEC-SIG-91-19.
+Version 1.4 incorporates several editorial changes, including updates to the references and the addition of a revision history. The following substantive changes were made:
+-
+
- Section 6: Parameter generation is modified to allow central authority to select private-value length in bits. +
- Section 7.1: Private-value generation is modified to handle private-value length. +
- Section 9: Optional privateValueLength field is added to DHParameter type. +
RSA Laboratories (415) 595-7703 +100 Marine Parkway (415) 595-4126 (fax) +Redwood City, CA 94065 USA pkcs-editor@rsa.com
+Different Diffie-Hellman groups are defined for use in IKE. These groups were generated by Richard Schroeppel at the University of Arizona. Properties of these primes are described in [Orm96].
+IKE implementations MAY support a MODP group with the following prime and generator. This group is assigned id 1 (one).
+The prime is: 2^768 - 2 ^704 - 1 + 2^64 * { [2^638 pi] + 149686 } Its hexadecimal value is:
+The generator is: 2.
+IKE implementations SHOULD support a MODP group with the following prime and generator. This group is assigned id 2 (two).
+The prime is 2^1024 - 2^960 - 1 + 2^64 * { [2^894 pi] + 129093 }. Its hexadecimal value is:
+The generator is 2 (decimal)
+IKE implementations MUST support a MODP group with the following prime and generator. This group is assigned id 5 (five). The 1536 bit MODP group has been used for the implementations for quite a long time, but it has not been documented in the current RFCs or drafts.
+The prime is 2^1536 - 2^1472 - 1 + 2^64 * {[2^1406 pi] + 741804}. Its hexadecimal value is
+The generator is 2.
+This prime is: 2^2048 - 2^1984 - 1 + 2^64 * { [2^1918 pi] + 124476 } Its hexadecimal value is
+The generator is: 2.
+This prime is: 2^3072 - 2^3008 - 1 + 2^64 * { [2^2942 pi] + 1690314 }
+Its hexadecimal value is:
+The generator is: 2.
+This prime is: 2^4096 - 2^4032 - 1 + 2^64 * { [2^3966 pi] + 240904 }
+Its hexadecimal value is :
+The generator is: 2.
+This prime is: 2^6144 - 2^6080 - 1 + 2^64 * { [2^6014 pi] + 929484 }
+Its hexadecimal value is :
+The generator is: 2.
+This prime is: 2^8192 - 2^8128 - 1 + 2^64 * { [2^8062 pi] + 4743158 }
+Its hexadecimal value is :
+The generator is: 2.
+As Jabber becomes more widely utilized, applications of the protocol are veering away from traditional use as an IM product and are utilizing it for more generic data transportation and negotiation. While many advances are being made to facilitate non-IM data transportation, they do not address the use of already-established mechanisms of transporting data via URLs. This JEP provides a method that is compatible with these data transportation mechanisms and that is based on standard Internet Uniform Resource Locators (see &rfc3986;).
+The requirements this protocol fulfills are:
+-
+
- Simple usage that can be easily extended +
- Provide any meta-data necessary for using the URL +
- Compatibility with &jep0095; +
The simplest use of this protocol is to provide just a URL to another entity.
+If more information is necessary for successfully using the URL, the sender includes meta-information in a scheme-specific format such as that defined in &jep0104;:
+The above example illustrates supplying a HTTP URL with a cookie header. Additional information could be provided, such as HTTP authentication requirements or even POST data.
+To support the use of bulk publishing methods such as &jep0060; or messages of type "headline", the <desc/> element is used to provide a textual description:
+To use "url-data" in conjunction with SI, the "sid" attribute of <url-data/> is used. This attribute MUST be equal to the SI session id.
+The general process flow for using "url-data" with SI is as follows
-
+
- The sender makes a SI request, adding "http://jabber.org/protocols/url-data" as one of the "stream-method" features. +
- The receiver accepts the SI request, and selects "http://jabber.org/protocols/url-data". +
- The sender provides an &IQ; with the <url-data/>. +
- The receiver retrieves the data from the provided URL [E1, E2]. +
- Once retrieval is complete, the Receiver responds to Sender (EUC). +
-
+
- E1: The given URL is not supported/understood +
- E2: Failure to connect to the given URL +
The sender starts with an SI request, using the semantics from JEP-0095:
+The receiver then accepts the request, specifying "url-data" as the stream method:
+The sender then sends an &IQ; with type "set" to the receiver, providing the <url-data/> element with the URL in the "target" attribute:
+The receiver attempts to retrieve the data from the given URL. The receiver MUST NOT respond to the &IQ; until the data is completely retrieved, or an error occurs. If the retrieval is successful, the receiver responds with an "iq-result":
+Including the <url-data/> element in the result is NOT REQUIRED.
+If the receiver does not understand or support the URL, it responds with an "iq-error" with the <malformed-url/> condition:
+If the receiver fails to retrieve data from the URL, it responds with an "iq-error" with the <transfer-failed/> condition:
+If the receiver refuses to accept the URL, it responds with an "iq-error" with the <transfer-refused/> condition:
+The additional information provided by a particular scheme is OPTIONAL. The additional data is provided as XML in a dedicated namespace, and this namespace SHOULD be declared (with an appropriate prefix) within the <url-data/> element.
+Entities receiving a <url-data/> element MAY incorporate this information into the use of the URL as necessary. An entity providing a <url-data/> with scheme-specific information SHOULD NOT assume the receiving entity understands it, even if the receiving entity is capable of processing a URL for that scheme.
+The <url-data/> element provides the root structure for providing URL addresses. The element has attribute for the target URL and (optional) stream identifier. It contains content for the optional description, and any and all scheme-specific content.
+The attribute "target" contains the URL. This attribute MUST be present, and MUST be a valid URL.
+The attribute "sid" contains the stream identifier. While this attribute is optional, its usage is REQUIRED when used with Stream Initiation, and MUST contain the Stream Initiation identifier previously agreed to.
+In cases where textual descriptions cannot be provided, this element fullfills this need. It MAY include the "xml:lang" attribute for localization purposes, and its content is the text of the description. Multiple instances of <desc/> MAY be present, but each instance MUST have a different value for "xml:lang" attribute.
+To simplify the discussion on error conditions, this document uses the following mapping between namespace URIs and namespace prefixes
| Prefix | +URI | +
|---|---|
| xmpp | +urn:ietf:params:xml:ns:xmpp-stanzas | +
| url | +http://jabber.org/protocol/url-data | +
Below are the errors that can result.
+| Error Type | +General Condition | +Specific Condition | +Description | +
|---|---|---|---|
| modify | +<xmpp:bad-request/> | +<url:malformed-url/> | +The URL is not supported or understood. | +
| cancel | +<xmpp:not-acceptable/> | +<url:transfer-refused/> | +The URL transfer failed for some unspecified reason. | +
| cancel | +<xmpp:undefined-condition/> | +<url:transfer-failed/> | +The URL transfer failed for some unspecified reason. | +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+ This JEP does not yet have any security considerations.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; shall register the namespace "http://jabber.org/protocol/url-data" as a standard namespace. Also, the Jabber Registrar shall register the &jep0020; option "url-data" for use with Stream Initiation.
+The most common URL scheme distributed over the Internet is HTTP and HTTPS. This JEP defines a structure that extends &jep0103; to enable more advanced access to such URLs within Jabber.
+This JEP supplements JEP-0103 to provide more detailed information about HTTP and HTTPS URLs. The requirements this JEP fulfills are:
+-
+
- Provide authentication information. +
- Provide cookie data. +
- Provide necessary headers. +
The intent of this information is to provide an HTTP client with enough information in order to construct the HTTP request and entity headers necessary, as defined in &rfc2616;.
+The use of this JEP in conjunction with JEP-0103 is OPTIONAL. The entity sending the URL is not required to provide any of this information, and receiving entities MAY ignore it.
+The two most typical types of information that can be necessary for accessing an HTTP URL are authentication details and cookies. In some cases, custom headers MAY also be necessary for successful use. Authentication information is provided in a scheme-independent format. Cookie data provided includes what would be necessary for a client to properly persist the value.
+At a minimum, this JEP allows for an entity to indicate what authentication scheme is in use:
+To provide additional parameters (such as a realm and username/password), the <auth-param/> element is used:
+
+
+
+
+
+
+ ]]>
+ Cookie information is provided by the <cookie/> element. This element can provide all of the information of the "Set-Cookie" response header
+
+
+
+ ]]>
+ The above cookie is considered "transient", and will terminate when the HTTP session ends. Additional information about the cookie can be provided:
+
+
+
+
+ ]]>
+ As demonstrated, the <cookie/> provides all the attributes provided by the "Set-Cookie" header. The only attributes required are "name" and "value".
+In some cases, arbitrary headers are necessary. They are provided using the <header/> element:
+
+
+
+
+ ]]>
+ Entities receiving cookie information SHOULD following the state management guidelines from &rfc2109;. In particular, the interpretation of the "persistence details" attribute values from <cookie/> is that defined in section 4.2.2 of RFC 1209.
+The attributes provided by <cookie/> MUST NOT be "pre-escaped" for HTTP message headers. it is the responsibility of the receiving entity to properly encode cookie information into the "cookie" message header, including any character escaping.
+The <header/> element only provides those message headers used for an HTTP request. There is currently no mechanism to convey HTTP response headers.
+The name and value attributes from <header/> MUST NOT be "pre-escaped" for HTTP message headers. It is the responsibility of the receiving entity to properly encode message headers, including any character escaping.
+The namespace for this structure is "http://jabber.org/protocol/url-data/scheme/http". Because this namespace is intended to supplement the <url-data/> element, this namespace SHOULD be declared within the <url-data/> element using the "http" namespace prefix (as demonstrated in the examples above). This namespace MUST only be applied when the "target" attribute in <url-data/> uses the scheme "http" or "https".
+The <auth/> element provides authentication information, including scheme. The contents of this element detail any additional parameters for authentication.
+The "scheme" attribute describes the HTTP authentication scheme to use. This attribute MUST be present, and MUST be the name of an HTTP authentication scheme (such as "basic").
+The <auth-param/> element provides authentication parameters. This element has attributes for the parameter name and value.
+The "name" attribute specifies the (logical) name of the authentication parameter. This attribute MUST be present, and MUST be applicable to the given scheme, although "realm" is always a valid parameter.
+The "value" attribute specifies the value for this authentication parameter. This attribute MUST be present, but MAY be empty if a value is not required.
+The <cookie/> element provides client cookie data. This element has attributes for the cookie name and value, as well as the persistence details.
+The "name" attribute specifies the name of the cookie. This attribute MUST be present, and MUST NOT be empty. It corresponds to the "name" in the "name=value" syntax.
+The "value" attribute specifies the value for the cookie. This attribute MUST be present, but MAY be empty if a value is not required. It corresponds to the "value" in the "name=value" syntax.
+The "comment" attribute provides the description of the cookie, as would be provided via the "Set-Cookie" header. This attribute is OPTIONAL.
+The "domain" attribute provides the applicable domain of the cookie, as would be provided via the "Set-Cookie" header. This attribute is OPTIONAL.
+The "path" attribute provides the applicable HTTP path of the cookie, as would be provided via the "Set-Cookie" header. This attribute is OPTIONAL.
+The "max-age" attribute provides the maximum age for the cookie, as would be provided via the "Set-Cookie" header. This attribute is OPTIONAL, and MUST be a non-negative integer. If not specified, the default value is "0".
+The "secure" attribute indicates if this cookie is only offered in secure environments, as would be provided via the "Set-Cookie" header. This attribute is OPTIONAL, and MUST be a boolean value of "true" or "false". The default value is "false".
+The "version" attribute provides the version of the cookie, as would be provided via the "Set-Cookie" header. This attribute is OPTIONAL, and SHOULD be "1.0" unless otherwise needed. If not specified, the default value is "1.0".
+The <header/> element provides generic request and entity header information, to be included in the connection attempt. This element is ONLY for message headers included in the HTTP request; it SHOULD NOT be used for message headers included in the HTTP response. The attributes for this element are the name and value of the header.
+The "name" attribute specifies the name of the header. This attribute MUST be present, and MUST conform to the "field-name" pattern for RFC 2616. It corresponds to the "name" in the (simplified) "name: value" header syntax.
+The "value" attribute specifies the value of the header. This attribute MUST be present, and MUST conform to the "field-value" pattern for RFC 2616. It MAY empty if a value is not required. It corresponds to the "value" in the (simplified) "name: value" header syntax.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+ This JEP allows complete authentication information to be passed. This information is only as secure as the connection-path between the provider and acceptor.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; shall register the "http://jabber.org/protocol/url-data/scheme/http" namespace.
+File transfers of entire trees require a lot more meta-data and prior setup to link paths to files with unique ids so that clients can track them. This profile provides a more robust method of defining that meta-data so that directory trees can be transfered.
+-
+
- Provide a full featured set of information that is applicable to tree transfers. +
- Meta-data that is to be provided:
+
-
+
- number of files +
- size of entire tree +
- list of files and stream ids +
+
The tree transfer profile is in the "http://jabber.org/protocol/si/profile/tree-transfer" namespace. The profile is fairly simple: it consists of the root element with child elements that specify a directory structure of files with stream ids that will be used for each file.
+This profile requires support for the File Transfer profile described in &jep0096;. Once you have accepted this SI, a new SI using the File Transfer profile will be offered for each file in the tree. This profile provides a mapping of files with paths and reserved stream ids which will be used to auto-accept a File Transfer SI that uses that same stream id from the sender.
+The root element is <tree> and has two attributes. The attributes are used only during the offer stage of stream initiation:
+-
+
- size - The size, in bytes, of all of the files to be sent. +
- numfiles - The number of files/File Transfer SIs that are in the tree. +
The size and numfiles attributes MUST be present in the profile.
+The only possible child element of the root is <directory/> since there are other JEPs that handle single file transfers. The directory structure is sent in a hierarchical manner with nested <directory/> and/or <file/> tags. One or more <file/> elements will be sent, one for each file. One or more <directory/> elements will be sent, one for each directory.
+The <directory/> element has one attribute:
+-
+
- name - The name of the directory to create on the target system. +
The attribute is REQUIRED on each <directory/> element.
+The <file/> element has two attributes:
+-
+
- sid - The stream id that MUST be sent for the File Transfer SI. +
- name - The name of the file. The file should be saved to the same location in the target directory tree as the <directory/> hierarchy defines. +
Both attributes are REQUIRED on each <file/> element. The total number of <file> elements MUST equal the numfiles attribute sent in the <tree/> element.
+The stream-method that is accepted for a Tree Profile SI MUST be remembered and the subsequent File Transfer SIs MUST NOT provide a Feature Negotiation packet. The stream-method has already been chosen and should be used for all of the streams.
+Implementations of this profile MUST support &jep0095; and JEP-0096.
+Above is repeated for ft2, ft3, etc...
++ No interaction with &IANA; is required as a result of this JEP. +
++ The profile described in this JEP will be registered with ®ISTRAR; as a valid Stream + Initiation profile. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+&xmppcore; defines the Nodeprep profile of stringprep (&rfc3454;), which specifies that the following nine Unicode code points are disallowed in the node identifier portion of a Jabber Identifier (hereafter we refer to these as "the disallowed characters"):
+-
+
- All whitespace characters (which reduce to U+0020, also called SP) +
- U+0022 (") +
- U+0026 (&) +
- U+0027 (') +
- U+002F (/) +
- U+003A (:) +
- U+003C (<) +
- U+003E (>) +
- U+0040 (@) +
This restriction is an inconvenience for users who have one or more of the disallowed characters in their desired usernames, particularly in the case of the ' character, which is common in names like O'Hara and D'Artagnan. The restriction is a positive hardship if existing email addresses are mapped to JIDs, since some of the disallowed characters are allowed in the username portion of an email address (specifically, the characters & ' / as described in Sections 3.2.4 and 3.2.5 of &rfc2822;).
+If the & character had not been in the list of disallowed characters, then normal XML escaping conventions (as specified in &w3xml;) could have been used, with the result that D'Artagnan (for example) could have been rendered as D'artagnan [sic]. Since there are good reasons for each of the disallowed characters, another escaping mechanism is needed.
+It might have been desirable to use percent-encoding (e.g., %27 for the ' character) as specified in Section 2.1 of &rfc3986;. However, that approach was rejected since the % character is an often-used character in existing JIDs (e.g., to replace the @ character in gateway addresses) and the resulting ambiguity would have caused misdelivered or undeliverable messages. Therefore, a new mechanism is described herein to escape only the disallowed characters and only in the node identifier portion of JIDs.
+This JEP addresses the following requirements:
+-
+
- The escaping mechanism shall apply to the node identitier portion of a JID only, and MUST NOT be applied to domain identifiers or resource identifiers. +
- Escaped JIDs MUST conform to the definition of a Jabber ID as specified in RFC 3920, including the Nodeprep profile of stringprep. In particular this means that even after passing through Nodeprep, the JID MUST be valid, with the result that Unicode look-alikes like U+02BC (Modifier Letter Apostrophe) MUST NOT be used. +
- It MUST NOT be possible for clients to use this escaping mechanism to avoid the goal of stringprep; namely, that JIDs that look alike should have same character representation after being processed by stringprep. Therefore, this mechanism MUST NOT be applied to any characters other than the disallowed characters. +
- Existing JIDs that include portions of the escaping mechanism MUST continue to be valid. +
- The escaping mechanism MUST NOT break commonly deployed Jabber/XMPP software implementations such as servers, components, gateways, and clients. +
- The escaping mechanism SHOULD NOT place undue strain upon server implementations; implementations or deployments that do not need to unescape SHOULD be able to ignore the escaping mechanism. +
If an entity needs to discover whether another entity supports JID escaping, it MUST send a disco#info request to the other entity as specified in &jep0030;.
+If the queried entity supports JID escaping, it MUST return a jid\20escaping [sic] feature in its reply.
+This JEP specifies encoding each disallowed character as \hexhex -- where "hexhex" is the hexadecimal value of the Unicode code point in question, ignoring the leading "00" in the code point (e.g., 27 for the ' character, resulting in an encoding of \27). (Note: This escaping method is quite similar to that used for disallowed characters in LDAP distinguished names, as specified in &rfc2253;.) Full encoding and decoding transformations for all nine disallowed characters are provided in the following sections. In addition, encoding and decoding transformations are shown for the \ character in case it needs to be "double-escaped" when it occurs in a non-XMPP address as part of a string that corresponds to one of the other encoded characters.
+Note: All transformations are exactly as specified below. CASE IS SIGNIFICANT. Lowercase was selected since Nodeprep will case fold to lowercase for US-ASCII characters such as A, C, E, and F.
+The encoding transformations are defined in the following table. Typically, encoding is performed only by a client that is processing information provided by a human user in unescaped form, or by a gateway to some external system (e.g., email or LDAP) that needs to generate a JID.
+| Unescaped Character | Encoded Character |
|---|---|
| <space> | \20 |
| " | \22 |
| & | \26 |
| ' | \27 |
| / | \2f |
| : | \3a |
| < | \3c |
| > | \3e |
| @ | \40 |
| \ | \5c |
The decoding transformations are defined in the following table. Typically, decoding is performed only by a client that wants to display JIDs containing encoded characters to a human user, or by a gateway to some external system (e.g., email or LDAP) that needs to generate identifiers for foreign systems.
+| Encoded Character | Decoded Character |
|---|---|
| \20 | <space> |
| \22 | " |
| \26 | & |
| \27 | ' |
| \2f | / |
| \3a | : |
| \3c | < |
| \3e | > |
| \40 | @ |
| \5c | \ |
The following processing rules apply to native XMPP implementations:
+-
+
- A client SHOULD render an encoded character as its decoded equivalent when presenting it to a human user. +
- A server MAY decode an encoded character for communication with external systems (e.g. LDAP), but only after the Nodeprep profile of stringprep has been applied. +
- The decoding transformation MUST be NFKC-safe -- i.e., it MUST conform to Unicode normalization form KC (see Appendix B.3 of RFC 3454). +
- An entity MUST NOT include the unescaped or decoded version of an encoded character over the wire in any XML stanzas sent to another entity. +
- An entity MUST NOT use the unescaped or decoded version of an encoded character when comparing two JIDs. +
When transforming a non-XMPP address into an XMPP address, an implementation MUST adhere to the following process:
+-
+
- The original address MUST first be properly decoded (e.g., according to the rules in RFC 3986) before it is transformed into a JID. +
- Any instances of strings that correspond to encodings of the disallowed characters (e.g., the string "\27") in the original address MUST be "double-escaped" by converting the backslash character to the string "\5c". +
- The URI scheme component MUST be removed. +
- All disallowed characters in the original address MUST be properly encoded in the resulting JID (as described above). +
While the fourth step should be clear from the foregoing text and the third step is necessary since XMPP addresses are not URIs, the meaning of the first and second steps may not be obvious.
+Regarding step one, many non-XMPP messaging systems use URIs to identify addresses (examples include the mailto:, sip:, sips:, im:, pres:, and wv: URI schemes) or otherwise encode an identifier (e.g., an LDAP distinguished name). Before transforming an address or identifier into a JID, it MUST first be decoded according the rules specified for that type of address or identifier in order to ensure that the proper characters are transformed.
+Regarding step two, it is possible for some non-XMPP addresses to contain strings that correspond to JID-escaped characters (e.g., "\27"). Consider a Wireless Village address of <wv:\3and\2is\5@example.com> -- if that addresses were directly converted into into a JID, the resulting XMPP address would be \3and\2is\5@example.com, which could be construed as :nd\2is\5@example.com if JID escaping logic is applied. Therefore the leading \ character MUST be converted to the string "\5c" during the transformation, leading to a JID of \5c3and\2is\5@example.com (which would be presented to a human user as \3and\2is\5@example.com). Escaping of the backslash character before two hexhex characters MUST NOT be performed if the string is "\5c", only if the string corresponds to the encoded representation of one ofthe disallowed characters.
+In order to maintain as much backward compatibility as possible, partial escape sequences and escape sequences corresponding to characters not on the list of disallowed characters MUST be ignored.
+When a client attempts to communicate with another entity through a gateway, it needs to know which encoding mechanism to use. A client MUST assume that the gateway does not support the JID escaping mechanism unless it explicitly discovers support for the jid\20escaping [sic] feature via Service Discovery as shown above. If there any errors in the service discovery exchange or if support for JID escaping is not discovered, the client SHOULD proceed as follows:
+-
+
- If the gateway supports the 'jabber:iq:gateway' protocol (as specified in &jep0100;), use that protocol. +
- If the gateway does not support the 'jabber:iq:gateway' protocol, use customary escaping mechanisms (such as transformation of the @ character to the % character). +
In order to assist implementors, this section describes specific mappings between JIDs and addresses or identifiers used in the following standardized protocols:
+-
+
- Mailboxes and the mailto: URI scheme as used in email. +
- The sip: and sips: URI schemes as used in SIP/SIMPLE. +
- The im: and pres: URI schemes. +
- The wv: URI scheme as used in Wireless Village (IMPS). +
- LDAP distinguished names. +
The address format for an Internet mailbox is specified in RFC 2822. The identifier of interest in this context is the "addr-spec" address and more particularly the "dot-atom" rule specified in Section 3.2.4, i.e., the email address shorn of angle brackets, display names, comments, quoted strings, and the like. Because some deployments of XMPP messaging systems may want to re-use existing email addresses as JIDs, it is helpful to define how to transform an email address into a JID.
+In general, it is straightforward to transform an email address (i.e., a "dot-atom") into a JID, since traditional email addresses allow US-ASCII characters only rather than the nearly full range of Unicode code points allowed in a JID.
(Note: Because the backslash character is forbidden in the "dot-atom" construction, an email address should not contain a string that corresponds to one of the encoded characters specified in the Transformations section of this document; therefore, no such examples are shown; see below under IMPS Addresses.)
+An email address may also exist in the form of a mailto: URI as specified in &rfc2368;. Before transforming a mailto: URI into a JID, it MUST be URL-decoded and all headers MUST be removed, leaving a mailbox identifier, as shown in the following example.
+The foregoing examples showed how to transform an email address or mailto: URI into a JID. However, it also may be necessary to convert a JID into an email address or mailto: URI, as shown in the following example.
+As specified in &rfc3261;, a SIP address (i.e., a sip: or sips: URI) can be quite complex if URI parameters or headers are included. However, a basic SIP address (the combination of the optional "userinfo" and required "hostport" constructions) is essentially similar to an email address (e.g., the same characters & ' / allowed in an email address but disallowed in an XMPP node identifier are also allowed in a basic SIP address).
+The foregoing example showed how to transform a sip: or sips: URI into a JID. However, it also may be necessary to convert a JID into a sip: or sips: URI, as shown in the following example.
+The im: and pres: URI schemes are specified in &rfc3860; and &rfc3859; respectively. With the exception of headers, an im: or pres: URI is simply a mailbox (as specified in RFC 2822) prepended with the im: or pres: scheme. Thus a basic IM or PRES address (not including optional headers) is essentially similar to an email address (e.g., the same characters & ' / allowed in an email address but disallowed in an XMPP node identifier are also allowed in a basic IM or PRES address).
+The foregoing example showed how to transform an im: or pres: URI into a JID. However, it also may be necessary to convert a JID into an im: or pres: URI, as shown in the following example.
+The Instant Messaging and Presence Service (IMPS) protocol was originally defined by the Wireless Village consortium and is now maintained by the &OMA;. An IMPS address is formatted as a wv: URI, as specified in &wv-csp;. A basic address (not including a private resource) is of the form <wv:user-id@domain> and an address with a private resource is of the form <wv:user-id/resource@domain>.
+The "User-ID" construction is either a mobile phone number (beginning with "+1" for international numbers and a digit for national numbers) or an "Internet-Identity". An "Internet-Identity" may contain any US-ASCII character other than / @ + SP TAB and thus may include the following characters that are disallowed in the node identifier portion of a JID: " & ' / : < > (which characters MUST be escaped when transforming an IMPS address into a JID). However, some of those characters are also reserved in URI syntax (namely the & ' / characters) so those characters will be found in encoded form within a wv: URI.
+Unlike the foregoing address types, IMPS addresses are allowed to contain backslashes. This implies that it is possible for an IMPS address to contain a string that corresponds to one of the encoded character representations for code points that are disallowed in XMPP node identifiers. An example would be the IMPS address <wv:\3and\2is\5@example.com>, where the string "\3a" could be interpreted as the : character if that IMPS address is directly converted into a JID. Therefore, the leading \ character MUST be transformed to "\5c" in order to avoid possible ambiguity. Thus the transformed JID would be <\5c3and\2is\5@example.com>, which would be presented to a user as <\3and\2is\5@example.com>.
+If an IMPS address contains a private resource, a gateway between XMPP and IMPS should process the resource and append it to the end of the JID; however, such gateway behavior is out of scope for this JEP.
+The foregoing example showed how to transform a wv: URI into a JID. However, it also may be necessary to convert a JID into a wv: URI, as shown in the following example.
+Within the Lightweight Directory Access Protocol (see &rfc2251;), a "distinguished name" (DN) is a hierarchically-organized string representation that uniquely identifies a user, system, or organization. It is possible that some messaging systems use LDAP distinguished names to identify entities that can communicate using the system (e.g., this is reputed to be the case for certain releases of the Lotus Sametime system sold by IBM), and in any case it may be helpful to transform an LDAP distinguished name into an XMPP address for identification or addressing purposes.
+As previously mentioned, a UTF-8 string representation of LDAP distinguished names is specified in RFC 2253. This representation specifies that the characters , + " \ < > ; are to be escaped with the backslash character (e.g., the string "\," would be used to escape the , character) and that any other non-US-ASCII characters are to be escaped using a string of the form "\xx".
+The following example shows a distinguished name (and transformations thereof) for a person whose common name is "D'Artagnan Saint-André" and who is associated with an organization called "Example & Company, Inc." whose domain name is "example.com":
+This example assumes that the specified user is identified with a gateway running at st.example.com (note that the backslash escaping the , character in the organization name is removed during the transformation).
+Naturally, a more intelligent gateway could use the Domain Components to construct a more readable JID, such as <D\27Artagnan\20Saint-André@example.com>; however, such gateway behavior is out of scope for this JEP.
+The foregoing example showed how to transform an LDAP distinguished name into a JID. However, it also may be necessary to convert a JID into an LDAP distinguished name, as shown in the following example.
+An entity that performs JID escaping MUST NOT compare unescaped/decoded versions, otherwise messages and other information could be directed to an entity other than the intended recipient.
+An entity that transforms a non-XMPP address into a JID MUST follow the algorithm specified in the Address Transformation Algorithm section of this document, otherwise messages and other information could be directed to an entity other than the intended recipient.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes the jid\20escaping [sic] feature in its registry of service discovery features.
+This JEP defines an extension mechanism for capturing "extended presence" data about user moods.
+Information about user moods is provided by the user and propagated on the network by the user's client. The information is structured via a <mood/> element that is qualified by the 'http://jabber.org/protocol/mood' namespace. The mood itself is provided as the element name of a defined child element of the <mood/> element (e.g., <happy/>); one such child element is REQUIRED. The user MAY also specify a natural-language description of, or reason for, the mood in the <text/> child of the <mood/> element, which is OPTIONAL. Here is an example:
+
+ Yay, the mood JEP has been approved!
+
+ ]]>
+ In addition, an application MAY provide a more specific mood value as a properly-namespaced child of the defined element, which extension MUST be ignored if the receiving application does not understand the extended namespace. Here is an example:
+
+
+
+ Yay, the mood JEP has been approved!
+
+ ]]>
+ The <mood/> element SHOULD be communicated by means of &jep0060; but MAY be provided in a message as well. Because mood information is not pure presence information and can change independently of the user's availability, it SHOULD NOT be provided as an extension to &PRESENCE;.
+If the user wishes to publish his mood to all of those who are subscribed to his mood information, the user SHOULD use publish-subscribe.
+The mood is then delivered to all subscribers:
+As mentioned in JEP-0060, the stanza containing the event notification or payload MAY also include 'replyto' data (as specified by the &jep0033; protocol) to provide an explicit association between the published data and the user:
+A user MAY also provide a mood extension in a specific message, in order to lend a defined emotional tone to the message.
+The <mood/> element could even contain a URL reference structured according to the &jep0066; protocol:
+There exist various theories of human affect, mood, and emotion, including those promulgated by Frijda
The mood values defined in this taxonomy are as follows:
+-
+
- afraid +
- amazed +
- angry +
- annoyed +
- anxious +
- aroused +
- ashamed +
- bored +
- brave +
- calm +
- cold +
- confused +
- contented +
- cranky +
- curious +
- depressed +
- disappointed +
- disgusted +
- distracted +
- embarrassed +
- excited +
- flirtatious +
- frustrated +
- grumpy +
- guilty +
- happy +
- hot +
- humbled +
- humiliated +
- hungry +
- hurt +
- impressed +
- in_awe +
- in_love +
- indignant +
- interested +
- intoxicated +
- invincible +
- jealous +
- lonely +
- mean +
- moody +
- nervous +
- neutral +
- offended +
- playful +
- proud +
- relieved +
- remorseful +
- restless +
- sad +
- sarcastic +
- serious +
- shocked +
- shy +
- sick +
- sleepy +
- stressed +
- surprised +
- thirsty +
- worried +
The Wireless Village (now "IMPS") specifications for mobile instant messaging define a number of presence attributes, encapsulated in the "StatusMood" information element
-
+
- ANGRY +
- ANXIOUS +
- ASHAMED +
- BORED +
- EXCITED +
- HAPPY +
- IN_LOVE +
- INVINCIBLE +
- JEALOUS +
- SAD +
- SLEEPY +
The full range of moods defined herein is richer than that defined in Wireless Village; no mapping is provided by this specification for mood values that are not present in Wireless Village, and any such mapping is the responsibility of a gateway between the two systems.
+The XML character data values of the <value/> elements is not intended to be presented to a human user and thus there is no special reason to include an 'xml:lang' attribute unless the sender includes a <text/> element as well (as explained in &rfc2277;, "internationalization is for humans"). It is the responsibility of the receiving application to provide localized text strings associated with the XML character data values defined herein, or some other appropriate presentation (e.g., graphical images that represent the mood).
+Because user moods may be published to a large number of pubsub subscribers, users should take care in approving subscribers and in characterizing their current moods.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'http://jabber.org/protocol/mood' in its registry of protocol namespaces.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+This JEP defines an extension mechanism for capturing "extended presence" data about user activities, above and beyond availability as defined in &xmppim; (e.g., the 'away', 'extended away', and 'dnd' values of the <show/> child of the <presence/> stanza).
+Information about user activities is provided by the user and propagated on the network by the user's client. The information is structured by means of an <activity/> element that is qualified by the 'http://jabber.org/protocol/activity' namespace. The general activity is provided as the element name of a first-level child of the <activity/> element (e.g., <relaxing/>); one such general activity element is REQUIRED. The general activity element MAY contain a child element that specifies a more particular form of the general activity (e.g., <partying/>). The user MAY also specify a natural-language description of the activity in the OPTIONAL <text/> child of the <activity/> element. Here is an example:
+
+
+
+ My nurse's birthday!
+
+ ]]>
+ Instead of (but not in addition to) one of the specific activity elements defined herein, an application MAY include a properly-namespaced child element for the specific activity. Here is an example:
+
+
+
+
+ ]]>
+ Finally, one of the specific activity elements defined herein MAY itself contain a properly-namespaced child element that provides more detailed information about the specific activity. Here is an example:
+
+
+
+
+
+
+ ]]>
+ In accordance with &xmppcore;, the receiving application MUST ignore a specific activity element or detailed activity element if it does not understand the namespace that qualifies the element.
+The <activity/> element SHOULD be communicated by means of &jep0060;. Because activity information is not pure presence information and can change independently of the user's availability, it SHOULD NOT be provided as an extension to &PRESENCE;.
+The activity is then delivered to all subscribers:
+As mentioned in JEP-0060, the stanza containing the event notification or payload MAY also include 'replyto' data (as specified by the &jep0033; protocol) to provide an explicit association between the published data and the user:
+Each activity has a REQUIRED general category and an OPTIONAL specific instance. One can understand each specifier as '[user] is [activity]' (e.g., 'Juliet is partying'), where the relevant value is the most specific activity provided (e.g., specifically "partying" rather than generally "relaxing").
+The activity values defined in this taxonomy are as follows, where the first indentation level is the general category and the second indentation level is the specific instance. Note: The specific activity elements are RECOMMENDED as forms of the general activities shown below, but can be included under any general activity (e.g., "gardening" could be used as the specific activity under "relaxing" rather than "doing_chores").
+ +-
+
+
- doing_chores
+
-
+
- buying_groceries +
- cleaning +
- cooking +
- doing_maintenance +
- doing_the_dishes +
- doing_the_laundry +
- gardening +
- running_an_errand +
- walking_the_dog +
+
+ - drinking
+
-
+
- having_a_beer +
- having_coffee +
- having_tea +
+
+ - eating
+
-
+
- having_a_snack +
- having_breakfast +
- having_dinner +
- having_lunch +
+
+ - exercising
+
-
+
- cycling +
- hiking +
- jogging +
- playing_sports +
- running +
- skiing +
- swimming +
- working_out +
+
+ - grooming
+
-
+
- at_the_spa +
- brushing_teeth +
- getting_a_haircut +
- shaving +
- taking_a_bath +
- taking_a_shower +
+
+ - having_appointment + +
- inactive
+
-
+
- day_off +
- hanging_out +
- on_vacation +
- scheduled_holiday +
- sleeping +
+
+ - relaxing
+
-
+
- gaming +
- going_out +
- partying +
- reading +
- rehearsing +
- shopping +
- socializing +
- sunbathing +
- watching_tv +
- watching_a_movie +
+
+ - talking
+
-
+
- in_real_life +
- on_the_phone +
+
+ - traveling
+
-
+
- commuting +
- cycling +
- driving +
- in_a_car +
- on_a_bus +
- on_a_plane +
- on_a_train +
- on_a_trip +
- walking +
+
+ - working
+
-
+
- coding +
- in_a_meeting +
- studying +
- writing +
+
+
In addition, the specific activity element can be <other/> in order to handle activities not defined herein.
&rfc4480; defines several extensions to the &pidf; for so-called "rich presence". One such extension is the <activity/> element (see Section 4.2), which "describes what the presentity is currently doing". The following table shows a mapping from the defined RPID activity values to the Jabber values defined herein.
+| RPID <activity/> | +General activity element | +Specific activity element | +
|---|---|---|
| appointment | +having_appointment | +-- | +
| away | +||
| busy | +||
| holiday | +inactive | +scheduled_holiday | +
| in-transit | +traveling | +|
| meal | +eating | +|
| meeting | +working | +in_a_meeting | +
| on-the-phone | +talking | +on_the_phone | +
| performance | +-- | +-- | +
| permanent-absence | +||
| sleeping | +inactive | +sleeping | +
| steering | +traveling | +driving | +
| travel | +traveling | +on_a_trip | +
| vacation | +inactive | +on_vacation | +
The full range of activities defined herein is considerably richer than that defined in RPID; no mapping to RPID is provided by this specification for activity values that are not present in RPID, and any such mapping is the responsibility of a gateway between the two systems.
+The XML character data values of the <text/> element are intended for presentation to human users; therefore, if a <text/> element is included the sending application SHOULD also ensure that the <text/> element or the parent <activity/> element possesses an 'xml:lang' attribute with an appropriate value.
+Because user activities may be published to a large number of pubsub subscribers, users should take care in approving subscribers and in characterizing their current activities.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'http://jabber.org/protocol/activity' in its registry of protocol namespaces.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Popular electronic mail systems have long including features that allow users to set up automated messages that are returned to message senders when the user is not able to deal with the message immediately. This feature is commonly known as "vacation messages", because it is most commonly used when a user is unable to read their messages because they are on vacation.
+This document describes a similar system that allows Jabber users to setup vacation messages when they are away.
+The requirements for this document are fairly straightforward. A user MUST be able to:
+ +-
+
- Discover if their server supports vacation messages. +
- Retrieve their current vacation settings. +
- Set new vacation settings. +
- Remove vacation settings. +
Additionally, a server supporting vacation messages MUST respond to a message sent to a local user that has an active vacation message set by automatically sending that message to the sender.
+ +Before attempting to set or retrieve its current vacation settings, a user SHOULD first verify that their server supports vacation messages. To do this, the user makes a &jep0030; "#info" query to their server. If supported, the server includes a feature of "http://www.jabber.org/protocol/vacation" in the result.
+ +A user may request their current vacation settings by sending an IQ get to the local server like so:
+ +<start/> and <end/> define the times between which this vacation message is valid. These are in the format specified by &jep0082;.
+<message/> contains the text of the message that will be sent to a remote user that sends the user a message while they have active vacation settings.
+ +If the user has no stored vacation settings, the user will receive a result like the following:
+ +A user may set new vacation settings by sending a IQ to the local server like so:
+ +The meaning of each element is as outlined above. All elements are required.
+ +Additionally, the <start/> and <end/> elements MAY be empty (ie have no CDATA). When <start/> is empty, the server MUST take this to mean that the settings should take effect immediately. Similarly, when <end/> is empty, the server MUST take this to mean that the settings should never expire (unless they are explicitly removed).
+ +A user may remove all stored vacation settings by sending a IQ to the local server like so:
+ +A server implementing vacation messages MUST reply to the message using the text specified in the receiving users' vacation settings if the time that message arrived from the remote users falls within data range specified, but only if the received message is to be queued for later delivery.
+ +Implementing servers SHOULD (if local resource contraints allow) only send one automated response to a remote user for each local user that has active vacation settings. The memory of this action MUST be reset when the active settings have expired or when the user resets or removes them.
+None yet defined.
+This JEP requires no interaction with &IANA;.
+The 'http://jabber.org/protocol/vacation' namespace shall be registered with the ®ISTRAR; as a result of this JEP.
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Generic maps provide a way to extending the roster into a general display showing contacts (JIDs) together with further additional information. The further information is provided by the position in the map (and possibly by the dot type - e.g. shape or colour). In addition to showing people belonging to one roster group, it is possible to cluster people, use more detailed inset maps etc. each of these features providing a unique context.
+The motivations for this JEP are:
+-
+
- It is faster and easier to find people using a rich graphical view as compared to linear lists/trees +
- Maps provide easily understandable further information (context) about the contact +
- Maps show relations among JIDs and give better idea about their distribution in a given space (e.g. geographic region, company, campus) +
The requirements for the protocol are:
+-
+
- General definition of projection based on some attribute(s) of particular JIDs +
- Scaleability - in display size and size of transmitted data +
Generic Map is actually XML description of a graphical display, which can then be sent as a part of <message/> or <iq/> packet together with information about how to obtain attributes needed for its display (other resources required).
+Example 1 shows a typical message containing simple Generic Map.
+Each map consists of one or more layers. The main purpose of layers is to combine maps and views to deliver information suitable for a particular context, and to offer greater flexibility to the user in respect to customization.
+Layers can be defined either inline or by a reference to another map. Each layer has a specified position in the map, a scale and a priority. The maps defined inline contain also projection, underlying image and a list of entities lying inside it (i.e. typically JIDs or clusters of JIDs). The underlying images are sent out of band using the jabber:x:oob namespace or possibly defined in some other way (e.g. xml-based SVG).
+The map in Example 1 uses an implicit map projection assuming that attributes x and y are directly the co-ordinates of a particular entity (e.g. buddy1@jabber.org) in the image (ortho_0.gif) expressed in pixels.
+A similar map with coordinates specified using geographic latitude + longitude (possibly obtained using Geographic Location Information
+ As can be seen in Example 2, the projection can be specified using any parameters either explicitly set in the item tags or obtained for the particular JID from some other source (e.g. JUD or LDAP).
+Another important feature of this proposal is scaleability, which is achieved by grouping the individual JIDs with similar properties (e.g. 'near' locations) into clusters. Cluster is basically a list of constituting entities (JIDs) that share similar values of specified attribute (e.g. JIDs that are co-located in the same town/region/country). The size of clusters may depend on the resolution and intended scale of the map. In the map clusters can be displayed using a distinctive icon.
+
+ The following guidelines may assist the developers of a mapping plug-in in the Jabber clients.
+The expression in the <projection/> tag uses values of different attributes specified for the JID either directly in the <map/> tag or elsewhere in the environment.
+The image files (maps) are transferred as an extra extension of packet using the filename as a unique id.
+The attributes are either specified in the <map/> tag or known in the environment (e.g. presence), but they could be also provided by a subscribed service using Publish-Subscribe
The clustering of items can be specified directly in the map tag or done using a pixel resolution of the display available.
+No security features or concerns related to this proposal.
+No IANA interaction required.
+The Jabber Registrar
Note Well: This proposal has been retracted by the authors in favor of &jep0166;.
+The Session Description Protocol (SDP; see &rfc2327;) provides a mechanism for describing multimedia sessions that are advertised and negotiated over the Internet. The "Transport for Initiating and Negotiating Sessions" (TINS) specified herein describes how to use SDP to build a framework for media stream/session initiation and negotiation between entities that natively support XMPP (see &rfc3920;).
+
This JEP addresses the following requirements:
+-
+
- Enable an XMPP entity to negotiate an out-of-band multimedia session with another XMPP entity. +
- Enable an XMPP entity to negotiate an out-of-band multimedia session with a non-XMPP entity through a gateway. +
- Maximize interoperability with existing gateways and devices by using standard Internet protocols. +
TINS exchanges are completed by sending &MESSAGE; stanzas containing a child <tins/> element qualified by the 'http://jabber.org/protocol/tins' namespace.
+
-
+
INVITE -- Used to invite the target user to an out-of-band session. The content inside the <tins/> element MAY be SDP descriptions of the connection types offered. If a session is already established for this transaction, the new INVITE serves as a renegotiation of session parameters.
+ ACK -- Used by the initiator to tell the invitee that an out-of-band session has been established.
+ BYE -- Used by either side of the conversation to terminate the transaction. This message SHOULD cause all resources associated with this transaction to be freed, and any associated network connections to be terminated.
+
The SDP data itself is included as the XML character data of an <sdp/> child of the <tins/> element, qualifed by the 'urn:ietf:rfc:2327' namespace (this is consistent with &rfc2648;).
+
The request stanza MAY also include either or both of the following:
+-
+
- Header information or Internet metadata (such as that defined by RFC 3261) in the format specified by &jep0131;. +
- Multicast addresses as specified by &jep0033;. +
In reply to a request, the receiver MUST send zero or more replies, with the value of the 'method' attribute set to a value of "result" and the value of the 'code' attribute set to one of the valid SIP response codes as specified in Section 21 of RFC 3261.
+Before initiating a TINS negotiation, an XMPP entity SHOULD determine that the target entity supports the 'http://jabber.org/protocol/tins' namespace. Such discovery SHOULD occur by means of &jep0030;, either directly by querying the target entity or indirectly by means of &jep0115;. If the target entity is a non-XMPP entity that is contacted through a gateway, the gateway itself SHOULD reply to service discovery queries on behalf of the non-XMPP entity and SHOULD insert a client capabilities extension into the presence stanzas it generates on behalf of the non-XMPP entity.
+If an XMPP entity receives, or a gateway handles, a &MESSAGE; stanza containing a <tins/> element qualified by the 'http://jabber.org/protocol/tins' namespace but it does not understand the TINS protocol, it SHOULD either silently ignore it or return a &unavailable; error (see &jep0086; for error syntax).
+The following XMPP stanzas could be used to initiate a voice call. The 'from' addresses will usually be added by the XMPP server or relevant gateway, but are shown here for the sake of clarity. Note the inclusion of SHIM headers and extended addresses.
+More examples to follow.
+TINS is subject to the same security considerations as XMPP, particularly with regard to authentication and channel encryption; for details, refer to RFC 3920.
+This document does not describe how the media protocols (e.g. RTP) traverse firewalls and NATs.
+There is no general-purpose way to ensure that media protocol connections are associated with the in-band TINS conversation.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; shall include 'http://jabber.org/protocol/tins' in its registry of protocol namespaces.
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+ ]]>
+ NOTE WELL: The protocol defined herein has been folded into &jep0080;.
+This JEP defines an extension mechanism for capturing "extended presence" information about a user's current physical location. The information structures defined herein are intended to provide a format for describing a location or address that may change fairly frequently (e.g., one's location on a campus or in a large building) in situations where the user or application does not possess, or does not wish to communicate, detailed latitude/longitude data of the type defined in JEP-0080.
+Information about the user's location is provided by the user and propagated on the network by the user's client. The information is structured by means of an <physloc/> element that is qualified by the 'http://jabber.org/protocol/physloc' namespace. The location information itself is provided as the XML character data of the following children of the <physloc/> element:
+| Element | Description | Example |
|---|---|---|
| <country/> | The nation where the user is located | USA |
| <region/> | An administrative region of the nation, such as a state or province | New York |
| <locality/> | A locality within the administrative region, such as a town or city | New York City |
| <area/> | A named area such as a campus or neighborhood | Central Park |
| <street/> | A thoroughfare within the locality, or a crossing of two thoroughfares | 34th and Broadway |
| <building/> | A specific building on a street or in an area | The Empire State Building |
| <floor/> | A particular floor in a building | 102 |
| <room/> | A particular room in a building | Observatory |
| <postalcode/> | A code used for postal delivery | 10027 |
| <text/> | A catch-all element that captures any other information about the user's location | Northwest corner of the lobby |
The <physloc/> information SHOULD be communicated by means of &jep0060;. Because physical location information is not pure presence information and can change independently of the user's availability, it SHOULD NOT be provided as an extension to &PRESENCE;.
+The location information is then delivered to all subscribers:
+As mentioned in JEP-0060, the stanza containing the event notification or payload MAY also include 'replyto' data (as specified by the &jep0033; protocol) to provide an explicit association between the published data and the user:
+There are many XML data formats for physical location or address information. It is beyond the scope of this JEP to provide a mapping from the extension defined herein to every such format. However, it would be valuable to provide a mapping from the Jabber/XMPP format to the formats used in other presence or extended presence protocols. The two main protocols of interest are:
+-
+
The Wireless Village (now "IMPS") specifications for mobile instant messaging; these specifications define a presence attribute for address information as encapsulated in the IMPS "Address" element
The Wireless Village Initiative: Presence Attributes v1.1 (WV-029); for further information, visit <http://www.openmobilealliance.org/tech/affiliates/wv/wvindex.html>. .
+ The SIP-based SIMPLE specifications; in particular, the IETF's GEOPRIV Working Group has defined an extension to the IETF's &pidf; for location information, as specified in &rfc4119; (also known as "PIDF-LO").
+
The following table also maps the format defined herein to the vCard XML format specified in &jep0054;.
+| Jabber/XMPP | +Wireless Village / IMPS | +SIMPLE (PIDF-LO) | +vCard XML | +
|---|---|---|---|
| <country/> | +<Country/> | +<country/> | +<CTRY/>
+ |
+
| <region/> | +-- | +<A1/> and/or <A2/> | +<REGION/> | +
| <locality/> | +<City/> | +<A3/> | +<LOCALITY/> | +
| <area/> | +<NamedArea/> | +<A4/> and/or <A5/> | +-- | +
| <street/> | +<Street/>
+ |
+ <A6/>
+ |
+ <STREET/> | +
| <building/> | +<Building/> | +<LMK/> | +-- | +
| <floor/> | +-- | +<FLR/> | +-- | +
| <room/> | +-- | +-- | +-- | +
| <postalcode/> | +-- | +<PC/> | +<PCODE/> | +
| <text/> | +<FreeTextLocation/> | +<LOC/> | +<EXTADR/> | +
| -- | +<Accuracy/>
+ |
+ -- | +-- | +
| -- | +-- | +<NAM/>
+ |
+ -- | +
Because the character data contained in most <physloc/> child elements is intended to be readable by humans, the <physloc/> element SHOULD possess an 'xml:lang' attribute specifying the natural language of such character data.
+It is imperative to control access to location information, at least by default. Imagine that a stalker got unauthorized access to this information, with enough accuracy and timeliness to be able to find the target person. This scenario could lead to loss of life, so please take access control checks seriously. A user SHOULD take care in approving subscribers and in characterizing his or her current physical location.
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'http://jabber.org/protocol/physloc' in its registry of protocol namespaces.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0112: http://www.jabber.org/jeps/jep-0112.html
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+As explained in the now obsolete JEP-0010: Whiteboarding
The increasing penetration of pen-based devices, such as PDAs and tablet PCs, makes the need for a protocol that allows for sending freehand drawing information more urgent.
+Several attempts have been made to create a whiteboarding protocol for Jabber:
+-
+
- Collaborative Imaging (Whiteboarding via Streaming XPM)
XPM over Jabber (http://docs.jabber.org/draft-proto/html/sxpm.html) describes a protocol that sends partial bitmaps. This protocol is not suitable for freehand drawing and has not been implemented.
+ - Jabber Whiteboarding using SVG
Jabber Whiteboarding using SVG http://www.protocol7.com/jabber/whiteboard_proposal.txt describes a protocol that uses a subset of SVG. It refers to a missing DTD that describes the precise subset, but there is little doubt that that subset will be hard to implement. This protocol has not been implemented.
+ - Coccinella
Coccinella Project Information - JabberStudio http://www.jabberstudio.org/projects/coccinella/project/view.php is an open source implementation of a whiteboarding protocol. However, the protocol has not been documented and does not seem easy to implement. In fact it is mostly raw TCL, making an implementation of that protocol in a language other than TCL rather difficult.
+ - Tkabber
Tkabber Project Information - JabberStudio http://www.jabberstudio.org/projects/tkabber/project/view.php has a whiteboard plugin. The protocol has not been documented, but it uses a subset of SVG, similar to the one defined in this JEP.
+
The protocol has the following requirements in order of importance:
+-
+
- It should allow for freehand drawing because that will be its principal use on pen-based devices. +
- It should be extremely easy to implement to ensure its rapid adaptation. +
- It should be light-weight. +
- It should not require server modifications. +
The following are definitely not objectives of the protocol:
+-
+
- It need not be complete. Eventually an SVG-based protocol will be defined that will either replace or coexist with this protocol and that will satisfy all drawing needs. However, given the history of whiteboarding protocols, such a protocol is far away. +
- It need not be extensible. As a "Simple Whiteboarding protocol" it should not try to grow into a more complex protocol that would be more difficult to implement. +
There are three scenarios where whiteboarding can be used:
+-
+
- One person sends a single, completed, whiteboard to another person. +
- The more typical scenario is the one where one person starts a whiteboard session with another person and both persons collaborate in the drawing. Both sides may add paths, move them around or delete them. +
- Finally multiple people gathered in a conference room can use single whiteboard. +
Typically the user right-clicks on the destination contact and will select a "whiteboard message" option. The client will show a dialog where the user can create the drawing. It is up to the implementation to decide whether the user can include text in the message as well. Upon clicking a send button the client will close the dialog and send the following message:
+The path node is a simplified SVG path node that allows only 'M', 'm', 'L' and 'l' commands. 'M' ('m') command is a (relative) moveto command, 'L' ('l') is a (relative) lineto command. All four commands take one or more coordinate pairs (in pixels). 'M' sets the current point to the coordinate pair. 'm' adds the coordinate pair to the current point. 'L' draws a line from the current point to the point designated by the coordinate pair and sets the current point to the coordinate pair. 'l' draws a line from the current point to the sum of the currentpoint and the coordinate pair and adds the coordinate pair to the current point. The optional stroke attribute indicates the color of the path and defaults to black, the optional stroke-width indicates the width of the path in pixels and defaults to 1. The id attribute can be used for later reference to the path. If there is no id attribute, the path can not be referred to.
+The path in example 1, draws a red triangle with vertices (100,100), (300,100) and (200, 300)
+Other respresentations of the same path are 'M100.0,100.0L300.0,100.0,200.0,300.0,100.0,100.0', 'M100,100l200,0-100,200-100-200' and 'M100,100l200,0L200,300,100,100'. Note that in the second representation some commas can be left out because the sign indicates that a new coordinate is starting. This fact can be used to reduce data size as much as possible to avoid karma problems. A precise grammar of the "d" attribute is given below.
+A typical implementation will generate such paths by adding an 'M' command with the mouse coordinates on a mouse down event and adding an 'L' command with the mouse coordinates on every mouse move event as long as the mouse is down. It is up to the implementation to decide whether to complete and send the message on a mouse up event or to wait for a click on a send button.
+A more typical use case is where two clients share a whiteboard. Again the user will right click on the destination and will select a "whiteboard chat" option. The client will present a dialog where the user can create a drawing. Upon clicking a send button or releasing the mouse button, the client will send the following message:
+In this case the dialog will not close. At the destination client a similar dialog will pop up, allowing the user at the other end to add her own part of the drawing. The resulting message will look like this (line breaks provided for readability only):
+It is left as a mental exercise to the reader to imagine Laertes answer. Alternatively the reader could build this protocol into her favorite Jabber client, set a breakpoint, and paste the path above at the appropriate place.
+Alternatively Laertes could respond like:
+This would move the King's triangle 100 pixels to the left and top, to the upper left corner of the screen.
+If Laertes were bold enough he might even answer:
+This would remove King Claudius's triangle from the screen.
+The final use case is the one where multiple users, gathered in a conference room, share a single whiteboard. Messages will typically look like this:
+Usually when a user wants to send a message to a contact, the client will present her with a choice between sending a message or starting a chat. If the client implements the present protocol, the client can add the options of sending a whiteboard message and starting a whiteboard chat. Whether the client offers these options for an individual contact could be based on standard &jep0030; or &jep0011; techniques.
+Presentation of a path in case of a "Single whiteboard message" is rather obvious. The presentation of multiple-user whiteboards, either chat or conference, leaves more to the imagination of the implementor. The implementor could decide to use different colors for paths drawn by different users. The saturation of a path could decrease with age.
+One issue that will hinder all whiteboard protocol implementations is the karma problem. At least jabberd uses karma to make sure that a client does not send to much data to the server. This should help against denial-of-service attacks. When you use up all your karma, the server stops handling your messages for a while. This is a problem for whiteboards because it is much easier to send a lot of drawing data, than to send a lot of textual data. Usually combining paths, that is, sending paths when the user clicks on a send button instead of on mouse up, reduces data size because it reduces the overhead of the message element. Using the relative lineto command ('l') instead of the absolute lineto ('L') command will also reduce message size, because usually relative coordinates will only use one or two digits whereas absolute coordinates will typically use three. Finally implementations can reduce message size by not recording every mouse move event, e.g. by dropping mouse events whose locations would be accurately interpolated.
+The protocol does not provide explicit support for drawing text. The reason for this is that explicit support, eg. in the form of the SVG text element
The code snippet below shows the lines along which this could be done:
+The string 'Jabber' would be encoded as the path 'M24 59l0,16-1,3-1,1-2,1-2,0-2-1-1-1-1-3 0-2M43 66l0,14M43 69l-2-2-2-1-3,0-2,1-2,2-1,3 0,2 1,3 2,2 2,1 3,0 2-1 2-2M51 59l0,21M51 69l2-2 2-1 3,0 2,1 2,2 1,3 0,2-1,3-2,2-2,1-3,0-2-1-2-2M70 59l0,21M70 69l2-2 2-1 3,0 2,1 2,2 1,3 0,2-1,3-2,2-2,1-3,0-2-1-2-2M88 72l12,0 0-2-1-2-1-1-2-1-3,0-2,1-2,2-1,3 0,2 1,3 2,2 2,1 3,0 2-1 2-2M107 66l0,14M107 72l1-3 2-2 2-1 3,0', which is 357 characters long. That is no more than twice the size of a typical groupchat text message.
+Some of the protocols mentioned in the introduction, have a clear-screen command. However the benefits of such a command are doubtful. Of course clients can implement such a command locally. A client might even implement finer control such as the possibility of opening new windows that will receive new paths, or showing paths based on whether they were drawn in a selectable timespan. Synchronization of such complex actions between clients is clearly beyond the scope of this protocol. Of course when it is absolutely necessary to clear the screens of both sides in a whiteboard chat, that could be implemented by sending delete-commands for all paths.
+There are no security features or concerns related to this proposal.
+This JEP requires no interaction with the &IANA;.
+This JEP requires registration of the namespace "http://jabber.org/protocol/swb" by the ®ISTRAR;.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+
+
+ ]]>
+ The grammar of the "d" attribute below is a slight simplification of section 8.3.9 in
The present protocol satisfies its basic requirements: it allows for freehand drawing, it is easy to implement, light-weight and it requires no server changes.
+The author would like to thank Alexey Shchepin for helpful comments.
+The Jabber network has long included a wire protocol that enables trusted components to connect to Jabber servers. While this component protocol is minimal and will probably be superseded by a more comprehensive component protocol at some point, informational documentation of the existing protocol would be helpful for component and server developers. This JEP provides such documentation.
+Traditionally there have been two basic kinds of server-side components: "internal components" (which utilize the internal API of a server, in the past particularly the &jabberd; server) and "external components" (which communicate with a server over a wire protocol and therefore are not tied to any particular server implementation). The wire component protocol in use today enables an external component to connect to a server (with proper configuration and authentication) and to send and receive XML stanzas through the server. There are two connection methods: "accept" and "connect". When the "accept" method is used, the server waits for connections from components and accepts them when they are initiated by a component. When the "connect" method is used, the server initiates the connection to a component. The "accept" method is by far the most common method, but both are documented herein. (In the past, there has been one other connection method for external components: "execute". However, this method is obsolete and is not documented herein.)
+An external component is called "trusted" because it authenticates with a server using authentication credentials that include a shared secret. This secret is commonly specified in the configuration files used by the server and component, but could be provided at runtime on the command line or extracted from a database. An external component is commonly trusted to do things that clients cannot, such as write 'from' addresses for the server's domain(s). Some server may also allow components to send packets that are used by the server's internal protocol (e.g., <log/> and <xdb/> packets in the jabberd 1.x series); however, those internal protocols are out of scope for this JEP.
+The main difference between the jabber:component:* namespaces and the 'jabber:client' or 'jabber:server' namespace is authentication. External components do not use the older &jep0078; protocol (i.e., the 'jabber:iq:auth' namespace), nor do they (yet) use SASL authentication as defined in &xmppcore; (although a future component protocol would most likely use SASL). Instead, they use a special <handshake/> element whose XML character data specifies credentials for the component's session with the server. The protocol flow for stream negotiation and authentication using jabber:component:accept is as follows:
+Note: In the 'jabber:component:accept' namespace, the value of the 'to' address is the component name, not the server name;
If the server will not service the component name specified in the 'to' attribute of the stream header, it MUST return a stream error (e.g., <conflict/> or <host-unknown/>). If the server does not recognize or support the namespace specified in the stream header (e.g., it does not support streams qualified by the 'jabber:component:accept' namespace), it MUST return an <invalid-namespace/> stream error. For all errors related to the stream header, the server MUST follow the rules in Section 4.7.1 of XMPP Core by returning an opening stream tag, stream error element, and closing stream tag rather than merely a stream error element (refer to RFC 3920 for details).
+After receiving the stream header reply from the server, the component MUST send a <handshake/> element with appropriate contents.
The XML character data of the handshake element is computed according to the following algorithm:
+-
+
- Concatenate the Stream ID received from the server with the shared secret (if necessary, characters that map to predefined XML entities MUST be escaped according to the rules defined in section 4.6 of the XML specification, and any non-ASCII characters MUST be encoded according to the encoding of XML streams as specified in XMPP Core, i.e., UTF-8 as defined in &rfc3269;). +
- Hash the concatenated string according to the SHA1 algorithm, i.e., SHA1( concat (sid, password)). +
- Ensure that the hash output is in hexadecimal format, not binary or base64. +
- Convert the hash output to all lowercase characters. +
If the credentials supplied by the initiator are not valid, the receiver MUST close the stream and the underlying TCP connection, and SHOULD return a <not-authorized/> stream error.
+If the credentials are acceptable, the receiving application (in this case the server) MUST return an empty <handshake/> element.
+Once authenticated, the component can send stanzas through the server and receive stanzas from the server. All stanzas sent to the server MUST possess a 'from' attribute and a 'to' attribute, as in the 'jabber:server' namespace. The domain identifier portion of the JID contained in the 'from' attribute MUST match the hostname of the component. However, this is the only restriction on 'from' addresses, and the component MAY send stanzas from any user at its hostname.
+Given that an external component is trusted to write 'from' addresses for any user at the component's hostname, server administrators SHOULD make sure that they in fact do trust the component software.
+This JEP requires no interaction with the &IANA;
+The ®ISTRAR; includes 'jabber:component:accept' and 'jabber:component:connect' in its registry of protocol namespaces.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0114: http://www.jabber.org/jeps/jep-0114.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0114: http://www.jabber.org/jeps/jep-0114.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+ It is often desirable for a Jabber/XMPP application (commonly but not necessarily a client) to take different actions depending on the capabilities of another application from which it receives presence information. Examples include:
+-
+
- Showing a different set of icons depending on the capabilities of other clients. +
- Not sending &jep0071; content to plaintext clients such as cell phones. +
- Allowing the initiation of Voice over IP (VoIP) sessions only to clients that support VoIP. +
- Not showing a "Send a File" button if another user's client does not support &jep0096;. +
Recently, some existing Jabber clients have begun sending &jep0092; requests to each entity from which they receive presence. That solution is impractical on a larger scale, particularly for users or applications with large rosters. This JEP proposes a more robust and scalable solution: namely, a presence-based mechanism for exchanging information about entity capabilities.
This JEP makes several assumptions:
+-
+
- The type of client I am using is of interest to the people on my roster. +
- Clients for the people on my roster might want to make user interface decisions based on my capabilities. +
- Different instances of the same client (including version) have the same base capabilities. +
- Some clients will have bundles of functionality that can be enabled and disabled. +
- One instance of a given client may not know about all of the possible bundles of functionality that can be enabled and disabled (for example, plugins written to a client SDK). +
- Members of a community tend to cluster around a small set of clients. More specifically, multiple people in my roster use the same client, and they upgrade versions relatively slowly (commonly a few times a year, perhaps once a week at most, certainly not once a minute). +
- Some clients are running against servers without server-to-server connectivity enabled, and without access to the Internet via HTTP. +
- Conversations are possible between users who are not on each other's roster. +
- Client capabilities may change over the course of a session, due to features being enabled and disabled. +
The protocol defined herein addresses the following requirements:
+-
+
- Clients MUST be able to participate even if they support only &xmppcore;, &xmppim;, and &jep0030;. +
- Clients MUST be able to participate even if they are on networks without connectivity to other XMPP servers, services offering specialized XMPP extensions, or HTTP servers.
These first two requirements effectively eliminated &jep0060; as a possible implementation of entity capabilities.
+ - Clients MUST be able to retrieve information without querying each user. +
- Since presence is normally broadcasted to many users, the byte size of the proposed extension MUST be as small as possible. +
- It MUST be possible to write a &jep0045; implementation that passes the given information along. +
- It MUST be possible to publish a change in capabilities within a single session. +
- Server infrastructure above and beyond that defined in XMPP Core and XMPP IM MUST NOT be required for this approach to work, although additional server infrastructure MAY be used for optimization purposes. +
Each time a conformant client sends presence, it annotates that presence with an element that specifies the client type, the version of that client, and which feature bundles (if any) are currently enabled. Unless the server optimizations shown later are being used, the client MUST send this with every presence change (except for unavailable presence) to enable existing servers to remember the last presence for use in responding to probes. The client MUST send the 'node' and 'ver' attributes.
+In addition, the client MAY send an 'ext' attribute (short for "extensions") if it has one or more feature bundles to advertise. A feature bundle is any non-standard addition or extension to the core application, such as a client plugin. If more than one feature bundle is advertised, the value of the 'ext' attribute MUST be a space-separated list of bundle names.
+
The values of the 'node', 'ver', and 'ext' attributes MUST NOT contain the '#' character, since that character is used as a separator in the Discovering Capabilities use case.
+ +Once someone on my roster knows what client I am using, they need to be able to figure out what features are supported by that client. The client that received the annotated presence sends a disco#info request (as defined in JEP-0030: Service Discovery) to exactly one of the users that sent a particular combination of node and ver. If the requestor has received the same annotation from multiple JIDs, the requestor SHOULD pick a random JID from that list to which the requestor will send the disco#info request.
+ +The disco#info request is sent to a JID + node combination that consists of the chosen <user@host/resource> JID and a service discovery node that is constructed as follows: concatenate (1) the value of the caps 'node' attribute, (2) the "#" character, and (3) the version number specified in the caps 'ver' attribute.
+ +Subsequent requests MAY be made to determine the info for each extension. These requests MUST be sent to a random <user@host/resource> JID that sent a caps annotation that included a particular node/ext combination. The disco#info request shall be sent to a JID + node combination that consists of the chosen JID and a service discovery node that is constructed as follows: concatenate (1) the value of the caps 'node' attribute, (2) the "#" character, and (3) the extension name specified by one of the space-separated names in the caps 'ext' attribute. The requestor SHOULD try to use different JIDs for each of these requests, as well as for the first request.
+ +All of the responses to the disco#info queries SHOULD be cached. If a particular entity cannot store the responses, it SHOULD NOT make the requests. An entity SHOULD NOT make the service discovery requests unless the information is required for some local functionality. An entity MUST NOT ever make a request to another entity that has the same version of the same application as the requesting entity, except for extensions that are not supported by the requestor's installation (e.g., one "Exodus 0.9" client MUST NOT query another "Exodus 0.9" client unless the second client has advertised an extension or plugin that the first client does not have).
+If an application sends message to an entity from which it has not received presence, it MAY choose to append a capabilities annotation to only the first message sent to that entity within a particular conversation thread or "session". The application MUST NOT append a capabilities annotation to later messages unless its capabilities have changed (e.g., the value of the 'ext' has changed as described above) and MUST NOT send the annotation to entities from which it has received presence. Also, an application MUST NOT send the capabilities annotation to entities which are in a user's roster (or equivalent entity store, as in a gateway) with subscription='both' or subscription='to' (since presence would have been received from these entities if they were online).
+ +If the recipient responds to one of these annotated messages, the first message back in the other direction SHOULD be annotated with capabilities.
+Alternatively, unsubscribed entities MAY send directed presence to each other, for which the same rules apply as listed above for messages.
+A server that is managing an entity's session MAY choose to optimize traffic through the server. In this case, the server MAY strip off redundant capabilities annotations. Because of this, receivers of annotations MUST NOT expect an annotation on every presence packet they receive. If the server wants to perform this traffic optimization, it MUST ensure that the first presence each subscriber receives contains the annotation. The server MUST also ensure that any changes in the annotation (typically in the 'ext' attribute) are sent to all subscribers.
+ +A client MAY query the server using disco#info to determine if the server supports the 'http://jabber.org/protocol/caps' feature. If so, the server MUST perform the optimization delineated above, and the client MAY choose to only send the capabilities annotation on the first presence packet, as well as whenever its capabilities change.
+ +If capabilities information has not been received from another entity, an application MUST assume that the other entity does not support capabilities.
+No application-specific error codes are defined by this document. See JEP-0030: Service Discovery for a list of potential service discovery error codes.
+Use of the protocol specified in this JEP might make some client-specific forms of attack slightly easier, since the attacker could more easily determine the type of client being used. However, since most clients respond to jabber:iq:version requests without performing access control checks, there is no new vulnerability. Entities that wish to restrict access to capabilities information SHOULD use the privacy lists protocol defined in XMPP IM to define appropriate communications blocking (e.g., an entity MAY choose to allow IQ requests only from "trusted" entities, such as those with whom it has a subscription of "both").
+It is possible (though unlikely) for a bad actor or rogue application to poison other entities by providing incorrect information in response to disco#info requests. To guard against such poisoning, a requesting entity MAY send disco#info requests to multiple entities that match the same node/ver or node/ext combination and then compare the results to ensure consistency. The requesting entity SHOULD NOT send the same request to more than five entities and MUST ensure that the entities are truly different by not sending the same request to multiple entities for which the <user@host> portion matches.
+This JEP requires no interaction with &IANA;.
+Upon advancement of this JEP to a status of Draft, the ®ISTRAR; shall add 'http://jabber.org/protocol/caps' to its registries of protocol namespaces and service discovery features.
+If it is useful or interesting, the Registrar may also provide registration of the URIs to be used in the 'node' attribute, but since these URIs can be scoped according to well-defined existing rules, this is not necessary.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0115: http://www.jabber.org/jeps/jep-0115.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+ Harmonised session termination with the protocol added to JEP-0155; added XML schema; minor clarifications
Added Upgradability requirement; added expires field to offline options; updated in line with latest version of PEP; moved some content to new JEPs (0187, 0188 and 0189)
Modified protocol in line with SIGMA: added Identity Protection requirement, no pre-indication of acceptable keys, send multiple values of e with ESession request, offline options published via SPPS, added LZW compression
Added diagramatic synopses; Added match_resource field; replaced req_mac and kid fields with prev_hash; Alice specifies initial counter (doubles as nonce); many other improvements
Simplified XML normalization; added Synopsis and Efficiency requirement; defined signature formats
Extended termination procedure; added object encryption/signing requirement and special case; clarified expired MAC publishing; added Flexible Offline Message Retrieval to Open Issues.
Added flexibility requirement; added late signature of initial request; added termination MAC.
Added (offline) replay protection; required offline Created header; compression is NOT RECOMMENDED; added second set of offline options for subscribers; added JIDs to session key generation; unencrypted sessions; added secure option; sign whole data form; HMAC whole <encrypted/> element; added ESession termination; option to distribute public keys within session negotiation; added Integrity requirement; several clarifications
Restored status to Experimental; complete rewrite; new Introduction, Background, Requirements and Security Considerations; new OTR-inspired protocol; JEP-0155-based negotiation; counter mode encryption; more secure hashes; offline sessions; re-keying; mac publishing; preliminary key and options publishing protocol.
At the request of the JEP author, changed status to Retracted.
Initial version.
End-to-end encryption is a desirable feature for any communication technology. Ideally, such a technology would design encryption in from the beginning and would forbid unencrypted communications. Realistically, most communication technologies have not been designed in that manner, and Jabber/XMPP technologies are no exception. In particular, the original Jabber technologies developed in 1999 did not include end-to-end encryption by default. PGP-based encryption of message bodies and signing of presence information was added as an extension to the core protocols in the year 2000; this extension is documented in &jep0027;. When the core protocols were formalized within the Internet Standards Process by the IETF's XMPP Working Group in 2003, a different extension was defined using S/MIME-based signing and encryption of CPIM-formatted messages (see &rfc3862;) and PIDF-formatted presence information (see &rfc3863;); this extension is specified in &rfc3923;.
+For reasons described in &jep0188;, the foregoing proposals (and others not mentioned) have not been widely implemented and deployed. This is unfortunate, since an open communication protocol needs to enable end-to-end encryption in order to be seriously considered for deployment by a broad range of users.
+This proposal describes a different approach to end-to-end encryption for use by entities that communicate using XMPP. The requirements and the consequent cryptographic design that underpin this protocol are described in Cryptographic Design of Encrypted Sessions. The basic concept is that of an encrypted session which acts as a secure tunnel between two endpoints. Once the tunnel is established, the content of each one-to-one XML stanza exchanged between the endpoints will be encrypted and then transmitted within a "wrapper" stanza.
+This JEP introduces two characters to help the reader follow the necessary exchanges:
+-
+
- "Alice" is the name of the initiator of the ESession. Within the scope of this JEP, we stipulate that her fully-qualified JID is: <alice@example.org/pda>. +
- "Bob" is the name of the other participant in the ESession started by Alice. Within the scope of this JEP, his fully-qualified JID is: <bob@example.com/laptop>. +
- "Aunt Tillie" the archetypal typical user (i.e. non-technical, with only very limited knowledge of how to use a computer, and averse to performing any procedures that are not familiar). +
While Alice and Bob are introduced as "end users", they are simply meant to be examples of Jabber entities. Any directly addressable Jabber entity may participate in an ESession.
+Before attempting to engage in an ESession with Bob, Alice SHOULD discover whether he supports this protocol, using either &jep0030; or the presence-based profile of JEP-0030 specified in &jep0115;.
+The normal course of events is for Alice to authenticate with her server, retrieve her roster (see RFC 3921), send initial presence to her server, and then receive presence information from all the contacts in her roster. If the presence information she receives from some contacts does not include capabilities data (per JEP-0115), Alice SHOULD then send a service discovery information ("disco#info") request to each of those contacts (in accordance with JEP-0030). Such initial service discovery stanzas MUST NOT be considered part of encrypted communication sessions for the purposes of this JEP, since they perform a "bootstrapping" function that is a prerequisite to encrypted communications. The disco#info request sent from Alice to Bob might look as follows:
+If Bob sends a disco#info reply and he supports the protocol defined herein, then he MUST include a service discovery feature variable of "http://jabber.org/protocol/esession".
+The process for establishing a secure session over an insecure transport is essentially a negotiation of various ESession algorithms and other parameters, combined with a translation into XMPP syntax of the σ approach to key exchange (see Cryptographic Design of Encrypted Sessions).
+If Alice believes Bob may be online then she SHOULD use the protocol specified in &jep0155; and in this section to negotiate the ESession options and the keys.
+Note: If Alice believes Bob is offline then she SHOULD NOT use this negotiation protocol. However, she MAY use the protocol specified in Offline Encrypted Sessions to establish the ESession options and keys. Alternatively, she MAY send stanzas without encryption - in which case her client MUST make absolutely clear to her that the stanzas will not be protected and give her the option not to send the stanzas.
+Note: In any case, Alice MUST NOT initiate a new ESession with Bob if she already has one established with him.
+In addition to the "accept", "otr" and "secure" fields specified in Chat Session Negotiation, Alice MUST send to Bob each of the ESession options (see list below) that she is willing to use, in her order of preference (see Mandatory to Implement Technologies). Note: Alice SHOULD NOT include a "reason" field since Aunt Tillie may not be aware the ESession request is not encrypted.
+-
+
The list of Modular Exponential (MODP) group numbers (as specified in &rfc2409; or &rfc3526;) that MAY be used for Diffie-Hellman key exchange (valid group numbers include 1,2,3,4,5,14,15,16,17 and 18)
+ Symmetric block cipher algorithm names
+ Hash algorithm names
+ Signature algorithm names
+ Compression algorithm names
+ The list of stanza types that MAY be encrypted and decrypted
+ Whether or not the other entity MUST send the fingerprint of its public signature-verification key instead of the full key
If the entity already possesses one of the other entity's public keys then it is RECOMMENDED that only the fingerprint is requested from the other entity - since this saves bandwidth.
+ The different versions of this protocol that are supported
This version of this document describes version 1.0 of this protocol.
+ The minimum number of stanzas that MUST be exchanged before an entity MAY initiate a key re-exchange (1 - every stanza, 100 - every hundred stanzas). Note: This value MUST be less than &twosup32; (see Re-Keying Limits)
+
Each MODP group has at least two well known constants: a large prime number p, and a generator g for a subgroup of GF(p). For each MODP group that Alice specifies she MUST perform the following computations to calculate her Diffie-Hellman keys (where n is the number of bits per cipher block for the block cipher algorithm with the largest block size out of those she specified):
+-
+
Generate a secret random number x (where &twosup2n; < x < p - 1)
+ Calculate e = &gsupx; mod p
+
Alice MUST send all her calculated values of e to Bob (in the same order as the associated MODP groups are being sent). She MUST also specify randomly generated Base64 encoded (in accordance with Section 3 of &rfc3548;) value of &NsubA; (her ESession ID).
+If Bob does not support one or more of the options in each ESession field, then he SHOULD return a &feature; error (but he MAY return no error if, for example, he does not want to reveal his presence to Alice for whatever reason):
+Either Bob or Alice MAY attempt to initiate a new ESession after any error during the negotiation process. However, both MUST consider the previous negotiation to have failed and MUST discard any information learned through the previous negotiation.
+If Bob is unwilling to start an ESession, but he is ready to initiate a one-to-one chat session with Alice (see Chat Session Negotiation), then he SHOULD accept the Chat Session and terminate the ESession negotiation by not including a 'nonce' field in his response.
+If Bob supports one or more of each of Alice's ESession options and is willing to start an ESession with Alice, then he MUST select one of the options from each of the ESession fields he received from Alice including one hash algorithm ("HASH"), and one of the MODP groups and Alice's corresponding value of e (see &rfc3766; or RFC 3526 for recommendations regarding balancing the sizes of symmetric cipher blocks and Diffie-Hellman moduli).
+Each MODP group has at least two well known constants: a large prime number p, and a generator g for a subgroup of GF(p). Bob SHOULD return a &feature; error unless: 1 < e < p - 1
+Bob MUST then perform the following computations (where n is the number of bits per cipher block for the selected block cipher algorithm):
+-
+
Generate a random number &NsubB; (his ESession ID)
+ Generate an n-bit random number &CsubA; (the block cipher counter for stanzas sent from Alice to Bob)
+ Set &CBeCAx2n1; (where &CsubB; is the block counter for stanzas sent from Bob to Alice)
+ Generate a secret random number y (where &twosup2n; < y < p - 1)
+ Calculate d = &gsupy; mod p
+ Calculate K = HASH(&esupy; mod p) (the shared secret)
+
Bob MUST use the shared secret ("K") and the selected hash algorithm ("HASH") to generate two sets of three keys, one set for each direction of the ESession.
+For stanzas that Alice will send to Bob, the keys are calculated as:
+-
+
Encryption key &KCsubA; = HASH(K, 0)
+ Integrity key &KMsubA; = HASH(K, 2)
+
+ SIGMA key &KSsubA; = HASH(K, 4)
+
For stanzas that Bob will send to Alice the keys are calculated as:
+-
+
Encryption key &KCsubB; = HASH(K, 1)
+ Integrity key &KMsubB; = HASH(K, 3)
+ SIGMA key &KSsubB; = HASH(K, 5)
+
Once the sets of keys have been calculated the value of K MUST be securely destroyed.
+Note: As many bits of key data as are needed for each key MUST be taken from the least significant bits of the hash output. When negotiating a hash, entities MUST ensure that the hash output is no shorter than the required key data. For algorithms with variable-length keys the maximum length (up to the hash output length) SHOULD be used.
+Bob MUST perform the following steps before he can prove his identity to Alice while protecting it from third parties.
+-
+
Select &pubKeyB;, the public key Alice should use to authenticate his signature with the signature algorithm he selected ("SIGN").
+ Set &formB; to the Normalized content of the reponse data form he will send back to Alice (including his responses for all the fields he received from Alice).
+Bob MUST encapsulate the Base64 encoded values of &CsubA; and Alice's &NsubA; in two new 'counter' and 'nonce' fields and add them to &formB;. Note: The 'pk_hash' field specifies whether or not Alice MUST send the fingerprint of her public signature-verification key instead of her full key. Note: The value of the 'rekey_freq' field MUST be less than &twosup32; and greater than or equal to the value specified by Alice. Note: Bob MUST place his Base64 encoded values of &NsubB; and d in the 'my_nonce' and 'keys' fields. Bob MUST NOT return Alice's values of e.
+ Concatenate Alice's ESession ID, Bob's ESession ID, d, &pubKeyB; and &formB;, and calculate the HMAC (as defined in Section 2 of &rfc2104;) of the resulting byte string using the selected hash algorithm ("HASH") and the key &KSsubB;.
+&macB; = HMAC(HASH, &KSsubB;, {&NsubA;, &NsubB;, d, &pubKeyB;, &formB;})
+ Calculate &signB;, the signature of the HMAC result using his private signature key that corresponds to &pubKeyB;
+&signB; = SIGN(&signKeyB;, &macB;)
+ If the value of the 'pk_hash' field that Alice sent Bob was true then Bob SHOULD set &pubKeyB; to the key's fingerprint
+if (pk_hash) &pubKeyB; = HASH(&pubKeyB;)
+ Concatenate &pubKeyB; and &signB; and encrypt the resulting byte string with the agreed algorithm ("CIPHER") in counter mode (see &nistfips800-38a;), using the encryption key &KCsubB; and block counter &CsubB;. Note: &CsubB; MUST be incremented by 1 for each encrypted block or partial block (i.e. &CsubB; = (&CsubB; + 1) mod 2n, where n is the number of bits per cipher block for the agreed block cipher algorithm).
+&IDB; = CIPHER(&KCsubB;, &CsubB;, {&pubKeyB;, &signB;})
+ Calculate the HMAC of the encrypted identity (&IDB;) and the value of Bob's block cipher counter &CsubB; before the encryption above using the selected hash algorithm ("HASH") and the integrity key &KMsubB;.
+&MsubB; = HMAC(HASH, &KMsubB;, &CsubB;, &IDB;)
+
Bob responds to Alice by sending her &formB;.
+If Bob prefers the RECOMMENDED 3-message ESession negotiation, where Alice's identity is protected from active attacks instead of his own, then he should encapsulate the Base64 encoded values of &IDB; and &MsubB; in data form fields ('identity' and 'mac'), and append the new fields to &formB; before sending it to Alice.
+After Alice receives Bob's response, she MUST use the value of d and the ESession options specified in Bob's response to perform the following steps (where p and g are the constants associated with the selected MODP group, HASH is the selected hash algorithm, and n is the number of bits per cipher block for the agreed block cipher algorithm):
+-
+
Return a &feature; error to Bob if she is not prepared to support any of the ESession options specified by Bob (if any of the options were not included in her initial ESession request)
+ Return a &feature; error to Bob unless: 1 < d < p - 1
+ Set &CBeCAx2n1; (where &CsubB; is the block counter for stanzas sent from Bob to Alice)
+ Select her values of x and e that correspond to the selected MODP group (from all the values of x and e she calculated previously)
+ Calculate K = HASH(&dsupx; mod p) (the shared secret)
+ Generate the session keys (&KCsubA;, &KMsubA;, &KSsubA;, &KCsubB;, &KMsubB; and &KSsubB;) in the same way as Bob did (see Generating Session Keys)
+
If Bob included 'identity' and 'mac' fields in his response then Alice MUST also perform the following steps:
+-
+
Calculate the HMAC of the encrypted identity (&IDB;) and the value of Bob's block cipher counter using HASH and the integrity key &KMsubB;.
+&MsubB; = HMAC(HASH, &KMsubB;, &CsubB;, &IDB;)
+ Return a &feature; error to Bob unless the value of &MsubB; she calculated matches the one she received in the 'mac' field
+ Obtain &pubKeyB; and &signB; by decrypting &IDB; with the agreed symmetric block cipher algorithm ("DECIPHER") in counter mode, using the encryption key &KCsubB; and block counter &CsubB;. Note: &CsubB; MUST be incremented by 1 for each encrypted block or partial block (i.e. &CsubB; = (&CsubB; + 1) mod 2n, where n is the number of bits per cipher block for the agreed block cipher algorithm).
+{&pubKeyB;, &signB;} = DECIPHER(&KCsubB;, &CsubB;, &IDB;)
+ If the value of the 'pk_hash' field she sent to Bob in her ESession Request was true, then Alice SHOULD change the value of &pubKeyB; to be her copy of the public key whose HASH matches the value of &pubKeyB; that she received from Bob. Note: If she cannot find a copy of the public key then Alice MUST terminate the ESession. She MAY then request a new ESession with the 'pk_hash' field set to false.
+ Return a &feature; error to Bob unless she can confirm (or has previously confirmed) that &pubKeyB; really is Bob's public key, for examples, via secure out-of-band communication, or through a third-party authority (see Verifying Keys).
+ Set the value of &formB; to be the Normalized content of the form she received from Bob without any 'identity' or 'mac' fields.
+ Concatenate Alice's ESession ID, Bob's ESession ID, d, &pubKeyB; and &formB;, and calculate the HMAC of the resulting byte string using HASH and the key &KSsubB;.
+&macB; = HMAC(HASH, &KSsubB;, {&NsubA;, &NsubB;, d, &pubKeyB;, &formB;})
+ Return a &feature; error to Bob unless she can use &pubKeyB; with the selected signature verification algorithm ("VERIFY") to confirm that &signB; is the signature of the HMAC result (see Signature Verification).
+VERIFY(&signB;, &pubKeyB;, &macB;)
+
Alice MUST then prove her identity to Bob while protecting it from third parties. She MUST perform the steps equivalent to those Bob performed above (see Hiding Identity for a more detailed description). Alice's calculations are summarised below (pay attention to the order of &NsubB; and &NsubA; when calculating &macA;). Note: &formA; is the Normalized content of the ESession Request data form that she sent to Bob previously.
+&macA; = HMAC(HASH, &KSsubA;, {&NsubB;, &NsubA;, e, &pubKeyA;, &formA;})
+ &signA; = SIGN(&signKeyA;, &macA;)
+ if (pk_hash) &pubKeyA; = HASH(&pubKeyA;)
+ &IDA; = CIPHER(&KCsubA;, &CsubA;, {&pubKeyA;, &signA;})
+ &MsubA; = HMAC(HASH, &KMsubA;, &CsubA;, &IDA;)
+
+ Alice MUST send the Base64 encoded values of &NsubB;, &IDA; and &MsubA; to Bob. If Alice has already confirmed Bob's identity (i.e. if Bob included 'identity' and 'mac' fields in his response), then she MAY also send encrypted content (see Exchanging Stanzas) in the same stanza as the proof of her identity.
+If Alice also includes a 'terminate' field with its value set to "1" or "true" (see ESession Termination) within the form then the ESession is terminated immediately. Note: This special case, where a single stanza is encrypted and sent in isolation, is equivalent to object encryption (or object signing if no encryption is specified) and offers several significant advantages over non-session approaches - including perfect forward secrecy.
+After receiving Alice's identity Bob MUST verify it by performing steps equivalent to those described in the section Verifying Bob's Identity above. Some of Bob's calculations are summarised below (pay attention to the order of &NsubB; and &NsubA; when calculating &macA;). Note: &formA; is the Normalized content of the ESession Request data form (the first form) that Alice sent him. Note: If Bob sends an error to Alice then he SHOULD ignore any encrypted content he received in the stanza.
+&MsubA; = HMAC(HASH, &KMsubA;, &CsubA;, &IDA;)
+ {&pubKeyA;, &signA;} = DECIPHER(&KCsubA;, &CsubA;, &IDA;)
+ &macA; = HMAC(HASH, &KSsubA;, {&NsubB;, &NsubA;, e, &pubKeyA;, &formA;})
+ VERIFY(&signA;, &pubKeyA;, &macA;)
+ If Alice has already confirmed Bob's identity (i.e. if Bob included 'identity' and 'mac' fields in his response above), then the ESession negotiation is complete.
+Otherwise, one more step is necessary. Bob MUST send Alice the Base64 encoded values of &NsubA;, &IDB; and &MsubB; that he calculated previously (see Hiding Identity). Note: He MAY also send encrypted content (see Exchanging Stanzas) in the same stanza.
+After receiving Bob's identity Alice MUST verify it by performing steps described in the section Verifying Bob's Identity above. Note: If Alice sends an error to Bob then she SHOULD ignore any encrypted content she received in the stanza.
+Once ESession negotiation is complete, Alice and Bob MUST exchange only encrypted forms of the one-to-one stanza types they agreed upon (e.g., &MESSAGE; and &IQ; stanzas).
+Either Alice or Bob MAY send encrypted stanzas. Here we describe the process where Alice sends Bob an encrypted stanza. She MUST only encrypt the XML content that would normally be ignored by the intermediate servers. She MUST NOT encrypt stanza wrapper elements or Advanced Message Processing elements.
+Alice MUST perform the following steps to encrypt the XML content. Note: if there is no XML content to be encrypted (e.g. if this is an empty Re-Keying stanza), then &CsubA; MUST be incremented by 1 (see below), and only the last two steps (normalization and MAC calculation) should be performed.
+-
+
Serialize the XML content she wishes to send into an array of UTF-8 bytes, m.
Although counter mode encryption requires no padding, implementations MAY still disguise the length of m by appending a random number of white-space characters.
+ -
+
Compress m using the negotiated algorithm. If a compression algorithm other than 'none' was agreed, the compression context is typically initialized after key exchange and passed from one stanza to the next, with only a partial flush at the end of each stanza.
+If Bob were to receive a stanza out-of-order, then he would fail to decrypt the stanza and be forced to terminate the ESession. m_compressed = compress(m)+
+ -
+
Encrypt the data with the agreed algorithm in counter mode, using the encryption key &KCsubA;. Note: &CsubA; MUST be incremented by 1 for each encrypted block or partial block (i.e. &CsubA; = (&CsubA; + 1) mod 2n, where n is the number of bits per cipher block for the agreed block cipher algorithm). Note: if the block cipher algorithm 'none' was agreed (see Unencrypted ESessions) then encryption MUST NOT be performed and &CsubA; MUST be incremented by 1 (for replay protection).
+m_final = encrypt(&KCsubA;, &CsubA;, m_compressed)+
+ -
+
Alice MUST now create the Normalized XML content of the <encrypted/> XML element. If there is encrypted XML content, the XML MUST include the Base64 encoded value of m_final wrapped in a <data/> element. Note: the <encrypted/> element MAY also contain one <key/> element and one or more <old/> elements (see Re-Keying).
+m_content = '<data> ** Base64 encoded m_final ** </data>'+
+ -
+
The XML content and the value of Alice's block cipher counter &CsubA; before the data was encrypted, are now processed through the HMAC algorithm, along with the agreed hash algorithm ("HASH") and the integrity key &KMsubA;.
+a_mac = HMAC(HASH, &KMsubA;, m_content, &CsubA;)+
+
Before sending the stanza to Bob, Alice MUST wrap m_content and the Base64 encoded value of a_mac (wrapped in a <mac/> element) inside an <encrypted/> element and insert it into the stanza in place of the original content. There MUST NOT be more than one <encrypted/> element per stanza.
+When Bob receives the stanza from Alice, he extracts and Base64 decodes the values of m_final and a_mac from the content and performs the following steps.
+-
+
-
+
Remove the <mac/> element from the <encrypted/> element and Normalize the remaining XML content. Calculate the Message Authentication Code (MAC) for the content.
+b_mac = HMAC(HASH, &KMsubA;, m_content, &CsubA;)+
+ -
+
Verify that b_mac and a_mac match. If they are not identical, the content has been tampered with and Bob MUST terminate the ESession, he MAY send a ¬acceptable; error to Alice.
+If Bob were to receive a stanza out-of-order, then the MACs would not match because the values of &CsubA; would not be synchronized.
+ -
+
Decrypt m_final using the agreed algorithm, &KCsubA; and &CsubA;. Note: &CsubA; MUST be incremented by 1 for each decrypted block (see Encryption). Note: if the block cipher algorithm 'none' was agreed decryption MUST NOT be performed and &CsubA; MUST be incremented by 1.
+m_compressed = decrypt(&KCsubA;, &CsubA;, m_final)+
+ -
+
Decompress m_compressed using the negotiated algorithm (usually 'none').
+m = decompress(m_compressed)+
+ -
+
Replace the <encrypted/> element in the serialized XML stanza with m and feed the stanza into an XML parser. If the parser returns an XML format error then Bob MUST terminate the ESession, he MAY send a ¬acceptable; error to Alice.
+Bob MUST NOT send a stream error to his server since intermediate entities are not responsible for encoded content.
+
Once an attacker has discovered an encryption key it could be used to decrypt all stanzas within a session, including stanzas that were intercepted before the key was discovered. To reduce the window of vulnerability, both Alice and Bob SHOULD change their values of x and y and re-exchange the encryption key as regularly as possible. They MUST also destroy all copies of keys as soon as they are no longer needed.
+Note: Although most entities are capable of re-keying after each stanza, clients running in constrained runtime environments may require a few seconds to re-key. During ESession negotiation these clients MAY negotiate the minimum number of stanzas to be exchanged between re-keys at the cost of a larger window of vulnerability. Entities MUST NOT initiate key re-exchanges more frequently than the agreed limit.
+ +Either Alice or Bob MAY initiate a key re-exchange. Here we describe the process initiated by Alice. First she MUST calculate new values for the encryption parameters:
+-
+
Generate a secret random number x (where &twosup2n; < x < p - 1, where n is the number of bits per cipher block for the agreed block cipher algorithm)
+ Calculate e = &gsupx; mod p
+ Calculate K = &dsupx; mod p (the new shared secret)
+ Calculate &KCsubA;, &KMsubA;, &KCsubB;, &KMsubB; from K (see Generating Session Keys)
+
To avoid extra stanzas, the new value of e SHOULD be sent to Bob along with an encrypted stanza. Note: Alice MUST NOT use the new &KCsubA; and &KMsubA; to encrypt this stanza or to calculate the MAC. However, she MUST use them when sending subsequent stanzas.
+Note: There is no need for Alice to provide a signature because the calculation of the MAC includes the new value of e, see Exchanging Stanzas).
+Note: Bob may not receive the new key before he sends his next stanzas (they may cross in transit). So, before destroying her old values of &KCsubB; and &KMsubB;, Alice MUST wait until either she receives a stanza encrypted with the new key, or a reasonable time has passed (60 seconds should cover a network round-trip and calculations by a constrained client). Similarly she MUST wait before destroying her old value of x, in case Bob sends two stanzas before receiving Alice's new key (the first stanza might include a re-key).
+After Bob has received a stanza with a new value of e, has confirmed it is greater than one, and has decrypted the stanza with the old value of &KCsubA;, he MUST securely destroy all copies of &KCsubA; and &KCsubB; and perform the following calculations with the new value of e:
+-
+
Calculate K = &esupy; mod p
+ Calculate &KCsubA;, &KMsubA;, &KCsubB;, &KMsubB; from K (see Generating Session Keys)
+
He MUST use these new values to encrypt and decrypt all subsequent stanzas.
The next time Bob sends Alice a stanza he MUST specify the number of rekeys he has received from her since he sent her his last stanza. He does that by setting the 'rekeys' attribute of the <data/> element. Note: The default value of the 'rekeys' attribute is zero.
+When Alice receives the stanza from Bob she MUST use the 'rekeys' attribute to decide which of her values of &KCsubB; and &KMsubB; (or x) she should use to decrypt the stanza - otherwise she would not know if Bob received her rekey(s) before he sent the stanza. Once she is sure Bob has received her rekey(s) she MUST discard all her older values of &KCsubB;, &KMsubB; and x.
+Once the expired MAC keys have been published, anyone could create valid arbitrary stanzas with them. This prevents anyone being able to prove the authenticity of a transcript of the ESession in the future.
+Either entity MAY publish old values of &KMsubA; and/or &KMsubB; within any encrypted stanza as long as it knows that all the stanzas that MAY use the old values have been received and validated. Note: A 'man-in-the-middle' could delay the delivery of stanzas indefinitely. So, before Alice publishes &KMsubA; (and &KMsubB;), she MUST wait until she has both sent a re-key to Bob and received a stanza from Bob encrypted with her new key. (She MAY also publish &KMsubB; after she has received a re-key from Bob.)
+Entities SHOULD ignore any <old/> elements they receive.
+Either entity MAY terminate an ESession at any time. Entities MUST terminate all open ESessions before they go offline. To terminate an ESession Alice MUST send an encrypted stanza to Bob including within the encrypted XML of the <data/> element a chat negotiation form with a "terminate" field (as specified in the Termination section of Chat Session Negotiation). Note: She MAY publish old values of &KMsubA; and/or &KMsubB; within her termination stanza as long as she is sure all the stanzas that MAY use the old values have been received and validated (see Publishing Old MAC Values). She MUST then securely destroy all keys associated with the ESession.
+When Bob receives a termination stanza he MUST verify the MAC (to be sure he received all the stanzas Alice sent him during the ESession) and immediately send an encrypted termination acknowledgement form (as specified in the Termination section of Chat Session Negotiation) back to Alice. Note: He MAY publish any old values of &KMsubA; or &KMsubB; within the acknowledgement stanza. He MUST then securely destroy all keys associated with the ESession.
+When Alice receives the stanza she MUST verify the MAC to be sure she received all the stanzas Bob sent her during the ESession. Once an entity has sent a termination or termination acknowledgement stanza it MUST NOT send another stanza within the ESession.
+Before the signature or MAC of a block of XML is generated or verified, all character data between all elements MUST be removed and the XML MUST be converted to canonical form (see &w3canon;).
+All the XML this protocol requires to be signed or MACed is very simple, so in this case, canonicalization SHOULD only require the following changes:
+-
+
- Set attribute value delimiters to quotation marks (i.e. simply replace all single quotes in the serialized XML with double quotes) +
- Impose lexicographic order on the attributes of "field" elements (i.e. ensure "type" is before "var") +
Implementations MAY conceivably also need to make the following changes. Note: Empty elements and special characters SHOULD NOT appear in the signed or MACed XML specified in this protocol.
+-
+
- Ensure there are no character references +
- Convert empty elements to start-end tag pairs +
- Ensure there is no whitespace except for single spaces before attributes +
Before the signature or MAC of a block of XML is generated or verified, the agreed hash algorithm MUST be used to generate the hash of the normalized XML.
+m_hash = HASH(m_content)
+ The signature generation depends on the type of private key being used.
+signature_rsa = rsa_sign(rsa_private_key, m_hash, hashOID)
+ The multiprecision integer signature_rsa is the signature (see &rfc3447;).
+sig_dsa_r, sig_dsa_s = dsa_sign(dsa_private_key, m_hash)
+ The multiprecision integers sig_dsa_r and sig_dsa_s are the signature (see &nistfips186-2;).
+The signature formats are the same for all public key formats. All integers are stored in big-endian byte order.
+Base64 encoding of the signature_rsa multiprecision integer (without any header or length prefix).
+Base64 encoding of the following structure:
+-
+
- number of bytes in sig_dsa_r (2-byte integer) +
- sig_dsa_r +
- number of bytes in sig_dsa_s (2-byte integer) +
- sig_dsa_s +
The signature verification depends on the type of public key being used.
+The rsa_modulus and rsa_public_exponent multiprecision integers are extracted from the other entity's authenticated public key. The signature_rsa multiprecision integer is the signature received from the other entity.
+boolean = rsa_verify(signature_rsa, m_hash, hashOID, rsa_modulus, rsa_public_exponent)
+ The dsa_p, dsa_q, dsa_g and dsa_y multiprecision integers are extracted from the other entity's authenticated public key. The sig_dsa_r and sig_dsa_s multiprecision integers are the signature received from the other entity.
+boolean = dsa_verify(sig_dsa_r, sig_dsa_s, m_hash, dsa_p, dsa_q, dsa_g, dsa_y)
+ Weak pseudo-random number generators (PRNG) enable successful attacks. Implementors MUST use a cryptographically strong PRNG to generate all random numbers (see &rfc1750;).
+After a key exchange an entity MUST NOT exchange a total of &twosup32; encrypted blocks before it initiates a key re-exchange (see &rfc4344;). Note: This limitation also ensures the same key and counter values are never used to encrypt two different blocks using counter mode (thus preventing simple attacks).
+In order to reduce the Perfect Forward Secrecy window of vulnerability, after an extended period of activity, entities SHOULD either re-key or terminate the ESession.
+The trust system outlined in this document is based on Alice trusting that the public key presented by Bob is actually Bob's key (and vice versa). Determining this trust may be done in a variety of ways depending on the entities' support for different public key (certificate) formats, signing algorithms and signing authorities. For instance, if Bob publishes a PGP/GPG public key, Alice MAY verify that his key is signed by another key that she knows to be good. Or, if Bob provides an X.509 certificate, she MAY check that his key has been signed by a Certificate Authority that she trusts.
+When trust cannot be achieved automatically, methods that are not transparent to the users may be employed. For example, Bob could communicate the SHA-256 fingerprint of his public key to Alice via secure out-of-band communication (e.g. face-to-face). This would enable Alice to confirm that the public key she receives in-band is valid. Note however that very few people bother to verify fingerprints in this way. So this method is exceptionally vulnerable to 'man-in-the-middle' attacks. In order to reduce the window of vulnerability, an entity SHOULD remember the fingerprints of all user-validated public keys and alert the user in the future if ever the fingerprint(s) it stored for an entity do not match any of the received public keys.
+Alternatively Alice and Bob could agree a shared secret via secure out-of-band communication, Bob could then use it to create an HMAC of his public key that only Alice could verify.
+Note: If no keys are acceptable to Alice (because Alice has never verified any of the keys, and because either the keys are not signed, or Alice does not support the signature algorithms of the keys, or she cannot parse the certificate formats, or she does not recognise the authorities that signed the keys) then, although the ESession can still be encrypted, she cannot be sure she is communicating with Bob.
+The block cipher counters maintained implicitly by Alice and Bob (&CsubA; and &CsubB;) prevent stanzas being replayed within any ESession. They ensure that the MAC will be different for all stanzas, even if the HMAC key and the content of the stanza are identical.
+Alice and Bob MUST ensure that the value of e or d they provide when negotiating each online ESession is unique. This prevents complete online ESessions being replayed.
+Organisations with full disclosure policies may require entities to disable encryption to enable the logging of all messages on their server. Unencrypted ESessions meet all the Security Requirements except for Confidentiality. Unencrypted ESessions enable Alice to to confirm securely with Bob that both client-server connections are secure. i.e. that the value of the 'secure' option (as specified in Chat Session Negotiation) has not been tampered with.
+If either entity stores a (re-encrypted) transcript of an ESession for future consultation then the Perfect Forward Secrecy offered by this protocol is lost. If the negotiated value of the 'otr' Chat Session Negotiation field is 'true' the entities SHOULD NOT store any part of the ESession content (not even in encrypted form).
+Cryptography plays only a small part in an entity's security. Even if it implements this protocol perfectly it may still be vulnerable to other attacks. For examples, an implementation might store ESession keys on swap space or save private keys to a file in cleartext! Implementors MUST take very great care when developing applications with secure technologies.
+An implementation of ESession MUST support the Diffie-Hellman Key Agreement and HMAC algorithms. Note: The parameter names mentioned below are related to secure shell; see SSH Transport Layer Encryption Modes for block cipher algorithm details; see the &ianassh; for other names.
+An implementation of ESession MUST support at least the following block cipher algorithm:
+-
+
- aes128-ctr (see &nistfips197;) +
The block length of an block cipher algorithm's cipher SHOULD be at least 128 bits. An implementation of ESession MAY also support the following block cipher algorithms:
+-
+
- aes256-ctr +
- aes192-ctr +
- twofish256-ctr (see &twofish;) +
- twofish192-ctr +
- twofish128-ctr +
- serpent256-ctr (see &serpent;) +
- serpent192-ctr +
- serpent128-ctr +
- none (no encryption, only signing) +
An implementation of ESession MUST support at least the following signing algorithm:
+-
+
- rsa (see RFC 3447) +
An implementation of ESession SHOULD also support at least the following signing algorithm:
+-
+
- dsa (see Digital Signature Standard) +
An implementation of ESession MUST support the following public key formats:
+-
+
- ssh-rsa +
An implementation of ESession SHOULD also support at least the following public key formats:
+-
+
- ssh-dss +
- x509v3-sign-rsa (see &sshx509;) +
- x509v3-sign-dss +
- pgp-sign-rsa +
- pgp-sign-dss +
An implementation of ESession MAY also support the following public key formats:
+-
+
- spki-sign-rsa +
- spki-sign-dss +
An implementation of ESession MUST support the following hash algorithm:
+-
+
- sha256 (see &nistfips180-2;) +
An implementation of ESession SHOULD also support at least the following hash algorithm (sha1 and md5 are NOT RECOMMENDED):
+-
+
- whirlpool (see &whirlpool;) +
An implementation of ESession MUST support the following compression algorithm:
+-
+
- none (no compression, the output MUST be the same as the input) +
Support for other algorithms is NOT RECOMMENDED since compression partially defeats the Repudiability requirement of this JEP by making it more difficult for a third party (with some knowledge of the plaintext) to modify a transcript of an encrypted session in a meaningful way. However, encrypted content is pseudo-random and cannot be compressed, so, in those cases where bandwidth is severely constrained, an implementation of ESession MAY support the following algorithms to compress content before it is encrypted:
+-
+
- lzw (see &ecma151;) +
- zlib (see &rfc1950;) +
This JEP requires no interaction with &IANA;.
+Upon approval of this JEP, the ®ISTRAR; shall register the following namespaces:
+-
+
- http://jabber.org/protocol/esession +
- http://jabber.org/protocol/esession#init +
- http://jabber.org/protocol/esession#error +
&jep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace. The following fields shall be registered for use in both Encrypted Sessions and Chat Session Negotiation:
+
+ http://jabber.org/protocol/esession
+ JEP-0116
+ ESession negotiation forms
+
+ http://jabber.org/protocol/chatneg
+ JEP-0155
+ ...
+
+ ]]>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+-
+
- Standardise on the X.509 public key and signature formats? +
- What challenges exist to make the OTR Gaim Plugin use this protocol natively when talking to Jabber entities? Can these be mitigated by 'non-critical' protocol changes? +
- Would anything in this protocol (e.g., its dependency on in-order stanza delivery) prevent an XMPP entity using it to exchange encrypted messages and presence with a user of a non-XMPP messaging system, assuming that the gateway both supports this protocol and is compatible with a purpose-built security plugin on the other user's client (e.g. a Gaim plugin connects to the gateway via a non-XMPP network)? +
- Could use &jep0013; (FOMR) instead of AMP to prevent any offline ESessions Bob can't decrypt being delivered to him. (Each <item/> that corresponds to an ESession message would have to contain a <ESessionID/> child, to allow Bob to discover which of his stored values of y was used to encrypt the message.) +
-
+
- Ask the authors of AMP to explain how to achieve the match_resource functionality specified in JEP-0187. +
- Define names for X.509 SubjectPublicKeyInfo public key formats (different to X.509 certificates). This format must be used when keys are distributed within session negotiation. +
- Add non-repudiable signing option +
- Perhaps the JEP needs to specify more carefully how block counters are handled between messages, especially in the event of partial blocks? +
- Give examples of specific errors and discuss error scenarios throughout document (e.g., what should Bob do if he is not offline and he receives an offline key exchange stanza?). +
- Define an optional protocol that would allow Alice to store values of &NsubA; and x (and the PKIDs she trusts) 'securely' on her own server (before she goes offline). +
The &jep0073; introduced the concept of a "protocol suite". This document extends the basic support specified in JEP-0073 by specifying an Intermediate IM Protocol Suite.
+This document follows the same approach as JEP-0073. By design, the Basic IM Protocol Suite does not include more advanced instant messaging functionality; the present document fills the need for a protocol suite that addresses such functionality.
+A protocol is deemed worthy of inclusion in this protocol suite if:
+-
+
- It addresses common needs of instant messaging users that are addressed by virtually all other popular IM services or systems. +
- It is more advanced than basic IM and presence. +
- It has achieved a status of at least Draft within the Jabber Software Foundation's standards process (as defined in &jep0001;). +
We define the Intermediate IM Protocol Suite as follows:
+| Specification | +Requirement Level | +
|---|---|
| JEP-0073: Basic IM Protocol Suite | +REQUIRED | +
| &jep0045; | +REQUIRED | +
| &jep0071; | +REQUIRED | +
| &jep0096; | +REQUIRED | +
| &jep0115; | +REQUIRED | +
Note well that the foregoing protocols apply to clients only (i.e., they do not introduce new requirements for servers). In addition, these protocols have their own dependencies, which include the following JEPs (as well as various IETF RFCs and W3C specifications):
+-
+
- &jep0004; +
- &jep0020; +
- &jep0047; +
- &jep0065; +
- &jep0068; +
- &jep0082; +
- &jep0095; +
In addition, because the intermediate suite builds on the basic suite, by definition all protocols required by JEP-0073 are also required by the intermediate suite (refer to JEP-0073 for details).
+This JEP introduces no additional security considerations above and beyond those defined in the documents on which it depends.
+This JEP requires no interaction with &IANA;.
+No namespaces or parameters need to be registered with the ®ISTRAR; as a result of this JEP.
+This JEP defines a protocol for communicating information about the music to which a user is listening. Such information may be seen as a kind of "extended presence", and users may want to communicate such information to their contacts on the network as a fun add-on to traditional IM applications or to provide integration with common music-player applications.
+Information about tunes is provided by the user and propagated on the network by the user's client. The information container for tune data is a <tune/> element that is qualified by the 'http://jabber.org/protocol/tune' namespace. The tune information itself is provided as the XML character data of the following children of the <tune/> element:
+| Element | +Description | +Example | +Datatype | +
|---|---|---|---|
| artist | +The artist or performer of the song or piece | +Yes | +xs:string | +
| title | +The title of the song or piece | +Heart of the Sunrise | +xs:string | +
| source | +The collection (e.g., album) or other source (e.g., a band website that hosts streams or audio files) | +Yessongs | +xs:string | +
| track | +A unique identifier for the tune; e.g., the track number within a collection or the specific URI for the object (e.g., a stream or audio file) | +3 | +xs:string | +
| length | +The duration of the song or piece in seconds | +686 | +xs:unsignedShort | +
NOTE: The datatypes specified above are defined in &w3xmlschema2;.
+Tune information SHOULD be communicated and transported by means of the &jep0060; protocol. Because tune information is not pure presence information and can change independently of the user's availability, it SHOULD NOT be provided as an extension to &PRESENCE;.
+The tune information is then delivered to all subscribers:
+As mentioned in JEP-0060, the stanza containing the event notification or payload MAY also include 'replyto' data (as specified by the &jep0033; protocol) to provide an explicit association between the published data and the user:
+Naturally, further extensions could be included, e.g., using &jep0066; to specify a URL where one could buy the recording.
+In order to indicate that the user is no longer listening to any tunes, the user's client SHOULD send an empty <tune/> element, which can be considered a "stop command" for user tunes:
+To prevent a large number of updates when a user is skipping through tracks, an implementation may wait several seconds before publishing new tune information.
+If the length is unknown (e.g., the user is listening to a stream), the <length/> element SHOULD NOT be included.
+This protocol introduces no security considerations above and beyond those defined in Publish-Subscribe (JEP-0060).
+This JEP requires no interaction with &IANA;.
+The ®ISTRAR; includes 'http://jabber.org/protocol/tune' in its registry of protocol namespaces.
+
+
+
+
+
+
+ The protocol documented by this schema is defined in
+ JEP-0118: http://www.jabber.org/jeps/jep-0118.html
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Retracted: superseded by Personal Eventing via Pubsub (JEP-0163).
Updated to reflect Personal Eventing via Pubsub (JEP-0163).
Added avatar support to required protocols.
Further defined the pubsub/disco interaction.
Removed text on auto-subscribe functionality.
Added introduction and background; defined well-known service discovery node for extended presence information; described auto-subscribe functionality.
Status changed to Deferred.
Initial version.
Note: This document has been retracted since its functionality is handled by &jep0163;.
+A number of network services enable the exchange of information about an entity's availability for communications over the network. This information is usually called "presence". Examples include a person's availability to talk over a traditional or mobile telephony network, chat over an instant messaging (IM) network, or participate in a video conference. In this core sense, presence is a boolean, "on/off" indicator of network availability.
+Over time, this core notion of presence has been extended to include other information about the entity that either (1) changes quickly or (2) affects the entity's interest in or ability to engage in communications. Examples of such "extended presence" include a person's proximity to or interaction with a user agent (e.g., "away" or "do not disturb"), activity (e.g., "driving"), ambient environment (e.g., "noisy"), and mood (e.g., "grumpy"). Related information includes data about the person's available devices (e.g., "phone" or "IM"), current contact modes or address, and date/time ranges for availability. Because extended presence information can change quite often (e.g., several times in the course of a typical IM session), it is distinct from more stable information about the individual (such as is captured in a vCard or other user profile).
+This document describes a unified approach to the provision and communication of extended presence information using the Extensible Messaging and Presence Protocol (XMPP), in the form of a "protocol suite" that incorporates by reference a number of existing XMPP extensions.
+XMPP began life as a dedicated instant messaging and presence protocol within the Jabber community. The needs of this community were not advanced (simple IM and presence), and the presence model designed by that community mainly takes account of basic presence only (i.e., on/off availability on an IM network). Within this model (and using the terminology of &rfc2778;), the only watchers are those in the principal's contact list (in XMPP called a "roster"). In addition, authorization to receive basic presence broadcasts is handled by the principal through a combination of roster management and basic presence subscriptions as defined in &xmppim;. The presence service is tied to the principal's session with a server, and the server's internal session manager handles both presence and instant messaging functionality (although IM and presence can be separated in system configuration or "on the fly" via negative presence priorities).
+This basic presence model was not designed for the more advanced world of extended presence. While some existing IM clients publish extended presence information as XML extensions to the XMPP &PRESENCE; stanza, that model does not scale well, does not respect the bandwidth restrictions of many clients on the network, and does not provide for more granular control over information access (anyone who receives presence will also receive geolocation data and the like). However, there is a more advanced protocol that is specially designed to fully implement the publish-subscribe design pattern on top of XMPP, specified in JEP-0060: &jep0060;. The publish-subscribe protocol can be used to create a service that provides full control over each type of extended presence data, sending that data only to those specifically authorized to receive it and those who have an active interest in each extension. In particular, for extended presence related to IM users, we specify the use of the personal eventing subset of JEP-0060, as defined in JEP-0163.
+The provision and communication of extended presence information follows the classic publish-subscribe design pattern: an individual publishes information such as geographical location data, and the data is broadcasted to all subscribers who are authorized to receive that data. (Alternatively, the data can be published on behalf of the individual, such as by a mobile telephony service that has knowledge of the individual's geographical location and authorization to act as a publisher of that data.) In general, the relationship between the publisher and subscriber is mediated by a service that receives publication requests, broadcasts data to subscribers, and enables the individual to manage lists of entities that are authorized to publish or subscribe to the data. This model makes it possible to deploy highly flexible extended presence services within the context of XMPP.
+The following diagram provides a schematic representation of such a service.
+
+
+Mobile XMPP
+Telephony Principal Session
+Service | Manager
+ |__________ ________|_________ __________|
+ | | | | | | | |
+ |1| |2| |3| |4| |5| |6|
+ +-------------------------+
+ | |
+ | Extended Presence |
+ | Service |
+ | |
+ +-------------------------+
+ |1| |2| |3| |4| |5| |6|
+ |___| |_| | _______|_
+ | | || | |
+ Sub Sub Sub Sub Sub
+
+ In this example, there are six different extended presence nodes (these might be, for example, geographical location, avatar, activity, mood, network availability, etc.). The principal is authorized to publish to all six, a Mobile Telephony Service is also authorized to publish to Node 1 (e.g., geolocation), and an XMPP Session Manager is also authorized to publish to Node 6 (e.g., network availability). There are five subscribers: Subscriber 1 is authorized to receive data from Node 1 and Node 2, Subscriber 2 is authorized to Node 2 and Node 3, Subscriber 3 is authorized to receive data from Node 4 and Node 6, and Subscribers 4 and 5 are authorized to receive data from Node 6 only.
+This document follows the same approach as &jep0073;. By design, the Basic IM Protocol Suite does not include more advanced functionality related to "extended presence"; the present document fills the need for a protocol suite that addresses such functionality.
+A protocol is deemed worthy of inclusion in this protocol suite if:
+-
+
- It addresses "extended presence" data that is defined in other presence services or protocols (e.g., Wireless Village or SIMPLE), or that is felt to be needed within the Jabber/XMPP community. +
- It has achieved a status of at least Draft within the Jabber Software Foundation's standards process (as defined in &jep0001;). +
We define the Extended Presence Protocol Suite as follows:
+| Specification | +Requirement Level | +
|---|---|
| JEP-0073: Basic IM Protocol Suite | +REQUIRED (prerequisite) | +
| JEP-0163: Personal Eventing via Pubsub | +REQUIRED (prerequisite) | +
| &jep0080; | +REQUIRED | +
| &jep0112; | +REQUIRED | +
| &jep0108; | +REQUIRED | +
| &jep0107; | +REQUIRED | +
| &jep0084; | +REQUIRED * | +
* Note: The User Avatar specification (JEP-0084) has not yet advanced to a status of Draft within the JSF's standards process, and the Extended Presence Protocol Suite will not be submitted for approval until it does so.
+Discovery of extended presence pubsub nodes is expedited through the use of Personal Eventing via Pubsub (PEP), since in PEP services there is a one-to-one relationship between payload types and NodeIDs. The NodeIDs MUST be as follows:
+-
+
- Activity: http://jabber.org/protocol/activity +
- Avatar: http://jabber.org/protocol/avatar#metadata +
- Geolocation: http://jabber.org/protocol/geoloc +
- Mood: http://jabber.org/protocol/mood +
- Physical Location: http://jabber.org/protocol/physloc +
These nodes SHOULD have an access model of either "presence" or "roster".
+This document introduces no new security considerations above and beyond those defined in the documents on which it depends. Because publicly exposing some forms of extended presence information (e.g., geolocation information) may lead to unnecessary risks, care should be taken in setting the access model for the relevant pubsub nodes (minimally, an access model of "presence" to take advantage of the bidirectional authorization scheme inherent in XMPP presence subscriptions).
+This JEP requires no interaction with &IANA;.
+This JEP requires no interaction with the ®ISTRAR;.
+Many Jabber protocols need to define metadata about "things" on the Jabber network; such things are not limited to entities that are addressable as JIDs (e.g., users, servers, services, and chatrooms) nor even to things that are addressable as &jep0060; or &jep0030; nodes (e.g., &jep0050;), but may include anything that Jabber entities can communicate about, including files sent via Jabber file transfer protocols (e.g., &jep0066; and &jep0096;), information published via pubsub protocols (e.g., &jep0118;), and other Jabber phenomena. To date, Jabber protocols have used disparate, specialized formats for capturing such meta-information. This JEP provides a generic information format that can be included whenever a protocol needs to define metadata about something on the network.
+The format defined herein uses a simple "key-value" structure. Although this may seem contrary to the XML basis of Jabber technologies, there are at least two good reasons for pursuing this approach:
+-
+
Using namespaced XML elements would force implementations to maintain a record of all namespaces and to differentiate those that define actionable protocols (e.g., 'http://jabber.org/protocol/si') from those that define informational metadata formats (e.g., 'http://purl.org/dc/elements/1.1'); the only way to do this would be to maintain an internal list of all possible namespaces that might be encountered by an application on the network.
+ Not all metadata formats that the Jabber community may want to use exist in stable XML representations (e.g., this is true of the vCard format) or in representations for which namespaces exist. In addition, some metadata formats (e.g., &foaf;) exist only in &w3rdf;, whose syntax is represented in XML but whose semantics impose a more complex structure that requires a specialized (non-XML) parser. As long as a clear mapping can be defined between such metadata formats and Jabber infobits, consistent information representation and exchange can be preserved.
+
The "infobits" protocol defined herein provides a data format only. The container element is <info/>, which is qualified by the 'http://jabber.org/protocol/infobits' namespace. There is one allowable child of the <info/> element -- <bundle/> -- and one allowable child of the <bundle/> element -- <bit/>. In order to provide the relevant metadata, the <info/> element MAY contain an unbounded number of <bundle/> elements, each of which MAY contain an unbounded number of <bit/> elements.
+Each <bundle/> element MUST possess a 'type' attribute, whose value specifies the aspect of reality to which the enclosed bits apply (e.g., geographical location). A <bundle/> element MAY also possess a 'context' attribute, whose value provides further specifying information about the kind of entities described by this bundle (e.g., a home address as opposed to a work address).
+Each <bit/> element MUST possess a 'key' attribute, whose value specifies the name of the key (this MUST be an NMTOKEN as defined in &w3xml;). A <bit/> element MAY also possess a 'datatype' attribute, whose value specifies the datatype of the key (which SHOULD be a datatype specified in &w3xmlschema2; or in a registry of values maintained by the Jabber Registrar, such as those described in &jep0122;). The <bit/> element SHOULD contain XML character data that specifies the relevant value of the 'key'. A <bundle/> element MAY contain more than one <bit/> element with the same value for the 'key' attribute when necessary (e.g., two instances of 'weblog' if the person has multiple weblogs), but obviously SHOULD NOT do so if a collision would occur (e.g., two instances of 'lat' and 'lon' to define a geographical location).
+Note well: no keys are defined in this JEP. All such keys MUST be defined in separate specifications. Keys and associated values shown in this JEP are provided for explanatory purposes only.
+When an entity is queried via &jep0030; regarding the features it supports, it SHOULD include the 'http://jabber.org/protocol/infobits' namespace.
+This set of examples is borrowed from &jep0080;.
+This set of examples is borrowed from &jep0118;.
+Data provided via the infobits protocol MAY be world-readable. Access control considerations MUST be defined by any protocol that makes use of infobits.
+Info key names registered with the Jabber Registrar MUST be considered as identifiers, not English-language words. For purposes of internationalization, an identifier SHOULD be rendered as a word or phrase that is appropriate to the end user's preferred language.
+This JEP requires no interaction with &IANA;.
+Upon advancement of this proposal to a status of Draft, the ®ISTRAR; shall add the 'http://jabber.org/protocol/infobits' namespace to its registry of official namespaces.
+The Jabber Registrar shall maintain a registry of infobit keynames and associated information.
+All keynames MUST begin with a short prefix string (letters and numbers only), followed by the '.' character used as a separator, followed by the name of the key as determined by the particular specification or organization that is identified with the prefix. Arbitrary keynames SHOULD begin with a prefix consisting of the capital 'X' character.
+The Jabber Registrar shall at its discretion reserve certain keyname prefixes for use in specifying particular classes of information. One example is the prefix 'DC', which is reserved for use by infobits specified by the &DUBLINCORE; (for details, see &jep0121;). Furthermore, the Jabber Registrar shall reserve the "XMPP" prefix for infobits related to documents created by the &XMPPWG; or its successors, and shall reserve the upper-case versions of all protocol "shortnames" specified in Jabber Enhancement Proposals (e.g., a prefix of "MUC" for infobits related to &jep0045;).
+In order to prevent naming collisions, infobits that will be used in public protocols that may interoperate with other protocols on the network SHOULD be registered with the Jabber Registrar, and MUST be so registered if they are defined in Jabber Enhancement Proposals (however, registration of private keys is NOT REQUIRED). Registration with the Jabber Registrar shall be considered to entail reservation of that infobit on the network, and a registered bit MUST NOT be re-used by other protocols and applications for purposes other than those implied by the registry entry.
+In addition to the key name, the following data may be provided (but is not required) for each bit:
+-
+
- datatype -- provide only if well-defined; otherwise assume string +
- doc -- the public identifier (e.g., JEP number or RFC number) of the document in which the info name is defined +
- valid values -- a series of <value/> elements, encapsulated within a <values/> parent whose 'type' attribute is set to "exhaustive" (these are the only valid values) or "nonexhaustive" (these are some of the valid values, but this list is not exhaustive and other values may be provided) +
The registry format is as follows:
+
+ some datatype
+ some document identifier
+
+ first value
+ second value
+
+
+ ]]>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Before defining a new protocol for metadata, the primary author of this proposal investigated several promising technologies that could be used to meet the above requirements -- in particular, the Friend of a Friend (FOAF) vocabulary, which is a subset of the Resource Description Framework (RDF). Ultimately, the primary author concluded that, while FOAF and RDF have many merits, they are not ideal for use on the Jabber network. In particular:
+-
+
- Although RDF uses XML syntax, processing of RDF requires an RDF parser, not an XML parser. The benefits of using RDF were outweighed by the costs of requiring an RDF parser in every application that would use the metadata format. +
- By design, FOAF and RDF allow an entity to define information about any other entity; this gives rise to significant concerns about data integrity, which have not been solved (and perhaps even cannot be solved) within the context of an RDF application. +
- The processes for proposing, changing, and approving RDF-related namespaces are not well defined and are outside the control or influence of the Jabber community. +
Given these and other concerns, the primary author concluded that the best course would be to define an extensible XML protocol that can be processed using tools that are standard within existing Jabber/XMPP implementations, that allows only the entity itself to define metadata about itself, and that is under the control of the Jabber/XMPP community.
+&jep0120; defines a protocol for capturing granular information (or "infobits") about users, servers, services, rooms, nodes, commands, files, and other phenomena on the Jabber/XMPP network; however, that document defines the protocol only, not the infobits themselves. This JEP specifies how to encapsulate one sort of metadata in infobits: the common metadata elements defined by the &DUBLINCORE;. Note well that this JEP is decidedly not meant to provide an exhaustive catalog of possible infobits. Future registrations, whether in Jabber Enhancement Proposals or direct submissions to the ®ISTRAR;, will specify additional infobits.
+The Dublin Core Metadata Initiative defines a number of common elements and element refinements that can be used to specify metadata about entities (especially but not exclusively publications). The semantics of any Dublin Core term can be represented as a Jabber infobit, where the infobit keyname consists of the term name (not label) prepended by a 'DC' prefix and a '.' separator character. Thus "DC.creator" is a valid infobit name and can be used to describe, for example, an IM user's relationship to the URI identifying the user's homepage or weblog. Infobit keynames beginning with the 'DC' prefix are reserved for &dcmiterms; only (the canonical list of these terms is available from the Dublin Core Metadata Initiative and is included here only for explanatory purposes).
+The following example is borrowed from &jep0118;.
+The following is an example of metadata for a conference room.
+This JEP introduces no security considerations above and beyond those already defined in JEP-0120.
+This JEP requires no interaction with &IANA;.
+The following is a submission to the infobits registry called for by JEP-0120.
+
+
+&jep0004; ("x:data") provides a simple and interoperable way to request and present information for both applications and humans. However, the simple nature of "x:data" requires the form interpreter at times to guess as to exactly what type of information is being requested or provided. This JEP builds upon "x:data" to provide this additional validation.
+The requirements for this JEP are:
+-
+
- Backwards compatible with the existing "x:data" protocol. +
- Provide extended datatypes (such as dates, times, and numbers). +
- Allow for multiple validation methods. +
- Allow for user-defined datatypes. +
- Accommodate value ranges. +
- Accommodate regular expression matching. +
This JEP defines a new namespace, "http://jabber.org/protocols/xdata-validate". The root element for this namespace is <validate/>, and MUST be contained within a <field/> element (qualified by the 'jabber:x:data' namespace) for each Data Forms field that possesses additional validation information.
+The simplest usage is to provide a more-granular datatype for a <field/> element used in Data Forms. To provide this datatype information, a <validate/> element is included whose 'datatype' attribute specifies the data type of any <value/> contained within the <field/> element:
+The preceding example demonstrates a field that is expected to contain a date/time value.
+The 'datatype' attribute specifies the datatype. This attribute is OPTIONAL, and defaults to "xs:string". It MUST meet one of the following conditions:
+-
+
- Start with "xs:", and be one of the "built-in" datatypes defined in &w3xmlschema2; +
- Start with a prefix registered with the ®ISTRAR; +
- Start with "x:", and specify a user-defined datatype
While "x:" allows for ad-hoc definitions, its use is NOT RECOMMENDED.
+
In addition to datatypes, the validation method can also be provided. The method is specified via a child element. The validation methods defined in this JEP are:
+-
+
- <basic/> for validation only against the datatype itself +
- <open/> for open-ended validation against the datatype +
- <range/> for validation against a given min/max and the datatype +
- <regex/> for validation against a given regular expression and the datatype +
If no validation method is specified, form processors MUST assume <basic/> validation. The <validate/> element SHOULD include one of the above validation method elements, and MUST NOT include more than one.
+Any validation method applied to a field of type "list-multi", "list-single", or "text-multi" (other than <basic/>) MUST imply the same behavior as <open/>, with the additional constraints defined by that method.
+Building upon the earlier example, to indicate that the value(s) should simply match the field type and datatype constraints, the <validate/> element shall contain a <basic/> child element.
+Using <basic/> validation, the form interpreter MUST follow the validation rules of the datatype (if understood) and the field type.
+The <basic/> element MUST be empty (i.e., not contain any character data or child elements) and MUST NOT possess any attributes.
+For "list-single" or "list-multi", to indicate that the user may enter a custom value (matching the datatype constraints) or choose from the predefined values, the <validate/> element shall contain an <open/> child element:
+The <open/> validation method applies to "text-multi" differently; it hints that each value for a "text-multi" field shall be validated separately. This effectively turns "text-multi" fields into an open-ended "list-multi", with no options and all values automatically selected.
+The <open/> element MUST be empty (i.e., not contain any character data or child elements) and MUST NOT possess any attributes.
+To indicate that the value should fall within a certain range, the <validate/> element shall contain a <range/> child element:
+The 'min' and 'max' attributes of the <range/> element specify the minimum and maximum values allowed, respectively.
+The 'max' attribute specifies the maximum allowable value. This attribute is OPTIONAL. The value depends on the datatype in use.
+The 'min' attribute specifies the minimum allowable value. This attribute is OPTIONAL. The value depends on the datatype in use.
+The <range/> element SHOULD possess either a 'min' or 'max' attribute, and MAY possess both. If neither attribute is included, the processor MUST assume that there are no range constraints.
+The <range/> element MUST be empty (i.e., not contain any character data or child elements).
+To indicate that the value should be restricted to a regular expression, the <validate/> element shall contain a <regex/> child element:
+The XML character data of this element is the pattern to apply. The syntax of this content MUST be that defined for POSIX extended regular expressions
The <regex/> element MUST contain character data only (i.e., not contain any child elements) and MUST NOT possess any attributes.
+For "list-multi", validation can indicate (via the <list-range/> element) that a minimum and maximum number of options should be selected and/or entered. This selection range MAY be combined with the other methods to provide more flexibility.
+The <list-range/> element SHOULD be included only when the <field/> is of type "list-multi" and SHOULD be ignored otherwise.
+The 'max' attribute specifies the maximum allowable number of selected/entered values. This attribute is OPTIONAL. The value MUST be a positive integer.
+The 'min' attribute specifies the minimum allowable number of selected/entered values. This attribute is OPTIONAL. The value MUST be a positive integer.
+The <list-range/> element SHOULD possess either a 'min' or 'max' attribute, and MAY possess both. If neither attribute is included, the processor MUST assume that there are no selection constraints.
+At a minimum, implementations MUST support the following:
+-
+
- Datatype validation +
- The <basic/> validation method +
If an implementation does not understand the specified datatype, it MUST validate according to the default "xs:string" datatype. If an implementation does not understand the specified method, it MUST validate according to the <basic/> method.
+While all elements associated with this JEP MUST be qualified by the 'http://jabber.org/protocol/xdata-validate' namespace, explicitly declaring the default namespace for each instance can be overly verbose. However, Jabber/XMPP implementations have historically been very lax regarding namespacing, thus requiring some careful use of prefixes.
+The use of namespace prefixes is RECOMMENDED for large forms, to reduce the data size. To maintain the highest level of compatibility, implementations sending the form using prefixes SHOULD use the namespace prefix "xdv", and SHOULD declare the namespace prefix mapping in the ancestor <x xmlns='jabber:x:data'/> element:
+This JEP relies on the internationalization/localization mechanisms provided by &xmppcore;. As much as possible, all datatype formats MUST be locale-independent.
+Form processors MUST NOT assume that a form with validation has actually been validated when submitted. There is no realistic expectation that form interpreters honor validation.
+While this JEP is compatible with the existing "x:data" definition, form providers SHOULD first determine support for it, using either &jep0115; if presence-aware or &jep0030;. This is especially important for limited-connection and/or limited-capabilities devices, such as cell phones.
+Although primarily intended for validating form submission, validation MAY have an impact on display, and MAY be applied to data forms that are not submitted (e.g. 'result' type forms). The following table outlines which field types a particular validation method is or is not appropriate for, and how a display SHOULD interpret the validation methods if considered
| Validation Method | +SHOULD be Allowed | +SHOULD NOT be Allowed | +Display Suggestions | +
|---|---|---|---|
| basic | +
|
+
|
+ Display the datatype appropriate to the locale | +
| open | +
|
+
|
+ Display the datatype appropriate to the locale. For "text-multi" treat each value as a discrete entry (e.g. a user-entered list). For "list-multi" or "list-single", allow user to add/remove entries to select. | +
| range | +
|
+
|
+ Display the datatype appropriate to the locale. For "text-single", allow user to increment/decrement through possible values. For "text-multi" treat each value as a discrete entry (e.g. a user-entered list). For "list-multi" or "list-single", allow user to add/remove entries to select. | +
| regex | +
|
+
|
+ Display the datatype appropriate to the locale. If possible, display a valid example. For "text-multi" treat each value as a discrete entry (e.g. a user-entered list). For "list-multi" or "list-single", allow user to add/remove entries to select. | +
The <range/> validation method MUST be used only with datatypes that have finite quantities. Within the standard datatype set, it MUST NOT be used with "xs:string".
+This JEP introduces no security concerns above and beyond those specified in JEP-0004: Data Forms.
+This JEP requires no interaction with &IANA;.
+The Jabber Registrar includes 'http://jabber.org/protocol/xdata-validate' in its registry of protocol namespaces.
+The Jabber Registrar maintains a registry of datatype prefixes used in the context of Data Forms Validation (see http://www.jabber.org/registrar/xdv-prefixes.html), where each prefix denotes a group of related datatypes.
+
+ the prefix token (e.g., "xs")
+ a natural-language description of the datatype family
+ the document in which datatype family is specified
+
+ ]]>
+ The registrant may register more than one prefix at a time, each contained in a separate <datatype-prefix/> element.
+As part of this JEP, the following datatype prefixes shall be registered:
+
+ x
+ An ad-hoc datatype
+ JEP-0122
+
+
+ xs
+ A "standard" datatype as defined in XML Schema Part 2
+ XML Schema Part 2
+
+ ]]>
+ The Jabber Registrar maintains a registry of datatypes used in the context of Data Forms Validation (see http://www.jabber.org/registrar/xdv-datatypes.html), where each datatype name includes the relevant prefix (e.g., "xs:anyURI").
+
+ the full datatype name (e.g., "xs:string")
+ a natural-language description of the datatype
+ the validation methods that may apply to the datatype
+ the minimum value for the datatype (if any)
+ the maximum value for the datatype (if any)
+
+ ]]>
+ The registrant may register more than one datatype at a time, each contained in a separate <datatype/> element.
+The following submission contains the built-in datatypes defined in XML Schema Part 2 that are deemed mostly like to be useful in the context of the Data Forms protocol; additional datatypes defined therein, as well as other datatypes not defined in XML Schema Part 2, may be registered via separate submissions in the future.
+
+ xs:anyURI
+ a Uniform Resource Identifier Reference (URI)
+ basic regex
+ N/A
+ N/A
+
+
+ xs:byte
+ an integer with the specified min/max
+ basic range
+ -128
+ 127
+
+
+ xs:date
+ a calendar date
+ basic range regex
+ N/A
+ N/A
+
+
+ xs:dateTime
+ a specific instant of time
+ basic range regex
+ N/A
+ N/A
+
+
+ xs:decimal
+ an arbitrary-precision decimal number
+ basic range
+ none
+ none
+
+
+ xs:double
+ an IEEE double-precision 64-bit floating point type
+ basic range
+ none
+ none
+
+
+ xs:int
+ an integer with the specified min/max
+ basic range
+ -2147483648
+ 2147483647
+
+
+ xs:integer
+ a decimal number with no fraction digits
+ basic range
+ none
+ none
+
+
+ xs:language
+ a language identifier as defined by RFC 1766
+ basic regex
+ N/A
+ N/A
+
+
+ xs:long
+ an integer with the specified min/max
+ basic range
+ -9223372036854775808
+ 9223372036854775807
+
+
+ xs:short
+ an integer with the specified min/max
+ basic range
+ -32768
+ 32767
+
+
+ xs:string
+ a character strings in XML
+ basic regex
+ N/A
+ N/A
+
+
+ xs:time
+ an instant of time that recurs every day
+ basic range regex
+ N/A
+ N/A
+
+ ]]>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+Traditionally, the only mechanism for communicating detailed information about entities on the Jabber network has been an XML version of the vCard format for electronic business cards (see &jep0054;). Unfortunately, the vCard format has several major drawbacks:
+-
+
- It is mainly limited to data about persons (although it has been used on the Jabber network to describe things like servers). +
- The format contains relatively few data fields. +
- The format is not extensible. +
- As implemented, the data is not searchable. +
- As implemented, the data cannot be filtered depending on the identity of the requestor. +
It is becoming increasingly important to define a robust, extensible format for describing entities on the Jabber network. Such a format should be:
+-
+
- Applicable not just to people but to any entity on the network, including but not limited to servers, components, bots, &jep0045; rooms, &jep0060; nodes, and in general anything that can be addressed as a Jabber ID (as defined in &xmppcore;). +
- Usable in encapsulating any information about the entity itself (name, address, description, title, etc.). +
- Extensible enough to handle any metadata that may be needed for current and future applications (including, at a minimum, everything that can be defined in vCard); it must be possible to use it for public protocols defined by the IETF or Jabber Software Foundation as well as for custom or private protocols. +
- Well-defined enough, through datatyping and public registries where applicable, to enable robust searching and filtering based on defined data fields and their values. +
Information about entities is provided using the &jep0120; protocol and registered infobit keynames (mainly those specified in &jep0125; although entity metadata is by no means limited to vCard information and could include infobits such as those specified in &jep0121;). The metadata is discovered by interacting with a common &jep0030; node named "metadata". The queried entity replies with a service discovery result containing any infobits that the entity wishes to reveal about itself to the requesting entity. This information is always metadata about the entity itself, not any other entities or any relationships that the entity may have to other entities.
+Support for entity metadata is discovered by means of Service Discovery. If the queried entity provides metadata about itself, it SHOULD advertise that fact by listing an item named "metadata" in response to a disco#items query.
+The entity returns its associated items:
+In order to request the advertised metadata, the requesting entity sends a disco#info request to the 'metadata' node of the JID communicated in the previous result.
+The entity returns its metadata to the requestor.
+One of the primary motivations behind this proposal is to enable the construction of useful directory services on the Jabber network. Examples of such services include but are not limited to:
+-
+
- robust user directories +
- directories of groupchat rooms +
- directories of pubsub nodes +
- server directories +
Although such directories will be a valuable addition to the network, it is imperative to understand that the canonical source for metadata about an entity is the entity itself. Mechanisms for keeping directories synchronized with entities are outside the scope of this JEP, and in any case a directory may not be privy to all information about an entity (since in general a user should publish to a directory only the information that he or she deems world-readable).
+Directories SHOULD require registration using &jep0077;. Before registering with a directory, an entity SHOULD adjust its access controls or privacy rules accordingly, including appropriate definition of classes and addition of the directory server's JID to the relevant privacy rules. Upon accepting registration from an entity, a directory SHOULD immediately send a metadata request to the registering entity. Synchronization of metadata is a matter for the directory implementation to determine, and perhaps negotiate with the registering entity; all such synchronization and negotiation is out of scope for this JEP.
+Metadata MAY be world-readable. Entities MUST take care to ensure that they exercise proper control over access to such information. Users of IM clients SHOULD be warned that their data may be world-readable and be given the option to not publish such information or control it via appropriate mechanisms (such as privacy rules).
+This JEP requires no interaction with &IANA;.
+Upon advancement of this proposal to a status of Draft, the ®ISTRAR; shall add the 'metadata' node to its registry of common Service Discovery nodes.
+&xmppcore; defines XML streams bound to TCP (see &rfc0793;) as the standard transport layer for Jabber/XMPP communications. However, the binding of XMPP to TCP is not always feasible because of client runtime environment and/or network constraints. This JEP describes the usage of the Hypertext Transfer Protocol (HTTP, see &rfc2068; and &rfc1945;) as an alternative transport binding that supports such constrained environments, normally via deployment of a specialized server-side connection manager that communicates with clients via HTTP rather than TCP.
+Before the authors pursued publication of this JEP, other approaches were explored. One possible approach might have been to apply state to a series of HTTP transactions via HTTP "cookies" as specified in &rfc2965;. However, there are several significant computing platforms which provide only limited access to underlying HTTP requests/responses; worse, some platforms hide or remove cookie-related headers. Therefore the cookie approach was rejected.
+Another approach might have been to modify or extend &jep0025;. This informational protocol has been used by Jabber clients without runtime constraints to access XMPP servers from behind firewalls. Unfortunately, the method defined in JEP-0025 also depends on cookies, does not meet most of the requirements described below, and cannot be extended without breaking all existing implementations.
+Therefore, this JEP specifies a new way of transporting XMPP via HTTP. All information is encoded in the body of standard HTTP POST requests and responses. Each HTTP body contains a single <body/> XML wrapper element (not to be confused with the <body/> child of the <message/> stanza as defined in &xmppim;), which encapsulates zero or more XML stanzas.
+Although this JEP documents some XMPP-specific features, the binding is not part of XMPP. In fact, the protocol is extensible and could be used to implement any bidirectional stream of XML stanzas.
+This document inherits terminology regarding the Hypertext Transport Protocol from RFCs 1945 and 2068.
+Platform limitiations, security restrictions, and other constraints imply that many clients can connect to Internet resources (e.g., Jabber servers) only via HTTP. The following design requirements reflect the need to offer performance as close as possible to a standard TCP connection.
+-
+
- Compatible with constrained runtime environments (e.g., mobile and browser-based clients). +
- Compatible with restricted network connections (e.g., firewalls, proxies, and gateways). +
- Fault tolerant (e.g., session recovers after an underlying TCP connection breaks during an HTTP request). +
- Extensible (based on XML). +
- Consume significantly less bandwidth than polling-based solutions. +
- Significantly more responsive than polling-based solutions. +
- Support for polling (for clients that are limited to one HTTP connection at a time). +
- XML stanzas should arrive at the server in the order they were sent by the client. +
- Protect against unauthorized users interjecting HTTP requests into a session. +
Compatibility with constrained runtime environments implies the following restrictions:
+-
+
- Clients should not be required to have programmatic access to the headers of each HTTP request and response (e.g., cookies or status codes). +
- The body of each HTTP request and response should be parsable XML with a single root element. +
- Clients should be able to specify the Content-Type of the HTTP responses they receive. +
The binding of XMPP to HTTP assumes a different architecture from that described for the binding of XMPP to TCP as defined in RFC 3920. In particular, because HTTP is not the native binding for XMPP, we assume that most XMPP implementations will utilize a specialized "connection manager" to handle HTTP connections rather than the usual TCP connections. Effectively, such a connection manager will be a specialized HTTP server that translates between the HTTP requests and responses defined herein and the XML streams (or a server API) implemented by the XMPP server or servers with which it communicates, thus enabling an HTTP client to connect to an XMPP server. We can illustrate this graphically as follows:
+ wrapper]
+ |
+ HTTP Client
+ ]]>
+ This JEP addresses communications between an HTTP client and the connection manager only. It does not address communications between the connection manager and the XMPP server, since such communications are implementation-specific (e.g., the connection manager and the XMPP server may use &jep0114; or an API defined by the XMPP server implementation in order to communicate; alternatively, the XMPP server may natively support the HTTP binding, in which case the connection manager will be a logical entity rather than a physical entity).
+Furthermore, no aspect of the HTTP binding limits its use to client-to-server communications; i.e., it could be used for server-to-server or component-to-server communications as well (probably through a slight change to the XML schema). However, this document focuses exclusively on use of the HTTP binding by clients that cannot maintain persistent TCP connections to a server and that therefore cannot use the TCP binding defined in RFC 3920. We assume that servers and components are under no such restrictions and thus would use the TCP binding.
+Clients SHOULD send HTTP requests over persistent HTTP/1.1 connections. However, a constrained client MAY open a new HTTP/1.0 connection (as defined in RFC 1945) to send each request.
+Requests and responses MAY include HTTP headers not specified herein. The receiver SHOULD ignore any such headers.
+Clients MAY include an HTTP Accept-Encoding header in any request. If the connection manager receives a request with an Accept-Encoding header, it MAY include an HTTP Content-Encoding header in the response (indicating one of the encodings specified in the request) and compress the response body accordingly.
+TLS compression (as defined in RFC 3920) and Stream Compression (as defined in &jep0138;) are NOT RECOMMENDED since compression SHOULD be negotiated at the HTTP layer and with the 'accept' attribute (see the Session Creation section below). TLS compression and Stream Compression SHOULD NOT be used simultaneously with HTTP content encoding.
+The body of each HTTP request and response contains a single <body/> wrapper element. The <body/> element MUST contain zero or more complete XML elements. It MUST NOT contain partial XML elements.
+If the <body/> wrapper element is not empty, then it MUST contain one of the following:
+-
+
- One or more complete XMPP stanzas (<message/>, <presence/>, and/or <iq/>). +
- A complete <stream:features/> element (in which case the body element MUST include namespace xmlns:stream='http://etherx.jabber.org/streams'). +
- A complete element used for SASL negotiation and qualified by the 'urn:ietf:params:xml:ns:xmpp-sasl' namespace. +
- XML elements associated with a binding error condition. For details, refer to the Binding Conditions section below. +
Note: Inclusion of TLS negotiation elements is allowed but is NOT RECOMMENDED (see Additional Preconditions below).
+The <body/> wrapper element SHOULD be qualified by the 'http://jabber.org/protocol/httpbind' namespace, and child elements SHOULD be qualified by their respective namespaces (e.g., 'http://etherx.jabber.org/streams' for stream features, 'urn:ietf:params:xml:ns:xmpp-sasl' for SASL negotiation, and 'jabber:client' for XML stanzas). However, even if the client does not specify the namespaces, the connection manager MUST ensure that the XMPP it provides to the XMPP server or other entities on the network meets the namespacing requirements of RFC 3920.
+The <body/> element of every client request MUST possess a sequential request ID encapsulated via the 'rid' attribute; For details, refer to the Request IDs section of this document.
+The first request from the client to the connection manager creates a new session.
+The <body/> element of the first request SHOULD possess the following attributes (they SHOULD NOT be included in any other requests except as specified in the Adding Streams To A Session section below):
+-
+
- 'to' -- This attribute specifies the target domain. +
- 'xml:lang' -- This attribute (as defined in Section 2.12 of &w3xml;) specifies the default language of any human-readable XML character data sent or received during the session. +
- 'wait' -- This attribute specifies the longest time (in seconds) that the connection manager is allowed to wait before responding to any request during the session. This enables the client to prevent its TCP connection from expiring due to inactivity, as well as to limit the delay before it discovers any network failure. +
- 'hold' -- This attribute specifies the maximum number of requests the connection manager is allowed to keep waiting at any one time during the session. (For example, if a constrained client is unable to keep open more than two HTTP connections to the same HTTP server simultaneously, then it SHOULD specify a value of "1".) +
Note: Clients that only support polling behavior MAY prevent the connection manager from waiting by setting 'wait' or 'hold' to "0". However, polling is NOT RECOMMENDED since the associated increase in bandwidth consumption and the decrease in responsiveness are typically one or two orders of magnitude!
+A connection manager MAY be configured to enable sessions with more than one XMPP server in different domains. When requesting a session with such a 'proxy' connection manager, a client SHOULD include a 'route' attribute that specifies the protocol, hostname, and port of the server with which it wants to communicate, formatted as "proto:host:port" (e.g., "xmpp:jabber.org:9999").
A client MAY include a 'secure' attribute to specify that communications between the connection manager and the XMPP server must be "secure". (Note: The 'secure' attribute is of type xs:boolean (see &w3xmlschema2;) and the default value is "false". &BOOLEANNOTE;) If a connection manager receives a session request with the 'secure' attribute set to 'true' or '1', then it MUST respond to the client with a remote-connection-failed error as soon as it determines that it cannot communicate in a secure way with the XMPP server. A connection manager SHOULD consider communications with the XMPP server to be "secure" if they are encrypted using SSL or TLS with verified certificates, or if it is running on the same physical machine as the XMPP server. A connection manager MAY consider communications over a "private" network to be secure, even without SSL or TLS; however, a network SHOULD be considered "private" only if the administrator of the connection manager is sure that unknown individuals or processes do not have access to the network (i.e., individuals or processes who do not have access to either the connection manager or the XMPP server). The connection manager SHOULD try to establish a secure connection with the XMPP server even if the client does not specifically require it.
+Some clients are constrained to only accept HTTP responses with specific Content-Types (e.g., "text/html"). The <body/> element of the first request MAY possess a 'content' attribute. This specifies the value of the HTTP Content-Type header that MUST appear in all the connection manager's responses during the session. If the client request does not possess a 'content' attribute, then the HTTP Content-Type of responses MUST be "text/xml; charset=utf-8".
+Note: The HTTP Content-Type of client requests SHOULD also be "text/xml; charset=utf-8". Clients MAY specify another value if they are constrained to do so (e.g., "application/x-www-form-urlencoded" or "text/plain"). The client and connection manager SHOULD ignore all HTTP Content-Type headers they receive.
+Note: Unlike the protocol defined in JEP-0025, an opening <stream:stream> tag is not sent. The protocol defined herein abstracts from XML streams between the connection manager and the client. Any XML streams between the connection manager and an XMPP server are the responsibility of the connection manager.
+Note: All requests after the first one MUST include a valid 'sid' attribue (provided by the connection manager in the session creation response below). The initialization request is unique in that the <body/> element MUST NOT possess a 'sid' attribute.
+After receiving a new session request, the connection manager MUST generate an opaque, unpredictable session identifier (or SID). The SID MUST be unique within the context of the connection manager application. The connection manager then returns that SID to the client in a response <body/> element.
+The connection manager MUST specify a 'wait' attribute. This is the longest time (in seconds) that it will wait before responding to any request during the session. The time MUST be less than or equal to the value specified in the session request.
+The connection manager MAY limit the number of simultaneous requests the client makes with the 'requests' attribute. The RECOMMENDED value is "2". Servers that only support polling behavior MUST prevent clients from making simultaneous requests by setting the 'requests' attribute to a value of "1" (however, polling is NOT RECOMMENDED). In any case, clients MUST NOT make more simultaneous requests than specified by the connection manager.
+The connection manager SHOULD include two additional attributes in the session creation response element, specifying the shortest allowable polling interval and the longest allowable inactivity period (both in seconds). Communication of these parameters enables the client to engage in appropriate behavior (e.g., not sending empty request elements more often than desired, and ensuring that the periods with no requests pending are never too long).
+The connection manager MAY include an 'accept' attribute in the session creation response element, to specify the content encodings it can decompress. After receiving a session creation response with an 'accept' attribute, clients MAY include an HTTP Content-Encoding header in subsequent requests (indicating one of the encodings specified in the 'accept' attribute) and compress the bodies of the requests accordingly.
+For both requests and responses, the <body/> element and its content SHOULD be UTF-8 encoded. If the HTTP Content-Type header of a request/response specifies a character encoding other than UTF-8, then the connection manager MAY convert between UTF-8 and the other character encoding. However, even in this case, it is OPTIONAL for the connection manager to convert between encodings. The connection manager MAY inform the client which encodings it can convert by setting the optional 'charsets' attribute in the session creation response element to a space-separated list of encodings.
+
Note: The 'authid' attribute contains the value of the XMPP stream ID generated by the XMPP server. The connection manager MUST retrieve the stream ID and pass it unmodified to the client. This value is needed by the client to successfully complete digest authentication using &jep0078; (see the jabber:iq:auth section below).
+Note: If the 'authid' attribute is not included in the connection manager's response to the session creation request (e.g., because the connection manager has not yet received a stream ID from the XMPP server), then the client SHOULD send empty request elements (see the "Requesting XML Stanzas" example below) until it receives a response with an 'authid' attribute. In any case, the connection manager MUST return the 'authid' in a response to the client as soon as possible after it receives the stream ID from the XMPP server.
+Separate 'sid' and 'authid' attributes are required because the connection manager is not necessarily part of a single XMPP server (e.g., it may handle HTTP connections on behalf of multiple XMPP servers).
+If it established a secure connection to the XMPP server (as defined in Initiating an HTTP Session), then the connection manager SHOULD include the 'secure' attribute set to 'true' or '1' in the response to the client that contains the 'authid' attribute.
+As an immediate child of the response that contains the 'authid' attribute, the connection manager SHOULD include a stream features element, as defined by RFC 3920.
+The stream features SHOULD NOT include a feature for Transport Layer Security (TLS), since channel encryption SHOULD be negotiated at the HTTP layer (see the Security Considerations section below).
+Initializing an HTTP session is the first precondition to sending XML message, presence, and IQ stanzas. However, before processing XML stanzas from the client, the connection manager MUST require completion of additional preconditions using either of the following methods:
+-
+
-
+
XMPP authentication, resource binding, and IM session creation, in the following order:
+-
+
- Optionally, TLS negotiation as defined in Section 5 of RFC 3920 (this is NOT RECOMMENDED since channel encryption and compression SHOULD be negotiated at the HTTP layer; see the Security Considerations section below) +
- SASL authentication as defined in Section 6 of RFC 3920 +
- Resource Binding as defined in Section 7 of RFC 3920 +
- IM Session Establishment as defined in Section 3 of RFC 3921, if appropriate +
+ -
+
Simultaneous authentication and resource binding as defined in Non-SASL Authentication, upon which a Jabber server will also establish an IM session on behalf of the connected resource.
+
+
It is RECOMMENDED to use the XMPP methods as defined in RFC 3920 and RFC 3921, rather than using older non-SASL authentication.
+ +A success case for authentication, resource binding, and IM session establishment using the XMPP protocols is shown below. For detailed specification of these protocols (including error cases) and for specification of TLS negotiation, refer to RFC 3920 and RFC 3921.
+Note: Because the context for a client's communication with a connection manager in the HTTP transport binding is HTTP rather than XML streams (as in the TCP binding), there is no need to re-start communications (e.g., by generating a new SID) at this point.
+ +