moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-21 08:45:04 -05:00
Code Issues Releases Wiki Activity

Initial revision

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2006-10-02 22:22:13 +00:00
commit 2ac91f50c8
219 changed files with 93420 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
all.sh Executable file
View File

@ -0,0 +1,31 @@
#!/bin/sh
# for each XEP, generates HTML file and IETF reference, then copies XML file
# also generates HTML for the README and template
# finally, copies the stylesheet, DTD, and schema
# usage: ./all.sh
xeppath=/var/www/stage.xmpp.org/extensions
ls xep-0*.xml > tmp.txt
sed s/xep-\(.*\).xml/\1/ tmp.txt > nums.txt
rm tmp.txt
while read f
do
xsltproc xep.xsl xep-$f.xml > $xeppath/xep-$f.html
xsltproc ref.xsl xep-$f.xml > $xeppath/refs/reference.JSF.XEP-$f.xml
cp xep-$f.xml $xeppath/
done < nums.txt
rm nums.txt
xsltproc xep.xsl xep-README.xml > $xeppath/README.html
xsltproc xep.xsl xep-template.xml > $xeppath/template.html
cp xep.dtd $xeppath/
cp xep.ent $xeppath/
cp xep.xsd $xeppath/
cp xep.xsl $xeppath/
# END

187
announce.py Executable file
View File

@ -0,0 +1,187 @@
#!/usr/bin/env python
# File: announce.py
# Version: 0.8
# Description: a script for announcing XEPs
# Last Modified: 2006-10-03
# Author: Peter Saint-Andre (stpeter@jabber.org)
# License: public domain
# HowTo: ./announce.py xepnum dbuser dbpw 'cvsmodsurl'
# NOTE: the cvsmodsurl MUST be in quotes!
# 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. XEP number
# 2. database user
# 3. database password
xepnum = sys.argv[1];
dbuser = sys.argv[2];
dbpw = sys.argv[3];
mods = sys.argv[4];
xepfile = 'xep-' + xepnum + '.xml'
# PARSE XEP HEADERS:
#
# - title
# - abstract
# - version
# - date
# - initials
# - remark
thexep = parse(xepfile)
xepNode = (thexep.getElementsByTagName("xep")[0])
headerNode = (xepNode.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])
xepstatus = getText(statusNode.childNodes)
typeNode = (headerNode.getElementsByTagName("type")[0])
xeptype = 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)
remNode = (revNode.getElementsByTagName("remark")[0])
# could be <p> or <ul>
testRemarkNode = remNode.firstChild.nodeName
# print testRemarkNode
if (testRemarkNode == "p"):
remarkNode = (remNode.getElementsByTagName("p")[0])
remark = getText(remarkNode.childNodes)
else:
remark = "[See revision history]"
# what kind of action are we taking?
xepflag = ""
if (version == "0.1"):
xepflag = "new"
elif ((version == "1.0") & (xeptype == "Standards Track")):
xepflag = "draft"
elif ((version == "1.0") & (xeptype != "Standards Track")):
xepflag = "active"
elif (version == "2.0"):
xepflag = "final"
elif (xepstatus == "Retracted"):
xepflag = "retract"
elif (xepstatus == "Deferred"):
xepflag = "defer"
# UPDATE DATABASE:
#
# number is $xepnum
# name is $title
# type is $xeptype
# status is $xepstatus
# notes is "Version $version of XEP-$xepnum 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 XEP-" + xepnum + " released " + date + "."
theLog = remark + " (" + initials + ")"
if xepflag == "new":
theStatement = "INSERT INTO jeps VALUES ('" + str(xepnum) + "', '" + title + "', '" + xeptype + "', '" + xepstatus + "', '" + theNotes + "', '" + str(version) + "', '" + str(now) + "', '" + abstract + "', '" + theLog + "', '0', '5', 'Proposed', 'none');"
cursor.execute(theStatement)
else:
theStatement = "UPDATE jeps SET name='" + title + "', type='" + xeptype + "', status='" + xepstatus + "', notes='" + theNotes + "', version='" + str(version) + "', last_modified='" + str(now) + "', abstract='" + abstract + "', changelog='" + theLog + "' WHERE number='" + str(xepnum) + "';"
cursor.execute(theStatement)
result = cursor.fetchall()
## SEND MAIL:
#
# From: editor@jabber.org
# To: standards-jig@jabber.org
# Subject: UPDATED: XEP-$xepnum ($title)
# [or "NEW..." if version 0.1]
# Body:
# Version $version of XEP-$xepnum ($title) is now available.
# Abstract: $abstract
# Changelog: $remark ($initials)
# CVS Diff: $mods
# URL: http://www.xmpp.org/extensions/xep-$xepnum.html
fromaddr = "editor@jabber.org"
# for testing...
# toaddrs = "stpeter@jabber.org"
# for real...
toaddrs = "standards-jig@jabber.org"
if xepflag == "new":
thesubject = 'NEW: XEP-'
elif xepflag == "draft":
thesubject = 'DRAFT: XEP-'
toaddrs = toaddrs + ", jdev@jabber.org"
elif xepflag == "final":
thesubject = 'FINAL: XEP-'
toaddrs = toaddrs + ", jdev@jabber.org"
elif xepflag == "active":
thesubject = 'ACTIVE: XEP-'
elif xepflag == "retract":
thesubject = 'RETRACTED: XEP-'
elif xepflag == "defer":
thesubject = 'DEFERRED: XEP-'
else:
thesubject = 'UPDATED: XEP-'
thesubject = thesubject + xepnum + ' (' + title + ')'
versionline = 'Version ' + version + ' of XEP-' + xepnum + ' (' + title + ') has been released.'
abstractline = 'Abstract: ' + abstract
changelogline = 'Changelog: ' + remark + ' (' + initials + ')'
modsline = 'CVS Diff: ' + mods
urlline = 'URL: http://www.xmpp.org/extensions/xep-' + xepnum + '.html'
msg = "From: XMPP Extensions Editor <%s>\r\n" % fromaddr
msg = msg + "To: %s\r\n" % toaddrs
msg = msg + "Subject: %s\r\n" % thesubject
msg = msg + versionline
msg = msg + "\r\n\n"
msg = msg + abstractline
msg = msg + "\r\n\n"
msg = msg + changelogline
msg = msg + "\r\n\n"
msg = msg + modsline
msg = msg + "\r\n\n"
msg = msg + urlline
msg = msg + "\r\n\n"
server = smtplib.SMTP('localhost')
server.set_debuglevel(1)
server.sendmail(fromaddr, toaddrs, msg)
server.quit()
# END

9
archive.sh Executable file
View File

@ -0,0 +1,9 @@
#!/bin/sh
# archive an old version of a XEP (before publishing new version)
# usage: ./archive.sh xepnum version
xeppath=/var/www/xmpp.org/extensions
cp $xeppath/xep-$1.html $jeppath/attic/xep-$1-$2.html
# end

143
deferred.py Executable file
View File

@ -0,0 +1,143 @@
#!/usr/bin/env python
# File: deferred.py
# Version: 0.2
# Description: a script for setting a JEP to Deferred
# Last Modified: 2006-04-24
# Author: Peter Saint-Andre (stpeter@jabber.org)
# License: public domain
# HowTo: ./deferred.py jepnum 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. database user
# 3. database password
jepnum = sys.argv[1];
dbuser = sys.argv[2];
dbpw = sys.argv[3];
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 + "; consideration deferred because of inactivity."
theLog = remark + " (" + initials + ")"
theStatement = "UPDATE jeps SET name='" + title + "', type='" + jeptype + "', status='Deferred', 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: DEFERRED: JEP-$jepnum ($title)
# Body:
# JEP-$jepnum ($title) has been Deferred because of inactivity.
#
# Abstract: $abstract
#
# URL: http://www.jabber.org/jeps/jep-$jepnum.html
#
# If and when a new revision of this JEP is published,
# its status will be changed back to Experimental.
#
fromaddr = "editor@jabber.org"
# for testing...
# toaddrs = "stpeter@jabber.org"
# for real...
toaddrs = "standards-jig@jabber.org"
thesubject = 'DEFERRED: JEP-' + jepnum + " (" + title + ")"
introline = 'JEP-' + jepnum + ' (' + title + ') has been Deferred because of inactivity.'
abstractline = 'Abstract: ' + abstract
urlline = 'URL: http://www.jabber.org/jeps/jep-' + jepnum + '.html'
endline = 'If and when a new revision of this JEP is published, its status will be changed back to Experimental.'
#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 + endline
msg = msg + "\r\n"
server = smtplib.SMTP('localhost')
server.set_debuglevel(1)
server.sendmail(fromaddr, toaddrs, msg)
server.quit()
# END

21
editor.shtml Executable file
View File

@ -0,0 +1,21 @@
<html>
<head>
<title>XEP Editor</title>
<!--#include virtual="/includes/head.txt" -->
<h2>XEP Editor</h2>
<p>In accordance with <a href="jep-0001.html">XEP-0001</a>, the XEP Editor is responsible for overall management of the Jabber Software Foundation's standards process and publication of <a href="/extensions/">XMPP Extension Protocols</a>; in particular, the XEP Editor:</p>
<ul>
<li>works with XEP authors</li>
<li>ensures that each XEP is properly formatted</li>
<li>assigns a unique number to each XEP</li>
<li>assigns or modifies the status of each XEP</li>
<li>maintains each XEP under <a href="http://www.jabberstudio.org/cgi-bin/viewcvs.cgi/jeps/">source control</a></li>
<li>maintains the canonical <a href="/extensions/">list of XEPs</a></li>
<li>publishes each XEP to the xmpp.org website</li>
<li>publicly announces the existence and status of each XEP</li>
<li>gathers and tallies the votes of the <a href="/council/">XMPP Council</a></li>
<li>fulfills the responsibilities of the <a href="/registrar/">XMPP Registrar</a></li>
</ul>
<p>Since the founding of the Jabber Software Foundation in 2001, the XEP Editor has been <a href="http://www.jabber.org/people/stpeter.shtml">Peter Saint-Andre</a>, who may be contacted via &lt;&#101;&#100;&#105;&#116;&#111;&#114;&#64;&#106;&#97;&#98;&#98;&#101;&#114;&#46;&#111;&#114;&#103&gt;.</p>
</div>
<!--#include virtual="/includes/foot.txt" -->

399
fo.xsl Normal file
View File

@ -0,0 +1,399 @@
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/XSL/Format">
<xsl:template match="/">
<root>
<layout-master-set>
<simple-page-master master-name="cover">
<region-body margin-left="1in" margin-right="1in" margin-top="2.5in" margin-bottom="1in"/>
</simple-page-master>
<!--<simple-page-master master-name="doc_info">
<region-body margin-left="1in" margin-top="1in" margin-right="1in" margin-bottom="1in"/>
</simple-page-master>
<simple-page-master master-name="toc_page">
<region-body margin-left="1in" margin-top="1in" margin-right="1in" margin-bottom="1in"/>
</simple-page-master>-->
<simple-page-master master-name="std_page">
<region-body margin-left="1in" margin-top="1in" margin-right="1in" margin-bottom="1in"/>
<region-before extent="1in" display-align="after"/>
<region-after extent="1in" display-align="before"/>
</simple-page-master>
<page-sequence-master master-name="jep_sequence">
<single-page-master-reference master-reference="cover"/>
<!--<single-page-master-reference master-reference="doc_info"/>
<single-page-master-reference master-reference="toc_page"/>-->
<repeatable-page-master-reference master-reference="std_page"/>
</page-sequence-master>
</layout-master-set>
<page-sequence master-reference="jep_sequence">
<flow flow-name="xsl-region-body" font-family="serif" color="black" font-size="10pt">
<block space-before="1.5in" text-align="right" font-family="sans-serif" font-size="18pt">
JEP-<xsl:value-of select="/jep/header/number"/>
</block>
<block text-align="right" font-family="sans-serif" font-size="18pt">
<xsl:value-of select="/jep/header/title"/>
</block>
<!--</flow>
</page-sequence>
<page-sequence master-reference="doc_info">
<flow flow-name="xsl-region-body" font-family="serif" font-size="10pt" color="black">-->
<block font-family="sans-serif" font-size="14pt" space-after=".5em" break-before="page">Document Information</block>
<block font-size="12pt" font-weight="bold">Document Author(s)</block>
<block>
<inline font-weight="bold">Name: </inline>
<inline>
<xsl:value-of select="/jep/header/author/firstname"/>
<xsl:value-of select="/jep/header/author/surname"/>
</inline>
</block>
<block>
<inline font-weight="bold">Email: </inline>
<inline>
<xsl:value-of select="/jep/header/author/email"/>
</inline>
</block>
<block space-after=".5em">
<inline font-weight="bold">JID: </inline>
<inline>
<xsl:value-of select="/jep/header/author/jid"/>
</inline>
</block>
<block font-size="12pt" font-weight="bold">Abstract</block>
<block space-after=".5em">
<xsl:value-of select="/jep/header/abstract"/>
</block>
<block font-size="12pt" font-weight="bold">Document Status</block>
<block space-after=".5em">
<xsl:value-of select="/jep/header/status"/>
</block>
<block font-size="12pt" font-weight="bold">Dependencies/References</block>
<block space-after=".5em">
<xsl:value-of select="/jep/header/dependencies"/>
</block>
<block font-size="12pt" font-weight="bold">Legal Notice</block>
<block space-after=".5em">
<xsl:value-of select="/jep/header/legal"/>
</block>
<block font-size="12pt" font-weight="bold" space-after=".5em">Revision History</block>
<table table-layout="fixed" border-width=".25pt" border-color="black" border-style="solid">
<table-column text-align="center" column-width=".625in" column-number="1"/>
<table-column text-align="center" column-width=".75in" column-number="2"/>
<table-column text-align="center" column-width=".5in" column-number="3"/>
<table-column column-width="4.125in" column-number="4"/>
<table-body>
<table-row background-color="black" color="white" font-weight="bold">
<table-cell padding="3pt">
<block>Version</block>
</table-cell>
<table-cell padding="3pt">
<block>Date</block>
</table-cell>
<table-cell padding="3pt">
<block>Initials</block>
</table-cell>
<table-cell padding="3pt">
<block>Comment</block>
</table-cell>
</table-row>
<xsl:apply-templates select="/jep/header"/>
</table-body>
</table>
<!--</flow>
</page-sequence>
<page-sequence master-reference="toc_page" force-page-count="no-force" format="i">
<flow flow-name="xsl-region-body" font-family="serif" font-size="10pt" color="black">-->
<xsl:call-template name="processTOC"/>
</flow>
</page-sequence>
<page-sequence master-reference="std_page" initial-page-number="1">
<!--<static-content flow-name="xsl-region-before" margin-top=".5in">
<block margin-left="1in" margin-right="1in" text-align-last="justify" font-size="9pt" font-family="sans-serif" color="silver">
<xsl:value-of select="/jep/header/customer"/>
<leader leader-pattern="space"/>
Requirements Proposal
</block>
<block margin-left="1in" margin-right="1in" padding-bottom="10pt" border-after-color="black" border-after-width=".25pt" border-after-style="solid" text-align-last="justify" font-size="9pt" font-family="sans-serif" color="silver">
<xsl:value-of select="/jep/header/title"/>
<leader leader-pattern="space"/>
<xsl:value-of select="/jep/header/revision[last()]/date"/>
</block>
</static-content>-->
<static-content flow-name="xsl-region-after">
<block margin-left="1in" margin-right="1in" padding-top="10pt" border-before-color="black" border-before-width=".125pt" border-before-style="solid" text-align-last="justify" font-size="8pt" font-family="sans-serif" color="black">
IJEP-<xsl:value-of select="/jep/header/number"/>:<xsl:text> </xsl:text>
<xsl:value-of select="/jep/header/title"/>
<leader leader-pattern="space"/>
Page <page-number/> of <page-number-citation ref-id="lastpage"/>
</block>
</static-content>
<flow flow-name="xsl-region-body" font-family="serif" font-size="10pt" color="black">
<xsl:apply-templates select="/jep/section1"/>
<block font-family="sans-serif" font-size="12pt" color="black" space-before=".5em" space-after=".5em">Notes:</block>
<xsl:apply-templates select="//note" mode="endlist"/>
<block id="lastpage"/>
</flow>
</page-sequence>
</root>
</xsl:template>
<!-- From the docbook XSL -->
<xsl:template name="object.id">
<xsl:param name="object" select="."/>
<xsl:choose>
<xsl:when test="$object/@id">
<xsl:value-of select="$object/@id"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="generate-id($object)"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template name="processTOC">
<block font-family="sans-serif" font-size="14pt" space-after=".5em" break-before="page">Table of Contents</block>
<xsl:apply-templates select="//section1" mode="toc"/>
</xsl:template>
<xsl:template match="/jep/header/revision">
<table-row>
<table-cell padding="3pt">
<block>
<xsl:value-of select="version"/>
</block>
</table-cell>
<table-cell padding="3pt">
<block>
<xsl:value-of select="date"/>
</block>
</table-cell>
<table-cell padding="3pt">
<block>
<xsl:value-of select="initials"/>
</block>
</table-cell>
<table-cell padding="3pt">
<block>
<xsl:value-of select="remark"/>
</block>
</table-cell>
</table-row>
</xsl:template>
<xsl:template match="section1" mode="toc">
<xsl:variable name="oid">
<xsl:call-template name="object.id"/>
</xsl:variable>
<xsl:variable name="num">
<xsl:number level="multiple" count="section1"/>
<xsl:text>.</xsl:text>
</xsl:variable>
<xsl:variable name="sect2.count" select="count(section2)"/>
<xsl:value-of select="$num"/>
<xsl:text> </xsl:text>
<block text-align-last="justify" font-variant="small-caps">
<xsl:value-of select="$num"/>
<xsl:value-of select="@topic"/>
<xsl:text> </xsl:text>
<leader leader-pattern="rule" space-end=".125in"/>
<xsl:text> </xsl:text>
<page-number-citation ref-id="sect-{$oid}"/>
</block>
<xsl:if test="$sect2.count &gt; 0">
<xsl:apply-templates select="section2" mode="toc">
<xsl:with-param name="prevnum" select="$num"/>
</xsl:apply-templates>
</xsl:if>
</xsl:template>
<xsl:template match="section1">
<xsl:variable name="oid">
<xsl:call-template name="object.id"/>
</xsl:variable>
<xsl:variable name="num">
<xsl:number level="multiple" count="section1"/>
<xsl:text>.</xsl:text>
</xsl:variable>
<!--<xsl:number level="single" count="section1"/>-->
<block id="sect-{$oid}" font-family="sans-serif" font-size="14pt" space-after="1em" space-before="1em" font-weight="bold">
<xsl:value-of select="$num"/>
<xsl:text> </xsl:text>
<xsl:value-of select="@topic"/>
</block>
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="section2" mode="toc">
<xsl:param name="prevnum" select='""'/>
<xsl:variable name="oid">
<xsl:call-template name="object.id"/>
</xsl:variable>
<xsl:variable name="num">
<xsl:value-of select="$prevnum"/>
<xsl:number level="multiple" count="section2"/>
<xsl:text>.</xsl:text>
</xsl:variable>
<xsl:variable name="sect3.count" select="count(section3)"/>
<block text-align-last="justify" margin-left="1em">
<xsl:value-of select="$num"/>
<xsl:text> </xsl:text>
<xsl:value-of select="@topic"/>
<xsl:text> </xsl:text>
<leader leader-pattern="rule" space-end=".125in"/>
<xsl:text> </xsl:text>
<page-number-citation ref-id="sect-{$oid}"/>
</block>
<xsl:if test="$sect3.count &gt; 0">
<xsl:apply-templates select="section3" mode="toc">
<xsl:with-param name="prevnum" select="$num"/>
</xsl:apply-templates>
</xsl:if>
</xsl:template>
<xsl:template match="section2">
<xsl:param name="prevnum" select='""'/>
<xsl:variable name="oid">
<xsl:call-template name="object.id"/>
</xsl:variable>
<xsl:variable name="num">
<xsl:number level="single" count="section1"/>.<xsl:number level="multiple" count="section2"/>
<xsl:text>.</xsl:text>
</xsl:variable>
<xsl:variable name="sect3.count" select="count(section3)"/>
<block id="sect-{$oid}" font-weight="bold" font-family="sans-serif">
<xsl:value-of select="$num"/>
<xsl:text> </xsl:text>
<xsl:value-of select="@topic"/>
</block>
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="section3" mode="toc">
<xsl:param name="prevnum" select='""'/>
<xsl:variable name="oid">
<xsl:call-template name="object.id"/>
</xsl:variable>
<xsl:variable name="num">
<xsl:value-of select="$prevnum"/>
<xsl:number level="multiple" count="section3"/>
<xsl:text>.</xsl:text>
</xsl:variable>
<block text-align-last="justify" margin-left="1em">
<xsl:value-of select="$num"/>
<xsl:text> </xsl:text>
<xsl:value-of select="@topic"/>
<xsl:text> </xsl:text>
<leader leader-pattern="rule" space-end=".125in"/>
<xsl:text> </xsl:text>
<page-number-citation ref-id="sect-{$oid}"/>
</block>
</xsl:template>
<xsl:template match="section3">
<xsl:variable name="oid">
<xsl:call-template name="object.id"/>
</xsl:variable>
<block id="sect-{$oid}" margin-left=".5em">
<xsl:if test="../../@type='functional-spec'">FR-<xsl:number level="single" count="section2"/>.<xsl:number level="single" count="section3"/>
</xsl:if>
<xsl:if test="../../@type='supp-spec'">SS-<xsl:number level="single" count="section2"/>.<xsl:number level="single" count="section3"/>
</xsl:if>
<xsl:text> </xsl:text>
<xsl:value-of select="@topic"/>
<xsl:apply-templates/>
</block>
</xsl:template>
<xsl:template match="p">
<block space-before=".5em" space-after=".5em">
<xsl:apply-templates/>
</block>
</xsl:template>
<xsl:template match="code">
<block space-after="1em" margin-bottom="1em" margin-left="1em" font-family="monospace" font-size="8pt" font-weight="normal" white-space-collapse="false" keep-together.within-page="always">
<xsl:value-of select="."/>
</block>
</xsl:template>
<xsl:template match="example">
<table table-layout="fixed" width="100%" space-after="1em">
<table-column column-width="proportional-column-width(1)"/>
<table-body>
<table-row keep-with-next="always">
<table-cell>
<block margin-left=".5em" space-after=".5em" space-before=".5em" font-weight="600" font-size="9pt">
Example <xsl:number level="any" count="example"/>.<xsl:text> </xsl:text>
<xsl:value-of select="@caption"/>
</block>
</table-cell>
</table-row>
<table-row>
<table-cell>
<block margin-left="1em" font-family="monospace" font-size="8pt" font-weight="normal" white-space-collapse="false" keep-together.within-page="always">
<xsl:value-of select="."/>
</block>
</table-cell>
</table-row>
</table-body>
</table>
</xsl:template>
<xsl:template match="note">
<xsl:variable name="notenum">
<xsl:number level="any" count="note"/>
</xsl:variable>
<xsl:variable name="oid">
<xsl:call-template name="object.id"/>
</xsl:variable>
<inline>[<basic-link color="blue" font-weight="bold" internal-destination="nt-{$oid}">
<xsl:value-of select="$notenum"/>
</basic-link>]</inline>
</xsl:template>
<xsl:template match="note" mode="endlist">
<xsl:variable name="oid">
<xsl:call-template name="object.id"/>
</xsl:variable>
<block id="nt-{$oid}" margin=".5em" font-size="8pt">
<xsl:value-of select="position()"/>. <xsl:apply-templates/>
</block>
</xsl:template>
<xsl:template match="link">
<basic-link external-destination="{@url}" text-decoration="underline" color="blue">
<xsl:apply-templates/>
</basic-link>
</xsl:template>
<xsl:template match="strong">
<inline font-weight="bold">
<xsl:apply-templates/>
</inline>
</xsl:template>
<xsl:template match="em">
<inline font-style="italic">
<xsl:apply-templates/>
</inline>
</xsl:template>
<xsl:template match="ul">
<list-block provisional-distance-between-starts="10pt" provisional-label-separation="3pt" space-after=".5em" space-start="1em" margin-left="1em">
<xsl:apply-templates select="li" mode="ul"/>
</list-block>
</xsl:template>
<xsl:template match="ol">
<list-block provisional-distance-between-starts="10pt" provisional-label-separation="3pt" space-after=".5em" space-start="1em" margin-left="1em">
<xsl:apply-templates select="li" mode="ol"/>
</list-block>
</xsl:template>
<xsl:template match="li" mode="ul">
<list-item>
<list-item-label end-indent="label-end()">
<block>&#x2022;</block>
</list-item-label>
<list-item-body start-indent="body-start()">
<block>
<xsl:value-of select="."/>
</block>
</list-item-body>
</list-item>
</xsl:template>
<xsl:template match="li" mode="ol">
<xsl:variable name="num">
<xsl:number level="multiple" count="li"/>
</xsl:variable>
<list-item>
<list-item-label end-indent="label-end()">
<block>
<xsl:value-of select="$num"/>.</block>
</list-item-label>
<list-item-body start-indent="body-start()">
<block>
<xsl:value-of select="."/>
</block>
</list-item-body>
</list-item>
</xsl:template>
</xsl:stylesheet>

12
gen.sh Executable file
View File

@ -0,0 +1,12 @@
#!/bin/sh
# for one XEP, generates HTML file and IETF reference, then copies XML file
# usage: ./gen.sh xxxx
# (where xxxx is the 4-digit XEP number)
xeppath=/var/www/stage.xmpp.org/extensions
xsltproc xep.xsl xep-$1.xml > $xeppath/jep-$1.html
xsltproc ref.xsl xep-$1.xml > $xeppath/refs/reference.JSF.XEP-$1.xml
cp xep-$1.xml $xeppath/
# end

BIN
gps_datum.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB

24
gps_datum.html Normal file
View File

@ -0,0 +1,24 @@
<html>
<head>
<title>GPS Datum Example</title>
</head>
<body>
<h1>GPS Datum Example</h1>
<p>The following example of GPS datum differences was kindly provided by Randy Steele of Apollo, Pennsylvania (URL: &lt;<a href="http://www.nb.net/~resteele/">http://www.nb.net/~resteele/</a>&gt;) and is archived here so that a permanent link is available from <a href="http://www.jabber.org/jeps/jep-0080.html">JEP-0080: User Geolocation</a>.</p>
<p>BEGIN EXAMPLE</p>
<hr />
<p>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.</p>
<p><img src='gps_datum.gif' alt='GPS Datum Example' longdesc='An example of different GPS readings when using a datum of NAD27 vs. WGS84, provided by Randy Steele'/>
<hr />
<p>END EXAMPLE</p>
</body>
</html>

29
index.shtml Executable file
View File

@ -0,0 +1,29 @@
<html>
<head>
<title>XMPP Extensions</title>
<!--#include virtual="/includes/head.txt" -->
<h2>XMPP Extensions</h2>
<p><a class="standardsButton" href="atom.xml">ATOM</a>&nbsp;&nbsp;<a class="standardsButton" href="rss.xml">RSS</a></p>
<p>The <a href='http://www.jabber.org/jsf/'>Jabber Software Foundation</a> (JSF) develops extensions to <a href="http://www.xmpp.org/">XMPP</a> through a standards process centered around XMPP Extension Protocols (XEPs). The <a href="xep-0001.html">process</a> is managed by the <a href="editor.shtml">XMPP Extensions Editor</a> and involves intensive discussion on the <a href="http://mail.jabber.org/mailman/listinfo/standards-jig/">Standards-JIG mailing list</a>, formal review and <a href="/council/votes.shtml">voting</a> by the <a href="/council/">XMPP Council</a>, and modification based on implementation experience and interoperability testing. All documents in the XEP series are available under a liberal <a href="ipr-policy.shtml">IPR Policy</a> for wide implementation. Submissions are <a href='submit.shtml'>welcome</a> (see also the <a href="/extensions/inbox/">&quot;inbox&quot;</a>). Changes are tracked via a <a href="http://www.jabberstudio.org/cgi-bin/viewcvs.cgi/jeps/">CVS repository</a> (see <a href='http://www.jabberstudio.org/cvs.php'>instructions</a>), <a href="/extensions/attic/">old versions</a> are available, and IETF-style <a href="/extensions/refs/">XML reference files</a> are provided.</p>
<p>This page lists approved XMPP extensions as well as proposals that are under active consideration. A <a href="all.shtml">list of all XEPs</a> (including retracted, rejected, deprecated, and obsolete XEPs) is also available. Good places for developers to start are the <a href='xep-0073.html'>basic</a> and <a href='xep-0117.html'>intermediate</a> protocol suites.</p>
<p><em>Note: The following table is sortable, just click on the headers (click twice to reverse the sort order).</em></p>
<table border='1' cellpadding='3' cellspacing='0' class='sortable' id='xeplist'>
<tr class='jepheader'>
<th align='left'>Number</th>
<th align='left'>Name</th>
<th align='left'>Type</th>
<th align='left'>Status</th>
<th align='left'>Date</th>
</tr>
<!--#include virtual="/includes/xeps-default.txt" -->
</table>
</div>
<!--#include virtual="/includes/foot.txt" -->

121
inxep.py Executable file
View File

@ -0,0 +1,121 @@
#!/usr/bin/env python
# File: protojep.py
# Version: 0.1
# Description: a script for announcing proto-JEPs
# Last Modified: 2004-09-14
# Author: Peter Saint-Andre (stpeter@jabber.org)
# License: public domain
# HowTo: ./protojep.py filename
# (note: do not include extension!)
# IMPORTS:
#
import glob
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
# READ IN ARGS:
#
# 1. JEP filename (sans extension)
jepname = sys.argv[1];
jepfile = 'inbox/' + jepname + '.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)
# SEND MAIL:
#
# From: editor@jabber.org
# To: standards-jig@jabber.org
# Subject: LAST CALL: JEP-$jepnum ($title)
# Body:
# The JEP Editor has received a proposal for a new JEP.
#
# Title: $title
#
# Abstract: $abstract
#
# URL: http://www.jabber.org/jeps/inbox/$jepname.html
#
# The Jabber Council will now consider whether to accept
# this proposal as a full JEP.
#
fromaddr = "editor@jabber.org"
# for testing...
# toaddrs = "stpeter@jabber.org"
# for real...
toaddrs = "standards-jig@jabber.org"
thesubject = 'proto-JEP: ' + title
introline = 'The JEP Editor has received a proposal for a new JEP.'
titleline = 'Title: ' + title
abstractline = 'Abstract: ' + abstract
urlline = 'URL: http://www.jabber.org/jeps/inbox/' + jepname + '.html'
actionline = 'The Jabber Council will decide within 7 days (or at its next meeting) whether to accept this proposal as an official JEP.'
#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 + titleline
msg = msg + "\r\n\n"
msg = msg + abstractline
msg = msg + "\r\n\n"
msg = msg + urlline
msg = msg + "\r\n\n"
msg = msg + actionline
msg = msg + "\r\n\n"
server = smtplib.SMTP('localhost')
server.set_debuglevel(1)
server.sendmail(fromaddr, toaddrs, msg)
server.quit()
# END

91
ipr-policy.shtml Executable file
View File

@ -0,0 +1,91 @@
<html>
<head>
<title>JSF IPR Policy</title>
<!--#include virtual="/includes/head.txt" -->
<h2>JSF IPR Policy</h2>
<p>This document defines the official policy of the <a href='http://www.jabber.org/jsf/'>Jabber Software Foundation</a> regarding intellectual property rights (IPR) pertaining to <a href='http://www.xmpp.org/extensions/'>XMPP Extension Protocol</a> (XEPs) specifications.</p>
<p><em>Version 1.2</em></p>
<p><hr></p>
<strong>Table of Contents:</strong><br><dl>
<dt>1. <a href="#intro">Introduction</a></dt>
<dl>
<dt>1.1. <a href="#intro-history">History</a></dt>
<dt>1.2. <a href="#intro-role">Purpose</a></dt>
</dl>
<dt>2. <a href="#terms">Terms</a></dt>
<dl>
<dt>2.1. <a href="#xmpp">XMPP</a></dt>
<dt>2.2. <a href="#extension">XMPP Extension Protocol</a></dt>
<dt>2.3. <a href="#implementation">Implementation</a></dt>
<dt>2.4. <a href="#claim">Intellectual Property Claim</a></dt>
</dl>
<dt>3. <a href="#contributing">Terms of Contributing to XMPP Extensions</a></dt>
<dl>
<dt>3.1. <a href="#contrib-ownership">Ownership</a></dt>
<dt>3.2. <a href="#contrib-approval">Approval of XMPP Extensions</a></dt>
<dt>3.3. <a href="#contrib-private">A Note about Private Extensions</a></dt>
</dl>
<dt>4. <a href="#legal">Legal Notice</a>
</dt>
</dl>
<p><hr></p>
<h2>1. <a name="intro"></a>Introduction</h2>
<p>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). [<a href="#note1">1</a>]</p>
<blockquote>
<h3>1.1 <a name="intro-history"></a>History</h3>
<p>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" [<a href="#note2">2</a>] to which new and established participants in the Jabber community have entrusted their XMPP Extensions.</p>
<h3>1.2 <a name="intro-role"></a>Purpose</h3>
<p>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.</p>
</blockquote>
<h2>2. <a name="terms"></a>Terms</h2>
<blockquote>
<h3>2.1 <a name="xmpp"></a>XMPP</a>
</h3>
<p>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 <a href='http://www.ietf.org/rfc/rfc3920.txt'>RFC 3920</a> and <a href='http://www.ietf.org/rfc/rfc3921.txt'>RFC 3921</a>.</p>
</blockquote>
<blockquote>
<h3>2.2 <a name="extension"></a>XMPP Extension</h3>
<p>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 <a href='/council/'>XMPP Council</a>). 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.)</p>
</blockquote>
<blockquote>
<h3>2.3 <a name="implementation"></a>Implementation</h3>
<p>Any software that implements XMPP or XMPP Extensions for the purpose of providing the functionality defined by the relevant specification(s).</p>
</blockquote>
<blockquote>
<h3>2.4 <a name="claim"></a>Intellectual Property Claim</h3>
<p>Any patent, copyright, or other proprietary claim or claims made by an entity regarding a XMPP Extension. (Also referred to as a Claim.)</p>
</blockquote>
<h2>3. <a name="contributing"></a>Terms of Contributing an XMPP Extension</h2>
<p>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:</p>
<blockquote>
<h3>3.1 <a name="contrib-ownership"></a>Ownership</h3>
<p>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.</p>
</p>
<h3>3.3 <a name="contrib-approval"></a>Approval of Extensions</h3>
<p>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.</p>
<h3>3.3 <a name="contrib-private"></a>A Note about Private Extensions</h3>
<p>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.</p>
</blockquote>
<h2>5. <a name="legal"></a>Legal Notice</h2>
<p>All XMPP Extension Protocol (XEP) specifications shall contain the following Legal Notice:</p>
<blockquote><pre>
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 (&lt;http://www.xmpp.org/extensions/ipr-policy.shtml&gt;).
This material may be distributed only subject to the terms and
conditions set forth in the Creative Commons Attribution
License (&lt;http://creativecommons.org/by/2.5/&gt;).
</pre></blockquote>
<p><hr></p>
<h3>Notes</h3>
<p><a name="note1"></a>1. For information about XMPP Extension Protocols, see &lt;<a href="http://www.xmpp.org/extensions/">http://www.xmpp.org/extensions/</a>&gt; and <a href="http://www.xmpp.org/extensions/xep-0001.html">JEP-0001</a>.</p>
<p><a name="note2"></a>2. For information about intellectual property conservancies, see &lt;<a href="http://www.creativecommons.org/concepts/#ip">http://www.creativecommons.org/concepts/#ip</a>&gt; and M. van Houweling, "Cultivating Open Information Platforms: A Land Trust Model." <cite>Journal of Telecommunications &amp; High Technology Law</cite> 1, no. 1 (2002): 309-23.</p>
<h3>Acknowledgements</h3>
<p>Many thanks to Lawrence Lessig and Molly van Houweling for their assistance in formulating this policy.</p>
<h3>Changelog</h3>
<p>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).</p>
<p>Version 1.1 (2005-10-04): Replaced Open Publication License with Creative Commons Attribution License.</p>
<p>Version 1.0 (2002-10-29): Initial version approved by JSF Board of Directors.</p>
</div>
<!--#include virtual="/includes/foot.txt" -->

146
lastcall.py Executable file
View File

@ -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

73
protopage.xsl Normal file
View File

@ -0,0 +1,73 @@
<!-- Author: stpeter -->
<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'>
<xsl:output method='html'/>
<xsl:template match='/'>
<html>
<head>
<title><xsl:value-of select='/jep/header/shortname'/></title>
<link rel='stylesheet' type='text/css' href='/jeps/jep.css' />
<link rel='shortcut icon' type='image/x-icon' href='/favicon.ico' />
<link>
<xsl:attribute name='rel'><xsl:text>alternate</xsl:text></xsl:attribute>
<xsl:attribute name='href'><xsl:text>http://www.jabber.org/jeps/jep-</xsl:text><xsl:value-of select='/jep/header/number'/><xsl:text>.html</xsl:text></xsl:attribute>
</link>
<!-- BEGIN META TAGS FOR DUBLIN CORE -->
<meta>
<xsl:attribute name='name'><xsl:text>DC.Title</xsl:text></xsl:attribute>
<xsl:attribute name='content'><xsl:value-of select='/jep/header/shortname'/></xsl:attribute>
</meta>
<meta>
<xsl:attribute name='name'><xsl:text>DC.Publisher</xsl:text></xsl:attribute>
<xsl:attribute name='content'>Jabber Software Foundation</xsl:attribute>
</meta>
<meta>
<xsl:attribute name='name'><xsl:text>DC.Date</xsl:text></xsl:attribute>
<xsl:attribute name='content'><xsl:value-of select='/jep/header/revision/date'/></xsl:attribute>
</meta>
<!-- END META TAGS FOR DUBLIN CORE -->
</head>
<body>
<h1><xsl:value-of select='/jep/header/shortname'/></h1>
<p>This page provides information about the XML namespaces defined in
<a>
<xsl:attribute name='href'>
<xsl:text>http://www.jabber.org/jeps/jep-</xsl:text>
<xsl:value-of select='/jep/header/number'/>
<xsl:text>.html</xsl:text>
</xsl:attribute>
<xsl:text>JEP-</xsl:text><xsl:value-of select='/jep/header/number' />:<xsl:text> </xsl:text><xsl:value-of select='/jep/header/title' />
</a>
(part of the <a href="http://www.jabber.org/jeps/">JEP series</a> published by the <a href="http://www.jabber.org/jsf/">Jabber Software Foundation</a>).</p>
<xsl:variable name='schema.count' select='count(/jep/header/schemaloc)'/>
<xsl:if test='$schema.count &gt; 0'>
<p>The following XML schemas are available for the <xsl:value-of select='/jep/header/title' /> protocol:</p>
<ul>
<xsl:apply-templates select='/jep/header/schemaloc'/>
</ul>
</xsl:if>
<p>Last Updated: <xsl:value-of select='/jep/header/revision/date'/></p>
</body>
</html>
</xsl:template>
<xsl:template match='schemaloc'>
<xsl:variable name='this.url' select='url'/>
<xsl:variable name='ns.count' select='count(ns)'/>
<xsl:choose>
<xsl:when test="$ns.count &gt; 0">
<li><a href='{$this.url}'><xsl:value-of select='url'/></a></li>
</xsl:when>
<xsl:otherwise>
<li><a href='{$this.url}'><xsl:value-of select='url'/></a></li>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>

122
ref.xsl Normal file
View File

@ -0,0 +1,122 @@
<?xml version='1.0' encoding='UTF-8'?>
<!-- Author: stpeter
Description: transforms XEP meta-data into IETF reference
-->
<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'>
<xsl:output method='xml' indent='yes'/>
<xsl:template match='/'>
<reference>
<xsl:attribute name='anchor'><xsl:text>XEP-</xsl:text><xsl:value-of select='/xep/header/number'/></xsl:attribute>
<front>
<title><xsl:value-of select='/xep/header/title' /></title>
<xsl:apply-templates select='/xep/header/author'/>
<xsl:variable name='fulldate' select='/xep/header/revision[position()=1]/date'/>
<xsl:variable name='year' select='substring-before($fulldate,"-")'/>
<xsl:variable name='monthday' select='substring-after($fulldate,"-")'/>
<xsl:variable name='month' select='substring-before($monthday,"-")'/>
<xsl:variable name='day' select='substring-after($monthday,"-")'/>
<date>
<xsl:attribute name='day'><xsl:value-of select='$day'/></xsl:attribute>
<xsl:choose>
<xsl:when test='$month = "01"'>
<xsl:attribute name='month'><xsl:text>January</xsl:text></xsl:attribute>
</xsl:when>
<xsl:when test='$month = "02"'>
<xsl:attribute name='month'><xsl:text>February</xsl:text></xsl:attribute>
</xsl:when>
<xsl:when test='$month = "03"'>
<xsl:attribute name='month'><xsl:text>March</xsl:text></xsl:attribute>
</xsl:when>
<xsl:when test='$month = "04"'>
<xsl:attribute name='month'><xsl:text>April</xsl:text></xsl:attribute>
</xsl:when>
<xsl:when test='$month = "05"'>
<xsl:attribute name='month'><xsl:text>May</xsl:text></xsl:attribute>
</xsl:when>
<xsl:when test='$month = "06"'>
<xsl:attribute name='month'><xsl:text>June</xsl:text></xsl:attribute>
</xsl:when>
<xsl:when test='$month = "07"'>
<xsl:attribute name='month'><xsl:text>July</xsl:text></xsl:attribute>
</xsl:when>
<xsl:when test='$month = "08"'>
<xsl:attribute name='month'><xsl:text>August</xsl:text></xsl:attribute>
</xsl:when>
<xsl:when test='$month = "09"'>
<xsl:attribute name='month'><xsl:text>September</xsl:text></xsl:attribute>
</xsl:when>
<xsl:when test='$month = "10"'>
<xsl:attribute name='month'><xsl:text>October</xsl:text></xsl:attribute>
</xsl:when>
<xsl:when test='$month = "11"'>
<xsl:attribute name='month'><xsl:text>November</xsl:text></xsl:attribute>
</xsl:when>
<xsl:when test='$month = "12"'>
<xsl:attribute name='month'><xsl:text>December</xsl:text></xsl:attribute>
</xsl:when>
<xsl:otherwise>
<xsl:attribute name='month'><xsl:text></xsl:text></xsl:attribute>
</xsl:otherwise>
</xsl:choose>
<xsl:attribute name='year'><xsl:value-of select='$year'/></xsl:attribute>
</date>
</front>
<seriesInfo>
<xsl:attribute name='name'><xsl:text>JSF XEP</xsl:text></xsl:attribute>
<xsl:attribute name='value'><xsl:value-of select='/xep/header/number'/></xsl:attribute>
</seriesInfo>
<format>
<xsl:attribute name='type'><xsl:text>HTML</xsl:text></xsl:attribute>
<xsl:attribute name='target'><xsl:text>http://www.xmpp.org/extensions/xep-</xsl:text><xsl:value-of select='/xep/header/number'/><xsl:text>.html</xsl:text></xsl:attribute>
</format>
</reference>
</xsl:template>
<xsl:template match='author'>
<author>
<xsl:variable name='fname' select='firstname'/>
<xsl:choose>
<xsl:when test='starts-with($fname,"A")'><xsl:attribute name='initials'><xsl:text>A.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"B")'><xsl:attribute name='initials'><xsl:text>B.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"C")'><xsl:attribute name='initials'><xsl:text>C.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"D")'><xsl:attribute name='initials'><xsl:text>D.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"E")'><xsl:attribute name='initials'><xsl:text>E.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"F")'><xsl:attribute name='initials'><xsl:text>F.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"G")'><xsl:attribute name='initials'><xsl:text>G.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"H")'><xsl:attribute name='initials'><xsl:text>H.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"I")'><xsl:attribute name='initials'><xsl:text>I.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"J")'><xsl:attribute name='initials'><xsl:text>J.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"K")'><xsl:attribute name='initials'><xsl:text>K.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"L")'><xsl:attribute name='initials'><xsl:text>L.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"M")'><xsl:attribute name='initials'><xsl:text>M.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"N")'><xsl:attribute name='initials'><xsl:text>N.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"O")'><xsl:attribute name='initials'><xsl:text>O.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"P")'><xsl:attribute name='initials'><xsl:text>P.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"Q")'><xsl:attribute name='initials'><xsl:text>Q.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"R")'><xsl:attribute name='initials'><xsl:text>R.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"S")'><xsl:attribute name='initials'><xsl:text>S.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"T")'><xsl:attribute name='initials'><xsl:text>T.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"U")'><xsl:attribute name='initials'><xsl:text>U.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"V")'><xsl:attribute name='initials'><xsl:text>V.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"W")'><xsl:attribute name='initials'><xsl:text>W.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"X")'><xsl:attribute name='initials'><xsl:text>X.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"Y")'><xsl:attribute name='initials'><xsl:text>Y.</xsl:text></xsl:attribute></xsl:when>
<xsl:when test='starts-with($fname,"Z")'><xsl:attribute name='initials'><xsl:text>Z.</xsl:text></xsl:attribute></xsl:when>
<xsl:otherwise>
<xsl:attribute name='initals'><xsl:text></xsl:text></xsl:attribute>
</xsl:otherwise>
</xsl:choose>
<xsl:attribute name='surname'><xsl:value-of select='surname'/></xsl:attribute>
<xsl:attribute name='fullname'><xsl:value-of select='firstname'/><xsl:text> </xsl:text><xsl:value-of select='surname'/></xsl:attribute>
<organization/>
<address>
<email><xsl:value-of select='email'/></email>
</address>
</author>
</xsl:template>
</xsl:stylesheet>

15
submit.shtml Executable file
View File

@ -0,0 +1,15 @@
<html>
<head>
<title>How to Submit an XMPP Extension Protocol</title>
<!--#include virtual="/includes/head.txt" -->
<h2>How to Submit an XMPP Extension Protocol</h2>
<p>Here is how to submit a proposal to the Jabber Software Foundation for consideration as an XMPP Extension Protocol:</p>
<ol>
<li><p>Contact the <a href="editor.shtml">XMPP Extensions Editor</a> so that he knows to expect your submission.</p></li>
<li><p>Write your proposal following the guidelines described in <a href="/extensions/xep-0143.html">XEP-0143: Guidelines for Authors of XMPP Extension Protocols</a>.</p></li>
<li>Make sure you read, understand, and agree to the JSF's <a href="/extensions/ipr-policy.shtml">IPR Policy</a> before you submit your proposal!</li>
<li><p>Email the XML file (or a URL for the file) to the <a href="editor.shtml">XMPP Extensions Editor</a> with a subject line of "ProtoJEP: [your title here]".</li>
</ol>
<p><strong>Note:</strong> It is the author's responsibility to provide a properly-formatted source file (see the <a href='template.xml'>template</a> and <a href='http://www.jabberstudio.org/cgi-bin/viewcvs.cgi/jeps/'>CVS repository</a>). Proposals submitted in HTML, TXT, MS Word, Open Document Format, etc. will be returned to the proposal author for proper formatting.</p>
</div>
<!--#include virtual="/includes/foot.txt" -->

688
xep-0001.xml Normal file
View File

@ -0,0 +1,688 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Jabber Enhancement Proposals (JEPs)</title>
<abstract>This document defines the standards process followed by the Jabber Software Foundation.</abstract>
&LEGALNOTICE;
<number>0001</number>
<status>Active</status>
<type>Procedural</type>
<jig>None</jig>
<approver>Board</approver>
<dependencies/>
<supersedes/>
<supersededby/>
<shortname>N/A</shortname>
&stpeter;
<revision>
<version>1.16</version>
<date>2006-06-23</date>
<initials>psa</initials>
<remark><p>Clarified and simplified the state charts based on implementation experience; summarized state definitions.</p></remark>
</revision>
<revision>
<version>1.15</version>
<date>2004-11-02</date>
<initials>psa</initials>
<remark><p>Specified that a Standards Track JEP defines either (1) a wire protocol or (2) a protocol suite.</p></remark>
</revision>
<revision>
<version>1.14</version>
<date>2004-09-28</date>
<initials>psa</initials>
<remark><p>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.</p></remark>
</revision>
<revision>
<version>1.13</version>
<date>2004-08-24</date>
<initials>psa</initials>
<remark><p>Further specified the goals of the JEP process; mentioned Board-approved JEPs.</p></remark>
</revision>
<revision>
<version>1.11</version>
<date>2004-07-14</date>
<initials>psa</initials>
<remark><p>Specified the procedure for changing a JEP from Historical to Standards Track.</p></remark>
</revision>
<revision>
<version>1.10</version>
<date>2004-03-24</date>
<initials>psa</initials>
<remark><p>Specified the procedure for acceptance of a proposal as a JEP; clarified the JEP types; completed editorial review.</p></remark>
</revision>
<revision>
<version>1.9</version>
<date>2003-12-22</date>
<initials>psa</initials>
<remark><p>Added rule about automatic deferral of inactive JEPs.</p></remark>
</revision>
<revision>
<version>1.8</version>
<date>2003-10-06</date>
<initials>psa</initials>
<remark><p>Clarified the definition of informational JEP.</p></remark>
</revision>
<revision>
<version>1.7</version>
<date>2003-04-11</date>
<initials>psa</initials>
<remark><p>Added status of Retracted; corrected several errors related to the Jabber Registrar.</p></remark>
</revision>
<revision>
<version>1.6</version>
<date>2003-01-08</date>
<initials>psa</initials>
<remark><p>Further clarified the proposal process per discussion on the JSF members list.</p></remark>
</revision>
<revision>
<version>1.5</version>
<date>2002-10-29</date>
<initials>psa</initials>
<remark><p>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.</p></remark>
</revision>
<revision>
<version>1.4</version>
<date>2002-01-16</date>
<initials>psa</initials>
<remark><p>Added information about the new "Experimental" state for Standards Track JEPs and made appropriate changes to the JEP process.</p></remark>
</revision>
<revision>
<version>1.3.1</version>
<date>2002-01-11</date>
<initials>psa</initials>
<remark><p>Added link to DTD.</p></remark>
</revision>
<revision>
<version>1.3</version>
<date>2001-10-23</date>
<initials>psa</initials>
<remark><p>(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.</p></remark>
</revision>
<revision>
<version>1.2</version>
<date>2001-09-27</date>
<initials>psa</initials>
<remark><p>(1) Added information about expiration dates; (2) Added a status of Deprecated to Standards Track JEPs.</p></remark>
</revision>
<revision>
<version>1.1</version>
<date>2001-09-09</date>
<initials>psa</initials>
<remark><p>(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.</p></remark>
</revision>
<revision>
<version>1.0</version>
<date>2001-07-09</date>
<initials>psa</initials>
<remark><p>Changed status to Active.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2001-06-28</date>
<initials>psa</initials>
<remark><p>Initial release -- a simplified and updated version of Rahul Dave's Jabberization of the process and format for Python Enhancement Proposals</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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, <note>Effectively the only such exceptions are protocols that were superseded by <cite>RFC 3920</cite> and <cite>RFC 3921</cite>.</note> such protocols can be considered extensions to the Extensible Messaging and Presence Protocol (XMPP) approved by the &IETF; in &xmppcore; and &xmppim;. Advancement through the JSF's standards process is subject to open discussion on public discussion lists and approval by a technical steering committee elected by the members of the JSF. The focal point of the process is a series of protocol specifications called Jabber Enhancement Proposals or JEPs. <note>The JEP concept as exemplified in version 1.0 of this document (approved in July of 2001) was borrowed from the Python community (see <link url="http://python.sourceforge.net/peps/pep-0001.html">PEP-1</link>). Subsequent revisions have been based on the Jabber/XMPP developer community's experience with the JEP process, as well as insights gleaned from the standards processes followed by the IETF (&rfc2026;), the &W3C; (&w3process;), and other standards development organizations.</note> The nature of JEPs and the mechanisms for managing and advancing them within the Jabber Software Foundation's standards process are canonically described in the current document, which represents the first document in the JEP series.</p>
</section1>
<section1 topic='Objectives' anchor='objectives'>
<p>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:</p>
<ol start='1'>
<li>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.</li>
<li>To document Jabber protocols and XMPP extensions in a clear, concise manner so that the task of implementing the protocols is straightforward.</li>
<li>To ensure interoperability among the disparate technologies used on Jabber/XMPP networks.</li>
<li>To guarantee that any person or entity may implement the protocols without encumbrance.</li>
<li>To work in an fair, open, objective manner.</li>
</ol>
<p>The standards process specified herein has been developed and refined in order to meet these objectives.</p>
</section1>
<section1 topic='JEP Types' anchor='types'>
<p>The five JEP types are described in the following sections.</p>
<p>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.</p>
<p>This document focuses primarily on Standards Track JEPs since they are the vehicle for defining new protocols, but also discusses the other JEP types.</p>
<section2 topic='Standards Track' anchor='types-Standards-Track'>
<p>A <span class='ref'>Standards Track JEP</span> defines one of the following:</p>
<ol>
<li>A wire protocol intended to be used as a standard part of Jabber/XMPP technologies.
<note>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).</note>
</li>
<li>A protocol suite that determines conformance requirements (e.g., &jep0073;).</li>
</ol>
</section2>
<section2 topic='Informational' anchor='types-Informational'>
<p>An <span class='ref'>Informational JEP</span> defines one of the following:</p>
<ol start='1'>
<li>Best practices for protocol development (e.g., &jep0128;).</li>
<li>A usage profile for an existing protocol (e.g., &jep0126;).</li>
</ol>
</section2>
<section2 topic='Historical' anchor='types-Historical'>
<p>An <span class='ref'>Historical JEP</span> 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.</p>
</section2>
<section2 topic='Humorous' anchor='types-Humorous'>
<p>A <span class='ref'>Humorous JEP</span> 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.</p>
</section2>
<section2 topic='Procedural' anchor='types-Procedural'>
<p>A <span class='ref'>Procedural JEP</span> defines a process or activity to be followed by the JSF, including JIG charters as specified by &jep0002;.</p>
</section2>
</section1>
<section1 topic='Submission Process' anchor='submission'>
<p>The JSF welcomes and encourages the submission of protocols to the JSF's standards process. <note>It is important to understand that private extensions to XMPP are also allowed. The JSF does not, and cannot, require such private extensions to be added to the public, official set of protocols recognized by the JSF. The processes and procedures in this document apply only to protocols that are submitted to the JSF, not to private protocol extensions used for custom functionality in particular applications. However, such private extensions must not be considered part of the protocols recognized by the JSF.</note> Any individual or group of individuals may author a proposal and submit it to the JSF for consideration as a JEP, and there is no requirement that a JEP author shall be an elected member of the JSF. However, proposals to define official JSF protocols must be presented in the JEP format and must follow the rules defined herein. The JEP authoring and submission process is defined in &jep0143; (see also &lt;<link url="http://www.jabber.org/jeps/submit.shtml">http://www.jabber.org/jeps/submit.shtml</link>&gt;). All inquiries related to the JEP process, and all submissions, should be directed to the &EDITOR;.</p>
<p>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!</p>
<p>All proposals submitted to the JSF for consideration as JEPs must contain the following information:</p>
<ol start='1'>
<li><p>Legal Notice -- the legal notice must be exactly that which is specified in the JSF IPR Policy</p></li>
<li><p>Author Information -- first name, last name, email address, and Jabber ID are all required and must be provided for all authors</p></li>
</ol>
<p>Finally, Standards Track, Informational, and Historical JEPs must conform to &rfc2119; in the use of terminology regarding requirements levels.</p>
</section1>
<section1 topic='Publication Process' anchor='publication'>
<p>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:</p>
<ul>
<li>ensure that its format is correct</li>
<li>publish it to &lt;<link url='http://www.jabber.org/jeps/inbox/'>http://www.jabber.org/jeps/inbox/</link>&gt;</li>
<li>publicly announce its existence by sending a message to the discussion list of the &SJIG;</li>
<li>request acceptance of the proposal as a JEP by the Jabber Council</li>
</ul>
<p>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.</p>
<p>If the proposal is accepted as a JEP, the JEP Editor shall do the following:</p>
<ul>
<li>assign it a number</li>
<li>specify an appropriate type</li>
<li>specify a status of Experimental</li>
<li>add it to source control <note>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 &lt;<link url='http://www.jabberstudio.org/cvs.php'>http://www.jabberstudio.org/cvs.php</link>&gt;, and a web interface to these files is available at &lt;<link url='http://www.jabberstudio.org/cgi-bin/viewcvs.cgi/jeps/'>http://www.jabberstudio.org/cgi-bin/viewcvs.cgi/jeps/</link>&gt;.</note></li>
<li>add tracking information to the JEPs database</li>
<li>publish version 0.1 of the JEP to the JSF website <note>The canonical URL for accessing JEPs is &lt;<link url='http://www.jabber.org/jeps/'>http://www.jabber.org/jeps/</link>&gt;.</note></li>
<li>publicly announce the existence of the JEP by sending a message to the Standards-JIG list</li>
</ul>
<p>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.</p>
</section1>
<section1 topic='Discussion Process' anchor='discussion'>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Proposal Process' anchor='proposal'>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Approval Process' anchor='approval'>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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 <note>A list of official JSF protocols is maintained at &lt;<link url='http://www.jabber.org/protocol/'>http://www.jabber.org/protocol</link>&gt;.</note> on the website of the Jabber Software Foundation.</p>
<p>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;.</p>
<p>More detailed information about the approval process is provided below, including criteria for Standards Track JEPs and for Historical, Informational, and Procedural JEPs.</p>
<section2 topic='Standards Track JEPs' anchor='approval-std'>
<p>The possible states for a Standards Track JEP are as follows:</p>
<code>
+--> Retracted
|
|
+--> Deferred +--> Rejected
| |
| |
Experimental ----> Proposed ----> Draft ----> Final
| |
| |
+-----------+---> Deprecated ---> Obsolete
</code>
<p>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.</p>
<p>In order for a Standards Track JEP to advance from Proposed to Draft, it must:</p>
<ol>
<li>fill known gaps in Jabber/XMPP technologies or deficiencies with existing protocols</li>
<li>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</li>
<li>document any known security considerations with the proposed technology</li>
<li>be generally stable and appropriate for further field experience</li>
<li>have achieved rough consensus (though not necessarily unanimity) within the Standards JIG</li>
<li>be formally defined by an XML schema</li>
<li>receive the requisite votes from the Jabber Council</li>
</ol>
<p>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 &lt;<link url='http://www.jabber.org/jeps/tmp/'>http://www.jabber.org/jeps/tmp/</link>&gt;, 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.</p>
<p>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.</p>
<p>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 <link url='#expiration'>Expiration Dates</link> 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.</p>
</section2>
<section2 topic='Historical, Informational, and Procedural JEPs' anchor='approval-info'>
<p>The possible states for a Historical, Informational, or Procedural JEP are as follows:</p>
<code>
+--> Retracted
|
|
+--> Deferred +--> Rejected
| |
| |
Experimental ----> Proposed ----> Active
|
|
+--> Deprecated --> Obsolete
</code>
<p>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.</p>
<p>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.</p>
<p>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 <link url="#proposal">Proposal Process</link>. 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.</p>
</section2>
</section1>
<section1 topic='Summary of JEP States' anchor='states'>
<p>The possible states for a JEP are summarized in the following sections.</p>
<section2 topic='Experimental' anchor='states-Experimental'>
<p>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.</p>
</section2>
<section2 topic='Proposed' anchor='states-Proposed'>
<p>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.</p>
</section2>
<section2 topic='Draft' anchor='states-Draft'>
<p>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.</p>
</section2>
<section2 topic='Final' anchor='states-Final'>
<p>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.</p>
</section2>
<section2 topic='Active' anchor='states-Active'>
<p>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.</p>
</section2>
<section2 topic='Deferred' anchor='states-Deferred'>
<p>An Experimental JEP of any type is changed to the Deferred state if it has not been updated in six (6) months.</p>
</section2>
<section2 topic='Retracted' anchor='states-Retracted'>
<p>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.</p>
</section2>
<section2 topic='Rejected' anchor='states-Rejected'>
<p>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.</p>
</section2>
<section2 topic='Deprecated' anchor='states-Deprecated'>
<p>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).</p>
</section2>
<section2 topic='Obsolete' anchor='states-Obsolete'>
<p>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.</p>
</section2>
</section1>
<section1 topic='Modification of Final and Active JEPs' anchor='mods'>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Expiration Dates' anchor='expiration'>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>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.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>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.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<p>The &REGISTRAR; 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;).</p>
<p>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;.</p>
<p>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.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>JEPs that define official JSF protocols must include a schema that conforms to &w3xmlschema1; and &w3xmlschema2;.</p>
<p>The schema for the JEP format itself is as follows:</p>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://www.jabber.org/jeps'
xmlns='http://www.jabber.org/jeps'
elementFormDefault='qualified'>
<xs:element name='jep'>
<xs:annotation>
<xs:documentation>
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
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element ref='header'/>
<xs:element ref='section1' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='header'>
<xs:complexType>
<xs:sequence>
<xs:element name='title' type='xs:string'/>
<xs:element name='abstract' type='xs:string'/>
<xs:element name='legal' type='xs:string'/>
<xs:element name='number' type='xs:byte'/>
<xs:element ref='status'/>
<xs:element ref='type'/>
<xs:element name='jig' type='xs:string'/>
<xs:element name='approver' type='xs:string'/>
<xs:element ref='dependencies'/>
<xs:element ref='supersedes'/>
<xs:element ref='supersededby'/>
<xs:element name='shortname' type='xs:NCNAME'/>
<xs:element ref='schemaloc' minOccurs='0' maxOccurs='unbounded'/>
<xs:element name='registry' type='empty' minOccurs='0'/>
<xs:element name='expires' type='xs:string'/>
<xs:element ref='author' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='revision' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='status'>
<xs:simpleType>
<xs:restriction base='xs:NCNAME'>
<xs:enumeration value='Active'/>
<xs:enumeration value='Deferred'/>
<xs:enumeration value='Deprecated'/>
<xs:enumeration value='Draft'/>
<xs:enumeration value='Experimental'/>
<xs:enumeration value='Final'/>
<xs:enumeration value='Obsolete'/>
<xs:enumeration value='Proposed'/>
<xs:enumeration value='ProtoJEP'/>
<xs:enumeration value='Rejected'/>
<xs:enumeration value='Retracted'/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name='type'>
<xs:simpleType>
<xs:restriction base='xs:string'>
<xs:enumeration value='Historical'/>
<xs:enumeration value='Humorous'/>
<xs:enumeration value='Informational'/>
<xs:enumeration value='Organizational'/>
<xs:enumeration value='Standards Track'/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name='dependencies'>
<xs:complexType>
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
<xs:element name='spec' type='xs:string'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='supersedes'>
<xs:complexType>
<xs:sequence>
<xs:element name='spec' type='xs:string'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='supersededby'>
<xs:complexType>
<xs:sequence>
<xs:element name='spec' type='xs:string'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='schemaloc'>
<xs:complexType>
<xs:sequence>
<xs:element name='ns' type='xs:string' minOccurs='0'/>
<xs:element name='url' type='xs:string'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='author'>
<xs:complexType>
<xs:sequence>
<xs:element name='firstname' type='xs:string'/>
<xs:element name='surname' type='xs:string'/>
<xs:element name='authornote' type='empty' minOccurs='0'/>
<xs:element name='org' type='xs:string' minOccurs='0'/>
<xs:element name='email' type='xs:string'/>
<xs:element name='jid' type='xs:string' minOccurs='0'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='revision'>
<xs:complexType>
<xs:sequence>
<xs:element name='version' type='xs:string'/>
<xs:element name='date' type='xs:dateTime'/>
<xs:element name='initials' type='xs:NCName'/>
<xs:element ref='remark'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='remark'>
<xs:complexType>
<xs:choice>
<xs:element ref='p' minOccurs='0' maxOccurs='1'/>
<xs:element ref='ul' minOccurs='0' maxOccurs='1'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name='section1'>
<xs:complexType>
<xs:choice maxOccurs='unbounded'>
<xs:element ref='div' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='p' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='section2' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='example' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='code' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='ul' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='ol' minOccurs='0' maxOccurs='unbounded'/>
</xs:choice>
<xs:attribute name='topic' type='xs:string' use='required'/>
<xs:attribute name='anchor' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='section2'>
<xs:complexType>
<xs:choice maxOccurs='unbounded'>
<xs:element ref='div' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='p' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='section3' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='example' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='code' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='ul' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='ol' minOccurs='0' maxOccurs='unbounded'/>
</xs:choice>
<xs:attribute name='topic' type='xs:string' use='required'/>
<xs:attribute name='anchor' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='section3'>
<xs:complexType>
<xs:choice maxOccurs='unbounded'>
<xs:element ref='div' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='p' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='section4' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='example' minOccurs='0' maxOccurs='unbounded'/>
<xs:element name='code' type='xs:string' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='ul' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='ol' minOccurs='0' maxOccurs='unbounded'/>
</xs:choice>
<xs:attribute name='topic' type='xs:string' use='required'/>
<xs:attribute name='anchor' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='section4'>
<xs:complexType>
<xs:choice maxOccurs='unbounded'>
<xs:element ref='div' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='p' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='example' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='code' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='ul' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='ol' minOccurs='0' maxOccurs='unbounded'/>
</xs:choice>
<xs:attribute name='topic' type='xs:string' use='required'/>
<xs:attribute name='anchor' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='div'>
<xs:complexType>
<xs:choice maxOccurs='unbounded'>
<xs:element ref='div' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='p' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='example' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='code' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='ul' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='ol' minOccurs='0' maxOccurs='unbounded'/>
</xs:choice>
<xs:attribute name='class' type='xs:string' use='optional'/>
<xs:attribute name='style' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='p' type='markup'/>
<xs:element name='ul'>
<xs:complexType>
<xs:sequence>
<xs:element ref='li' minOccurs='1' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='ol'>
<xs:complexType>
<xs:sequence>
<xs:element ref='li' minOccurs='1' maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='start' type='xs:byte' use='optional'/>
<xs:attribute name='type' type='xs:NCName' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='li' type='markup'/>
<xs:element name='img'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='source' use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='link'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='url' use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='note' type='markup'/>
<xs:element name='example'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='caption' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='code'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='caption' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='table'>
<xs:complexType>
<xs:sequence>
<xs:element ref='tr' minOccurs='1' maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='caption' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='tr'>
<xs:complexType>
<xs:choice>
<xs:element ref='th' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='td' minOccurs='0' maxOccurs='unbounded'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name='th'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='colspan' use='optional'/>
<xs:attribute name='rowspan' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='td'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='colspan' use='optional'/>
<xs:attribute name='rowspan' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:complexType name='markup' type='mixed'>
<xs:choice minOccurs='0' maxOccurs='unbounded'>
<xs:element name='cite' type='xs:token'/>
<xs:element name='em' type='xs:token'/>
<xs:element ref='img'/>
<xs:element ref='link'/>
<xs:element ref='note'/>
<xs:element name='span' type='xs:token'/>
<xs:element name='strong' type='xs:token'/>
<xs:element name='tt' type='xs:token'/>
</xs:choice>
<xs:attribute name='class' type='xs:string' use='optional'/>
<xs:attribute name='style' type='xs:string' use='optional'/>
</xs:complexType>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
</jep>

42
xep-0002.xml Normal file
View File

@ -0,0 +1,42 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Jabber Interest Groups (JIGs)</title>
<abstract>A definition of Jabber Interest Groups, including their structure and role within the Jabber Software Foundation.</abstract>
&LEGALNOTICE;
<number>0002</number>
<status>Active</status>
<type>Procedural</type>
<jig>None</jig>
<approver>Board</approver>
<dependencies/>
<supersedes/>
<supersededby/>
&stpeter;
<revision>
<version>1.1</version>
<date>2002-01-11</date>
<initials>psa</initials>
<remark>Clarified some details and added information about cut-offs for inactivity.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2001-06-28</date>
<initials>psa</initials>
<remark>First release, modified from Rahul Dave's modification of my original post.</remark>
</revision>
</header>
<section1 topic='Short Definition'>
<p>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).</p>
</section1>
<section1 topic='Explanation'>
<p>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 <note>For information about Jabber Enhancement Proposals, see <link url="http://foundation.jabber.org/jeps/jep-0001.html">http://foundation.jabber.org/jeps/jep-0001.html</link>.</note>) within a reasonably limited period of time. However, at the discretion of the Jabber Council, a handful of standing JIGs may be approved (e.g., to address security or standards compliance).</p>
<p>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.</p>
<p>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).</p>
</section1>
</jep>

347
xep-0003.xml Normal file
View File

@ -0,0 +1,347 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Proxy Accept Socket Service (PASS)</title>
<abstract>A proposal for proxy support in Jabber.</abstract>
&LEGALNOTICE;
<number>0003</number>
<status>Active</status>
<type>Historical</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>pass</shortname>
<schemaloc>
<url>http://jabber.org/protocol/pass/pass.xsd</url>
</schemaloc>
&jer;
&reatmon;
<revision>
<version>1.2</version>
<date>2004-01-22</date>
<initials>psa</initials>
<remark>Editorial revisions.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2004-01-06</date>
<initials>psa</initials>
<remark>Added XML schema.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-10-15</date>
<initials>psa</initials>
<remark>Changed status to Active.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2001-07-02</date>
<initials>rwe</initials>
<remark>Error codes update</remark>
</revision>
<revision>
<version>0.3</version>
<date>2001-06-29</date>
<initials>rwe</initials>
<remark>Protocol update</remark>
</revision>
<revision>
<version>0.2</version>
<date>2001-06-28</date>
<initials>psa</initials>
<remark>DocBook version</remark>
</revision>
<revision>
<version>0.1</version>
<date>2001-06-01</date>
<initials>jer</initials>
<remark>Initial release</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
</section1>
<section1 topic='Registration/Setup'>
<p>The first step is to communicate with a PASS service to set it up.</p>
<example caption='Registration request'>
&#60;iq id='pass1' type='set' to='pass.jabber.org'&#62;
&#60;query xmlns='jabber:iq:pass'&#62;
&#60;expire&#62;600&#60;/expire&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<example caption='Result from PASS Service'>
&#60;iq id='pass1' type='result' from='pass.jabber.org'&#62;
&#60;query xmlns='jabber:iq:pass'&#62;
&#60;server port='43253'&#62;1.2.3.4&#60;/server&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<p>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.</p>
<p>The default behavior for the PASS service is to listen on the port forever, unless the requesting client specifies an &lt;expire/&gt; 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.</p>
<table caption='Error Codes'>
<tr>
<th>Code</th>
<th>Message</th>
<th>Cause</th>
</tr>
<tr>
<td>502</td>
<td>No more ports available. Try again later.</td>
<td>The PASS service is listening on all of its available ports.</td>
</tr>
</table>
</section1>
<section1 topic='Incoming Connections'>
<p>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:</p>
<example caption='Request to entity'>
&#60;iq type='set'
id='pass2'
to='user@jabber.org/resource'
from='pass.jabber.org'&#62;
&#60;query xmlns='jabber:iq:pass'&#62;
&#60;client port='1234'&#62;4.3.2.1&#60;/client&#62;
&#60;proxy port='43523'&#62;1.2.3.4&#60;/proxy&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<example caption='IQ result to accept connection'>
&#60;iq type='result'
id='pass2'
from='user@jabber.org/resource'
to='pass.jabber.org'&#62;
&#60;query xmlns='jabber:iq:pass'/&#62;
&#60;/iq&#62;
</example>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Controls'>
<p>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.</p>
<section2 topic='&#60;expire/&#62;'>
<p>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 &#60;iq/&#62; to the JID to tell it that the port has been closed down. It notifies the client with:</p>
<example caption='Notification of expiration'>
&#60;iq type='set'
id='pass3'
to='user@jabber.org/resource'
from='pass.jabber.org'&#62;
&#60;query xmlns='jabber:iq:pass'&#62;
&#60;expire/&#62;
&#60;close/&#62;
&#60;proxy port='43253'&#62;1.2.3.4&#60;/proxy&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<example caption='Acknowledgement of expiration'>
&#60;iq type='result'
id='pass3'
from='user@jabber.org/resource'
to='pass.jabber.org'&#62;
&#60;query xmlns='jabber:iq:pass'/&#62;
&#60;/iq&#62;
</example>
</section2>
<section2 topic='&#60;oneshot/&#62;'>
<p>This tells the server to listen once, and then close the port. Even if the &#60;expire/&#62; has not been met, the &#60;oneshot/&#62; overrides that and shuts down the listening port. When this happens the server notifies the client with the following packet:</p>
<example caption='Server notifies client of oneshot port closing'>
&#60;iq type='set'
id='pass4'
to='user@jabber.org/resource'
from='pass.jabber.org'&#62;
&#60;query xmlns='jabber:iq:pass'&#62;
&#60;oneshot/&#62;
&#60;close/&#62;
&#60;proxy port='43253'&#62;1.2.3.4&#60;/proxy&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<example caption='Client acknowledges closing of oneshot port'>
&#60;iq type='result'
id='pass4'
from='user@jabber.org/resource'
to='pass.jabber.org'&#62;
&#60;query xmlns='jabber:iq:pass'/&#62;
&#60;/iq&#62;
</example>
</section2>
<section2 topic='&#60;close/&#62;'>
<p>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:</p>
<example caption='Client request to shut down port'>
&#60;iq type='set'
id='pass5'
to='pass.jabber.org'
from='user@jabber.org/resource'&#62;
&#60;query xmlns='jabber:iq:pass'&#62;
&#60;close/&#62;
&#60;proxy port='43253'&#62;1.2.3.4&#60;/proxy&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<example caption='Server acknowledges port closing request'>
&#60;iq type='result'
id='pass5'
to='user@jabber.org/resource'
from='pass.jabber.org'&#62;
&#60;query xmlns='jabber:iq:pass'/&#62;
&#60;/iq&#62;
</example>
<table caption='Error Codes'>
<tr>
<th>Code</th>
<th>Message</th>
<th>Cause</th>
</tr>
<tr>
<td>400</td>
<td>Missing &#60;proxy/&#62; specification.</td>
<td>Sent a &#60;close/&#62; w/o a &#60;proxy/&#62;</td>
</tr>
<tr>
<td>401</td>
<td>Port not registered to your JID.</td>
<td>You did not register this port with the server.</td>
</tr>
<tr>
<td>404</td>
<td>Port not found in registry.</td>
<td>The &#60;proxy port=''/&#62; was not a defined port.</td>
</tr>
<tr>
<td>405</td>
<td>Proxy IP does not match.</td>
<td>The IP sent in the &#60;proxy/&#62; does not match the IP of the pass-service</td>
</tr>
</table>
</section2>
</section1>
<section1 topic='Security Considerations'>
<section2 topic='Client Authentication'>
<p>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:</p>
<p>You send the other client:</p>
<example>
&#60;iq type='get'
id='pass6'
to='them@jabber.org/resource'
from='you@jabber.org/resource'&#62;
&#60;query xmlns='jabber:iq:pass'/&#62;
&#60;/iq&#62;
</example>
<p>The other client SHOULD send back:</p>
<example>
&#60;iq type='result'
id='pass6'
to='you@jabber.org/resource'
from='them@jabber.org/resource'&#62;
&#60;query xmlns='jabber:iq:pass'&#62;
&#60;client&#62;4.3.2.1&#60;/client&#62;
&#60;query&#62;
&#60;/iq&#62;
</example>
<p>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 &#60;client/&#62; information upon a connection.</p>
</section2>
<section2 topic='Denying a Connection'>
<p>When a server gets an Incoming Connection notification the client has the right to deny that connection based on the &#60;client/&#62; information that it receives. It can return an error to the PASS service specifying the &#60;proxy/&#62; port and hangup on the active &#60;client/&#62; connection and start listening again. This does not affect the &#60;oneshot/&#62; control. For example:</p>
<p>The PASS service sends you:</p>
<example>
&#60;iq type='set'
id='pass7'
to='user@jabber.org/resource'
from='pass.jabber.org'&#62;
&#60;query xmlns='jabber:iq:pass'&#62;
&#60;client port='1234'&#62;4.3.2.1&#60;/client&#62;
&#60;proxy port='43523'&#62;1.2.3.4&#60;/proxy&#62;
&#60;query&#62;
&#60;/iq&#62;
</example>
<p>Your client would send back:</p>
<example>
&#60;iq type='error'
id='pass7'
to='pass.jabber.org'
from='user@jabber.org/resource'&#62;
&#60;query xmlns='jabber:iq:pass'&#62;
&#60;client port='1234'&#62;4.3.2.1&#60;/client&#62;
&#60;proxy port='43523'&#62;1.2.3.4&#60;/proxy&#62;
&#60;query&#62;
&#60;error code='401' type='auth'&#62;
&#60;not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/&gt;
&#60;/error&#62;
&#60;/iq&#62;
</example>
<table caption='Error Codes'>
<tr>
<th>Code</th>
<th>Message</th>
<th>Cause</th>
</tr>
<tr>
<td>401</td>
<td>Unauthorized</td>
<td>The incoming &#60;client/&#62; does not match the &#60;client/&#62; from the client you want to exchange data with.</td>
</tr>
</table>
</section2>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<p>No action on the part of the &REGISTRAR; is necessary as a result of this JEP, since 'jabber:iq:pass' is already a registered protocol namespace.</p>
</section1>
<section1 topic='XML Schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:iq:pass'
xmlns='jabber:iq:pass'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0003: http://www.jabber.org/jeps/jep-0003.html
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:choice minOccurs='0' maxOccurs='unbounded'>
<xs:element name='client' type='PassEntity'/>
<xs:element name='close' type='empty'/>
<xs:element name='expire' type='xs:unsignedLong'/>
<xs:element name='oneshot' type='empty'/>
<xs:element name='proxy' type='PassEntity'/>
<xs:element name='server' type='PassEntity'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:complexType name='PassEntity'>
<xs:simpleContent>
<xs:extension base='xs:NMTOKEN'>
<xs:attribute name='port' type='xs:short' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
</jep>

709
xep-0004.xml Normal file
View File

@ -0,0 +1,709 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Data Forms</title>
<abstract>This JEP defines a protocol for data forms and generic data description in Jabber/XMPP.</abstract>
&LEGALNOTICE;
<number>0004</number>
<status>Final</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>x-data</shortname>
<schemaloc>
<url>http://jabber.org/protocol/x-data/x-data.xsd</url>
</schemaloc>
&reatmon;
&hildjj;
&jer;
&temas;
&stpeter;
<revision>
<version>2.7</version>
<date>2006-01-25</date>
<initials>psa</initials>
<remark>Incorporated errata: (1) clarified rules regarding inclusion of option and value elements depending on field type; (2) clarified handling of default values; (3) added value elements to list-multi field in Example 2; (4) harmonized spelling of form-processing entity and form-submitting entity.</remark>
</revision>
<revision>
<version>2.6</version>
<date>2004-10-13</date>
<initials>psa</initials>
<remark>Incorporated errata: (1) corrected syntax of &lt;reported/&gt; element (&lt;field/&gt; element should not contain a &lt;value/&gt; child); (2) corrected Example 8.</remark>
</revision>
<revision>
<version>2.5</version>
<date>2004-05-07</date>
<initials>psa</initials>
<remark>Clarified terminology regarding form-processing entities and form-submitting entities; corrected several small errors in the schema.</remark>
</revision>
<revision>
<version>2.4</version>
<date>2004-05-04</date>
<initials>psa</initials>
<remark>Per discussion by the JEP authors and Jabber Council, specified that the 'var' attribute is required for all field types except "fixed", for which the 'var' attribute is optional.</remark>
</revision>
<revision>
<version>2.3</version>
<date>2004-03-31</date>
<initials>psa</initials>
<remark>Formalization and further editorial revisions.</remark>
</revision>
<revision>
<version>2.2</version>
<date>2004-01-22</date>
<initials>psa</initials>
<remark>Editorial revisions.</remark>
</revision>
<revision>
<version>2.1</version>
<date>2003-02-16</date>
<initials>psa</initials>
<remark>Added schema.</remark>
</revision>
<revision>
<version>2.0</version>
<date>2002-12-09</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, changed status to Final.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2002-10-15</date>
<initials>rwe</initials>
<remark>Call for Experience changes (see <link url="#draft-to-final">Changes Between Draft and Final</link> section). This version voted to Final on 2002-12-09.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-04-24</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, changed status to Draft.</remark>
</revision>
<revision>
<version>0.6</version>
<date>2002-03-15</date>
<initials>rwe</initials>
<remark>Protocol tweaks based on standards-jig discussion.</remark>
</revision>
<revision>
<version>0.5</version>
<date>2002-02-06</date>
<initials>rwe</initials>
<remark>Protocol tweaks based on implementation and discussion.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2001-11-16</date>
<initials>rwe</initials>
<remark>Major redesign to attempt to clarify the scope of this JEP and limit what it is trying to solve.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2001-07-23</date>
<initials>rwe</initials>
<remark>Protocol update</remark>
</revision>
<revision>
<version>0.2</version>
<date>2001-06-29</date>
<initials>rwe</initials>
<remark>Protocol update and DocBook version</remark>
</revision>
<revision>
<version>0.1</version>
<date>2001-01-25</date>
<initials>rwe</initials>
<remark>Initial release</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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.</p>
<p>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., &lt;room_logging_period/&gt;), a better design would involve a more flexible format.</p>
<p>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).</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>This JEP addresses the following requirements:</p>
<ol>
<li><strong>Data Gathering</strong> -- 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).</li>
<li><strong>Data Reporting</strong> -- 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.</li>
<li><strong>Portability</strong> -- 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.</li>
<li><strong>Simplicity</strong> -- 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.</li>
<li><strong>Flexibility</strong> -- the protocol should be flexible and extensible rather than "hard-coded".</li>
<li><strong>Compatibility</strong> -- the protocol should define an extension to existing Jabber/XMPP protocols and not break existing implementations unless absolutely necessary.</li>
</ol>
</section1>
<section1 topic='Protocol' anchor='protocol'>
<p>The base syntax for the 'jabber:x:data' namespace is as follows (a formal description can be found in the <link url="#schema">XML Schema</link> section below):</p>
<code><![CDATA[
<x xmlns='jabber:x:data'
type='{form-type}'>
<title/>
<instructions/>
<field var='field-name'
type='{field-type}'
label='description'>
<desc/>
<required/>
<value>field-value</value>
<option label='option-label'><value>option-value</value></option>
<option label='option-label'><value>option-value</value></option>
</field>
</x>
]]></code>
<p>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).</p>
<p>The OPTIONAL &lt;title/&gt; and &lt;instructions/&gt; 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 &lt;instructions/&gt; element MAY be included.</p>
<section2 topic='Form Types' anchor='protocol-formtypes'>
<p>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:</p>
<ol>
<li>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)</li>
<li>the place of the form within a transaction (e.g., an IQ "set" or "result") or structured conversation (e.g., a message &lt;thread/&gt;)</li>
<li>the 'type' attribute on the form's root &X; element</li>
</ol>
<p>The first two pieces of contextual information are provided by other protocols, whereas the form types are described in the following table.</p>
<table caption='Form Types'>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>form</td>
<td>The form-processing entity is asking the form-submitting entity to complete a form.</td>
</tr>
<tr>
<td>submit</td>
<td>The form-submitting entity is submitting data to the form-processing entity.</td>
</tr>
<tr>
<td>cancel</td>
<td>The form-submitting entity has cancelled submission of data to the form-processing entity.</td>
</tr>
<tr>
<td>result</td>
<td>The form-processing entity is returning data (e.g., search results) to the form-submitting entity, or the data is a generic data set.</td>
</tr>
</table>
<p>In order to maintain the context of the data as captured in the form type, the following rules MUST be observed:</p>
<ul>
<li><p>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".</p></li>
<li><p>For &MESSAGE; stanzas, the &lt;thread/&gt; 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.</p></li>
<li><p>The only data form type allowed for &lt;presence/&gt; stanzas is "result". The &X; element qualified by the 'jabber:x:data' namespace MUST be a child of the &PRESENCE; stanza. In accordance with <strong>XMPP Core</strong>, use of data forms is not recommended unless necessary to provide information that is directly related to an entity's network availability.</p></li>
</ul>
</section2>
<section2 topic='The Field Element' anchor='protocol-field'>
<p>A data form of type "form", "submit", or "result" SHOULD contain at least one &lt;field/&gt; element; a data form of type "cancel" SHOULD NOT contain any &lt;field/&gt; elements.</p>
<p>The &lt;field/&gt; element MAY contain any of the following child elements:</p>
<ul>
<li><p><strong>&lt;desc/&gt;</strong> -- 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 &lt;desc/&gt; 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 &lt;desc/&gt; element rather than a separate &lt;field/&gt; element of type "fixed".)</p></li>
<li><p><strong>&lt;required/&gt;</strong> -- This element, which MUST be empty, flags the field as required in order for the form to be considered valid.</p></li>
<li><p><strong>&lt;value/&gt;</strong> -- 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 &lt;value/&gt; 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 &lt;value/&gt; element; all other field types MUST NOT contain more than one &lt;value/&gt; element.</p></li>
<li><p><strong>&lt;option/&gt;</strong> -- One of the options in a field of type "list-single" or "list-multi". The XML character of the &lt;value/&gt; child defines the option value, and the 'label' attribute defines a human-readable name for the option. The &lt;option/&gt; element MUST contain one and only one &lt;value/&gt; child. If the field is not of type "list-single" or "list-multi", it MUST NOT contain an &lt;option/&gt; element.</p></li>
</ul>
<p>If the &lt;field/&gt; 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 &lt;field/&gt; element MAY possess a 'label' attribute that defines a human-readable name for the field. For data forms of type "form", each &lt;field/&gt; 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.</p>
<p>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.</p>
</section2>
<section2 topic='Field Types' anchor='protocol-fieldtypes'>
<p>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.</p>
<table caption='Field Types'>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>boolean</td>
<td>The field enables an entity to gather or provide an either-or choice between two options. The default value is "false". &BOOLEANNOTE;</td>
</tr>
<tr>
<td>fixed</td>
<td>The field is intended for data description (e.g., human-readable text such as "section" headers) rather than data gathering or provision. The &lt;value/&gt; child SHOULD NOT contain newlines (the \n and \r characters); instead an application SHOULD generate multiple fixed fields, each with one &lt;value/&gt; child.</td>
</tr>
<tr>
<td>hidden</td>
<td>The field is not shown to the form-submitting entity, but instead is returned with the form.</td>
</tr>
<tr>
<td>jid-multi *</td>
<td>The field enables an entity to gather or provide multiple Jabber IDs.</td>
</tr>
<tr>
<td>jid-single *</td>
<td>The field enables an entity to gather or provide a single Jabber ID.</td>
</tr>
<tr>
<td>list-multi</td>
<td>The field enables an entity to gather or provide one or more options from among many.</td>
</tr>
<tr>
<td>list-single</td>
<td>The field enables an entity to gather or provide one option from among many.</td>
</tr>
<tr>
<td>text-multi **</td>
<td>The field enables an entity to gather or provide multiple lines of text.</td>
</tr>
<tr>
<td>text-private</td>
<td>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., *****).</td>
</tr>
<tr>
<td>text-single</td>
<td>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.</td>
</tr>
</table>
<p>* 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 <strong>XMPP Core</strong> (see the <link url='#validation'>Data Validation</link> section below).</p>
<p>** 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 &lt;value/&gt; element. Similarly, an application that receives multiple &lt;value/&gt; 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.</p>
</section2>
<section2 topic='Multiple Items in Form Results' anchor='protocol-results'>
<p>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 &lt;reported/&gt; element followed by zero or more &lt;item/&gt; elements. The syntax is as follows:</p>
<code><![CDATA[
<x xmlns='jabber:x:data'
type='result'>
<reported>
<field var='field-name' label='description' type='{field-type}'/>
</reported>
<item>
<field var='field-name'>
<value>field-value</value>
</field>
</item>
<item>
<field var='field-name'>
<value>field-value</value>
</field>
</item>
.
.
.
</x>
]]></code>
<p>Each of these elements MUST contain one or more &lt;field/&gt; children. The &lt;reported/&gt; element defines the data format for the result items by specifying the fields to be expected for each item; for this reason, the &lt;field/&gt; elements SHOULD possess a 'type' attribute and 'label' attribute in addition to the 'var' attribute, and SHOULD NOT contain a &lt;value/&gt; element. Each &lt;item/&gt; element defines one item in the result set, and MUST contain each field specified in the &lt;reported/&gt; element (although the XML character data of the &lt;value/&gt; element MAY be null).</p>
</section2>
</section1>
<section1 topic='Data Validation' anchor='validation'>
<p>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 &lt;text/&gt; element or an application-specific child element that identifies the problem (see &jep0086; for information about mappings and formats).</p>
</section1>
<section1 topic='Examples' anchor='examples'>
<p>For the sake of the following examples, let us suppose that there exists a bot hosting service on the Jabber network, located at &lt;botster.shakespeare.lit&gt;. 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.</p>
<p>Note: Additional examples can be found in the specifications for various using protocols, such as <strong>JEP-0045: Multi-User Chat</strong> and <strong>JEP-0055: Jabber Search</strong>.</p>
<section2 topic='Configuration' anchor='examples-config'>
<p>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:</p>
<example caption="User Requests Bot Creation"><![CDATA[
<iq from='romeo@montague.net/home'
to='joogle@botster.shakespeare.lit'
type='get'
xml:lang='en'
id='create1'>
<command xmlns='http://jabber.org/protocol/commands'
node='create'
action='execute'/>
</iq>
]]></example>
<p>The hosting service then returns a data form to the user:</p>
<example caption="Service Returns Bot Creation Form"><![CDATA[
<iq from='joogle@botster.shakespeare.lit'
to='romeo@montague.net/home'
type='result'
xml:lang='en'
id='create1'>
<command xmlns='http://jabber.org/protocol/commands'
node='create'
sessionid='create:20040408T0128Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Bot Configuration</title>
<instructions>Fill out this form to configure your new bot!</instructions>
<field type='hidden'
var='FORM_TYPE'>
<value>jabber:bot</value>
</field>
<field type='fixed'><value>Section 1: Bot Info</value></field>
<field type='text-single'
label='The name of your bot'
var='botname'/>
<field type='text-multi'
label='Helpful description of your bot'
var='description'/>
<field type='boolean'
label='Public bot?'
var='public'>
<required/>
</field>
<field type='text-private'
label='Password for special access'
var='password'/>
<field type='fixed'><value>Section 2: Features</value></field>
<field type='list-multi'
label='What features will the bot support?'
var='features'>
<option label='Contests'><value>contests</value></option>
<option label='News'><value>news</value></option>
<option label='Polls'><value>polls</value></option>
<option label='Reminders'><value>reminders</value></option>
<option label='Search'><value>search</value></option>
<value>news</value>
<value>search</value>
</field>
<field type='fixed'><value>Section 3: Subscriber List</value></field>
<field type='list-single'
label='Maximum number of subscribers'
var='maxsubs'>
<value>20</value>
<option label='10'><value>10</value></option>
<option label='20'><value>20</value></option>
<option label='30'><value>30</value></option>
<option label='50'><value>50</value></option>
<option label='100'><value>100</value></option>
<option label='None'><value>none</value></option>
</field>
<field type='fixed'><value>Section 4: Invitations</value></field>
<field type='jid-multi'
label='People to invite'
var='invitelist'>
<desc>Tell all your friends about your new bot!</desc>
</field>
</x>
</command>
</iq>
]]></example>
<p>The user then submits the configuration form:</p>
<example caption="User Submits Bot Creation Form"><![CDATA[
<iq from='joogle@botster.shakespeare.lit'
to='romeo@montague.net/home'
type='set'
xml:lang='en'
id='create2'>
<command xmlns='http://jabber.org/protocol/commands'
node='create'
sessionid='create:20040408T0128Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:bot</value>
</field>
<field type='text-single' var='botname'>
<value>The Jabber Google Bot</value>
</field>
<field type='text-multi' var='description'>
<value>This bot enables you to send requests to</value>
<value>Google and receive the search results right</value>
<value>in your Jabber client. It&apos; really cool!</value>
<value>It even supports Google News!</value>
</field>
<field type='boolean' var='public'>
<value>0</value>
</field>
<field type='text-private' var='password'>
<value>v3r0na</value>
</field>
<field type='list-multi' var='features'>
<value>news</value>
<value>search</value>
</field>
<field type='list-single' var='maxsubs'>
<value>50</value>
</field>
<field type='jid-multi' var='invitelist'>
<value>juliet@capulet.com</value>
<value>benvolio@montague.net</value>
</field>
</x>
</command>
</iq>
]]></example>
<p>The service then returns the results to the user:</p>
<example caption="Service Returns Bot Creation Result"><![CDATA[
<iq from='joogle@botster.shakespeare.lit'
to='romeo@montague.net/home'
type='result'
xml:lang='en'
id='create2'>
<command xmlns='http://jabber.org/protocol/commands'
node='create'
sessionid='create:20040408T0128Z'
status='completed'>
<x xmlns='jabber:x:data' type='result'>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:bot</value>
</field>
<field type='text-single' var='botname'>
<value>The Jabber Google Bot</value>
</field>
<field type='boolean' var='public'>
<value>0</value>
</field>
<field type='text-private' var='password'>
<value>v3r0na</value>
</field>
<field type='list-multi' var='features'>
<value>news</value>
<value>search</value>
</field>
<field type='list-single' var='maxsubs'>
<value>50</value>
</field>
<field type='jid-multi' var='invitelist'>
<value>juliet@capulet.com</value>
<value>benvolio@montague.net</value>
</field>
</x>
</command>
</iq>
]]></example>
</section2>
<section2 topic='Search' anchor='examples-search'>
<p>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:</p>
<example caption="User Requests Search Form"><![CDATA[
<iq from='juliet@capulet.com/chamber'
to='joogle@botster.shakespeare.lit'
type='get'
xml:lang='en'
id='search1'>
<command xmlns='http://jabber.org/protocol/commands'
node='search'
action='execute'/>
</iq>
]]></example>
<example caption="Service Returns Search Form"><![CDATA[
<iq from='joogle@botster.shakespeare.lit'
to='juliet@capulet.com/chamber'
type='result'
xml:lang='en'
id='search1'>
<command xmlns='http://jabber.org/protocol/commands'
node='search'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Joogle Search</title>
<instructions>Fill out this form to search for information!</instructions>
<field type='text-single'
var='search_request'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<example caption="User Submits Search Form"><![CDATA[
<iq from='juliet@capulet.com/chamber'
to='joogle@botster.shakespeare.lit'
type='get'
xml:lang='en'
id='search2'>
<command xmlns='http://jabber.org/protocol/commands'
node='search'>
<x xmlns='jabber:x:data' type='submit'>
<field type='text-single' var='search_request'>
<value>verona</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption="Service Returns Search Results"><![CDATA[
<iq from='joogle@botster.shakespeare.lit'
to='juliet@capulet.com/chamber'
type='result'
xml:lang='en'
id='search2'>
<command xmlns='http://jabber.org/protocol/commands'
node='search'
status='completed'>
<x xmlns='jabber:x:data' type='result'>
<title>Joogle Search: verona</title>
<reported>
<field var='name'/>
<field var='url'/>
</reported>
<item>
<field var='name'>
<value>Comune di Verona - Benvenuti nel sito ufficiale</value>
</field>
<field var='url'>
<value>http://www.comune.verona.it/</value>
</field>
</item>
<item>
<field var='name'>
<value>benvenuto!</value>
</field>
<field var='url'>
<value>http://www.hellasverona.it/</value>
</field>
</item>
<item>
<field var='name'>
<value>Universita degli Studi di Verona - Home Page</value>
</field>
<field var='url'>
<value>http://www.univr.it/</value>
</field>
</item>
<item>
<field var='name'>
<value>Aeroporti del Garda</value>
</field>
<field var='url'>
<value>http://www.aeroportoverona.it/</value>
</field>
</item>
<item>
<field var='name'>
<value>Veronafiere - fiera di Verona</value>
</field>
<field var='url'>
<value>http://www.veronafiere.it/</value>
</field>
</item>
</x>
</command>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>There are no security concerns related to this specification above and beyond those described in the relevant section of <strong>XMPP Core</strong>.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-namespaces'>
<p>The &REGISTRAR; includes the 'jabber:x:data' namespace in its registry of protocol namespaces.</p>
</section2>
<section2 topic='Parameter Values' anchor='registrar-parameters'>
<p>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 &lt;<link url="http://www.jabber.org/registrar/formtypes.html">http://www.jabber.org/registrar/formtypes.html</link>&gt;.</p>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>This schema is descriptive, not normative.</p>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:x:data'
xmlns='jabber:x:data'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0004: http://www.jabber.org/jeps/jep-0004.html
</xs:documentation>
</xs:annotation>
<xs:element name='x'>
<xs:complexType>
<xs:sequence>
<xs:element name='instructions'
minOccurs='0'
maxOccurs='unbounded'
type='xs:string'/>
<xs:element name='title' minOccurs='0' type='xs:string'/>
<xs:element ref='field' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='reported' minOccurs='0' maxOccurs='1'/>
<xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='type' use='required'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='cancel'/>
<xs:enumeration value='form'/>
<xs:enumeration value='result'/>
<xs:enumeration value='submit'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name='field'>
<xs:complexType>
<xs:sequence>
<xs:element name='desc' minOccurs='0' type='xs:string'/>
<xs:element name='required' minOccurs='0' type='empty'/>
<xs:element ref='value' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='option' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='label' type='xs:string' use='optional'/>
<xs:attribute name='type' use='optional' default='text-single'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='boolean'/>
<xs:enumeration value='fixed'/>
<xs:enumeration value='hidden'/>
<xs:enumeration value='jid-multi'/>
<xs:enumeration value='jid-single'/>
<xs:enumeration value='list-multi'/>
<xs:enumeration value='list-single'/>
<xs:enumeration value='text-multi'/>
<xs:enumeration value='text-private'/>
<xs:enumeration value='text-single'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name='var' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='option'>
<xs:complexType>
<xs:sequence>
<xs:element ref='value'/>
</xs:sequence>
<xs:attribute name='label' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='value' type='xs:string'/>
<xs:element name='reported'>
<xs:complexType>
<xs:sequence>
<xs:element ref='field' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
<xs:annotation>
<xs:documentation>
When contained in a "reported" element, the "field" element
SHOULD NOT contain a "value" child.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name='item'>
<xs:complexType>
<xs:sequence>
<xs:element ref='field' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
<section1 topic='Changes Between Draft and Final' anchor='draft-to-final'>
<p>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):</p>
<ul>
<li>The &lt;x/&gt; element MAY be included in &lt;message/&gt; and &lt;presence/&gt; elements.</li>
<li>The &lt;x/&gt; element MAY contain a &lt;title/&gt; child for forms and results.</li>
<li>The &lt;x/&gt; element MUST possess a 'type' attribute.</li>
<li>A &lt;field/&gt; element MAY be of type='jid-single'.</li>
<li>Results MAY be reported back in &lt;item/&gt; tags.</li>
<li>Results MAY contain a &lt;reported/&gt; element with result set.</li>
<li>The &lt;reported/&gt; fields MAY possess a 'type' attribute to provide hints about how to interact with the data (type='jid-single' being the most useful).</li>
</ul>
</section1>
</jep>

108
xep-0005.xml Normal file
View File

@ -0,0 +1,108 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Jabber Interest Groups</title>
<abstract>This is the official list and summary information of the Jabber Interest Groups.</abstract>
&LEGALNOTICE;
<number>0005</number>
<status>Obsolete</status>
<type>Informational</type>
<jig>None</jig>
<author>
<firstname>Jeremie</firstname>
<surname>Miller</surname>
<email>jer@jabber.org</email>
</author>
<revision>
<version>1.1</version>
<date>2002-05-08</date>
<initials>psa</initials>
<remark>Changed Status to Obsolete per approval of JEP-0019.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2001-07-03</date>
<initials>jer</initials>
<remark>First Post! ;)</remark>
</revision>
</header>
<section1 topic='Standards Compliance'>
<ul>
<li>Michael Bauer / bauer@jabber.com</li>
<li>Julian Missig / julian@jabber.org</li>
<li>Terry Smelser / tsmelser@sltscommunications.net</li>
<li>DJ Adams / dj.adams@pobox.com</li>
<li>Mike Szczerban / mikeszcz@delanet.com</li>
</ul>
<p>Determine standards for implementing derivative trademarks (e.g., "100% Jabber Protocol Compliant") and test software and services for compliance.</p>
</section1>
<section1 topic='File Transfer and Out Of Band data (OOB)'>
<ul>
<li>Ryan Eatmon / reatmon@jabber.org</li>
<li>Jer / jer@jabber.org</li>
<li>Stephen Lee / srlee@myjabber.org</li>
<li>Jim Powell / PowellJF@navair.navy.mil</li>
<li>Zad / zadk@mynet.com</li>
<li>Michael J. Emswiler / memswiler@hotmail.com</li>
</ul>
<p>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).</p>
</section1>
<section1 topic='Security'>
<ul>
<li>Thomas Muldowney / temas@jabber.org</li>
<li>Al Sutton / al@alsutton.com</li>
<li>Rahul Dave / rahul@mozdev.org</li>
</ul>
<p>Focusing on authentication, message encryption, connection security, etc.</p>
</section1>
<section1 topic='Forms'>
<ul>
<li>Ryan Eatmon / reatmon@jabber.org</li>
<li>Thomas Muldowney / temas@jabber.org</li>
<li>Adam Theo / adamtheo@theoretic.com</li>
<li>Mike Szczerban / mikeszcz@delanet.com</li>
<li>Michael J. Emswiler / memswiler@hotmail.com</li>
</ul>
<p>To define a new namespace for dynamic forms. Minimally to supplant jabber:iq:register and jabber:iq:search.</p>
</section1>
<section1 topic='Text Formatting'>
<ul>
<li>Julian Missig / julian@jabber.org</li>
<li>Michael J. Emswiler / memswiler@hotmail.com</li>
</ul>
<p>Will determine the protocol for sending and receiving formatted messages in Jabber (XHTML-Basic)</p>
</section1>
<section1 topic='Browsing'>
<ul>
<li>Jer / jer@jabber.org</li>
<li>Peter Millard / me@pgmillard.com</li>
<li>David Waite / dwaite@jabber.com</li>
</ul>
<p>The replacement for agents, including extensible directory lookups and namespace feature negotiation. Defined as a draft protocol but needs additional work.</p>
</section1>
<section1 topic='Presence Management'>
<ul>
<li>Dave Smith / dave@jabber.org</li>
<li>Oliver Wing / owing@vianetworks.co.uk</li>
<li>David Waite / dwaite@jabber.com</li>
<li>Rahul Dave / rahul@mozdev.org</li>
<li>Peter Millard / me@pgmillard.com</li>
</ul>
<p>Describe in detail how presence management currently works, and work on proposals for things like invisibility.</p>
</section1>
</jep>

96
xep-0006.xml Normal file
View File

@ -0,0 +1,96 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Profiles</title>
<abstract>A proposal for a more powerful and extensible protocol for the management of personal information within Jabber.</abstract>
&LEGALNOTICE;
<number>0006</number>
<status>Obsolete</status>
<type>JIG Formation</type>
<jig>Forms, Security</jig>
<author>
<firstname>Adam</firstname>
<surname>Theo</surname>
<email>adamtheo@theoretic.com</email>
<jid>adamtheo@theoretic.com</jid>
</author>
<author>
<firstname>Michael</firstname>
<surname>Hearn</surname>
<email>mhearn@subdimension.com</email>
<jid>tweedledee@jabber.org</jid>
</author>
<author>
<firstname>Eric</firstname>
<surname>Murphy</surname>
<email>ericmurphy@jabber.org</email>
<jid>ericmurphy@jabber.org</jid>
</author>
<revision>
<version>1.1</version>
<date>2002-05-08</date>
<initials>psa</initials>
<remark>Changed Status to Obsolete per approval of JEP-0019.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2001-07-30</date>
<initials>at</initials>
<remark>Initial release</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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:</p>
<ul>
<li>It is inflexible, as you can only store information that is defined by a subset of the vCard format.</li>
<li>It is inefficient, as the whole vCard must be retrieved even if all you want to know is the name of a user.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Specification'>
<section2 topic='Interface'>
<p>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.</p>
<p>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 <link url="http://www.theoretic.com/identity">Theoretic Identity</link> website.</p>
</section2>
<section2 topic='Structure'>
<p>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.</p>
<p>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.</p>
</section2>
<section2 topic='Storage'>
<p>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.</p>
<p>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.</p>
</section2>
<section2 topic='Gate'>
<p>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.</p>
<p>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.</p>
</section2>
</section1>
<section1 topic='Road-map'>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Benefits'>
<p>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.</p>
<ul>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
</ul>
</section1>
<section1 topic='Conclusion'>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='History'>
<p>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 (<link url="http://www.theoretic.com/identity/">http://www.theoretic.com/identity/</link>), 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.</p>
</section1>
</jep>

73
xep-0007.xml Normal file
View File

@ -0,0 +1,73 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Conferencing JIG</title>
<abstract>A proposal for a Jabber Interest Group that will discuss the protocol for implementing many-to-many communications.</abstract>
&LEGALNOTICE;
<number>0007</number>
<status>Obsolete</status>
<type>JIG Proposal</type>
<jig>Conferencing</jig>
<author>
<firstname>David</firstname>
<surname>Waite</surname>
<email>akuma@jabber.org</email>
<jid>akuma@jabber.org</jid>
</author>
<revision>
<version>1.1</version>
<date>2002-05-08</date>
<initials>psa</initials>
<remark>Changed Status to Obsolete per approval of JEP-0019.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2001-08-03</date>
<initials>akuma</initials>
<remark>Initial version</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
</section1>
<section1 topic='Base conferencing protocol'>
<p>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.</p>
<p>The framework's scope consists of the following minimum functionality:</p>
<ul>
<li>Browsing a list of public rooms</li>
<li>Finding a public room based on search parameters</li>
<li>Creating new rooms</li>
<li>Destroying rooms</li>
<li>Entering existing rooms</li>
<li>Altering functionality of a room</li>
<li>Querying a room for public information</li>
<li>Sending and accepting invitations to a room</li>
<li>Changing a participant's nickname within a room</li>
<li>Discovering and changing features on a running room</li>
<li>Changing a participant's status within a room</li>
<li>Sending a message to a room or a specific participant within a room</li>
</ul>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Justification for new Conferencing protocol'>
<p>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:</p>
<ul>
<li>There is no control over how you enter a room - for instance, you can not specify a password for entering a password-protected room.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>This new conferencing protocol will be designed to solve these problems.</p>
<p>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.</p>
</section1>
<section1 topic='Continuing Development'>
<p>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.</p>
</section1>
</jep>

138
xep-0008.xml Normal file
View File

@ -0,0 +1,138 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>IQ-Based Avatars</title>
<abstract>This JEP provides historical documentation of an IQ-based protocol for exchanging user avatars.</abstract>
&LEGALNOTICE;
<number>0008</number>
<status>Deferred</status>
<type>Historical</type>
<jig>Standards JIG</jig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
</dependencies>
<supersedes>None</supersedes>
<supersededby>None</supersededby>
<shortname>None</shortname>
&temas;
&xvirge;
<author>
<firstname>Jens</firstname>
<surname>Alfke</surname>
<email>jens@mac.com</email>
</author>
&pgmillard;
<revision>
<version>0.3</version>
<date>2005-06-16</date>
<initials>psa</initials>
<remark>Coincident with publication of JEP-0153, changed type to Historical.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-05-06</date>
<initials>psa</initials>
<remark>At the request of the authors, the status of this JEP has been changed to Retracted, to be superseded by a forthcoming JEP. This JEP will not be considered further by the Jabber Software Foundation and should not be used as a basis for implementations.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2001-09-14</date>
<initials>tm</initials>
<remark>Initial release</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
</section1>
<section1 topic='Image Requirements'>
<p>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 <note>It is highly recommended that clients never scale up images when displaying them.</note>. Images should be square, but this is not required. Images should be in GIF, JPEG, or PNG format, although it is possible that in future revisions of this spec more formats will be allowed. Finally, images must use less than eight (8) kilobytes of data.</p>
</section1>
<section1 topic='Avatar Availability'>
<p>There are two methods of showing that a client has an avatar available:</p>
<ol>
<li>Embedding the jabber:x:avatar namespace within &#60;presence/&#62; packets using Jabber's &#60;x/&#62; element</li>
<li>Displaying the jabber:iq:avatar namespace in browse requests</li>
</ol>
<p>Partly because Jabber browsing is relatively undeveloped, this proposal focuses on the first option.</p>
<p>The &#60;x/&#62; 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 &#60;hash/&#62; 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:</p>
<example>
&#60;presence&#62;
&#60;x xmlns='jabber:x:avatar'&#62;
&#60;hash&#62;SHA1 of image data&#60;/hash&#62;
&#60;/x&#62;
&#60;/presence&#62;
</example>
<p>If the avatar-generating user changes the avatar, a new presence packet is sent out with the updated information:</p>
<example>
&#60;presence&#62;
&#60;x xmlns='jabber:x:avatar'&#62;
&#60;hash&#62;SHA1 of new image data&#60;/hash&#62;
&#60;/x&#62;
&#60;/presence&#62;
</example>
<p>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:</p>
<example>
&#60;presence&#62;
&#60;x xmlns='jabber:x:avatar'/&#62;
&#60;/presence&#62;
</example>
<p>Clients should send the current avatar hash in every &#60;presence/&#62; packet even if the avatar has not changed. Remember that other clients logging in will receive a copy of the most recent &#60;presence/&#62; 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 &#60;presence/&#62; 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:</p>
<example>
&#60;presence/&#62;
</example>
</section1>
<section1 topic='Avatar Retrieval'>
<p>There are two methods for retrieving the actual avatar data:</p>
<ol>
<li>An exchange between clients of &#60;iq/&#62; elements in the jabber:iq:avatar namespace</li>
<li>Public XML storage from the avatar-generating client to the server and public XML retrieval from the server to the avatar-requesting client <note>Refer to the <link url="http://docs.jabber.org/draft-proto/html/xml.html">Generic XML Namespace Storage</link> draft protocol.</note></li>
</ol>
<p>The first of these methods is preferred. On this model, a query is sent directly to the avatar-generating client using an &#60;iq/&#62; element of type "get" in the jabber:iq:avatar namespace <note>Whenever possible, the avatar-requesting client should attempt to determine if the avatar-generating client has an avatar available before requesting it.</note> <note>It is suggested that no request be made if it is known (such as through a browse reply) that a client does not support the jabber:iq:avatar namespace.</note>:</p>
<example>
&#60;iq id='2' type='get' to='user@server/resource'&#62;
&#60;query xmlns='jabber:iq:avatar'/&#62;
&#60;/iq&#62;
</example>
<p>The avatar-generating client will reply with an &#60;iq/&#62; element of type "result" in the jabber:iq:avatar namespace; this reply will contain a query element that in turn contains a &#60;data/&#62; element with the MIME type in the 'mimetype' attribute and the data base64-encoded in the body of the &#60;data/&#62; element:</p>
<example>
&#60;iq id='2' type='result' to='user@server/resource'&#62;
&#60;query xmlns='jabber:iq:avatar'&#62;
&#60;data mimetype='image/jpeg'&#62;
Base64-Encoded Data
&#60;/data&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<p>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:</p>
<example>
&#60;iq id='0' type='set' to='user@server'&#62;
&#60;query xmlns='storage:client:avatar'&#62;
&#60;data mimetype='image/jpeg'&#62;
Base64 Encoded Data
&#60;/data&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<p>Once such data has been set, the avatar can be retrieved by any requesting client from the avatar-generating client's public XML storage:</p>
<example>
&#60;iq id='1' type='get' to='user@server'&#62;
&#60;query xmlns='storage:client:avatar'/&#62;
&#60;/iq&#62;
</example>
</section1>
<section1 topic='Future Considerations'>
<p>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.</p>
</section1>
<section1 topic='Author Note' anchor='authornote'>
<p>Peter Millard, a co-author of this specification from version 0.1 through version 0.3, died on April 26, 2006.</p>
</section1>
</jep>

316
xep-0009.xml Normal file
View File

@ -0,0 +1,316 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Jabber-RPC</title>
<abstract>This JEP defines a method for transporting XML-RPC encoded requests and responses over Jabber/XMPP.</abstract>
&LEGALNOTICE;
<number>0009</number>
<status>Final</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XML-RPC</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>jabber-rpc</shortname>
<schemaloc>
<url>http://jabber.org/protocol/jabber-rpc/jabber-rpc.xsd</url>
</schemaloc>
<author>
<firstname>DJ</firstname>
<surname>Adams</surname>
<email>dj.adams@pobox.com</email>
<jid>dj@gnu.mine.nu</jid>
</author>
<revision>
<version>2.1</version>
<date>2006-02-09</date>
<initials>psa</initials>
<remark>Defined error handling, service discovery, security considerations, and Jabber Registrar considerations.</remark>
</revision>
<revision>
<version>2.0</version>
<date>2002-12-09</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, changed status to Final.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2001-09-27</date>
<initials>psa</initials>
<remark>Changed status to Draft</remark>
</revision>
<revision>
<version>0.1</version>
<date>2001-09-14</date>
<initials>dja</initials>
<remark>Initial version</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>&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.</p>
<p>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 <message/> element as opposed to an &IQ; stanza), resulting in potential interoperability problems.</p>
<p>A working session during JabberCon 2001 resulted in a <link url="http://www.pipetree.com/jabber/jrpc.html">formalisation</link> of a single method. This JEP describes that method, which is labelled as Jabber-RPC to differentiate it from XML-RPC itself.</p>
</section1>
<section1 topic='Jabber-RPC'>
<p>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.</p>
<p>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 &lt;methodCall/&gt; element (in the case of a request) or a single &lt;methodResponse/&gt; 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.</p>
<p>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.</p>
<p>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 &lt;error/&gt; tag as a direct child of the &IQ; stanza. There are no specific XML-RPC-related, transport-level errors.</p>
</section1>
<section1 topic='Examples'>
<example caption='A typical request'><![CDATA[
<iq type='set'
from='requester@company-b.com/jrpc-client'
to='responder@company-a.com/jrpc-server'
id='rpc1'>
<query xmlns='jabber:iq:rpc'>
<methodCall>
<methodName>examples.getStateName</methodName>
<params>
<param>
<value><i4>6</i4></value>
</param>
</params>
</methodCall>
</query>
</iq>
]]></example>
<example caption='A typical response'><![CDATA[
<iq type='result'
from='responder@company-a.com/jrpc-server'
to='requester@company-b.com/jrpc-client'
id='rpc1'>
<query xmlns='jabber:iq:rpc'>
<methodResponse>
<params>
<param>
<value><string>Colorado</string></value>
</param>
</params>
</methodResponse>
</query>
</iq>
]]></example>
<p>If the requesting entity does not have sufficient permissions to perform remote procedure calls, the responding entity MUST return a &forbidden; error:</p>
<example caption='Requesting entity is forbidden to perform remote procedure calls'><![CDATA[
<iq type='error'
from='responder@company-a.com/jrpc-server'
to='requester@company-b.com/jrpc-client'
id='rpc1'>
<query xmlns='jabber:iq:rpc'>
<methodCall>
<methodName>examples.getStateName</methodName>
<params>
<param>
<value><i4>6</i4></value>
</param>
</params>
</methodCall>
</query>
<error code='403' type='auth'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section1>
<section1 topic='Service Discovery' anchor='disco'>
<p>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":</p>
<example caption='A disco#info query'><![CDATA[
<iq type='get'
from='requester@company-b.com/jrpc-client'
to='responder@company-a.com/jrpc-server'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption='A disco#info response'><![CDATA[
<iq type='result'
to='requester@company-b.com/jrpc-client'
from='responder@company-a.com/jrpc-server'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity category='automation' type='rpc'/>
<feature var='jabber:iq:rpc'/>
</query>
</iq>
]]></example>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>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.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic="Jabber Registrar Considerations" anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; includes 'jabber:iq:rpc' in its registry of protocol namespaces.</p>
</section2>
<section2 topic='Service Discovery Identity' anchor='registrar-disco'>
<p>The Jabber Registrar includes a Service Discovery type of "rpc" within the "automation" category in its registry of service discovery identities.</p>
</section2>
</section1>
<section1 topic='XML Schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:iq:rpc'
xmlns='jabber:iq:rpc'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
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
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:choice minOccurs='0' maxOccurs='1'>
<xs:element ref='methodCall'/>
<xs:element ref='methodResponse'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name="methodCall">
<xs:complexType>
<xs:all>
<xs:element name="methodName">
<xs:simpleType>
<xs:restriction base="ASCIIString">
<xs:pattern value="([A-Za-z0-9]|/|\.|:|_)*" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="params" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element name="param" type="ParamType"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="methodResponse">
<xs:complexType>
<xs:choice>
<xs:element name="params">
<xs:complexType>
<xs:sequence>
<xs:element name="param" type="ParamType"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="fault">
<!-- What can appear inside a fault is very restricted -->
<xs:complexType>
<xs:sequence>
<xs:element name="value">
<xs:complexType>
<xs:sequence>
<xs:element name="struct">
<xs:complexType>
<xs:sequence>
<xs:element name="member"
type="MemberType">
</xs:element>
<xs:element name="member"
type="MemberType">
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:complexType name="ParamType">
<xs:sequence>
<xs:element name="value" type="ValueType"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ValueType" mixed="true">
<xs:choice>
<xs:element name="i4" type="xs:int"/>
<xs:element name="int" type="xs:int"/>
<xs:element name="string" type="ASCIIString"/>
<xs:element name="double" type="xs:decimal"/>
<xs:element name="Base64" type="xs:base64Binary"/>
<xs:element name="boolean" type="NumericBoolean"/>
<xs:element name="dateTime.iso8601" type="xs:dateTime"/>
<xs:element name="array" type="ArrayType"/>
<xs:element name="struct" type="StructType"/>
</xs:choice>
</xs:complexType>
<xs:complexType name="StructType">
<xs:sequence>
<xs:element name="member" type="MemberType"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="MemberType">
<xs:sequence>
<xs:element name="name" type="xs:string" />
<xs:element name="value" type="ValueType"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ArrayType">
<xs:sequence>
<xs:element name="data">
<xs:complexType>
<xs:sequence>
<xs:element name="value" type="ValueType"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="ASCIIString">
<xs:restriction base="xs:string">
<xs:pattern value="([ -~]|\n|\r|\t)*" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="NumericBoolean">
<xs:restriction base="xs:boolean">
<xs:pattern value="0|1" />
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
</jep>

55
xep-0010.xml Normal file
View File

@ -0,0 +1,55 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Whiteboarding JIG</title>
<abstract>A proposal to form a JIG to develop a protocol for whiteboarding over Jabber.</abstract>
&LEGALNOTICE;
<number>0010</number>
<status>Obsolete</status>
<type>JIG Formation</type>
<jig>None</jig>
<author>
<firstname>Niklas</firstname>
<surname>Gustavsson</surname>
<email>niklas@protocol7.com</email>
<jid>nikgus@jabber.org</jid>
</author>
<revision>
<version>1.1</version>
<date>2002-05-08</date>
<initials>psa</initials>
<remark>Changed Status to Obsolete per approval of JEP-0019.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2001-09-30</date>
<initials>ng</initials>
<remark>Initial release</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
<p>There exists today a protocol draft for sending streaming XPM over Jabber <note>XPM over Jabber (<link url="http://docs.jabber.org/draft-proto/html/sxpm.html">http://docs.jabber.org/draft-proto/html/sxpm.html</link>)</note>. XPM is a bitmap format, which makes it well-suited for certain applications (e.g., smaller drawings and sketches). However, significant changes in an XPM image will require sending large amounts of XML data (even with the compression described in the protocol draft). Also, for example, XPM does not scale without loss of resolution, nor does it support metadata. In addition, the current draft specifies the data format only, not the way the data will be sent or handled by Jabber servers and clients.</p>
<p>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 <note>Conferencing protocol draft (<link url="http://jabber.org/?oid=1538">http://jabber.org/?oid=1538</link>)</note>.</p>
</section1>
<section1 topic='Deliverables'>
<p>The Whiteboarding JIG should produce the following deliverables (these deliverables will be presented to the Jabber Council as a JEP):</p>
<section2 topic='Requirements'>
<p>A set of requirements that the proposed protocol should fulfill.</p>
</section2>
<section2 topic='Analysis of existing work'>
<p>There are today at least four different attempts <note>Distributed SVG documents (<link url="http://www.jabber.org/?oid=1025">http://www.jabber.org/?oid=1025</link>)</note> <note>SVG over Jabber (<link url="http://www.protocol7.com/jabber/whiteboard_proposal.txt">http://www.protocol7.com/jabber/whiteboard_proposal.txt</link>)</note> <note>Jabberzilla Whiteboard (<link url="http://jabberzilla.mozdev.org/">http://jabberzilla.mozdev.org/</link>)</note> to create a whiteboarding protocol in Jabber. The Whiteboarding JIG should evaluate them all and see which features of each are worth keeping.</p>
</section2>
<section2 topic='Graphics data format'>
<p>One or more data formats for the graphics data, presented both as a description and as a DTD or XML schema.</p>
</section2>
<section2 topic='Jabber protocol'>
<p>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.</p>
</section2>
</section1>
</jep>

483
xep-0011.xml Normal file
View File

@ -0,0 +1,483 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Jabber Browsing</title>
<abstract>This JEP defines a way to describe information about Jabber entities and the relationships between entities. Note: This JEP is superseded by JEP-0030: Service Discovery.</abstract>
&LEGALNOTICE;
<number>0011</number>
<status>Deprecated</status>
<type>Historical</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby>
<spec>JEP-0030</spec>
</supersededby>
<shortname>iq-browse</shortname>
<schemaloc>
<url>http://jabber.org/protocol/iq-browse/iq-browse.xsd</url>
</schemaloc>
&jer;
&xvirge;
&temas;
<revision>
<version>1.2</version>
<date>2004-11-12</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, changed status to Deprecated.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2004-01-06</date>
<initials>psa</initials>
<remark>Added schema.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-05-08</date>
<initials>psa</initials>
<remark>Changed status to Active.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2002-04-15</date>
<initials>jer</initials>
<remark>Changed the suggested use of category to an attribute of item instead of the element names.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-01-16</date>
<initials>psa</initials>
<remark>Added additional category/type combinations from the protocol draft (also created new category 'validate' as a bucket for the grammar and spelling checkers, which formerly were under the 'render' category).</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-01-04</date>
<initials>jkm</initials>
<remark>Updated to JEP format and revised description.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2001-01-25</date>
<initials>jm</initials>
<remark>Initial draft version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
<p><em>Note well that implementors are encouraged to implement &jep0030; instead of Jabber Browsing.</em></p>
</section1>
<section1 topic='JID-Types'>
<p>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:</p>
<table caption='Official List of JID-Type Categories and Types'>
<tr>
<th>Category</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td rowspan="7">application/</td>
<td> </td>
<td>Specific applications running as a resource on a user@host</td>
</tr>
<tr>
<td>bot</td>
<td>Automated conversations</td>
</tr>
<tr>
<td>calendar</td>
<td>Calendaring and scheduling service</td>
</tr>
<tr>
<td>editor</td>
<td>Collaborative editor</td>
</tr>
<tr>
<td>fileserver</td>
<td>Available files</td>
</tr>
<tr>
<td>game</td>
<td>Multi-player game</td>
</tr>
<tr>
<td>whiteboard</td>
<td>Whiteboard tool</td>
</tr>
<tr>
<td rowspan="7">conference/</td>
<td> </td>
<td>Nodes of this category provide multi-user chat facilities (a.k.a. conference rooms).</td>
</tr>
<tr>
<td>irc</td>
<td>IRC rooms (note: this enables Jabber users to connect to Internet Relay Chat rooms)</td>
</tr>
<tr>
<td>list</td>
<td>Mailing-list-style conferences</td>
</tr>
<tr>
<td>private</td>
<td>Private, dynamically-generated conference rooms</td>
</tr>
<tr>
<td>public</td>
<td>Public, permanent conference rooms</td>
</tr>
<tr>
<td>topic</td>
<td>Topic-based conferences</td>
</tr>
<tr>
<td>url</td>
<td>Website-hosted conferences</td>
</tr>
<tr>
<td rowspan="5">headline/</td>
<td> </td>
<td>Recognize different sources of headlines, GUI hints</td>
</tr>
<tr>
<td>logger</td>
<td>Log messages (usually presented in a scrolling GUI)</td>
</tr>
<tr>
<td>notice</td>
<td>Alerts and warnings (usually presented as popup messages)</td>
</tr>
<tr>
<td>rss</td>
<td>Rich Site Summary syndication</td>
</tr>
<tr>
<td>stock</td>
<td>Stock market information by symbol (ticker)</td>
</tr>
<tr>
<td rowspan="7">keyword/</td>
<td> </td>
<td>Keyword-based lookup services (search engines, etc.)</td>
</tr>
<tr>
<td>dictionary</td>
<td>Dictionary lookup service</td>
</tr>
<tr>
<td>dns</td>
<td>DNS resolver</td>
</tr>
<tr>
<td>software</td>
<td>Software search</td>
</tr>
<tr>
<td>thesaurus</td>
<td>Thesaurus lookup service</td>
</tr>
<tr>
<td>web</td>
<td>Web search</td>
</tr>
<tr>
<td>whois</td>
<td>Whois query service</td>
</tr>
<tr>
<td rowspan="4">render/</td>
<td> </td>
<td>Automated translation services</td>
</tr>
<tr>
<td>en2fr</td>
<td>English to French</td>
</tr>
<tr>
<td>*2*</td>
<td>Other language to language (using standard language codes)</td>
</tr>
<tr>
<td>tts</td>
<td>Text to Speech</td>
</tr>
<tr>
<td rowspan="12">service/</td>
<td> </td>
<td>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.</td>
</tr>
<tr>
<td>aim</td>
<td>AIM transport</td>
</tr>
<tr>
<td>icq</td>
<td>ICQ transport</td>
</tr>
<tr>
<td>irc</td>
<td>IRC gateway (note: this enables IRC users to connect to Jabber)</td>
</tr>
<tr>
<td>jabber</td>
<td>A Jabber server which conforms to the specification for the 'jabber:client' namespace</td>
</tr>
<tr>
<td>jud</td>
<td>Jabber User Directory</td>
</tr>
<tr>
<td>msn</td>
<td>MSN transport</td>
</tr>
<tr>
<td>pager</td>
<td>Pager gateway</td>
</tr>
<tr>
<td>serverlist</td>
<td>A list of servers. It is assumed that this node has service/* children</td>
</tr>
<tr>
<td>sms</td>
<td>SMS gateway</td>
</tr>
<tr>
<td>smtp</td>
<td>SMTP gateway</td>
</tr>
<tr>
<td>yahoo</td>
<td>Yahoo! transport</td>
</tr>
<tr>
<td rowspan="6">user/</td>
<td> </td>
<td>Nodes of this category are Jabber users, typically implementing enough of the 'jabber:client' namespace to be compliant.</td>
</tr>
<tr>
<td>client</td>
<td>A standard or fully-featured Jabber client compliant with the 'jabber:client' namespace</td>
</tr>
<tr>
<td>forward</td>
<td>A forward alias</td>
</tr>
<tr>
<td>inbox</td>
<td>An alternate inbox</td>
</tr>
<tr>
<td>portable</td>
<td>A portable device implementing some of the 'jabber:client' namespace</td>
</tr>
<tr>
<td>voice</td>
<td>A node providing phone or voice access</td>
</tr>
<tr>
<td rowspan="4">validate/</td>
<td> </td>
<td>Validation services</td>
</tr>
<tr>
<td>grammar</td>
<td>Grammar-checking tool</td>
</tr>
<tr>
<td>spell</td>
<td>Spell-checking tool</td>
</tr>
<tr>
<td>xml</td>
<td>XML validator</td>
</tr>
</table>
<p>Historically each category was used as the name of an element, and the type was an attribute, such as <![CDATA[<service type="aim"/>]]>. The proper expression for all new implementations supporting this specification is to express the type information as attributes on a generic item element: <![CDATA[<item category="service" type="aim"/>]]>. 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.</p>
<p>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.</p>
</section1>
<section1 topic='The jabber:iq:browse Namespace'>
<p>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).</p>
<section2 topic='Browsing to a JabberID'>
<p>The common way to browse to a JabberID using IQ is:</p>
<example caption='Browsing to a JabberID'>
&lt;iq type="get" to="jer@jabber.org" id="browse1"/&gt;
&lt;query xmlns="jabber:iq:browse"/&gt;
&lt;/iq&gt;
</example>
</section2>
<section2 topic='Generic Attributes for Browse Results'>
<p>The item element has these attributes in a browse result:</p>
<ul>
<li>jid [required] -- The full JabberID of the entity described.</li>
<li>category [optional] -- One of the categories from the list above, or a non-standard category prefixed with the string "x-".</li>
<li>type [optional] -- One of the official types from the specified category, or a non-standard type prefixed with the string "x-".</li>
<li>name [optional] -- A friendly name that may be used in a user interface.</li>
<li>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).</li>
</ul>
</section2>
<section2 topic='Expressing Relationships'>
<p>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.</p>
<p>For example, this could be the result of browsing to jer@jabber.org:</p>
<example caption='Result of Browsing to a User'>
&lt;iq type="result" from="jer@jabber.org" id="browse1"&gt;
&lt;query
xmlns="jabber:iq:browse"
category="user"
jid="jer@jabber.org"
name="jer"&gt;
&lt;item
category="user"
jid="jer@jabber.org/foxy"
type="client"/&gt;
&lt;item
category="application"
jid="jer@jabber.org/chess"
name="XChess"/
type="game"&gt;
&lt;item
category="user"
jid="jer@jabber.org/palm"
type="client"/&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<p>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.</p>
<p>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.</p>
</section2>
<section2 topic='Namespace Advertising'>
<p>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 &#60;ns/&#62; element is allowed as a subelement of the item. This element contains a single namespace that the entity supports, and multiple &#60;ns/&#62; elements can be included in any item. For a connected client this might be &#60;ns&#62;jabber:iq:oob&#60;/ns&#62;, or for a service &#60;ns&#62;jabber:iq:search&#60;/ns&#62;. This list of namespaces should be used to present available options for a user or to automatically locate functionality for an application.</p>
<p>The children of a browse result may proactively contain a few &#60;ns/&#62; 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.</p>
<p>Clients should answer incoming browsing requests to advertise the namespaces they support.</p>
<example caption='Result of Browsing to a Resource'>
&lt;iq type="result" from="jer@jabber.org/foxy" id="browse2"&gt;
&lt;query
xmlns="jabber:iq:browse"
category="user"
jid="jer@jabber.org/foxy"
name="laptop"
type="client"&gt;
&lt;ns&gt;jabber:client&lt;/ns&gt;
&lt;ns&gt;jabber:iq:browse&lt;/ns&gt;
&lt;ns&gt;jabber:iq:conference&lt;/ns&gt;
&lt;ns&gt;jabber:iq:time&lt;/ns&gt;
&lt;ns&gt;jabber:iq:version&lt;/ns&gt;
&lt;ns&gt;jabber:x:roster&lt;/ns&gt;
&lt;ns&gt;jabber:x:signed&lt;/ns&gt;
&lt;ns&gt;jabber:x:encrypted&lt;/ns&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
</section2>
<section2 topic='Empty Results'>
<p>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.</p>
</section2>
</section1>
<section1 topic='Supplanting jabber:iq:agents'>
<p>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:</p>
<example caption='Result of Browsing to a Server'>
&lt;iq type="result" from="jabber.org" id="browse3"&gt;
&lt;query
xmlns="jabber:iq:browse"
category="service"
type="jabber"
jid="jabber.org"
name="Jabber.org Public Server"&gt;
&lt;ns&gt;jabber:client&lt;/ns&gt;
&lt;ns&gt;jabber:iq:browse&lt;/ns&gt;
&lt;ns&gt;jabber:iq:conference&lt;/ns&gt;
&lt;ns&gt;jabber:iq:time&lt;/ns&gt;
&lt;ns&gt;jabber:iq:version&lt;/ns&gt;
&lt;item
category="service"
jid="icq.jabber.org"
name="ICQ Transport"
type="icq"&gt;
&lt;ns&gt;jabber:iq:register&lt;/ns&gt;
&lt;ns&gt;jabber:iq:search&lt;/ns&gt;
&lt;ns&gt;jabber:iq:gateway&lt;/ns&gt;
&lt;/item&gt;
&lt;item
category="conference"
type="private"
jid="conference.jabber.org"
name="Private Chatrooms"/&gt;
&lt;item
category="application"
jid="jabber.org/help"
name="Assistance Agent"
type="bot"/&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<p>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.</p>
</section1>
<section1 topic='Implementation Notes'>
<p>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.</p>
</section1>
<section1 topic='Security Considerations'>
<p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<p>No action on the part of the &REGISTRAR; is necessary as a result of this JEP, since 'jabber:iq:browse' is already a registered protocol namespace.</p>
</section1>
<section1 topic='XML Schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:iq:browse'
xmlns='jabber:iq:browse'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0011: http://www.jabber.org/jeps/jep-0011.html
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:choice minOccurs='0' maxOccurs='unbounded'>
<xs:element ref='item'/>
<xs:element ref='ns'/>
</xs:choice>
<xs:attribute name='category' type='xs:string' use='optional'/>
<xs:attribute name='jid' type='xs:string' use='optional'/>
<xs:attribute name='name' type='xs:string' use='optional'/>
<xs:attribute name='type' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='item'>
<xs:complexType>
<xs:sequence>
<xs:element ref='ns' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='category' type='xs:string' use='optional'/>
<xs:attribute name='jid' type='xs:string' use='optional'/>
<xs:attribute name='name' type='xs:string' use='optional'/>
<xs:attribute name='type' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='ns' type='xs:string'/>
</xs:schema>
]]></code>
</section1>
<section1 topic='Future Considerations'>
<p>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.</p>
</section1>
</jep>

159
xep-0012.xml Normal file
View File

@ -0,0 +1,159 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Last Activity</title>
<abstract>This JEP defines a protocol for retrieving information about the last activity associated with a Jabber entity.</abstract>
&LEGALNOTICE;
<number>0012</number>
<status>Active</status>
<type>Historical</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>iq-last</shortname>
<schemaloc>
<url>http://jabber.org/protocol/iq-last/iq-last.xsd</url>
</schemaloc>
&jer;
&temas;
&stpeter;
<revision>
<version>1.1</version>
<date>2004-01-22</date>
<initials>psa</initials>
<remark>Editorial revisions.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-01-22</date>
<initials>psa</initials>
<remark>Changed status to Active.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-01-14</date>
<initials>psa</initials>
<remark>Made appropriate changes to reflect this JEP's status as informational.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-01-04</date>
<initials>tjm</initials>
<remark>JEP form for standardization.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2001-01-25</date>
<initials>jm</initials>
<remark>Initial version from website.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Basic Protocol'>
<p>The 'jabber:iq:last' namespace is used as the value of the 'xmlns' attribute of a &#60;query&#62; element contained within an &#60;iq/&#62; element. When requesting last activity information, a Jabber Entity sends an &#60;iq&#62; element of type='get' to another Jabber Entity (i.e., a JID). When responding to such a request, a Jabber Entity sends an &#60;iq&#62; element of type='result'. The &#60;query&#62; element never has any children and contains only one attribute and CDATA, depending on the scenario in which it is used.</p>
<p>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.</p>
</section1>
<section1 topic='Offline User Query'>
<p>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 &#60;query&#62; 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:</p>
<example caption='Offline User Last Query'><![CDATA[
<iq id='l4' type='get' to='user@host'>
<query xmlns='jabber:iq:last'/>
</iq>
<iq id='l4' type='result' from='user@host'>
<query xmlns='jabber:iq:last' seconds='903'>
Heading home
</query>
</iq>
]]></example>
<p>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 &lt;status/&gt; element contained the text "Heading home".</p>
<p>If the user has at least one available resource when the server receives the request, the response SHOULD contain an empty &lt;query/&gt; element whose 'seconds' attribute is set to a value of '0'.</p>
<p>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;).</p>
</section1>
<section1 topic='Online User Query'>
<p>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:</p>
<example caption='Online User Last Query'><![CDATA[
<iq id='l67' type='get' to='user@host/resource'>
<query xmlns='jabber:iq:last'/>
</iq>
<iq id='l67' type='result' from='user@host/resource'>
<query xmlns='jabber:iq:last' seconds='123'/>
</iq>
]]></example>
<p>In this example, the user has been idle for about two minutes.</p>
<p>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 <strong>XMPP IM</strong> in order to determine what error stanza to return.</p>
</section1>
<section1 topic='Server and Component Query'>
<p>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.</p>
<example caption='Server/Component Last Query'><![CDATA[
<iq id='l5' type='get' to='server'>
<query xmlns='jabber:iq:last'/>
</iq>
<iq id='l5' type='result' from='server'>
<query xmlns='jabber:iq:last' seconds='123456'/>
</iq>
]]></example>
<p>In this example, the server has been up for a little more than 34 hours.</p>
</section1>
<section1 topic='Security Considerations'>
<p>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 <strong>XMPP IM</strong> and further profiled in &jep0126;).</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<p>No action on the part of the &REGISTRAR; is necessary as a result of this JEP, since 'jabber:iq:last' is already a registered protocol namespace.</p>
</section1>
<section1 topic='XML Schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:iq:last'
xmlns='jabber:iq:last'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0012: http://www.jabber.org/jeps/jep-0012.html
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute
name='seconds'
type='xs:unsignedLong'
use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
<section1 topic='Future Considerations'>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section1>
</jep>

447
xep-0013.xml Normal file
View File

@ -0,0 +1,447 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Flexible Offline Message Retrieval</title>
<abstract>This JEP defines a protocol for flexible, POP3-like handling of offline messages in Jabber/XMPP.</abstract>
&LEGALNOTICE;
<number>0013</number>
<status>Draft</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>JEP-0030</spec>
<spec>JEP-0082</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>offline</shortname>
<schemaloc>
<url>http://jabber.org/protocol/offline/offline.xsd</url>
</schemaloc>
&stpeter;
<author>
<firstname>Craig</firstname>
<surname>Kaes</surname>
<email>ckaes@jabber.com</email>
<jid>ckaes@corp.jabber.com</jid>
</author>
<revision>
<version>1.2</version>
<date>2005-07-14</date>
<initials>psa</initials>
<remark>Added use case for retrieving number of messages; defined registar considerations more completely.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2004-01-22</date>
<initials>psa</initials>
<remark>Editorial revisions.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2003-09-09</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
</revision>
<revision>
<version>0.8</version>
<date>2003-08-25</date>
<initials>psa</initials>
<remark>More changes to address Council feedback: removed bandwidth rationale in requirements; added protocol flow section; adjusted semantics for node values (opaque, but dictionary ordering allowed). Also added &lt;fetch/&gt; and &lt;purge/&gt; elements.</remark>
</revision>
<revision>
<version>0.7</version>
<date>2003-08-21</date>
<initials>psa</initials>
<remark>Changes to address Council feedback: added error codes; enhanced the security considerations; clarified the nature of the node IDs and removed the protocol URI string (leaving only the timestamp).</remark>
</revision>
<revision>
<version>0.6</version>
<date>2003-06-10</date>
<initials>psa</initials>
<remark>Slight fixes to JEP-0082 reference and XML schema.</remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-04-28</date>
<initials>psa</initials>
<remark>Added reference to JEP-0082; changed timestamp format to use milliseconds rather than ten-thousandths of a second; made several small editorial changes throughout.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-02-27</date>
<initials>psa</initials>
<remark>Major overhaul: clarified requirements, incorporated disco, simplified and updated the protocol, specified syntax and semantics for nodes, defined business rules, and added XML schema.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-10-02</date>
<initials>cak</initials>
<remark>Reworked to exclude XDBID performace hack, thereby maximizing palatability. Removed all changes made by psa.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-10-02</date>
<initials>psa</initials>
<remark>Changed type and added information about scope.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-01-11</date>
<initials>cak</initials>
<remark>Initial version</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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:</p>
<ol>
<li><p>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.</p></li>
<li><p>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.</p></li>
</ol>
<p>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.</p>
<p>In particular, such a protocol should support the following use cases:</p>
<ol>
<li>Client determines server support for this protocol.</li>
<li>Client requests number of messages.</li>
<li>Client requests message "header" information (thereby choosing flexible offline message retrieval as opposed to old-fashioned "flood" mode).</li>
<li>Client retrieves specific messages.</li>
<li>Client removes specific messages.</li>
<li>Client retrieves all messages.</li>
<li>Client removes all messages.</li>
</ol>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Discovering Server Support' anchor='discover'>
<p>In order to discover whether one's server supports this protocol, one uses &jep0030;.</p>
<example caption='User Requests Service Discovery Information'><![CDATA[
<iq type='get' to='montague.net'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption='Server Reply to Discovery Request'><![CDATA[
<iq type='result'
from='montague.net'
to='romeo@montague.net/orchard'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
...
<feature var='http://jabber.org/protocol/offline'/>
...
</query>
</iq>
]]></example>
<p>If the server supports this protocol, it MUST return a &lt;feature/&gt; element in the disco result with the 'var' attribute set to the namespace name for this protocol: 'http://jabber.org/protocol/offline'.</p>
</section2>
<section2 topic='Requesting Number of Messages' anchor='request-number'>
<p><cite>RFC 1939</cite> 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.</p>
<p>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':</p>
<example caption='User Requests Information About Offline Message Node'><![CDATA[
<iq type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://jabber.org/protocol/offline'/>
</iq>
]]></example>
<p>If the server supports retrieval of the number of messages, it MUST include &jep0128; data specifying the number of messages:</p>
<example caption='Server Returns Information About Offline Message Node, Including Number of Messages'><![CDATA[
<iq type='result' to='romeo@montague.net/orchard'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://jabber.org/protocol/offline'>
<identity
category='automation'
type='message-list'/>
<feature var='http://jabber.org/protocol/offline'/>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/offline</value>
</field>
<field var='number_of_messages'>
<value>66</value>
</field>
</x>
</query>
</iq>
]]></example>
<p>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.</p>
</section2>
<section2 topic='Requesting Message Headers' anchor='request-headers'>
<p>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'.</p>
<example caption='User Requests Offline Message Headers'><![CDATA[
<iq type='get'>
<query xmlns='http://jabber.org/protocol/disco#items'
node='http://jabber.org/protocol/offline'/>
</iq>
]]></example>
<p>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.</p>
<example caption='Server Provides Offline Message Headers'><![CDATA[
<iq type='result' to='romeo@montague.net/orchard'>
<query xmlns='http://jabber.org/protocol/disco#items'
node='http://jabber.org/protocol/offline'>
<item
jid='romeo@montague.net'
node='2003-02-27T22:49:17.008Z'
name='mercutio@shakespeare.lit/pda'/>
<item
jid='romeo@montague.net'
node='2003-02-27T22:52:37.225Z'
name='juliet@capulet.com/balcony'/>
<item
jid='romeo@montague.net'
node='2003-02-27T22:52:51.270Z'
name='juliet@capulet.com/balcony'/>
<item
jid='romeo@montague.net'
node='2003-02-27T22:53:03.421Z'
name='juliet@capulet.com/balcony'/>
<item
jid='romeo@montague.net'
node='2003-02-27T22:53:13.925Z'
name='juliet@capulet.com/balcony'/>
</query>
</iq>
]]></example>
<p>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 &notfound; 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;.)</p>
<p>The syntax and semantics of the attributes are as follows:</p>
<ul>
<li>The 'jid' attribute is the Jabber ID with which the item nodes are associated, i.e., the user himself.</li>
<li>The 'name' attribute is the full JID of the sender as received in the 'from' address of the message itself.</li>
<li>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;).</li>
</ul>
</section2>
<section2 topic='Retrieving Specific Messages' anchor='retrieve-specific'>
<p>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.</p>
<example caption='User Requests Offline Messages'><![CDATA[
<iq type='get' id='view1'>
<offline xmlns='http://jabber.org/protocol/offline'>
<item action='view'
node='2003-02-27T22:52:37.225Z'/>
</offline>
</iq>
]]></example>
<p>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 &notfound; error. Otherwise, the server MUST send the requested message(s) plus an IQ result:</p>
<example caption='Server Provides Offline Messages'><![CDATA[
<message to='romeo@montague.net' from='juliet@capulet.com/balcony'>
<body>O Romeo, Romeo! wherefore art thou Romeo?</body>
<offline xmlns='http://jabber.org/protocol/offline'>
<item node='2003-02-27T22:52:37.225Z'/>
</offline>
</message>
<iq type='result' to='user@domain/resource' id='view1'/>
]]></example>
<p>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.</p>
</section2>
<section2 topic='Removing Specific Messages' anchor='remove-specific'>
<p>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.</p>
<p>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.</p>
<example caption='User Requests Removal of Offline Messages'><![CDATA[
<iq type='set' id='remove1'>
<offline xmlns='http://jabber.org/protocol/offline'>
<item action='remove'
node='2003-02-27T22:49:17.008Z'
<item action='remove'
node='2003-02-27T22:52:37.225Z'/>
</offline>
</iq>
]]></example>
<p>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 &notfound; error. Otherwise, the server MUST remove the messages and inform the user:</p>
<example caption='Server Informs User of Removal'><![CDATA[
<iq type='result' to='romeo@montague.net/orchard' id='remove1'/>
]]></example>
</section2>
<section2 topic='Retrieving All Messages' anchor='retrieve-all'>
<p>The user retrieves all message by sending the "fetch" command:</p>
<example caption='User Retrieval of All Offline Messages'><![CDATA[
<iq type='get' id='fetch1'>
<offline xmlns='http://jabber.org/protocol/offline'>
<fetch/>
</offline>
</iq>
]]></example>
<p>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 &notfound; error. Otherwise, the server MUST retrieve all messages and inform the user:</p>
<example caption='Server Sends All Messages and Informs User of Successful Fetch'><![CDATA[
<message to='romeo@montague.net' from='juliet@capulet.com/balcony'>
<body>O Romeo, Romeo! wherefore art thou Romeo?</body>
<offline xmlns='http://jabber.org/protocol/offline'>
<item node='2003-02-27T22:52:37.225Z'/>
</offline>
</message>
...
<iq type='result' to='romeo@montague.net/orchard' id='fetch1'/>
]]></example>
<p>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.</p>
</section2>
<section2 topic='Removing All Messages' anchor='remove-all'>
<p>The user removes all message by sending the "purge" command:</p>
<example caption='User Requests Removal of Offline Messages'><![CDATA[
<iq type='set' id='purge1'>
<offline xmlns='http://jabber.org/protocol/offline'>
<purge/>
</offline>
</iq>
]]></example>
<p>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 &notfound; error. Otherwise, the server MUST remove all messages and inform the user:</p>
<example caption='Server Informs User of Successful Purge'><![CDATA[
<iq type='result' to='romeo@montague.net/orchard' id='purge1'/>
]]></example>
</section2>
</section1>
<section1 topic='Protocol Flow' anchor='flow'>
<p>This section shows the flow of protocol between client (C:) and server (S:) for the existing (flood) scenario and the improved (POP3-like) scenario.</p>
<example caption='Existing Protocol Flow (Flood)'><![CDATA[
C: <stream:stream ...>
S: <stream:stream ...>
C: authentication (SASL in XMPP, non-SASL in older systems)
S: acknowledge successful authentication
C: <presence/>
S: send message flood to Client
C: receive flood, send and receive messages, etc.
... and so on]]></example>
<p>The semantics change with POP-like offline message handling, and server behavior changes as well...</p>
<example caption='Improved Protocol Flow (POP3-Like)'><![CDATA[
C: <stream:stream ...>
S: <stream:stream ...>
C: authentication (SASL in XMPP, non-SASL in older systems)
S: acknowledge successful authentication
C: request message headers
S: send message headers to Client
NOTE: Server now MUST NOT flood Client with offline messages.
C: <presence/>
NOTE: Server does not flood Client with offline messages, but
sends in-session messages as usual.
C: request and remove offline messages, send and receive messages, etc.
... and so on]]></example>
</section1>
<section1 topic='Security Considerations' anchor='sec'>
<p>A server MUST NOT deliver a user's offline messages to any JID except one of the user's authorized resources.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; includes 'http://jabber.org/protocol/offline' in its registry of protocol namespaces.</p>
</section2>
<section2 topic='Service Discovery Identities' anchor='registrar-disco-identity'>
<p>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:</p>
<table caption='Types for Category "automation"'>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>message-list</td>
<td>The node for the offline message queue; valid only for the node "http://jabber.org/protocol/offline".</td>
</tr>
<tr>
<td>message-node</td>
<td>A node for a specific offline message if service discovery is provided for messages.</td>
</tr>
</table>
<p>The registry submission is as follows:</p>
<code caption='Registry Submission'><![CDATA[
<type>
<name>message-list</name>
<desc>
The node for the offline message queue; valid only for the node
"http://jabber.org/protocol/offline"
</desc>
<doc>JEP-0013</doc>
</type>
<type>
<name>message-node</name>
<desc>A node for a specific offline message if service discovery is provided for messages</desc>
<doc>JEP-0013</doc>
</type>
</category>
]]></code>
</section2>
<section2 topic='Well-Known Service Discovery Nodes' anchor='registrar-disco-nodes'>
<p>The Jabber Registrar includes "http://jabber.org/protocol/offline" in its registry of well-known Service Discovery nodes.</p>
</section2>
<section2 topic='Field Standardization' anchor='registrar-formtype'>
<p>&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 <link url='#request-number'>Requesting Number of Messages</link> section of this JEP. The registry submission is as follows:</p>
<code caption='Registry Submission'><![CDATA[
<form_type>
<name>http://jabber.org/protocol/offline</name>
<doc>JEP-0013</doc>
<desc>
Service Discovery extension for number of messages
in an offline message queue.
</desc>
<field
var='number_of_messages'
type='text-single'
label='N/A'/>
</form_type>
]]></code>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/offline'
xmlns='http://jabber.org/protocol/offline'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0013: http://www.jabber.org/jeps/jep-0013.html
</xs:documentation>
</xs:annotation>
<xs:element name='offline'>
<xs:complexType>
<xs:sequence>
<xs:element ref='item' minOccurs='1' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='item'>
<xs:complexType>
<xs:attribute name='action' use='optional'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='remove'/>
<xs:enumeration value='view'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name='jid' type='xs:string' use='optional'/>
<xs:attribute name='node' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</jep>

70
xep-0014.xml Normal file
View File

@ -0,0 +1,70 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Message Tone</title>
<abstract>A proposal for including the sender's tone in messages.</abstract>
&LEGALNOTICE;
<number>0014</number>
<status>Rejected</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<author>
<firstname>Mike</firstname>
<surname>Mintz</surname>
<email>psicoder@yahoo.com</email>
<jid>mikem@jabber.org</jid>
</author>
<revision>
<version>0.2</version>
<date>2002-01-16</date>
<initials>psa</initials>
<remark>First release to CVS, including editorial changes by the JEP Editor and assignment of JEP number.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2001-11-17</date>
<initials>mm</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
</section1>
<section1 topic='Protocol Implementation'>
<p>Tone can be added only to messages, and it is added as an &#60;x&#62; tag inside a message. The &#60;x&#62; tag will look something like this:</p>
<example>
&#60;x xmlns='jabber:x:tone'&#62;angry&#60;/x&#62;
</example>
<p>The specified tone is included as CDATA within the &#60;x&#62; element.</p>
<section2 topic='Example'>
<p>Here is an example of a message with a tone:</p>
<example>
&#60;message to='mikem@jabber.org'&#62;
&#60;body&#62;
Why the hell did they reject my idea?
&#60;/body&#62;
&#60;x xmlns='jabber:x:tone'&#62;angry&#60;/x&#62;
&#60;/message&#62;
</example>
</section2>
</section1>
<section1 topic='Representing Tones'>
<p>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.</p>
<p>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.</p>
<p>Tones should be short and simple. Here is a list of good tones:</p>
<ul>
<li>angry</li>
<li>confused</li>
<li>excited</li>
<li>joking</li>
<li>sad</li>
<li>sarcastic</li>
<li>serious</li>
</ul>
</section1>
</jep>

258
xep-0015.xml Normal file
View File

@ -0,0 +1,258 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Account Transfer</title>
<abstract>A proposal for enabling the ability to transfer an account from one Jabber server to another.</abstract>
&LEGALNOTICE;
<number>0015</number>
<status>Rejected</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<author>
<firstname>Casey</firstname>
<surname>Crabb</surname>
<email>crabbkw@nafai.dyndns.org</email>
<jid>airog@floobin.cx</jid>
</author>
<revision>
<version>0.4</version>
<date>2002-04-18</date>
<initials>cwc</initials>
<remark>Cleaned up the open issues and concerns section.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-04-16</date>
<initials>cwc</initials>
<remark>Added more specific details to the protocol. Added more examples. Tried to make the whole JEP more readable.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-02-26</date>
<initials>cwc</initials>
<remark>Setting scope, adding discussion about using jabber:iq:browse in the future for transports</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-01-24</date>
<initials>cwc</initials>
<remark>Added more pseudo-protocol information. Added a known issues section.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-01-16</date>
<initials>psa</initials>
<remark>First release to CVS, including editorial changes by the JEP Editor and assignment of JEP number.</remark>
</revision>
<revision>
<version>0.9</version>
<date>2001-12-04</date>
<initials>cwc</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
<p>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. </p>
</section1>
<section1 topic='Main Body'>
<p>A basic overview of the behavior would be as follows.</p>
<section2 topic='Preconditions'>
<ul>
<li>Bob has a jabber account on a server, floobin.cx
specifically: olduser@floobin.cx.</li>
<li>Bob knows that the floobin.cx server is going to go down soon
and therefore needs to find a new jabber server.</li>
<li>He realizes that jabber.org offers accounts to anyone, so he
sets out to migrate his account to jabber.org.</li>
<li>Bob does not yet have an account on jabber.org.</li>
</ul>
</section2>
<section2 topic='Order of events'>
<p>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.</p>
<ol>
<li>Bob creates an account on Jabber.org:
bobsnewaccount@jabber.org.</li>
<li>Bob logs into both bobsnewaccount@jabber.org and
olduser@floobin.cx.</li>
<li>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.</li>
<li>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.</li>
<li>bobsnewsaccount@jabber.org receives the 'user wants to
migrate account to you' packet and authorizes the
transfer.</li>
<li>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.</li>
<li>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.</li>
<li>finally floobin.cx informs olduser@floobin.cx that the
transfer was completed.</li>
</ol>
</section2>
<section2 topic='Protocol Example'>
<example caption="User initiates process">
&#60;iq id='initacctxfer' to='floobin.cx' from='airog@floobin.cx' type='ask'&#62;
&#60;query xmlns='jabber:iq:accountxfer'&#62;
&#60;oldaccount&#62;airog@jabber.org&#60;/oldaccount&#62;
&#60;newaccount&#62;newaccount@jabber.org&#60;/newaccount&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<example caption='Server asks for permission from newaccount@jabber.org'>
&#60;iq id='acctxfer1' type='ask' from='floobin.cx' to='newaccount@jabber.org'&#62;
&#60;query xmlns='jabber:iq:accountxfer'&#62;
&#60;oldaccount&#62;airog@jabber.org&#60;/oldaccount&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<example caption="XML received at user's new account">
&#60;iq id='acctxfer1' type='ask' from='floobin.cx' to='newaccount@jabber.org'&#62;
&#60;query xmlns='jabber:iq:accountxfer'&#62;
&#60;oldaccount&#62;airog@jabber.org&#60;/oldaccount&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<example caption="newaccount@jabber.org accepts the migration">
&#60;iq id='acctxfer1' type='result' to='floobin.cx' from='newaccount@jabber.org'&#62;
&#60;query xmlns='jabber:iq:accountxfer'&#62;
&#60;allowed/&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<p>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.</p>
<example caption="XML sent to each JID subscribed to airog@floobin.cx's presence">
&#60;iq id='acctxferss1' type='set' from='floobin.cx' to='jabber.org'&#62;
&#60;query xmlns='jabber:iq:accountxfer'&#62;
&#60;oldaccount&#62;airog@jabber.org&#60;/oldaccount&#62;
&#60;newaccount&#62;newaccount@jabber.org&#60;/newaccount&#62;
&#60;rosteritem jid='frienduser@jabber.org'/&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<example caption="The server hosting the account of the roster item responds">
&#60;iq id='acctxferss1' type='result' to='floobin.cx' from='jabber.org'/&#62;
</example>
<p>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:</p>
<example caption="airog@floobin.cx's roster is transferred into newuser@jabber.org's roster">
&#60;iq type='set' id='acctxferss2' from='floobin.cx' to='jabber.org'&#62;
&#60;query xmlns='jabber:iq:accountxfer'&#62;
&#60;oldaccount&#62;airog@jabber.org&#60;/oldaccount&#62;
&#60;newaccount&#62;newaccount@jabber.org&#60;/newaccount&#62;
&#60;item jid='frienduser@jabber.org' name='friend1' subscription='both'/&#62;
&#60;item jid='annoyuser@jabber.org' ask='subscribe'/&#62;
&#60;item jid='someone@jabber.org' subscription='from'/&#62;
&#60;/query&#62;
&#60;/iq&#62;
</example>
<example caption="floobin.cx responds saying the roster transfer was successful">
&#60;iq type='set' id='acctxferss2' to='floobin.cx' from='jabber.org'&#62;
</example>
<p>Once the migration finishes a notification is sent to the user:</p>
<example caption="Process completed">
&#60;iq id='initacctxfer' from='floobin.cx' to='airog@floobin.cx' type='result'/&#62;
</example>
</section2>
</section1>
<section1 topic='Open Issues, Concerns and Scoping'>
<section2 topic='How do we handle transferring transport stuff?'>
<p>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.</p>
<p>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.</p>
</section2>
<section2 topic='Empty Pointer Accounts'>
<p>Does the server keep an empty account that redirects requests
to the new account? I've been hearing mass rumblings of 'NO'
here.</p>
</section2>
<section2 topic='vCards and private storage data'>
<p>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?</p>
<p>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.</p>
<p> 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.</p>
</section2>
</section1>
</jep>

236
xep-0016.xml Normal file
View File

@ -0,0 +1,236 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Server-Based Privacy Rules</title>
<abstract>Note: This JEP has been superseded by the XMPP IM Internet-Draft; please refer to that document for the most up-to-date protocol.</abstract>
&LEGALNOTICE;
<number>0016</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>None</dependencies>
<supersedes>None</supersedes>
<supersededby>XMPP IM</supersededby>
<shortname>None</shortname>
&pgmillard;
<revision>
<version>1.3</version>
<date>2004-07-26</date>
<initials>psa</initials>
<remark>Formally retracted this proposal in favor of XMPP IM.</remark>
</revision>
<revision>
<version>1.2</version>
<date>2003-03-12</date>
<initials>psa</initials>
<remark>Changed status to Deprecated since this protocol is now included in the XMPP IM Internet-Draft.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2002-11-17</date>
<initials>pgm</initials>
<remark>Added remarks about default handling, and where list processing should take place.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-10-22</date>
<initials>psa</initials>
<remark>Changed status to Draft.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2002-10-03</date>
<initials>pgm</initials>
<remark>Elaborated on various JID possibilities.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-07-31</date>
<initials>pgm</initials>
<remark>Added info describing current session issues</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-07-30</date>
<initials>pgm</initials>
<remark>Added whitelists, subscription filtering, and multiple list capabilities. Changed block to deny.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-01-18</date>
<initials>pgm</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic="Introduction">
<p><em>Note: This JEP has been superseded by &xmppim;; please refer to that document for the most up-to-date protocol!</em></p>
<p>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:</p>
<ol>
<li>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.</li>
<li>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.</li>
<li>Most implementations have no way of blocking specific types of packets -- they typically block only message packets.</li>
</ol>
<p>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).</p>
</section1>
<section1 topic="Protocol Details">
<p>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 &lt;query/&gt; element as a direct child under the main &lt;iq/&gt; element. A client application would use &lt;iq type="get"&gt; to retrieve the lists from the server, and use &lt;iq type="set"&gt; 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 &quot;zebra lists&quot;.</p>
<p>Each &lt;query/&gt; element would have one or more &lt;list&gt; elements which would contain the information for an entire zebra list. The &lt;query&gt; element also contains an &lt;active&gt; element and a &lt;default&gt; 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 &lt;active&gt; element and/or and empty &lt;default&gt; 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.</p>
<p>The &lt;default&gt; 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.</p>
<p>Each &lt;item&gt; 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 &lt;item&gt; elements missing.</p>
<p>If the &lt;item&gt; 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. </p>
<p>If the &lt;item&gt; element contains no child elements, then all packets would be blocked or allowed. This includes: messages, presence packets, and iq packets. The &lt;item&gt; elements MAY contain the following empty child elements:</p>
<ul>
<li>The &lt;message/&gt; element (blocks or allows all message packets).</li>
<li>The &lt;presence/&gt; element (blocks or allows all presence packets).</li>
<li>The &lt;iq/&gt; element (blocks or allows all iq packets).</li>
</ul>
<p>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 &lt;error/&gt; element with a code attribute of 405.</p>
<p>If a &lt;list&gt; 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.</p>
</section1>
<section1 topic="Implementation Notes and Rules">
<p>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.
</p>
<p>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 &lt;item&gt; 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 &lt;active&gt; element indicating the new currently active list. If no &lt;active&gt; element is sent, the currently active list is used.</p>
<p>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 &lt;active&gt; element. If the named list does not exist, the server MUST send back an error using error code 406 (Not Acceptable).</p>
<p>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.</p>
<p>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 &lt;iq/&gt; as a type="error" using an error code of 406 (Not Acceptable).</p>
<p>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.</p>
<p>When a jabber ID is specified on a rule and the ID does not conform to user@host, the following rules apply:</p>
<ul>
<li>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'</li>
<li>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.</li>
<li>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'.)</li>
</ul>
<p>If a packet does not match any rules in the active list, the default action is to allow.</p>
</section1>
<section1 topic="Retrieving the zebra lists">
<p>The following protocol segments illustrate the exchange of packets between the client application and the server in order to retrieve the zebra list information.</p>
<example caption="Client Requests the zebra lists"><![CDATA[
<iq type="get" id="1">
<query xmlns="jabber:iq:privacy"/>
</iq>]]></example>
<example caption="Server Replies to the zebra lists request"><![CDATA[
<iq type="result" id="1">
<query xmlns="jabber:iq:privacy">
<active name="home"/>
<list name="home">
<item jid="romeo@jabber.org" type="deny"/>
<item jid="juliet@jabber.org" type="deny"/>
<item type="allow"/>
</list>
<list name="work">
<item type="allow" subscription="from"/>
<item type="allow" subscription="to"/>
<item type="deny"/>
</list>
</query>
</iq>]]></example>
</section1>
<section1 topic="Changing the currently active zebra list">
<p>The following protocol segments illustrate the exchange of packets used to change the active zebra list.</p>
<example caption="Client changes active list"><![CDATA[
<iq type="set" id="2">
<query xmlns="jabber:iq:privacy">
<active name="work"/>
</query>
</iq>]]></example>
<example caption="Server Replies to the change request">
&lt;iq type="result" id="2"/&gt;
</example>
</section1>
<section1 topic="Adding or Changing a zebra list">
<p>The following protocol segments illustrate the exchange of packets used to add or edit a zebra list.</p>
<example caption="Changing a zebra list"><![CDATA[
<iq type="set" id="3">
<query xmlns="jabber:iq:privacy">
<list name="home">
<item jid="romeo@jabber.org" type="deny"/>
<item jid="juliet@jabber.org" type="deny"/>
<item jid="mercutio@jabber.org" type="deny"/>
<item type="allow"/>
</list>
</query>
</iq>]]></example>
<example caption="Server Replies to the change request">
&lt;iq type="result" id="3"/&gt;
</example>
</section1>
<section1 topic="Removing an entire zebra list">
<p>The following protocol segments illustrate how a client application would remove a zebra list.</p>
<example caption="Client Requests Removal of a zebra list"><![CDATA[
<iq type="set" id="4">
<query xmlns="jabber:iq:privacy">
<list name="home"/>
</query>
</iq>]]></example>
<example caption="Server replies to remove request">
&lt;iq type="result" id="4"/&gt;
</example>
</section1>
<section1 topic="Blocked User Sending a Message">
<p>The following protocol segments illustrate the exchange of message packets when the sender is blocked by the currently active zebra list.</p>
<example caption="Blocked User Sends a Message"><![CDATA[
<message to="jill@jabber.org" id="msg_1">
<body>Hey, I just wanted to chat!</body>
</message>]]></example>
<example caption="Recipient's Server Bounces Message Back to Blocked Sender"><![CDATA[
<message id="msg_1" type="error">
<body>Hey, I just wanted to chat!</body>
<error code="405">Not Allowed</error>
</message>]]></example>
</section1>
<section1 topic="Protocol DTD">
<example caption="jabber:iq:privacy DTD"><![CDATA[<!ELEMENT query (active?, list*)>
<!ATTLIST query
xmlns CDATA #REQUIRED
>
<!ELEMENT active (#PCDATA)>
<!ATTLIST active
name CDATA #REQUIRED
>
<!ELEMENT list (item*)>
<!ATTLIST list
name CDATA #REQUIRED
>
<!ELEMENT item (iq?, message?, presence?)>
<!ATTLIST item
jid CDATA #IMPLIED
type (allow | deny) #REQUIRED
subscription (from | to) #IMPLIED
>
<!Element iq (#PCDATA)>
<!Element message (#PCDATA)>
<!Element presence (#PCDATA)>
]]></example>
</section1>
<section1 topic="Future considerations">
<p>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:</p>
<example caption="Client Requests to Filter a Specific IQ Namespace"><![CDATA[<iq type="set" id="6">
<query xmlns="jabber:iq:privacy">
<list name="home">
<item jid="romeo@jabber.org" type="deny"/>
<item jid="juliet@jabber.org" type="deny"/>
<item jid="mercutio@jabber.org" type="deny">
<iq>jabber:iq:oob</iq>
<item type="allow"/>
</list>
</query>
</iq>]]></example>
<example caption="Server Replies to Filter Namespace Request">
&lt;iq type="result" id="6"/&gt;
</example>
<p>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.</p>
<p>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).</p>
</section1>
<section1 topic='Author Note' anchor='authornote'>
<p>Peter Millard, the author of this specification from version 0.1 through version 0.3, died on April 26, 2006.</p>
</section1>
</jep>

83
xep-0017.xml Normal file
View File

@ -0,0 +1,83 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Naive Packet Framing Protocol</title>
<abstract>An intermediate method for more efficient framing of the Jabber XML Stream.</abstract>
<legal>This document has been placed in the public domain.</legal>
<number>0017</number>
<status>Rejected</status>
<type>Informational</type>
<jig>Standards JIG</jig>
<author>
<firstname>Mike</firstname>
<surname>Lin</surname>
<email>mikelin@mit.edu</email>
<jid>mlin@mlin.mit.edu</jid>
</author>
<author>
<firstname>Julian</firstname>
<surname>Missig</surname>
<email>julian@jabber.org</email>
<jid>julian@jabber.org</jid>
</author>
<revision>
<version>0.3</version>
<date>2002-02-19</date>
<initials>mfl</initials>
<remark>Continued improvement and specification.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-01-31</date>
<initials>mfl</initials>
<remark>Added various clarifications and implementation notes.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-01-23</date>
<initials>mfl</initials>
<remark>Initial revision.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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 &lt;stream:stream&gt; document consisting of a direct (depth=1) child element of the &lt;stream:stream&gt; 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.</p>
<p>This JEP describes a framing method that may provide performance and code simplicity advantages over the framing method currently used.</p>
</section1>
<section1 topic='Framing in Jabber'> <p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Byte Length Framing'>
<p>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.</p>
<p>This technique has the following advantages:</p>
<ul>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>This technique has the following disadvantages:</p>
<ul>
<li>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.</li>
<li>Error-handling semantics must be arbitrarily defined in the event that a transmitting agent misframes a packet (that is, sends the incorrect packet size).</li>
</ul>
</section1>
<section1 topic='Implementation Notes'>
<p>Framing data is included for the &lt;stream:stream&gt; and &lt;/stream:stream&gt; 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.</p>
<p>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 &lt;) and, if it is detected, activate outgoing framing for that session.</p>
<p>Regardless of the use of framing data, all nodes must verify the well-formedness of XML payloads in order to avoid propagating misframes.</p>
</section1>
<section1 topic='Example'>
<example caption='A Trivial And Nearly Meaningless Example'>
94&lt;message to="whomever@mlin.mit.edu" from="mlin@mlin.mit.edu"&gt;some opaque information&lt;/message&gt;
</example>
</section1>
<section1 topic='Philosophical Notes and Conclusion'>
<p>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).</p>
</section1>
</jep>

135
xep-0018.xml Normal file
View File

@ -0,0 +1,135 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Invisible Presence</title>
<abstract>Documentation of invisible presence.</abstract>
&LEGALNOTICE;
<number>0018</number>
<status>Rejected</status>
<type>Informational</type>
<jig>Standards JIG</jig>
<dependencies>XMPP Core, XMPP IM</dependencies>
<supersedes>None</supersedes>
<supersededby>None</supersededby>
<shortname>N/A</shortname>
<author>
<firstname>Ben</firstname>
<surname>Schumacher</surname>
<email>ben@blahr.com</email>
<jid>rynok@jabber.com</jid>
</author>
<author>
<firstname>Jeremie</firstname>
<surname>Miller</surname>
<email>jer@jabber.org</email>
<jid>jer@jabber.org</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-09-26</date>
<initials>bs</initials>
<remark>Updated to focus solely on &lt;presence type='invisible'/&gt;.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-01-28</date>
<initials>jmm</initials>
<remark>Initial draft.</remark>
</revision>
</header>
<section1 topic="Introduction">
<p>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.</p>
<p><strong>Note well:</strong> 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.</p>
</section1>
<section1 topic="Requirements">
<p>The requirements for invisible mode are basic:</p>
<ol>
<li>A user should be able to become visible or invisible at any time.</li>
<li>When in either mode, users should be able to selectively allow or block presence updates to be distributed to their contacts.</li>
</ol>
</section1>
<section1 topic="Use Cases">
<p>For the purposes of this discussion, we will assume this terminology.</p>
<ul>
<li>Undirected Presence - A presence stanza without a "to" attribute.</li>
<li>Directed Presence - A presence stanza with a "to" attribute.</li>
</ul>
<section2 topic="User Becomes Invisible to All Contacts">
<p>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.</p>
<example caption="Invisible presence stanza"><![CDATA[<presence type="invisible"/>]]></example>
</section2>
<section2 topic="User Becomes Visible to All Contacts">
<p>If a user chooses to become visible after being invisible, the client will send undirected presence with a type="visible" attribute.</p>
<example caption="Visible presence stanza"><![CDATA[<presence type="visible"/>]]></example>
</section2>
<section2 topic="User Becomes Invisible to Selected Contact">
<p>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.</p>
<example caption="User becomes invisible to joe@foo.com"><![CDATA[<presence to="joe@foo.com" type="invisible"/>]]></example>
<p>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.</p>
<example caption="User becomes visible to joe@foo.com"><![CDATA[<presence to="joe@foo.com" type="visible"/>]]></example>
</section2>
<section2 topic="User Becomes Visible to Selected Contact">
<p>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.</p>
<p>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).</p>
</section2>
</section1>
<section1 topic="Server Implementation Details">
<p>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.</p>
<p>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.</p>
<section2 topic="Undirected Presence While Invisible to Selected Contacts">
<p>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.</p>
<p>Consider the following situation (the protocol for which is shown in the examples below):</p>
<ol>
<li>joe@foo.com has contacts stpeter@foo.com, pgmillard@foo.com and rynok@foo.com on his roster.</li>
<li>joe@foo.com has logged into the foo.com sever, but has set his presence to invisible.</li>
<li>Assume that stpeter@foo.com, pgmillard@foo.com and rynok@foo.com are all online and visible.</li>
<li>joe@foo.com wants rynok@foo.com to see his presence updates, but not stpeter@foo.com or pgmillard@foo.com</li>
<li>joe@foo.com sets his presence to extended away.</li>
<li>joe@foo.com decides to become visible to all contacts on his roster.</li>
<li>joe@foo.com decides to become invisible to pgmillard@foo.com.</li>
<li>joe@foo.com set his presence to free to chat.</li>
</ol>
<example caption="joe@foo.com sends initial presence stanza"><![CDATA[<presence type="invisible"/>]]></example>
<p>Since joe@foo.com has just come online, the server SHOULD NOT forward any presence stanzas to contacts on his roster.</p>
<example caption="joe@foo.com sends visible presence to rynok@foo.com"><![CDATA[<presence to="rynok@foo.com" type="visible"/>]]></example>
<example caption="Server forwards presence update to rynok@foo.com"><![CDATA[<presence from="joe@foo.com/resource" to="rynok@foo.com"/>]]></example>
<example caption="joe@foo.com sets his presence to extended away"><![CDATA[<presence><show>xa</show><status>Away (due to idle)</status></presence>]]></example>
<example caption="Server forwards presence update to rynok@foo.com"><![CDATA[<presence from="joe@foo.com/resource" to="rynok@foo.com">
<show>away</show><status>Meeting</status>
</presence>]]></example>
<p>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.</p>
<example caption="joe@foo.com sends undirected visible stanza"><![CDATA[<presence type="visible"/>]]></example>
<example caption="Server forwards last presence update to stpeter@foo.com and pgmillard@foo.com"><![CDATA[<presence from="joe@foo.com/resource" to="stpeter@foo.com"/>
<presence from="joe@foo.com/resource" to="pgmillard@foo.com"/>]]></example>
<p>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.</p>
<example caption="joe@foo.com sends directed presence stanza to pgmillard@foo.com"><![CDATA[<presence to="pgmillard@foo.com" type="invisible"/>]]></example>
<p>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."</p>
<example caption="Server sends unavailable presence stanza to pgmillard@foo.com"><![CDATA[<presence from="joe@foo.com/resource" to="pgmillard@foo.com" type="unavailable"/>]]></example>
<p>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.</p>
<example caption="joe@foo.com set his presence to free to chat"><![CDATA[<presence><show>chat</show></presence>]]></example>
<example caption="Server forwards presence update to stpeter@foo.com and rynok@foo.com"><![CDATA[<presence from="joe@foo.com/resource" to="stpeter@foo.com">
<show>chat</show>
</presence>
<presence from="joe@foo.com/resource" to="rynok@foo.com/resource">
<show>chat</show>
</presence>]]></example>
<p>The server MUST NOT forward presence stanzas containing the type="visible" or type="invisible" attribute to a client.</p>
</section2>
</section1>
<section1 topic="Security Considerations">
<p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic="IANA Considerations">
<p>No interaction with &IANA; is required as a result of this JEP.</p>
</section1>
<section1 topic="Jabber Registrar Considerations">
<p>No namespaces or parameters need to be registered with the &REGISTRAR; as a result of this JEP.</p>
</section1>
</jep>

81
xep-0019.xml Normal file
View File

@ -0,0 +1,81 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type="text/xsl" href="../jep.xsl"?>
<jep>
<header>
<title>Streamlining the JIGs</title>
<abstract>This JEP proposes to streamline the existing Jabber Interest Groups (JIGs).</abstract>
&LEGALNOTICE;
<number>0019</number>
<status>Active</status>
<type>Procedural</type>
<jig>None</jig>
<approver>Board</approver>
<dependencies/>
<supersedes/>
<supersededby/>
<author>
<firstname>Peter</firstname>
<surname>Saint-Andre</surname>
<email>stpeter@jabber.org</email>
<jid>stpeter@jabber.org</jid>
</author>
<revision>
<version>1.0</version>
<date>2002-03-20</date>
<initials>psa</initials>
<remark>Changed status to Active.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-03-06</date>
<initials>psa</initials>
<remark>Minor revisions.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-02-24</date>
<initials>psa</initials>
<remark>Initial release.</remark>
</revision>
</header>
<section1 topic="Introduction">
<p>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). <note>The proposal contained in this JEP formalizes some conclusions reached during a weekly discussion forum held by the Jabber Software Foundation on 2002-01-23. A log of that discussion is available at <link url="http://www.jabber.org/chatbot/logs/conference.jabber.org/foundation/2002-01-23.html">http://www.jabber.org/chatbot/logs/conference.jabber.org/foundation/2002-01-23.html</link>. Further discussion within the Standards JIG has been helpful in clarifying the argument presented here.</note></p>
</section1>
<section1 topic="The Problem">
<p>JEP-0002 <note>URL: <link url='http://www.jabber.org/jeps/jep-0002.html'>http://www.jabber.org/jeps/jep-0002.html</link></note> defined a JIG as "a working group approved by the Jabber Council to address specific areas of growth or concern within the Jabber community", and specified that the function of a JIG is to "produce acceptable enhancements to the Jabber protocol (delivered in the form of Jabber Enhancement Proposals or JEPs) within a reasonably limited period of time". In early January of 2002, JEP-0002 was modified to incorporate language about disbanding a JIG after a defined period of inactivity on the JIG's mailing list (normally six months).</p>
<p>Unfortunately, it is widely recognized in the Jabber community that the JIGs are not working. Ten JIGs have been approved by the Jabber Council,<note>See <link url='http://www.jabber.org/jigs.html'>http://www.jabber.org/jigs.html</link> for the official list.</note> eight of them over six months ago in July and August of 2001. Two of the special-purpose JIGs (OOB and Presence) have seen no activity whatsoever and thus are clearly eligible to be disbanded. The other special-purpose JIGs (Conference, Formatting, Forms, Profiles, RPC, and Whiteboard) have seen extremely limited activity and it is a judgment call whether some of them should be allowed to continue according to the current standards defined in JEP-0002. Only the two "standing" JIGs (Security and Standards) have experienced significant and continued mailing list activity, mainly because the Standards JIG has assumed the role of discussion forum for JEPs before they are submitted to the Jabber Council.</p>
<p>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 <note>URL: <link url='http://www.jabber.org/jeps/jep-0009.html'>http://www.jabber.org/jeps/jep-0009.html</link></note> for transporting XML-RPC over Jabber) was essentially created outside the JIG structure at JabberCon 2001. Perhaps most ominously, no other JIG has shown any signs of progress toward completing a JEP, or even starting work on one. With the possible exception of JEP-0009, all of the JEPs created so far have come from individuals or small, ad-hoc groups -- not through the efforts of the JIGs.</p>
<p>In other words, an honest assessment forces us to conclude that the JIGs are not working.</p>
</section1>
<section1 topic="Analysis and Possible Solutions">
<p>I see several possible solutions to the JIG problem:</p>
<ol>
<li>"Crack the whip" -- encourage and cajole the existing JIGs into becoming more active, and energetically manage them so that they produce JEPs.</li>
<li>"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).</li>
<li>"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.</li>
</ol>
<p>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.</p>
<p>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.</p>
<p>I see several reasons why the JIGs are not working:</p>
<ol>
<li>The Jabber community right now is too small to be split up successfully into smaller interest groups.</li>
<li>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.</li>
<li>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.</li>
</ol>
<p>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.</p>
</section1>
<section1 topic="Proposed Solution">
<p>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:</p>
<ol>
<li>Immediately disband all but the Standards JIG. <note>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.</note></li>
<li>Rely on individuals and small, ad-hoc groups to create JEPs.</li>
<li>Continue to use the Standards JIG as the preferred forum for discussion of experimental JEPs before they are submitted to the Jabber Council.</li>
<li>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. <note>One option would be to send interested parties off to their own ad-hoc mailing list (e.g., on JabberStudio, <link url="http://www.jabberstudio.org/">http://www.jabberstudio.org/</link>). 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.</note></li>
</ol>
<p>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. <note>Lest there be any concern that disbanding the JIGs is outside the power or purview of the Jabber Council, I note that Section 8.2 of the Bylaws of the Jabber Software Foundation states in part that "The Jabber Council or the Members of the Corporation may, by resolution, ... terminate a Jabber Interest Group at any time for any reason." (An electronic copy of the Bylaws may be found at <link url="http://www.jabber.org/bylaws.html">http://www.jabber.org/bylaws.html</link>.)</note></p>
</section1>
</jep>

296
xep-0020.xml Normal file
View File

@ -0,0 +1,296 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Feature Negotiation</title>
<abstract>This JEP defines a A protocol that enables two Jabber entities to mutually negotiate feature options.</abstract>
&LEGALNOTICE;
<number>0020</number>
<status>Draft</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>JEP-0004</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>feature-neg</shortname>
<schemaloc>
<url>http://jabber.org/protocol/feature-neg/feature-neg.xsd</url>
</schemaloc>
&pgmillard;
&stpeter;
<revision>
<version>1.4</version>
<date>2004-05-21</date>
<initials>psa</initials>
<remark>Moved remaining feature negotiation text from JEP-0030 to this document.</remark>
</revision>
<revision>
<version>1.3</version>
<date>2004-04-23</date>
<initials>psa</initials>
<remark>Per Council discussion, changed root element from &lt;query/&gt; to &lt;feature/&gt; for the sake of consistency with using protocols; moved some text from JEP-0030 to this document.</remark>
</revision>
<revision>
<version>1.2</version>
<date>2004-03-08</date>
<initials>psa</initials>
<remark>Added XMPP error handling; clarified the text; corrected the examples; fixed an error in the schema; added numerous references.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2003-02-16</date>
<initials>psa</initials>
<remark>Made corrections to the text; added security and IANA considerations; added schema.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-12-06</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, revision 0.4 was advanced to Draft on 2002-12-06.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2002-11-17</date>
<initials>pgm</initials>
<remark>Changed protocol to use jabber:x:data.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-10-01</date>
<initials>pgm</initials>
<remark>Added some extra text to help clarify protocol &amp; purpose.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-05-22</date>
<initials>pgm</initials>
<remark>Changed examples.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-02-26</date>
<initials>pgm</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic="Introduction" anchor='intro'>
<p>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;).</p>
<p>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.</p>
</section1>
<section1 topic="Protocol Details" anchor='protocol'>
<p>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. <note>Earlier versions of this JEP defined an structured data format to handle the feature negotiation workflow; versions later than 0.4 use <strong>Data Forms</strong>, i.e., the 'jabber:x:data' namespace.</note></p>
<p>In order to begin a negotation, the initiator sends an &IQ; stanza of type "get" to the recipient with a single &lt;feature/&gt; 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.</p>
<p>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".</p>
<p>The following examples show some likely scenarios for feature negotiation between entities. Further examples can be found in using protocols, such as &jep0096;.</p>
<section2 topic="Basic Flow" anchor='protocol-basic'>
<p>A typical negotiation flow is shown in the following example of two entities negotiating the time and place for a meeting.</p>
<example caption="Initiating entity sends offer"><![CDATA[
<iq type='get'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='neg1'>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'>
<field type='list-single' var='places-to-meet'>
<option><value>Lover's Lane</value></option>
<option><value>Secret Grotto</value></option>
<option><value>Verona Park</value></option>
</field>
<field type='list-single' var='times-to-meet'>
<option><value>22:00</value></option>
<option><value>22:30</value></option>
<option><value>23:00</value></option>
<option><value>23:30</value></option>
</field>
</x>
</feature>
</iq>
]]></example>
<example caption="Responding entity sends preferred option values"><![CDATA[
<iq type='result'
id='neg1'
from='juliet@jabber.org/balcony'
to='romeo@montague.net/orchard'>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='places-to-meet'>
<value>Secret Grotto</value>
</field>
<field var='times-to-meet'>
<value>22:30</value>
</field>
</x>
</feature>
</iq>
]]></example>
<p>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 &lt;text/&gt; element.</p>
<example caption="Responding entity does not support a feature"><![CDATA[
<iq type='error'
id='neg1'
from='juliet@jabber.org/balcony'
to='romeo@montague.net/orchard'>
<error code='501' type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>times-to-meet</text>
</error>
</iq>
]]></example>
<p>If the responding entity supports none of the options offered for a certain feature, it MUST return a &notacceptable; error, and SHOULD specify the relevant feature in the XMPP &lt;text/&gt; element.</p>
<example caption="Responding entity supports no options"><![CDATA[
<iq type='error'
from='juliet@jabber.org/balcony'
to='romeo@montague.net/orchard'
id='neg1'>
<error code='406' type='modify'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>places-to-meet</text>
</error>
</iq>
]]></example>
</section2>
<section2 topic="Querying for Negotiable Features" anchor='protocol-query'>
<p>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 &lt;feature var='http://jabber.org/protocol/feature-neg'/&gt; as one of the features.</p>
<example caption='Client queries a chatroom for supported features'><![CDATA[
<iq type='get'
from='juliet@capulet.com/balcony'
to='balconyscene@plays.shakespeare.lit'
id='neg1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
<example caption='Chatroom returns supported features'><![CDATA[
<iq type='result'
from='balconyscene@plays.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='neg1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://jabber.org/protocol/feature-neg'/>
<feature var='muc-password'/>
...
</query>
</iq>]]></example>
<p>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.</p>
<example caption='Client queries a chatroom for supported features'><![CDATA[
<iq type='get'
from='juliet@capulet.com/balcony'
to='balconyscene@plays.shakespeare.lit'
id='neg1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
<example caption='Chatroom returns supported features'><![CDATA[
<iq type='result'
from='balconyscene@plays.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='neg1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://jabber.org/protocol/feature-neg'/>
<feature var='muc-password'/>
...
</query>
</iq>]]></example>
<p>The using protocol (in these examples, <cite>JEP-0045</cite>) 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 &lt;<link url='http://www.jabber.org/registrar/disco-vars.html'>http://www.jabber.org/registrar/disco-vars.html</link>&gt;). However, the requesting entity MAY also query the responding entity in order to determine which features are negotiable, as shown below.</p>
<example caption='Client queries chatroom regarding options for a negotiable feature'><![CDATA[
<iq type='get'
from='juliet@capulet.com/balcony'
to='balconyscene@plays.shakespeare.lit'
id='neg2'>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='muc-password'/>
</x>
</feature>
</iq>]]></example>
<p>If that feature is not negotiable, the responding entity MUST return a "Feature Not Implemented" error:</p>
<example caption='Chatroom returns error'><![CDATA[
<iq type='result'
from='balconyscene@plays.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='neg2'>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='result'>
<field var='muc-password' type='list-single'>
<option><value>cleartext</value></option>
<option><value>SHA1</value></option>
<option><value>SASL</value></option>
</field>
</x>
</feature>
<error code='501' type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>]]></example>
<p>If that feature is negotiable, the responding entity MUST return an appropriate negotiation form:</p>
<example caption='Chatroom returns negotiation form'><![CDATA[
<iq type='result'
from='balconyscene@plays.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='neg2'>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='result'>
<field var='muc-password' type='list-single'>
<option><value>cleartext</value></option>
<option><value>SHA1</value></option>
<option><value>SASL</value></option>
</field>
</x>
</feature>
</iq>]]></example>
<p>The requesting entity MAY then submit a data form containing the required information.</p>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>Security considerations are the responsibility of the using protocol.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic="Jabber Registrar Considerations" anchor='registrar'>
<p>In order for Jabber entities to adequately leverage <strong>Data Forms</strong> (e.g., by using machine-readable fields), it is RECOMMENDED to register standard x-data fields with the &REGISTRAR; via the mechanisms defined in &jep0068;. Whether to do so for any given features and options shall be determined by the using protocol.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/feature-neg'
xmlns='http://jabber.org/protocol/feature-neg'
elementFormDefault='qualified'>
<xs:import
namespace='jabber:x:data'
schemaLocation='http://jabber.org/protocol/x-data/x-data.xsd'/>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0020: http://www.jabber.org/jeps/jep-0020.html
</xs:documentation>
</xs:annotation>
<xs:element name='feature'>
<xs:complexType>
<xs:sequence xmlns:data='jabber:x:data'>
<xs:element ref='data:x'/>
</xs:sequence>
</xs:complexType>
</xs:schema>
]]></code>
</section1>
<section1 topic='Author Note' anchor='authornote'>
<p>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.</p>
</section1>
</jep>

343
xep-0021.xml Normal file
View File

@ -0,0 +1,343 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Jabber Event Notification Service (ENS)</title>
<abstract>A generic publish-and-subscribe service for Jabber.</abstract>
&LEGALNOTICE;
<number>0021</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards</jig>
<supersedes>None</supersedes>
<supersededby>JEP-0060</supersededby>
<shortname>None</shortname>
<author>
<firstname>Robert</firstname>
<surname>Norris</surname>
<email>rob@cataclysm.cx</email>
<jid>rob@cataclysm.cx</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-04-22</date>
<initials>psa</initials>
<remark>At the request of the author, the status of this JEP has been changed to Retracted since it has been superseded by JEP-0060. This JEP will not be considered further by the Jabber Software Foundation and should not be used as a basis for implementations.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-03-04</date>
<initials>rn</initials>
<remark>Initial version</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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:</p>
<ul>
<li>User has logged in</li>
<li>A new message has arrived</li>
<li>User's avatar has changed</li>
<li>The coffee machine is empty</li>
</ul>
<p>In Jabber, the role of the ENS has traditionally been filled by overloading the &lt;presence/&gt; packet type. However, this method was never designed to be used as a general publish-and-subscribe mechanism, and so has the following problems:</p>
<ul>
<li>Dispatching of &lt;presence/&gt; 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).</li>
<li>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 &lt;presence/&gt; in situations where large chunks of data must be dispatched to subscribers (eg avatars).</li>
</ul>
<p>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.</p>
<p>The protocol operates in the 'http://xml.cataclysm.cx/jabber/ens/' namespace.</p>
<p>A reference implementation is available at <link url='http://cataclysm.cx/jabber/ens.html'>http://cataclysm.cx/jabber/ens.html</link>.</p>
</section1>
<section1 topic='Definitions'>
<p>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.</p>
<section2 topic='Event'>
<p>An event can be defined as a change to the value of one or more properties of a resource.</p>
<p>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:</p>
<ul>
<li>rob@imap.cataclysm.cx/NewMessage</li>
<li>joe@imap.cataclysm.cx/DeletedMessage</li>
<li>jim@imap.cataclysm.cx/FiledMessage</li>
</ul>
<p>Alternatively, an end-user client that wanted to notify the ENS when its avatar changes might do so using a JID like &quot;rob@cataclysm.cx/avatar&quot;</p>
</section2>
<section2 topic='Subscriber'>
<p>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.</p>
<p>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.
</p>
<p>Once subscribed to an event, the subscriber will receive any notifications that the publisher sends about that event.</p>
</section2>
<section2 topic='Publisher'>
<p>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 &quot;payload&quot; 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.</p>
<p>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.</p>
</section2>
</section1>
<section1 topic='Subscriber protocol'>
<section2 topic='Subscription request'>
<p>To subscribe to a particular event, the subscriber sends a packet like of the following form to the ENS:</p>
<example caption='Subscription request'>
&lt;iq id='sub1' type='set' from='subscriber-jid' to='ens-jid'&gt;
&lt;subscribe xmlns='http://xml.cataclysm.cx/jabber/ens/' jid='event-jid'/&gt;
&lt;/iq&gt;
</example>
<section3 topic='Option: &lt;auth-info/&gt;'>
<p>The subscriber may include an &lt;auth-info/&gt; XML fragment containing some (application-specific) information that the publisher can use to authorise it:</p>
<example caption='Subscription request with authorisation information'>
&lt;iq id='sub2' type='set' from='subscriber-jid' to='ens-jid'&gt;
&lt;subscribe xmlns='http://xml.cataclysm.cx/jabber/ens/' jid='event-jid'&gt;
&lt;auth-info xmlns='jabber:iq:auth'&gt;password&lt;/auth-info&gt;
&lt;/subscribe&gt;
&lt;/iq&gt;
</example>
</section3>
<section3 topic='Option: &lt;reliable/&gt;'>
<p>If it wishes, the subscriber may request a &quot;reliable&quot; 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.</p>
<example caption='Reliable subscription request'>
&lt;iq id='sub2' type='set' from='subscriber-jid' to='ens-jid'&gt;
&lt;subscribe xmlns='http://xml.cataclysm.cx/jabber/ens/' jid='event-jid'&gt;
&lt;reliable/&gt;
&lt;/subscribe&gt;
&lt;/iq&gt;
</example>
</section3>
</section2>
<section2 topic='Subscription response'>
<p>Once subscribed, the ENS will return a packet of the following form to the subscriber:</p>
<example caption='Successful subscription response'>
&lt;iq id='sub1' type='result' from='ens-jid' to='subscriber-jid'&gt;
&lt;subscribed xmlns='http://xml.cataclysm.cx/jabber/ens/' jid='event-jid'/&gt;
&lt;/iq&gt;
</example>
<p>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:</p>
<example caption='Failed subscription response'>
&lt;iq id='sub1' type='error' from='ens-jid' to='subscriber-jid'&gt;
&lt;subscribe xmlns='http://xml.cataclysm.cx/jabber/ens/' jid='event-jid'/&gt;
&lt;error code='401'&gt;Unauthorized&lt;/error&gt;
&lt;/iq&gt;
</example>
<p>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.</p>
</section2>
<section2 topic='Unsubscription request'>
<p>To unsubscribe from a particular event, the subscriber sends a packet like of the following form to the ENS:</p>
<example caption='Unsubscription request'>
&lt;iq id='unsub1' type='set' from='subscriber-jid' to='ens-jid'&gt;
&lt;unsubscribe xmlns='http://xml.cataclysm.cx/jabber/ens/' jid='event-jid'/&gt;
&lt;/iq&gt;
</example>
</section2>
<section2 topic='Unsubscription response'>
<p>Once unsubscribed, the ENS will return a packet of the following form to the subscriber:</p>
<example caption='Unsubscription response'>
&lt;iq id='unsub1' type='result' from='ens-jid' to='subscriber-jid'&gt;
&lt;unsubscribed xmlns='http://xml.cataclysm.cx/jabber/ens/' jid='event-jid'/&gt;
&lt;/iq&gt;
</example>
<p>No further notifications for the event will be received.</p>
</section2>
<section2 topic='Publish'>
<p>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:</p>
<example caption='Event notification (publish)'>
&lt;iq id='enspub1' type='set' from='ens-jid' to='subscriber-jid'&gt;
&lt;publish xmlns='http://xml.cataclysm.cx/jabber/ens/' jid='event-jid'/&gt;
&lt;/iq&gt;
</example>
<p>A notification may also contain a (application-specific) &quot;payload&quot; XML fragment:</p>
<example caption='Event notification (publish) with payload'>
&lt;iq id='enspub2' type='set' from='ens-jid' to='subscriber-jid'&gt;
&lt;publish xmlns='http://xml.cataclysm.cx/jabber/ens/' jid='event-jid'&gt;
&lt;xml-payload/&gt;
&lt;/publish&gt;
&lt;/iq&gt;
</example>
<p>Section 4.1 has more information about the payload.</p>
<p>If the subscriber responds to the notification with an error, the subscriber will be automatically unsubscribed from the event by the ENS.</p>
</section2>
<section2 topic='Publish response (reliable subscriptions)'>
<p>If the &lt;reliable/&gt; 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:</p>
<example caption='Event notification (publish) response'>
&lt;iq id='enspub1' type='result' from='subscriber-jid' to='ens-jid'&gt;
&lt;published xmlns='http://xml.cataclysm.cx/jabber/ens/'/&gt;
&lt;/iq&gt;
</example>
<p>If the subscriber does not respond, or responds with an error, the notification will be resent by the ENS after a (implementation-specific) timeout.</p>
</section2>
</section1>
<section1 topic='Publisher protocol'>
<section2 topic='Publish'>
<p>To publish a notification, the publisher sends a packet of the following form to the ENS:</p>
<example caption='Event notification (publish)'>
&lt;iq id='pub1' type='set' from='event-jid' to='ens-jid'&gt;
&lt;publish xmlns='http://xml.cataclysm.cx/jabber/ens/'/&gt;
&lt;/iq&gt;
</example>
<p>A notification may also contain a (application-specific) &quot;payload&quot; XML fragment:</p>
<example caption='Event notification (publish) with payload'>
&lt;iq id='pub1' type='set' from='event-jid' to='ens-jid'&gt;
&lt;publish xmlns='http://xml.cataclysm.cx/jabber/ens/'&gt;
&lt;xml-payload/&gt;
&lt;/publish&gt;
&lt;/iq&gt;
</example>
<p>The payload can be any well-formed XML data. Everything inside the &lt;publish/&gt; tag will be forwarded untouched to the subscriber.</p>
</section2>
<section2 topic='Publish response'>
<p>Once the ENS has dispatched the notification to subscribers, it will return a packet of the following form to the publisher:</p>
<example caption='Event notification (publish) response'>
&lt;iq id='pub1' type='result' from='ens-jid' to='event-jid'&gt;
&lt;published xmlns='http://xml.cataclysm.cx/jabber/ens/'/&gt;
&lt;/iq&gt;
</example>
</section2>
<section2 topic='Authorisation request'>
<p>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:</p>
<example caption='Authorisation request'>
&lt;iq id='ensauth1' type='get' from='ens-jid' to='event-jid'&gt;
&lt;authorise xmlns='http://xml.cataclysm.cx/jabber/ens/' jid='subscriber-jid'/&gt;
&lt;/iq&gt;
</example>
<p>The subscriber may include an &lt;auth-info/&gt; XML fragment containing some (application-specific) information that the publisher can use to authorise it:</p>
<example caption='Authorisation request with authorisation information'>
&lt;iq id='ensauth1' type='get' from='ens-jid' to='event-jid'&gt;
&lt;authorise xmlns='http://xml.cataclysm.cx/jabber/ens/' jid='subscriber-jid'&gt;
&lt;auth-info xmlns='jabber:iq:auth'&gt;password&lt;/auth-info&gt;
&lt;/authorise&gt;
&lt;/iq&gt;
</example>
</section2>
<section2 topic='Authorisation response'>
<p>To signal to the ENS that a subscriber should be allowed to subscribe, the publisher should return a packet of the following form:</p>
<example caption='Successful authorisation response'>
&lt;iq id='ensauth1' type='result' from='event-jid' to='ens-jid'&gt;
&lt;authorised xmlns='http://xml.cataclysm.cx/jabber/ens/' jid='subscriber-jid'/&gt;
&lt;/iq&gt;
</example>
<p>To deny the subscription, the publisher should return an error packet, containing the appropriate &lt;error/&gt; fragment:</p>
<example caption='Unsuccessful authorisation response'>
&lt;iq id='ensauth1' type='error' from='event-jid' to='ens-jid'&gt;
&lt;authorise xmlns='http://xml.cataclysm.cx/jabber/ens/' jid='subscriber-jid'/&gt;
&lt;error code='401'&gt;Unauthorized&lt;/error&gt;
&lt;/iq&gt;
</example>
<p>The &lt;error/&gt; fragment will be copied untouched into the error response sent back to the subscriber. See section 3.2 for more details.</p>
</section2>
</section1>
<section1 topic='Errors'>
<p>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).</p>
<p>Other errors may occur, and they are described in the appropriate sections of the above protocol specification.</p>
</section1>
<section1 topic='Considerations'>
<p>The following items should be discussed before this proposal is approved by the Council:</p>
<section2 topic='ENS discovery'>
<p>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.</p>
<p>There are several potential solutions, each with their problems:</p>
<ul>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>This problem may be outside of the scope of this specification.</p>
</section2>
<section2 topic='How reliable should &lt;reliable/&gt; be?'>
<p>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).</p>
<p>At what point should even &lt;reliable/&gt; 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?</p>
<p>&lt;reliable/&gt; is an interesting idea, but it may be that it is too problematic for its own good.</p>
</section2>
<section2 topic='Longevity of subscriptions'>
<p>The topic of reliable subscriptions raises the question as to how long a subscription lasts. Should a subscription last forever (like &lt;presence/&gt; does), even across restarts of the server?</p>
<p>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.</p>
</section2>
<section2 topic='Replacing &lt;presence/&gt; with the ENS?'>
<p>As I see it, basic presence will always be a function of the session manager, for the following reasons:</p>
<ul>
<li>No ENS discovery problems</li>
<li>Subscriptions are maintained across sessions</li>
<li>In very widespread use (ie. everywhere)</li>
</ul>
<p>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 - &quot;you have new mail&quot;, &quot;someone has scheduled a meeting with you in your online calendar&quot;, etc).</p>
</section2>
</section1>
</jep>

321
xep-0022.xml Normal file
View File

@ -0,0 +1,321 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Message Events</title>
<abstract>This JEP defines protocol extensions used to request and respond to events relating to the delivery, display, and composition of messages.</abstract>
&LEGALNOTICE;
<number>0022</number>
<status>Active</status>
<type>Historical</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>x-event</shortname>
<schemaloc>
<url>http://jabber.org/protocol/x-event/x-event.xsd</url>
</schemaloc>
&jer;
<author>
<firstname>DJ</firstname>
<surname>Adams</surname>
<email>dj.adams@pobox.com</email>
<jid>dj@gnu.mine.nu</jid>
</author>
&stpeter;
<revision>
<version>1.3</version>
<date>2004-01-06</date>
<initials>psa</initials>
<remark>Added XML schema.</remark>
</revision>
<revision>
<version>1.2</version>
<date>2003-02-11</date>
<initials>psa</initials>
<remark>Attempted to clarify usage and business rules.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2003-01-26</date>
<initials>psa</initials>
<remark>Added more detailed information and clarified a few points.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-05-08</date>
<initials>psa</initials>
<remark>Changed status to Active.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-03-13</date>
<initials>dja</initials>
<remark>Minor corrections and additions.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-03-05</date>
<initials>dja</initials>
<remark>Initial draft.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>The 'jabber:x:event' namespace defines extensions used to request and respond to events relating to the delivery, display, and composition of messages.</p>
<p>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.</p>
</section1>
<section1 topic='The Events'>
<p>There are four message events currently defined in this namespace:</p>
<section2 topic='Offline'>
<p>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.</p>
</section2>
<section2 topic='Delivered'>
<p>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.</p>
</section2>
<section2 topic='Displayed'>
<p>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.</p>
</section2>
<section2 topic='Composing'>
<p>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.</p>
</section2>
</section1>
<section1 topic='Usage'>
<p>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.</p>
<p>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.</p>
<p>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 &lt;offline/&gt; tag should be removed from the extension.</p>
<section2 topic='Requesting Event Notifications'>
<p>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 &lt;offline/&gt;, &lt;delivered/&gt;, &lt;displayed/&gt;, and &lt;composing/&gt;.</p>
<p>An example of a &MESSAGE; element with a jabber:x:event extension is shown here.</p>
<example caption='Requesting notification of offline storage and delivery for a message'><![CDATA[
<message to='romeo@montague.net' id='message22'>
<body>Art thou not Romeo, and a Montague?</body>
<x xmlns='jabber:x:event'>
<offline/>
<delivered/>
<composing/>
</x>
</message>
]]></example>
<p>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.</p>
<p>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.</p>
</section2>
<section2 topic='Raising Events'>
<p>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:</p>
<example caption='Raising the offline event'><![CDATA[
<message
from='romeo@montague.net'
to='juliet@capulet.com/balcony'>
<x xmlns='jabber:x:event'>
<offline/>
<id>message22</id>
</x>
</message>
]]></example>
<p>When raising an event, the raiser must send a &MESSAGE; element constructed according to the following rules:</p>
<ul>
<li>The element must contain only a jabber:x:event extension. Standard message elements such as &lt;subject/&gt;, &lt;body/&gt;, MUST NOT be included.</li>
<li>The extension must contain one tag representing the event being raised. For example, if the offline event is being raised, an &lt;offline/> tag must be included. (The events are temporally exclusive, thus only one event tag should ever be included.)</li>
<li>The extension must also contain an &lt;id/&gt; tag. The contents of this tag MUST be the value of the 'id' <em>attribute</em> of the original message to which this event notification pertains. (If no 'id' attribute was included in the original message, then the &lt;id/&gt; tag must still be included with no CDATA.)</li>
<li>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.)</li>
<li>The link between the original message for which the event is being raised, and the message containing that raised event, is the &lt;id/&gt; tag in the jabber:x:event extension of the message containing that raised event, that points to the id attribute of the original message.</li>
</ul>
</section2>
<section2 topic='The Composing Event'>
<p>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.</p>
<p>The cancellation is raised by sending another jabber:x:event; however, in contrast to how the events are usually raised, no &lt;composing/&gt; tag is sent, just an &lt;id/&gt; tag, like this:</p>
<example caption='Romeo begins to compose a reply'><![CDATA[
<message
from='romeo@montague.net'
to='juliet@capulet.com/balcony'>
<x xmlns='jabber:x:event'>
<composing/>
<id>message22</id>
</x>
</message>
]]></example>
<example caption='Romeo pauses to reflect before answering, thus cancelling the composing event'><![CDATA[
<message
from='romeo@montague.net'
to='juliet@capulet.com/balcony'>
<x xmlns='jabber:x:event'>
<id>message22</id>
</x>
</message>
]]></example>
<p>The lack of an &lt;composing/&gt; 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.</p>
</section2>
</section1>
<section1 topic='Examples'>
<p>This section contains a number of examples to illustrate the full flow of messages, event notifications, and event cancellations for a fictional conversation.</p>
<example caption='Juliet sends a message to Romeo and requests all event types'><![CDATA[
SEND: <message to='romeo@montague.net' id='message22'>
<body>Art thou not Romeo, and a Montague?</body>
<x xmlns='jabber:x:event'>
<offline/>
<delivered/>
<displayed/>
<composing/>
</x>
</message>
]]></example>
<p>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.</p>
<example caption='Receiving the offline event'><![CDATA[
RECV: <message
from='romeo@montague.net'
to='juliet@capulet.com/balcony'>
<x xmlns='jabber:x:event'>
<offline/>
<id>message22</id>
</x>
</message>
]]></example>
<p>Romeo reconnects and the message is delivered to his Jabber client, which generates a delivered event and sends it to Juliet's client.</p>
<example caption='Juliet receives notification of message delivery'><![CDATA[
RECV: <message
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'>
<x xmlns='jabber:x:event'>
<delivered/>
<id>message22</id>
</x>
</message>
]]></example>
<p>Romeo's Jabber client displays the message and sends a displayed event to Juliet's client.</p>
<example caption='Juliet receives notification of message display'><![CDATA[
RECV: <message
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'>
<x xmlns='jabber:x:event'>
<displayed/>
<id>message22</id>
</x>
</message>
]]></example>
<p>Romeo begins composing a reply to Juliet's heartfelt question, and his Jabber client notifies Juliet that he is composing a reply.</p>
<example caption='Juliet receives notification of message composing'><![CDATA[
RECV: <message
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'>
<x xmlns='jabber:x:event'>
<composing/>
<id>message22</id>
</x>
</message>
]]></example>
<p>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.</p>
<example caption='Juliet receives cancellation of message composing'><![CDATA[
RECV: <message
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'>
<x xmlns='jabber:x:event'>
<id>message22</id>
</x>
</message>
]]></example>
<p>Romeo starts composing again, and his Jabber client sends a notification to Juliet's client.</p>
<example caption='Juliet receives a second notification of message composing'><![CDATA[
RECV: <message
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'>
<x xmlns='jabber:x:event'>
<composing/>
<id>message22</id>
</x>
</message>
]]></example>
<p>Romeo finally sends his reply, and requests composing events related to it.</p>
<example caption='Romeo replies'><![CDATA[
SEND: <message to='juliet@capulet.com' id='GabberMessage43'>
<body>Neither, fair saint, if either thee dislike.</body>
<x xmlns='jabber:x:event'>
<composing/>
</x>
</message>
]]></example>
</section1>
<section1 topic='Implementation Notes'>
<p>Compliant implementations SHOULD observe the following business rules:</p>
<ol>
<li>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.</li>
<li>When a client receives a request for events from another entity, it should cache the most recent ID.</li>
<li>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 &lt;id/&gt; element to the cached ID value.</li>
<li>The CDATA of the &lt;id/&gt; element MUST be the same as the value of the 'id' attribute of the notification request.</li>
</ol>
</section1>
<section1 topic='Security Considerations'>
<p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<p>No action on the part of the &REGISTRAR; is necessary as a result of this JEP, since 'jabber:x:event' is already a registered protocol namespace.</p>
</section1>
<section1 topic='XML Schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:x:event'
xmlns='jabber:x:event'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0022: http://www.jabber.org/jeps/jep-0022.html
</xs:documentation>
</xs:annotation>
<xs:element name='x'>
<xs:complexType>
<xs:sequence>
<xs:element name='offline' minOccurs='0' type='empty'/>
<xs:element name='delivered' minOccurs='0' type='empty'/>
<xs:element name='displayed' minOccurs='0' type='empty'/>
<xs:element name='composing' minOccurs='0' type='empty'/>
<xs:element name='id' minOccurs='0' type='xs:NMTOKEN'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
<section1 topic='Open Issues'>
<ol>
<li>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).</li>
</ol>
</section1>
</jep>

175
xep-0023.xml Normal file
View File

@ -0,0 +1,175 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Message Expiration</title>
<abstract>This JEP documents an historical protocol that was used to specify expiration dates for messages; this protocol has been deprecated in favor of JEP-0079: Advanced Message Processing.</abstract>
&LEGALNOTICE;
<number>0023</number>
<status>Deprecated</status>
<type>Historical</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby>
<spec>JEP-0079</spec>
</supersededby>
<shortname>x-expire</shortname>
<schemaloc>
<url>http://jabber.org/protocol/x-expire/x-expire.xsd</url>
</schemaloc>
&jer;
<author>
<firstname>DJ</firstname>
<surname>Adams</surname>
<email>dj.adams@pobox.com</email>
<jid>dj@gnu.mine.nu</jid>
</author>
<author>
<firstname>Harold</firstname>
<surname>Gottschalk</surname>
<email>heg@imissary.com</email>
<jid>heg@imissary.com</jid>
</author>
<revision>
<version>1.2</version>
<date>2004-10-18</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, changed status to Deprecated since message expiration functionality should be implemented via JEP-0079: Advanced Message Processing.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2004-01-06</date>
<initials>psa</initials>
<remark>Added XML schema; added security, IANA, and Jabber Registrar considerations.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-07-15</date>
<initials>psa</initials>
<remark>Changed status to Active.</remark>
</revision>
<revision>
<version>0.9</version>
<date>2002-03-19</date>
<initials>dja</initials>
<remark>Added remarks about client-end expiry.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-03-07</date>
<initials>dja</initials>
<remark>Initial draft.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p><em>Note Well: The protocol described herein has been deprecated by the &JSF;. The recommended protocol for implementing message expiration functionality is now &jep0079;.</em></p>
<p>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.</p>
<p>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:</p>
<ul>
<li>The sender of the message is responsible for attaching a jabber:x:expire extension to the XML stanza (usually a message).</li>
<li>Mechanisms involved in the store-and-forward of such a stanza
<note>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.</note>
en route to its intended recipient are responsible for checking the remaining time to live and expiring (discarding) the XML stanza if necessary.</li>
</ul>
</section1>
<section1 topic='Specifying a TTL'>
<p>An Endpoint can specify a TTL for an XML stanza that it wishes to send by attaching an &lt;x/&gt; 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.</p>
<example caption='Specifying a 30-minute TTL for a message'>
SEND: &lt;message to='sabine@gnu.mine.nu' id='msg811'&gt;
&lt;subject&gt;Eccles cakes!&lt;/subject&gt;
&lt;body&gt;
I've got some freshly made Eccles cakes here, come
round for one before they all disappear!
&lt;/body&gt;
&lt;x xmlns='jabber:x:expire' seconds='1800'/&gt;
&lt;/message&gt;
</example>
</section1>
<section1 topic='Handling XML Stanzas with a TTL'>
<p>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 &lt;x/&gt; 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'.</p>
<p>Here we see what the original message looks like after the stanza has been committed to storage and the time of storage recorded:</p>
<example caption='Recording a storage-time in the extension'>
SEND: &lt;message to='sabine@gnu.mine.nu' id='msg811'&gt;
&lt;subject&gt;Eccles cakes!&lt;/subject&gt;
&lt;body&gt;
I've got some freshly made Eccles cakes here, come
round for one before they all disappear!
&lt;/body&gt;
&lt;x xmlns='jabber:x:expire'
seconds='1800'
stored='912830221'/&gt;
&lt;/message&gt;
</example>
<p>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!</p>
<section2 topic='Usage in client space'>
<p>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.</p>
</section2>
</section1>
<section1 topic='Security Considerations'>
<p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<p>No action on the part of the &REGISTRAR; is necessary as a result of this JEP, since 'jabber:x:expire' is already a registered protocol namespace.</p>
</section1>
<section1 topic='XML Schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:x:expire'
xmlns='jabber:x:expire'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0023: http://www.jabber.org/jeps/jep-0023.html
</xs:documentation>
</xs:annotation>
<xs:element name='x'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='seconds' type='xs:unsignedLong' use='required'/>
<xs:attribute name='stored' type='xs:unsignedLong' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
<section1 topic='Open Issues'>
<ol>
<li>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.</li>
<li>A physical, time-based TTL is not implemented by this JEP, and would not be possible across systems without synchronized time.</li>
</ol>
</section1>
</jep>

1132
xep-0024.xml Normal file
View File

File diff suppressed because it is too large Load Diff

386
xep-0025.xml Normal file
View File

@ -0,0 +1,386 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Jabber HTTP Polling</title>
<abstract>This document defines a protocol that enables access to a Jabber server from behind firewalls which do not allow outgoing sockets on port 5222, via HTTP requests.</abstract>
&LEGALNOTICE;
<number>0025</number>
<status>Deprecated</status>
<type>Historical</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby>
<spec>JEP-0124</spec>
</supersededby>
<shortname>httppoll</shortname>
&hildjj;
<author>
<firstname>Craig</firstname>
<surname>Kaes</surname>
<email>ckaes@jabber.com</email>
<jid>ckaes@corp.jabber.com</jid>
</author>
<author>
<firstname>David</firstname>
<surname>Waite</surname>
<email>mass@akuma.org</email>
<jid>mass@akuma.org</jid>
</author>
<revision>
<version>1.1</version>
<date>2006-07-26</date>
<initials>psa</initials>
<remark><p>Per a vote of the Jabber Council, changed status to Deprecated.</p></remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-10-11</date>
<initials>psa</initials>
<remark><p>Per a vote of the Jabber Council, advanced status to Active.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-09-23</date>
<initials>dew</initials>
<remark><p>Changed format to allow socket-equivalent security.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-03-14</date>
<initials>jjh</initials>
<remark><p>Initial version.</p></remark>
</revision>
</header>
<section1 topic="Introduction">
<p><em>Note Well: This protocol specified in this document has been superseded by the protocol specified in &jep0124;.</em></p>
<p>
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.
</p>
</section1>
<section1 topic="Background">
<p>
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).
</p>
<p>
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.
</p>
<p>
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
<note>
DMZ definition at
<link
url="http://searchwebmanagement.techtarget.com/sDefinition/0,,sid27_gci213891,00.html">
searchwebmanagement.com
</link>
</note>
network. However, there are network configuration where an external
Jabber server must still be used and port 5222/tcp outbound cannot be
allowed. In these situations, different methods for connecting to a
Jabber server are required. Several methods exist today for doing this
traversal. Most rely on the fact that a most firewalls are configured to
allow access through port 80/tcp. Although some less-complicated
firewalls will allow any protocol to traverse this port, many will proxy,
filter, and verify requests on this port as HTTP. Because of this, a
normal Jabber connection on port 80/tcp will not suffice.
</p>
<p>
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.
</p>
<p>
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.
</p>
</section1>
<section1 topic="Normal data transfer">
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
The client sends requests with bodies in the following format:
<example caption="Request Format">
identifier ; key [ ; new_key] , [xml_body]
</example>
If the identifier is zero, key indicates an initial key. In this case,
new_key should not be specified, and must be ignored.
<table caption="Request Values">
<tr>
<th>Identifier</th>
<th>Purpose</th>
</tr>
<tr>
<td>identifier</td>
<td>
To uniquely identify the session server-side. This field is only
used to identify the session, and provides no security.
</td>
</tr>
<tr>
<td>key</td>
<td>
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.
</td>
</tr>
<tr>
<td>new_key</td>
<td>
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.
</td>
</tr>
<tr>
<td>xml_body</td>
<td>
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.
</td>
</tr>
</table>
</p>
<p>
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.
</p>
<section2 topic="Error conditions">
<p>
Any identifier that ends in ':0' indicates an error. Any previous
identifier associated with this session is no longer valid.
</p>
<section3 topic="Unknown Error">
<p>
Server returns ID=0:0. The response body can contain a textual error
message.
</p>
</section3>
<section3 topic="Server Error">
<p>Server returns ID=-1:0</p>
</section3>
<section3 topic="Bad Request">
<p>Server returns ID=-2:0</p>
</section3>
<section3 topic="Key Sequence Error">
<p>Server returns ID=-3:0</p>
</section3>
</section2>
<p>
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.
</p>
<p>The key algorithm should be familiar with those with knowledge of Jabber zero-knowledge authentication.</p>
<example caption="Key Algorithm">
K(n, seed) = Base64Encode(SHA1(K(n - 1, seed))), for n &gt; 0
K(0, seed) = seed, which is client-determined
</example>
<p>Note: Base64 encoding is defined in &rfc3548;. SHA1 is defined in &rfc3174;.</p>
<p>
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.
</p>
<p>
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'.
</p>
<p>
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 &lt;stream:stream&gt; must be
sent to end the session. Failure to do this may have the client continue
to be represented to other users as available.
</p>
<p>
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.
</p>
</section1>
<section1 topic="Usage">
<p>
The following is the sequence used for client communication
<ol>
<li>
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)
</li>
<li>
The client sends the request to the server to start the stream,
including an identifier with a value of zero and K(n, seed)
</li>
<li>
The server responds with the session identifier in the headers
(within the Set-Cookie field).
</li>
<li>
For each further request done by the client, the identifier from the
server and K(n - 1, seed) are sent along.
</li>
<li>
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.
</li>
<li>
The client may send a new key K(m, seed') at any point, but should
do this for n &gt; 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.
</li>
</ol>
</p>
<example caption="Initial request (without keys)">
<![CDATA[POST /wc12/webclient HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: webim.jabber.com
0,<stream:stream to="jabber.com"
xmlns="jabber:client"
xmlns:stream="http://etherx.jabber.org/streams">]]>
</example>
<example caption="Initial response">
<![CDATA[Date: Fri, 15 Mar 2002 20:30:30 GMT
Server: Apache/1.3.20
Set-Cookie: ID=7776:2054; path=/webclient/; expires=-1
Content-Type: text/xml
<?xml version='1.0'?>
<stream:stream xmlns:stream='http://etherx.jabber.org/streams'
id='3C9258BB'
xmlns='jabber:client' from='jabber.com'>]]>
</example>
<example caption="Next request (without keys)">
<![CDATA[POST /wc12/webclient HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: webim.jabber.com
7776:2054,<iq type="get" id="WEBCLIENT3">
<query xmlns="jabber:iq:auth">
<username>hildjj</username>
</query>
</iq>]]>
</example>
<example caption='key sequence'>
K(0, "foo") = "foo"
K(1, "foo") = "C+7Hteo/D9vJXQ3UfzxbwnXaijM="
K(2, "foo") = "6UU8CDmH3O4aHFmCqSORCn721+M="
K(3, "foo") = "vFFYSOhGyaGUgLrldtMBX7x91Wc="
K(4, "foo") = "ZaDxCilBVTHS9dJfbBo1NsC2b+8="
K(5, "foo") = "moPFsvHytDGiJQOjp186AMXAeP0="
K(6, "foo") = "VvxEk07IFy6hUmG/PPBlTLE2fiA="
</example>
<example caption="Initial request (with keys)">
<![CDATA[POST /wc12/webclient HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: webim.jabber.com
0;VvxEk07IFy6hUmG/PPBlTLE2fiA=,<stream:stream to="jabber.com"
xmlns="jabber:client"
xmlns:stream="http://etherx.jabber.org/streams">]]>
</example>
<example caption="Next request (with keys)">
<![CDATA[POST /wc12/webclient HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: webim.jabber.com
7776:2054;moPFsvHytDGiJQOjp186AMXAeP0=,<iq type="get" id="WEBCLIENT3">
<query xmlns="jabber:iq:auth">
<username>hildjj</username>
</query>
</iq>]]>
</example>
<example caption='Changing key'>
<![CDATA[POST /wc12/webclient HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: webim.jabber.com
7776:2054;C+7Hteo/D9vJXQ3UfzxbwnXaijM=;Tr697Eff02+32FZp38Xaq2+3Bv4=,<presence/>]]>
</example>
</section1>
<section1 topic="Known issues">
<ul>
<li>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.</li>
</ul>
</section1>
</jep>

209
xep-0026.xml Normal file
View File

@ -0,0 +1,209 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Internationalization (I18N)</title>
<abstract>NOTE WELL: this JEP was retracted on 2003-11-05 since the topic is addressed definitively in XMPP Core. Please refer to XMPP Core for further information.</abstract>
&LEGALNOTICE;
<number>0026</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards</jig>
<dependencies>None</dependencies>
<supersedes>None</supersedes>
<supersededby>XMPP Core</supersededby>
<shortname>N/A</shortname>
<author>
<firstname>Max</firstname>
<surname>Horn</surname>
<email>max@quendi.de</email>
<jid>black_fingolfin@jabber.org</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-11-05</date>
<initials>psa</initials>
<remark>The status of this JEP has been changed to Retracted since it has been superseded by &xmppcore;. This JEP will not be considered further by the Jabber Software Foundation and should not be used as a basis for implementations.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-03-14</date>
<initials>mh</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
Some examples on how this information could and should be used, include
</p>
<ul>
<li>Forms (e.g. for registration or searching, refer also to <link url="http://foundation.jabber.org/jeps/jep-0004.html">JEP-0004</link>) can be localized, so that instructions and field labels are in the native language of the person who has to fill them out</li>
<li>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</li>
<li>Incoming messages in a different language could be automatically translated (server-side or client-side)</li>
<li>Redirection of messages based on their language (think of a help desk which services world wide requests)</li>
<li>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</li>
</ul>
</section1>
<section1 topic='Implementation'>
<p>
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.
</p>
<section2 topic='Encoding the locale'>
<p>To encode the locale on any given XML packet, we use the xml:lang attribute, as defined in the <link url="http://www.w3.org/TR/REC-xml#sec-lang-tag">XML specification</link>. This in turn uses values as specified in <link url="http://www.ietf.org/rfc/rfc1766.txt">RFC 1766</link> to encode languages and regions. This way, you can even distinguish between British and Australian English.
</p>
<example caption='Example message with locale set to German'>
&lt;message to='friedrich@jabber.org' xml:lang='de-DE'&gt;
&lt;body'&gt;Ich bin ein Berliner!&lt;/body'&gt;
&lt;/message&gt; </example>
<p>
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: &lt;stream/&gt;, &lt;message/&gt;, &lt;iq/&gt; and &lt;presence/&gt;.
</p>
</section2>
<section2 topic='Client support'>
<p>
A client claiming to support this JEP has to initiate server connection slightly differently by putting an xml:lang attribute in the initial &lt;stream:stream&gt; element.
</p>
<example caption='Jabber session initiated with Canadian French as default'>
&lt;?xml version="1.0" encoding="UTF-8" ?&gt;
&lt;stream:stream to='jabber.org' xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams' xml:lang='fr-CA'&gt; </example>
<p>
Servers not supporting this JEP will just ignore the additional attribute. Compliant server can be distinguished by the fact that their reply &lt;stream:stream&gt; 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.
</p>
<example caption='Reply by an English-language Jabber server'>
&lt;stream:stream from='jabber.org' id='12345' xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams' xml:lang='en'&gt; </example>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</section2>
<section2 topic='Server support'>
<p>
A compliant server must detect the xml:lang attribute in incoming &lt;stream:stream&gt; 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.
</p>
<p>
Additionally, a compliant server must attach an xml:lang attribute to the reply &lt;stream:stream&gt; 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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</section2>
<section2 topic='Service support'>
<p>
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 <link url="http://foundation.jabber.org/jeps/jep-0004.html">JEP-0004</link>.
</p>
<example caption='Search form in English'>
&lt;iq from='users.jabber.org' type='result' id='4' xml:lang='en'&gt;
&lt;query xmlns='jabber:iq:search'&gt;
&lt;instructions&gt;
Fill in a field to search for any matching Jabber users.
&lt;/instructions&gt;
&lt;nick/&gt;
&lt;first/&gt;
&lt;last/&gt;
&lt;email/&gt;
&lt;x xmlns='jabber:x:data'&gt;
&lt;instructions&gt;
To search for a user fill out at least one
of the fields below and submit the form.
&lt;/instructions&gt;
&lt;field type='text-single' label='First (Given)' var='first'/&gt;
&lt;field type='text-single' label='Last (Family)' var='last'/&gt;
&lt;field type='text-single' label='Nick (Alias)' var='nick'/&gt;
&lt;field type='text-single' label='Email' var='email'/&gt;
&lt;/x&gt;
&lt;/query&gt;
&lt;/iq&gt; </example>
<p>
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.
</p>
<p>
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.
</p>
<example caption='Request for a German-language search form'>
&lt;iq to='users.jabber.org' type='get' id='5' xml:lang='de'&gt;
&lt;query xmlns='jabber:iq:search'/&gt;
&lt;/iq&gt; </example>
<p>
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:
</p>
<example caption='Search form in German'>
&lt;iq from='users.jabber.org' type='result' id='5' xml:lang='de'&gt;
&lt;query xmlns='jabber:iq:search'&gt;
&lt;instructions&gt;
F&#252;llen Sie ein Feld aus um nach einem beliebigen
passenden Jabber-Benutzer zu suchen.
&lt;/instructions&gt;
&lt;nick/&gt;
&lt;first/&gt;
&lt;last/&gt;
&lt;email/&gt;
&lt;x xmlns='jabber:x:data'&gt;
&lt;instructions&gt;
Um nach einem Benutzer zu suchen, f&#252;llen Sie mindestens eines
der folgenden Felder aus und schicken dann das Formular ab.
&lt;/instructions&gt;
&lt;field type='text-single' label='Vorname' var='first'/&gt;
&lt;field type='text-single' label='Nachname' var='last'/&gt;
&lt;field type='text-single' label='Spitzname' var='nick'/&gt;
&lt;field type='text-single' label='Email' var='email'/&gt;
&lt;/x&gt;
&lt;/query&gt;
&lt;/iq&gt; </example>
<p>
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).
</p>
</section2>
</section1>
</jep>

183
xep-0027.xml Normal file
View File

@ -0,0 +1,183 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Current Jabber OpenPGP Usage</title>
<abstract>This document outlines the current usage of OpenPGP for messaging and presence.</abstract>
&LEGALNOTICE;
<number>0027</number>
<status>Active</status>
<type>Historical</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>openpgp</shortname>
<schemaloc>
<ns>jabber:x:encrypted</ns>
<url>http://jabber.org/protocol/openpgp/x-encrypted.xsd</url>
</schemaloc>
<schemaloc>
<ns>jabber:x:signed</ns>
<url>http://jabber.org/protocol/openpgp/x-signed.xsd</url>
</schemaloc>
&temas;
<revision>
<version>1.2</version>
<date>2004-03-08</date>
<initials>psa</initials>
<remark>Clarified the text in several places; added several more security considerations and known issues.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2004-01-06</date>
<initials>psa</initials>
<remark>Added XML schemas; added security, IANA, and Jabber Registrar considerations.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-04-23</date>
<initials>psa</initials>
<remark>Changed status to Active.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-04-11</date>
<initials>tjm</initials>
<remark>Merged DW's comments on key usage as well as more known issues.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-03-12</date>
<initials>tjm</initials>
<remark>First draft.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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.</p>
<p>All operations described here are done with standard OpenPGP software such as <link url='http://www.gnupg.org/'>GnuPG</link>. 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).</p>
</section1>
<section1 topic='Signing' anchor='signing'>
<p>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:</p>
<ul>
<li>A &PRESENCE; stanza MUST have a &lt;status&gt; element containing XML character data.</li>
<li>A &MESSAGE; stanza MUST have a &lt;body&gt; element containing XML character data.</li>
</ul>
<p>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 &lt;status&gt; 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).</p>
<example caption='A signed presence stanza'>
&lt;presence from='pgmillard@jabber.org/wj_dev2' to='jer@jabber.org'&gt;
&lt;status&gt;Online&lt;/status&gt;
&lt;x xmlns='jabber:x:signed'&gt;
iQA/AwUBOjU5dnol3d88qZ77EQI2JACfRngLJ045brNnaCX78ykKNUZaTIoAoPHI
2uJxPMGR73EBIvEpcv0LRSy+
=45f8
&lt;/x&gt;
&lt;/presence&gt;
</example>
</section1>
<section1 topic='Encrypting' anchor='encrypting'>
<p>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 &lt;body&gt; 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).</p>
<example caption='An encrypted message stanza'>
&lt;message to='reatmon@jabber.org/jarl' from='pgmillard@jabber.org/wj_dev2'&gt;
&lt;body&gt;This message is encrypted.&lt;/body&gt;
&lt;x xmlns='jabber:x:encrypted'&gt;
qANQR1DBwU4DX7jmYZnncmUQB/9KuKBddzQH+tZ1ZywKK0yHKnq57kWq+RFtQdCJ
WpdWpR0uQsuJe7+vh3NWn59/gTc5MDlX8dS9p0ovStmNcyLhxVgmqS8ZKhsblVeu
IpQ0JgavABqibJolc3BKrVtVV1igKiX/N7Pi8RtY1K18toaMDhdEfhBRzO/XB0+P
AQhYlRjNacGcslkhXqNjK5Va4tuOAPy2n1Q8UUrHbUd0g+xJ9Bm0G0LZXyvCWyKH
kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA
w7R61cCPt8KSd8Vcl8K+StqOMZ5wkhosVjUqvEu8uJ9RupdpB/4m9E3gOQZCBsmq
OsX4/jJhn2wIsfYYWdqkbNKnuYoKCnwrlmn6I+wX72p0R8tTv8peNCwK9bEtL/XS
mhn4bCxoUkCITv3k8a+Jdvbov9ucduKSFuCBq4/l0fpHmPhHQjkFofxmaWJveFfF
619NXyYyCfoLTmWk2AaTHVCjtKdf1WmwcTa0vFfk8BuFHkdah6kJJiJ7w/yNwa/E
O6CMymuZTr/LpcKKWrWCt+SErxqmq8ekPI8h7oNwMxZBYAa7OJ1rXWKNgL9pDtNI
824Mf0mXj7q5N1eMHvX1QEoKLAda/Ae3TTEevOyeUK1DEgvxfM2KRZ11RzU+XtIE
My/bJk7EycAw8P/QKyeNlO1fxP58VEd6Gb8NCPqKOYn/LKh1O+c20ZNVEPFM4bNV
XA4hB4UtFF7Ao8kpdlrUqdKyw4lEtnmdemYQ6+iIIVPEarWl9PxOMY90KAnZrSAq
bt9uRY/1rPgelRaWblMKvxgpRO8++Y8VjdEyGgMOXxOiE851Ve72ftGzkSxDH8mW
TgY3pf2aATmBp3lagQ1COkGS/xupovT5AQPA3RzbCxDvc6s6eGYKmVVQVj5vmSj1
WULad5MB9KT1DzCm6FOSy063nWGBYYMWiejRvGLpo1j4eAnj0qOt7rTWmgv3RkYF
Oin0vDOhW7aC
=CvnG&lt;/x&gt;
&lt;/message&gt;
</example>
<p>It is considered polite to include an unencrypted message &lt;body/&gt; 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).</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>The method defined herein has the following security issues:</p>
<ul>
<li>Key exchange relies on the web of trust model used on the OpenPGP keys network.</li>
<li>There is no mechanism for checking a fingerprint or ownership of a key other than checking the user IDs on a key.</li>
<li>When the recipient is not mentioned in the encrypted body, replay attacks are possible on messages.</li>
<li>Replay of the signed &PRESENCE; status is possible.</li>
<li>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 &lt;status/&gt; element and encryption of the message &lt;body/&gt; element only. Thus the method is not acceptable when signing or encryption of full stanzas is required.</li>
<li>It does not enable both signing and encryption of a stanza, only signing of the presence status and encryption of the message body.</li>
</ul>
</section1>
<section1 topic='Other Known Issues' anchor='issues'>
<p>In addition to the security considerations listed above, there are several other known issues with this method:</p>
<ul>
<li>It is limited to PGP keys and does not support X.509 certificates, Kerberos, RSA keys, etc.</li>
<li>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.</li>
<li>It is verbose (the example encrypted &MESSAGE; is "Hi").</li>
</ul>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<p>The &REGISTRAR; shall register the 'jabber:x:encrypted' and 'jabber:x:signed' namespaces as a result of this JEP.</p>
</section1>
<section1 topic='XML Schemas' anchor='schemas'>
<section2 topic='jabber:x:encrypted' anchor='schemas-encrypted'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:x:encrypted'
xmlns='jabber:x:encrypted'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0027: http://www.jabber.org/jeps/jep-0027.html
</xs:documentation>
</xs:annotation>
<xs:element name='x' type='xs:string'/>
</xs:schema>
]]></code>
</section2>
<section2 topic='jabber:x:signed' anchor='schemas-signed'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:x:signed'
xmlns='jabber:x:signed'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0027: http://www.jabber.org/jeps/jep-0027.html
</xs:documentation>
</xs:annotation>
<xs:element name='x' type='xs:string'/>
</xs:schema>
]]></code>
</section2>
</section1>
</jep>

13
xep-0028.xml Normal file
View File

@ -0,0 +1,13 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>No Such JEP</title>
<abstract>This JEP was removed from the JSF website and source control at the request of the author.</abstract>
<number>0028</number>
</header>
</jep>

117
xep-0029.xml Normal file
View File

@ -0,0 +1,117 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Definition of Jabber Identifiers (JIDs)</title>
<abstract>This document defines the exact nature of a Jabber Identifier (JID). <em>Note well: this document is superseded by the XMPP Core memo defined by the IETF's XMPP Working Group.</em></abstract>
&LEGALNOTICE;
<number>0029</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>None</dependencies>
<supersedes>None</supersedes>
<supersededby>XMPP Core</supersededby>
<shortname>N/A</shortname>
<author>
<firstname>Craig</firstname>
<surname>Kaes</surname>
<email>craigk@jabber.com</email>
<jid>craigk@jabber.com</jid>
</author>
<revision>
<version>1.1</version>
<date>2003-10-03</date>
<initials>psa</initials>
<remark>Changed status to Retracted. This JEP is superseded by the XMPP Core memo defined by the IETF's XMPP Working Group.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-05-15</date>
<initials>psa</initials>
<remark>Changed status to Draft.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-05-01</date>
<initials>cak</initials>
<remark>
Added info on restricting resource identifier length; standardized nomenclature.
</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-04-24</date>
<initials>cak</initials>
<remark>Initial version</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
</section1>
<section1 topic='JIDs'>
<p>JIDs consist of three main parts:</p>
<ol>
<li>The node identifier (optional)</li>
<li>The domain identifier (required)</li>
<li>The resource identifier (optional)</li>
</ol>
<p>JIDs are encoded UTF-8. A grammar will be presented first, followed by specific clarifying and further restricting remarks.</p>
<section2 topic='Grammar'>
<p>
<code>
&lt;JID&gt; ::= [&lt;node&gt;"@"]&lt;domain&gt;["/"&lt;resource&gt;]
&lt;node&gt; ::= &lt;conforming-char&gt;[&lt;conforming-char&gt;]*
&lt;domain&gt; ::= &lt;hname&gt;["."&lt;hname&gt;]*
&lt;resource&gt; ::= &lt;any-char&gt;[&lt;any-char&gt;]*
&lt;hname&gt; ::= &lt;let&gt;|&lt;dig&gt;[[&lt;let&gt;|&lt;dig&gt;|"-"]*&lt;let&gt;|&lt;dig&gt;]
&lt;let&gt; ::= [a-z] | [A-Z]
&lt;dig&gt; ::= [0-9]
&lt;conforming-char&gt; ::= #x21 | [#x23-#x25] | [#x28-#x2E] |
[#x30-#x39] | #x3B | #x3D | #x3F |
[#x41-#x7E] | [#x80-#xD7FF] |
[#xE000-#xFFFD] | [#x10000-#x10FFFF]
&lt;any-char&gt; ::= [#x20-#xD7FF] | [#xE000-#xFFFD] |
[#x10000-#x10FFFF]
</code>
</p>
</section2>
<section2 topic='Domain Identifier'>
<p>A domain identifier is a standard DNS hostname as specified in RFC952 <note><link url='http://www.ietf.org/rfc/rfc952.txt'>http://www.ietf.org/rfc/rfc952.txt</link></note> and RFC1123. <note><link url='http://www.ietf.org/rfc/rfc1123.txt'>http://www.ietf.org/rfc/rfc1123.txt</link></note> It is case-insensitive 7-bit ASCII and limited to 255 bytes. It is the only required component of a JID.</p>
</section2>
<section2 topic='Node Identifier'>
<p>Node identifiers are restricted to 256 bytes, They may contain any Unicode character higher than #x20 with the exception of the following:</p>
<ol>
<li>#x22 (")</li>
<li>#x26 (&amp;)</li>
<li>#x27 (')</li>
<li>#x2F (/)</li>
<li>#x3A (:)</li>
<li>#x3C (&lt;)</li>
<li>#x3E (&gt;)</li>
<li>#x40 (@)</li>
<li>#x7F (del)</li>
<li>#xFFFE (BOM)</li>
<li>#xFFFF (BOM)</li>
</ol>
<p>Case is preserved, but comparisons will be made in case-normalized canonical form.</p>
</section2>
<section2 topic='Resource Identifier'>
<p>Resources identifiers are case-sensitive and are limited to 256 bytes. They may include any Unicode character greater than #x20, except #xFFFE and #xFFFF.</p>
</section2>
<section2 topic='Limited Resources'>
<p>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:</p>
<ol>
<li>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.</li>
<li>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.</li>
<li>There exist denial of service attacks stemming from an unlimited resource length.</li>
</ol>
<p>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.</p>
<p>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.</p>
</section2>
</section1>
</jep>

1032
xep-0030.xml Normal file
View File

File diff suppressed because it is too large Load Diff

2328
xep-0031.xml Normal file
View File

File diff suppressed because it is too large Load Diff

158
xep-0032.xml Normal file
View File

@ -0,0 +1,158 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Jabber URI Scheme</title>
<abstract>A URI scheme for Jabber communications.</abstract>
&LEGALNOTICE;
<number>0032</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>None</dependencies>
<supersedes>None</supersedes>
<supersededby>draft-saintandre-xmpp-uri</supersededby>
<author>
<firstname>Peter</firstname>
<surname>Saint-Andre</surname>
<email>stpeter@jabber.org</email>
<jid>stpeter@jabber.org</jid>
</author>
<author>
<firstname>Peter</firstname>
<surname>Millard</surname>
<email>me@pgmillard.com</email>
<jid>pgmillard@jabber.org</jid>
</author>
<revision>
<version>0.4</version>
<date>2003-09-02</date>
<initials>psa</initials>
<remark>Retracted the JEP, since it is superseded by draft-ietf-xmpp-uri, an Internet-Draft produced by the IETF's XMPP WG.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-10-16</date>
<initials>psa</initials>
<remark>Changed 'jabber:' scheme to 'xmpp:' scheme; further specified use cases; removed references to official Jabber namespaces.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-05-10</date>
<initials>psa</initials>
<remark>Added information about syntax, allowable characters, and potential conflict with official Jabber namespaces.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-05-08</date>
<initials>psa</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>It is widely acknowledged that it would be good to be able to express a Jabber Identifier (JID) <note>Jabber Identifiers are formally defined in JEP-0029: <link url='http://www.jabber.org/jeps/jep-0029.html'>http://www.jabber.org/jeps/jep-0029.html</link>.</note> as a Uniform Resource Identifier (see &rfc3986;). In addition, there would be value in being able to interact with a JID through a URI scheme (e.g., by sending a message or a presence update).</p>
<p>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:</p>
<ul>
<li>Sending of basic messages</li>
<li>Sending of basic presence</li>
<li>Sending of subscription requests</li>
</ul>
</section1>
<section1 topic='Syntax'>
<p>The syntactic components of a Jabber URI are as follows:</p>
<code>&lt;xmpp&gt;:[&lt;node-identifier&gt;@]&lt;domain-identifier&gt;[?&lt;query&gt;]</code>
<p>This scheme is similar to the mailto URI scheme <note>The mailto URI scheme is described in RFC 2368: <link url='http://www.ietf.org/rfc/rfc2368.txt'>http://www.ietf.org/rfc/rfc2368.txt</link>.</note>. One similarity is that a Jabber URI is, in the terminology of RFC 3986, not hierarchical but opaque. A URI that is hierarchical in nature uses the slash ("/") character in order to separate hierarchical components, as is familiar from HTTP and FTP URIs. By contrast, an opaque URI such as a mailto URI contains only the scheme (e.g., 'mailto'), a colon, an address (e.g., 'user@host'), and an optional query component.</p>
<p>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.</p>
</section1>
<section1 topic='URI Characters and Escape Sequences'>
<p>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.</p>
<section2 topic='Scheme Component'>
<p>The scheme component for a Jabber URI is 'xmpp'. This component is delimited from the remainder of the URI by a colon character (':').</p>
</section2>
<section2 topic='Node Identifier Component'>
<p>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:</p>
<code>#x22 (") | #x26 (&amp;) | #x27 (') | #x2F (/) |
#x3A (:) | #x3C (&lt;) | #x3E (&gt;) | #x40 (@) |
#x7F (del) | #xFFFE (BOM) | #xFFFF (BOM)</code>
<p>In addition, Section 2.2 of RFC 3986 stipulates that the following additional characters are reserved:</p>
<code>#x24 ($) | #x2B (+) | #x2C (,) | #x3B (;) | #x3D (=) | #x3F (?)</code>
<p>Section 2.4.3 of RFC 3986 further stipulates that the following characters are excluded from URIs in their unescaped form:</p>
<code>#x23 (#) | #x25 (%)</code>
<p>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.</p>
<p>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.</p>
</section2>
<section2 topic='Domain Identifier Component'>
<p>A domain identifier is a standard DNS hostname as specified in RFC 952 <note><link url='http://www.ietf.org/rfc/rfc952.txt'>http://www.ietf.org/rfc/rfc952.txt</link></note>.</p>
</section2>
<section2 topic='Query Component'>
<p>The query component of a Jabber URI may contain any US-ASCII character higher than #x20 with the exception of the following:</p>
<code>#x22 (") | #x23 (#) | #x24 ($) | #x25 (%) |
#x26 (&amp;) | #x27 (') | #x2B (+) | #x2C (,) |
#x2F (/) | #x3A (:) | #x3B (;) | #x3C (&lt;) |
#x3D (=) | #x3E (&gt;) | #x3F (?) | #x40 (@) |
#x7F (del) | #xFFFE (BOM) | #xFFFF (BOM)</code>
</section2>
</section1>
<section1 topic='Use Cases'>
<p>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.</p>
<code>
xmpp:user@host
</code>
<p>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.</p>
<p>The authors propose three allowable query types in a Jabber URI: message, presence, and subscribe <note>These query types are URI queries as defined in RFC 3986 and are not to be confused with the &lt;query/&gt; element often included as the child of an &lt;iq/&gt; element in XMPP.</note>. These three basic URIs are described below by way of use cases.</p>
<section2 topic='Sending a Message'>
<p>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.</p>
<example caption='Invoking an Interface to Send a Message to a JID'>
xmpp:user@host?message
</example>
<p>The query component may include parameters that further specify the message to be sent to the intended recipient. The following parameters are allowed:</p>
<ul>
<li>body</li>
<li>subject</li>
<li>thread (for conversation tracking)</li>
</ul>
<example caption='Sending a Message with a Subject, Body, and Thread'>
xmpp:user@host?message&amp;subject=hi&amp;body=Hello%20World&amp;thread=abc123
</example>
</section2>
<section2 topic='Sending Presence'>
<p>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.</p>
<example caption='Invoking an Interface to Send Presence to a JID'>
xmpp:user@host?presence
</example>
<p>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:</p>
<ul>
<li>type ('unavailable'; if not specified, the sender is defined to be online and available)</li>
<li>show (one of 'away', 'xa', 'dnd', or 'chat')</li>
<li>status (user-defined status message)</li>
<li>priority (a non-negative integer, with zero as the lowest priority)</li>
</ul>
<example caption='Sending a Specific Presence'>
xmpp:user@host?presence&amp;show=dnd&amp;status=taking%20a%20nap
</example>
</section2>
<section2 topic="Managing Subscriptions">
<p>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.</p>
<example caption='Invoking an Interface to Send a Subscription Request to a JID'>
xmpp:user@host?subscribe
</example>
<p>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'.</p>
<example caption='Sending a Subscription Request'>
xmpp:user@host?subscribe&amp;type=subscribe
</example>
<example caption='Accepting a Subscription Request'>
xmpp:user@host?subscribe&amp;type=subscribed
</example>
<example caption="Unsubscribing from Another User's Presence">
xmpp:user@host?subscribe&amp;type=unsubscribe
</example>
<example caption="Cancelling Another User's Subscription to Your Presence">
xmpp:user@host?subscribe&amp;type=unsubscribed
</example>
</section2>
</section1>
</jep>

667
xep-0033.xml Normal file
View File

@ -0,0 +1,667 @@
<?xml version='1.0'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Extended Stanza Addressing</title>
<abstract>This document specifies an XMPP protocol extension that enables entities to include RFC822-style address headers within XMPP stanzas in order to specify multiple recipients or sub-addresses.</abstract>
&LEGALNOTICE;
<number>0033</number>
<status>Draft</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>JEP-0030</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>address</shortname>
<schemaloc>
<url>http://jabber.org/protocol/address/address.xsd</url>
</schemaloc>
&hildjj;
&stpeter;
<revision>
<version>1.1</version>
<date>2004-09-15</date>
<initials>psa</initials>
<remark>Per list discussion, removed prohibition on multiple replyto and replyroom addresses, since this is allowed by RFC 822.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2004-05-10</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Draft; also added Security Considerations in consultation with JEP author.</remark>
</revision>
<revision>
<version>0.10</version>
<date>2004-03-18</date>
<initials>psa</initials>
<remark>Disallowed &lt;addresses/&gt; as direct child
of &IQ;.</remark>
</revision>
<revision>
<version>0.9</version>
<date>2004-02-27</date>
<initials>jjh</initials>
<remark>Added language note on desc attribute. Ensured
that if uri attribute is used, node MUST NOT be.</remark>
</revision>
<revision>
<version>0.8</version>
<date>2004-02-11</date>
<initials>jjh</initials>
<remark>Editorial cleanups, rearrangement. Allowed IQ's
in certain cases. Clarified node rules. Changed
delivered='yes' to delivered='true'. Noreply shouldn't
imply no other addresses. Clarified when authorization
checks take place. Remove own address on reply. Bad URI
error added.</remark>
</revision>
<revision>
<version>0.7</version>
<date>2004-02-04</date>
<initials>jjh</initials>
<remark>Clarified that a node attribute refers to a disco
node.</remark>
</revision>
<revision>
<version>0.6</version>
<date>2004-02-04</date>
<initials>jjh</initials>
<remark>Changed namespace to
'http://www.jabber.org/protocol/address', and removed one
level of nesting, since addresses are the only block left.
Made it clearer that the session manager can implement
multicast directly. Removed infobits (needs to be a
separate JEP). Reworked the examples to be more correct.
Added reply handling rules. Added schema.</remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-12-17</date>
<initials>jjh</initials>
<remark>Replaced info with infobits, added noreply address
type.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-12-15</date>
<initials>jjh</initials>
<remark>Removed trace; if you want that, use a different
namespace. Required disco use, and removed agents/browse.
Added URI addressing.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-07-29</date>
<initials>jjh</initials>
<remark>Made addresses extensible, added replyroom</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-05-06</date>
<initials>jjh</initials>
<remark>Re-worked to simpler/more structured XML.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-04-19</date>
<initials>jjh</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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.</p>
<p>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' <note><link url='http://www.jabber.org/old-docs/proto-draft/envelope.html'>jabber:x:envelope</link> - Message Envelope Information Extension</note> proposal, which this JEP can supersede.</p>
</section1>
<section1 topic='Discovering Server Support' anchor='disco'>
<p>Support for Extended Stanza Addressing in a given server instance SHOULD be determined using &jep0030;. A conforming server MUST respond to disco#info requests.</p>
<section2 topic='Disco to determine support' anchor='disco-support'>
<p>To determine if a server or service supports Extended Stanza Addressing, the requesting entity SHOULD send a disco#info request to it.</p>
<example caption='Disco request for address header support'><![CDATA[
<iq type='get'
from='romeo@montague.net/orchard'
to='multicast.montague.net'
id='info1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]>
</example>
<p>If the server supports Extended Stanza Addressing, it MUST include a "http://jabber.org/protocol/address" feature in the response.</p>
<example caption='Disco response for server supporting address headers'><![CDATA[
<iq type='result'
from='multicast.montague.net'
to='romeo@montague.net/orchard'
id='info1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://jabber.org/protocol/address'/>
...
</query>
</iq>]]>
</example>
</section2>
<section2 topic='Multicast service' anchor='disco-multicast'>
<p>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:</p>
<ol>
<li>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.</li>
<li>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.</li>
<li>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.</li>
</ol>
<p>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 <link url='#errors'>Error Conditions</link> section below). In the relaying case, the server SHOULD NOT deliver to <em>any</em> of the addresses (even the local ones) if the sender is disallowed.</p>
</section2>
<section2 topic='Caching' anchor='disco-caching'>
<p>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.</p>
</section2>
</section1>
<section1 topic='Outer Stanza' anchor='outer'>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>Address headers MAY be included in message or presence
stanzas. They MUST NOT be included as the direct child of an
IQ stanza.</p>
</section1>
<section1 topic='Addresses' anchor='addresses'>
<p>Address values are packaged together into an
&lt;addresses/&gt; element.</p>
<example caption='Message with an extended address'><![CDATA[<message to='multicast.jabber.org'>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='to' jid='hildjj@jabber.org/Work' desc='Joe Hildebrand'/>
<address type='cc' jid='jer@jabber.org/Home' desc='Jeremie Miller'/>
</addresses>
<body>Hello, world!</body>
</message>]]></example>
<example caption='Presence with an extended address'><![CDATA[<presence from='hildjj@jabber.com' to='multicast.jabber.org' type='unavailable'>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='bcc' jid='temas@jabber.org'/>
<address type='bcc' jid='jer@jabber.org'/>
</addresses>
</presence>]]></example>
<p>Each address to which the sender wants the stanza to be re-sent will show up as an &lt;address/&gt; in the &lt;addresses/&gt; element. There are several different types of address, shown below.</p>
<p>An &lt;address/&gt; element MUST possess a 'type' attribute, and MUST possess at least one of the 'jid', 'uri', 'node', and 'desc' attributes. An &lt;address/&gt; 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'.</p>
<section2 topic="'jid' attribute" anchor='addr-jid'>
<p>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.</p>
</section2>
<section2 topic="'uri' attribute" anchor='addr-uri'>
<p>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 &amp; &lt; &gt; &apos; &quot; replaced by their equivalent XML escapes, &amp;amp; &amp;lt; &amp;gt; &amp;apos; &amp;quot;. 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.</p>
</section2>
<section2 topic="'node' attribute" anchor='addr-node'>
<p>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.</p>
</section2>
<section2 topic="'desc' attribute" anchor='addr-desc'>
<p>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.</p>
</section2>
<section2 topic="'delivered' attribute" anchor='addr-delivered'>
<p>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 <link url='#multicast'>Multicast Usage</link> section below for more details. Support for the 'delivered' attribute is REQUIRED.</p>
</section2>
<section2 topic="'type' attribute" anchor='addr-type'>
<p>The 'type' attribute is used to specify the semantics of a particular address. Support for the 'type' attribute is REQUIRED.</p>
<section3 topic="Address type='to'" anchor='addr-type-to'>
<p>These addressees are the primary recipients of the stanza.</p>
</section3>
<section3 topic="Address type='cc'" anchor='addr-type-cc'>
<p>These addressees are the secondary recipients of the stanza.</p>
</section3>
<section3 topic="Address type='bcc'" anchor='addr-type-bcc'>
<p>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.</p>
</section3>
<section3 topic="Address type='replyto'" anchor='addr-type-replyto'>
<p>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.</p>
</section3>
<section3 topic="Address type='replyroom'" anchor='addr-type-replyroom'>
<p>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.</p>
</section3>
<section3 topic="Address type='noreply'" anchor='addr-type-noreply'>
<p>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.</p>
</section3>
</section2>
<section2 topic="Extensibility" anchor='extensibility'>
<p>As specified herein, the &lt;address/&gt; element is empty. Implementations or future protocols MAY extend the &lt;address/&gt; 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.</p>
<example caption='Possible future extension'><![CDATA[<message to='groups.jabber.org'>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='to' desc='Foo Group'>
<group xmlns='some:funny:group:ns'>foo</group>
</address>
<address type='replyroom' jid='jdev@conference.jabber.org'/>
</addresses>
</message>]]></example>
</section2>
</section1>
<section1 topic='Multicast Usage' anchor='multicast'>
<p>The following usage scenario shows how messages flow through both address-enabled and non-address-enabled portions of the Jabber network.</p>
<p>Note: the logic associated with <em>how</em> 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 <em>will not</em>) use this algorithm.</p>
<ol>
<li>User desires to send a stanza to more than one
recipient.</li>
<li>Client determines the JID of a multicast service,
using Service Discovery.</li>
<li>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.</li>
<li>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.)</li>
<li>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.</li>
<li>The server adds a delivered='true' attribute to all
addresses.</li>
<li>The server removes all type='bcc' attributes.</li>
<li>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
&lt;address type='bcc'/&gt; associated with that
addressee.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
</ol>
</section1>
<section1 topic='Example Flow' anchor='examples'>
<p>Assume for these examples that header1.org and header2.org
support address headers, and noheader.org does not.</p>
<example caption='Client checks local server for address header support'><![CDATA[<iq type='get' to='header1.org' from='a@header1.org/work' id='id_1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
<example caption='Client receives positive results from server'><![CDATA[<iq type='result' from='header1.org' to='a@header1.org/work' id='id_1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='http://jabber.org/protocol/address'/>
</query>
</iq>]]></example>
<example caption='Client sends message to local server with address header'><![CDATA[<message to='header1.org' from='a@header1.org/work'>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='to' jid='to@header1.org'/>
<address type='cc' jid='cc@header1.org'/>
<address type='bcc' jid='bcc@header1.org'/>
<address type='to' jid='to@header2.org'/>
<address type='cc' jid='cc@header2.org'/>
<address type='bcc' jid='bcc@header2.org'/>
<address type='to' jid='to@noheader.org'/>
<address type='cc' jid='cc@noheader.org'/>
<address type='bcc' jid='bcc@noheader.org'/>
</addresses>
<body>Hello, World!</body>
</message>]]></example>
<example caption='Server delivers to local addresses'><![CDATA[<message to='to@header1.org' from='a@header1.org/work'>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='to' jid='to@header1.org' delivered='true'/>
<address type='cc' jid='cc@header1.org' delivered='true'/>
<address type='to' jid='to@header2.org' delivered='true'/>
<address type='cc' jid='cc@header2.org' delivered='true'/>
<address type='to' jid='to@noheader.org' delivered='true'/>
<address type='cc' jid='cc@noheader.org' delivered='true'/>
</addresses>
<body>Hello, World!</body>
</message>
<message to='cc@header1.org' from='a@header1.org/work'>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='to' jid='to@header1.org' delivered='true'/>
<address type='cc' jid='cc@header1.org' delivered='true'/>
<address type='to' jid='to@header2.org' delivered='true'/>
<address type='cc' jid='cc@header2.org' delivered='true'/>
<address type='to' jid='to@noheader.org' delivered='true'/>
<address type='cc' jid='cc@noheader.org' delivered='true'/>
</addresses>
<body>Hello, World!</body>
</message>
<message to='bcc@header1.org' from='a@header1.org/work'>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='to' jid='to@header1.org' delivered='true'/>
<address type='cc' jid='cc@header1.org' delivered='true'/>
<address type='to' jid='to@header2.org' delivered='true'/>
<address type='cc' jid='cc@header2.org' delivered='true'/>
<address type='to' jid='to@noheader.org' delivered='true'/>
<address type='cc' jid='cc@noheader.org' delivered='true'/>
</addresses>
<body>Hello, World!</body>
</message>]]></example>
<example caption='Local server checks target server for address support'><![CDATA[<iq type='get' to='header2.org' from='header1.org' id='id_2'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption='Local server receives initial negative results from target server'><![CDATA[<iq type='result' from='header2.org' to='header1.org' id='id_2'>
<query xmlns='http://jabber.org/protocol/disco#info'>
... no address feature ...
</query>
</iq>]]></example>
<example caption='Local server checks target server for another component having address support'><![CDATA[<iq type='get' to='header2.org' from='header1.org' id='id_3'>
<query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
]]></example>
<example caption='Local server receives associated services from target server'><![CDATA[<iq type='result' from='header2.org' to='header1.org' id='id_3'>
<query xmlns='http://jabber.org/protocol/disco#items>
<item jid='multicast.header2.org'
name='Multicast Service'/>
</query>
</iq>]]></example>
<example caption='Local server checks associated services for address support'><![CDATA[<iq type='get' to='multicast.header2.org' from='header1.org' id='id_4'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption='Local server receives positive results from target server'><![CDATA[<iq type='result' from='multicast.header2.org' to='header1.org/work' id='id_4'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='http://jabber.org/protocol/address'/>
</query>
</iq>]]></example>
<example caption='Local server delivers to target server supporting address headers'><![CDATA[<message to='multicast.header2.org' from='a@header1.org/work'>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='to' jid='to@header1.org' delivered='true'/>
<address type='cc' jid='cc@header1.org' delivered='true'/>
<address type='to' jid='to@header2.org'/>
<address type='cc' jid='cc@header2.org'/>
<address type='bcc' jid='bcc@header2.org'/>
<address type='to' jid='to@noheader.org' delivered='true'/>
<address type='cc' jid='cc@noheader.org' delivered='true'/>
</addresses>
<body>Hello, World!</body>
</message>]]></example>
<example caption='Target server delivers to its recipients'><![CDATA[<message to='to@header2.org' from='a@header1.org/work'>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='to' jid='to@header1.org' delivered='true'/>
<address type='cc' jid='cc@header1.org' delivered='true'/>
<address type='to' jid='to@header2.org' delivered='true'/>
<address type='cc' jid='cc@header2.org' delivered='true'/>
<address type='to' jid='to@noheader.org' delivered='true'/>
<address type='cc' jid='cc@noheader.org' delivered='true'/>
</addresses>
<body>Hello, World!</body>
</message>
<message to='cc@header2.org' from='a@header1.org/work'>
<address xmlns='http://jabber.org/protocol/address'>
<address type='to' jid='to@header1.org' delivered='true'/>
<address type='cc' jid='cc@header1.org' delivered='true'/>
<address type='to' jid='to@header2.org' delivered='true'/>
<address type='cc' jid='cc@header2.org' delivered='true'/>
<address type='to' jid='to@noheader.org' delivered='true'/>
<address type='cc' jid='cc@noheader.org' delivered='true'/>
</addresses>
<body>Hello, World!</body>
</message>
<message to='bcc@header2.org' from='a@header1.org/work'>
<address xmlns='http://jabber.org/protocol/address'>
<address type='to' jid='to@header1.org' delivered='true'/>
<address type='cc' jid='cc@header1.org' delivered='true'/>
<address type='to' jid='to@header2.org' delivered='true'/>
<address type='cc' jid='cc@header2.org' delivered='true'/>
<address type='to' jid='to@noheader.org' delivered='true'/>
<address type='cc' jid='cc@noheader.org' delivered='true'/>
</addresses>
<body>Hello, World!</body>
</message>]]></example>
<example caption='Local server checks target server for address header support'><![CDATA[<iq type='get' to='noheader.org' from='header1.org' id='id_5'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
<example caption='Local server receives negative results from target server (assume no associated services found)'><![CDATA[<iq type='result' from='noheader.org' to='header1.org' id='id_5'>
<query xmlns='http://jabber.org/protocol/disco#info'>
... no address feature ...
</query>
</iq>]]></example>
<example caption='Server delivers to each address on the target server not supporting address headers'><![CDATA[<message to='to@noheader.org' from='a@header1.org/work'>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='to' jid='to@header1.org' delivered='true'/>
<address type='cc' jid='cc@header1.org' delivered='true'/>
<address type='to' jid='to@header2.org' delivered='true'/>
<address type='cc' jid='cc@header2.org' delivered='true'/>
<address type='to' jid='to@noheader.org' delivered='true'/>
<address type='cc' jid='cc@noheader.org' delivered='true'/>
</addresses>
<body>Hello, World!</body>
</message>
<message to='cc@noheader.org' from='a@header1.org/work'>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='to' jid='to@header1.org' delivered='true'/>
<address type='cc' jid='cc@header1.org' delivered='true'/>
<address type='to' jid='to@header2.org' delivered='true'/>
<address type='cc' jid='cc@header2.org' delivered='true'/>
<address type='to' jid='to@noheader.org' delivered='true'/>
<address type='cc' jid='cc@noheader.org' delivered='true'/>
</addresses>
<body>Hello, World!</body>
</message>
<message to='bcc@noheader.org' from='a@header1.org/work'>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='to' jid='to@header1.org' delivered='true'/>
<address type='cc' jid='cc@header1.org' delivered='true'/>
<address type='to' jid='to@header2.org' delivered='true'/>
<address type='cc' jid='cc@header2.org' delivered='true'/>
<address type='to' jid='to@noheader.org' delivered='true'/>
<address type='cc' jid='cc@noheader.org' delivered='true'/>
</addresses>
<body>Hello, World!</body>
</message>]]></example>
</section1>
<section1 topic='Reply Handling' anchor='replies'>
<p>When replying to a message stanza that contains an extended
address, the following rules apply:</p>
<ol>
<li>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.</li>
<li>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.</li>
<li>If a replyto address is specified, the reply SHOULD go
to the specified address. No further extended address
processing is required. Any &lt;thread/&gt; element from
the initial message MUST be copied into the reply.</li>
<li>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 <link url='#multicast'>Multicast Usage</link>
section above for delivery of the message.</li>
</ol>
</section1>
<section1 topic='Error Conditions' anchor='errors'>
<p>The following error conditions are to be used by implementations (for further information regarding error syntax, see &jep0086;):</p>
<table caption='Error Conditions'>
<tr>
<th>XMPP Condition</th>
<th>Purpose</th>
</tr>
<tr>
<td>&lt;forbidden/&gt;</td>
<td>The sending user does not have permission to use this multicast service.</td>
</tr>
<tr>
<td>&lt;jid-malformed/&gt;</td>
<td>A URI attribute was invalid or not understood (note that support for the 'uri' attribute is optional).</td>
</tr>
<tr>
<td>&lt;not-acceptable/&gt;</td>
<td>Too many receiver fields were specified. Servers MAY have configurable limits for this, but the limit MUST be at least 50.</td>
</tr>
</table>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>A recipient SHOULD trust a stanza's extended addressing headers only as much as it trusts the sender of the stanza.</p>
<p>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;.)</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<p>The &REGISTRAR; shall include 'http://jabber.org/protocol/address' in its registry of protocol namespaces.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/address'
xmlns='http://jabber.org/protocol/address'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0033: http://www.jabber.org/jeps/jep-0033.html
</xs:documentation>
</xs:annotation>
<xs:element name='addresses'>
<xs:complexType>
<xs:sequence>
<xs:element ref='address'
minOccurs='1'
maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='address'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='delivered' use='optional' fixed='true'/>
<xs:attribute name='desc' use='optional' type='xs:string'/>
<xs:attribute name='jid' use='optional' type='xs:string'/>
<xs:attribute name='node' use='optional' type='xs:string'/>
<xs:attribute name='type' use='required'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='bcc'/>
<xs:enumeration value='cc'/>
<xs:enumeration value='noreply'/>
<xs:enumeration value='replyroom'/>
<xs:enumeration value='replyto'/>
<xs:enumeration value='to'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name='uri' use='optional' type='xs:string'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Sections of this document were inspired by RFC 822.</p>
</section1>
</jep>

249
xep-0034.xml Normal file
View File

@ -0,0 +1,249 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>SASL Integration</title>
<abstract>NOTE WELL: this JEP was retracted on 2003-11-05 since the topic is addressed definitively in XMPP Core. Please refer to XMPP Core for further information.</abstract>
&LEGALNOTICE;
<number>0034</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards</jig>
<dependencies>None</dependencies>
<supersedes>None</supersedes>
<supersededby>XMPP Core</supersededby>
<shortname>N/A</shortname>
<author>
<firstname>Robert</firstname>
<surname>Norris</surname>
<email>rob@cataclysm.cx</email>
<jid>rob@cataclysm.cx</jid>
</author>
<author>
<firstname>Jeremie</firstname>
<surname>Miller</surname>
<email>jeremie@jabber.org</email>
<jid>jer@jabber.org</jid>
</author>
<author>
<firstname>Peter</firstname>
<surname>Saint-Andre</surname>
<email>stpeter@jabber.org</email>
<jid>stpeter@jabber.org</jid>
</author>
<revision>
<version>1.1</version>
<date>2003-11-05</date>
<initials>psa</initials>
<remark>The status of this JEP has been changed to Retracted since it has been superseded by &xmppcore;. This JEP will not be considered further by the Jabber Software Foundation and should not be used as a basis for implementations.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2002-08-13</date>
<initials>psa</initials>
<remark>Changed status to Draft.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-07-26</date>
<initials>rn</initials>
<remark>Reworked for server-to-server SASL; added jabber:iq:auth get (as in xmpp-im).</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-06-05</date>
<initials>rn</initials>
<remark>Fleshed out.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-06-03</date>
<initials>psa</initials>
<remark>Initial version based on Jer's notes.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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".</p>
<p>This profile may be used for both client-to-server and server-to-server connections. For client connections, the service name used is &quot;jabber-client&quot;. For server connections, the service name used is &quot;jabber-server&quot;. Both these names are registered in the IANA service registry.</p>
<p>The reader is expected to have read and understood the SASL specification before reading this document.</p>
</section1>
<section1 topic='Protocol'>
<section2 topic="Overview">
<p>In these examples, &quot;client&quot; refers to the remote entity that initiated the connection, either a Jabber client or a Jabber server. &quot;Server&quot; refers to the server that the remote entity is attempting to connect and authenticate to.</p>
<p>The steps involved for a SASL negotiation are as follows:</p>
<ol>
<li>Client requests SASL authentication</li>
<li>Server responds with list of available SASL authentication mechanisms</li>
<li>Client selects mechanism</li>
<li>Server sends a challenge</li>
<li>Client responds to challenge</li>
<li>Server sends more challenges, client sends more responses</li>
</ol>
<p>This series of challenge/response pairs continues until one of three things happens:</p>
<ol>
<li>Client aborts the handshake.</li>
<li>Server reports failure.</li>
<li>Server reports success.</li>
</ol>
<p>After authentication has completed, the client sends a packet to begin the session.</p>
<p>The namespace identifier for this protocol is http://www.iana.org/assignments/sasl-mechanisms.</p>
<p>The following examples show the dialogue between a client [C] and a server [S].</p>
<p>
</p>
</section2>
<section2 topic="Stream initialization">
<p>The client begins by requesting SASL authentication as part of the normal Jabber stream negotiation. <note>In the case of the remote entity being a server, the default namespace in the stream header will be &quot;jabber:server&quot;.</note> The server responds by sending the available authentication mechanisms to the client along with the stream information:</p>
<example caption="Stream initialization">
C: &lt;stream:stream xmlns=&apos;jabber:client&apos;
xmlns:stream=&apos;http://etherx.jabber.org/streams&apos;
xmlns:sasl=&apos;http://www.iana.org/assignments/sasl-mechanisms&apos;
to=&apos;jabber.org&apos;&gt;
S: &lt;stream:stream xmlns=&apos;jabber:client&apos;
xmlns:stream=&apos;http://etherx.jabber.org/streams&apos;
xmlns:sasl=&apos;http://www.iana.org/assignments/sasl-mechanisms&apos;
id=&apos;12345678&apos;&gt;
&lt;sasl:mechanisms&gt;
&lt;sasl:mechanism&gt;PLAIN&lt;/sasl:mechanism&gt;
&lt;sasl:mechanism&gt;DIGEST-MD5&lt;/sasl:mechanism&gt;
&lt;sasl:mechanism&gt;EXTERNAL&lt;/sasl:mechanism&gt;
&lt;sasl:mechanisms&gt;
</example>
</section2>
<section2 topic="Mechanism selection and handshake">
<p>Next, the client selects an authentication mechanism:</p>
<example caption="Plaintext mechanism selection">
C: &lt;sasl:auth mechanism=&apos;PLAIN&apos;/&gt;
</example>
<p>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.</p>
<p>Challenges and responses are Base64<note><link url="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</link>, section 6.8.</note> encoded.</p>
<example caption="Plaintext handshake">
S: &lt;sasl:challenge/&gt;
C: &lt;sasl:response&gt;cm9iAHNlY3JldA==&lt;/sasl:response&gt;
</example>
<example caption="Digest handshake">
S: &lt;sasl:challenge&gt;
cmVhbG09ImNhdGFjbHlzbS5jeCIsbm9uY2U9Ik9BNk1HOXRFUUdtMmhoIi
xxb3A9ImF1dGgiLGNoYXJzZXQ9dXRmLTgsYWxnb3JpdGhtPW1kNS1zZXNz
&lt;/sasl:challenge&gt;
C: &lt;sasl:response&gt;
dXNlcm5hbWU9InJvYiIscmVhbG09ImNhdGFjbHlzbS5jeCIsbm9uY2U9Ik
9BNk1HOXRFUUdtMmhoIixjbm9uY2U9Ik9BNk1IWGg2VnFUclJrIixuYz0w
MDAwMDAwMSxxb3A9YXV0aCxkaWdlc3QtdXJpPSJqYWJiZXIvY2F0YWNseX
NtLmN4IixyZXNwb25zZT1kMzg4ZGFkOTBkNGJiZDc2MGExNTIzMjFmMjE0
M2FmNyxjaGFyc2V0PXV0Zi04
&lt;/sasl:response&gt;
S: &lt;sasl:challenge&gt;
cnNwYXV0aD1lYTQwZjYwMzM1YzQyN2I1NTI3Yjg0ZGJhYmNkZmZmZA==
&lt;/sasl:challenge&gt;
C: &lt;sasl:response/&gt;
</example>
<p>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:</p>
<example caption="Plaintext mechanism selection; client sends data first">
C: &lt;sasl:auth mechanism=&apos;PLAIN&apos;&gt;cm9iAHNlY3JldA==&lt;/sasl:auth&gt;
</example>
</section2>
<section2 topic="Success, failure and client abort">
<p>The handshake continues until authentication completes successfully, authentication fails, or the client aborts the handshake:</p>
<example caption="Authentication success">
S: &lt;sasl:success/&gt;
</example>
<example caption="Authentication failure">
S: &lt;sasl:failure/&gt;
</example>
<example caption="Client abort">
C: &lt;sasl:abort/&gt;
</example>
<p>Optionally, the server or client may send an informative message along with the success, failure or abort command:</p>
<example caption="Authentication failure; optional informative message">
S: &lt;sasl:failure&gt;Plaintext authentication failed (Incorrect username or password)&lt;/sasl:failure&gt;
</example>
<p>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.</p>
</section2>
<section2 topic='Session start'>
<p>Note: that this section only applies to client-to-server connections.</p>
<p>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.</p>
<example caption="Session start after successful authentication">
C: &lt;iq id=&quot;a1&quot; type=&quot;get&quot;&gt;
&lt;query xmlns=&quot;jabber:iq:auth&quot;&gt;
&lt;username&gt;rob&lt;/username&gt;
&lt;/query&gt;
&lt;/iq&gt;
S: &lt;iq id=&quot;a1&quot; type=&quot;result&quot;&gt;
&lt;query xmlns=&quot;jabber:iq:auth&quot;&gt;
&lt;username&gt;rob&lt;/username&gt;
&lt;resource/&gt;
&lt;/query&gt;
&lt;/iq&gt;
C: &lt;iq id=&quot;a2&quot; type=&quot;set&quot;&gt;
&lt;query xmlns=&quot;jabber:iq:auth&quot;&gt;
&lt;username&gt;rob&lt;/username&gt;
&lt;resource&gt;laptop&lt;/resource&gt;
&lt;/query&gt;
&lt;/iq&gt;
S: &lt;iq id=&quot;a2&quot; type=&quot;result&quot;&gt;
&lt;query xmlns=&quot;jabber:iq:auth&quot;/&gt;
&lt;/iq&gt;
</example>
<p>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.</p>
</section2>
</section1>
<section1 topic='Support for existing authentication methods'>
<p>Traditionally, Jabber servers have supported two authentication models - jabber:iq:auth for client-to-server authentication, and dialback for server-to-server authentication.</p>
<section2 topic='Legacy client-to-server authentication support'>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section2>
<section2 topic='Dialback support for server-to-server authentication'>
<p>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.</p>
<p>To this end, the use of dialback is not deprecated. If a remote server connects and requests the use of dialback (by specifying the &quot;jabber:server:dialback&quot; 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.</p>
</section2>
</section1>
</jep>

129
xep-0035.xml Normal file
View File

@ -0,0 +1,129 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>SSL/TLS Integration</title>
<abstract>NOTE WELL: this JEP was retracted on 2003-11-05 since the topic is addressed definitively in XMPP Core. Please refer to XMPP Core for further information.</abstract>
&LEGALNOTICE;
<number>0035</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards</jig>
<dependencies>None</dependencies>
<supersedes>None</supersedes>
<supersededby>XMPP Core</supersededby>
<shortname>N/A</shortname>
<author>
<firstname>Robert</firstname>
<surname>Norris</surname>
<email>rob@cataclysm.cx</email>
<jid>rob@cataclysm.cx</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-11-05</date>
<initials>psa</initials>
<remark>The status of this JEP has been changed to Retracted since it has been superseded by &xmppcore;. This JEP will not be considered further by the Jabber Software Foundation and should not be used as a basis for implementations.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-06-14</date>
<initials>rn</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>The TLS protocol <note><link url="http://www.ietf.org/rfc/rfc2246.txt">RFC 2246</link></note> (formerly known as SSL) provides a way to secure an application protocol from tampering and eavesdropping. The option of using such security is desirable for Jabber due to common connection eavesdropping and hijacking attacks. <note>See <link url="http://www.ietf.org/rfc/rfc1704.txt">RFC 1704</link>, "On Internet Authentication."</note><note>This paragraph adapted from <link url="http://www.ietf.org/rfc/rfc2595.txt">RFC 2595</link>, section 1.</note></p>
<p>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 <note>The Internet Assigned Numbers Authority defines jabber-client (port 5222) and jabber-server (port 5269) as the standard Jabber ports; see <link url='http://www.iana.org/assignments/port-numbers'>http://www.iana.org/assignments/port-numbers</link>.</note> (commonly 5223 for client-to-server communications and 5270 for server-to-server communications). In the case of client-to-server communications, clients must initiate a TLS session immediately after connecting, before beginning the normal XML stream. This method of utilising TLS is typical of many servers that implement stream-based protocols, but has a number of flaws, which are outlined in section 7 of <link url="http://www.ietf.org/rfc/rfc2595.txt">RFC 2595</link>. Accordingly, the use of port 5223 and port 5270 for secure sessions is deprecated.</p>
<p>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 <link url="http://www.ietf.org/rfc/rfc2595.txt">RFC 2595</link>, which describes the STARTTLS extension for the IMAP <note><link url="http://www.ietf.org/rfc/rfc2060">RFC 2060</link></note>, POP3 <note><link url="http://www.ietf.org/rfc/rfc1939">RFC 1939</link></note> and ACAP <note><link url="http://www.ietf.org/rfc/rfc2244">RFC 2244</link></note> protocols. A future document (or an addition to this document) will define TLS support within server-to-server streams.</p>
</section1>
<section1 topic='Protocol'>
<section2 topic="Overview">
<p>This protocol operates over the standard Jabber client connection on port 5222.</p>
<p>The namespace identifier for this protocol is http://www.ietf.org/rfc/rfc2595.txt.</p>
<p>The following examples show the dialogue between a client [C] and a server [S].</p>
<p>
</p>
</section2>
<section2 topic="Stream initialization">
<p>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:</p>
<example caption="Stream initialization">
C: &lt;stream:stream xmlns=&apos;jabber:client&apos;
xmlns:stream=&apos;http://etherx.jabber.org/streams&apos;
xmlns:tls=&apos;http://www.ietf.org/rfc/rfc2595.txt&apos;
to=&apos;jabber.org&apos;&gt;
S: &lt;stream:stream xmlns=&apos;jabber:client&apos;
xmlns:stream=&apos;http://etherx.jabber.org/streams&apos;
xmlns:tls=&apos;http://www.ietf.org/rfc/rfc2595.txt&apos;
id=&apos;12345678&apos;&gt;
</example>
<p>In the event that a server does not support the STARTTLS extension, it will respond with the normal stream negotiation response:</p>
<example caption="Stream initialization; server not supporting STARTTLS">
C: &lt;stream:stream xmlns=&apos;jabber:client&apos;
xmlns:stream=&apos;http://etherx.jabber.org/streams&apos;
xmlns:tls=&apos;http://www.ietf.org/rfc/rfc2595.txt&apos;
to=&apos;jabber.org&apos;&gt;
S: &lt;stream:stream xmlns=&apos;jabber:client&apos;
xmlns:stream=&apos;http://etherx.jabber.org/streams&apos;
id=&apos;12345678&apos;&gt;
</example>
</section2>
<section2 topic="TLS negotiation">
<p>To begin the TLS negotiation, the client issues the STARTTLS command:</p>
<example caption="STARTTLS request">
C: &lt;tls:starttls/&gt;
</example>
<p>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:</p>
<example caption="STARTTLS response">
S: &lt;/stream:stream&gt;
</example>
<p>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:</p>
<example caption="Stream initialization">
C: &lt;stream:stream xmlns=&apos;jabber:client&apos;
xmlns:stream=&apos;http://etherx.jabber.org/streams&apos;
to=&apos;jabber.org&apos;&gt;
S: &lt;stream:stream xmlns=&apos;jabber:client&apos;
xmlns:stream=&apos;http://etherx.jabber.org/streams&apos;
id=&apos;12345678&apos;&gt;
</example>
<p>This is necessary, since any information about the stream presented by the server or the client may have been modified by an attacker.</p>
<p>Note that once the secure channel has been established, the server must not advertise or allow the use of the STARTTLS command.</p>
</section2>
</section1>
<section1 topic="Certificate-based authentication">
<p>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 <note><link url="http://www.jabber.org/jeps/jep-0034.html">JEP-0034</link></note> and the EXTERNAL mechanism.</p>
<p>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 <link url="http://www.ietf.org/rfc/rfc2222">RFC 2222</link> and <link url="http://www.jabber.org/jeps/jep-0034.html">JEP-0034</link> for more information.</p>
<p>Servers implementing STARTTLS functionality are not required to implement certificate-based authentication.</p>
</section1>
</jep>

126
xep-0036.xml Normal file
View File

@ -0,0 +1,126 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Pub-Sub Subscriptions</title>
<abstract>A proposal for the subscribe half of a publish-subscribe protocol within Jabber.</abstract>
&LEGALNOTICE;
<number>0036</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards</jig>
<supersedes>None</supersedes>
<supersededby>JEP-0060</supersededby>
<shortname>None</shortname>
<author>
<firstname>Peter</firstname>
<surname>Millard</surname>
<email>pgmillard@jabber.org</email>
<jid>pgmillard@jabber.org</jid>
</author>
<author>
<firstname>Peter</firstname>
<surname>Saint-Andre</surname>
<email>stpeter@jabber.org</email>
<jid>stpeter@jabber.org</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-04-22</date>
<initials>psa</initials>
<remark>At the request of the authors, the status of this JEP has been changed to Retracted since it has been superseded by JEP-0060. This JEP will not be considered further by the Jabber Software Foundation and should not be used as a basis for implementations.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-07-12</date>
<initials>psa</initials>
<remark>Initial version based on discussions at JabberConf.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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. <note><link url='http://www.jabber.org/jeps/jep-0021.html'>JEP-0021</link>, <link url='http://www.jabber.org/jeps/jep-0024.html'>JEP-0024</link>, <link url='http://www.jabber.org/jeps/jep-0028.html'>JEP-0028</link>.</note> Unfortunately, past discussion of this issue has been clouded by confusion over requirements and even terminology. This JEP seeks to clarify the situation somewhat and to provide a protocol for the subscribe half of publish-subscribe functionality within Jabber.</p>
</section1>
<section1 topic='Narrative'>
<p>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:</p>
<ul>
<li>Auction and trading systems</li>
<li>Online catalogs</li>
<li>Document workflow systems</li>
<li>Network management systems</li>
<li>NNTP over Jabber</li>
<li>Groupchat</li>
</ul>
<p>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:</p>
<ol>
<li>A description of the information that will be provided</li>
<li>A list of subscribers to items that fit the description</li>
<li>One or more items that fit the description</li>
</ol>
<p>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.)</p>
<p>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).</p>
</section1>
<section1 topic='Protocol Details'>
<example caption="Protocol">
&lt;iq type="set" from="pgm@jabber.org" to="pubsub.jabber.org" id="1"&gt;
&lt;query xmlns="jabber:iq:pubsub"&gt;
&lt;subscribe&gt;
&lt;topic id="12345"/&gt;
&lt;topic id="/presence/dizzyd@jabber.org"/&gt;
&lt;/subscribe&gt;
&lt;/query&gt;
&lt;/iq&gt;
&lt;iq type="set" from="pgm@jabber.org" to="pubsub.jabber.org" id="1"&gt;
&lt;query xmlns="jabber:iq:pubsub"&gt;
&lt;unsubscribe&gt;
&lt;topic id="12345"/&gt;
&lt;/unsubscribe&gt;
&lt;/query&gt;
&lt;/iq&gt;
&lt;iq type="set" to="pubsub.jabber.org" id="1"&gt;
&lt;query xmlns="jabber:iq:pubsub"&gt;
&lt;publish&gt;
&lt;topic id="12345"&gt;
&lt;item&gt;some kind of cdata goes here&lt;/item&gt;
&lt;/topic&gt;
&lt;/publish&gt;
&lt;/query&gt;
&lt;/iq&gt;
&lt;iq type="set" to="pubsub.jabber.org" id="1"&gt;
&lt;query xmlns="jabber:iq:pubsub"&gt;
&lt;createtopic&gt;
&lt;topic id="new_topic"&gt;
&lt;profile&gt;
&lt;!-- is this even remotely close?? --&gt;
&lt;publisher&gt;pgm@jabber.org&lt;/publisher&gt;
&lt;publisher&gt;dizzyd@jabber.org&lt;/publisher&gt;
&lt;/profile&gt;
&lt;/topic&gt;
&lt;topic id="another_topic&gt;
&lt;profile&gt;
&lt;publisher/&gt;
&lt;/profile&gt;
&lt;/topic&gt;
&lt;/createtopic&gt;
&lt;/query&gt;
&lt;/iq&gt;
&lt;iq type="set" to="pubsub.jabber.org" id="1"&gt;
&lt;query xmlns="jabber:iq:pubsub"&gt;
&lt;removetopic&gt;
&lt;topic id="12345"/&gt;
&lt;/removetopic&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
</section1>
</jep>

848
xep-0037.xml Normal file
View File

@ -0,0 +1,848 @@
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<jep>
<header>
<title>DSPS - Data Stream Proxy Service</title>
<abstract>A proposal for proxy support in Jabber.</abstract>
<legal>This document has been placed in the public domain.</legal>
<number>0037</number>
<status>Rejected</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<author>
<firstname>David</firstname>
<surname>Sutton</surname>
<email></email>
<jid></jid>
</author>
<author>
<firstname>"Bac9"</firstname>
<surname></surname>
<email>bac9@bac9.yi.org</email>
<jid>bac9@jabber.org</jid>
</author>
<revision>
<version>Version 0.8</version>
<date>2002-09-18</date>
<initials>Bac9</initials>
<remark>Streamlined and enhanced handshake procedure, and cleaned up document.</remark>
</revision>
<revision>
<version>Version 0.7</version>
<date>2002-08-20</date>
<initials>Bac9</initials>
<remark>Added public connections and reduced number of tags.</remark>
</revision>
<revision>
<version>Version 0.6</version>
<date>2002-08-11</date>
<initials>Bac9</initials>
<remark>Added data tracking, inviting peer, auto-disconnect for slow peers, elaboration on protocol and suggested example of file transfer.</remark>
</revision>
<revision>
<version>Version 0.5</version>
<date>2002-07-29</date>
<initials>Bac9</initials>
<remark>Elaborated on some functionality and cleaned up XML protocol.</remark>
</revision>
<revision>
<version>Version 0.4</version>
<date>2002-07-11</date>
<initials>lw</initials>
<remark>Reformatted to JEP XML.</remark>
</revision>
<revision>
<version>Version 0.3</version>
<date>2002-06-25</date>
<initials>Bac9</initials>
<remark>Added support for HTTP, SSL and throughput logging. Changed relay behaviour.</remark>
</revision>
<revision>
<version>Version 0.2</version>
<date>2002-06-21</date>
<initials>Bac9</initials>
<remark>Revised, standardized and extended XML protocol structure.</remark>
</revision>
<revision>
<version>Version 0.1</version>
<date></date>
<initials>rn</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
</section1>
<section1 topic='Startup'>
<p>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).</p>
</section1>
<section1 topic='General Operation'>
<section2 topic='Stream Creation/Relay {optional}'>
<p><em>(optional)</em> Creating or modifying stream is done like so:</p>
<example>
&lt;iq
id='dsps1'
type='get'
from='rob@nauseum.org/dspsclient'
to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a44'&gt;
&lt;query type='create'
xmlns='jabber:iq:dsps'
minthroughput='1.5KB'
maxpublic='20'&gt;
&lt;peer port='5290'&gt;
dsps.myjabber.net/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33
&lt;/peer&gt;
&lt;comment&gt;public comment&lt;/comment&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;to&quot;</strong> with resource implies reconnection to previous relay stream with previously supplied credentials and authentication as per section &quot;DSPS relay setup&quot;, otherwise implies creation of new stream where creator is granted &quot;master&quot; rights.</li>
<li><strong>&quot;minthroughput&quot;</strong> <em>(optional)</em> 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 &quot;who&quot; query for each peer. Legal only upon initial creation of stream. If omitted or negative, 0 is assumed.</li>
<li><strong>&quot;maxpublic&quot;</strong> <em>(optional)</em> 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 &quot;stats&quot; message. Said id remains constant for life of stream.</li>
<li><strong>&lt;peer/&gt;</strong> <em>(optional)</em> full JID of stream on another DSPS. Relay stream will be treated using &quot;slave&quot; 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 &lt;peer/&gt; 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 &quot;Connecting to DSPS via default method&quot;. Authentication is done as per section &quot;DSPS relay setup&quot;. Upon successful handshake, DSPS sends presence notification to peer as per section &quot;Acknowledge of DSPS connection&quot;.</li>
<li><strong>&quot;port&quot;</strong> <em>(optional)</em> for connecting to destination DSPS. If omitted, default is assumed.</li>
<li><strong>&lt;comment/&gt;</strong> <em>(optional)</em> all such blocks reported in &quot;stats&quot; message. Multiple such blocks allowed. Block may contain a full XML stack of elements. No order implied for &quot;stats&quot; message.</li>
</ul>
<p>Possible failure messages:</p>
<table>
<tr><th>Code</th><th>Message</th><th>Description</th></tr>
<tr><td>405</td><td>Method Not Allowed</td><td>Attempt at reconnect to relay without existing credentials, relay still connected, &lt;peer/&gt; block present in reconnect request, or feature not supported</td></tr>
<tr><td>504</td><td>Gateway Timeout</td><td>All destination DSPS are unreachable.</td></tr>
</table>
</section2>
<section2 topic='Connection waiting'>
<p>DSPS creates &quot;id&quot; (empty string is legal), used in &quot;who&quot; replies and notifies client of waiting connection like so:</p>
<example>
&lt;iq
id='dsps1'
type='result'
from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
to='rob@nauseum.org/dspsclient'&gt;
&lt;query type='create' xmlns='jabber:iq:dsps'
wait='10'
host='dsps.jabber.org'
port='5290'
minthroughput='1.5KB'
protocol='0.5'&gt;
&lt;feature type='http' version='1.1'/&gt;
&lt;feature type='ssl' version='3.0'/&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;from&quot;</strong> full JID of DSPS, internally globally unique. Used in handshake and every subsequent communication with stream. May differ with the one specified in &quot;invite&quot; message.</li>
<li><strong>&quot;wait&quot;</strong> amount of time in <strong>milliseconds</strong> that DSPS will wait for client to initiate handshake. If timeout occurs, DSPS will totally forget prepared connection and act accordingly.</li>
<li><strong>&quot;host&quot;</strong> <em>(optional)</em> for handshake and data stream. If omitted default from the &quot;from&quot; is assumed. Intended for P2P connections to be able to report alternate hostname or IP for connection.</li>
<li><strong>&quot;port&quot;</strong> <em>(optional)</em> for handshake and data stream. If omitted default is assumed.</li>
<li><strong>&quot;minthroughput&quot;</strong> value from &quot;create&quot;.</li>
<li><strong>&quot;protocol&quot;</strong> version this DSPS supports.</li>
<li><strong>&lt;feature/&gt;</strong> <em>(optional)</em> 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.</li>
</ul>
</section2>
<section2 topic='Establishing prepared connection'>
<p>Upon receipt of message as per section &quot;Connection waiting&quot;, 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 &quot;Connecting to DSPS via default method&quot;. DSPS will not discriminate method via which direct connection is made, even if prior to &quot;disconnect&quot; a different method was used. Any packet from an unauthorized connection is ignored without reporting an error.</p>
<section3 topic='DSPS relay setup {optional}'>
<p>Client may request another DSPS to relay this connection as per section &quot;Stream Creation/Relay&quot;, utilizing the &quot;create&quot; 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):</p>
<example>
&lt;iq
id='dsps1'
type='get'
from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
to='rob@nauseum.org/dspsclient'&gt;
&lt;query type='create' xmlns='jabber:iq:dsps'&gt;acDgH63I27Gb1&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;get&quot;</strong> denotes request for auth key.</li>
<li><strong>&quot;create&quot;</strong> body contains key returned by destination.</li>
</ul>
<p>Client must send said key to destination as per section &quot;Connecting to DSPS via default method&quot; and send response to DSPS (which will be transmitted to destination) like so:</p>
<example>
&lt;iq
id='dsps1'
type='result'
from='rob@nauseum.org/dspsclient'
to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
&lt;query type='create' xmlns='jabber:iq:dsps'&gt;acDgH63I27Gb1&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;result&quot;</strong> denotes reply with auth key.</li>
<li><strong>&quot;create&quot;</strong> body contains key returned by destination.</li>
</ul>
</section3>
<section3 topic='Connecting to DSPS via HTTP method {optional}'>
<p>Client must connect to DSPS on port 80 and initiate handshake. This may be attempted after &quot;create&quot; result received or &quot;disconnect&quot; occurred, and prior to &quot;wait&quot; timeout expiring, then send HTTP request like so:</p>
<example>
GET /DSPS/STREAM/ HTTP/1.0&lt;CR&gt;
Host: dsps.server&lt;CR&gt;
&lt;CR&gt;
</example>
<p>And will receive reply from DSPS before the start of data stream, like so:</p>
<example>
HTTP/1.0 200 OK&lt;CR&gt;
Content-Type: application/octet-stream&lt;CR&gt;
&lt;CR&gt;
</example>
<p>Upon completion, Client must resume DSPS handshake as per either section &quot;Connecting to DSPS via default method&quot; or section &quot;Connecting to DSPS via SSL method&quot; (if applicable). Subsequent data will not follow HTTP protocol. On error connection closed immediately with optional error messages.</p>
<p>Possible failure messages:</p>
<table>
<tr><th>Code</th><th>Message</th><th>Description</th></tr>
<tr><td>401</td><td>Unauthorized</td><td><em>(optional)</em> Returned if any error in HTTP handshake.</td></tr>
</table>
</section3>
<section3 topic='Connecting to DSPS via SSL method {optional}'>
<p>Client must connect to DSPS on specified port and initiate handshake. This may be attempted after &quot;create&quot; result received or &quot;disconnect&quot; occurred, and prior to &quot;wait&quot; timeout expiring, then send following on stream:</p>
<example>starttls&lt;CR&gt;</example>
<p>Next, regular TLS handshake is initiated. Upon completion, Client must resume DSPS handshake as per section &quot;Connecting to DSPS via default method&quot;. On error connection closed immediately with optional error messages.</p>
<p>Possible failure messages:</p>
<table>
<tr><th>Code</th><th>Message</th><th>Description</th></tr>
<tr><td>401</td><td>Unauthorized</td><td><em>(optional)</em> Returned if any error in SSL handshake.</td></tr>
</table>
</section3>
<section3 topic='Connecting to DSPS via default method'>
<p>Client must connect to DSPS on specified port and initiate handshake. May be attempted after &quot;create&quot; result received or &quot;disconnect&quot; occurred, and prior to &quot;wait&quot; timeout expiring. Standard and SSL handshakes are identical in decrypted state and take the form of:</p>
<example>Client_full_JID DSPS_full_JID&lt;CR&gt;</example>
<ul>
<li><strong>&quot;Client_full_JID&quot;</strong> client full JID as supplied in either the &quot;create&quot; or &quot;acknowledge&quot; message.</li>
<li><strong>&quot;DSPS_full_JID&quot;</strong> DSPS full JID as supplied in &quot;from&quot; field of &quot;create&quot; result message from section &quot;Connection waiting&quot;</li>
<li><strong>&lt;CR&gt;</strong> regular carriage return, commonly referred to as the newline character.</li>
</ul>
<p>For example, the appropriate string for the above request would be:</p>
<example>rob@nauseum.org/dspsclient dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33</example>
<p>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 &lt;CR&gt; like so:</p>
<example>uGhhb74d21</example>
<p>Client must now send key to DSPS via XML stream like so:</p>
<example>
&lt;iq
id='dsps1'
type='get'
from='rob@nauseum.org/dspsclient'
to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'&gt;
&lt;query type='auth' xmlns='jabber:iq:dsps'&gt;uGhhb74d21&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;get&quot;</strong> denotes request for next auth key.</li>
<li><strong>&quot;auth&quot;</strong> body contains key returned by DSPS.</li>
</ul>
<p>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:</p>
<example>
&lt;iq
id='dsps1'
type='result'
from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
to='rob@nauseum.org/dspsclient'
&lt;query type='auth' xmlns='jabber:iq:dsps'&gt;qgqB42Ij784&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;result&quot;</strong> denotes return of next auth key.</li>
<li><strong>&quot;auth&quot;</strong> body contains key returned by DSPS.</li>
</ul>
<p>Client must now send received key to DSPS via the stream followed by a &lt;CR&gt;. 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 &quot;master&quot; connection, all members of the stream get notified. If the client had type &quot;slave&quot; connection, only other type &quot;master&quot; members get notified. The message takes the form of:</p>
<example>
&lt;iq
id='dsps2'
type='set'
from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
to='foo@bar.com/resource'&gt;
&lt;query type='presence' xmlns='jabber:iq:dsps'&gt;
&lt;peer status='connect'&gt;JID&lt;/peer&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;presence&quot;</strong> denotes presence change. Body may contain multiple &lt;peer/&gt; blocks where same JID peers must be placed in chronological order relative to each other from start to end of message.</li>
<li><strong>&lt;peer/&gt;</strong> body is full JID of the joined peer unless peer of type &quot;relay&quot;, in which case the resource is not reported.</li>
<li><strong>&quot;status&quot;</strong> is new status of peer.</li>
</ul>
<p>Possible failure messages:</p>
<table>
<tr><th>Code</th><th>Message</th><th>Description</th></tr>
<tr><td>401</td><td>Unauthorized</td><td><em>(optional)</em> Returned if the DSPS is not aware of said Client_full_JID + DSPS_full_JID pair. Where &quot;from&quot; contains DSPS_full_JID that was used in the handshake and &quot;to&quot; contains Client_full_JID that was used in the handshake.</td></tr>
<tr><td>409</td><td>Conflict</td><td><em>(optional)</em> Returned if connection from said full client JID and full DSPS JID is in use (i.e. client is still connected to it). Where &quot;from&quot; contains DSPS_full_JID that was used in the handshake and &quot;to&quot; contains Client_full_JID that was used in the handshake.</td></tr>
</table>
</section3>
</section2>
<section2 topic='Stream administration'>
<p>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: &quot;master&quot;, &quot;slave&quot;, and &quot;relay&quot;. &quot;master&quot; peers get full control of the stream, &quot;slave&quot; peers get limited control of the stream, and &quot;relay&quot; are treated similar to &quot;slave&quot; except in reporting of JIDs where the resource must be omitted.</p>
<p>&quot;master&quot; peers are allowed to invite any other user to the stream and drop any peer registered with the stream, including themselves. &quot;slave&quot; peers are only allowed to drop themselves from the stream. Any administrative changes coming from a &quot;slave&quot; 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.</p>
<p>Any data received from a &quot;master&quot; gets copied to every other peer on the stream. Any data received from a &quot;slave&quot; peer gets copied to all &quot;master&quot; peers on the stream only.</p>
<p>Stream administration request looks like so:</p>
<example>
&lt;iq
id='dsps3'
type='set'
from='rob@nauseum.org/dspsclient'
to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'&gt;
&lt;query type='admin' xmlns='jabber:iq:dsps' expire='20' wait='10'&gt;
&lt;comment&gt;welcome to the stream&lt;/comment&gt;
&lt;peer type='master'&gt;someone@somewhere.net&lt;/peer&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;admin&quot;</strong> denotes administrative functions are to follow. Any properties within this block apply to this block alone. Multiple such blocks are allowed.</li>
<li><strong>&quot;expire&quot;</strong> time DSPS should wait for the &quot;acknowledge&quot; message from any invited peer within block. An &quot;expire&quot; of 0 denotes no time limit. Actual value sent to peer as &quot;expire&quot; is <em>minimum</em> of this value and default value preset for DSPS. If value unparseable or not present, default is used.</li>
<li><strong>&quot;wait&quot;</strong> time DSPS should wait for invited peer to connect to DSPS after &quot;acknowledge&quot; is received and message from section &quot;Connection waiting&quot;. is sent. A &quot;wait&quot; of 0 denotes no time limit. Actual value sent to peer as &quot;wait&quot; is <em>minimum</em> of this value and default value preset for DSPS. If the value unparseable or not present, default is used.</li>
<li><strong>&lt;comment/&gt;</strong> <em>(optional)</em> 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 &lt;invite/&gt; message.</li>
<li><strong>&lt;peer/&gt;</strong> 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.</li>
<li><strong>&quot;type&quot;</strong> type of action to do. &quot;master&quot; denotes invitation, granting master rights. &quot;slave&quot; denotes invitation, granting slave rights. &quot;drop&quot; denotes request to drop peer from stream. &quot;relay&quot; peers may not be invited but may be dropped using this method.</li>
</ul>
<p>Possible optional errors include the following:</p>
<example>
&lt;iq
id='dsps3'
type='result'
from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
to='user@server.org/resource'&gt;
&lt;query type='admin' xmlns='jabber:iq:dsps'&gt;
&lt;peer acknowledge='expire'&gt;abc@company.com/net&lt;/peer&gt;
&lt;peer acknowledge='reject'&gt;friend@someplace.com/home&lt;/peer&gt;
&lt;peer acknowledge='timeout'&gt;abd@company.com/net&lt;/peer&gt;
&lt;peer acknowledge='missing'&gt;who@knows.org/winjab&lt;/peer&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;admin&quot;</strong> denotes admin response, sent to sender of &quot;admin&quot; request for every peer in block. Peers may be combined from multiple &quot;admin&quot; requests or peers from single &quot;admin&quot; request may be split over multiple &quot;admin&quot; replies.</li>
<li><strong>&lt;peer/&gt;</strong> peer in question. For &quot;expire&quot; JID is one from invite request. For &quot;reject&quot; JID is one from which reject received. For &quot;timeout&quot; JID is one from invite request. For &quot;missing&quot; is one from drop request. After this DSPS will totally forget about this peer.</li>
<li><strong>&quot;acknowledge&quot;</strong> reason for failure. &quot;expire&quot; denotes &quot;expire&quot; timeout sent, has ended. &quot;reject&quot; denotes peer rejected invite. &quot;timeout&quot; denotes &quot;wait&quot; timeout sent, has ended. &quot;missing&quot; denotes peer marked for drop not found registered on tis stream.</li>
</ul>
<p>Possible failure messages:</p>
<table>
<tr><th>Code</th><th>Message</th><th>Description</th></tr>
<tr><td>403</td><td>Forbidden</td><td><em>(optional)</em> Returned if peer with &quot;slave&quot; rights attempts to use &quot;master&quot; admin privileges.</td></tr>
</table>
<section3 topic='Invitation to stream {optional}'>
<p>Upon invite DSPS will attempt to invite each of the peers like so:</p>
<example>
&lt;iq
id='dsps4'
type='get'
from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
to='foo@bar.com/resource'&gt;
&lt;query type='acknowledge'
xmlns='jabber:iq:dsps'
status='master'
expire='20'&gt;
&lt;peer&gt;rob@nauseum.org/dspsclient&lt;/peer&gt;
&lt;comment&gt;some long comment block or structure&lt;/comment&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;from&quot;</strong> is unique JID/resource pair generated for this JID, not necessarily same as JID/resource pair specified in section &quot;Connection waiting&quot;. It is used for identification of the &quot;acknowledge&quot; message.</li>
<li><strong>&quot;acknowledge&quot;</strong> denotes request for invitation acknowledge.</li>
<li><strong>&quot;status&quot;</strong> type of connection the client is granted. Same type as tag in invitation request.</li>
<li><strong>&quot;expire&quot;</strong> time DSPS will wait for the &quot;acknowledge&quot; message.</li>
<li><strong>&lt;peer/&gt;</strong> 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.</li>
<li><strong>&lt;comment/&gt;</strong> is &lt;comment/&gt; structure(s) sent in admin request, present if admin request contained it.</li>
</ul>
</section3>
<section3 topic='Dropping from stream'>
<p>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:</p>
<example>
&lt;iq
id='dsps5'
type='set'
from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
to='foo@bar.com/resource'&gt;
&lt;query type='acknowledge' xmlns='jabber:iq:dsps' status='drop'&gt;
&lt;comment&gt;some long comment block or structure&lt;/comment&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;from&quot;</strong> is the DSPS JID/resource pair which DSPS has associated with this connection.</li>
<li><strong>&quot;acknowledge&quot;</strong> denotes drop notification. Despite the block name, this message does not require a reply.</li>
<li><strong>&quot;status&quot;</strong> drop denotes a connection drop.</li>
<li><strong>&lt;comment/&gt;</strong> is &lt;comment/&gt; structure(s) sent in admin request, preset if admin request contained it.</li>
</ul>
<p>For every successfully dropped peer a message is sent to all other stream members, following the rules stated for the &quot;presence&quot; message, and takes the form of:</p>
<example>
&lt;iq
id='dsps6'
type='set'
from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
to='foo@bar.com/resource'&gt;
&lt;query type='presence' xmlns='jabber:iq:dsps'&gt;
&lt;peer status='drop'&gt;JID&lt;/peer&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;from&quot;</strong> is the DSPS JID/resource pair which DSPS has associated with the connection of the recipient of the message.</li>
<li><strong>&quot;presence&quot;</strong> denotes presence change. Body may contain multiple &lt;peer/&gt; blocks where same JID peers must be placed in chronological order relative to each other from start to end of message.</li>
<li><strong>&lt;peer/&gt;</strong> body is full JID of the dropped peer registered on the stream, unless peer is of type &quot;relay&quot;, in which case the resource is not reported.</li>
<li><strong>&quot;status&quot;</strong> is new status of peer.</li>
</ul>
</section3>
</section2>
<section2 topic='Invitation reply'>
<p>An invited peer has the option to accept or reject an invitation to a stream.</p>
<section3 topic='Accepting an invite'>
<p>To accept an invitation to a stream, the peer must reply like so:</p>
<example>
&lt;iq
id='dsps4'
type='result'
from='foo@bar.com/moredsps'
to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33&gt;
&lt;query type='acknowledge' xmlns='jabber:iq:dsps' status='connect'/&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;from&quot;</strong> 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.</li>
<li><strong>&quot;to&quot;</strong> contains the DSPS JID/resource pair which was the source in the original &quot;acknowledge&quot; message.</li>
<li><strong>&quot;acknowledge&quot;</strong> denotes acknowledgment to invitation.</li>
<li><strong>&quot;status&quot;</strong> connect denotes an acceptance of invitation.</li>
</ul>
<p>Upon receipt of this reply the DSPS creates a unique resource for this client JID/resource pair. It then prepares the &quot;create&quot; message as described in section &quot;Connection waiting&quot;.</p>
</section3>
<section3 topic='Rejecting an invite'>
<p>Rejecting an invitation can be done in two ways. A peer can forget about the invitation and let the invitation &quot;expire&quot;, or preferably a message can be sent like so:</p>
<example>
&lt;iq
id='dsps4'
type='result'
from='foo@bar.com/moredsps'
to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33&gt;
&lt;query type='acknowledge' xmlns='jabber:iq:dsps' status='drop'/&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;to&quot;</strong> contains the DSPS JID/resource pair which was the source in the original &quot;acknowledge&quot; message.</li>
<li><strong>&quot;acknowledge&quot;</strong> denotes acknowledgment to invitation.</li>
<li><strong>&quot;status&quot;</strong> drop denotes an rejection of invitation.</li>
</ul>
<p>Regardless of the way a rejection was achieved a notification message is sent to the inviting peer, as was described in section &quot;Stream administration&quot;. If unknown &quot;type&quot; is sent, it will be interpreted as a reject. A maximum of one &quot;acknowledge&quot; 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.</p>
</section3>
</section2>
<section2 topic='Disconnection handling'>
<p>If a peer ever disconnects without first dropping themselves, the following policy applies:</p>
<p>The peer may reconnect within the &quot;wait&quot; timeout provided in the &quot;create&quot; reply in section &quot;Connection waiting&quot;. The peer may choose any supported mode of reconnection supplied in &quot;create&quot; reply, regardless of mode previously used. The &quot;wait&quot; timeout is not cumulative over multiple disconnects. After reconnect, peer will not receive any data that exists on the stream while it was disconnected.</p>
<p>Upon such disconnection DSPS notifies all other members of the stream, following the rules stated for the &quot;presence&quot; message, and takes the form of:</p>
<example>
&lt;iq
id='dsps7'
type='set'
from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
to='foo@bar.com/resource'&gt;
&lt;query type='presence' xmlns='jabber:iq:dsps'&gt;
&lt;peer status='waiting'&gt;JID&lt;/peer&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;from&quot;</strong> is the DSPS JID/resource pair which DSPS has associated with the connection of the recipient of the message.</li>
<li><strong>&quot;presence&quot;</strong> denotes presence change. Body may contain multiple &lt;peer/&gt; blocks where same JID peers must be placed in chronological order relative to each other from start to end of message.</li>
<li><strong>&lt;peer/&gt;</strong> body is full JID of the disconnected peer registered on the stream, unless peer is of type &quot;relay&quot;, in which case the resource is not reported.</li>
<li><strong>&quot;status&quot;</strong> is new status of peer.</li>
</ul>
<p>Upon reaching &quot;wait&quot; timeout the procedure is the same if the peer dropped its own connection.</p>
</section2>
<section2 topic='Ending a connection'>
<p>Permanent termination of connection can be done in two ways: peer may disconnect from the stream and let the &quot;wait&quot; timeout expire, or more preferably the peer will drop itself from the stream via an &quot;admin&quot; message. The &quot;admin&quot; is still allowed to contain multiple &quot;peer&quot; blocks.</p>
</section2>
<section2 topic='Stream use'>
<p>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 &lt;comment/&gt; blocks). The DSPS stream operates at the speed of the slowest connection (or slower if it is so configured in its internal configuration).</p>
<p>Data read from peer in a unit of transfer (decided by DSPS) is sent to other peers in a format like so:</p>
<example>0&lt;size&gt;&lt;CR&gt;&lt;id&gt;&lt;CR&gt;&lt;data&gt;</example>
<ul>
<li><strong>&quot;0&quot;</strong> at beginning for checking start of block.</li>
<li><strong>&lt;size&gt;</strong> 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.</li>
<li><strong>&lt;id&gt;</strong> id of the sender as per &quot;who&quot; query.</li>
<li><strong>&lt;data&gt;</strong> data sent.</li>
<li><strong>&lt;CR&gt;</strong> regular carriage return, commonly referred to as the newline character.</li>
</ul>
<p>For example, the appropriate string for the above block would be:</p>
<example>
0340&lt;CR&gt;
010&lt;CR&gt;
this is the data in ASCII form
</example>
<p>First block received after connection will always be full block. If discrepancy occurs, receiving peer should disconnect and reconnect back to stream.</p>
</section2>
<section2 topic='Stream information'>
<p>Two mechanisms exists to gain information about the stream configuration and its members. They are described within next few subsections.</p>
<section3 topic='Stream peer listing'>
<p>To retrieve listing of all registered peers of this stream and their respective connection status any registered peer sends a message like so:</p>
<example>
&lt;iq
id='dsps8'
type='get'
from='rob@nauseum.org/dspsclient'
to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'&gt;
&lt;query type='who' xmlns='jabber:iq:dsps'/&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;to&quot;</strong> has the usual meaning for this client when referring to this DSPS stream.</li>
<li><strong>&quot;who&quot;</strong> denotes that this is a listing request. It may not contain a body or attributes, otherwise it will be ignored without error.</li>
</ul>
<p>The query follows the standard rules: query originating from a &quot;master&quot; peer will return listing of all registered peers and their associated statuses, query originating from a &quot;slave&quot; peer will only return listing of all registered &quot;master&quot; peers and their associated statuses. Returned results do not have any strict order. If multiple &quot;who&quot; queries were requested by a peer that have not yet received a reply, only one reply need be sent.</p>
<p>The query reply is formatted like so:</p>
<example>
&lt;iq
id='dsps8'
type='result'
from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
to='rob@nauseum.org/dspsclient'&gt;
&lt;query type='who' xmlns='jabber:iq:dsps'&gt;
&lt;peer
type='master'
id='0'
status='connect'
throughput='1KB////4.8KB//3KB'&gt;
rob@nauseum.org/dspsclient
&lt;/peer&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;from&quot;</strong> is unique DSPS JID/resource pair for the peer receiving the result.</li>
<li><strong>&lt;peer/&gt;</strong> body is full JID of registered peer, unless peer is of type &quot;relay&quot;, in which case the resource is not reported. A separate block exists for every viewable peer.</li>
<li><strong>&quot;type&quot;</strong> the type of connection peer has. May contain value of &quot;master&quot;, &quot;slave&quot;, or &quot;relay&quot;.</li>
<li><strong>&quot;id&quot;</strong> id prepended to data coming from this peer.</li>
<li><strong>&quot;status&quot;</strong> current status of peer. &quot;connect&quot; denotes peer able to receive data. &quot;wait&quot; denotes peer registered but not connected. &quot;expire&quot; denotes peer was invited but no reply was received yet.</li>
<li><strong>&quot;throughput&quot;</strong> 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.</li>
</ul>
</section3>
<section3 topic='Stream status listing'>
<p>To retrieve listing of all stream configuration/statistics values or public streams, any registered peer sends a message like so:</p>
<example>
&lt;iq
id='dsps9'
type='get'
from='rob@nauseum.org/dspsclient'
to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'&gt;
&lt;query type='stats' xmlns='jabber:iq:dsps'/&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;to&quot;</strong> if contains a resource, will return statistics for specified stream. Otherwise will return listing of public streams, i.e. any stream with &quot;maxpublic&quot; greater then 0.</li>
<li><strong>&quot;stats&quot;</strong> denotes that this is a configuration/statistics request. It may not contain a body or attributes, otherwise it will be ignored without error.</li>
</ul>
<p>The query reply is formatted like so:</p>
<example>
&lt;iq
id='dsps9'
type='result'
from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
to='rob@nauseum.org/dspsclient'&gt;
&lt;query type='stats' xmlns='jabber:iq:dsps'
init='00000000000000'
protocol='0.5'
port='5290'
minthroughput='1.5KB'
expiredefault='150'
waitdefault='100'
wait='10'
public='5'
maxpublic='25'
mastercount='20'
slavecount='40'
relaycount='0'&gt;
&lt;feature type='http' version='1.1'/&gt;
&lt;feature type='ssl' version='3.0'/&gt;
&lt;peer&gt;mydsps@jabber.org/8xd67f56df4f546fdgsfdg65f6g58f&lt;/peer&gt;
&lt;comment&gt;some server comment&lt;/comment&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&quot;from&quot;</strong> the DSPS JID/resource pair for the peer receiving the result.</li>
<li><strong>&quot;init&quot;</strong> UNIX timestamp of the date this stream was initiated.</li>
<li><strong>&quot;protocol&quot;</strong> protocol version this DSPS supports.</li>
<li><strong>&quot;port&quot;</strong> default port this DSPS listens for connections on.</li>
<li><strong>&quot;minthroughput&quot;</strong> as defined in &quot;create&quot;.</li>
<li><strong>&quot;expiredefault&quot;</strong> default time this DSPS will wait for an &quot;acknowledge&quot; response.</li>
<li><strong>&quot;waitdefault&quot;</strong> default time this DSPS will wait for a connection to its default port after an invitation is accepted.</li>
<li><strong>&quot;wait&quot;</strong> 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 &quot;create&quot; response.</li>
<li><strong>&quot;public&quot;</strong> number of &quot;slave&quot; peers registered with stream without invitation.</li>
<li><strong>&quot;maxpublic&quot;</strong> maximum number of &quot;slave&quot;peers allowed without invitation.</li>
<li><strong>&quot;mastercount&quot;</strong> number of peers with a &quot;master&quot; connection registered on this stream.</li>
<li><strong>&quot;slavecount&quot;</strong> number of peers with a &quot;slave&quot; connection registered on this stream.</li>
<li><strong>&quot;relaycount&quot;</strong> number of peers with a &quot;relay&quot; connection registered on this stream.</li>
<li><strong>&lt;feature/&gt;</strong> <em>(optional)</em> denotes a supported feature. All supported features must be listed.</li>
<li><strong>&lt;peer/&gt;</strong> <em>(optional)</em> list of public stream connections where all reported statistics match. Present only if &quot;to&quot; in original request contained no resource. Multiple allowed where statistics match for all.</li>
<li><strong>&lt;comment/&gt;</strong> <em>(optional)</em> parameter(s) with a comments from &quot;create&quot;. This block may contain full XML stack of elements. Multiple such blocks are allowed.</li>
</ul>
<p>All &quot;status&quot; 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 &quot;to&quot; in original request contained no resource, multiple &quot;stats&quot; blocks are allowed, where each contains at least one &lt;peer/&gt; block which has &quot;maxpublic&quot; greater than 0. To join a public stream a client must send message as per section &quot;Accepting an invite&quot;.</p>
</section3>
</section2>
<section2 topic='Stream shutdown'>
<p>Stream exists from its &quot;create&quot;ion time to the time when there are no more &quot;master&quot; peers registered with the stream.</p>
<p>When last &quot;master&quot; peer is dropped from the stream, DSPS will make sure that all the data sent by all the &quot;master&quot; peers was actually copied to all the &quot;slave&quot; peers still present. For every remaining &quot;slave&quot; 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.</p>
</section2>
<section2 topic='Error message format'>
<p>Error messages look like so:</p>
<example>
&lt;iq
id='dsps9'
type='error'
from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
to='rob@nauseum.org/dspsclient'&gt;
&lt;error code='405'&gt;Method Not Allowed&lt;/error&gt;
&lt;/iq&gt;
</example>
<ul>
<li><strong>&lt;error/&gt;</strong> denotes error block where body is text description.</li>
<li><strong>&quot;code&quot;</strong> denotes error code.</li>
</ul>
</section2>
</section1>
<section1 topic='Possible applications'>
<section2 topic='File transfer'>
<p>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: &lt;meta type='file' name='myfile.txt' size='500K' crc32='12345' sha1='23451' mime='application/octet-stream' timestamp='12345' date='20020412T00:00:00'/&gt;. Where the &quot;size&quot; 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 &quot;drop&quot;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.</p>
</section2>
<section2 topic='VoIP'>
<p>Same idea as the file transfer. However if more then two parties are involved, every party must have a &quot;master&quot; connection.</p>
</section2>
<section2 topic='Multicast'>
<p>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 &quot;slave&quot; 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 &quot;master&quot; connection, thus if one of them goes down, the others can take over.</p>
</section2>
<section2 topic='File Storage'>
<p>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 &quot;invite&quot;ed or &quot;invite&quot; other users onto personal streams to transfer files as described in 6.1.</p>
</section2>
</section1>
<section1 topic='Why DSPS instead of PASS'>
<p>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.</p>
<section2 topic='Ports'>
<p>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.</p>
<p>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.</p>
<p>DSPS only uses one port, and so resolves the first problem, while making the second almost a non-issue.</p>
</section2>
<section2 topic='Knowledge of IP'>
<p>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.</p>
<p>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.</p>
</section2>
<section2 topic='IP Addresses'>
<p>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.</p>
<p>DSPS never transmits IP address information across the XML stream, and so does not have this problem.</p>
</section2>
<section2 topic='Intuitiveness'>
<p>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.</p>
<p>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.</p>
</section2>
<section2 topic='Scalability'>
<p>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.</p>
<p>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.</p>
</section2>
</section1>
<section1 topic='DSPS with P2P'>
<p>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.</p>
<p>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 &quot;create&quot; message would list the serving client as the DSPS and would utilize the &quot;host&quot; attribute to tell the recipient client where to connect to the DSPS.</p>
<p>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.</p>
</section1>
</jep>

365
xep-0038.xml Normal file
View File

@ -0,0 +1,365 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Icon Styles</title>
<abstract>A protocol for specifying exchangeable styles of emoticons and genicons within Jabber IM clients.</abstract>
&LEGALNOTICE;
<number>0038</number>
<status>Deferred</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>None</dependencies>
<supersedes>None</supersedes>
<supersededby>None</supersededby>
<shortname>None</shortname>
<schemaloc>Not yet assigned</schemaloc>
<author>
<firstname>Adam</firstname>
<surname>Theo</surname>
<email>theo@theoretic.com</email>
<jid>theo@theoretic.com</jid>
</author>
<revision>
<version>0.5</version>
<date>2003-06-02</date>
<initials>at</initials>
<remark>Bent to public will on using a common object element and enveloping all meta information into a meta element.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-03-05</date>
<initials>at</initials>
<remark>Added "format" back in. Refused to simplify to use "object" for everything. Fixed some typos.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-11-05</date>
<initials>at</initials>
<remark>Simplified, even though it loses some flexibility. Should be the final version.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-07-24</date>
<initials>at</initials>
<remark>Added feedback, still needs serious Schema work</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-06-28</date>
<initials>at</initials>
<remark>Initial version</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
<p><link url="http://www.wikipedia.com/wiki/Emoticon">Emoticons</link> are the text string 'smiley' or 'frowny' faces such as <tt>:-)</tt> and <tt>:-(</tt> 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 '<link url="http://www.wikipedia.com/wiki/Ascii+Art">ASCII Art</link>') that serve to replace typing the full word or to simply be cute or creative in the conversation.</p>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Requirements'>
<p>The following issues must be solved for in this specification.</p>
<ul>
<li><b>Here and Now</b>: 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.</li>
<li><b>Meaningful</b>: 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.</li>
<li><b>Component Friendly</b>: 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.</li>
<li><b>Protect Privacy</b>: 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.</li>
<li><b>Conserve Bandwidth</b>: 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.</li>
<li><b>Be Passive</b>: 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.</li>
<li><b>Internationalization</b>: 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.</li>
</ul>
<p>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.</p>
</section1>
<section1 topic='Discovery'>
<p>To find out if an entity supports Jabber Icon Styles, look for the feature category of <tt>http://jabber.org/protocol/icon-styles</tt> using <tt>jabber:iq:browse</tt> or <tt>http://jabber.org/protocol/disco</tt>. The same feature category can be used with feature negotiation.</p>
</section1>
<section1 topic='Specification'>
<p>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).</p>
<p>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.</p>
<section2 topic="Definition File">
<p>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.</p>
</section2>
<section2 topic="Meta Elements">
<p>The meta elements contain information about the Icon Style itself, rather that the individual icons. They are contained within the <tt>&lt;meta&gt;</tt> element, which is directly under the root element. There is one and only one the <tt>&lt;meta&gt;</tt> element.</p>
<ul>
<li><b>Name</b>: This is an arbitrary text string (spaces allowed) which is the full name of the Icon Style. Only one name can be included.</li>
<li><b>Version</b>: 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 <tt>major.minor</tt> or <tt>major.minor.trivial</tt> formats are recommended. Only one version can be included.</li>
<li><b>Description</b>: 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.</li>
<li><b>Author</b>: This is the full name of the author. Multiple authors are allowed.</li>
<li><b>Creation</b>: This is the date of the creation of this version of the Icon Style. The date is in the <link url="http://www.w3.org/TR/NOTE-datetime">ISO 8601</link> standard format.</li>
<li><b>Home</b>: This is the full HTTP web address of the Icon Style's homepage. This is optional.</li>
</ul>
</section2>
<section2 topic="Text Strings">
<p>The <tt>&lt;text/&gt;</tt> element defines what text string(s) are recognized by the client as an icon. There may be multiple <tt>&lt;text/&gt;</tt> elements in an <tt>&lt;icon/&gt;</tt>, such as for different languages or simply for multiple text strings producing the same result (for example: <tt>:-)</tt> and <tt>:)</tt>)</p>
<section3 topic="Internationalization">
<p>Each may have an <tt>xml:lang</tt> attribute, as defined in Section 2.12 in the official <link url="http://www.w3.org/TR/REC-xml#sec-lang-tag">XML 1.0 reference document</link>. The <tt>xml:lang</tt> attribute allows for two-letter language codes, dialects, and custom "languages" to define foreign IM protocols, for example.</p>
</section3>
<section3 topic="Whitespace">
<p>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.</p>
</section3>
<section3 topic="Case Sensitivity">
<p>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 <tt>&lt;text/&gt;</tt> elements, although they may of course use the same objects.</p>
</section3>
</section2>
<section2 topic="Objects">
<p>The <tt>&lt;object/&gt;</tt> element defines what multimedia objects are inserted into the displayed message, replacing the text string(s) defined in <tt>&lt;text/&gt;</tt>. 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 <tt>&lt;object/&gt;</tt> element is identical to <link url="http://www.w3.org/TR/2003/WD-xhtml2-20030131/mod-object.html#s_objectmodule">the OBJECT element used in XHTML 2.0</link>, and the specification used there should be used to govern the <tt>&lt;object/&gt;</tt> 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 <tt>&lt;object/&gt;</tt> elements in an <tt>&lt;icon/&gt;</tt>, such as for alternative file formats (such as <tt>
GIF</tt> vs. <tt>PNG</tt>), or multiple objects to use at the same time (such as graphic and sound files).</p>
</section2>
<section2 topic="X Tags">
<p>The <tt>&lt;x/&gt;</tt> element allows any type of extensions to the <tt>icondef.xml</tt> 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 <tt>xmlns</tt> attribute with a namespace that the extension operates under. Multiple <tt>&lt;x/&gt;</tt> elements may be in the <tt>&lt;icon/&gt;</tt> or <tt>&lt;icondef/&gt;</tt> elements. This functionality is optional for clients to support, and clients should ignore all extensions they do not understand.</p>
</section2>
<section2 topic="Hierarchy">
<p>The <tt>icondef.xml</tt> file must all be located in the root directory, which is named after the style and version (example: <tt>./happy_days-1.2</tt> or <tt>./gold_angelic-1.0.0</tt>). 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 <tt>&lt;object/&gt;</tt> element in the <tt>icondef.xml</tt> file.</p>
<example caption="Gold Angelic v1.0.0 Hierarchy Example">
./gold_angelic-1.0.0
./gold_angelic-1.0.0/icondef.xml
./gold_angelic-1.0.0/alert.ogg
./gold_angelic-1.0.0/red-exclamation-mark.svg
./gold_angelic-1.0.0/shocked.svg
./gold_angelic-1.0.0/woman.svg
./gold_angelic-1.0.0/pngs/happy.png
./gold_angelic-1.0.0/pngs/sad.png
./gold_angelic-1.0.0/pngs/man.png
./gold_angelic-1.0.0/pngs/woman.png
./gold_angelic-1.0.0/wavs/boohoo.wav
./gold_angelic-1.0.0/wavs/choir.wav
./gold_angelic-1.0.0/wavs/alert.wav
</example>
</section2>
<section2 topic="Packaging">
<p>The <tt>icondef.xml</tt> file and all object files must be packaged in the <tt>ZIP</tt> format following the above hierarchy (the directory must exist in the package, with all files in it). The package must have the file extension <tt>.jisp</tt> (Jabber Icon Style Package), and the MIME type <tt>application/vnd.jisp</tt> as defined in the official <link url="http://www.iana.org/assignments/media-types/application/vnd.jisp">IANA registration</link>. 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.</p>
</section2>
</section1>
<section1 topic='Implementation Notes'>
<p>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.</p>
<section2 topic='Procedure'>
<p>The procedure for using Jabber icons is simple and straightforward.</p>
<ol>
<li>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.</li>
<li>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).</li>
<li>The client translates the selected icon into its main text string equivelent, which is found in the icon's <tt>&lt;text&gt;</tt> element. If there are multiple <tt>&lt;text&gt;</tt> elements, follow the procedure under "Text Strings", below.</li>
<li>The client sends the message with the text string to the intended recipient.</li>
<li>The recipient client receives the message with the text string.</li>
<li>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.</li>
</ol>
</section2>
<section2 topic='Text Strings'>
<p>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:</p>
<ol>
<li>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 <tt>xml:lang</tt> attribute for <tt>&lt;text/&gt;</tt> elements.</li>
<li>If there are no text strings that match the user's language, then look for one that has no defined language.</li>
<li>If there are multiple options even after the above steps, select the one that comes first in the <tt>&lt;icon/&gt;</tt> element.</li>
<li>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 <tt>&lt;icon/&gt;</tt> element.</li>
</ol>
</section2>
<section2 topic='Objects'>
<p>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).</p>
<ol>
<li>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 <tt>image/bmp</tt> and maybe <tt>audio/x-wav</tt>, but some newer clients may be able to support <tt>image/png</tt>, <tt>image/svg+xml</tt> and <tt>audio/x-ogg</tt>.</li>
<li>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.</li>
<li>If there are still multiple objects of the same MIME type, then the client should choose the first one in order in the <tt>&lt;icon/&gt;</tt> element.</li>
<li>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.</li>
</ol>
<p>The <link url="http://www.w3.org/TR/2003/WD-xhtml2-20030131/mod-object.html#sec_14.1.3.">Rules for processing objects</link> 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.</p>
<p>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.</p>
<p>Also, if you are developing an icon style, please make sure the MIME types specified in your <tt>icondef.xml</tt> 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 <tt>BMP</tt>, <tt>PNG</tt>, <tt>SVG</tt>, <tt>WAV</tt>, <tt>OGG</tt> formats because they are open, free, and becoming increasingly supported in developer tools and programming languages.</p>
</section2>
<section2 topic='Combining Styles'>
<p>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.</p>
</section2>
<section2 topic='Core Icons'>
<p>Although any text string can be turned into an icon by defining it in an <tt>icondef.xml</tt> 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:</p>
<ul>
<li><b>:-)</b> and <b>:)</b> - A smiling face.</li>
<li><b>:-(</b> and <b>:(</b> - A frowing face.</li>
<li><b>;-)</b> and <b>;)</b> - A winking smiling face.</li>
<li><b>:'-(</b> and <b>:'(</b> - A crying face.</li>
<li><b>>:-(</b> and <b>>:(</b> - An angry face.</li>
<li><b>:yes:</b> - A thumbs-up or checkmark.</li>
<li><b>:no:</b> - A thumbs-down or a crossmark.</li>
<li><b>:wait:</b> - An open hand, palm outstretched.</li>
<li><b>@->--</b> and <b>:rose:</b> - A rose flower.</li>
<li><b>:telephone:</b> - A telephone.</li>
<li><b>:email:</b> - An electronic-looking envelope.</li>
<li><b>:jabber:</b> - Jabber's lightbulb logo.</li>
<li><b>:cake:</b> - A birthday cake.</li>
<li><b>:kiss:</b> - A pair of puckered lips.</li>
<li><b>:heart:</b> and <b>:love:</b> - A heart.</li>
<li><b>:brokenheart:</b> - A broken heart.</li>
<li><b>:music:</b> - A musical note or instrument.</li>
<li><b>:beer:</b> - A beer mug.</li>
<li><b>:coffee:</b> - A cup of coffee.</li>
<li><b>:money:</b> - A gold coin.</li>
<li><b>:moon:</b> - A moon.</li>
<li><b>:sun:</b> - A sun.</li>
<li><b>:star:</b> - A star.</li>
</ul>
</section2>
</section1>
<section1 topic='Security Considerations'>
<p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>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 <tt>application/vnd.jisp</tt> and <tt>.jisp</tt>, respectively. The registration can be found at <link url="http://www.iana.org/assignments/media-types/application/vnd.jisp">http://www.iana.org/assignments/media-types/application/vnd.jisp</link>. Sebastiaan's registration shall be considered the official MIME type and file extension of this specification.</p>
<p>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.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<p>JANA shall register the namespace <tt>http://jabber.org/protocol/icon-styles</tt> as an official feature category.</p>
<p>Also, JANA may choose to define IM-specific <tt>xml:lang</tt> "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.</p>
</section1>
<section1 topic='Formal Definition'>
<section2 topic='Schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="icondef">
<xs:complexType>
<xs:sequence>
<xs:complexType>
<xs:sequence>
<xs:element name="name" type="xs:string"/>
<xs:element name="version" type="xs:string"/>
<xs:element name="description" type="xs:string"/>
<xs:element name="author" type="xs:string" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="jid" type="xs:string" use="optional"/>
</xs:complexType>
</xs:element>
<xs:element name="creation" type="xs:date"/>
</xs:sequence>
</xs:complexType>
<xs:element name="icon" minOccurs="1" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="text" type="xs:string" minOccurs="1" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="xml:lang" type="xs:language" use="optional"/>
</xs:complexType>
</xs:element>
<xs:element name="object" type="xs:string" minOccurs="1" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="mime" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="x" type="xs:string" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="xmlns" type="xs:anyURI" use="required"/>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="x" type="xs:string" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="xmlns" type="xs:anyURI" use="required"/>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section2>
<section2 topic="icondef.xml file example">
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<icondef>
<meta>
<name>Gold Angelic</name>
<version>1.0.0</version>
<description>Angelic faces and themes with gold highlights.</description>
<author jid="theo@theoretic.com">Adam Theo</author>
<author jid="cbas@rhymbox.com">Sebastiaan Deckers</author>
<author jid="cobnet@jabber.org">Mattias Campe</author>
<creation>2002-10-31</creation>
<home>http://icon-styles.jabberstudio.org/Gold_Angelic</home>
</meta>
<icon>
<text>:-)</text>
<text>:)</text>
<object mime="image/png">happy.png</object>
<object mime="audio/x-wav">choir.wav</object>
</icon>
<icon>
<text>:-(</text>
<text>:(</text>
<object mime="image/png">sad.png</object>
<object mime="audio/x-wav">boohoo.wav</object>
</icon>
<icon>
<text>:-O</text>
<text>:O</text>
<object mime="image/svg+xml">shocked.svg</object>
</icon>
<icon>
<text xml:lang="en">::man::</text>
<text xml:lang="de">::mann::</text>
<text xml:lang="cs">::muz::</text>
<text xml:lang="x-msn">(z)</text>
<object mime="image/png">man.png</object>
</icon>
<icon>
<text xml:lang="en">::woman::</text>
<text xml:lang="x-msn">(x)</text>
<object mime="image/svg+xml">woman.svg</object>
<object mime="image/png">woman.png</object>
</icon>
<icon>
<text xml:lang="en">::alert::</text>
<object mime="image/svg+xml">red-exclamation-mark.svg</object>
<object mime="audio/x-ogg">alert.ogg</object>
<object mime="audio/x-wav">alert.wav</object>
</icon>
</icondef>
]]></code>
</section2>
</section1>
<section1 topic='Future Considerations'>
<ol>
<li>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.</li>
<li>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.</li>
<li>The functionality of the <tt>icondef.xml</tt> 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.</li>
<li>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.</li>
<li>A "SVG Transport" may be created to enable clients to send <tt>SVG</tt> icons to it and get back icons in another format of their choice, such as <tt>PNG</tt> or <tt>JPG</tt>. This would speed up the adoption of <tt>SVG</tt> within Jabber greatly.</li>
<li>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 <link url="http://www.jabberstudio.org">JabberStudio</link> or even the <link url="http://www.theoretic.com/Ransom">Ransom model</link>.</li>
</ol>
</section1>
</jep>

426
xep-0039.xml Normal file
View File

@ -0,0 +1,426 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Statistics Gathering</title>
<abstract>A protocol to enable gathering statistics from Jabber servers and components.</abstract>
&LEGALNOTICE;
<number>0039</number>
<status>Deferred</status>
<type>Standards Track</type>
<jig>Standards</jig>
<author>
<firstname>Paul</firstname>
<surname>Curtis</surname>
<email>pcurtis@terrapin.com</email>
<jid>pcurtis@www.terrapin.com</jid>
</author>
<author>
<firstname>Russell</firstname>
<surname>Davis</surname>
<email>ukscone@burninghorse.com</email>
<jid>ukscone@burninghorse.com</jid>
</author>
<author>
<firstname>Ryan</firstname>
<surname>Eatmon</surname>
<email>reatmon@jabber.org</email>
<jid>reatmon@jabber.org</jid>
</author>
<author>
<firstname>David</firstname>
<surname>Sutton</surname>
<email>dsutton@legend.co.uk</email>
<jid>peregrine@legend.net.uk</jid>
</author>
<revision>
<version>0.6.0</version>
<date>2002-11-05</date>
<initials>rkd</initials>
<remark>Corrected David Sutton's JID and email. It has been pointed out
to me by amoungst others Rob Norris that things such as lists of JIDs
and lists in general are really the province of disco and browse and
that at least one of the suggested 'core' statistics doesn't
make sense for all components so removed these from the JEP. This namespace
was starting to become a generic data gathering namespace and we already
have one of those, so i've reworked yet again hopefully for the
final time it should now be simpler to implement and more consistent in
all cases.</remark>
</revision>
<revision>
<version>0.5.0</version>
<date>2002-11-03</date>
<initials>rkd</initials>
<remark>Heavily modified JEP according to suggestions from Matt Miller (linuxwolf). rkd had some additional thoughts on the name attribute, this version reflects those. Reorganized the description section.</remark>
</revision>
<revision>
<version>0.4.2</version>
<date>2002-10-25</date>
<initials>rkd</initials>
<remark>Changed rkd's email address and jid. Modified namespace to use http uri.</remark>
</revision>
<revision>
<version>0.4.1</version>
<date>2002-08-20</date>
<initials>rkd</initials>
<remark>Corrected error codes</remark>
</revision>
<revision>
<version>0.4</version>
<date>2002-08-18</date>
<initials>rkd</initials>
<remark>Fixed two silly typos that crept back in. Rewrote SNMP
to read better. Added the DTD</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-08-16</date>
<initials>rkd</initials>
<remark>Added &lt;display/&gt; so a server or component may
optionally return data in a human readable format. It is nothing
more than a bit of visual fluff but it has potential to be quite
useful. Renumbered the revisions to allow room for stpeter's new
JEP numbering scheme, sorry if it is now confusing but I hadn't
left much room to grow with the previous revision numbering. A
little more prettying and judicious use of punctuation has occurred.</remark>
</revision>
<revision>
<version>0.2.2</version>
<date>2002-08-15</date>
<initials>rkd</initials>
<remark>Fixed some typos and generally prettied up</remark>
</revision>
<revision>
<version>0.2.1</version>
<date>2002-08-14</date>
<initials>rkd</initials>
<remark>I seem to have misunderstood one of Ryan Eatmon's
suggestions and didn't make this generic enough. I have
fixed that now. Clarified error codes and reworked how errors
are indicated to work with the new generic
namespace. Rearranged the order of the sections a bit make this
JEP a more linear read.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-08-13</date>
<initials>rkd</initials>
<remark>Complete reworking to take into account suggestions made
by Ryan Eatmon and others. Ryan Eatmon added to list of authors to
reflect his significant contribution to the current form of this
JEP. I have also received a few comments that this document
previously read like an IETF document. Whether that was a good or
bad thing I was unable to ascertain but I've tried to lighten the
tone a little.</remark>
</revision>
<revision>
<version>0.1.5</version>
<date>2002-07-23</date>
<initials>rkd</initials>
<remark>Changed data returned by &lt;who/&gt; as per comments by
psa</remark>
</revision>
<revision>
<version>0.1.4</version>
<date>2002-07-23</date>
<initials>rkd</initials>
<remark>Converted to XML as per JEP spec in preparation for
submission as experimental JEP.</remark>
</revision>
<revision>
<version>0.1.3</version>
<date>2002-07-23</date>
<initials>rkd</initials>
<remark>A numeric values unit type is now returned using an attribute
"units" rather than specifying that it be returned in the smallest
sensible unit type to produce an unsigned integer.</remark>
</revision>
<revision>
<version>0.1.2</version>
<date>2002-07-23</date>
<initials>rkd</initials>
<remark>Justify inclusion of the 501 (Not Implemented) error code
as per comments by Zion</remark>
</revision>
<revision>
<version>0.1.1</version>
<date>2002-07-22</date>
<initials>rkd</initials>
<remark>Fixed some typos</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-07-21</date>
<initials>rkd</initials>
<remark>Initial version.</remark>
</revision>
<dependencies>JEP-0053 (JANA)</dependencies>
</header>
<section1 topic='Introduction'>
<p>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 <strong>number</strong> 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.</p>
</section1>
<section1 topic='Description'>
<section2 topic='Namespace'>
<p>This is a pretty simple namespace. It consists of a &lt;stat/&gt; tag with
three attributes. name, units and value.</p>
<code>
&lt;query xmlns='http://jabber.org/protocol/stats'&gt;
&lt;stat name='' units='' value=''/&gt;
&lt;/query&gt;
</code>
<p> 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.</p>
<code>
&lt;query xmlns='http://jabber.org/protocol/stats'&gt;
&lt;stat name=''&gt;&lt;error code=''&gt;...&lt;/error&gt;&lt;/stat&gt;
&lt;/query&gt;
</code>
</section2>
<section2 topic='Name Attribute'>
<p>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<note>See Name Registration</note>.</p>
</section2>
<section2 topic='Units Attribute'>
<p>This is the units type of the statistic. As with the name attribute it
will be assigned and administered by JANA<note>See Name
Registration</note>It is suggested that JANA use where appropriate
commonly accepted international standards when assigning unit types
i.e. seconds, grams, meters, bytes etc.</p>
</section2>
<section2 topic='Value Attribute'>
<p>This is the actual returned value of the queried statistic. The value returned is in
multiples of the unit described by the units attribute.</p>
</section2>
<section2 topic="Query">
<p>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 <em>list</em> of statistics that it supports.</p>
<example>
send: &lt;iq type='get' to='component'&gt;
&lt;query xmlns='http://jabber.org/protocol/stats'/&gt;
&lt;/iq&gt;
recv: &lt;iq type='result' from='component'&gt;
&lt;query xmlns='http://jabber.org/protocol/stats'&gt;
&lt;stat name='time/uptime'/&gt;
&lt;stat name='users/online'/&gt;
.
.
.
&lt;stat name='bandwidth/packets-in'/&gt;
&lt;stat name='bandwidth/packets-out'/&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<p>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.</p>
<example>
send: &lt;iq type='get' to='component'&gt;
&lt;query xmlns='http://jabber.org/protocol/stats'&gt;
&lt;stat name='time/uptime'/&gt;
&lt;stat name='users/online'/&gt;
&lt;stat name='bandwidth/packets-in'/&gt;
&lt;stat name='bandwidth/packets-out'/&gt;
&lt;/query&gt;
&lt;/iq&gt;
recv: &lt;iq type='result' from='component'&gt;
&lt;query xmlns='http://jabber.org/protocol/stats'&gt;
&lt;stat name='time/uptime' units='seconds' value='3054635'/&gt;
&lt;stat name='users/online' units='users' value='365'/&gt;
&lt;stat name='bandwidth/packets-in' units='packets' value='23434'/&gt;
&lt;stat name='bandwidth/packets-out' units='packets' value='23422'/&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
</section2>
<section2 topic='Errors'>
<p>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.</p>
<table caption='Error Codes'>
<tr><th>Code</th><th>String</th><th>Reason</th></tr>
<tr><td>401</td><td>Unauthorized</td><td>Querying JID is not
authorized to perform that query</td></tr>
<tr><td>404</td><td>Not Found</td><td>The statistic was not
found for some reason</td></tr>
<tr><td>501</td><td>Not Implemented</td><td>Although statistic
is advertised as available it has not been implemented</td></tr>
<tr><td>503</td><td>Service Unavailable</td><td>Statistic is
temporarily unavailable</td></tr>
</table>
<p>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
<strong>all</strong> the statistics meaningless being indicated
with a type='error' in the returned packet.</p>
<example>
&lt;iq type='error' from='component'&gt;
&lt;query xmlns='http://jabber.org/protocol/stats'&gt;
&lt;error code='401'&gt;Not Authorized&lt;/error&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<p>Errors in a query that only invalidate one or more of the
requested statistics are indicated with an &lt;/error&gt; tag
embedded inside the &lt;/stat&gt; tag.
</p>
<example>
&lt;iq type='result' from='component'&gt;
&lt;query xmlns='http://jabber.org/protocol/stats'&gt;
&lt;stat name='time/uptime units='seconds' value='4534'/&gt;
&lt;stat name='bandwidth/packets-in'&gt;&lt;error code='503'&gt;Service Unavailable&lt;/error&gt;&lt;/stat&gt;
&lt;stat name='bandwidth/packets-out'&gt;&lt;error code='503'&gt;Service Unavailable&lt;/error&gt;&lt;/stat&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
</section2>
</section1>
<section1 topic='Implementation'>
<section2 topic='Name Registration'>
<p>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 <em><strong>stat</strong></em>.
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.
</p>
<table caption='how to document your statistic'>
<tr>
<th>Stat</th><th>Description</th><th>Returned Units</th>
</tr>
<tr>
<td>registered name</td><td>description of
statistic/reason</td><td>unit type returned by
query</td>
</tr>
</table>
</section2>
<section2 topic='Core Statistics'>
<p>
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.</p>
<ul>
<li>&lt;stat name='time/uptime'/&gt;</li>
<li>&lt;stat name='bandwidth/packets-in'/&gt;</li>
<li>&lt;stat name='bandwidth/packets-out'/&gt;</li>
</ul>
<table caption='core statistic registration information'>
<tr>
<th>Stat</th><th>Description</th><th>Returned Units</th>
</tr>
<tr>
<td>time/uptime</td><td>uptime of component or
server</td><td>Seconds</td>
</tr>
<tr>
<td>bandwidth/packets-in</td><td>packets received by component or server</td><td>packets</td>
</tr>
<tr>
<td>bandwidth/packets-out</td><td>packets transmitted by component or server</td><td>packets</td>
</tr>
</table>
</section2>
<section2 topic='Human readable labels'>
<p>For several reasons the
<strong>http://jabber.org/protocol/stats</strong> 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.</p>
</section2>
<section2 topic='Namespace query authorization'>
<p>In most cases the <strong>http://jabber.org/protocol/stats</strong> 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 <strong>http://jabber.org/protocol/stats</strong>
namespace is configured to use the three tier method of
authorizing queries.</p>
</section2>
<section2 topic='SNMP'>
<p>Supporting industry accepted standards and procedures
<note>For more details on <link url='http://www.snmplink.org'>SNMP</link>
and <link url='http://www.dmtf.org'>CIM</link></note> within
the Jabber protocol is highly desirable as long as it does not
restrict the flexibility or functionality of Jabber. So while
the <strong>http://jabber.org/protocol/stats</strong> namespace seems to fall within the domain of
the SNMP and CIM standards amongst others and large jabber
installations would find direct support an appealing prospect
when tying jabber into their existing network information and
management systems the jabber:iq:namespace will not do this.
Because Jabber is an XML based protocol, conversion of
the returned data to other formats including those required
for SNMP, CIM etc. should be relatively simple. Not supporting
industry standards is not without advantages. By leaving the
<strong>http://jabber.org/protocol/stats</strong> as a <em>pure</em> jabber namespace we allow
ourselves to obtain not only commonly used statistics but also
some unusual ones as well. For example imagine a jabber enabled
vending machine, by remaining free of the encumberence and
limitations of SNMP etc. we can directly (if allowed by the
controlling component) query the fluid ounces dispensed, most
popular beverage and the amount of money that has been collected.
Finally although it is unlikely to occur by staying true to our
roots and avoiding direct SNMP support we avoid any possibility
of conflict with other network management agents such as net(ucd)-snmp.
</p>
</section2>
</section1>
<section1 topic='Realworld Examples'>
TBD
</section1>
<section1 topic='DTD'>
<section2 topic='DTD in English'>
TBD
</section2>
<section2 topic='DTD'>
TBD
</section2>
</section1>
</jep>

270
xep-0040.xml Normal file
View File

@ -0,0 +1,270 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type="text/xsl" href="../jep.xsl"?>
<jep>
<header>
<title>Jabber Robust Publish-Subscribe</title>
<abstract>Note: This proposal has been superseded by JEP-0060; please refer to that document for the successor protocol.</abstract>
&LEGALNOTICE;
<number>0040</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards</jig>
<dependencies>None</dependencies>
<supersedes>None</supersedes>
<supersededby>JEP-0060</supersededby>
<shortname>None</shortname>
<author>
<firstname>Tim</firstname>
<surname>Carpenter</surname>
<email>tim.carpenter@in8limited.co.uk</email>
<jid></jid>
</author>
<revision>
<version>0.2</version>
<date>2004-07-26</date>
<initials>psa</initials>
<remark>Formally retracted this proposal in favor of JEP-0060: Publish-Subscribe.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-08-02</date>
<initials>tc</initials>
<remark>Initial Release For Comment</remark>
</revision>
</header>
<section1 topic="Introduction">
<p><em>Note: This JEP has been superseded by &jep0060;; please refer to that document for the successor protocol.</em></p>
<p>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).</p>
<p>Implementation issues in the environment are appended, covering Permissioning and Contributions. Both are likely to require separate JEPs, but need to be constructed sympathetically.</p>
<p>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.</p>
<section2 topic="Background">
<p>Publish-Subscribe and other messaging environments that exist are often classified as providing one or more of the following three levels of service.</p>
<ol>
<li>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.</li>
<li>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.</li>
<li>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.</li>
</ol>
<p>This document concerns itself with level 2 Publish Subscribe -- "Robust".</p>
</section2>
<section2 topic="Positioning">
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<ol>
<li>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.)</li>
<li>Discuss other projects or protocols and how Jabber could interface with them because of your proposed protocol enhancement (e.g., XML-RPC, SOAP, DotGNU).</li>
<li>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.</li>
<li>Review the relevant history of thinking within the Jabber community.</li>
</ol>
<p>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 &lt;publish&gt; tag, being a means to identify data much as the namespace or topic does.</p>
<p>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.</p>
<p>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.</p>
</section2>
</section1>
<section1 topic="Gap Detection And Repair">
<p>This can be achieved by the use of packet sequence numbering and heartbeats whilst avoiding the necessity to positively ACK each packet.</p>
<section2 topic="Sequence Numbering">
<p>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.</p>
<p>Sequence numbers will be sent in each publish thus:</p>
<example>
&lt;iq type="set"
to="myclient@server.net"
from="pubsub.localhost"&gt;
&lt;query xmlns="jabber:iq:pubsub"&gt;
&lt;publish ns="data topics"
linkseq="57372"
sourceseq="7547392"
from="publisher.fromaplace"&gt;
&lt;/publish&gt;
&lt;publish ns="data topics"
linkseq="57373"
sourceseq="44211"
from="publisher.elsewhere"&gt;
&lt;/publish&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<p>The above shows sequence numbers placed in the &lt;publish/&gt; 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.</p>
<p>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.</p>
<p>The operation of LINK and SOURCE sequence numbers are described below.</p>
</section2>
<section2 topic="Link Level Swquence Numbering">
<p>This will concern itself with data sent on each channel. A
channel can be, but is not limited to the following:</p>
<ul>
<li>Socket connection between Subscriber (and/or resource within same) and the Jabber pubsub component.</li>
<li>Multicast datastream sent from a pubsub component but shared amongst 0..n subscribers.</li>
</ul>
<p>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 &lt;iq/&gt; before subscription requests are levied.</p>
<p>E.g., in a 16-bit sequence number resolution channel, the sequence numbers would run as follows</p>
<p>1, 2, 3, 65533, 65534, 65535, 1, 2,</p>
<p>For information on sequence number bit resolution, see section 4, Source Queries.</p>
</section2>
<section2 topic="Source Level Sequence Numbering">
<p>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.</p>
<p>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.</p>
<p>The subscriber need not know how the source sequencing operates, only notify from when the link last gave a contiguous datastream.</p>
<p>One can now see that the pubsub component's conversation to the source is akin to that of a subscriber to a pubsub component.</p>
</section2>
<section2 topic="Gap Filling">
<p>When a subscriber detects a gap on its link, it can request for the data to be resent thus:</p>
<example>
&lt;iq
type="get"
id="plugthegap1"
from="myclient@server.net"
to="pubsub.localhost"&gt;
&lt;query xmlns="jabber:iq:pubsub"&gt;
&lt;gap linkfrom="56737" linkto="56739"&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<p>The values represent the missed link sequence numbers. For a gap of 1, the linkfrom and linkto are the same.</p>
<p>Should the pubsub have lost the link context and thus is unable to plug the gaps it will return an error &lt;iq/&gt; packet.</p>
<p>All is not lost. The subscriber has a last-ditch repair scenario by sending last-received source sequence numbers. </p>
<example>
&lt;iq
type="get"
id="plugthegap1"
from="myclient@server.net"
to="pubsub.localhost"&gt;
&lt;query xmlns="jabber:iq:pubsub"&gt;
&lt;gap ns="publisher.fromaplace" after="56737"&gt;
&lt;gap ns="publisher.elsewhere" after="211234"&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<p>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.</p>
<p>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:</p>
<example>
&lt;iq
type="set"
to="myclient@server.net"
from="pubsub.localhost"&gt;
&lt;query xmlns="jabber:iq:pubsub"&gt;
&lt;publish
ns="data topics"
linkseq="0"
sourceseq="7547392"
from="publisher.fromaplace"&gt;
&lt;/publish&gt;
&lt;publish
ns="data topics"
linkseq="1"
sourceseq="44211"
from="publisher.elsewhere"&gt;
&lt;/publish&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
</section2>
<section2 topic="Heartbeats">
<p>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.</p>
<example>
&lt;iq
type="set"
to="myclient@server.net"
from="pubsub.localhost"&gt;
&lt;query xmlns="jabber:iq:pubsub"&gt;
&lt;publish
ns="link.heartbeat"
linkseq="57374"
from="pubsub.localhost"&gt;
&lt;/publish&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<p>No source sequence numbering exists here, as it is purely a link-level entity.</p>
</section2>
</section1>
<section1 topic="Publish Types">
<p>To be able to interpret published data in a more logical manner, more meaning needs to be given to data received.</p>
<p>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?</p>
<p>To resolve this a type field may be added to the &lt;publish/&gt; tag.</p>
<example>
&lt;iq
type="set"
to="myclient@server.net"
from="pubsub.localhost"&gt;
&lt;query xmlns="jabber:iq:pubsub"&gt;
&lt;publish
ns="data topics"
linkseq="57372"
sourceseq="7547392"
from="publisher.fromaplace"
type="update"&gt;
&lt;/publish&gt;
&lt;publish
ns="data topics"
linkseq="57373"
sourceseq="44211"
from="publisher.elsewhere"
type="correction"&gt;
&lt;/publish&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<p>This option is preferable to extending the &lt;iq/&gt; type field as there will then be no need to split &lt;iq/&gt; packets if &lt;publish/&gt; elements have different types.</p>
<section2 topic="Publish Type Field Values">
<p>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.</p>
<p>'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.</p>
<p>'correction' - previous data for contained fields was incorrect - e.g. paragraph in a news story, but, as per update, unsent items are still valid.</p>
<p>'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. </p>
<p>'drop' - namespace/topic item is now dead and all data in it should be deleted and purged from cache.</p>
<p>'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.</p>
<p>'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?)</p>
<p>The above states (except "add") are very important for downstream caches and for applications that apply business logic to the datastreams.</p>
</section2>
</section1>
<section1 topic="Source Queries">
<p>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:</p>
<ul>
<li>Heartbeat. Integer milliseconds. Represents the interval between heartbeat messages. Useful for rapid detection of link level problems.</li>
<li>Link Sequence Resolution. Integer. Allows subscriber to predict link sequence number rollover. Zero would indicate that it is not supported.</li>
<li>Source Sequence Resolution. Integer. Allows a subscriber to predict source sequence number rollover. A zero would indicate that it is not supported.</li>
<li>Gap Support. Boolean. Used to indicate if the publisher supports gap filling.</li>
<li>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.</li>
<li>Rebuild On Demand. If the pubsub can support a rebuild/refresh of the current values of all subscribed-to data on demand.</li>
<li>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.</li>
</ul>
</section1>
<section1 topic="Implementation Issues">
<section2 topic="Permissioning Requirements">
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<example>
&lt;iq
type="set"
to="myclient@server.net"
from="pubsub.localhost"&gt;
&lt;query xmlns="jabber:iq:pubsub"&gt;
&lt;publish
ns="data topics"
type="update"
permtoken="6747"
linkseq="57372"
sourceseq="7547392"
from="publisher.fromaplace"&gt;
&lt;/publish&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<p>This does not prevent namespace/topic permissioning systems from being applied, nor should the permtoken be compulsory1.</p>
<p>The pubsub systems should be able to &lt;iq/&gt; the publisher for the permissioning regime that applies.</p>
<p>The definition of the XML carrying permissioning tables/information should be regime specific.</p>
<p>Further information on why tokenised grant and deny permissioning is advantageous can be provided upon request.</p></section2>
<section2 topic="Contributions">
<p>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.</p>
<p>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!)</p>
</section2>
</section1>
</jep>

266
xep-0041.xml Normal file
View File

@ -0,0 +1,266 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Reliable Entity Link</title>
<abstract>Protocol for linking a bytestream between two Jabber entities.</abstract>
&LEGALNOTICE;
<number>0041</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>XMPP Core, JEP-0020, JEP-0030</dependencies>
<supersedes>None</supersedes>
<supersededby>JEP-0065</supersededby>
<shortname>rel</shortname>
<author>
<firstname>Justin</firstname>
<surname>Karneges</surname>
<email>justin@affinix.com</email>
<jid>justin@andbit.net</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-09-30</date>
<initials>psa</initials>
<remark>At the request of the author, the status of this JEP has been changed to Retracted since it has been superseded by JEP-0065. This JEP will not be considered further by the Jabber Software Foundation and should not be used as a basis for implementations.</remark>
</revision>
<revision>
<version>0.8</version>
<date>2003-06-26</date>
<initials>jk</initials>
<remark>Refactored to old jidlink roots</remark>
</revision>
<revision>
<version>0.7</version>
<date>2003-04-29</date>
<initials>jk</initials>
<remark>Overhaul and rename</remark>
</revision>
<revision>
<version>0.6</version>
<date>2002-11-23</date>
<initials>jk</initials>
<remark>Reflect changes to DTCP</remark>
</revision>
<revision>
<version>0.5</version>
<date>2002-10-10</date>
<initials>jk</initials>
<remark>Table of stream transports</remark>
</revision>
<revision>
<version>0.4</version>
<date>2002-10-10</date>
<initials>jk</initials>
<remark>New name, cleaned up the text, added test mode.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-09-12</date>
<initials>jk</initials>
<remark>Changed the implementation.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-08-16</date>
<initials>jk</initials>
<remark>Fixed spelling errors, simplified the document.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-08-15</date>
<initials>jk</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Overview'>
<section2 topic='Introduction'>
<p>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.</p>
</section2>
<section2 topic='Stream transport properties'>
<p>A REL-compatible stream transport must have the following properties:</p>
<ul>
<li>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.</li>
<li>Has a the following link states:
<table caption='Link states'>
<tr>
<th>Code</th>
<th>Description</th>
</tr>
<tr>
<td><tt>INIT</tt></td>
<td>Initiation</td>
</tr>
<tr>
<td><tt>GOOD</tt></td>
<td>Successful initiation (connected)</td>
</tr>
<tr>
<td><tt>BAD</tt></td>
<td>Unsuccessful initiation (stream is closed, no further state)</td>
</tr>
<tr>
<td><tt>CLOS</tt></td>
<td>Successful closure after establishment (stream is closed, no further state)</td>
</tr>
<tr>
<td><tt>ERR</tt></td>
<td>Link failure after establishment (stream is closed, no further state)</td>
</tr>
</table>
</li>
<li>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.</li>
</ul>
<p>The following stream transports that meet these guidelines are:</p>
<table caption='Supported streams'>
<tr>
<th>Short name</th>
<th>Protocol</th>
</tr>
<tr>
<td>ibb</td>
<td>&jep0047;</td>
</tr>
<tr>
<td>s5b</td>
<td>&jep0065;</td>
</tr>
</table>
</section2>
</section1>
<section1 topic='Usage'>
<section2 topic='Service discovery'>
<p>Before using REL, ensure it is a supported service of the remote entity by using &jep0030;:</p>
<example caption='Requesting disco information'><![CDATA[
<iq type="get" to="joe@blow.com/Home" id="sd_1">
<query xmlns="http://jabber.org/protocol/disco#info"/>
</iq>
]]></example>
The remote entity will advertise the "http://jabber.org/protocol/rel" namespace as a feature to represent they implement this JEP.
<example caption='Response'><![CDATA[
<iq type="result" from="joe@blow.com/Home" id="sd_1">
<query xmlns="http://jabber.org/protocol/disco#info">
<feature var="http://jabber.org/protocol/rel"/>
</query>
</iq>
]]></example>
</section2>
<section2 topic='Obtaining a REL context'>
<p>To use REL, the entities must obtain a REL Context ID (or <em>cid</em>) through some action. A <em>cid</em> is simply an opaque alphanumeric string. For example, perhaps the link is needed for a file transfer:</p>
<example caption='Possible File Transfer'><![CDATA[
<iq type="set" id="ft_1" to="joe@blow.com/Home">
<query xmlns="filexfer" filename="coolfile.txt"/>
</iq>
]]></example>
<example caption='Possible response'><![CDATA[
<iq type="result" id="ft_1" from="joe@blow.com/Home">
<query xmlns="filexfer">
<cid xmlns="http://jabber.org/protocol/rel" value="myCID"/>
</query>
</iq>
]]></example>
<p>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.</p>
</section2>
<section2 topic='Selecting a Stream'>
<p>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.</p>
<example caption='Selecting a stream'><![CDATA[
<iq type="get" id="rel_1" to="joe@blow.com/Home">
<query xmlns="http://jabber.org/protocol/rel" cid="myCID" keepAlive='true'>
<feature xmlns="http://jabber.org/protocol/feature-neg">
<x xmlns="jabber:x:data">
<field var="method" type="list-single">
<option><value>s5b</value></option>
<option><value>ibb</value></option>
</field>
</x>
</feature>
</query>
</iq>
]]></example>
<p>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.</p>
<p>The remote entity will then agree on a method:</p>
<example caption='Possible response'><![CDATA[
<iq type="result" id="rel_1" from="joe@blow.com/Home">
<query xmlns="http://jabber.org/protocol/rel" cid="myCID">
<feature xmlns="http://jabber.org/protocol/feature-neg">
<x xmlns="jabber:x:data" type="submit">
<field var="method">
<value>s5b</value>
</field>
</x>
</feature>
</query>
</iq>
]]></example>
<p>Or maybe an error:</p>
<example caption='Error'><![CDATA[
<iq type="error" id="rel_1" from="joe@blow.com/Home">
<error code="501">No supported protocols.</error>
</iq>
]]></example>
<p>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 <strong><tt>INIT</tt></strong> state).</p>
<p>On <strong><tt>GOOD</tt></strong>: 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.</p>
<p>On <strong><tt>BAD</tt></strong>: 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.</p>
<p>On <strong><tt>CLOS</tt></strong> or <strong><tt>ERR</tt></strong>, the REL cid is invalidated.</p>
</section2>
</section1>
<section1 topic='Security Considerations'>
<p>There are no security considerations.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<p>The &REGISTRAR; shall register the 'http://jabber.org/protocol/rel' namespace as a result of this JEP.</p>
</section1>
<section1 topic='XML Schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/rel'
xmlns='http://jabber.org/protocol/rel'
elementFormDefault='qualified'>
<xs:element name='query'>
<xs:complexType>
<xs:attribute name='cid' type='xs:string' use='required'/>
<xs:attribute name='keepAlive' type='xs:boolean' use='optional'/>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</jep>

1075
xep-0042.xml Normal file
View File

File diff suppressed because it is too large Load Diff

793
xep-0043.xml Normal file
View File

@ -0,0 +1,793 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Jabber Database Access</title>
<abstract>Expose RDBM systems directly to the jabber network</abstract>
&LEGALNOTICE;
<number>0043</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards</jig>
<author>
<firstname>Justin</firstname>
<surname>Kirby</surname>
<email>justin@openaether.org</email>
<jid>zion@openaether.org</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-10-20</date>
<initials>psa</initials>
<remark>At the request of the author, changed status to Retracted; interested parties should refer to &lt;<link url="http://www.openaether.org/projects/jabber_database.html">http://www.openaether.org/projects/jabber_database.html</link>&gt; for further information.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-08-21</date>
<initials>jk</initials>
<remark>Initial public release</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
<p>This JEP has two aims.</p>
<ol>
<li>Be able to request the available schemas</li>
<li>Perform near SQL-like data manipulation</li>
</ol>
<p>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.</p>
</section1>
<section1 topic='Prerequisites'>
<p>To understand the following sections of this JEP the reader
must be aware of the following.</p>
<section2 topic='Namespace'>
<p>The current namespace of <link>http://openaether.org/projects/jabber_database.html</link>
will be used until this becomes a jep. Once officially accepted as
a jep and approved as final by the council, it will become
<link>http://www.jabber.org/jeps/jep-0043.html</link>.</p>
</section2>
<section2 topic='Elements'>
<ul>
<li>version - specify the version of the protocol that the client/server supports</li>
<li>database - specify the database/catalog has the following attributes:</li>
<ul>
<li>name - name of the database/catalog</li>
<li>sql - embed native SQL queries directly</li>
</ul>
<ul>
<li>table - the element scopes the children into the table. has the following attributes:</li>
<ul>
<li>name - name of the table</li>
<li>permission - what the user can do with the data</li>
<li>col - describes the column. has the following attributes</li>
<ul>
<li>name - name of the column</li>
<li>type - SQL99 datatype of the column</li>
<li>size - size of the datatype if required</li>
<li>op - comparison operator, used only if child of where element</li>
</ul>
<li>where - scopes col elements into a 'sql-like' where clause</li>
<ul>
<li>col - see above</li>
</ul>
</ul>
<li>proc - element scopes the children into a procedure has the following attributes:</li>
<ul>
<li>name - name of the sproc</li>
<li>permission - what the user can do with the data</li>
<li>col - see above</li>
<li>result - indicated return value by running the procedure (restricted to integer)</li>
</ul>
</ul>
</ul>
</section2>
<section2 topic='Data Types'>
<p>There are a limited subset of data types available:</p>
<ul>
<li>bit - a single 'bit', usually used to represent boolean values</li>
<li>tinyint - signed 8bit integer, has a range from -128 to +127</li>
<li>integer - signed 32bit integer, has a range from -2147483648 to +2147483647</li>
<li>utinyint - unsigned 8bit integer, has a range from 0 to +255</li>
<li>uinteger - usigned 32bit integer, has a range from 0 to +4294967296</li>
<li>float - allowed values are -3.402823466E+38 to
-1.175494351E-38, 0, and 1.175494351E-38 to 3.402823466E+38 (can NOT be unsigned)</li>
<li>numeric - unlimited size (some databases constrain this though)</li>
<li>date - resolution is one day. acceptable ranges vary (TODO: constrain minimal range to something)</li>
<li>datetime - a date and time combination (often has range dependencies)</li>
<li>timestamp - a datetime used most often to record events</li>
<li>time - a time in the format HH:MM:SS (TODO: specify valid range)</li>
<li>char - an unsigned byte representing a single character (ASCII)</li>
<li>vchar - a variable width char</li>
<li>text - an extremely large chunk of text</li>
<li>blob - an extremely large chunk of binary data (encode in MIME)</li>
</ul>
</section2>
<section2 topic='Assumed Database Setup'>
<p>All SQL/RDBMS units will be scoped in the xml hierarchy:</p>
<code>
&lt;database&gt;
&lt;table&gt;
&lt;col/&gt;
&lt;/table&gt;
&lt;/database&gt;
</code>
<p>All examples will assume the existence of the following rdbms setup. A
database named 'testdb' with tables created with following SQL
script:</p>
<code>
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)
)
</code>
</section2>
</section1>
<section1 topic='Usage'>
<section2 topic='Requesting Schemas'>
<example caption='A simple schema request'>
&lt;iq id="001" to="db.host" type="get"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;/iq&gt;
</example>
<p>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:</p>
<example caption='Response to a schema request'>
&lt;iq id="001" type="result" from="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one" permission="both"/&gt;
&lt;table name="tbl_two" permission="read"/&gt;
&lt;/database&gt;
&lt;/iq&gt;
</example>
<p>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.</p>
<p>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'.</p>
<example caption='Request detailed table schema'>
&lt;iq id="002" type="get" to="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one"/&gt;
&lt;/database&gt;
&lt;/iq&gt;
</example>
<p>The response would look like:</p>
<example caption='Response to detailed request'>
&lt;iq id="002" type="result" from="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one" permission="both"&gt;
&lt;col name="a_int" type="int"/&gt;
&lt;col name="a_float" type="float"/&gt;
&lt;col name="a_char" type="char" size="10"/&gt;
&lt;/table&gt;
&lt;/database&gt;
&lt;/iq&gt;
</example>
<p>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.</p>
</section2>
<section2 topic='Manipulating Data'>
<p>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.</p>
<section3 topic='Selects'>
<p>To indicate a select like query, specify an &lt;iq&gt; 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 &lt;col&gt; 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.</p>
<example caption='Basic select'>
&lt;iq id="003" type="get" to="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one"&gt;
&lt;col name="a_int"/&gt;
&lt;col name="a_float"/&gt;
&lt;col name="a_char"/&gt;
&lt;/table&gt;
&lt;/database&gt;
&lt;/iq&gt;
SQL Syntax:
select a_int, a_float, a_char
from tbl_one
</example>
<p>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.</p>
<example caption='Basic select with limit'>
&lt;iq id="003" type="get" to="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one" limit="2"&gt;
&lt;col name="a_int"/&gt;
&lt;col name="a_float"/&gt;
&lt;col name="a_char"/&gt;
&lt;/table&gt;
&lt;/database&gt;
&lt;/iq&gt;
</example>
<p>In this case a limit of two rows will be returned in the result set.</p>
<p> 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
&lt;table&gt; element. This allows for queries on multiple
tables to be used in one &lt;iq&gt; packet.</p>
<example caption='Response to basic select'>
&lt;iq id="003" type="result" from="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one"&gt;
&lt;col name="a_int"&gt;1234&lt;/col&gt;
&lt;col name="a_float"&gt;123.45&lt;/col&gt;
&lt;col name="a_char"&gt;onetwothre&lt;/col&gt;
&lt;/table&gt;
&lt;table name="tbl_one"&gt;
&lt;col name="a_int"&gt;2345&lt;/col&gt;
&lt;col name="a_float"&gt;234.56&lt;/col&gt;
&lt;col name="a_char"&gt;twothreefo&lt;/col&gt;
&lt;/table&gt;
&lt;/database&gt;
&lt;/iq&gt;
</example>
</section3>
<section3 topic='Constraining Result Sets'>
<p>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.</p>
<example caption='Select with constraints'>
&lt;iq id="004" type="get" to="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one"&gt;
&lt;col name="a_int"/&gt;
&lt;col name="a_float"/&gt;
&lt;col name="a_char"/&gt;
&lt;where&gt;
&lt;col name="a_int" op="eq"&gt;1234&lt;/col&gt;
&lt;col name="a_float" op="lt" conj="and"&gt;200.00&lt;/col&gt;
&lt;/where&gt;
&lt;/table&gt;
&lt;/database&gt;
&lt;/iq&gt;
SQL Syntax:
select a_int, a_float, a_char from tbl_one
where a_int = 1234 and a_float &lt; 200.00
</example>
<p>Attributes only used in the &lt;col&gt; element within a
&lt;where&gt; element are the op (for operator) and conj for
(conjunction). The op is used for comparison operators such
as &lt;, &gt;, =, &lt;&gt;, &lt;=, &gt;=
<ul>
<li>eq - equivalent =</li>
<li>neq - not-equivalent &lt;&gt;</li>
<li>lt - less than &lt;</li>
<li>gt - greater than &gt;</li>
<li>let - less than or equivalent &lt;=</li>
<li>get - greater than or equivalent &gt;=</li>
<li>null - IS NULL (the column is null in the database sense of the word)</li>
</ul>
</p>
<p>The conjuction attribute is used to combined constraints in the where clause
<ul>
<li>not - to negate a result</li>
<li>or - logical OR ||</li>
<li>and - logical AND &amp;&amp;</li>
</ul>
</p>
<p><strong>Result</strong></p>
<example caption='Response to select with constraints'>
&lt;iq id="003" type="result" to="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one"&gt;
&lt;col name="a_int"&gt;1234&lt;/col&gt;
&lt;col name="a_float"&gt;123.45&lt;/col&gt;
&lt;col name="a_char"&gt;onetwothre&lt;/col&gt;
&lt;/table&gt;
&lt;/database&gt;
&lt;/iq&gt;
</example>
</section3>
<section3 topic='Inserts'>
<p>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 &lt;where&gt; element is used. If there is no
&lt;where&gt; element then it must be interpreted as an insert.
If a &lt;where&gt; element does exist, then it must be
interpreted as an update.</p>
<example caption='Inserting data'>
&lt;iq id="004" type="set" to="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one"&gt;
&lt;col name="a_int"&gt;3456&lt;/col&gt;
&lt;col name="a_float"&gt;345.67&lt;/col&gt;
&lt;col name="a_char"&gt;threefour&lt;/col&gt;
&lt;/table&gt;
&lt;table name="tbl_two"&gt;
&lt;col name="a_date"&gt;02/16/2002&lt;/col&gt;
&lt;col name="a_numeric"&gt;123456789123.123&lt;/col&gt;
&lt;/table&gt;
&lt;/database&gt;
&lt;/iq&gt;
SQL syntax:
insert tbl_one (a_int, a_float,a_char)VALUES(3456, 345.67, 'threefour')
insert tbl_two (a_date, a_numeric) VALUES('02/16/2002', 123456789123.123)
</example>
<p><strong>Result</strong></p>
<p> 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 &lt;table&gt; element scope. An empty
&lt;table&gt; element indicates success, and a &lt;table&gt;
element containing an &lt;error&gt; element indicates a failure.</p>
<example caption='Response to data insert'>
&lt;iq id="004" type="result" from="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one"/&gt;
&lt;table name="tbl_two"&gt;
&lt;error code="380"&gt;permission denied on table&lt;/error&gt;
&lt;/table&gt;
&lt;/database&gt;
&lt;/iq&gt;
</example>
<p> The insert into tbl_one succeeded since the response has an
empty &lt;table&gt; element. However, the insert into tbl_two
failed with a permission denied error. Which is indicated with a
non-empty &lt;table&gt; element.</p>
</section3>
<section3 topic='Updates'>
<p> As stated previously, if the type attribute has a value of
set and a &lt;where&gt; element exists, then it must be interpreted as an update.</p>
<example caption='Updating'>
&lt;iq id="005" type="set" to="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one"&gt;
&lt;col name="a_char"&gt;aaaaaaaaaa&lt;/col&gt;
&lt;where&gt;
&lt;col name=c"a_int"&gt;1234&lt;/col&gt;
&lt;/where&gt;
&lt;/table&gt;
&lt;/database&gt;
&lt;/iq&gt;
SQL Syntax:
update tbl_one
set a_char = 'aaaaaaaaaa'
where a_int = 1234
</example>
<p><strong>Result</strong></p>
<p> Again, if there is no result set returned by the query, then
success or failure must be indicated.</p>
<example caption='Response to update'>
&lt;iq id="005" type="result" to="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one"/&gt;
&lt;/database&gt;
&lt;/iq&gt;
</example>
</section3>
<section3 topic='Deletes'>
<p> If the type attribute has a value of set and there are no
&lt;col&gt; elements scoped within the &lt;table&gt; element,
then the query must be interpreted as a delete.</p>
<example caption='Simple delete'>
&lt;iq id="006" type="set" to="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one"&gt;
&lt;where&gt;
&lt;col name="a_int" op="eq"&gt;1234&lt;/col&gt;
&lt;/where&gt;
&lt;/table&gt;
&lt;/database&gt;
&lt;/iq&gt;
SQL Syntax:
delete from tbl_one where a_int = 1234
</example>
<p><strong>Result</strong></p>
<p>Again, if a result set is not generated by a query, then
success or failure must be indicated by the &lt;table&gt; element</p>
<example caption='Response to delete'>
&lt;iq id="006" type="result" to="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one"/&gt;
&lt;/database&gt;
&lt;/iq&gt;
</example>
</section3>
</section2>
<section2 topic='Procedures'>
<p> Procedures, or stored procedures <note>Apparently procedures
are not as common in RDBMS as I thought. Postgres and MySQL have
functions, but not procedures. So until I, or someone else,
researches this issue this feature is on hold.</note>
, are often handy to make frequently used sql queries execute faster.
These are simply queries stored in a precompiled form and given a
name with a list of parameters. Each RDBMS handles procedures
differently, but the common characteristics are that they are
stored server side and have in/out parameters.</p>
<p> The &lt;proc&gt; element will be used to indicate a procedure.
It has similar characteristics to the &lt;table&gt; element. The
core differences are that the &lt;col&gt; elements have permissions
and a &lt;result&gt; element can be used to indicate the value
returned by the procedure.</p>
<p> The permission attribute on a &lt;col&gt; element is used to
indicate whether the parameter is in (read), out (write) or in/out (both). </p>
<p> The only result set acceptable from a procedure is that of the
parameters or &lt;col&gt; element. If the procedure produces a
result set outside of the parameters this should be ignored.</p>
</section2>
<section2 topic='Errors'>
<p> The server must be able to let the client know when an error
occurs, instead of just being silent.</p>
<table caption='Error Codes'>
<tr>
<th>Code</th>
<th>Message</th>
<th>Description</th>
</tr>
<tr>
<td>399</td>
<td>Invalid Database Name</td>
<td>Returned when the client has requested information from a
database which does not exist according to the component.</td>
</tr>
<tr>
<td>398</td>
<td>Invalid Table Name</td>
<td>Returned when the client has requested information from a
table/procedure which does not exist according to the component.</td>
</tr>
<tr>
<td>397</td>
<td>Invalid Column Name</td>
<td>Returned when the client has requested information from a
column which does not exist according to the component.</td>
</tr>
<tr>
<td>380</td>
<td>Permission Denied on Table</td>
<td>Returned when the requested action is not allowed for the
user on the table</td>
</tr>
<tr>
<td>401</td>
<td>Access Denied</td>
<td>Returned when the user does not have permission to use the
component.</td>
</tr>
</table>
<p>If the user requests an action on a table which they do not have
permission to do the following should be returned</p>
<example caption='Permission denied error'>
&lt;iq id="004" type="error" from="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_two"&gt;
&lt;error code="380"&gt;permission denied on table&lt;/error&gt;
&lt;/table&gt;
&lt;/database&gt;
&lt;/iq&gt;
</example>
<p>If the user is not allowed to access the component the following should be returned</p>
<example caption='General access denied'>
&lt;iq id="004" type="error" from="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;error code="401"&gt;Access Denied&lt;/error&gt;
&lt;/database&gt;
&lt;/iq&gt;
</example>
</section2>
<section2 topic='Optional Features'>
<p> 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 &lt;query&gt; element will extend
the functionality </p>
<section3 topic='Embedded SQL'>
<p> 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 &lt;sql&gt; element may
be implemented to provide this feature.</p>
<p> The &lt;sql&gt; element must be scoped within the &lt;database&gt; element.</p>
<example caption='Embedded sql query'>
&lt;iq id="007" type="get" to="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;sql&gt; select a_int, a_float from tbl_one &lt;/sql&gt;
&lt;/database&gt;
&lt;/iq&gt;
</example>
<p><strong>Result</strong></p>
<example caption='Response to embedded query'>
&lt;iq id="007" type="result" to="db.host"&gt;
&lt;database
name="testdb"
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;table name="tbl_one" permission="both"&gt;
&lt;col name="a_int" type="integer"/&gt;
&lt;col name="a_float" type="float"/&gt;
&lt;/table&gt;
&lt;table name="tbl_one"&gt;
&lt;col name="a_int"&gt;1234&lt;/col&gt;
&lt;col name="a_float"&gt;123.45&lt;/col&gt;
&lt;/table&gt;
&lt;table name="tbl_one"&gt;
&lt;col name="a_int"&gt;2345&lt;/col&gt;
&lt;col name="a_float"&gt;234.56&lt;/col&gt;
&lt;/table&gt;
&lt;/database&gt;
&lt;/iq&gt;
</example>
<p> 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.</p>
<p> If multiple tables are used within one SQL statement, then
then name attribute within the &lt;table&gt; 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 &lt;database&gt; element. This will allow for
multiple &lt;sql&gt; results to be scoped within the same result.</p>
</section3>
<section3 topic='Version Negotiation'>
<p>It is expected that this protocol will grow and be extended
to meet various demands. Therefore, version
negotiation<note>Version Negotiation is being killed since browsing, feature
negotiation, or disco will be able to perform this function,
however it might be useful as an optional feature for clients
that don't implement these yet, especially considering none
of these have been standardized.</note> will be
incorporated up front.</p>
<p>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.</p>
<code>
&lt;iq id="000" type="get" to="db.host"&gt;
&lt;database
xmlns="http://openaether.org/projects/jabber_database.html"&gt;
&lt;version&gt;0.1&lt;/version&gt;
&lt;/database&gt;
&lt;/iq&gt;
</code>
<p>Three responses are possible from the server.</p>
<ol>
<li>It supports that version number and responds with:
<p><code>
&lt;iq id="000" type="result" from="db.host"&gt;
&lt;database
xmlns="http://openaether.org/projects/jabber_database.html"&gt;
&lt;version&gt;0.1&lt;/version&gt;
&lt;/database&gt;
&lt;/iq&gt;
</code>
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.</p></li>
<li>It does not support that version number and responds with:
<p><code>
&lt;iq id="000" type="error" from="db.host"&gt;
&lt;database
xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
&lt;/iq&gt;
</code>
The type of 'error' indicates a failure in conforming to the
desired version number. The server may optionally send an
alternative option.
<code>
&lt;iq id="000" type="error" from="db.host"&gt;
&lt;database
xmlns="http://openaether.org/projects/jabber_database.html"&gt;
&lt;version&gt;0.2&lt;/version&gt;
&lt;/database&gt;
&lt;/iq&gt;
</code></p></li>
<li>If the server has no idea what the client is talking
about it should send the appropriate Jabber error code.</li>
</ol>
</section3>
</section2>
</section1>
<section1 topic='Limitations'>
<ol>
<li>No joins, roll ups, cubes</li>
<li>Views are not differentiated from tables</li>
<li>provides basic sql-like functionality only</li>
<li>Utilizes <em>lowest common denominator</em> approach</li>
</ol>
</section1>
<section1 topic='Todos'>
<ul>
<li>define procedures; what they are and how they work</li>
<li>determine value of adding administration features</li>
</ul>
</section1>
<section1 topic='Thanks'>
<p>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.</p>
</section1>
<section1 topic='DTD and Schema'>
<section2 topic='DTD'>
<code>
&lt;!ELEMENT version (#PCDATA)&gt;
&lt;!ELEMENT error (#PCDATA)&gt;
&lt;!ELEMENT sql(#PCDATA)&gt;
&lt;!ELEMENT database (table | sproc | sql | error)*&gt;
&lt;!ELEMENT table (col | where | error)*&gt;
&lt;!ELEMENT where (col+)&gt;
&lt;!ELEMENT col (#PCDATA)&gt;
&lt;!ELEMENT proc(col | result | error)*&gt;
&lt;!ELEMENT result (#PCDATA)&gt;
&lt;!ATTLIST error code CDATA #IMPLIED&gt;
&lt;!ATTLIST database name CDATA #IMPLIED&gt;
&lt;!ATTLIST table
name CDATA #IMPLIED
permission (read | write | both) #IMPLIED
limit CDATA #IMPLIED
&gt;
&lt;!ATTLIST proc name CDATA #IMPLIED&gt;
&lt;!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
&gt;
</code>
</section2>
<section2 topic='Schema'>
<p><strong>Anyone care to do this?</strong></p>
</section2>
</section1>
</jep>

172
xep-0044.xml Normal file
View File

@ -0,0 +1,172 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Full Namespace Support for XML Streams</title>
<abstract>A description of the use of namespaces within Jabber.</abstract>
&LEGALNOTICE;
<number>0044</number>
<status>Deferred</status>
<type>Standards Track</type>
<jig>Standards</jig>
<author>
<firstname>Robert</firstname>
<surname>Norris</surname>
<email>rob@cataclysm.cx</email>
<jid>rob@cataclysm.cx</jid>
</author>
<revision>
<version>0.1</version>
<date>2002-08-26</date>
<initials>rn</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>Jabber has traditionally supported a subset of the XML Namespaces specification <note><link url="http://www.w3.org/TR/REC-xml-names">http://www.w3.org/TR/REC-xml-names</link></note>. The protocol has been restricted to using specific namespace prefixes.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Requirements and Protocol'>
<p>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:</p>
<example caption="A typical XML stream"><![CDATA[
SEND: <stream:stream xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
to='jabber.org'>
RECV: <stream:stream xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
id='12345678'>
SEND: <iq type='get' to='jabber.org'>
<query xmlns='jabber:iq:version'/>
</iq>
RECV: <iq type='result' from='jabber.org'>
<query xmlns='jabber:iq:version'>
<name>jsm</name>
<version>1.4.2</version>
<os>Linux 2.4.19</os>
</query>
</iq>]]>
</example>
<p>Note that there may also be additional namespaces specified in the stream header, to select or inform of various server features:</p>
<example caption="A typical XML stream with stream options"><![CDATA[
SEND: <stream:stream xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
xmlns:sasl='http://www.iana.org/assignments/sasl-mechanisms'
to='jabber.org'>
RECV: <stream:stream xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
xmlns:sasl='http://www.iana.org/assignments/sasl-mechanisms'
id='12345678'>
<sasl:mechanisms>
<sasl:mechanism>PLAIN</sasl:mechanism>
<sasl:mechanism>DIGEST-MD5</sasl:mechanism>
<sasl:mechanism>EXTERNAL</sasl:mechanism>
</sasl:mechanisms>
SEND: <iq type='get' to='jabber.org'>
<query xmlns='jabber:iq:version'/>
</iq>
RECV: <iq type='result' from='jabber.org'>
<query xmlns='jabber:iq:version'>
<name>jsm</name>
<version>1.4.2</version>
<os>Linux 2.4.19</os>
</query>
</iq>]]>
</example>
<p>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:</p>
<example caption="XML stream with arbitrary namespace prefixes (1)"><![CDATA[
SEND: <stream xmlns:app='jabber:client'
xmlns='http://etherx.jabber.org/streams'
to='jabber.org'>
RECV: <stream xmlns:app='jabber:client'
xmlns='http://etherx.jabber.org/streams'
id='12345678'>
SEND: <app:iq type='get' to='jabber.org'>
<query xmlns='jabber:iq:version'/>
</app:iq>
RECV: <app:iq type='result' from='jabber.org'>
<query xmlns='jabber:iq:version'>
<name>jsm</name>
<version>1.4.2</version>
<os>Linux 2.4.19</os>
</query>
</app:iq>]]>
</example>
<p>Also, since there exist streams in both directions, it should be possible for prefixes to differ between the two streams:</p>
<example caption="XML stream with arbitrary namespace prefixes"><![CDATA[
SEND: <stream xmlns:app='jabber:client'
xmlns='http://etherx.jabber.org/streams'
to='jabber.org'>
RECV: <stream:stream xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
id='12345678'>
SEND: <app:iq type='get' to='jabber.org'>
<query xmlns='jabber:iq:version'/>
</app:iq>
RECV: <iq type='result' from='jabber.org'>
<ver:query xmlns:ver='jabber:iq:version'>
<ver:name>jsm</ver:name>
<ver:version>1.4.2</ver:version>
<ver:os>Linux 2.4.19</ver:os>
</ver:query>
</iq>]]>
</example>
<p>Additionally, it should be possible to declare namespaces on the stream header so that they don't need to be declared later:</p>
<example caption="XML stream with namespaces declared in the stream header"><![CDATA[
SEND: <stream:stream xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
xmlns:ver='jabber:iq:version'
to='jabber.org'>
RECV: <stream:stream xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
xmlns:ver='jabber:iq:version'
id='12345678'>
SEND: <iq type='get' to='jabber.org'>
<ver:query/>
</iq>
RECV: <iq type='result' from='jabber.org'>
<ver:query>
<ver:name>jsm</ver:name>
<ver:version>1.4.2</ver:version>
<ver:os>Linux 2.4.19</ver:os>
</ver:query>
</iq>]]>
</example>
<p>And of course, any combinations of these should be valid, as long as they conform to the XML Namespaces specification.</p>
</section1>
<section1 topic='Implementation Notes'>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section1>
</jep>

5206
xep-0045.xml Normal file
View File

File diff suppressed because it is too large Load Diff

216
xep-0046.xml Normal file
View File

@ -0,0 +1,216 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>DTCP</title>
<abstract>Direct TCP connection between two Jabber entities.</abstract>
&LEGALNOTICE;
<number>0046</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards</jig>
<dependencies>None</dependencies>
<supersedes>None</supersedes>
<supersededby>JEP-0065</supersededby>
<shortname>None</shortname>
<author>
<firstname>Justin</firstname>
<surname>Karneges</surname>
<email>justin@affinix.com</email>
<jid>justin@andbit.net</jid>
</author>
<revision>
<version>0.8</version>
<date>2003-04-11</date>
<initials>psa</initials>
<remark>At the request of the JEP author, changed status to Retracted. This JEP will not be considered further by the Jabber Software Foundation and should not be used as a basis for implementations.</remark>
</revision>
<revision>
<version>0.7</version>
<date>2002-12-10</date>
<initials>jk</initials>
<remark>Remove 'comment' block</remark>
</revision>
<revision>
<version>0.6</version>
<date>2002-12-02</date>
<initials>jk</initials>
<remark>Simplification of the document</remark>
</revision>
<revision>
<version>0.5</version>
<date>2002-11-19</date>
<initials>jk</initials>
<remark>Changed handshake and namespace, merged active/passive</remark>
</revision>
<revision>
<version>0.4</version>
<date>2002-10-10</date>
<initials>jk</initials>
<remark>Change to 'comment' block</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-09-18</date>
<initials>jk</initials>
<remark>Support for SSL</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-09-18</date>
<initials>jk</initials>
<remark>Simplified things.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-09-12</date>
<initials>jk</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
</section1>
<section1 topic='Requirements'>
<p>The following design goals are considered:</p>
<ul>
<li>The protocol should be reasonably effective in scenarios involving NAT and/or firewalls.<note>DTCP works in situations where at least one client can accept incoming connections.</note></li>
<li>It should be reasonably secure.</li>
<li>Establishing a connection should be fast.</li>
<li>The protocol should be simple.</li>
</ul>
</section1>
<section1 topic='Implementation'>
<section2 topic='Requesting a DTCP connection'>
<p>Say you wish to initiate a DTCP session with Joe:</p>
<example caption='Requesting a DTCP session'><![CDATA[
<iq type="set" id="dtcp_1" to="joe@blow.com/Home">
<query xmlns="http://jabber.org/protocol/dtcp">
<key>c7b5ea3f</key>
<host>192.168.0.32:8000</host>
<host>63.110.44.12:8000</host>
</query>
</iq>
]]></example>
<p>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.</p>
<example caption='Success response'><![CDATA[
<iq type="result" id="dtcp_1" from="joe@blow.com/Home">
<query xmlns="http://jabber.org/protocol/dtcp">
<key>a1b2c3d4</key>
<host>192.168.0.33:8000</host>
</query>
</iq>
]]></example>
<p>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.</p>
<example caption='Error response'><![CDATA[
<iq type="error" id="dtcp_1" from="joe@blow.com/Home">
<error code="501">DTCP not supported</error>
</iq>
]]></example>
<p>Or he may send an error.</p>
</section2>
<section2 topic='Establishing the TCP connection'>
<p>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.</p>
<p>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:</p>
<example><![CDATA[
<iq type="error" to="joe@blow.com/Home">
<query xmlns="http://jabber.org/protocol/dtcp">
<key>a1b2c3d4</key>
</query>
<error code="503">Could not connect to any of the hosts.</error>
</iq>
]]></example>
<p>If an entity was not provided any hosts, then it is assumed that he has given up and this packet need not be sent.</p>
</section2>
<section2 topic='The handshake'>
<p>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).</p>
<example caption='Command format'>
[command]:[argument]&lt;LF&gt;
</example>
<p>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.</p>
<p>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.</p>
<section3 topic='SSL/TLS'>
<p>If you want an encrypted channel, then it must be requested using the 'starttls' command</p>
<example>
starttls&lt;LF&gt;
</example>
<p>If successful, the serving client should send back:</p>
<example>
ok&lt;LF&gt;
</example>
<p>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.</p>
<p>Or the serving client might report an error:</p>
<example>
error&lt;LF&gt;
</example>
<p>This means SSL is not supported by the serving client.</p>
</section3>
<section3 topic='Authenticating'>
<p>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:</p>
<example>
key:a1b2c3d4&lt;LF&gt;
</example>
<p>If the serving client recognizes the key, then it should respond by sending the connecting client's key:</p>
<example>
ok:c7b5ea3f&lt;LF&gt;
</example>
<p>Or the serving client might report an error:</p>
<example>
error&lt;LF&gt;
</example>
<p>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":</p>
<example>
ok&lt;LF&gt;
</example>
<p>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.</p>
<p>At this point, the channel is established. No further commands may be issued, as the TCP connection is now for application data only.</p>
</section3>
</section2>
</section1>
</jep>

291
xep-0047.xml Normal file
View File

@ -0,0 +1,291 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>In-Band Bytestreams (IBB)</title>
<abstract>This JEP defines a protocol for bytestreaming data in band between any two entities over Jabber/XMPP.</abstract>
&LEGALNOTICE;
<number>0047</number>
<status>Draft</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>JEP-0079</spec>
</dependencies>
<supersedes/>
<supersededby/>
<schemaloc>
<url>http://jabber.org/protocol/ibb/ibb.xsd</url>
</schemaloc>
<shortname>ibb</shortname>
&infiniti;
<revision>
<version>1.0</version>
<date>2003-12-10</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
</revision>
<revision>
<version>0.8</version>
<date>2003-12-04</date>
<initials>jk</initials>
<remark>Add 'block-size' attribute and usage guidelines</remark>
</revision>
<revision>
<version>0.7</version>
<date>2003-05-23</date>
<initials>jk</initials>
<remark>Use IQ for shutdown, remove JEP-0022 dependency, loop the counter</remark>
</revision>
<revision>
<version>0.6</version>
<date>2003-05-14</date>
<initials>jk</initials>
<remark>Use message for delivery</remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-04-06</date>
<initials>jk</initials>
<remark>Changed newseq to prevseq, added acks, changed seq size to 32-bit</remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-03-22</date>
<initials>jk</initials>
<remark>Changed protocol, added sequence id</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-12-10</date>
<initials>jk</initials>
<remark>Removed the 'comment' block, changed namespace</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-10-10</date>
<initials>jk</initials>
<remark>Revised the text</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-09-29</date>
<initials>jk</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
</section1>
<section1 topic='Uses'>
<p>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.</p>
</section1>
<section1 topic='Implementation'>
<section2 topic='Creating a bytestream'>
<example caption='Initiation of Interaction'><![CDATA[
<iq type='set'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='inband_1'>
<open sid='mySID'
block-size='4096'
xmlns='http://jabber.org/protocol/ibb'/>
</iq>
]]></example>
<p>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.</p>
<example caption='Success Response'><![CDATA[
<iq type='result'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='inband_1'/>
]]></example>
<p>This is a success response from juliet@capulet.com/balcony, saying that the bytestream is active.</p>
<example caption='Error'><![CDATA[
<iq type='error'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='inband_1'/>
<error code='501' type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>This is an error response from juliet@capulet.com/balcony saying that an In-Band Bytestreams is not possible.</p>
</section2>
<section2 topic='Sending data'>
<p>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.</p>
<example caption='Sending data'><![CDATA[
<message from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='msg1'>
<data xmlns='http://jabber.org/protocol/ibb' sid='mySID' seq='0'>
qANQR1DBwU4DX7jmYZnncmUQB/9KuKBddzQH+tZ1ZywKK0yHKnq57kWq+RFtQdCJ
WpdWpR0uQsuJe7+vh3NWn59/gTc5MDlX8dS9p0ovStmNcyLhxVgmqS8ZKhsblVeu
IpQ0JgavABqibJolc3BKrVtVV1igKiX/N7Pi8RtY1K18toaMDhdEfhBRzO/XB0+P
AQhYlRjNacGcslkhXqNjK5Va4tuOAPy2n1Q8UUrHbUd0g+xJ9Bm0G0LZXyvCWyKH
kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA
</data>
<amp xmlns='http://jabber.org/protocol/amp'>
<rule condition='deliver-at' value='stored' action='error'/>
<rule condition='match-resource' value='exact' action='error'/>
</amp>
</message>
]]></example>
<p>The data to send is included as XML character data of the &lt;data/&gt; 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.</p>
<p>It is possible that the message may fail to be delivered:</p>
<example caption='Failed delivery'><![CDATA[
<message from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='msg1' type='error'>
...
<error code='504' type='cancel'>
<remote-server-timeout xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</message>
]]></example>
<p>Upon delivery failure, the sender MUST consider the bytestream to be closed and invalid.</p>
</section2>
<section2 topic='Closing the bytestream'>
<p>To close the bytestream, send the following:</p>
<example caption='Closing the bytestream'><![CDATA[
<iq type='set'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='inband_2'>
<close xmlns='http://jabber.org/protocol/ibb' sid='mySID'/>
</iq>
]]></example>
<example caption='Success response'><![CDATA[
<iq type='result'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='inband_2'/>
]]></example>
<p>This is a success response from juliet@capulet.com/balcony, saying that the bytestream is now closed.</p>
<example caption='Possible error'><![CDATA[
<iq type='error'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='inband_2'>
<error code='404' type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>Upon error, the bytestream MUST be considered closed and invalid.</p>
</section2>
<section2 topic='Receiving packets'>
<p>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.</p>
</section2>
</section1>
<section1 topic='Usage Guidelines'>
<ul>
<li>Generally, IBB should be used as a last resort. <strong>SOCKS5 Bytestreams</strong> will almost always be preferable.</li>
<li>A server MAY rate limit a connection, depending on the size and frequency of data packets.</li>
<li>A server MAY disconnect a connection that sends overly large packets as defined by server policy.</li>
<li>It is RECOMMENDED to use a 'block-size' of 4096.</li>
<li>For proper tracking of message delivery errors, the use of the stanza 'id' attribute is RECOMMENDED.</li>
</ul>
</section1>
<section1 topic='Security Considerations'>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<section2 topic='Protocol Namespaces'>
<p>The &REGISTRAR; shall register the 'http://jabber.org/protocol/ibb' namespace as a result of this JEP.</p>
</section2>
</section1>
<section1 topic='XML Schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/ibb'
xmlns='http://jabber.org/protocol/ibb'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0047: http://www.jabber.org/jeps/jep-0047.html
</xs:documentation>
</xs:annotation>
<xs:element name='open'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='sid' type='xs:string' use='required'/>
<xs:attribute name='block-size' type='xs:string' use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='close'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='sid' type='xs:string' use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='data'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='sid' type='xs:string' use='required'/>
<xs:attribute name='seq' type='xs:string' use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
</jep>

171
xep-0048.xml Normal file
View File

@ -0,0 +1,171 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Bookmark Storage</title>
<abstract>This JEP documents a protocol for the storage of bookmarks to conference rooms and other entities in a Jabber user's account.</abstract>
&LEGALNOTICE;
<number>0048</number>
<status>Active</status>
<type>Historical</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>JEP-0049</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>bookmarks</shortname>
<schemaloc>
<url>http://jabber.org/protocol/bookmarks/bookmarks.xsd</url>
</schemaloc>
<author>
<firstname>Rachel</firstname>
<surname>Blackman</surname>
<email>rcb@ceruleanstudios.com</email>
<jid>sparks@jabber.org</jid>
</author>
&pgmillard;
<revision>
<version>1.0</version>
<date>2003-10-08</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, changed status to Active; also added XML schema.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-05-13</date>
<initials>rcb</initials>
<remark>Re-focused to document only the existing protocol in use.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-10-03</date>
<initials>pgm</initials>
<remark>Typos, etc...</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-10-03</date>
<initials>pgm</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
<p>&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.</p>
</section1>
<section1 topic='The storage:bookmarks Namespace'>
<p>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.</p>
<p>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.</p>
<section2 topic='The url element'>
<p>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.</p>
<p>A URL element therefore only needs a 'url' tag in addition to the required 'name', like so:</p>
<example caption='An example of the URL element'><![CDATA[
<iq type='result' id='1'>
<query xmlns='jabber:iq:private'>
<storage xmlns='storage:bookmarks'>
<url name='Complete Works of Shakespeare'
url='http://the-tech.mit.edu/Shakespeare/'/>
</storage>
</query>
</iq>
]]>
</example>
<p>This bookmark would be displayed in the client as 'Complete Works of Shakespeare' and would take the user to <link url='http://the-tech.mit.edu/Shakespeare/'>http://the-tech.mit.edu/Shakespeare/</link> if activated. A bookmark set can contain any number of urls.</p>
</section2>
<section2 topic='The conference element'>
<p>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 <note>Exodus, see &lt;<link url='http://exodus.jabberstudio.org/'>http://exodus.jabberstudio.org/</link>&gt;.</note> and Rival Messenger <note>Rival Messenger, see &lt;<link url='http://rival.chote.net'>http://rival.chote.net/</link>&gt;.</note>. In addition to the required 'jid' attribute, the conference element also possesses an 'autojoin' attribute, which determines whether or not the client should automatically join that conference room on login; this attribute is of type xs:boolean (see &w3xmlschema2;) and the default value is "false". &BOOLEANNOTE;</p>
<p>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.</p>
<example caption='An example of the conference element'><![CDATA[
<iq type='result' id='2'>
<query xmlns='jabber:iq:private'>
<storage xmlns='storage:bookmarks'>
<conference name='Council of Oberon'
autojoin='true'
jid='council@conference.underhill.org'>
<nick>Puck</nick>
<password>titania</password>
</conference>
</storage>
</query>
</iq>
]]></example>
<p>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.</p>
</section2>
</section1>
<section1 topic='Security Considerations'>
<p>Security considerations related to private XML storage are described in JEP-0049.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<p>No namespaces or parameters need to be registered with the &REGISTRAR; as a result of this JEP.</p>
</section1>
<section1 topic='XML Schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='storage:bookmarks'
xmlns='storage:bookmarks'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0048: http://www.jabber.org/jeps/jep-0048.html
</xs:documentation>
</xs:annotation>
<xs:element name='storage'>
<xs:complexType>
<xs:choice>
<xs:element ref='url'/>
<xs:element ref='conference'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name='url'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='name' type='xs:string' use='required'/>
<xs:attribute name='url' type='xs:string' use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='conference'>
<xs:complexType>
<xs:sequence>
<xs:element name='nick' type='xs:string' minOccurs='0'/>
<xs:element name='password' type='xs:string' minOccurs='0'/>
</xs:sequence>
<xs:attribute name='autojoin' type='xs:boolean' use='optional' default='false'/>
<xs:attribute name='jid' type='xs:string' use='required'/>
<xs:attribute name='name' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
<section1 topic='Author Note' anchor='authornote'>
<p>Peter Millard, a co-author of this specification from version 0.1 through version 1.0, died on April 26, 2006.</p>
</section1>
</jep>

252
xep-0049.xml Normal file
View File

@ -0,0 +1,252 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Private XML Storage</title>
<abstract>This JEP provides canonical documentation of the 'jabber:iq:private' namespace currently in common usage.</abstract>
&LEGALNOTICE;
<number>0049</number>
<status>Active</status>
<type>Historical</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>iq-private</shortname>
<schemaloc>
<url>http://jabber.org/protocol/iq-private/iq-private.xsd</url>
</schemaloc>
&stpeter;
<author>
<firstname>Russell</firstname>
<surname>Davis</surname>
<email>ukscone@burninghorse.com</email>
<jid>ukscone@burninghorse.com</jid>
</author>
<revision>
<version>1.2</version>
<date>2004-03-01</date>
<initials>psa</initials>
<remark>Corrected several errors in the text; specified security considerations.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2004-01-06</date>
<initials>psa</initials>
<remark>Added XML schema; specified XMPP error handling; added security, IANA, and Jabber Registrar considerations.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2003-01-09</date>
<initials>psa</initials>
<remark>Updated status to Active per vote of the Jabber Council.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2002-11-21</date>
<initials>psa</initials>
<remark>Fixed error handling with regard to reserved namespaces; specified error regarding empty IQ get request.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-11-21</date>
<initials>psa</initials>
<remark>Added error scenarios, removed most error codes, cleaned up the text.</remark>
</revision>
<revision>
<version>0.2.1</version>
<date>2002-10-09</date>
<initials>rkd</initials>
<remark>Added error code table.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-10-08</date>
<initials>rkd</initials>
<remark>Corrected author email and jid. Added sentence about the
inadvisability of use.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-10-08</date>
<initials>rkd</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
</section1>
<section1 topic='jabber:iq:private Namespace'>
<section2 topic='Description'>
<p>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;.</p>
</section2>
<section2 topic='Methods'>
<table caption='Description of Acceptable Methods'>
<tr><td>get</td><td>Sent with a blank query to retrieve the private data from the server.</td></tr>
<tr><td>set</td><td>Sent with the private XML data contained inside of a query.</td></tr>
<tr><td>result</td><td>Returns the private data from the server.</td></tr>
<tr><td>error</td><td>There was an error processing the request. The exact error can be found in the child error element.</td></tr>
</table>
</section2>
<section2 topic='Elements'>
<p>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.</p>
<example caption='Client Stores Private Data'><![CDATA[
CLIENT:
<iq type="set" id="1001">
<query xmlns="jabber:iq:private">
<exodus xmlns="exodus:prefs">
<defaultnick>Hamlet</defaultnick>
</exodus>
</query>
</iq>
SERVER:
<iq type="result"
from="hamlet@shakespeare.lit/denmark"
to="hamlet@shakespeare.lit/denmark"
id="1001"/>
]]></example>
<example caption='Client Retrieves Private Data'><![CDATA[
CLIENT:
<iq type="get" id="1002">
<query xmlns="jabber:iq:private">
<exodus xmlns="exodus:prefs"/>
</query>
</iq>
SERVER:
<iq type="result"
from="hamlet@shakespeare.lit/denmark"
to="hamlet@shakespeare.lit/denmark"
id="1002">
<query xmlns="jabber:iq:private">
<exodus xmlns="exodus:prefs">
<defaultnick>Hamlet</defaultnick>
</exodus>
</query>
</iq>
]]></example>
<p>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).</p>
<example caption='User Attempts to Get or Set Data for Another User'><![CDATA[
CLIENT:
<iq type="set" to="hamlet@shakespeare.lit" id="1003">
<query xmlns="jabber:iq:private">
<exodus xmlns="exodus:prefs">
<defaultnick>Macbeth</defaultnick>
</exodus>
</query>
</iq>
SERVER:
<iq type="error"
from="hamlet@shakespeare.lit"
to="macbeth@shakespeare.lit"
iq="1003">
<query xmlns="jabber:iq:private">
<exodus xmlns="exodus:prefs">
<defaultnick>Macbeth</defaultnick>
</exodus>
</query>
<error code="403" type="cancel">
<service-unavailable
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>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):</p>
<example caption='User Attempts to Get Data Without Specifying Child Element/Namespace'><![CDATA[
CLIENT:
<iq type="set" id="1004">
<query xmlns="jabber:iq:private"/>
</iq>
SERVER:
<iq type="error" iq="1004">
<query xmlns="jabber:iq:private"/>
<error code="400" type="modify">
<not-acceptable
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>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.</p>
<example caption='User Attempts to Get or Set Data in a Reserved Namespace'><![CDATA[
CLIENT:
<iq type="set" id="1005">
<query xmlns="jabber:iq:private">
<vCard xmlns="vcard-temp">
<FN>Hamlet</FN>
</vCard>
</query>
</iq>
SERVER (optional error):
<iq type="error" iq="1005">
<query xmlns="jabber:iq:private">
<vCard xmlns="vcard-temp">
<FN>Hamlet</FN>
</vCard>
</query>
<error code="406" type="modify">
<not-acceptable
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Error Conditions'>
<table caption='Error Conditions used by jabber:iq:private'>
<tr><th>Condition</th><th>Description</th></tr>
<tr><td>Bad Format</td><td>The IQ get does not contain a child element.</td></tr>
<tr><td>Forbidden</td><td>The IQ get or set is sent to a JID other than that of the sender.</td></tr>
<tr><td>Not Acceptable</td><td>The IQ get or set is qualified by a reserved namespace.</td></tr>
</table>
</section1>
<section1 topic='Security Considerations'>
<p>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.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<p>No action on the part of the &REGISTRAR; is necessary as a result of this JEP, since 'jabber:iq:private' is already a registered namespace.</p>
</section1>
<section1 topic='XML Schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:iq:private'
xmlns='jabber:iq:private'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0049: http://www.jabber.org/jeps/jep-0049.html
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:sequence minOccurs='0'>
<xs:any namespace='##other'/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</jep>

983
xep-0050.xml Normal file
View File

@ -0,0 +1,983 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Ad-Hoc Commands</title>
<abstract>This JEP defines protocol for reporting and executing ad-hoc, human-oriented commands in Jabber/XMPP.</abstract>
&LEGALNOTICE;
<number>0050</number>
<status>Draft</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec dep='SHOULD'>JEP-0004</spec>
<spec>JEP-0030</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>commands</shortname>
<schemaloc>
<url>http://jabber.org/protocol/commands/commands.xsd</url>
</schemaloc>
&linuxwolf;
<revision>
<version>1.2</version>
<date>2005-06-30</date>
<initials>psa</initials>
<remark>Corrected typos and other small errors.</remark>
</revision>
<revision>
<version>1.1.1</version>
<date>2004-01-02</date>
<initials>lw</initials>
<remark>Cleaned up errors in schema; added more clarifications about actions</remark>
</revision>
<revision>
<version>1.1</version>
<date>2003-12-30</date>
<initials>lw</initials>
<remark>More strict usage of the terms "requester" and "responder"; added explicit flow-control information; cleaned up i18n and l10n based on IETF efforts</remark>
</revision>
<revision>
<version>1.0</version>
<date>2003-05-19</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
</revision>
<revision>
<version>0.13</version>
<date>2003-04-28</date>
<initials>lw</initials>
<remark>More clarity on security; added notes about i18n and l10n; included xml:lang in XML-Schema.</remark>
</revision>
<revision>
<version>0.12</version>
<date>2003-04-22</date>
<initials>lw</initials>
<remark>Fixed typos; removed references to &PRESENCE;; added more security condiderations; added notes about &lt;command/&gt; child precedence.</remark>
</revision>
<revision>
<version>0.11</version>
<date>2003-02-20</date>
<initials>lw</initials>
<remark>Created XML Schema.</remark>
</revision>
<revision>
<version>0.10</version>
<date>2003-02-20</date>
<initials>lw</initials>
<remark>Relaxed and clarified &lt;command/&gt; payload requirements; Fixed minor errors in examples.</remark>
</revision>
<revision>
<version>0.9.1</version>
<date>2003-02-12</date>
<initials>lw</initials>
<remark>Fixed disco examples to reflect specification text.</remark>
</revision>
<revision>
<version>0.9</version>
<date>2003-02-09</date>
<initials>lw</initials>
<remark>Added "Implementation Notes" section; Removed syntax requirements for disco &lt;item/&gt; "node" attributes; Added "disclaimer" with regards to "node" values; Added clarifications regarding predefined/required commands; Added clarifications for command payloads; Added clarifications for command success versus failure; Added clarifications on "sessionid"; Fixed "x:data" errors.</remark>
</revision>
<revision>
<version>0.8</version>
<date>2003-01-26</date>
<initials>lw</initials>
<remark>Fixed minor grammatical errors; Changed some MUSTs to SHOULDs.</remark>
</revision>
<revision>
<version>0.7</version>
<date>2003-01-22</date>
<initials>lw</initials>
<remark>Added disco node syntax for commands; Expanded "Jabber Registrar" section.</remark>
</revision>
<revision>
<version>0.6</version>
<date>2003-01-21</date>
<initials>lw</initials>
<remark>Consistency in the usage of the "x-commands" short name; Added "Discovering Support" usecase; made other disco usage more "disco-like".</remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-01-18</date>
<initials>lw</initials>
<remark>Fixed minor errors; Removed "complete" action value from &lt;command/&gt;; Removed &lt;list/&gt; in favor of disco.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2002-11-05</date>
<initials>lw</initials>
<remark>Fixed minor errors with examples; Changed position of DTD to be more consistent with other JEPs by this author; Added details for "disco" support; Added section on "Security Considerations", "IANA Considerations", and "JANA Considerations".</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-10-11</date>
<initials>lw</initials>
<remark>Fixed minor errors with examples; Changed from using &lt;query/&gt; and &lt;x/&gt; to &lt;list/&gt; for command lists; Made the "cancel" use-case more explicit.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-10-10</date>
<initials>lw</initials>
<remark>Changed namespace from "jabber:x:commands" to "http://jabber.org/protocol/commands"; Changed execution to use &lt;iq/&gt; instead of any packet element; Changed execution to contain extensions; Reorganized for better clarity; Corrected spelling and grammar errors.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-10-08</date>
<initials>lw</initials>
<remark>Initial release.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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.</p>
<section2 topic='Motivation' anchor='motivation'>
<p>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.</p>
<p>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).</p>
</section2>
<section2 topic='Concepts' anchor='concepts'>
<p>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.</p>
</section2>
<section2 topic='Prerequisites' anchor='prerequisites'>
<p>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".</p>
<p>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.</p>
</section2>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Discovering Support' anchor='discover'>
<p>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 &lt;feature/&gt; with the "var" of "http://jabber.org/protocol/commands".</p>
<example caption='Disco request for information'><![CDATA[
<iq type='get'
to='responder@domain'
from='requester@domain'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption='Disco result for information'><![CDATA[
<iq type='result'
from='responder@domain'
to='requester@domain'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://jabber.org/protocol/commands'/>
...
</query>
</iq>
]]></example>
</section2>
<section2 topic='Retrieving the Command List' anchor='retrieve'>
<p>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.</p>
<p>Each command is a disco item. The node attribute of &lt;item/&gt; identifies the command, and the name attribute is the label for the command.</p>
<p>The requester retrieves the list of commands by querying for the responder's items for the node "http://jabber.org/protocol/commands":</p>
<example caption='Disco request for items'><![CDATA[
<iq type='get'
from='requester@domain'
to='responder@domain'>
<query xmlns='http://jabber.org/protocol/disco#items'
node='http://jabber.org/protocol/commands'/>
</iq>
]]></example>
<example caption='Disco result for items'><![CDATA[
<iq type='result'
to='requester@domain'
from='responder@domain'>
<query xmlns='http://jabber.org/protocol/disco#items'
node='http://jabber.org/protocol/commands'>
<item jid='responder@domain'
node='list'
name='List Service Configurations'/>
<item jid='responder@domain'
node='config'
name='Configure Service'/>
<item jid='responder@domain'
node='reset'
name='Reset Service Configuration'/>
<item jid='responder@domain'
node='start'
name='Start Service'/>
<item jid='responder@domain'
node='stop'
name='Stop Service'/>
<item jid='responder@domain'
node='restart'
name='Restart Service'/>
</query>
</iq>
]]></example>
<p>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.</p>
<p>If additional information about a command is desired, the requester queries for disco information on the command node:</p>
<example caption='Disco request for command information'><![CDATA[
<iq type='get'
from='requester@domain'
to='responder@domain'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='config'/>
</iq>
]]></example>
<example caption='Disco result for command information'><![CDATA[
<iq type='result'
to='requester@domain'
from='responder@domain'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='config'>
<identity name='Configure Service'
category='automation'
type='command-node'/>
<feature var='http://jabber.org/protocol/commands'/>
<feature var='jabber:x:data'/>
</query>
</iq>
]]></example>
<p>A responder MUST at least provide &lt;identity category='automation' type='command-node'/&gt; and &lt;feature var='http://jabber.org/protocol/commands'/&gt;, and SHOULD include &lt;feature var='jabber:x:data'/&gt;. 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.</p>
</section2>
<section2 topic='Announcing the Command List' anchor='announce'>
<p>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;:</p>
<example caption='Announcing commands (via &lt;message/&gt;)'><![CDATA[
<message from='responder@domain' to='requester@domain'>
<subject>Service Controls</subject>
<query xmlns='http://jabber.org/protocol/disco#items'
node='http://jabber.org/protocol/commands'>
<item jid='responder@domain'
node='list'
name='List Service Configurations'/>
<item jid='responder@domain'
node='config'
name='Configure Service'/>
<item jid='responder@domain'
node='reset'
name='Reset Service Configuration'/>
<item jid='responder@domain'
node='start'
name='Start Service'/>
<item jid='responder@domain'
node='stop'
name='Stop Service'/>
<item jid='responder@domain'
node='restart'
name='Restart Service'/>
</query>
</message>
]]></example>
<p>The only portion required is &lt;query xmlns='http://jabber.org/protocol/disco#items'/&gt;. Any other information (such as the &lt;subject/&gt; in the foregoing example) is OPTIONAL.</p>
</section2>
<section2 topic='Executing Commands' anchor='execute'>
<section3 topic='Simple Execution' anchor='execute-simple'>
<p>To execute a command, the requester sends an &IQ; containing the command to execute:</p>
<example caption="Execute command request"><![CDATA[
<iq type='set' to='responder@domain' id='exec1'>
<command xmlns='http://jabber.org/protocol/commands'
node='list'
action='execute'/>
</iq>
]]></example>
<p>The requester MAY include the "action='execute'", although this is implied.</p>
<p>If the command does not require any user interaction (returns results only), the responder sends a packet similar to the following:</p>
<example caption="Execute command result"><![CDATA[
<iq type='result' from='responder@domain' to='requester@domain' id='exec1'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='list:20020923T213616Z-700'
node='list'
status='completed'>
<x xmlns='jabber:x:data' type='result'>
<title>Available Services</title>
<reported>
<field var='service' label='Service'/>
<field var='runlevel-1' label='Single-User mode'/>
<field var='runlevel-2' label='Non-Networked Multi-User mode'/>
<field var='runlevel-3' label='Full Mult-User mode'/>
<field var='runlevel-5' label='X-Windows mode'/>
</reported>
<item>
<field var='service'><value>httpd</value></field>
<field var='runlevel-1'><value>off</value></field>
<field var='runlevel-2'><value>off</value></field>
<field var='runlevel-3'><value>on</value></field>
<field var='runlevel-5'><value>on</value></field>
</item>
<item>
<field var='service'><value>postgresql</value></field>
<field var='runlevel-1'><value>off</value></field>
<field var='runlevel-2'><value>off</value></field>
<field var='runlevel-3'><value>on</value></field>
<field var='runlevel-5'><value>on</value></field>
</item>
<item>
<field var='service'><value>jabberd</value></field>
<field var='runlevel-1'><value>off</value></field>
<field var='runlevel-2'><value>off</value></field>
<field var='runlevel-3'><value>on</value></field>
<field var='runlevel-5'><value>on</value></field>
</item>
</x>
</command>
</iq>
]]></example>
</section3>
<p>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.</p>
<section3 topic='Multiple Stages' anchor='execute-multiple'>
<p>If the command requires more interaction, the responder sends a result &IQ; that contains the command information and the form to be filled out:</p>
<example caption='Execute command request (stage 1)'><![CDATA[
<iq type='set' to='responder@domain' id='exec1'>
<command xmlns='http://jabber.org/protocol/commands'
node='config'
action='execute'/>
</iq>
]]></example>
<example caption='Execute command result (stage 1)'><![CDATA[
<iq type='result' from='responder@domain' to='requester@domain' id='exec1'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='config:20020923T213616Z-700'
node='config'
status='executing'>
<actions execute='next'>
<next/>
</actions>
<x xmlns='jabber:x:data' type='form'>
<title>Configure Service</title>
<instructions>
Please select the service to configure.
</instructions>
<field var='service' label='Service' type='list-single'>
<option><value>httpd</value></option>
<option><value>jabberd</value></option>
<option><value>postgresql</value></option>
</field>
</x>
</command>
</iq>
]]></example>
<p>The &lt;command/&gt; SHOULD include an &lt;actions/&gt; element, which specifies the details of what the allowed actions are for this stage of execution. Each element within &lt;action/&gt; matches a possible value for the &lt;command/&gt; 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.</p>
<p>The requester then submits the form, maintaining the command node and sessionid:</p>
<example caption='Execute command request (stage 2)'><![CDATA[
<iq type='set' to='responder@domain' id='exec2'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='config:20020923T213616Z-700'
node='config'>
<x xmlns='jabber:x:data' type='submit'>
<field var='service'>
<value>httpd</value>
</field>
</x>
</command>
</iq>
]]></example>
<p>The responder then provides the next stage's form in the result <note>Note that the second stage can be reverted to the first stage or completed (signaled by the inclusion of the &lt;prev/&gt; and &lt;complete/&gt; elements), and that the default action is to complete execution (signaled by the "execute" attribute's value of "complete").</note>:</p>
<example caption='Execute command result (stage 2)'><![CDATA[
<iq type='result' from='responder@domain' to='requester@domain' id='exec2'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='config:20020923T213616Z-700'
node='config'
status='executing'>
<actions execute='complete'>
<prev/>
<complete/>
</actions>
<x xmlns='jabber:x:data' type='form'>
<title>Configure Service</title>
<instructions>
Please select the run modes and state for 'httpd'.
</instructions>
<field var='runlevel' label='Run Modes' type='list-multi'>
<value>3</value>
<value>5</value>
<option label='Single-User'><value>1</value></option>
<option label='Non-Networked Multi-User'><value>2</value></option>
<option label='Full Multi-User'><value>3</value></option>
<option label='X-Windows'><value>5</value></option>
</field>
<field var='state' label='Run State' type='list-single'>
<value>off</value>
<option label='Active'><value>off</value></option>
<option label='Inactive'><value>on</value></option>
</field>
</x>
</command>
</iq>
]]></example>
<p>The requester then submits the second stage's form, again maintaining the node and sessionid:</p>
<example caption='Execute command request (stage 3)'><![CDATA[
<iq type='set' to='responder@domain' id='exec3'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='config:20020923T213616Z-700'
node='config'>
<x xmlns='jabber:x:data' type='submit'>
<field var='mode'>
<value>3</value>
</field>
<field var='state'>
<value>on</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Execute command result (stage 3)'><![CDATA[
<iq type='result' from='responder@domain' to='requester@domain' id='exec3'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='config:20020923T213616Z-700'
node='config'
status='completed'>
<note type='info'>Service 'httpd' has been configured.</note>
</command>
</iq>
]]></example>
<p>If the requester wishes to revert to the previous stage, it sends an &IQ; with the command's node and sessionid, and "action='prev'":</p>
<example caption='Execute command request (revert from stage 2 to stage 1)'><![CDATA[
<iq type='set' to='responder@domain' id='exec2'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='config:20020923T213616Z-700'
node='config'
action='prev'/>
</iq>
]]></example>
<p>If the responder accepts this, it responds with the previous stage's command <note>The responder MAY present "remembered" field values, but doing so is OPTIONAL.</note>:</p>
<example caption='Execute command result (revert from stage 2 to stage 1)'><![CDATA[
<iq type='result' from='responder@domain' to='requester@domain' id='exec2'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='config:20020923T213616Z-700'
node='config'
status='executing'>
<actions execute='next'>
<next/>
</actions>
<x xmlns='jabber:x:data' type='form'>
<title>Configure Service</title>
<instructions>
Please select the service to configure.
</instructions>
<field var='service' label='Service' type='list-single'>
<value>httpd</value>
<option><value>httpd</value></option>
<option><value>jabberd</value></option>
<option><value>postgresql</value></option>
</field>
</x>
</command>
</iq>
]]></example>
</section3>
<section3 topic='Canceling' anchor='cancel'>
<p>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'":</p>
<example caption='Execute command request (stage 2; canceling)'><![CDATA[
<iq type='set' to='responder@domain' id='exec3'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='config:20020923T213616Z-700'
node='config'
action='cancel'/>
</iq>
]]></example>
<p>This enables the responder to free any resources allocated during the process. The responder MUST reply with the success of the command:</p>
<example caption='Execute command result (stage 2; canceled)'><![CDATA[
<iq type='result' from='responder@domain' to='requester@domain' id='exec3'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='config:20020923T213616Z-700'
node='config'
status='canceled'/>
</iq>
]]></example>
</section3>
</section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<section2 topic='Defined/Required Command Nodes' anchor='impl-req'>
<p>All commands used in the above examples are for illustrative purposes only. There are no predefined or required commands.</p>
</section2>
<section2 topic='Command Nodes' anchor='impl-nodes'>
<p>Each command is identified by its 'node' attribute. This matches the 'node' attribute from the service discovery &lt;item/&gt; element. Service Discovery requires that all 'node' values be unique within a given JID. This JEP requires that the 'node' value used in &lt;command/&gt; exactly match the value used in the &lt;item/&gt; element. It is the responsibility of the responder implementation to ensure each command's node is unique for their JID.</p>
</section2>
<section2 topic='Session Lifetime' anchor='impl-session'>
<p>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.</p>
<p>The requester starts a new session for a command by simply sending a &lt;command/&gt; 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 &lt;command status='completed'/&gt; or the requester sends a &lt;command action='cancel'/&gt; with the provided 'sessionid' value.</p>
<p>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.</p>
<p>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 &notallowed; error (see &jep0086;).</p>
</section2>
<section2 topic='Command Actions' anchor='impl-actions'>
<p>The result for each stage (other than the last) of a command's execution SHOULD include an &lt;actions/&gt; element. The user-agent can use this information to present a more-intelligent user interface, such as a "druid" or "wizard".</p>
<p>For a user-agent, a typical interpretation of the &lt;actions/&gt; information (or lack thereof) would be the following:</p>
<ol>
<li>The action "cancel" is always allowed.</li>
<li>If there is no &lt;actions/&gt; element, the user-agent can use a single-stage dialog or view.
<ul>
<li>The action "execute" is equivalent to the action "complete".</li>
</ul>
</li>
<li>If there is an &lt;actions/&gt; element, the user-agent usually uses a multi-stage dialog or view, such as a wizard.
<ul>
<li>The action "execute" is always allowed, and is equivalent to the action "next".</li>
<li>The "prev" action is typically the "back" or "previous" button or option in a wizard. If &lt;prev/&gt; is not contained by the &lt;actions/&gt;, it is disabled.</li>
<li>The "next" action is typically the "next" button or option in a wizard. If &lt;next/&gt; is not contained by the &lt;actions/&gt;, it is disabled.</li>
<li>The "complete" action is typically the "finish" or "done" button or option in a wizard. If &lt;complete/&gt; is not contained by the &lt;actions/&gt;, it is disabled.</li>
<li>If the &lt;actions/&gt; possesses the "execute" attribute, that value is the default button or option. If the &lt;actions/&gt; does not possess the "execute" attribute, there is no default button or option.</li>
</ul>
</li>
</ol>
<p>Responders SHOULD use the following guidelines when providing &lt;actions/&gt;:</p>
<ul>
<li>The "execute" attribute SHOULD NOT specify a value that does not match one of the allowed actions.</li>
</ul>
</section2>
<section2 topic='Command Payloads' anchor='impl-payloads'>
<p>On its own, the &lt;command/&gt; 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 &lt;note/&gt; elements. Any namespaced elements can be used within a &lt;command/&gt;. The only limitations are that the elements not require certain parent elements (such as &IQ;), or specifically allow for &lt;command/&gt; qualified by the "http://jabber.org/protocol/commands" namespace as a possible parent element.</p>
<p>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).</p>
<p>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).</p>
<section3 topic='Use of Data Forms' anchor='impl-forms'>
<p>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 &lt;x type='cancel'/&gt; to be &lt;x type='submit'/&gt;.</p>
</section3>
</section2>
<section2 topic='Commands Successful/Failed' anchor='impl-commands'>
<p>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 &lt;note type='error'/&gt; with the &lt;command status='completed'/&gt; it returns.</p>
</section2>
<section2 topic='Internationalization and Localization' anchor='impl-i18n'>
<p>The requester SHOULD provide its locale information using the "xml:lang" attribute on either the &IQ; (RECOMMENDED) or &lt;command/&gt; 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.</p>
<example caption='Execute command request (with language/locale)'><![CDATA[
<iq type='set' to='responder@domain' id='exec1' xml:lang='en-us'>
<command xmlns='http://jabber.org/protocol/commands'
node='list'
action='execute'/>
</iq>
]]></example>
<example caption="Execute command result (with language/locale)"><![CDATA[
<iq type='result'
from='responder@domain'
to='requester@domain'
id='exec1'
xml:lang='en-us'>
<command xmlns='http://jabber.org/protocol/commands'
sessionid='list:20020923T213616Z-700'
node='list'
status='completed'>
<x xmlns='jabber:x:data' type='result'>
<title>Available Services</title>
<reported>
<field var='service' label='Service'/>
<field var='runlevel-1' label='Single-User mode'/>
<field var='runlevel-2' label='Non-Networked Multi-User mode'/>
<field var='runlevel-3' label='Full Mult-User mode'/>
<field var='runlevel-5' label='X-Windows mode'/>
</reported>
<item>
<field var='service'><value>httpd</value></field>
<field var='runlevel-1'><value>off</value></field>
<field var='runlevel-2'><value>off</value></field>
<field var='runlevel-3'><value>on</value></field>
<field var='runlevel-5'><value>on</value></field>
</item>
<item>
<field var='service'><value>postgresql</value></field>
<field var='runlevel-1'><value>off</value></field>
<field var='runlevel-2'><value>off</value></field>
<field var='runlevel-3'><value>on</value></field>
<field var='runlevel-5'><value>on</value></field>
</item>
<item>
<field var='service'><value>jabberd</value></field>
<field var='runlevel-1'><value>off</value></field>
<field var='runlevel-2'><value>off</value></field>
<field var='runlevel-3'><value>on</value></field>
<field var='runlevel-5'><value>on</value></field>
</item>
</x>
</command>
</iq>
]]></example>
<p>Within the "http://jabber.org/protocol/commands" schema, the language/locale applies only to the human-readable character data for &lt;info/&gt; elements. It SHOULD also apply to all payload elements, appropriate to their respective specifications.</p>
<p>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 &lt;bad-request/&gt; (&lt;bad-locale/&gt;) error condition.</p>
<example caption='Execute command request (with language/locale)'><![CDATA[
<iq type='set' to='responder@domain' id='exec1' xml:lang='fr-ca'>
<command xmlns='http://jabber.org/protocol/commands'
node='list'
action='execute'/>
</iq>
]]></example>
<example caption='Execute command failed result (with language/locale)'><![CDATA[
<iq type='set' from='responder@domain' to='requester@domain/resource' id='exec1'>
<command xmlns='http://jabber.org/protocol/commands'
node='list'
action='execute'
xml:lang='fr-ca'/>
<error type='modify' code='400'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<bad-locale xmlns='http://jabber.org/protocol/commands'/>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Formal Description' anchor='desc'>
<p>The focal element in x-commands is &lt;command/&gt;. It is the element used to guide the process, and the element used to report command options.</p>
<section2 topic='&lt;command/&gt; Element' anchor='desc-command'>
<p>Each &lt;command/&gt; 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 &lt;note/&gt; 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.</p>
<p>The "node" attribute uniquely identifies the command. This attribute MUST be present.</p>
<p>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.</p>
<p>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:</p>
<table caption='Possible "status" values'>
<tr>
<th>Status</th>
<th>Description</th>
</tr>
<tr>
<td>executing</td>
<td>The command is being executed.</td>
</tr>
<tr>
<td>completed</td>
<td>The command has completed. The command session has ended.</td>
</tr>
<tr>
<td>canceled</td>
<td>The command has been canceled. The command session has ended.</td>
</tr>
</table>
<p>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:</p>
<table caption='Possible "action" values'>
<tr>
<th>Action</th>
<th>Description</th>
</tr>
<tr>
<td>execute</td>
<td>The command should be executed or continue to be executed. This is the default value.</td>
</tr>
<tr>
<td>cancel</td>
<td>The command should be canceled.</td>
</tr>
<tr>
<td>prev</td>
<td>The command should be digress to the previous stage of execution.</td>
</tr>
<tr>
<td>next</td>
<td>The command should progress to the next stage of execution.</td>
</tr>
<tr>
<td>complete</td>
<td>The command should be completed (if possible).</td>
</tr>
</table>
<p>The "xml:lang" attribute specifies the language/locale this &lt;command/&gt; 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.</p>
<p>The children of a &lt;command/&gt; element (other than &lt;actions/&gt; and &lt;note/&gt;) 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.</p>
</section2>
<section2 topic='&lt;actions/&gt; Element' anchor='desc-actions'>
<p>The allowed actions for a particular stage of execution are provided by the &lt;actions/&gt; 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.</p>
<p>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 &lt;command/&gt;. The value of this attribute SHOULD match the local name of one of the contained child elements.</p>
<p>The child elements contained by &lt;action/&gt; specify the allowed actions. The name of each child element MUST be one of the following:</p>
<ul>
<li>prev</li>
<li>next</li>
<li>complete</li>
</ul>
</section2>
<section2 topic='&lt;note/&gt; Element' anchor='desc-note'>
<p>Notes about the current status of commands are provided by &lt;note/&gt; 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 &lt;note/&gt; should contain a user-readable text message.</p>
<p>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:</p>
<table caption='Possible "type" values'>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>info</td>
<td>The note is informational only. This is not really an exceptional condition.</td>
</tr>
<tr>
<td>warn</td>
<td>The note indicates a warning. Possibly due to illogical (yet valid) data.</td>
</tr>
<tr>
<td>error</td>
<td>The note indicates an error. The text should indicate the reason for the error.</td>
</tr>
</table>
</section2>
<section2 topic='Possible Errors' anchor='desc-errors'>
<p>To simplify the discussion on error conditions, this document uses the following mapping between namespace URIs and namespace prefixes <note>This mapping is provided solely for the purpose of simplifying this discussion.</note>:</p>
<table caption='Namespace Mappings'>
<tr>
<th>Prefix</th>
<th>URI</th>
</tr>
<tr>
<td>xmpp</td>
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
</tr>
<tr>
<td>cmd</td>
<td>http://jabber.org/protocol/commands</td>
</tr>
</table>
<p>Below are the possible errors that can occur during execution.</p>
<table caption='Command execution errors'>
<tr>
<th>Error Type</th>
<th>General Condition</th>
<th>Specific Condition</th>
<th>Description</th>
</tr>
<tr>
<td>modify</td>
<td>&lt;xmpp:bad-request/&gt;</td>
<td>&lt;cmd:malformed-action/&gt;</td>
<td>The responding JID does not understand the specified action.</td>
</tr>
<tr>
<td>modify</td>
<td>&lt;xmpp:bad-request/&gt;</td>
<td>&lt;cmd:bad-action/&gt;</td>
<td>The responding JID cannot accept the specified action.</td>
</tr>
<tr>
<td>modify</td>
<td>&lt;xmpp:bad-request/&gt;</td>
<td>&lt;cmd:bad-locale/&gt;</td>
<td>The responding JID cannot accept the specified language/locale.</td>
</tr>
<tr>
<td>modify</td>
<td>&lt;xmpp:bad-request/&gt;</td>
<td>&lt;cmd:bad-payload/&gt;</td>
<td>The responding JID cannot accept the specified payload (e.g. the data form did not provide one or more required fields).</td>
</tr>
<tr>
<td>modify</td>
<td>&lt;xmpp:bad-request/&gt;</td>
<td>&lt;cmd:bad-sessionid/&gt;</td>
<td>The responding JID cannot accept the specified sessionid.</td>
</tr>
<tr>
<td>cancel</td>
<td>&lt;xmpp:not-allowed/&gt;</td>
<td>&lt;cmd:session-expired/&gt;</td>
<td>The requesting JID specified a sessionid that is no longer active (either because it was completed, canceled, or timed out).</td>
</tr>
<tr>
<td>cancel</td>
<td>&lt;xmpp:forbidden/&gt;</td>
<td>NONE</td>
<td>The requesting JID is not allowed to execute the command.</td>
</tr>
<tr>
<td>cancel</td>
<td>&lt;xmpp:item-not-found/&gt;</td>
<td>NONE</td>
<td>The responding JID cannot find the requested command node.</td>
</tr>
<tr>
<td>cancel</td>
<td>&lt;xmpp:feature-not-implemented/&gt;</td>
<td>NONE</td>
<td>The responding JID does not support "http://jabber.org/protocol/commands".</td>
</tr>
</table>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='sec'>
<p>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.</p>
<p>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".</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; includes 'http://jabber.org/protocol/commands' in its registry of protocol namespaces.</p>
</section2>
<section2 topic='Service Discovery Identities' anchor='registrar-disco-identity'>
<p>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:</p>
<table caption='Types for Category "automation"'>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>command-list</td>
<td>The node for a list of commands; valid only for the node "http://jabber.org/protocol/commands".</td>
</tr>
<tr>
<td>command-node</td>
<td>A node for a specific command; the 'node' attribute uniquely identifies the command.</td>
</tr>
</table>
<p>The registry submission is as follows:</p>
<code><![CDATA[
<category>
<name>automation</name>
<desc>The "automation" category consists of entities and nodes that provide automated or programmed interaction.</desc>
<type>
<name>command-list</name>
<desc>The node for a list of commands; valid only for the node "http://jabber.org/protocol/commands"</desc>
<doc>JEP-0050</doc>
</type>
<type>
<name>command-node</name>
<desc>A node for a specific command; the 'node' attribute uniquely identifies the command</desc>
<doc>JEP-0050</doc>
</type>
</category>
]]></code>
</section2>
<section2 topic='Well-Known Service Discovery Nodes' anchor='registrar-disco-nodes'>
<p>The Jabber Registrar includes "http://jabber.org/protocol/commands" in its registry of well-known Service Discovery nodes.</p>
</section2>
<section2 topic='URI Query Types' anchor='registrar-querytypes'>
<p>As authorized by &jep0147;, the Jabber Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).</p>
<p>The "command" querytype is defined herein for interaction with entities that support the ad-hoc command protocol, with keys of "action" and "node".</p>
<example caption='Command Action: IRI/URI'><![CDATA[
xmpp:montague.net?command;node=stats
]]></example>
<example caption='Command Action: Resulting Stanza'><![CDATA[
<iq to='montague.net' type='set'>
<command xmlns='http://jabber.org/protocol/commands' node='stats'/>
</iq>
]]></example>
<p>The following submission registers the "command" querytype.</p>
<code><![CDATA[
<querytype>
<name>command</name>
<proto>http://jabber.org/protocol/commands</proto>
<desc>enables completion of ad-hoc commands</desc>
<doc>JEP-0050</doc>
<keys>
<key>
<name>action</name>
<desc>the ad-hoc commands action type</desc>
<values>
<value>
<name>cancel</name>
<desc>a request to cancel processing of the command</desc>
</value>
<value>
<name>complete</name>
<desc>a request to complete processing of the command</desc>
</value>
<value>
<name>execute</name>
<desc>a request to execute the command (the default implied action)</desc>
</value>
<value>
<name>next</name>
<desc>a request to move to the next command in a series</desc>
</value>
<value>
<name>complete</name>
<desc>a request to move to the previous command in a series</desc>
</value>
</values>
</key>
<key>
<name>node</name>
<desc>the command node</desc>
</key>
</keys>
</querytype>
]]></code>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/commands'
xmlns='http://jabber.org/protocol/commands'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0050: http://www.jabber.org/jeps/jep-0050.html
</xs:documentation>
</xs:annotation>
<xs:element name='command'>
<xs:complexType>
<xs:choice>
<xs:element ref='actions' minOccurs='0'/>
<xs:element ref='note' minOccurs='0' maxOccurs='unbounded'/>
<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
</xs:choice>
<xs:attribute name='action' use='optional'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='cancel'/>
<xs:enumeration value='complete'/>
<xs:enumeration value='execute'/>
<xs:enumeration value='next'/>
<xs:enumeration value='prev'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name='node' type='xs:string' use='required'/>
<xs:attribute name='sessionid' type='xs:string' use='optional'/>
<xs:attribute name='status' use='optional'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='canceled'/>
<xs:enumeration value='completed'/>
<xs:enumeration value='executing'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute ref='xml:lang' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='actions'>
<xs:complexType>
<xs:sequence>
<xs:element name='prev' type='empty' minOccurs='0'/>
<xs:element name='next' type='empty' minOccurs='0'/>
<xs:element name='complete' type='empty' minOccurs='0'/>
</xs:sequence>
<xs:attribute name='execute' use='optional'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='complete'/>
<xs:enumeration value='next'/>
<xs:enumeration value='prev'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name='note'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='type' use='required'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='error'/>
<xs:enumeration value='info'/>
<xs:enumeration value='warn'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='bad-action' type='empty'/>
<xs:element name='bad-locale' type='empty'/>
<xs:element name='bad-payload' type='empty'/>
<xs:element name='bad-sessionid' type='empty'/>
<xs:element name='malformed-action' type='empty'/>
<xs:element name='session-expired' type='empty'/>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
</jep>

272
xep-0051.xml Normal file
View File

@ -0,0 +1,272 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Redirect and Connection Transfer</title>
<abstract>This document describes redirection of Jabber queries, and a method to replace the current (non standard) use of 302 to redirect connections.</abstract>
<legal>This document has been placed in the public domain.</legal>
<number>0051</number>
<status>Deferred</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<author>
<firstname>Klaus</firstname>
<surname>Wolf</surname>
<email>wolf@bluehands.de</email>
<jid>klaus@jabber.bluehands.de</jid>
</author>
<author>
<firstname>Richard</firstname>
<surname>Dobson</surname>
<email>richard@dobson-i.net</email>
<jid>richard@dobson-i.net</jid>
</author>
<revision>
<version>0.1</version>
<date>2002-10-08</date>
<initials>psa</initials>
<remark>Initial release as a JEP.</remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2002-09-14</date>
<initials>rd</initials>
<remark>Added the server transfer section.</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2002-07-31</date>
<initials>hw</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>
To be written.
</p>
</section1>
<section1 topic='IQ Redirect'>
<section2 topic='Introduction'>
<p>
This document describes a general request redirection mechanism for Jabber queries.
</p>
<p>
There are cases where only the receiver of a query, e.g. the receiver of &lt;iq type='get'/&gt; 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.
</p>
<p>
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.
</p>
<p>
For security reasons the redirection mechanism is only valid for &lt;iq type='get'/&gt; packets.
</p>
</section2>
<section2 topic='Scenario'>
<p>
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.
</p>
</section2>
<section2 topic='Redirection Message'>
<p>
The meaning of &lt;iq/&gt; queries is specified by multiple parameters, i.e. JID, &lt;query/&gt; 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.
</p>
<p>
The redirection query is identified by the "type" attribute and by the code of an embedded &lt;error/&gt; tag. The code is "302". The redirection is meant to be temporary, not permanent.
</p>
<p>
The original query is returned as a child of the &lt;iq type='error'/&gt;.</p>
<p>
The redirected query sent from the server back to the client is embedded into the &lt;error/&gt; tag.
</p>
<p>
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.
</p>
<p>
The must not redirect any query other than &lt;iq type='get'/&gt;.
</p>
<p>
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. </p>
</section2>
<section2 topic='Examples'>
<example caption='The original query which will be redirected'>
&lt;iq type='get' from='jid-A' to='jid-B'&gt;
original query
&lt;/iq&gt;
</example>
<example caption='Redirection response to original query'>
&lt;iq type='error' from='jid-B' to='jid-A'&gt;
original query
&lt;error code='302'&gt;redirection message&lt;/error&gt;
&lt;/iq&gt;
</example>
<example caption='Redirected query'>
&lt;iq type='get' from='jid-A' to='jid-C'&gt;
redirected query
&lt;/iq&gt;
</example>
<example caption=' A simple redirection which changes the destination JID'>
A: &lt;iq id='5' type='get' from='user@server-A' to='user@server-B&gt;
A: &lt;query xmlns='jabber:iq:browse'/&gt;
A: &lt;/iq&gt;
B: &lt;iq type='error' from='user@server-B' to='user@server-A'&gt;
B: &lt;query xmlns='jabber:iq:browse'/&gt;
B: &lt;error code='302'&gt;
B: &lt;iq id='5' type='get' to='user@server-C'&gt;
B: &lt;query xmlns='jabber:iq:browse'/&gt;
B: &lt;/iq&gt;
B: &lt;/error&gt;
B: &lt;/iq&gt;
A: &lt;iq id='5' type='get' from='user@server-A' to='user@server-C'&gt;
A: &lt;query xmlns='jabber:iq:browse'/&gt;
A: &lt;/iq&gt;
</example>
<example caption='A redirection which changes a client-client data request to client-storage'>
A: &lt;iq id='5' type='get' from='user@server-A' to='user@server-B/work'&gt;
A: &lt;query xmlns='jabber:iq:app-specific'/&gt;
A: &lt;/iq&gt;
B: &lt;iq type='error' from='user@server-B/work' to='user@server-A'&gt;
B: &lt;query xmlns='jabber:iq:app-specific'/&gt;
B: &lt;error code='302'&gt;
B: &lt;iq id='5' type='get' to='user@server-B'&gt;
B: &lt;query xmlns='storage:client:app-specific'/&gt;
B: &lt;/iq&gt;
B: &lt;/error&gt;
B: &lt;/iq&gt;
A: &lt;iq id='5' type='get' from='user@server-A' to='user@server-B'&gt;
A: &lt;query xmlns='storage:client:app-specific'/&gt;
A: &lt;/iq&gt;
</example>
</section2>
<section2 topic='Scope and Validity'>
<p>The client must check the redirected query. The redirected query is valid only if all three of the following conditions are met:</p>
<ol>
<li>the original query is &lt;iq type='get'/&gt;</li>
<li>the redirected query is &lt;iq type='get'/&gt;</li>
<li>the &lt;iq/&gt; envelope of the redirected query has all attributes of the original query except for the &quot;to&quot; attribute</li>
</ol>
</section2>
<section2 topic='Repeated Redirections'>
<p>
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.
</p>
<p>
Applications must not rely on more than three consecutive redirections for a single query.
</p>
</section2>
<section2 topic='Implementation Note'>
<p>
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. </p>
<p>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.</p>
<p>
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.
</p>
<p>
However, the client must check the validity before re-sending the redirected query.
</p>
</section2>
</section1>
<section1 topic='Server Transfer'>
<section2 topic='Introduction'>
<p>
This document describes a connection transfer mechanism for telling clients (or others) to reconnect to a different address.
</p>
<p>
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.
</p>
</section2>
<section2 topic='Scenarios'>
<section3 topic='Scenario 1'>
A server needs to be shutdown for maintenance by an administrator but there are other servers available in the cluster and the administrator wants to cause the least disruption possible by having the users automatically reconnect to one of the other available servers.
</section3>
<section3 topic='Scenario 2'>
Users of a Jabber cluster are hosted on particular servers, the server the user has connected to is not their server in the cluster, so the server redirects the user to connect to the correct server.
</section3>
<section3 topic='Scenario 3'>
A new server is brought online in the cluster. To reduce the load on the other servers and to balance out the load, the other servers direct some of their users to connect to the new server.
</section3>
</section2>
<section2 topic='Server Transfer Packet'>
<p>
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.
</p>
</section2>
<section2 topic='Examples'>
<example caption='Server tells client to connect to a different server in the cluster (by ip address)'>
&lt;iq type='set' from='jabber.org' to='user@jabber.org'&gt;
&lt;query xmlns='jabber:iq:srvxfr'&gt;
&lt;domain&gt;jabber.org&lt;/domain&gt;
&lt;server&gt;123.123.123.122&lt;/server&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<example caption='Server tells client to connect to a different server in the cluster (by domain name)'>
&lt;iq type='set' from='jabber.org' to='user@jabber.org'&gt;
&lt;query xmlns='jabber:iq:srvxfr'&gt;
&lt;domain&gt;jabber.org&lt;/domain&gt;
&lt;server&gt;server2.jabber.org&lt;/server&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<example caption='Server tells client to connect to a different server in the cluster (using a different port number)'>
&lt;iq type='set' from='jabber.org' to='user@jabber.org'&gt;
&lt;query xmlns='jabber:iq:srvxfr'&gt;
&lt;domain&gt;jabber.org&lt;/domain&gt;
&lt;server&gt;server3.jabber.org:6222&lt;/server&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<example caption='Server tells client to simply reconnect'>
&lt;iq type='set' from='jabber.org' to='user@jabber.org'&gt;
&lt;query xmlns='jabber:iq:srvxfr'&gt;
&lt;domain&gt;jabber.org&lt;/domain&gt;
&lt;server&gt;jabber.org&lt;/server&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
</section2>
</section1>
</jep>

387
xep-0052.xml Normal file
View File

@ -0,0 +1,387 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>File Transfer</title>
<abstract>A protocol for transferring a file between two Jabber IDs.</abstract>
&LEGALNOTICE;
<number>0052</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>XMPP Core, XMPP IM, JEP-0004, JEP-0020, JEP-0030</dependencies>
<supersedes>None</supersedes>
<supersededby>JEP-0095, JEP-0096</supersededby>
<shortname>N/A</shortname>
<author>
<firstname>Thomas</firstname>
<surname>Muldowney</surname>
<email>temas@box5.net</email>
<jid>temas@jabber.org</jid>
</author>
<author>
<firstname>Matthew</firstname>
<surname>Miller</surname>
<email>linuxwolf@outer-planes.net</email>
<jid>linuxwolf@outer-planes.net</jid>
</author>
<author>
<firstname>Justin</firstname>
<surname>Karneges</surname>
<email>justin@affinix.com</email>
<jid>justin@andbit.net</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-09-30</date>
<initials>psa</initials>
<remark>At the request of the authors, the status of this JEP has been changed to Retracted since it has been superseded by JEP-0095 and JEP-0096. This JEP will not be considered further by the Jabber Software Foundation and should not be used as a basis for implementations.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-12-03</date>
<initials>tjm</initials>
<remark>Initial version, based on original JEP-0052 revision 0.1.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>
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.
</p>
</section1>
<section1 topic='Use Cases'>
<p>
This JEP covers one use case of sending a file to another user. Future JEPs
may enhance this to include searching and offering.
</p>
<section2 topic='Send File Use Case'>
<p>Primary Flow:</p>
<ol>
<li>Determine if the receiver supports FT through disco/browse. [E1]</li>
<li>Sender sends meta-data and available methods to receiver</li>
<li>Receiver sends the accepted method to Sender and any range/offset
information. [E2],[E3]</li>
<li>Sender and Receiver establish the negotiated method[E4]</li>
<li>Sender sends data as described by method</li>
<li>After the stream closes the Receiver notifies the Sender of
completion. [E5]</li>
<li>END</li>
</ol>
<p>Errors Conditions:</p>
<ol>
<li>User does not support filetransfer. END</li>
<li>Receiver rejects send. END</li>
<li>Receiver does not have any methods shared with the sender. END</li>
<li>The stream is unable to be started. END</li>
<li>The Receiver notifies sender of an error transferring. END</li>
</ol>
</section2>
</section1>
<section1 topic='Basic Usage'>
<p>
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.
</p>
<example caption='Generic Offer'>
&lt;iq type='set' id='ft_1' to='recvr@jabber.org/Home'&gt;
&lt;file xmlns='http://www.jabber.org/protocol/filexfer'
action='offer'
id='a0'
name='myfile.txt'
size='1024'
mime-type='text/plain'&gt;
&lt;feature xmlns='http://jabber.org/protocol/feature-neg'&gt;
&lt;x xmlns='jabber:x:data'&gt;
&lt;field var='file-transfer-method' type='list-single'&gt;
&lt;option&gt;&lt;value&gt;jabber:iq:oob&lt;/value&gt;&lt;/option&gt;
&lt;/field&gt;
&lt;/x&gt;
&lt;/feature&gt;
&lt;/file&gt;
&lt;/iq&gt;
</example>
<p>
That is the basic request, a more complete requeset with range support is
shown below.
</p>
<example caption='Complete File Offer'>
&lt;iq type='set' id='ft_1' to='recvr@jabber.org/Home'&gt;
&lt;file xmlns='http://www.jabber.org/protocol/filexfer'
action='offer'
id='a0'
name='myfile.txt'
size='1024'
mime-type='text/plain'
date='20020412T00:00:00'
hash='23e4ad6b63343b33a333c334'&gt;
&lt;desc&gt;A cool file&lt;/desc&gt;
&lt;range/&gt;
&lt;feature xmlns='http://jabber.org/protocol/feature-neg'&gt;
&lt;x xmlns='jabber:x:data'&gt;
&lt;field var='file-transfer-method' type='list-single'&gt;
&lt;option&gt;&lt;value&gt;jobs&lt;/value&gt;&lt;/option&gt;
&lt;option&gt;&lt;value&gt;dtcp&lt;/value&gt;&lt;/option&gt;
&lt;option&gt;&lt;value&gt;jabber:iq:oob&lt;/value&gt;&lt;/option&gt;
&lt;option&gt;&lt;value&gt;ibb&lt;/value&gt;&lt;/option&gt;
&lt;/field&gt;
&lt;/x&gt;
&lt;/feature&gt;
&lt;/file&gt;
&lt;/iq&gt;
</example>
<p>If a receiver decides to accept an offered file they request it from the sending with an &lt;iq/&gt; 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.</p>
<example caption='Request the Offered File'>
&lt;iq type='result' id='ft_req_1' to='sender@jabber.org/res'&gt;
&lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='get'&gt;
&lt;feature xmlns='http://jabber.org/protocol/feature-neg'&gt;
&lt;x xmlns='jabber:x:data'&gt;
&lt;field var='file-transfer-method'&gt;
&lt;option&gt;&lt;value&gt;jabber:iq:oob&lt;/value&gt;&lt;/option&gt;
&lt;/field'&gt;
&lt;/x&gt;
&lt;/feature&gt;
&lt;/file&gt;
&lt;/iq&gt;
</example>
<example caption='Accept the Offered File with a Range and Offset'>
&lt;iq type='result' id='ft_req_q' to='sender@jabber.org/res'&gt;
&lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='get'&gt;
&lt;range offset='100' length='500' /&gt;
&lt;x xmlns='jabber:x:data'&gt;
&lt;field var='file-transfer-method'&gt;
&lt;option&gt;&lt;value&gt;jobs&lt;/value&gt;&lt;/option&gt;
&lt;/field&gt;
&lt;/x&gt;
&lt;/feature&gt;
&lt;/file&gt;
&lt;/iq&gt;
</example>
<p>
If the receiver decides to not accept the file they SHOULD send back an
error 403 to the sender.
</p>
<example caption='Declining the Offered File'>
&lt;iq type='error' id='ft_1' to='sender@jabber.org/res'&gt;
&lt;error code='403'&gt;Offer Declined&lt;/error&gt;
&lt;/iq&gt;
</example>
<p>
If the receiver does not support any of the offered stream methods they
SHOULD send back an error 406 to the sender.
</p>
<example caption='No Acceptable Methods'>
&lt;iq type='error' id='ft_1' to='sender@jabber.org/res'&gt;
&lt;error code='406'&gt;No Acceptable Methods&lt;/error&gt;
&lt;/iq&gt;
</example>
<p>
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.
</p>
<example caption='Starting an iq:oob transfer'>
&lt;iq type='set' id='ft_oob_1' to='recvr@jabber.org/Home'&gt;
&lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='start'/&gt;
&lt;query xmlns='jabber:iq:oob'&gt;
&lt;url&gt;http://www.jabber.org/file.txt&lt;/url&gt;
&lt;desc&gt;Here is the file&lt;/desc&gt;
&lt;/query&gt;
&lt;/iq&gt;
</example>
<p>
If the receiver is unable to start the negotiated stream for any reason they
should send an &lt;error/&gt; with a 502 code to the sender.
</p>
<example caption='Unable to Start Stream'>
&lt;iq type='error' id='ft_oob_e_1' to='sender@jabber.org/res'&gt;
&lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='error'/&gt;
&lt;error code='502'&gt;Unable to Start Stream&lt;/error&gt;
&lt;/iq&gt;
</example>
<p>
Once the data has been transferred the receiver SHOULD send the sender a
notification that the transfer completed. This is done by sending an
&lt;iq/&gt; type set with the file id and a completed action.
</p>
<example caption='Completed Transfer Notification'>
&lt;iq type='set' id='ft_c_1' to='sender@jabber.org/res'&gt;
&lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='complete' /&gt;
&lt;/iq&gt;
</example>
<p>
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.
</p>
<example caption='Failed Transfer Error'>
&lt;iq type='error' id='ft_1' to='sender@jabber.org/res'&gt;
&lt;error code='500'&gt;File Transfer Failed&lt;/error&gt;
&lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='error'/&gt;
&lt;/iq&gt;
</example>
</section1>
<section1 topic='Stream Relation'>
<p>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 &lt;file/&gt; with an action of start and the correct id. The &lt;file/&gt; 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.</p>
<section2 topic='"iq:oob" Relation'>
<p>For an "iq:oob" transfer to be related to it's meta-data, a &lt;file/&gt; is transported along side the &lt;query/&gt;. The id used on the &lt;file/&gt; is the id for the meta-data of the actual data that is being sent. The action on the &lt;file/&gt; is "start". An example of this can be found in the Basic Usage section.</p>
</section2>
</section1>
<section1 topic='Formal Description'>
<section2 topic='DTD'>
<code><![CDATA[
<!ELEMENT file ( ( desc )? | ( range )? | ( PCDATA )* ) >
<!ELEMENT desc ( #PCDATA )* >
<!ELEMENT range EMPTY >
<!ATTLIST file
id CDATA #REQUIRED
action "offer" | "get" | "complete" | "start" | "error" #IMPLIED "offer"
name CDATA #OPTIONAL
size CDATA #OPTIONAL >
mime-type CDATA #OPTIONAL
date CDATA #OPTIONAL
hash CDATA #OPTIONAL
<!ATTLIST range
length CDATA #OPTIONAL
offset CDATA #OPTIONAL >
]]></code>
</section2>
<section2 topic='&lt;file/&gt; Element'>
<p>The &lt;file/&gt; 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 &lt;desc/&gt;, a &lt;range/&gt;, and zero or more &lt;feature xmlns='jabber:iq:negotiate'/&gt;<note>JEP-0020: "Feature Negotiation" -- <link url='http://www.jabber.org/jeps/jep-0020.html'>http://www.jabber.org/jeps/jep-0020.html</link></note> elements.</p>
<p>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.</p>
<p>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:</p>
<table caption='Possible "action" values'>
<tr>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>complete</td>
<td>The file transfer is complete.</td>
</tr>
<tr>
<td>get</td>
<td>The file transfer should start.</td>
</tr>
<tr>
<td>offer</td>
<td>The file transfer is offered (meta-data MUST be present)</td>
</tr>
<tr>
<td>start</td>
<td>The file transfer is starting.</td>
</tr>
<tr>
<td>error</td>
<td>The file transfer has failed. The outlying error tag has more
information.
</td>
</tr>
</table>
<p>The "name" attribute specifies the file name. This attribute MUST be present if the action is "offer", otherwise it SHOULD NOT be present.</p>
<p>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.</p>
<p>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<note>RFC 2046: "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types" -- <link url='http://www.ietf.org/rfc/rfc2046.txt'>http://www.ietf.org/rfc/rfc2046.txt</link></note>.</p>
<p>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<note>ISO 8601: "[Summary of the] International Standard Date and Time Notation" -- <link url='http://www.cl.cam.ac.uk/~mgk25/iso-time.html'>http://www.cl.cam.ac.uk/~mgk25/iso-time.html</link></note>.</p>
<p>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.</p>
</section2>
<section2 topic='&lt;desc/&gt; Element'>
<p>The &lt;desc/&gt; element contains a human-readable description of the file. This element has no attributes, and contains character data content.</p>
</section2>
<section2 topic='&lt;range/&gt; Element'>
<p>The &lt;range/&gt; 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.</p>
<p>The "length" attribute defines the range length, in bytes. This attribute MUST be present if the containing &lt;file/&gt; 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.</p>
<p>The "offset" attribute defines the range offset, in bytes. This attribute MAY be present if the containing &lt;file/&gt; 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).</p>
</section2>
<section2 topic='Error Descriptions'>
<p>
There are three main error conditions in file transfer. Following are the
conditions, error codes and descriptions:
<ul>
<li>
<em>Declining Transfer (403)</em>: During the meta-data negotiation
the receiver may decline the transfer by sending the 403 error. The
&lt;error/&gt; CDATA MAY contain a descriptive reason why, but is not
necessary.
</li>
<li>
<em>No Available Methods (406)</em>: When the sender presents the
available stream methods, and the receiver can not use any of them,
they send a 406 error. The &lt;error/&gt; CDATA is not important.
</li>
<li>
<em>Transfer Failed (500)</em>: 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 &lt;error/&gt; CDATA MAY contain
information about the failure.
</li>
<li>
<em>Unable to Start Stream (502)</em>: When the receiver is unable to
start the negotiated stream method they send a 502 error to the
sender. The &lt;error/&gt; CDATA is not important.
</li>
</ul>
</p>
</section2>
</section1>
<section1 topic='Security Considerations'>
<p>
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.
</p>
</section1>
<section1 topic='IANA Considerations'>
<p>
The mime-type attribute on &lt;file/&gt; is a valid MIME type as controlled
by the IANA.
</p>
</section1>
<section1 topic='JANA Considerations'>
<p>
The "http://jabber.org/protocol/filexfer" is the only namespace that needs
to be registered with the JANA.
</p>
</section1>
</jep>

86
xep-0053.xml Normal file
View File

@ -0,0 +1,86 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Jabber Registrar</title>
<abstract>This JEP defines the roles and processes of the Jabber Registrar within the Jabber Software Foundation.</abstract>
&LEGALNOTICE;
<number>0053</number>
<status>Active</status>
<type>Procedural</type>
<jig>None</jig>
<approver>Board</approver>
<dependencies/>
<supersedes/>
<supersededby/>
<shortname>N/A</shortname>
&stpeter;
<revision>
<version>1.1</version>
<date>2004-05-20</date>
<initials>psa</initials>
<remark>Updated to reflect experience.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2003-03-20</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Active.</remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-01-21</date>
<initials>psa</initials>
<remark>Changed name to Jabber Registrar in response to feedback from the JSF Board of Directors.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-01-20</date>
<initials>psa</initials>
<remark>Added reference to jana@jabber.org mailing list.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-11-22</date>
<initials>psa</initials>
<remark>Simplified to reflect discussion in the Jabber Council; in particular, reserved JANA functions to the JEP Editor until there is a perceived need for a more formal governing body.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-10-27</date>
<initials>psa</initials>
<remark>Clarified JANA composition, panel member requirements, and JANA process.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-10-24</date>
<initials>psa</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction and Purpose'>
<p>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;.</p>
</section1>
<section1 topic='Composition'>
<p>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.</p>
</section1>
<section1 topic='Process'>
<p>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.</p>
<p>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.</p>
<p>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 &lt;registrar@jabber.org&gt;. 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.</p>
<p>The Jabber Registrar shall maintain registries of assigned namespaces and parameters at &lt;<link url="http://www.jabber.org/registrar/">http://www.jabber.org/registrar/</link>&gt; and shall update those registries in a timely fashion. Changes to JSF registries shall be announced on the Standards-JIG mailing list.</p>
</section1>
<section1 topic='Security Considerations'>
<p>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.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>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.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<p>This entire document defines the processes and procedures of the Jabber Registrar.</p>
</section1>
</jep>

524
xep-0054.xml Normal file
View File

@ -0,0 +1,524 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>vcard-temp</title>
<abstract>This JEP provides canonical documentation of the vCard-XML format currently in use within the Jabber community.</abstract>
&LEGALNOTICE;
<number>0054</number>
<status>Active</status>
<type>Historical</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>vcard-temp</shortname>
&stpeter;
<revision>
<version>1.1</version>
<date>2003-03-26</date>
<initials>psa</initials>
<remark>Clarified certain historical inaccuracies and added links to archived versions of Frank Dawson's Internet-Drafts.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2003-01-09</date>
<initials>psa</initials>
<remark>Updated status to Active per vote of the Jabber Council.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-11-06</date>
<initials>psa</initials>
<remark>Many small fixes; added implementation notes.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-10-31</date>
<initials>psa</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
<p>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 &lt;iq/&gt; of type "set" (storage) or "get" (retrieval) to one's Jabber server containing a &lt;vCard/&gt; child scoped by the 'vcard-temp' namespace, with the &lt;vCard/&gt; element containing the actual vCard-XML elements as defined by the vCard-XML DTD. Other users may then view one's vCard information.</p>
</section1>
<section1 topic='History'>
<p>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;.</p>
<p>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 <note>This document is archived at &lt;<link url='http://www.watersprings.org/pub/id/draft-dawson-vcard-xml-dtd-01.txt'>http://www.watersprings.org/pub/id/draft-dawson-vcard-xml-dtd-01.txt</link>&gt;.</note>. He also submitted a -02 revision on November 15, 1998 <note>This document is archived at &lt;<link url='http://www.watersprings.org/pub/id/draft-dawson-vcard-xml-dtd-02.txt'>http://www.watersprings.org/pub/id/draft-dawson-vcard-xml-dtd-02.txt</link>&gt;.</note> and a -03 revision on June 22, 1999 <note>This document is archived at &lt;<link url='http://www.watersprings.org/pub/id/draft-dawson-vcard-xml-dtd-03.txt'>http://www.watersprings.org/pub/id/draft-dawson-vcard-xml-dtd-03.txt</link>&gt;.</note>.</p>
<p>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.</p>
</section1>
<section1 topic='Use Cases'>
<section2 topic="Retrieving One's vCard">
<p>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):</p>
<example caption="Requesting One's Own vCard"><![CDATA[
<iq
from='stpeter@jabber.org/Gabber'
type='get'
id='v1'>
<vCard xmlns='vcard-temp'/>
</iq>
]]></example>
<p>The server should then return the vCard to the user:</p>
<example caption="Receiving One's Own vCard"><![CDATA[
<iq
to='stpeter@jabber.org/Gabber'
type='result'
id='v1'>
<vCard xmlns='vcard-temp'>
<FN>Peter Saint-Andre</FN>
<N>
<FAMILY>Saint-Andre</FAMILY>
<GIVEN>Peter</GIVEN>
<MIDDLE/>
</N>
<NICKNAME>stpeter</NICKNAME>
<URL>http://www.jabber.org/people/stpeter.php</URL>
<BDAY>1966-08-06</BDAY>
<ORG>
<ORGNAME>Jabber Software Foundation</ORGNAME>
<ORGUNIT/>
</ORG>
<TITLE>Executive Director</TITLE>
<ROLE>Patron Saint</ROLE>
<TEL><WORK/><VOICE/><NUMBER>303-308-3282</NUMBER></TEL>
<TEL><WORK/><FAX/><NUMBER/></TEL>
<TEL><WORK/><MSG/><NUMBER/></TEL>
<ADR>
<WORK/>
<EXTADD>Suite 600</EXTADD>
<STREET>1899 Wynkoop Street</STREET>
<LOCALITY>Denver</LOCALITY>
<REGION>CO</REGION>
<PCODE>80202</PCODE>
<CTRY>USA</CTRY>
</ADR>
<TEL><HOME/><VOICE/><NUMBER>303-555-1212</NUMBER></TEL>
<TEL><HOME/><FAX/><NUMBER/></TEL>
<TEL><HOME/><MSG/><NUMBER/></TEL>
<ADR>
<HOME/>
<EXTADD/>
<STREET/>
<LOCALITY>Denver</LOCALITY>
<REGION>CO</REGION>
<PCODE>80209</PCODE>
<CTRY>USA</CTRY>
</ADR>
<EMAIL><INTERNET/><PREF/><USERID>stpeter@jabber.org</USERID></EMAIL>
<JABBERID>stpeter@jabber.org</JABBERID>
<DESC>
More information about me is located on my
personal website: http://www.saint-andre.com/
</DESC>
</vCard>
</iq>
]]></example>
</section2>
<section2 topic="Updating One's vCard">
<p>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.</p>
<p>If a user attempts to perform an IQ set on another user's vCard, the server MUST return a 403 "Forbidden" error.</p>
</section2>
<section2 topic="Viewing Another User's vCard">
<p>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.</p>
<example caption="Requesting Another User's vCard"><![CDATA[
<iq
to='jer@jabber.org'
type='get'
id='v3'>
<vCard xmlns='vcard-temp'/>
</iq>
]]></example>
<p>The server should then return the other user's vCard to the requestor:</p>
<example caption="Receiving Another User's vCard"><![CDATA[
<iq
from='jer@jabber.org'
to='stpeter@jabber.org/home'
type='result'
id='v3'>
<vCard xmlns='vcard-temp'>
<FN>JeremieMiller</FN>
<N>
<GIVEN>Jeremie</GIVEN>
<FAMILY>Miller</FAMILY>
<MIDDLE/>
</N>
<NICKNAME>jer</NICKNAME>
<EMAIL><INTERNET/><PREF/><USERID>jeremie@jabber.org</USERID></EMAIL>
<JABBERID>jer@jabber.org</JABBERID>
</vCard>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Security Considerations'>
<p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-protocol'>
<p>The &REGISTRAR; includes the 'vcard-temp' namespace in its registry of official namespaces (see &NAMESPACES;).</p>
</section2>
<section2 topic='URI Query Types' anchor='registrar-querytypes'>
<p>As authorized by &jep0147;, the Jabber Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).</p>
<p>The "vcard" querytype is registered as a vCard-related action.</p>
<example caption='vCard Action: IRI/URI'><![CDATA[
xmpp:romeo@montague.net?vcard
]]></example>
<example caption='vCard Action: Resulting Stanza'><![CDATA[
<iq to='romeo@montague.net' type='get'>
<vCard xmlns='vcard-temp'/>
</iq>
]]></example>
<p>The following submission registers the "vcard" querytype.</p>
<code><![CDATA[
<querytype>
<name>vcard</name>
<proto>vcard-temp</proto>
<desc>enables retrieval of an entity's vCard data</desc>
<doc>JEP-0054</doc>
</querytype>
]]></code>
</section2>
</section1>
<section1 topic='Implementation Notes'>
<p>Note the following:</p>
<ul>
<li>The correct capitalization of the wrapper element is &lt;vCard/&gt; (and XML element names are case-sensitive).</li>
<li>All elements within the &lt;vCard/&gt; element MUST be in ALL CAPS (even though this is at odds with draft-dawson-vcard-xml-dtd-01).</li>
<li>The country abbreviation is contained in a &lt;CTRY/&gt; element, <em>not</em> a &lt;COUNTRY/&gt; element (even though this is at odds with draft-dawson-vcard-xml-dtd-01).</li>
<li>Phone numbers MUST be contained in a &lt;NUMBER&gt; element, not included as CDATA within the &lt;TEL/&gt; element.</li>
<li>If no telephone number is included in a &lt;TEL/&gt; element, an empty &lt;NUMBER/&gt; child MUST be included.</li>
<li>Email addresses MUST be contained in a &lt;USERID&gt; element, not included as CDATA within the &lt;EMAIL/&gt; element.</li>
<li>Some Jabber implementations add a 'version' attribute to the &lt;vCard/&gt; 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 &lt;VERSION/&gt; 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".</li>
</ul>
</section1>
<section1 topic='DTD'>
<p>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.</p>
<code><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (C) The Internet Society (2000). All Rights Reserved.
This document and translations of it may be copied and
furnished to others, and derivative works that comment
on or otherwise explain it or assist in its implmentation
may be prepared, copied, published and distributed, in whole
or in part, without restriction of any kind, provided that
the above copyright notice and this paragraph are included
on all such copies and derivative works.
However, this document itself may not be modified in any
way, such as by removing the copyright notice or references
to the Internet Society or other Internet organizations,
except as needed for the purpose of developing Internet
standards in which case the procedures for copyrights
defined in the Internet Standards process MUST be followed,
or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will
not be revoked by the Internet Society or its successors or
assigns.
This document and the information contained herein is provided
on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE
USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR
ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE.
-->
<!-- ==== -->
<!-- NOTE: the following root element is not used in the
modified vcard-temp DTD published by the Jabber
project (now Jabber Software Foundation) and is
included here only for historical purposes;
implementations that comply with vcard-temp must
specify the root element as vCard, not xCard. -->
<!-- Root element and container for one
or more vCard objects -->
<!ELEMENT xCard (vCard)+>
<!-- Individual vCard container -->
<!ELEMENT vCard (
(VERSION, FN, N),
(NICKNAME?,
PHOTO?,
BDAY?,
ADR?,
LABEL?,
TEL?,
EMAIL?,
JABBERID?,
MAILER?,
TZ?,
GEO?,
TITLE?,
ROLE?,
LOGO?,
AGENT?,
ORG?,
CATEGORIES?,
NOTE?,
PRODID?,
REV?,
SORT-STRING?,
SOUND?,
UID?,
URL?,
CLASS?,
KEY?,
DESC?
)*)>
<!-- vCard specification version property.
This MUST be 2.0, if the document conforms to RFC 2426. -->
<!ELEMENT VERSION (#PCDATA)>
<!-- Formatted or display name property. -->
<!ELEMENT FN (#PCDATA)>
<!-- Structured name property. Name components with multiple
values must be specified as a comma separated
list of values. -->
<!ELEMENT N ( FAMILY?, GIVEN?, MIDDLE?, PREFIX?, SUFFIX?)>
<!ELEMENT FAMILY (#PCDATA)>
<!ELEMENT GIVEN (#PCDATA)>
<!ELEMENT MIDDLE (#PCDATA)>
<!ELEMENT PREFIX (#PCDATA)>
<!ELEMENT SUFFIX (#PCDATA)>
<!-- Nickname property. Multiple nicknames must be
specified as a comma separated list value. -->
<!ELEMENT NICKNAME (#PCDATA)>
<!-- Photograph property. Value is either a BASE64 encoded
binary value or a URI to the external content. -->
<!ELEMENT PHOTO ((TYPE, BINVAL) | EXTVAL)>
<!-- Birthday property. Value must be an ISO 8601 formatted
date or date/time value. -->
<!ELEMENT BDAY (#PCDATA)>
<!-- Structured address property. Address components with
multiple values must be specified as a comma separated list
of values. -->
<!ELEMENT ADR (
HOME?,
WORK?,
POSTAL?,
PARCEL?,
(DOM | INTL)?,
PREF?,
POBOX?,
EXTADD?,
STREET?,
LOCALITY?,
REGION?,
PCODE?,
CTRY?
)>
<!ELEMENT POBOX (#PCDATA)>
<!ELEMENT EXTADD (#PCDATA)>
<!ELEMENT STREET (#PCDATA)>
<!ELEMENT LOCALITY (#PCDATA)>
<!ELEMENT REGION (#PCDATA)>
<!ELEMENT PCODE (#PCDATA)>
<!ELEMENT CTRY (#PCDATA)>
<!-- Address label property. -->
<!ELEMENT LABEL (
HOME?,
WORK?,
POSTAL?,
PARCEL?,
(DOM | INTL)?,
PREF?,
LINE+
)>
<!-- Individual label lines. -->
<!ELEMENT LINE (#PCDATA)>
<!-- Telephone number property. -->
<!ELEMENT TEL (
HOME?,
WORK?,
VOICE?,
FAX?,
PAGER?,
MSG?,
CELL?,
VIDEO?,
BBS?,
MODEM?,
ISDN?,
PCS?,
PREF?,
NUMBER
)>
<!-- Phone number value. -->
<!ELEMENT NUMBER (#PCDATA)>
<!-- Email address property. Default type is INTERNET. -->
<!ELEMENT EMAIL (
HOME?,
WORK?,
INTERNET?,
PREF?,
X400?,
USERID
)>
<!ELEMENT USERID (#PCDATA)>
<!-- NOTE: the following element was added by the Jabber
project (now Jabber Software Foundation) to
handle Jabber IDs; the value must be in the
form of user@host -->
<!ELEMENT JABBERID (#PCDATA)>
<!-- Mailer (e.g., Mail User Agent Type) property. -->
<!ELEMENT MAILER (#PCDATA)>
<!-- Time zone's Standard Time UTC offset. Value must be an
ISO 8601 formatted UTC offset. -->
<!ELEMENT TZ (#PCDATA)>
<!-- Geographical position. Values are the decimal degress of
LATitude and LONgitude. The value should be specified to
six decimal places.-->
<!ELEMENT GEO (LAT, LON)>
<!-- Latitude value. -->
<!ELEMENT LAT (#PCDATA)>
<!-- Longitude value. -->
<!ELEMENT LON (#PCDATA)>
<!-- Title property. -->
<!ELEMENT TITLE (#PCDATA)>
<!-- Role property. -->
<!ELEMENT ROLE (#PCDATA)>
<!-- Organization logo property. -->
<!ELEMENT LOGO ((TYPE, BINVAL) | EXTVAL)>
<!-- Administrative agent property. -->
<!ELEMENT AGENT (vCard | EXTVAL)>
<!-- Organizational name and units property. -->
<!ELEMENT ORG (ORGNAME, ORGUNIT*)>
<!ELEMENT ORGNAME (#PCDATA)>
<!ELEMENT ORGUNIT (#PCDATA)>
<!-- Application specific categories property. -->
<!ELEMENT CATEGORIES (KEYWORD+)>
<!ELEMENT KEYWORD (#PCDATA)>
<!-- Commentary note property. -->
<!ELEMENT NOTE (#PCDATA)>
<!-- Identifier of product that generated the vCard property. -->
<!ELEMENT PRODID (#PCDATA)>
<!-- Last revised property. The value must be an
ISO 8601 formatted UTC date/time. -->
<!ELEMENT REV (#PCDATA)>
<!-- Sort string property. -->
<!ELEMENT SORT-STRING (#PCDATA)>
<!-- Formatted name pronunciation property. The value is
either a textual phonetic pronunciation, a BASE64
encoded binary digital audio pronunciation or a URI to
an external binary digital audio pronunciation.-->
<!ELEMENT SOUND (PHONETIC | BINVAL | EXTVAL)>
<!-- Textual phonetic pronunciation. -->
<!ELEMENT PHONETIC (#PCDATA)>
<!-- Unique identifier property. -->
<!ELEMENT UID (#PCDATA)>
<!-- Directory URL property. -->
<!ELEMENT URL (#PCDATA)>
<!-- NOTE: the following element was added by the Jabber
project (now Jabber Software Foundation) to
handle free-form descriptive text. -->
<!ELEMENT DESC (#PCDATA)>
<!-- Privacy classification property. -->
<!ELEMENT CLASS (PUBLIC | PRIVATE | CONFIDENTIAL)>
<!ELEMENT PUBLIC EMPTY>
<!ELEMENT PRIVATE EMPTY>
<!ELEMENT CONFIDENTIAL EMPTY>
<!-- Authentication credential or encryption key property. -->
<!ELEMENT KEY (TYPE?, CRED)>
<!ELEMENT CRED (#PCDATA)>
<!-- ==== -->
<!-- Common elements. -->
<!-- Addressing type indicators. -->
<!ELEMENT HOME EMPTY>
<!ELEMENT WORK EMPTY>
<!ELEMENT POSTAL EMPTY>
<!ELEMENT PARCEL EMPTY>
<!ELEMENT DOM EMPTY>
<!ELEMENT INTL EMPTY>
<!ELEMENT PREF EMPTY>
<!ELEMENT VOICE EMPTY>
<!ELEMENT FAX EMPTY>
<!ELEMENT PAGER EMPTY>
<!ELEMENT MSG EMPTY>
<!ELEMENT CELL EMPTY>
<!ELEMENT VIDEO EMPTY>
<!ELEMENT BBS EMPTY>
<!ELEMENT MODEM EMPTY>
<!ELEMENT ISDN EMPTY>
<!ELEMENT PCS EMPTY>
<!ELEMENT INTERNET EMPTY>
<!ELEMENT X400 EMPTY>
<!-- Format type parameter. -->
<!ELEMENT TYPE (#PCDATA)>
<!-- Base64 encoded binary value. -->
<!ELEMENT BINVAL (#PCDATA)>
<!-- URI to external binary value -->
<!ELEMENT EXTVAL (#PCDATA)>
<!-- ==== -->
]]></code>
</section1>
</jep>

327
xep-0055.xml Normal file
View File

@ -0,0 +1,327 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Jabber Search</title>
<abstract>This JEP provides canonical documentation of the 'jabber:iq:search' namespace currently in use within the Jabber community.</abstract>
&LEGALNOTICE;
<number>0055</number>
<status>Active</status>
<type>Historical</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec dep="SHOULD">JEP-0004</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>iq-search</shortname>
<schemaloc>
<url>http://jabber.org/protocol/iq-search/iq-search.xsd</url>
</schemaloc>
&stpeter;
<revision>
<version>1.2</version>
<date>2004-03-22</date>
<initials>psa</initials>
<remark>Clarified scope (searching of any information repository, not just user directories); added search and result examples to the extensibility section.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2004-01-06</date>
<initials>psa</initials>
<remark>Added XML schema; added text regarding extensibility via Data Forms; added FORM_TYPE submission.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2003-01-09</date>
<initials>psa</initials>
<remark>Updated status to Active per vote of the Jabber Council.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-11-01</date>
<initials>psa</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic="Searching" anchor='usecases-search'>
<p>In order to search an information respository, a user first needs to discover what search fields are supported by the service:</p>
<example caption="Requesting Search Fields"><![CDATA[
<iq type='get'
from='romeo@montague.net/home'
to='characters.shakespeare.lit'
id='search1'
xml:lang='en'>
<query xmlns='jabber:iq:search'/>
</iq>
]]></example>
<p>The service MUST then return the possible search fields to the user, and MAY include instructions:</p>
<example caption="Receiving Search Fields"><![CDATA[
<iq type='result'
from='characters.shakespeare.lit'
to='romeo@montague.net/home'
id='search1'
xml:lang='en'>
<query xmlns='jabber:iq:search'>
<instructions>
Fill in one or more fields to search
for any matching Jabber users.
</instructions>
<first/>
<last/>
<nick/>
<email/>
</query>
</iq>
]]></example>
<p>The user MAY then submit a search request, specifying values for any desired fields:</p>
<example caption="Submitting a Search Request"><![CDATA[
<iq type='set'
from='romeo@montague.net/home'
to='characters.shakespeare.lit'
id='search2'
xml:lang='en'>
<query xmlns='jabber:iq:search'>
<last>Capulet</last>
</query>
</iq>
]]></example>
<p>The service SHOULD then return a list of search results that match the values provided:</p>
<example caption="Receiving Search Results"><![CDATA[
<iq type='result'
from='characters.shakespeare.lit'
to='romeo@montague.net/home'
id='search2'
xml:lang='en'>
<query xmlns='jabber:iq:search'>
<item jid='juliet@capulet.com'>
<first>Juliet</first>
<last>Capulet</last>
<nick>JuliC</nick>
<email>juliet@shakespeare.lit</email>
</item>
<item jid='tybalt@shakespeare.lit'>
<first>Tybalt</first>
<last>Capulet</last>
<nick>ty</nick>
<email>tybalt@shakespeare.lit</email>
</item>
</query>
</iq>
]]></example>
<p>If there are no matching directory entries, the service MUST return an empty &lt;query/&gt; element:</p>
<example caption="Service Informs User that No Records Match"><![CDATA[
<iq type='result'
from='characters.shakespeare.lit'
to='romeo@montague.net/home'
id='search2'
xml:lang='en'>
<query xmlns='jabber:iq:search'/>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Extensibility' anchor='extensibility'>
<p>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, <strong>Data Forms</strong> SHOULD be used; a host MUST NOT add new fields to the 'jabber:iq:search' namespace. Support for extensibility via <strong>Data Forms</strong> is RECOMMENDED, but is not required for compliance with this JEP.</p>
<p>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.</p>
<example caption='Entity Requests Search Fields from Service'><![CDATA[
<iq type='get'
from='juliet@capulet.com/balcony'
to='characters.shakespeare.lit'
id='search3'
xml:lang='en'>
<query xmlns='jabber:iq:search'/>
</iq>
]]></example>
<example caption='Host Returns Search Form to Entity'><![CDATA[
<iq type='result'
from='characters.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='search3'
xml:lang='en'>
<query xmlns='jabber:iq:search'>
<instructions>
Use the enclosed form to search. If your Jabber client does not
support Data Forms, visit http://shakespeare.lit/
</instructions>
<x xmlns='jabber:x:data' type='form'>
<title>User Directory Search</title>
<instructions>
Please provide the following information
to search for Shakespearean characters.
</instructions>
<field type='hidden'
var='FORM_TYPE'>
<value>jabber:iq:search</value>
</field>
<field type='text-single'
label='Given Name'
var='first'/>
<field type='text-single'
label='Family Name'
var='last'/>
<field type='list-single'
label='Gender'
var='gender'>
<option label='Male'><value>male</value></option>
<option label='Female'><value>female</value></option>
</field>
</x>
</query>
</iq>
]]></example>
<example caption='Entity Submits Search Form'><![CDATA[
<iq type='set'
from='juliet@capulet.com/balcony'
to='characters.shakespeare.lit'
id='search4'
xml:lang='en'>
<query xmlns='jabber:iq:search'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:iq:search</value>
</field>
<field var='gender'>
<value>male</value>
</field>
</x>
</query>
</iq>
]]></example>
<example caption='Service Returns Search Results'><![CDATA[
<iq type='result'
from='characters.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='search4'
xml:lang='en'>
<query xmlns='jabber:iq:search'>
<x xmlns='jabber:x:data' type='result'>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:iq:search</value>
</field>
<reported>
<field var='first' label='First Name'/>
<field var='last' label='Last Name'/>
<field var='jid' label='Jabber ID'/>
<field var='gender' label='Gender'/>
</reported>
<item>
<field var='first'><value>Benvolio</value></field>
<field var='last'><value>Montague</value></field>
<field var='jid'><value>benvolio@montague.net</value></field>
<field var='gender'><value>male</value></field>
</item>
<item>
<field var='first'><value>Romeo</value></field>
<field var='last'><value>Montague</value></field>
<field var='jid'><value>romeo@montague.net</value></field>
<field var='gender'><value>male</value></field>
</item>
.
.
.
</x>
</query>
</iq>
]]></example>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<p>The &REGISTRAR; shall include the following information in its registries.</p>
<section2 topic='Protocol Namespaces' anchor='registrar-namespaces'>
<p>The Jabber Registrar includes the 'jabber:iq:search' namespace in its registry of protocol namespaces.</p>
</section2>
<section2 topic='Field Standardization' anchor='registrar-formtypes'>
<p>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.</p>
<code caption='Registry Submission'><![CDATA[
<form_type>
<name>jabber:iq:search</name>
<doc>JEP-0055</doc>
<desc>Forms enabling directory searches.</desc>
<field
var='first'
type='text-single'
label='First Name'/>
<field
var='last'
type='text-single'
label='Family Name'/>
<field
var='nick'
type='text-single'
label='Nickname'/>
<field
var='email'
type='text-single'
label='Email Address'/>
</form_type>
]]></code>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:iq:search'
xmlns='jabber:iq:search'
elementFormDefault='qualified'>
<xs:import namespace='jabber:x:data'
schemaLocation='http://jabber.org/protocol/x-data/x-data.xsd'/>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0055: http://www.jabber.org/jeps/jep-0055.html
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:choice>
<xs:all xmlns:xdata='jabber:x:data'>
<xs:element name='instructions' type='xs:string'/>
<xs:element name='first' type='xs:string'/>
<xs:element name='last' type='xs:string'/>
<xs:element name='nick' type='xs:string'/>
<xs:element name='email' type='xs:string'/>
<xs:element ref='xdata:x' minOccurs='0'/>
</xs:all>
<xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name='item'>
<xs:complexType>
<xs:all>
<xs:element name='first' type='xs:string'/>
<xs:element name='last' type='xs:string'/>
<xs:element name='nick' type='xs:string'/>
<xs:element name='email' type='xs:string'/>
</xs:all>
<xs:attribute name='jid' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</jep>

181
xep-0056.xml Normal file
View File

@ -0,0 +1,181 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Business Data Interchange</title>
<abstract>This JEP defines a way to transmit ebXML messages, ANSI X.11, EDIFACT/UN, and SAP iDoc over Jabber/XMPP.</abstract>
&LEGALNOTICE;
<number>0056</number>
<status>Deferred</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>None</dependencies>
<author>
<firstname>Ulrich</firstname>
<surname>Staudinger</surname>
<email>chicago5@gmx.de</email>
<jid>uls@jabber.org</jid>
</author>
<revision>
<version>0.3</version>
<date>2002-11-18</date>
<initials>uls</initials>
<remark>added SAP iDoc, EDIFACT, changed from Base64 to XML aware, minor changes in wording</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-11-06</date>
<initials>uls</initials>
<remark>Changed namespace, improved structure, added ANSI X.12</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-11-06</date>
<initials>uls</initials>
<remark>Initial release.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>
ANSI X.12, EDIFACT/UN and ebXML are all standards. This JEP describes a fundamental approach to transmit messages that conform to these standards.
</p>
</section1>
<section1 topic='Transmitting ebXML via XMPP'>
<section2 topic='Introduction to ebXML'>
<p>EbXML <note><link url='http://www.ebxml.org'>http://www.ebxml.org</link></note>, a subset of XML that is defined through OASIS.org, is quickly becoming a de-facto standard for electronic, unified, inter and intra business process communication and for business process specification. The direct adjacency to UN/CEFACT EDIFACT, especially object-oriented EDI, make the widespread use of ebXML for automatic business transaction negotiation, process definition, etc. quite likely.
</p>
</section2>
<section2 topic='Protocol'>
<p>
ebXML Messages SHALL be transmitted within Jabber IQ chunks. The value of the 'type' attribute SHALL be 'set' and the chunk SHALL contain a &lt;query/&gt; 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.
</p>
<example caption='ebXML Envelope'><![CDATA[
<iq from='a@b.c' to='d@e.f' type='set' id='some'>
<query xmlns='http://jabber.org/protocol/ebxml'>
[data]
</query>
</iq>
]]></example>
<p>
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.
</p>
<p>
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' <note>Walsh. 2002. <em>ebXML: The Technical Specifications</em>; p. 69</note>, only one ebXML message can be (at the moment) transmitted at a time in one message. However, the ebXML Message MAY contain payload in it's own payload envelope.
</p>
<p>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.
</p>
</section2>
<section2 topic='Examples'>
<example caption='ebXML Query from a client to a Gateway'><![CDATA[
<iq to='ebxml.gateway.com' type='set' id='f0a0f0'>
<query xmlns='http://jabber.org/protocol/ebxml'>
<RegistryEntryQuery>
<RegistryEntryFilter>
objectType EQUAL "CPP" AND status EQUAL "Approved"
</RegistryEntryFilter>
<HasClassificationBranch>
<ClassificationNodeFilter>
id STARTSWITH "urn:urn:spsc:321118'
</ClassificationNodeFilter>
</HasClassificationBranch>
</RegistryEntryQuery>
</query>
</iq>
]]></example>
<p>
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'.
</p>
<example caption='ebXML component OK from component to client'><![CDATA[
<iq to='client@server.com' from='ebxml.gateway.com' type='result' id='f0a0f0'>
<query xmlns='http://jabber.org/protocol/ebxml'/>
</iq>
]]></example>
<p>
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.
</p>
</section2>
</section1>
<section1 topic='Transmitting ANSI X.12 via XMPP'>
<section2 topic='Introduction'>
<p>ANSI X.12 is a character oriented protocol. X.12 is separated into segments. Segments are separated by an asterisk <note>Angeli, Streit, Gonfaloniere. 2000. <em>The SAP R/3 Guide to EDI and interfaces</em>; p. 133</note>.</p>
</section2>
<section2 topic='Protocol'>
<p>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.</p>
</section2>
<section2 topic='Example'>
<example><![CDATA[
<iq type='set' id='ANY' to='ANSI_X12Gate@way.com'>
<query xmlns='http://jabber.org/protocol/ansi_x.12'>
ST*850*000000101~
BEG*00*NE*123456789*991125**AC~
N1*BT***0111213~
N1*ST***5566789~
PO1*1*250*KGM*15.3*SR*EAN*MY1001~
CTT*1*2~
SE*7*000000101~
</query>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Transmitting UN/EDIFACT via XMPP'>
<section2 topic='Introduction'>
<p>
EDIFACT/UN is very similar to X.12 and differs only in the meaning of tags and in some syntactical details.
</p>
</section2>
<section2 topic='Protocol'>
<p>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.</p>
</section2>
</section1>
<section1 topic='Transmitting SAP iDoc via XMPP'>
<section2 topic='Introduction'>
SAP Systems can create IDocs as receipts of transactions. These receipts can be used within other EDI systems, or within the SAP system. Of course transmission of IDocs can take place through XMPP as well.
</section2>
<section2 topic='Protocol'>
<p>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.
</p>
</section2>
<section2 topic='Example'>
<example><![CDATA[
<iq type='set' id='ANY' from='sap_idoc_gate@way.com'>
<query xmlns='http://jabber.org/protocol/sap_idoc'>
EDI_DC0350000000000000001301230C30USDEL4111SAPI10
...
</query>
</iq>
]]></example>
</section2>
</section1>
</jep>

182
xep-0057.xml Normal file
View File

@ -0,0 +1,182 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type="text/xsl" href="../jep.xsl"?>
<jep>
<header>
<title>Extended Roster</title>
<abstract>This JEP defines a way to handle extended roster items.</abstract>
&LEGALNOTICE;
<number>0057</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<supersedes>None</supersedes>
<supersededby>None</supersededby>
<shortname>None</shortname>
<author>
<firstname>Alexey</firstname>
<surname>Shchepin</surname>
<email>alexey@sevcom.net</email>
<jid>aleksey@jabber.ru</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-04-28</date>
<initials>psa</initials>
<remark>Changed the status to Retracted at the request of the author, since the proposed protocol was incompatible with XMPP and clients have begun using jabber:iq:private for this kind of functionality. This JEP will not be considered further by the Jabber Software Foundation and should not be used as a basis for implementations.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-11-12</date>
<initials>as</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic="Introduction">
<p>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.</p>
</section1>
<section1 topic="What we need to store">
<p>All information, that can be stored for each item can be divided into three categories:</p>
<ol>
<li>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).</li>
<li>Information, neccessary only for client-side. E.g. user description of this item.</li>
<li>Information for both sides. This is at least the JID, category and type.</li>
</ol>
</section1>
<section1 topic="Where to store">
<p>Using <tt>jabber:iq:private</tt> as in JEP-0048 <note><link url='http://www.jabber.org/jeps/jep-0048.html'>http://www.jabber.org/jeps/jep-0048.html</link></note> for storing this information has one big problem: it is hard to mantain roster data in two separate places. When a client is online, then the client application can handle <tt>jabber:iq:roster</tt> changes and make similar changes in private storage, but when the user is online with a few different resources, or when he is offline, then making the information consistent is very hard task (a roster can be changed when user offline, e.g. if someone is making an account transfer).</p>
<p>But we have a place where this problem does not exist: <tt>jabber:iq:roster</tt>. We can store it in <tt>&lt;item/&gt;</tt> subtags. Existing server implementation MUST NOT remove <tt>&lt;x/&gt;</tt> tags from it. In this case all information always relates to its JID and disappears when this JID removed.</p>
</section1>
<section1 topic="How to store">
<section2 topic="General information">
<p> JID, category and type are stored as attributes of <tt>&lt;item/&gt;</tt> 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 <link url='http://www.jabber.org/jana/disco.php'>http://www.jabber.org/jana/disco.php</link>.</p>
<example><![CDATA[<item jid="jdev@conference.jabber.org"
category="conference"
type="text">]]></example>
</section2>
<section2 topic="Server-side information">
<p>This information is implementation-dependent, so to provide flexibility for it, the <tt>jabber:x:data</tt> namespace defined in JEP-0004 <note><link url='http://www.jabber.org/jeps/jep-0004.html'>http://www.jabber.org/jeps/jep-0004.html</link></note> must be used. The client can set these parameters by setting this item with this form with <tt>type='submit'</tt>.</p>
<example><![CDATA[<item jid="romeo@montague.net"
name="Romeo"
subscription="both">
<x xmlns='jabber:x:data' type='form'>
<field type='list-single' label='Visibility' var='visibility'>
<value>visible</value>
<option label='Normal'>
<value>normal</value>
</option>
<option label='Always visible'>
<value>visible</value>
</option>
<option label='Always invisible'>
<value>invisible</value>
</option>
</field>
</x>
...
</item>]]></example>
</section2>
<section2 topic="Client-side information">
<p>This information stored in <tt>&lt;x/&gt;</tt> tag with namespace <tt>jabber:x:roster:item</tt>. Following subtags can be used for diferent types of JIDs, however client applications can make this set bigger, to implement more functions.</p>
<section3 topic="Generic JIDs">
<p>
For all categories and types of JID allowed following subtag:
</p>
<ul>
<li>
<strong>desc</strong>: A description or note describing the JID.
</li>
</ul>
</section3>
<section3 topic="Client JIDs">
For all JIDs with category=client allowed following subtags:
<ul>
<li>
<strong>always-visible</strong>, <strong>always-invisible</strong>:
The client should send custom presence to this JID to be always
visible or invisible to it.
</li>
</ul>
</section3>
<section3 topic="Conference JIDs">
<p>
For all JIDs with category=conference allowed following subtags:
</p>
<ul>
<li>
<strong>nick</strong>: 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.
</li>
<li>
<strong>password</strong>: The password to be used to joing the
room.
</li>
<li>
<strong>auto-join</strong>: The client should automatically join
this room once the user has been authenticated, and the roster have
been fetched.
</li>
</ul>
</section3>
<example><![CDATA[<x xmlns="jabber:x:roster:item">
<always-visible/>
<desc>My old good friend</desc>
</x>]]></example>
</section2>
<section2 topic="Complete example">
<example><![CDATA[<iq id="roster_1" type="result">
<query xmlns="jabber:iq:roster">
<item jid="romeo@montague.net"
name="Romeo"
category="user"
type="client"
subscription="both">
<x xmlns="jabber:x:roster:item">
<always-visible/>
<desc>bla bla bla</desc>
</x>
<x xmlns='jabber:x:data' type='form'>
<field type='list-single' label='Visibility' var='visibility'>
<value>visible</value>
<option label='Normal'>
<value>normal</value>
</option>
<option label='Always visible'>
<value>visible</value>
</option>
<option label='Always invisible'>
<value>invisible</value>
</option>
</field>
</x>
</item>
<item jid="jdev@conference.jabber.org"
name="Developers Zone"
category="conference"
type="text"
subscription="none">
<x xmlns="jabber:x:roster:item">
<password>bigsecret</password>
<auto-join/>
<nick>aleksey</nick>
<nick>alexey</nick>
<desc>Jabber developers talks</desc>
</x>
</item>
</query>
</iq>]]> </example>
</section2>
</section1>
</jep>

173
xep-0058.xml Normal file
View File

@ -0,0 +1,173 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type="text/xsl" href="../jep.xsl"?>
<jep>
<header>
<title>Multi-User Text Editing</title>
<abstract>This JEP defines how several people may simultaneously edit text.</abstract>
&LEGALNOTICE;
<number>0058</number>
<status>Deferred</status>
<type>Standards Track</type>
<jig>Standards</jig>
<author>
<firstname>Alexey</firstname>
<surname>Shchepin</surname>
<email>alexey@sevcom.net</email>
<jid>aleksey@jabber.ru</jid>
</author>
<revision>
<version>0.1</version>
<date>2002-11-12</date>
<initials>as</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic="Introduction">
This JEP defines a protocol for editing one text document by several people.
This can be useful when several people write different parts of one single document, or
one person edits the text and other people can see the changes. The advantage of
using this protocol in compared to using a version control systems is that all
changes are distributed between editors in real-time.
</section1>
<section1 topic="Protocol description">
<p>
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.
</p>
<example caption="User asks the server list of editable texts"><![CDATA[<iq type='get' to='server' id='mute1'>
<list xmlns='http://jabber.org/protocol/mute#server'/>
</iq>]]></example>
<p>
After that the server returns a list of the documents. For each list
item an ID and description is given.
</p>
<example caption="Ancestor returns list of editable texts"><![CDATA[<iq type='result' to='editor1' id='mute1'>
<list xmlns='http://jabber.org/protocol/mute#server'>
<item id='id1' desc='Useful text'/>
<item id='id2' desc='Useless text'/>
</list>
</iq>]]></example>
<p>
Then the user can send a subscribe request to the server by sending the documents ID.
Attribute <tt>type</tt> can be <tt>rdwr</tt> for full access or
<tt>rdonly</tt> for read-only access.
</p>
<example caption="User sends subscribe request"><![CDATA[<iq type='set' to='server' id='mute2'>
<subscribe xmlns='http://jabber.org/protocol/mute#server'>
<item id='id1' type='rdwr'/>
</subscribe>
</iq>]]></example>
<example caption="Positive response from server on subscribe
request"><![CDATA[<iq type='result' to='editor1' id='mute2'/>]]></example>
<example caption="Negative response from server on subscribe
request"><![CDATA[<iq type='error' to='editor1' id='mute2'>
<subscribe xmlns='http://jabber.org/protocol/mute#server'>
<item id='id1' type='rdwr'/>
</subscribe>
<error code="405">Not Allowed</error>
</iq>]]></example>
<p>
After successful subscription, the server sends the full contents of the document to
the new editor.
</p>
<example caption="Server sends text to editor"><![CDATA[<iq type='set' to='editor1' id='mute3'>
<text xmlns='http://jabber.org/protocol/mute#editor' id='id1'>
...
8. Admin Use Cases
8.1. Banning a User
8.2. Modifying the Ban List
8.3. Granting Membership
8.4. Revoking Mambership
8.5. Modifying the Member List
8.6. Granting Moderator Privileges
8.7. Revoking Moderator Privileges
8.8. Modifying the Moderator List
...
</text>
</iq>]]></example>
<example caption="Positive response from editor"><![CDATA[<iq type='result' to='server' id='mute3'/>]]></example>
<p>
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).
</p>
<example caption="Editor sends patch to server"><![CDATA[<iq type='set' to='server' id='mute4'>
<patch xmlns='http://jabber.org/protocol/mute#server' id='id1'>
@@ -2,7 +2,7 @@
8.1. Banning a User
8.2. Modifying the Ban List
8.3. Granting Membership
- 8.4. Revoking Mambership
+ 8.4. Revoking Membership
8.5. Modifying the Member List
8.6. Granting Moderator Privileges
8.7. Revoking Moderator Privileges
</patch>
</iq>]]></example>
<example caption="Server accepts patch"><![CDATA[<iq type='result' to='editor1' id='mute4'/>]]></example>
<example caption="Server not accepts patch"><![CDATA[<iq type='error' to='editor1' id='mute4'>
<patch xmlns='http://jabber.org/protocol/mute#server' id='id1'>
@@ -2,7 +2,7 @@
8.1. Banning a User
8.2. Modifying the Ban List
8.3. Granting Membership
- 8.4. Revoking Mambership
+ 8.4. Revoking Membership
8.5. Modifying the Member List
8.6. Granting Moderator Privileges
8.7. Revoking Moderator Privileges
</patch>
<error code="405">Not Allowed</error>
</iq>]]></example>
<p>
If server accepts the patch, then it resends it to all subscribed text editors and readers.
</p>
<example caption="Server resend accepted patch to all editors and readers
of this text"><![CDATA[<iq type='set' to='editor1' id='mute5'>
<patch xmlns='http://jabber.org/protocol/mute#editor' id='id1'>
@@ -2,7 +2,7 @@
8.1. Banning a User
8.2. Modifying the Ban List
8.3. Granting Membership
- 8.4. Revoking Mambership
+ 8.4. Revoking Membership
8.5. Modifying the Member List
8.6. Granting Moderator Privileges
8.7. Revoking Moderator Privileges
</patch>
</iq>]]></example>
<example caption="Positive response from editors and readers"><![CDATA[<iq type='result' to='server' id='mute5'/>]]></example>
<p>
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.
</p>
</section1>
<section1 topic="Formal Definitions">
<example caption="DTD for http://jabber.org/protocol/mute#server"><![CDATA[<?xml version="1.0" encoding="UTF-8" ?>
<!ELEMENT list ((item)*)>
<!ELEMENT subscribe (item)>
<!ELEMENT item EMPTY>
<!ATTLIST item
id CDATA #REQUIRED
desc CDATA #IMPLIED
type ( rdwr | rdonly ) #IMPLIED >
<!ELEMENT patch (#PCDATA)>]]></example>
<example caption="DTD for http://jabber.org/protocol/mute#editor"><![CDATA[<?xml version="1.0" encoding="UTF-8" ?>
<!ELEMENT patch (#PCDATA)>
<!ELEMENT text (#PCDATA)>]]></example>
</section1>
</jep>

561
xep-0059.xml Normal file
View File

@ -0,0 +1,561 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Result Set Management</title>
<abstract>This document defines an XMPP protocol extension to enable entities to page through and otherwise manage the receipt of large result sets.</abstract>
&LEGALNOTICE;
<number>0059</number>
<status>Draft</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>JEP-0030</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>rsm</shortname>
<schemaloc>
<url>http://jabber.org/protocol/rsm/rsm.xsd</url>
</schemaloc>
&ianpaterson;
&stpeter;
&val;
<author>
<firstname>Jean-Louis</firstname>
<surname>Seguineau</surname>
<email>jls@antepo.com</email>
<jid>jlseguineau@im.antepo.com</jid>
</author>
<revision>
<version>1.0</version>
<date>2006-09-20</date>
<initials>psa</initials>
<remark><p>Per a vote of the Jabber Council, advanced status to Draft.</p></remark>
</revision>
<revision>
<version>0.14</version>
<date>2006-09-13</date>
<initials>ip</initials>
<remark><p>Clarified terminology regarding pages and result sets.</p></remark>
</revision>
<revision>
<version>0.13</version>
<date>2006-09-07</date>
<initials>ip/psa</initials>
<remark><p>Reverted to v0.11 with slight wording changes.</p></remark>
</revision>
<revision>
<version>0.12</version>
<date>2006-09-06</date>
<initials>psa/vm</initials>
<remark><p>Added index attribute to before element; removed index element (use after or before instead).</p></remark>
</revision>
<revision>
<version>0.11</version>
<date>2006-08-25</date>
<initials>ip</initials>
<remark><p>Made count and index optional, changed protocol for getting count, more clarifications and examples.</p></remark>
</revision>
<revision>
<version>0.10</version>
<date>2006-08-24</date>
<initials>ip</initials>
<remark><p>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.</p></remark>
</revision>
<revision>
<version>0.9</version>
<date>2006-08-23</date>
<initials>ip</initials>
<remark><p>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.</p></remark>
</revision>
<revision>
<version>0.8</version>
<date>2006-08-22</date>
<initials>psa</initials>
<remark><p>Added optional method for handling dynamic result sets.</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2006-08-10</date>
<initials>psa</initials>
<remark><p>Updated implementation note to clarify handling of result sets (static vs. dynamic).</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2006-07-12</date>
<initials>psa</initials>
<remark><p>Updated implementation note to clarify handling of result sets (static vs. dynamic).</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2006-05-02</date>
<initials>psa</initials>
<remark><p>Clarified error handling, determination of support in the context of using protocols, and security considerations.</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2006-04-24</date>
<initials>psa</initials>
<remark><p>Specified that an item count may be approximate; specified that an item count may be returned with a page of results.</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2006-04-21</date>
<initials>psa/vm</initials>
<remark><p>Added &lt;end/&gt; element to specify last result set; added service discovery information; added more examples.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2005-12-22</date>
<initials>psa/vm</initials>
<remark><p>Revived and renamed the JEP; modified syntax; added use case for getting number of items; defined XML schema.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-11-12</date>
<initials>jls</initials>
<remark><p>Initial version.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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:</p>
<ol>
<li>Limit the number of items returned.</li>
<li>Page forwards or backwards through a result set by retrieving the items in smaller subsets.</li>
<li>Discover the size of a result set without retrieving the items themselves.</li>
<li>Retrieve a page (subset) of items starting at any point in a result set.</li>
</ol>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Limiting the Number of Items' anchor='limit'>
<p>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 &lt;max/&gt; element):</p>
<example caption='Requesting a Limit to the Result Set'><![CDATA[
<iq type='get' from='stpeter@jabber.org/roundabout' to='users.jabber.org' id='limit1'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
</set>
</query>
</iq>
]]></example>
<p>The responding entity then returns the first items of the result set in order. The number of items is limited to the requested size:</p>
<example caption='Returning a Limited Result Set'><![CDATA[
<iq type='result' from='users.jabber.org' to='stpeter@jabber.org/roundabout' id='limit1'>
<query xmlns='jabber:iq:search'>
<item jid='stpeter@jabber.org'>
<first>Peter</first>
<last>Saint-Andre</last>
<nick>Pete</nick>
</item>
.
[8 more items]
.
<item jid='peterpan@neverland.lit'>
<first>Peter</first>
<last>Pan</last>
<nick>Pete</nick>
</item>
</query>
</iq>
]]></example>
</section2>
<section2 topic='Paging Forwards Through a Result Set' anchor='forwards'>
<p>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.</p>
<p>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:</p>
<ul>
<li>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).</li>
<li>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).</li>
<li>When paging through the list in order, duplicate items are never received.</li>
<li>The responding entity maintains no state (or a single minimal state for all requesting entities containing the positions of all recently deleted items).</li>
<li>Rapid calculation of which items should appear on a requested page by responding entity (even for large result sets).</li>
</ul>
<p>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.</p>
<p>The request for the first page is the same as when <link url='#limit'>Limiting the Number of Items</link>:</p>
<example caption='Requesting the First Page of a Result Set'><![CDATA[
<iq type='get' from='stpeter@jabber.org/roundabout' to='users.jabber.org' id='page1'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
</set>
</query>
</iq>
]]></example>
<p>Responding entity support for paging through a result set is optional. If it does support paging (not just <link url='#limit'>Limiting the Number of Items</link>), then in each page it returns, the responding entity MUST include &lt;first/&gt; and &lt;last/&gt; 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 &lt;first/&gt; and &lt;last/&gt; elements MUST NOT be included.</p>
<p>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.</p>
<p>The responding entity SHOULD also include the number of items in the full result set (which MAY be approximate) encapsulated in a &lt;count/&gt; element. The &lt;first/&gt; 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 &lt;first/&gt; element's 'index' attribute SHOULD be the specified count minus the number of items in the last page.</p>
<p>Note: The &lt;count/&gt; element and 'index' attribute enable important functionality for requesting entities (for example, a scroll-bar user-interface component). They MAY be omitted, but <em>only</em> if it would be either impossible or exceptionally resource intensive to calculate reasonably accurate values.</p>
<example caption='Returning the First Page of a Result Set'><![CDATA[
<iq type='result' from='users.jabber.org' to='stpeter@jabber.org/roundabout' id='page1'>
<query xmlns='jabber:iq:search'>
<item jid='stpeter@jabber.org'>
<first>Peter</first>
<last>Saint-Andre</last>
<nick>Pete</nick>
</item>
.
[8 more items]
.
<item jid='peterpan@neverland.lit'>
<first>Peter</first>
<last>Pan</last>
<nick>Pete</nick>
</item>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='0'>stpeter@jabber.org</first>
<last>peterpan@neverland.lit</last>
<count>800</count>
</set>
</query>
</iq>
]]></example>
<p>The requesting entity can then ask for the next page in the result set by including in its request the UID of the <em>last</em> item from the previous page (encapsulated in an &lt;after/&gt; element), along with the maximum number of items to return. Note: If no &lt;after/&gt; element is specified, then the UID defaults to "before the first item in the result set" (i.e., effectively an index of negative one).</p>
<example caption='Requesting the Second Page of a Result Set'><![CDATA[
<iq type='get' from='stpeter@jabber.org/roundabout' to='users.jabber.org' id='page2'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<after>peterpan@neverland.lit</after>
</set>
</query>
</iq>
]]></example>
<p>The <em>first</em> item in the page returned by the responding entity MUST be the item that immediately <em>follows</em> the item that the requesting entity indicated in the &lt;after/&gt; element:</p>
<example caption='Returning the Second Page of a Result Set'><![CDATA[
<iq type='result' from='users.jabber.org' to='stpeter@jabber.org/roundabout' id='page2'>
<query xmlns='jabber:iq:search'>
<item jid='peter@pixyland.org'>
<first>Peter</first>
<last>Pan</last>
<nick>Pete</nick>
</item>
.
[8 more items]
.
<item jid='peter@rabbit.lit'>
<first>Peter</first>
<last>Rabbit</last>
<nick>Pete</nick>
</item>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='10'>peter@pixyland.org</first>
<last>peter@rabbit.lit</last>
<count>800</count>
</set>
</query>
</iq>
]]></example>
<p>It may sometimes be necessary to return an empty <em>page</em> 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 <link url='#count'>Getting the Item Count</link>).</p>
<example caption='Returning an Empty Page'><![CDATA[
<iq type='result' from='users.jabber.org' to='stpeter@jabber.org/roundabout' id='page80'>
<query xmlns='jabber:iq:search'>
<set xmlns='http://jabber.org/protocol/rsm'>
<count>790</count>
</set>
</query>
</iq>
]]></example>
<p>If there are no items whatsoever in the <em>full</em> 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 <cite>JEP-0055</cite> and <cite>JEP-0030</cite>, that means the responding entity shall return an empty &QUERY; element; for <cite>JEP-0060</cite>, that means the responding entity shall return an empty &lt;pubsub/&gt; element; for <cite>JEP-0136</cite>, that means the responding entity shall return an empty &lt;list/&gt; or &lt;store/&gt; element.</p>
</section2>
<section2 topic='Paging Backwards Through a Result Set' anchor='backwards'>
<p>The requesting entity MAY ask for the previous page in a result set by including in its request the UID of the <em>first</em> item from the page that has already been received (encapsulated in a &lt;before/&gt; element), along with the maximum number of items to return.</p>
<example caption='Requesting the Previous Page of a Result Set'><![CDATA[
<iq type='get' from='stpeter@jabber.org/roundabout' to='users.jabber.org' id='back1'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<before>peter@pixyland.org</before>
</set>
</query>
</iq>
]]></example>
<p>The <em>last</em> item in the page returned by the responding entity MUST be the item that immediately <em>preceeds</em> the item that the requesting entity indicated it has already received:</p>
<example caption='Returning the Previous Page of a Result Set'><![CDATA[
<iq type='result' from='users.jabber.org' to='stpeter@jabber.org/roundabout' id='back1'>
<query xmlns='jabber:iq:search'>
<item jid='stpeter@jabber.org'>
<first>Peter</first>
<last>Saint-Andre</last>
<nick>Pete</nick>
</item>
.
[8 more items]
.
<item jid='peterpan@neverland.lit'>
<first>Peter</first>
<last>Pan</last>
<nick>Pete</nick>
</item>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='0'>stpeter@jabber.org</first>
<last>peterpan@neverland.lit</last>
<count>800</count>
</set>
</query>
</iq>
]]></example>
</section2>
<section2 topic='Page Not Found' anchor='notfound'>
<p>The responding entity MUST reply with an 'item-not-found' error if <em>all</em> the following circumstances apply:</p>
<ol>
<li><p>The item specified by the requesting entity via the UID in the &lt;after/&gt; or &lt;before/&gt; element no longer exists (it was deleted after the previous page was sent).</p></li>
<li><p>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).</p></li>
<li><p>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.)</p></li>
</ol>
<example caption='Returning a Page-Not-Found Error'><![CDATA[
<iq type='error' from='users.jabber.org' to='stpeter@jabber.org/roundabout' id='page2'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<after>peterpan@neverland.lit</after>
</set>
</query>
<error type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section2>
<section2 topic='Requesting the Last Page in a Result Set' anchor='last'>
<p>The requesting entity MAY ask for the last page in a result set by including in its request an empty &lt;before/&gt; element, and the maximum number of items to return.</p>
<example caption='Requesting the Last Page of a Result Set'><![CDATA[
<iq type='get' from='stpeter@jabber.org/roundabout' to='users.jabber.org' id='page1'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<before/>
</set>
</query>
</iq>
]]></example>
</section2>
<section2 topic='Retrieving a Page Out of Order' anchor='jump'>
<p>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.)</p>
<p>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 <em>starts</em> at a particular index within the result set. It does that by including in its request the index of the <em>first</em> item to be returned (encapsulated in an &lt;index/&gt; element), as well as the maximum number of items to return. Note: For reasons mentioned in <link url='#forwards'>Paging Forwards Through a Result Set</link> requesting entities SHOULD, where possible, specify pages using a UID instead of an index.</p>
<p>Note: If the responding entity omitted the &lt;count/&gt; 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).</p>
<example caption='Requesting a Result Page by Index'><![CDATA[
<iq type='get' from='stpeter@jabber.org/roundabout' to='users.jabber.org' id='index10'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<index>371</index>
</set>
</query>
</iq>
]]></example>
<p>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.</p>
<p>Note: The 'index' attribute of the &lt;first/&gt; 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 <link url='#forwards'>Paging Forwards Through a Result Set</link>).</p>
<example caption='Returning a Result Page at an Index'><![CDATA[
<iq type='result' from='users.jabber.org' to='stpeter@jabber.org/roundabout' id='index10'>
<query xmlns='jabber:iq:search'>
<item jid='peter@pixyland.org'>
<first>Peter</first>
<last>Pan</last>
<nick>Pete</nick>
</item>
.
[8 more items]
.
<item jid='peter@rabbit.lit'>
<first>Peter</first>
<last>Rabbit</last>
<nick>Pete</nick>
</item>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='10'>peter@pixyland.org</first>
<last>peter@rabbit.lit</last>
<count>800</count>
</set>
</query>
</iq>
]]></example>
<p>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.</p>
<example caption='Returning a Feature-not-Implemented Error'><![CDATA[
<iq type='error' from='users.jabber.org' to='stpeter@jabber.org/roundabout' id='index10'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<index>371</index>
</set>
</query>
<error type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section2>
<section2 topic='Getting the Item Count' anchor='count'>
<p>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:</p>
<example caption='Requesting the Item Count'><![CDATA[
<iq type='get' from='stpeter@jabber.org/roundabout' to='users.jabber.org' id='count1'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>0</max>
</set>
</query>
</iq>
]]></example>
<p>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:</p>
<example caption='Returning the Item Count'><![CDATA[
<iq type='result' from='users.jabber.org' to='stpeter@jabber.org/roundabout' id='count1'>
<query xmlns='jabber:iq:search'>
<set xmlns='http://jabber.org/protocol/rsm'>
<count>800</count>
</set>
</query>
</iq>
]]></example>
<p>Note: The &lt;count/&gt; element MAY be omitted, but <em>only</em> if it would be either impossible or exceptionally resource intensive to calculate reasonably accurate values.</p>
<p>Note: If there are no items in the <em>full</em> result set then the responding entity MUST return a response that adheres to the definition of the wrapper protocol (see <link url='#forwards'>Paging Forwards Through a Result Set</link>).</p>
</section2>
</section1>
<section1 topic='Examples' anchor='examples'>
<p>The foregoing examples show the use of result set management in the context of <cite>Jabber Search</cite>. In the following examples we show the use of this protocol in the context of <cite>Service Discovery</cite>. <cite>JEP-0136</cite> ("Message Archiving") includes more examples. A future version of this document may also include examples from <cite>Publish-Subscribe</cite> and other XMPP protocol extensions.</p>
<example caption='Requesting a Limit to the Result Set'><![CDATA[
<iq type='get' from='stpeter@jabber.org/roundabout' to='conference.jabber.org' id='ex2'>
<query xmlns='http://jabber.org/protocol/disco#items'>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>20</max>
</set>
</query>
</iq>
]]></example>
<example caption='Returning a Limited Result Set'><![CDATA[
<iq type='result' from='conference.jabber.org' to='stpeter@jabber.org/roundabout' id='ex2'>
<query xmlns='http://jabber.org/protocol/disco#items'>
<item jid='12@conference.jabber.org'/>
<item jid='adium@conference.jabber.org'/>
<item jid='airhitch@conference.jabber.org'/>
<item jid='alphaville@conference.jabber.org'/>
<item jid='apache@conference.jabber.org'/>
<item jid='argia@conference.jabber.org'/>
<item jid='armagetron@conference.jabber.org'/>
<item jid='atticroom123@conference.jabber.org'/>
<item jid='banquise@conference.jabber.org'/>
<item jid='bar_paradise@conference.jabber.org'/>
<item jid='beer@conference.jabber.org'/>
<item jid='blondie@conference.jabber.org'/>
<item jid='bpnops@conference.jabber.org'/>
<item jid='brasileiros@conference.jabber.org'/>
<item jid='bulgaria@conference.jabber.org'/>
<item jid='cantinalivre@conference.jabber.org'/>
<item jid='casablanca@conference.jabber.org'/>
<item jid='chinortpcrew@conference.jabber.org'/>
<item jid='coffeetalk@conference.jabber.org'/>
<item jid='council@conference.jabber.org'/>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='0'>acc3594e844c77696f7a7ba9367ae324b6b958ad</first>
<last>4da91d4b330112f683dddaebf93180b1bd25e95f</last>
<count>150</count>
</set>
</query>
</iq>
]]></example>
<example caption='Requesting a Page Beginning After the Last Item Received'><![CDATA[
<iq type='get' from='stpeter@jabber.org/roundabout' to='conference.jabber.org' id='ex3'>
<query xmlns='http://jabber.org/protocol/disco#items'>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>20</max>
<after>4da91d4b330112f683dddaebf93180b1bd25e95f</after>
</set>
</query>
</iq>
]]></example>
</section1>
<section1 topic='Determining Support' anchor='disco'>
<p>In order for a requesting entity to determine if a responding entity supports result set management, it SHOULD send a <cite>Service Discovery</cite> information request to the responding entity:</p>
<example caption='Requesting entity queries responding entity regarding protocol support'><![CDATA[
<iq from='stpeter@jabber.org/roundabout'
to='conference.jabber.org'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption='Responding entity communicates protocol support'><![CDATA[
<iq from='conference.jabber.org'
to='stpeter@jabber.org/roundabout'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://jabber.org/protocol/rsm'/>
...
</query>
</iq>
]]></example>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>Security considerations are the responsibility of the using ("wrapper") protocol, such as <cite>JEP-0030</cite> for the 'http://jabber.org/protocol/disco#items' namespace, <cite>JEP-0055</cite> for the 'jabber:iq:search' namespace, and <cite>JEP-0136</cite> for the 'http://jabber.org/protocol/archive' namespace.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; includes 'http://jabber.org/protocol/rsm' in its registry of protocol namespaces.</p>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/rsm'
xmlns='http://jabber.org/protocol/rsm'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0059: http://www.jabber.org/jeps/jep-0059.html
</xs:documentation>
</xs:annotation>
<xs:element name='set'>
<xs:complexType>
<xs:sequence>
<xs:element name='after' type='xs:string' minOccurs='0' maxOccurs='1'/>
<xs:element name='before' type='xs:string' minOccurs='0' maxOccurs='1'/>
<xs:element name='count' type='xs:int' minOccurs='0' maxOccurs='1'/>
<xs:element ref='first' minOccurs='0' maxOccurs='1'/>
<xs:element name='index' type='xs:int' minOccurs='0' maxOccurs='1'/>
<xs:element name='last' type='xs:string' minOccurs='0' maxOccurs='1'/>
<xs:element name='max' type='xs:int' minOccurs='0' maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='first'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='index' type='xs:int' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Olivier Goffart, Jon Perlow, and Andrew Plotkin for their feedback.</p>
</section1>
</jep>

6429
xep-0060.xml Normal file
View File

File diff suppressed because it is too large Load Diff

83
xep-0061.xml Normal file
View File

@ -0,0 +1,83 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Shared Notes</title>
<abstract>A simplistic mechanism for shared notes, modeled after common stickie note applications.</abstract>
&LEGALNOTICE;
<number>0061</number>
<status>Deferred</status>
<type>Informational</type>
<jig>Standards JIG</jig>
<dependencies>XMPP Core</dependencies>
<supersedes>None</supersedes>
<supersededby>None</supersededby>
<shortname>Not yet assigned</shortname>
<author>
<firstname>Jeremie</firstname>
<surname>Miller</surname>
<email>jer@jabber.org</email>
<jid>jer@jabber.org</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-09-30</date>
<initials>psa</initials>
<remark>At the request of the author, changed the status of this JEP to Deferred pending development of an implementation; also changed the type to Informational.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-12-06</date>
<initials>jer</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
</section1>
<section1 topic='Message Extension'>
<p>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).</p>
<example caption='An Example Shared Note Message'><![CDATA[
<message from="jer@jabber.org/foo" to="stpeter@jabber.org/bar">
<thread>1X544O</thread>
<subject>Council Votes</subject>
<body>Need votes from bob, tom, and jane yet for JEP-0000</body>
<note xmlns="http://www.jabber.org/protocol/sharednote">
<color>#001122</color>
<bgcolor>#221100</bgcolor>
<font>font-name</font>
<x>%left</x>
<y>%top</y>
<z>#</z>
<width>%</width>
<height>%</height>
<update>auto|user</update>
</note>
</message>
]]></example>
<p>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.</p>
</section1>
<section1 topic='Implementation Notes'>
<p>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.</p>
</section1>
</jep>

347
xep-0062.xml Normal file
View File

@ -0,0 +1,347 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Packet Filtering</title>
<abstract>A framework for packet filtering rules.</abstract>
&LEGALNOTICE;
<number>0062</number>
<status>Deferred</status>
<type>Informational</type>
<jig>Standards JIG</jig>
<dependencies>XMPP Core, JEP-0030</dependencies>
<supersedes>None</supersedes>
<supersededby>None</supersededby>
<shortname>Not yet assigned</shortname>
<author>
<firstname>Robert</firstname>
<surname>Norris</surname>
<email>rob@cataclysm.cx</email>
<jid>rob@cataclysm.cx</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-09-30</date>
<initials>psa</initials>
<remark>At the request of the author, changed the status of this JEP to Deferred pending development of an implementation; also changed the type to Informational.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-12-05</date>
<initials>rn</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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:</p>
<ul>
<li>The service and protocol were undocumented, apart from some documentation reverse-engineered from the source code.</li>
<li>The processing requirements that the service required made it unusable for large installations.</li>
<li>Bugs in the service often caused the Jabber server to crash.</li>
</ul>
<p>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;.</p>
<p>However, packet filtering (as opposed to the subset of JID blacklisting) is still of use, for the following tasks:</p>
<ul>
<li>Setting up automatic responses to messages (e.g., "vacation" messages).</li>
<li>Redirecting packets to another JID.</li>
<li>Modifying the contents of a packet in-transit (e.g., language translation, adding &lt;x/&gt; data).</li>
<li>Force incoming messages to be stored offline (e.g., for low-bandwidth clients).</li>
</ul>
<p>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.</p>
<p>The framework itself operates in the "http://jabber.org/protocol/filter" namespace.</p>
<section2 topic='Definitions'>
<p>The following definitions are used throughout this document:</p>
<ul>
<li>ruleset - a set of filtering rules.</li>
<li>rule - a set of conditions with an associated action.</li>
<li>condition - an expression (or set of expressions) that, when applied to a packet, is either true or false.</li>
<li>action - a task that may be performed on a packet.</li>
</ul>
</section2>
</section1>
<section1 topic='Structure'>
<p>A single rule is be expressed in XML like so:</p>
<example caption='XML representation of a rule'><![CDATA[
<rule description='natural-language description of rule'>
<condition>[conditionexpr]</condition>
<action>[actionspec]</action>
</rule>
]]></example>
<p>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.</p>
<p>A ruleset is be expressed in XML like so:</p>
<example caption='XML representation of a ruleset'><![CDATA[
<ruleset>
<rule description='rule description'>
<condition>[conditionexpr]</condition>
<action>[actionspec]</action>
</rule>
<rule description='rule description'>
<condition>[conditionexpr]</condition>
<action>[actionspec]</action>
</rule>
<rule description='rule description'>
<condition>[conditionexpr]</condition>
<action>[actionspec]</action>
</rule>
</ruleset>
]]></example>
<p>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, <emphasis>unless</emphasis> the "continue" attribute is found on the matched rule, in which case the remaining rules get processed as though the current rule did not match. If no rules match, packet processing continues as though no rules were specified.</p>
<p>If the &lt;condition/> element contains no condition expression, then the rule matches all packets.</p>
<p>A ruleset does not have to contain any rules:</p>
<example caption='Empty ruleset'><![CDATA[
<ruleset/>
]]></example>
<p>Conditions may be aggregated using AND or OR modifiers, like so:</p>
<example caption='Aggregated condition'><![CDATA[
<condition>
<and>
[conditionexpr1]
[conditionexpr2]
<or>
[conditionexpr3]
[conditionexpr4]
</or>
</and>
</condition>
]]></example>
<p>The above example is equivalent to "conditionexpr1 AND conditionexpr2 AND (conditionexpr3 OR conditionexpr4)".</p>
<p>No such aggregation exists for actions - only a single action expression may be included within an &lt;action/> element.</p>
</section1>
<section1 topic='Filter modules'>
<p>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.</p>
<p>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:</p>
<ul>
<li>&lt;to/> - true when the CDATA of this element matches the "to" attribute of the packet.</li>
<li>&lt;from/> - true when the CDATA of this element matches the "from" attribute of the packet.</li>
<li>&lt;type/> - true when the CDATA of this element matches the "type" attribute of the packet.</li>
</ul>
<p>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:</p>
<ul>
<li>&lt;redirect/> - redirects the packet to the JID specified in the CDATA of this element.</li>
<li>&lt;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.</li>
</ul>
<p>These two modules might be combined to produce a ruleset like the following:</p>
<example caption='Using modules in a ruleset'><![CDATA[
<ruleset>
<rule description='Send messages from my friend to my home account to be dealt with later'>
<condition>
<from xmlns='http://jabber.org/protocol/filter/header'>friend@theirisp.com</from>
</condition>
<action>
<redirect xmlns='http://jabber.org/protocol/filter/redirect'>me@home.com</redirect>
</action>
</rule>
</ruleset>
]]></example>
<p>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.</p>
</section1>
<section1 topic='Protocol'>
<p>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.
</p>
<section2 topic='Module discovery'>
<p>An entity may find out if a service supports filtering, and the modules its supports, by issuing a discovery request to the service:</p>
<example caption='Module discovery'><![CDATA[
<iq type='get' to='jabber.org' 'disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]> </example>
<example caption='Module discovery response'><![CDATA[
<iq type='result' to='jabber.org' id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity category='server' type='jabber' name='Jabber server'/>
<feature var='http://jabber.org/protocol/filter'/>
<feature var='http://jabber.org/protocol/filter/header'/>
<feature var='http://jabber.org/protocol/filter/redirect'/>
<feature var='...'/>
</query>
</iq>
]]> </example>
</section2>
<section2 topic='Setting the ruleset'>
<p>An entity may set the filter ruleset for an entity (which may be itself) like so:</p>
<example caption='Setting the ruleset'><![CDATA[
<iq type='set' to='rob@cataclysm.cx' id='filter1'>
<ruleset xmlns='http://jabber.org/protocol/filter'>
<rule description='Send messages from my friend to my home account to be dealt with later'>
<condition>
<from xmlns='http://jabber.org/protocol/filter/header'>friend@theirisp.com</from>
</condition>
<action>
<redirect xmlns='http://jabber.org/protocol/filter/redirect'>me@home.com</redirect>
</action>
</rule>
<rule description='Copy messages from this spammer to our abuse address'>
<condition>
<from xmlns='http://jabber.org/protocol/filter/header'>spammer@badsite.com</from>
</condition>
<action>
<copy xmlns='http://jabber.org/protocol/filter/redirect'>abuse@company.com</redirect>
</action>
</rule>
</ruleset>
</iq>
]]> </example>
<p>On success, the service returns:</p>
<example caption='Setting the ruleset result'><![CDATA[
<iq type='result' from='rob@cataclysm.cx' id='filter1'/>
]]> </example>
<p>On error, the server returns the original packet with an appropriate error:</p>
<example caption='Setting the ruleset failure'><![CDATA[
<iq type='error' to='rob@cataclysm.cx' id='filter1'>
<ruleset xmlns='http://jabber.org/protocol/filter'>
<rule description='Send messages from my friend to my home account to be dealt with later'>
<condition>
<from xmlns='http://jabber.org/protocol/filter/header'>friend@theirisp.com</from>
</condition>
<action>
<redirect xmlns='http://jabber.org/protocol/filter/redirect'>me@home.com</redirect>
</action>
</rule>
<rule description='Copy messages from this spammer to our abuse address'>
<condition>
<from xmlns='http://jabber.org/protocol/filter/header'>spammer@badsite.com</from>
</condition>
<action>
<copy xmlns='http://jabber.org/protocol/filter/redirect'>abuse@company.com</redirect>
</action>
</rule>
</ruleset>
<error code='403'>Forbidden</error>
</iq>
]]> </example>
</section2>
<section2 topic='Retrieving the ruleset'>
<p>An entity may retrieve the filter ruleset for an entity (which may be itself) like so:</p>
<example caption='Requesting the ruleset'><![CDATA[
<iq type='get' id='filter2'>
<ruleset xmlns='http://jabber.org/protocol/filter'/>
</iq>
]]> </example>
<p>If the requesting entity has permissions to view the ruleset, the server must return the ruleset to the entity:</p>
<example caption='Retrieving the ruleset result'><![CDATA[
<iq type='error' to='rob@cataclysm.cx' id='filter2'>
<ruleset xmlns='http://jabber.org/protocol/filter'>
<rule description='Send messages from my friend to my home account to be dealt with later'>
<condition>
<from xmlns='http://jabber.org/protocol/filter/header'>friend@theirisp.com</from>
</condition>
<action>
<redirect xmlns='http://jabber.org/protocol/filter/redirect'>me@home.com</redirect>
</action>
</rule>
<rule description='Copy messages from this spammer to our abuse address'>
<condition>
<from xmlns='http://jabber.org/protocol/filter/header'>spammer@badsite.com</from>
</condition>
<action>
<copy xmlns='http://jabber.org/protocol/filter/redirect'>abuse@company.com</redirect>
</action>
</rule>
</ruleset>
</iq>
]]> </example>
<p>On error, the server returns the original packet with an appropriate error:</p>
<example caption='Retrieving the ruleset failure'><![CDATA[
<iq type='error' to='rob@cataclysm.cx' id='filter2'>
<ruleset xmlns='http://jabber.org/protocol/filter'/>
<error code='403'>Forbidden</error>
</iq>
]]> </example>
</section2>
</section1>
<section1 topic='Error Codes'>
<p>Possible errors are:</p>
<table caption='Errors returned when retrieving the ruleset'>
<tr>
<th>Code</th><th>Text</th><th>Description</th>
</tr>
<tr>
<td>403</td><td>Forbidden</td><td>The sender does not have permission to modify the ruleset for this entity.</td>
</tr>
<tr>
<td>404</td><td>Not Found</td><td>The entity does not exist.</td>
</tr>
</table>
</section1>
<section1 topic='Implementation notes'>
<p>Ruleset processing should be the first thing that a service does when it receives a packet - even before processing privacy rules per JEP-0016.</p>
<p>Rules must be processed in the order they are given, and must be returned to a requesting entity in the same order.</p>
</section1>
<section1 topic='Security Considerations'>
<p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with the IANA.</p>
</section1>
<section1 topic='JANA Considerations'>
<p>No namespaces or parameters need to be registered with JANA as a result of this JEP.</p>
</section1>
</jep>

107
xep-0063.xml Normal file
View File

@ -0,0 +1,107 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Basic Filtering Operations</title>
<abstract>A module that provides basic conditions and actions for packet filtering.</abstract>
&LEGALNOTICE;
<number>0063</number>
<status>Deferred</status>
<type>Informational</type>
<jig>Standards JIG</jig>
<dependencies>JEP-0062</dependencies>
<supersedes>None</supersedes>
<supersededby>None</supersededby>
<shortname>Not yet assigned</shortname>
<author>
<firstname>Robert</firstname>
<surname>Norris</surname>
<email>rob@cataclysm.cx</email>
<jid>rob@cataclysm.cx</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-09-30</date>
<initials>psa</initials>
<remark>At the request of the author, changed the status of this JEP to Deferred pending development of an implementation; also changed the type to Informational.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-12-05</date>
<initials>rn</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>This document defines a module for &jep0062; that provides some basic conditions and actions to perform common packet filtering tasks.</p>
<p>This module operates in the "http://jabber.org/protocol/filter/basic" namespace.</p>
</section1>
<section1 topic='Conditions'>
<p>This module defines the fullowing conditions:</p>
<ul>
<li>&lt;message/> - true if the packet is a &lt;message/> packet.</li>
<li>&lt;presence/> - true if the packet is a &lt;presence/> packet.</li>
<li>&lt;iq/> - true if the packet is a &lt;iq/> packet. If this element contains CDATA, then it must match the namespace of the first element inside the packet (typically &lt;query/>) in order to be true.</li>
<li>&lt;to/> - true when the CDATA of this element matches the "to" attribute of the packet.</li>
<li>&lt;from/> - true when the CDATA of this element matches the "from" attribute of the packet.</li>
<li>&lt;type/> - true when the CDATA of this element matches the "type" attribute of the packet.</li>
</ul>
<example caption='Matches all presence packets'><![CDATA[
<presence xmlns='http://jabber.org/protocol/filter/basic'/>
]]></example>
<example caption='Matches all jabber:iq:version IQ packets'><![CDATA[
<iq xmlns='http://jabber.org/protocol/filter/basic'>jabber:iq:version</iq>
]]></example>
<example caption='Matches all packets from user@company.com'><![CDATA[
<from xmlns='http://jabber.org/protocol/filter/basic'>user@company.com</from>
]]></example>
</section1>
<section1 topic='Actions'>
<p>This module defines the fullowing actions:</p>
<ul>
<li>&lt;drop/> - drops the packet</li>
<li>&lt;bounce/> - bounces the packet with the error specified in the "code" attribute of this element.</li>
<li>&lt;redirect/> - redirects the packet to the JID specified in the CDATA of this element.</li>
<li>&lt;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.</li>
</ul>
<example caption='Pretend that we don&apos;t exist'><![CDATA[
<bounce xmlns='http://jabber.org/protocol/filter/basic' code='404'/>
]]></example>
<example caption='Send a copy to our home account'><![CDATA[
<copy xmlns='http://jabber.org/protocol/filter/basic'>me@home.com</copy>
]]></example>
</section1>
<section1 topic='Security Considerations'>
<p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with the IANA.</p>
</section1>
<section1 topic='JANA Considerations'>
<p>No namespaces or parameters need to be registered with JANA as a result of this JEP.</p>
</section1>
</jep>

78
xep-0064.xml Normal file
View File

@ -0,0 +1,78 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>XPath Filtering</title>
<abstract>A module that provides an XPath matching condition for packet filtering.</abstract>
&LEGALNOTICE;
<number>0064</number>
<status>Deferred</status>
<type>Informational</type>
<jig>Standards JIG</jig>
<dependencies>JEP-0062</dependencies>
<supersedes>None</supersedes>
<supersededby>None</supersededby>
<shortname>Not yet assigned</shortname>
<author>
<firstname>Robert</firstname>
<surname>Norris</surname>
<email>rob@cataclysm.cx</email>
<jid>rob@cataclysm.cx</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-09-30</date>
<initials>psa</initials>
<remark>At the request of the author, changed the status of this JEP to Deferred pending development of an implementation; also changed the type to Informational.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-12-05</date>
<initials>rn</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>This document defines a module for &jep0062; that provides an XPath matching condition for packet filtering.</p>
<p>This module operates in the "http://jabber.org/protocol/filter/xpath" namespace.</p>
</section1>
<section1 topic='Conditions'>
<p>This module defines the fullowing conditions:</p>
<ul>
<li>&lt;xpath/> - true if the XPath expression contained in the CDATA of this element, when applied to the packet, returns one or more nodes.</li>
</ul>
<example caption='Matches all messages with that have a subject element'><![CDATA[
<xpath xmlns='http://jabber.org/protocol/filter/xpath'>/message/subject</xpath>
]]></example>
<example caption='Matches all presence packets that have an x:delay stamp'><![CDATA[
<xpath xmlns='http://jabber.org/protocol/filter/xpath'>/presence/x[namespace-uri()=='jabber:x:delay']</xpath>
]]></example>
</section1>
<section1 topic='Security Considerations'>
<p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with the IANA.</p>
</section1>
<section1 topic='JANA Considerations'>
<p>No namespaces or parameters need to be registered with JANA as a result of this JEP.</p>
</section1>
</jep>

827
xep-0065.xml Normal file
View File

@ -0,0 +1,827 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>SOCKS5 Bytestreams</title>
<abstract>This JEP defines a protocol for establishing an out-of-band bytestream between any two Jabber entities.</abstract>
&LEGALNOTICE;
<number>0065</number>
<status>Draft</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>RFC 1928</spec>
<spec>RFC 3174</spec>
<spec>JEP-0030</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>bytestreams</shortname>
<schemaloc>
<url>http://jabber.org/protocol/bytestreams/bytestreams.xsd</url>
</schemaloc>
&dizzyd;
&linuxwolf;
&stpeter;
<revision>
<version>1.6</version>
<date>2004-11-12</date>
<initials>ds/psa</initials>
<remark>Added UDP support (OPTIONAL).</remark>
</revision>
<revision>
<version>1.5</version>
<date>2004-06-29</date>
<initials>psa</initials>
<remark>Added requirement to apply stringprep profiles before SHA1 hashing; added reference to RFC 3174.</remark>
</revision>
<revision>
<version>1.4</version>
<date>2004-06-28</date>
<initials>ds</initials>
<remark>Cleaned up narratives to reflect current practices and removed unnecessary authentication references; fixed mismatch SOCKS5 parameter table values.</remark>
</revision>
<revision>
<version>1.3</version>
<date>2003-09-24</date>
<initials>psa</initials>
<remark>Added disco#info &lt;identity/&gt; and corresponding Jabber Registrar submission; added XMPP error handling.</remark>
</revision>
<revision>
<version>1.2</version>
<date>2003-07-15</date>
<initials>rwe</initials>
<remark>Removed SIDs from the result queries, you should key off the IQ 'id' attribute instead. Added the disco exchange for finding available proxies.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2003-07-09</date>
<initials>ds</initials>
<remark>Changed srvid to zeroconf; cleaned up use cases; updated the schema.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2003-04-21</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
</revision>
<revision>
<version>0.7</version>
<date>2003-03-04</date>
<initials>psa</initials>
<remark>Clarified that this proposal uses an adaptation of the SOCKS5 protocol, not the full protocol; replaced DTD with schema; added security considerations.</remark>
</revision>
<revision>
<version>0.6</version>
<date>2003-01-27</date>
<initials>psa/ds</initials>
<remark>Added service discovery example; added 'srvid' attribute to streamhost element and required inclusion of either 'srvid' or 'port' attribute; improved the algorithms for generating SOCKS5 UNAME and PASSWD parameters; specified that the DST.ADDR and DST.PORT parameters may be ignored; removed references to connected/disconnected notification, bidirectional bytestreams, and multiple targets; updated implementation notes.</remark>
</revision>
<revision>
<version>0.5</version>
<date>2002-12-20</date>
<initials>psa</initials>
<remark>Specified option of "reversing the connection" (Target becomes Initiator); added more error cases; resurrected and cleaned up formal use case.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2002-12-19</date>
<initials>psa, mm</initials>
<remark>Added section on connected/disconnected notifications sent from Proxy to Initiator; cleaned up several examples; specified more error conditions; clarified the formal descriptions; added implementation notes and future considerations.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2002-12-17</date>
<initials>psa</initials>
<remark>Added lots of detail to the narrative and protocol.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2002-12-16</date>
<initials>ds</initials>
<remark>Added SOCKS info.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-12-13</date>
<initials>ds</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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:</p>
<ul>
<li>Bytestreams are established over standard TCP connections (&rfc0793;) or UDP associations (&rfc0768;), where TCP support is REQUIRED and UDP support is OPTIONAL</li>
<li>Sockets may be direct (peer-to-peer) or mediated (established through a bytestreaming service)</li>
<li>Where possible, standard wire protocols are used</li>
</ul>
<p>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.)</p>
</section1>
<section1 topic='Terminology' anchor='terms'>
<p>The following terms are used throughout this JEP.</p>
<table caption='Glossary of Entities'>
<tr>
<th>Term</th><th>Description</th>
</tr>
<tr>
<td>Initiator</td>
<td>A Jabber Entity that wishes to establish a bytestream with another Entity</td>
</tr>
<tr>
<td>Target</td>
<td>The Entity with which the Initiator is attempting to establish a bytestream</td>
</tr>
<tr>
<td>Proxy</td>
<td>A Jabber entity which is not NAT/Firewalled and is willing to be a middleman for the bytestream between the Initiator and the Target</td>
</tr>
<tr>
<td>StreamHost</td>
<td>The system that the Target connects to and that is "hosting" the bytestream -- may be either the Initiator or a Proxy</td>
</tr>
<tr>
<td>StreamID</td>
<td>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</td>
</tr>
</table>
</section1>
<section1 topic='Narrative' anchor='narrative'>
<p>There are two scenarios addressed by this protocol:</p>
<ol>
<li>direct connection (i.e., the StreamHost is the Initiator)</li>
<li>mediated connection (i.e., the StreamHost is a Proxy)</li>
</ol>
<p>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 <link url='#udp'>Optional UDP Support</link> section of this document.</p>
<section2 topic='Direct Connection' anchor='narr-direct'>
<p>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:</p>
<ol>
<li><p>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.</p></li>
<li><p>Target opens a TCP socket to the specified network address.</p></li>
<li><p>Target requests connection
via SOCKS5, with the DST.ADDR and DST.PORT parameters set to the values defined below.</p></li>
<li><p>StreamHost/Initiator sends acknowledgement of successful connection to Target via SOCKS5.</p></li>
<li><p>Target sends IQ-result to Initiator, preserving the 'id' of the initial IQ-set.</p></li>
<li><p>StreamHost/Initiator activates the bytestream.</p></li>
<li><p>Initiator and Target may begin using the bytestream.</p></li>
</ol>
</section2>
<section2 topic='Mediated Connection' anchor='narr-direct'>
<p>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:</p>
<ol>
<li><p>Optionally, Initiator discovers the network address of StreamHost in-band.</p></li>
<li><p>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.</p></li>
<li><p>Target opens a TCP socket to the selected StreamHost.</p></li>
<li><p>Target establishes connection via SOCKS5, with the DST.ADDR and DST.PORT parameters set to the values defined below.</p></li>
<li><p>StreamHost sends acknowledgement of successful connection to Target via SOCKS5.</p></li>
<li><p>Target sends IQ-result to Initiator, preserving the 'id' of the initial IQ-set.</p></li>
<li><p>Initiator opens a TCP socket at the StreamHost.</p></li>
<li><p>Initiator establishes connection via SOCKS5, with the DST.ADDR and DST.PORT parameters set to the values defined below.</p></li>
<li><p>StreamHost sends acknowledgement of successful connection to Initiator via SOCKS5.</p></li>
<li><p>Initiator sends IQ-set to StreamHost requesting that StreamHost activate the bytestream associated with the StreamID.</p></li>
<li><p>StreamHost activates the bytestream. (Data is now relayed between the two SOCKS5 connections by the proxy.)</p></li>
<li><p>StreamHost sends IQ-result to Initiator acknowledging that the bytestream has been activated (or specifying an error).</p></li>
<li><p>Initiator and Target may begin using the bytestream.</p></li>
</ol>
</section2>
</section1>
<section1 topic='Protocol' anchor='proto'>
<section2 topic='Initiator Queries Target Regarding Bytestreams Support' anchor='proto-disco'>
<p>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:</p>
<example caption='Initiator Sends Service Discovery Request to Target'><![CDATA[
<iq type='get'
from='initiator@host1/foo'
to='target@host2/bar'
id='hello'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<p>If the Target supports bytestreams, it MUST answer to that effect in the service discovery result.</p>
<example caption='Target Replies to Service Discovery Request'><![CDATA[
<iq type='result'
from='target@host2/bar'
to='initiator@host1/foo'
id='hello'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity
category='proxy'
type='bytestreams'
name='SOCKS5 Bytestreams Service'/>
...
<feature var='http://jabber.org/protocol/bytestreams'/>
...
</query>
</iq>
]]></example>
</section2>
<section2 topic='Initiator Queries Server For Proxies' anchor='proto-proxies'>
<p>Before attempting to initiate a bytestream, the Initiator needs to find a proxy. It may do so using Service Discovery as follows:</p>
<example caption='Initiator Sends Service Discovery Request to Server'><![CDATA[
<iq type='get'
from='initiator@host1/foo'
to='host1'
id='server_items'>
<query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
]]></example>
<p>The server will return all of the known JIDs in its disco list.</p>
<example caption='Server Replies to Service Discovery Request'><![CDATA[
<iq type='result'
from='host1'
to='initiator@host1/foo'
id='server_items'>
<query xmlns='http://jabber.org/protocol/disco#items'>
...
<item jid='proxy.host3' name='Bytestreams Proxy'/>
...
</query>
</iq>
]]></example>
</section2>
<section2 topic='Initiator Queries Proxy to Find Out if it is a Proxy' anchor='proto-proxyinfo'>
<p>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:</p>
<example caption='Initiator Sends Service Discovery Request to Proxy'><![CDATA[
<iq type='get'
from='initiator@host1/foo'
to='proxy.host3'
id='proxy_info'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<p>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".</p>
<example caption='Server Replies to Service Discovery Request'><![CDATA[
<iq type='result'
from='proxy.host3'
to='initiator@host1/foo'
id='proxy_info'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<identity category='proxy'
type='bytestreams'
name='SOCKS5 Bytestreams Service'/>
...
<feature var='http://jabber.org/protocol/bytestreams'/>
...
</query>
</iq>
]]></example>
</section2>
<section2 topic='Initiator Discovers Network Address of StreamHost' anchor='proto-address'>
<p>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:</p>
<example caption='Initiator Requests Network Address from Proxy'><![CDATA[
<iq type='get'
from='initiator@host1/foo'
to='proxy.host3'
id='discover'>
<query xmlns='http://jabber.org/protocol/bytestreams'/>
</iq>
]]></example>
<p>The &lt;streamhost/&gt; element specifying a network address MUST possess the following attributes:</p>
<ul>
<li><cite>jid</cite> = the JID of the StreamHost for communications over Jabber</li>
</ul>
<p>In addition, the &lt;streamhost/&gt; element MUST include:</p>
<p>EITHER</p>
<ul>
<li><cite>host</cite> = the hostname or IP address of the StreamHost for SOCKS5 communications over TCP</li>
<li><cite>port</cite> = a port associated with the hostname or IP address for
SOCKS5 communications over TCP</li>
</ul>
<p>OR</p>
<ul>
<li><cite>zeroconf</cite> = a zeroconf <note>Zeroconf is a set of protocols that enable IP networking without the need for configuration. For further information, refer to &lt;<link url='http://www.zeroconf.org/'>http://www.zeroconf.org/</link>&gt;.</note> identifier to which an entity may connect, for which the service identifier and protocol name SHOULD be "_jabber.bytestreams".</li>
</ul>
<example caption='Proxy Informs Initiator of Network Address'><![CDATA[
<iq type='result'
from='proxy.host3'
to='initiator@host1/foo'
id='discover'>
<query xmlns='http://jabber.org/protocol/bytestreams'>
<streamhost
jid='proxy.host3'
host='24.24.24.1'
zeroconf='_jabber.bytestreams'/>
</query>
</iq>
]]></example>
<p>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;):</p>
<example caption='Proxy Returns Error to Initiator'><![CDATA[
<iq type='error'
from='initiator@host1/foo'
to='proxy.host3'
id='discover'>
<query xmlns='http://jabber.org/protocol/bytestreams'/>
<error code='403' type='auth'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>If the Proxy is unable to act as a StreamHost, the Proxy SHOULD return a &notallowed; error to the Initiator:</p>
<example caption='Proxy Returns Error to Initiator'><![CDATA[
<iq type='error'
from='initiator@host1/foo'
to='proxy.host3'
id='discover'>
<query xmlns='http://jabber.org/protocol/bytestreams'/>
<error code='405' type='cancel'>
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section2>
<section2 topic='Initiator Informs Target of StreamHosts' anchor='proto-inform'>
<p>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:</p>
<ul>
<li>The network address of at least one StreamHost to which the Target may attempt to connect</li>
<li>The Stream ID for this connection</li>
<li>The "mode" to use, normally "tcp" but optionally "udp" (see the <link url='#udp'>Optional UDP Support</link> section of this document)</li>
</ul>
<p>The protocol format is shown below.</p>
<example caption='Initiation of Interaction'><![CDATA[
<iq type='set'
from='initiator@host1/foo'
to='target@host2/bar'
id='initiate'>
<query xmlns='http://jabber.org/protocol/bytestreams'
sid='mySID'
mode='tcp'>
<streamhost
jid='initiator@host1/foo'
host='192.168.4.1'
port='5086'/>
<streamhost
jid='proxy.host3'
host='24.24.24.1'
zeroconf='_jabber.bytestreams'/>
</query>
</iq>
]]></example>
<p>If the Target is unwilling to accept the bytestream, it MUST return a &notacceptable; error to the Initiator.</p>
<example caption='Target Refuses Bytestream'><![CDATA[
<iq type='error'
from='target@host2/bar'
to='initiator@host1/foo'
id='initiate'>
<error code='406' type='auth'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section2>
<section2 topic='Target Establishes SOCKS5 Connection with StreamHost' anchor='proto-establish'>
<p>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.</p>
<p>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 &notfound; error to the Initiator.</p>
<example caption='Target Is Unable to Connect to Any StreamHost and Wishes to End Transaction'><![CDATA[
<iq type='error'
from='target@host2/bar'
to='initiator@host1/foo'
id='initiate'>
<error code='404' type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>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.</p>
<p>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., &lt;user@host/resource&gt;); 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.</p>
<example caption='Target Connects to StreamHost'><![CDATA[
CMD = X'01'
ATYP = X'03'
DST.ADDR = SHA1 Hash of: (SID + Initiator JID + Target JID)
DST.PORT = 0
]]></example>
<example caption='StreamHost Acknowledges Connection'><![CDATA[
STATUS = X'00'
]]></example>
<!--
<example caption='StreamHost Acknowledges Request'><![CDATA[
STATUS = X'00'
]]></example>
-->
</section2>
<section2 topic='Target Acknowledges SOCKS5 Connection' anchor='proto-ack'>
<p>After the Target has authenticated with the StreamHost, it MUST send an IQ-result to the Initiator indicating which StreamHost was used.</p>
<example caption='Target Notifies Initiator of Connection'><![CDATA[
<iq type='result'
from='target@host2/bar'
to='initiator@host1/foo'
id='initiate'>
<query xmlns='http://jabber.org/protocol/bytestreams'>
<streamhost-used jid='proxy.host3'/>
</query>
</iq>
]]></example>
<p>At this point, the Initiator knows which StreamHost was used by
the Target.</p>
</section2>
<section2 topic='Initiator Establishes SOCKS5 Connection with StreamHost' anchor='proto-initiator'>
<p>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.</p>
</section2>
<section2 topic='Activation of Bytestream' anchor='proto-activation'>
<p>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 &lt;activate/&gt; element whose XML character data specifies the full JID of the Target.</p>
<example caption='Initiator Requests Activation of Bytestream'><![CDATA[
<iq type='set'
from='initiator@host1/foo'
to='proxy.host3'
id='activate'>
<query xmlns='http://jabber.org/protocol/bytestreams' sid='mySID'>
<activate>target@host2/bar</activate>
</query>
</iq>
]]></example>
<p>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.</p>
<p>If the Proxy can fulfill the request, it MUST then respond to the Initiator with an IQ-result.</p>
<example caption='Proxy Informs Initiator of Activation'><![CDATA[
<iq type='result'
from='proxy.host3'
to='initiator@host1/foo'
id='activate'/>
]]></example>
<p>The Proxy MUST then send SOCKS5 acknowledgement of the connection to the Target.</p>
<example caption='StreamHost Acknowledges Connection to Target'><![CDATA[
STATUS = X'00'
]]></example>
<p>If the Proxy cannot fulfill the request, it MUST return an IQ-error to the Initiator; the following conditions are defined:</p>
<ul>
<li>&notfound; error if the from address does not match that of the Initiator's full JID</li>
<li>&notallowed; error if only one party (either Initiator or Recipient, but not both) is connected to the Proxy</li>
<li>&internalserver; error if the proxy cannot activate the bytestream because of some internal malfunction</li>
</ul>
</section2>
</section1>
<section1 topic='Formal Use Case' anchor='usecase'>
<p>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".)</p>
<section2 topic='Primary Flow' anchor='usecase-primary'>
<ol>
<li>Initiator wishes to establish a bytestream with Target</li>
<li>Initiator sends an IQ-set to Target specifying a StreamID and the network addresses of one or more StreamHosts [A1]</li>
<li>Target wishes to establish a bytestream with Initiator [A2]</li>
<li>Target requests TCP connection with a StreamHost [A3]</li>
<li>Target receives TCP acknowledgement from StreamHost [A4]</li>
<li>Target provides authentication credentials to StreamHost via SOCKS5</li>
<li>Target receives acknowledgement of authentication with StreamHost via SOCKS5 [A5]</li>
<li>Target requests connection with StreamHost via SOCKS5</li>
<li>Target receives acknowledgement of successful connection with StreamHost via SOCKS5 [A7]</li>
<li>Target sends IQ-result to Initiator announcing successful connection to StreamHost [A6]</li>
<li>Use Case Ends (bytestream is established and ready for use)</li>
</ol>
</section2>
<section2 topic='Alternate Flows' anchor='usecase-alternate'>
<p><cite>A1.</cite> Initiator does not know the full network address of a StreamHost (i.e., Proxy)</p>
<ol>
<li>Initiator sends IQ-get to Proxy</li>
<li>Initiator receives IQ-result from Proxy containing network address [A9][A10]</li>
<li>Return to P2</li>
</ol>
<p><cite>A2.</cite> Target does not wish to establish a bytestream with Initiator</p>
<ol>
<li>Initiator receives &notacceptable; error from Target</li>
<li>UCE unsuccessfully</li>
</ol>
<p><cite>A3.</cite> No more StreamHosts in list (Target is unable to reach any of the provided StreamHosts)</p>
<ol>
<li>Target returns &remoteserver; error to Initiator</li>
<li>UCE unsuccessfully</li>
</ol>
<p><cite>A4.</cite> Target cannot reach StreamHost</p>
<ol>
<li>Return to P4</li>
</ol>
<p><cite>A5.</cite> Target authentication with StreamHost fails</p>
<ol>
<li>Return to P4</li>
</ol>
<p><cite>A6.</cite> Proxy is unwilling to act as a StreamHost for Initiator</p>
<ol>
<li>Initiator receives &forbidden; error from Proxy</li>
<li>Return to P2</li>
</ol>
<p><cite>A7.</cite> Proxy is unable to act as a StreamHost for Initiator</p>
<ol>
<li>Initiator receives &notallowed; error from Proxy</li>
<li>Return to P2</li>
</ol>
<p><cite>A8.</cite> Target connects to a Proxy</p>
<ol>
<li>Initiator reaches Proxy [A9]</li>
<li>Target receives TCP acknowledgement from StreamHost [A9]</li>
<li>Initiator authenticates with Proxy via SOCKS5</li>
<li>Initiator receives acknowledgement of authentication with Proxy via SOCKS5 [A10]</li>
<li>Initiator requests connection with Proxy via SOCKS5</li>
<li>Initiator receives acknowledgement of successful connection with Proxy via SOCKS5 [A11]</li>
<li>Initiator sends IQ-set to Proxy requesting activation of bytestream</li>
<li>Initiator receives IQ-result from Proxy acknowledging activation of bytestream [A12]</li>
<li>Return to P9</li>
</ol>
<p><cite>A9.</cite> Initiator is unable to reach Proxy</p>
<ol>
<li>UCE unsuccessfully</li>
</ol>
<p><cite>A10.</cite> Initiator is unable to authenticate with Proxy</p>
<ol>
<li>UCE unsuccessfully</li>
</ol>
<p><cite>A11.</cite> Initiator is unable to connect to Proxy</p>
<ol>
<li>UCE unsuccessfully</li>
</ol>
<p><cite>A12.</cite> Proxy is unable to activate bytestream</p>
<ol>
<li>Initiator receives &internalserver; error from Proxy</li>
<li>UCE unsuccessfully</li>
</ol>
</section2>
</section1>
<section1 topic='Formal Description' anchor='desc'>
<section2 topic='&lt;query/&gt; Element' anchor='desc-query'>
<p>The &lt;query/&gt; 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 &lt;streamhost/&gt; elements, a single &lt;streamhost-used/&gt; element, or a single &lt;activate/&gt; element.</p>
<p>The "sid" specifies the bytestream session identifier. This attribute MUST be present. The value of this attribute is any character data.</p>
<p>The "mode" specifies the mode to use, either 'tcp' or 'udp'. If this attribute is missing, the default value of "tcp" MUST be assumed.</p>
<p>The &lt;streamhost/&gt; 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.</p>
<p>The &lt;streamhost-used/&gt; 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.</p>
<p>The &lt;activate/&gt; 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.</p>
</section2>
<section2 topic='&lt;streamhost/&gt; Element' anchor='desc-streamhost'>
<p>The &lt;streamhost/&gt; 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.</p>
<p>The "jid" attribute specifies the StreamHost's JID. This attribute MUST be present, and MUST be a valid JID for use with an &lt;iq/&gt;.</p>
<p>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").</p>
<p>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.</p>
<p>The "zeroconf" attribute specifies the zero-configuration service available for bytestreaming. This attribute SHOULD be present. The value SHOULD be '_jabber.bytestreams'.</p>
<p>When communicating the available hosts, the Initiator MUST include EITHER the host and port OR the zeroconf information.</p>
</section2>
<section2 topic='&lt;streamhost-used/&gt; Element' anchor='desc-streamhost-used'>
<p>The &lt;streamhost-used/&gt; 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.</p>
<p>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 &lt;iq/&gt;.</p>
</section2>
<section2 topic='&lt;activate/&gt; Element' anchor='desc-activate'>
<p>The &lt;activate/&gt; element is a flag to trigger a Proxy to complete a connection.</p>
</section2>
</section1>
<section1 topic='Optional UDP Support' anchor='udp'>
<p>Support for UDP associations is strictly OPTIONAL. However, implementations that support UDP associations MUST adhere to the profile described in this section.</p>
<section2 topic='Discovering UDP Support' anchor='udp-disco'>
<p>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 <cite>Service Discovery</cite> information requests.</p>
<example caption='Initiator Sends Service Discovery Request to Target'><![CDATA[
<iq type='get'
from='initiator@host1/foo'
to='target@host2/bar'
id='hello2'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<p>If the Target supports UDP associations, it MUST answer to that effect in the service discovery result.</p>
<example caption='Target Replies to Service Discovery Request'><![CDATA[
<iq type='result'
from='target@host2/bar'
to='initiator@host1/foo'
id='hello2'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity
category='proxy'
type='bytestreams'
name='SOCKS5 Bytestreams Service'/>
...
<feature var='http://jabber.org/protocol/bytestreams'/>
<feature var='http://jabber.org/protocol/bytestreams#udp'/>
...
</query>
</iq>
]]></example>
</section2>
<section2 topic='Requesting UDP Mode' anchor='udp-request'>
<p>UDP associations are requested by setting the 'mode' attribute to a value of "udp" rather than "tcp".</p>
<example caption='Initiation of Interaction (UDP)'><![CDATA[
<iq type='set'
from='initiator@host1/foo'
to='target@host2/bar'
id='initiate'>
<query xmlns='http://jabber.org/protocol/bytestreams'
sid='mySID'
mode='udp'>
<streamhost
jid='initiator@host1/foo'
host='192.168.4.1'
port='5086'/>
</query>
</iq>
]]></example>
</section2>
<section2 topic='UDP Process' anchor='udp-process'>
<p>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:</p>
<ul>
<li>If direct connection is followed, Target MUST complete UDP association and initialization of the UDP channel before informing Initiator of success via the &lt;streamhost-used/&gt; element.</li>
<li>If mediated connection is followed, (1) Target MUST complete UDP association and initialization of the UDP channel before informing Initiator of success via the &lt;streamhost-used/&gt; element, and (2) Initiator MUST complete UDP association and initialization of the UDP channel before asking StreamHost to activate the bytestream.</li>
</ul>
<p>The processes for establishing the UDP association and for initializing the UDP channel are described below.</p>
<section3 topic='Establishing the UDP Association' anchor='udp-process-assoc'>
<p>Once the Target has successfully authenticated with the Proxy (as described under <link url='#proto-establish'>Target Establishes SOCKS5 Connection with StreamHost</link>), it MUST send a UDP ASSOCIATE (rather than CONNECT) request to the host identified by the algorithm defined above.</p>
<example caption='Target Requests UDP Association with StreamHost'><![CDATA[
CMD = X'03'
ATYP = X'03'
DST.ADDR = SHA1 Hash of: (SID + Initiator JID + Target JID)
DST.PORT = 0
]]></example>
<p>The StreamHost then acknowledges this request:</p>
<example caption='StreamHost Acknowledges Request'><![CDATA[
STATUS = X'00'
]]></example>
</section3>
<section3 topic='Initializing the UDP Channel' anchor='udp-process-init'>
<p>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).</p>
<example caption='Target or Initiator Sends UDP Initialization Packet to StreamHost'><![CDATA[
ATYP = X'03'
DST.ADDR = SHA1 Hash of: (SID + Initiator JID + Target JID)
DST.PORT = 1
DATA = Target or Initiator JID
]]></example>
<p>Upon successful receipt by the StreamHost, the StreamHost MUST reply with a message notification indicating success:</p>
<example caption='StreamHost Notifies Target or Initiator of UDP Success'><![CDATA[
<message
from='proxy.host3'
to='target@host2/bar'
id='initiate'>
<udpsuccess xmlns='http://jabber.org/protocol/bytestreams' dstaddr='Value of Hash'/>
</message>
]]></example>
<p>The &lt;udpsuccess/&gt; 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.</p>
<p>If Target is unable to initialize the UDP channel, it MUST return a &remoteserver; error to Initiator.</p>
<p>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.</p>
</section3>
</section2>
<section2 topic='Exchanging UDP Packets' anchor='udp-ports'>
<p>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".</p>
<p>For all packets sent to the StreamHost, DST.PORT is set to 0, and DATA contains the payload.</p>
<example caption='Sending UDP to StreamHost'><![CDATA[
ATYP = X'03'
DST.ADDR = SHA1 Hash of: (SID + Initiator JID + Target JID)
DST.PORT = 0
DATA = (payload)
]]></example>
<p>UDP packets sent from the StreamHost do not have any SOCKS5 headers, and so the payload should be delivered as-is.</p>
<p>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.</p>
</section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<section2 topic='StreamHost Requirements' anchor='impl-streamhost'>
<p>A StreamHost MUST support TCP connections.</p>
<p>A StreamHost SHOULD:</p>
<ol>
<li>Allow bi-directional bytestreaming between the Initiator and Target.</li>
<li>Allow only one Target to connect to a bytestream (i.e., disallow multicasting).</li>
<li>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.</li>
<li>Ignore but not drop any bytes sent before the bytestream is activated.</li>
<li>Prefer to use zero-configuration IP networking if supported.</li>
</ol>
<p>A StreamHost MAY:</p>
<ol>
<li>Support UDP associations in addition TCP connections.</li>
<li>Ignore the DST.ADDR and DST.PORT parameters if desired.</li>
</ol>
</section2>
<section2 topic='SOCKS5 Parameter Mapping' anchor='impl-socks5'>
<p>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.</p>
<table caption='Request/Parameter Mapping for CONNECT'>
<tr><th>Parameter</th><th>Value</th></tr>
<tr><td>CMD</td><td>1 (CONNECT)</td></tr>
<tr><td>ATYP</td><td>1 (IP V4), 3 (DOMAINNAME), or 4 (IP V6)</td></tr>
<tr><td>DST.ADDR</td><td>SHA1 Hash of: (SID + Initiator JID + Target JID)</td></tr>
<tr><td>DST.PORT</td><td>0</td></tr>
</table>
<table caption='Request/Parameter Mapping for UDP ASSOCIATE'>
<tr><th>Parameter</th><th>Value</th></tr>
<tr><td>CMD</td><td>3 (UDP ASSOCIATE)</td></tr>
<tr><td>ATYP</td><td>1 (IP V4), 3 (DOMAINNAME), or 4 (IP V6)</td></tr>
<tr><td>DST.ADDR</td><td>SHA1 Hash of: (SID + Initiator JID + Target JID)</td></tr>
<tr><td>DST.PORT</td><td>0</td></tr>
</table>
<table caption='Request/Parameter Mapping for UDP Packets'>
<tr><th>Parameter</th><th>Value</th></tr>
<tr><td>ATYP</td><td>1 (IP V4), 3 (DOMAINNAME), or 4 (IP V6)</td></tr>
<tr><td>DST.ADDR</td><td>SHA1 Hash of: (SID + Initiator JID + Target JID)</td></tr>
<tr><td>DST.PORT</td><td>0 or 1, for payload or initialization packets, respectively.</td></tr>
</table>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>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.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; includes 'http://jabber.org/protocol/bytestreams' in its registry of protocol namespaces.</p>
</section2>
<section2 topic='Service Discovery Features' anchor='registrar-discovar'>
<p>The Jabber Registrar shall includes 'http://jabber.org/protocol/bytestreams#udp' in its registry of service discovery features.</p>
</section2>
<section2 topic='Service Discovery Category/Type' anchor='registrar-discoid'>
<p>The Jabber Registrar includes the "proxy" category and associated "bytestreams" type in the Service Discovery registry. The registry submission is as follows:</p>
<code><![CDATA[
<category>
<name>proxy</name>
<desc>Proxy servers or services</desc>
<type>
<name>bytestreams</name>
<desc>A proxy for SOCKS5 bytestreams</desc>
<doc>JEP-0065</doc>
</type>
</category>
]]></code>
</section2>
</section1>
<section1 topic='Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/bytestreams'
xmlns='http://jabber.org/protocol/bytestreams'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0065: http://www.jabber.org/jeps/jep-0065.html
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:choice>
<xs:element ref='streamhost' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='streamhost-used' minOccurs='0'/>
<xs:element name='activate' type='empty' minOccurs='0'/>
</xs:choice>
<xs:attribute name='sid' type='xs:string' use='optional'/>
<xs:attribute name='mode' use='optional' default='tcp'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='tcp'/>
<xs:enumeration value='udp'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name='streamhost'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='jid' type='xs:string' use='required'/>
<xs:attribute name='host' type='xs:string' use='required'/>
<xs:attribute name='zeroconf' type='xs:string' use='optional'/>
<xs:attribute name='port' type='xs:string' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='udpsuccess'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='dstaddr' type='xs:string' use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='streamhost-used'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='jid' type='xs:string' use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
</jep>

294
xep-0066.xml Normal file
View File

@ -0,0 +1,294 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Out of Band Data</title>
<abstract>This document provides canonical documentation of two XMPP protocol extensions for communicating URIs.</abstract>
&LEGALNOTICE;
<number>0066</number>
<status>Draft</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>oob</shortname>
<schemaloc>
<ns>jabber:iq:oob</ns>
<url>http://jabber.org/protocol/oob/iq-oob.xsd</url>
</schemaloc>
<schemaloc>
<ns>jabber:x:oob</ns>
<url>http://jabber.org/protocol/oob/x-oob.xsd</url>
</schemaloc>
&stpeter;
<revision>
<version>1.5</version>
<date>2006-08-16</date>
<initials>psa</initials>
<remark><p>Per a vote of the Jabber Council, converted to Standards Track.</p></remark>
</revision>
<revision>
<version>1.4</version>
<date>2006-01-11</date>
<initials>psa</initials>
<remark><p>Removed example of including URL in presence stanza.</p></remark>
</revision>
<revision>
<version>1.3</version>
<date>2004-10-18</date>
<initials>psa</initials>
<remark><p>Added non-normative section on integration with stream initiation (JEP-0095); added optional sid attribute to jabber:iq:oob schema.</p></remark>
</revision>
<revision>
<version>1.2</version>
<date>2004-04-13</date>
<initials>psa</initials>
<remark><p>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.</p></remark>
</revision>
<revision>
<version>1.1</version>
<date>2004-02-10</date>
<initials>psa</initials>
<remark><p>Editorial adjustments and clarifications; added references to relevant RFCs.</p></remark>
</revision>
<revision>
<version>1.0</version>
<date>2003-10-08</date>
<initials>psa</initials>
<remark><p>Per a vote of the Jabber Council, changed status to Active.</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-06-22</date>
<initials>psa</initials>
<remark><p>Made several small editorial changes; added XML schemas.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-01-08</date>
<initials>psa</initials>
<remark><p>Added information about non-HTTP URIs.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-12-16</date>
<initials>psa</initials>
<remark><p>Initial version.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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.</p>
</section1>
<section1 topic='jabber:iq:oob' anchor='iq-oob'>
<p>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;.</p>
<p>To initiate an out-of-band file transfer with an intended recipient using the 'jabber:iq:oob' namespace (whether or not negotiated via <cite>JEP-0096</cite>), 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 &lt;url/&gt; child specifying the URL of the file to be transferred, and MAY contain an optional &lt;desc/&gt; child describing the file. This usage is shown in the following example.</p>
<example caption="Sender Initiates Request-Response"><![CDATA[
<iq type='set'
from='stpeter@jabber.org/work'
to='MaineBoy@jabber.org/home'
id='oob1'>
<query xmlns='jabber:iq:oob'>
<url>http://www.jabber.org/images/psa-license.jpg</url>
<desc>A license to Jabber!</desc>
</query>
</iq>
]]></example>
<p>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):</p>
<example caption="Recipient Informs Sender of Success"><![CDATA[
<iq type='result'
from='MaineBoy@jabber.org/home'
to='stpeter@jabber.org/work'
id='oob1'/>
]]></example>
<p>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:</p>
<example caption="Recipient Informs Sender of Failure"><![CDATA[
<iq type='error'
from='MaineBoy@jabber.org/home'
to='stpeter@jabber.org/work'
id='oob1'>
<query xmlns='jabber:iq:oob'>
<url>http://www.jabber.org/images/psa-license.jpg</url>
<desc>A license to Jabber!</desc>
</query>
<error code='404' type='cancel'>
<not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>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:</p>
<example caption="Recipient Rejects Request"><![CDATA[
<iq type='error'
from='MaineBoy@jabber.org/home'
to='stpeter@jabber.org/work'
id='oob1'>
<query xmlns='jabber:iq:oob'>
<url>http://www.jabber.org/images/psa-license.jpg</url>
<desc>A license to Jabber!</desc>
</query>
<error code='406' type='modify'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section1>
<section1 topic='jabber:x:oob' anchor='x-oob'>
<p>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 &lt;url/&gt; child specifying the URL of the resource, and MAY contain an optional &lt;desc/&gt; child describing the resource.</p>
<example caption="Sender Communicates a URI"><![CDATA[
<message from='stpeter@jabber.org/work'
to='MaineBoy@jabber.org/home'>
<body>Yeah, but do you have a license to Jabber?</body>
<x xmlns='jabber:x:oob'>
<url>http://www.jabber.org/images/psa-license.jpg</url>
</x>
</message>
]]></example>
</section1>
<section1 topic='Use With Non-HTTP URI Schemes' anchor='nonhttp'>
<p>The value of the &lt;url/&gt; 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 &lt;url/&gt; element is a valid URI (as specified by &rfc3986;).</p>
</section1>
<section1 topic='Integration With Stream Initiation' anchor='si'>
<p><em>This section is non-normative.</em></p>
<p>&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.</p>
<p>A sample protocol flow is shown below.</p>
<example caption='Stream Initiation Offer'>
<![CDATA[
<iq type='set'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/chamber'
id='offer1'>
<si xmlns='http://jabber.org/protocol/si'
id='a0'
mime-type='text/plain'
profile='http://jabber.org/protocol/si/profile/file-transfer'>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'/>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'>
<field var='stream-method' type='list-single'>
<option><value>http://jabber.org/protocol/bytestreams</value></option>
<option><value>http://jabber.org/protocol/ibb</value></option>
<option><value>jabber:iq:oob</value></option>
</field>
</x>
</feature>
</si>
</iq>
]]>
</example>
<example caption='Stream Initiation Result'>
<![CDATA[
<iq type='result'
from='juliet@capulet.com/chamber'>
to='romeo@montague.net/orchard'
id='offer1'>
<si xmlns='http://jabber.org/protocol/si'
id='a0'
profile='http://jabber.org/protocol/si/profile/file-transfer'>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='stream-method'>
<value>jabber:iq:oob</value>
</field>
</x>
</feature>
</si>
</iq>
]]>
</example>
<example caption="Sender Initiates Request-Response"><![CDATA[
<iq type='set'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/chamber'>
id='send1'>
<query xmlns='jabber:iq:oob'
sid='a0'>
<url>http://www.shakespeare.lit/files/letter.txt</url>
</query>
</iq>
]]></example>
<example caption="Recipient Informs Sender of Success"><![CDATA[
<iq type='result'
from='juliet@capulet.com/chamber'>
to='romeo@montague.net/orchard'
id='send1'/>
]]></example>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>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).</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<p>The 'jabber:iq:oob' and 'jabber:x:oob' namespaces are included in the protocol namespaces registry maintained by the &REGISTRAR; (see &NAMESPACES;).</p>
</section1>
<section1 topic='XML Schemas' anchor='schemas'>
<section2 topic='jabber:iq:oob' anchor='schemas-iq'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:iq:oob'
xmlns='jabber:iq:oob'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0066: http://www.jabber.org/jeps/jep-0066.html
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:sequence>
<xs:element name='url' type='xs:string' minOccurs='1'/>
<xs:element name='desc' type='xs:string' minOccurs='0'/>
</xs:sequence>
<xs:attribute name='sid' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section2>
<section2 topic='jabber:x:oob' anchor='schemas-x'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:x:oob'
xmlns='jabber:x:oob'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0066: http://www.jabber.org/jeps/jep-0066.html
</xs:documentation>
</xs:annotation>
<xs:element name='x'>
<xs:complexType>
<xs:sequence>
<xs:element name='url' type='xs:string' minOccurs='1'/>
<xs:element name='desc' type='xs:string' minOccurs='0'/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section2>
</section1>
</jep>

200
xep-0067.xml Normal file
View File

@ -0,0 +1,200 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Stock Data Transmission</title>
<abstract>This JEP specifies a data format for stock data distribution in the Jabber community.</abstract>
&LEGALNOTICE;
<number>0067</number>
<status>Deferred</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>JEP-0060</dependencies>
<author>
<firstname>Ulrich</firstname>
<surname>Staudinger</surname>
<email>chicago5@gmx.de</email>
<jid>uls@jabber.org</jid>
</author>
<revision>
<version>0.3</version>
<date>2003-07-19</date>
<initials>uls</initials>
<remark>Added transmission in messages</remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-01-26</date>
<initials>uls</initials>
<remark>Added ISO-8601 time scheme, added symbols, fixed typos.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-01-12</date>
<initials>uls</initials>
<remark>Initial Release</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>
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.
</p>
<p>
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.
</p>
<p>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.
</p></section1>
<section1 topic="Realtime data distribution">
<p>
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.
</p>
<example caption='Component distributes realtime share value ticker data'><![CDATA[
<iq from='stockgate@way.com' to='publish@gate.way' type='set' id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='stocks/WEB2T.DE/realtime'>
<item id='some'>
<realtime>
<symbol>web2t.de</symbol>
<name>Web.de Xetra</name>
<time>04-06-2002T12:12:12</time>
<value>0.57</value>
<volume>10000</volume>
<bid>0.56</bid>
<ask>0.60</ask>
<bidsize>-1</bidsize>
<asksize>-1</asksize>
</realtime>
</item>
</publish>
</pubsub>
</iq>
]]></example>
<example caption='A client recieves realtime stock value data'><![CDATA[
<iq from='stockgate@way.com' to='publish@gate.way' type='set' id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='stocks/WEB2T.DE/realtime'>
<item id='some'>
<realtime>
<symbol>web2t.de</symbol>
<name>Web.de Xetra</name>
<time>04-06-2002T19:12:12</time>
<value>0.57</value>
<volume>10000</volume>
<bid>0.56</bid>
<ask>0.60</ask>
<bidsize>1000</bidsize>
<asksize>2000</asksize>
</realtime>
</item>
</publish>
</pubsub>
</iq>
]]></example>
<example caption="A client recieves data in a message chunk">
<![CDATA[
<message from='cerberus@jabber.org'>
<x xmlns='http://www.jabber.org/jeps/jep-0067.html'>
<realtime>
<symbol>^GDAXI</symbol>
<name>DAX</name>
<time>07-07-2003T12:00:00</time>
<value>3200</value>
<bid>-1</bid>
<ask>-1</bid>
<bidsize>-1</bidsize>
<asksize>-1</asksize>
</realtime>
</x>
</message>
]]>
</example>
</section1>
<section1 topic="Distribution of barchart, time framed stock value data ">
<p>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. </p>
<p>If a value is not available, the value MUST be set to '-1'. </p>
<p>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.
</p>
<p>
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.
</p>
<example caption='Component distributes realtime barcharted share value ticker data'><![CDATA[
<iq from='stockgate@way.com' to='publish@gate.way' type='set' id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='stocks/WEB2T.DE/bar/0:0:0:0:15:0'>
<item id='some'>
<bar>
<symbol>web2t.de</symbol>
<name>Web.de Xetra</name>
<time>04-06-2002T19:01:00</time>
<timespan>0:0:0:0:15:0</timespan>
<open>0.52</open>
<hi>0.8</hi>
<low>0.2</low>
<close>0.51</close>
<volume>10000</volume>
</bar>
</item>
</publish>
</pubsub>
</iq>
]]></example>
<p>
Similar to section 2, timeframed data MAY be transmitted in a message element.
</p>
</section1>
<section1 topic="Distribution of share/stock specific news">
<p>
Another important part in a stock system is distribution of stock/share specific news.
</p>
<p>
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.
</p>
<example caption='Component publishes share/stock specific news'><![CDATA[
<iq from='stockgate@way.com' to='publish@gate.way' type='rset' id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='stocks/WEB2T.DE/news'>
<item id='some'>
<stocknews>
<symbol>web2t.de</symbol>
<time>04-06-2002T21:10:00</time>
<subject>Web.de looses employees</subject>
<body>Web.de looses 99% of all employees! Employees went on strike and did a collective quit.</body>
<source>Web.de PR</source>
</stocknews>
</item>
</publish>
</pubsub>
</iq>
]]></example>
</section1>
<section1 topic="Known implementations">
<p>
Greenthumb (http://greenthumb.jabberstudio.org) supports reception of stock ticker data.
</p>
<p>
The 'StockComponent' (http://www.die-horde.de) is a partial component implementation.
</p>
</section1>
</jep>

374
xep-0068.xml Normal file
View File

@ -0,0 +1,374 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Field Standardization for Data Forms</title>
<abstract>This JEP specifies how to standardize field variables used in the context of jabber:x:data forms.</abstract>
&LEGALNOTICE;
<number>0068</number>
<status>Active</status>
<type>Informational</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>JEP-0004</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>formtypes</shortname>
<registry/>
&hildjj;
&stpeter;
<revision>
<version>1.1</version>
<date>2004-07-07</date>
<initials>psa</initials>
<remark>Specified ability to standardize field option values.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2003-08-18</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Active.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-06-05</date>
<initials>psa</initials>
<remark>Specified rules regarding registration and naming of FORM_TYPEs and associated fields.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-05-09</date>
<initials>psa</initials>
<remark>Clarified the relation of FORM_TYPE to registered namespaces; defined registry format; added IQ example.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-01-22</date>
<initials>jjh</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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).</p>
<p>The 'jabber:x:data' namespace provides an adequate mechanism for both of these uses, as long as computer processes can rely on the var=&quot;&quot; names on a particular type of form.</p>
<p>This JEP proposes a specific mechanism for the &REGISTRAR; 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.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<ol>
<li>Forms must continue to be presentable to humans for data entry.</li>
<li>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.</li>
<li>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).</li>
<li>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.</li>
<li>Forms that are not directed <em>to</em> 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).</li>
<li>Forms must continue to be flexible for implementations; unknown future expansion fields must not be limited.</li>
<li>The chosen approach must work for forms embedded in messages as well as in IQs.</li>
</ol>
</section1>
<section1 topic='Approach' anchor='approach'>
<section2 topic='Overview' anchor='approach-overview'>
<p>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".</p>
</section2>
<section2 topic='Whether to Register' anchor='approach-register'>
<p>The first decision-point is whether a FORM_TYPE needs to be registered with the Jabber Registrar. The following rules apply:</p>
<ol>
<li>If the FORM_TYPE is used in the context of a form defined in a JEP, it MUST be registered.</li>
<li>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.</li>
<li>If the FORM_TYPE is used in the context of a custom protocol, it MAY be registered.</li>
</ol>
</section2>
<section2 topic='Naming Convention' anchor='approach-naming'>
<p>While the value of the FORM_TYPE attribute SHOULD be considered an opaque string from the application perspective, the following rules apply:</p>
<ol>
<li>For custom protocols, the name SHOULD be an HTTP URI that is managed by the namespace "owner".</li>
<li>For all new protocols approved by the JSF, the name MUST be an HTTP URI or IETF-style URN.</li>
<li>For "legacy" protocols managed by the JSF, the name SHOULD use the old-style "jabber:*:*" format.</li>
</ol>
</section2>
<section2 topic='Field Names' anchor='approach-fieldnames'>
<p>For FORM_TYPEs that are registered with the Jabber Registrar, the field names MUST conform to one of the following two conditions:</p>
<ol>
<li>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.</li>
<li>If the field name is unregistered, the field name MUST begin with "x-".</li>
</ol>
<p>If the FORM_TYPE is not registered, the field name MAY have any name (presumably managed by the namespace "owner").</p>
</section2>
<section2 topic='Field Values' anchor='approach-values'>
<p>Field values may also be registered; refer to the <link url='registrar'>Jabber Registrar</link> section of this document.</p>
</section2>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Unspecified Form' anchor='usecases-unspecified'>
<p>These are forms that do not have a hidden field of name FORM_TYPE.
Existing processing rules still apply.</p>
<example caption='Message with no FORM_TYPE'><![CDATA[
<message
from='juliet@capulet.com/balcony'
to='romeo@montague.net/garden'>
<thread>vote-thread-reatmon-134</thread>
<x xmlns='jabber:x:data' type='form'>
<title>Vote #134</title>
<instructions>
This is the vote to pick a new mascot.
Thanks for your time!
</instructions>
<field var='mascot' type='list-single'>
<required/>
<option label='Light Bulb'><value>light_bulb</value></option>
<option label='Penguin'><value>penguin</value></option>
<option label='Moose'><value>moose</value></option>
<option label='Triangle Man'><value>triangle_man</value></option>
<option label='Other'><value>other</value></option>
</field>
</x>
</message>
]]></example>
</section2>
<section2 topic='Correctly Specified FORM_TYPE' anchor='usecases-correct'>
<p>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.</p>
<example caption='Message with FORM_TYPE'><![CDATA[
<message to="node-owner" from="pubsub.jabber.org">
<x xmlns="jabber:x:data" type="form">
<title>PubSub subscriber request</title>
<instructions>To approve this entity's subscription request,
click the OK button. To deny the request, click the
cancel button.</instructions>
<field var="FORM_TYPE" type="hidden">
<value>http://jabber.org/protocol/pubsub</value>
</field>
<field var="pubsub_node" type="hidden">
<value>generic/pgm-mp3-player</value>
</field>
<field var="pubsub_node_label" type="fixed">
<value>The pub-sub node is: generic/pgm-mp3-player</value>
</field>
<field var="pubsub_subscriber_jid" type="jid-single"
label="Jabber ID of Subscriber">
<value>sub1@foo.com</value>
</field>
<field var="x-time_restrictions" type="text-multi"
label="Limit to these time ranges">
<value>09:00-12:00</value>
<value>13:00-17:00</value>
</field>
</x>
</message>
]]></example>
</section2>
<section2 topic='Incorrectly Specified FORM_TYPE' anchor='usecases-incorrect'>
<p>If the FORM_TYPE field is not hidden, it MUST be ignored as a
context indicator.</p>
<example caption='Message with bad FORM_TYPE'><![CDATA[
<message to="juliet@capulet.com" from="romeo@montague.net/garden">
<x xmlns="jabber:x:data" type="form">
<title>Balcony Scene (Act 2, Scene 2)</title>
<instructions>But soft! What light through yonder window breaks?</instructions>
<!-- Not hidden. Treated as any other text-single field: -->
<field var="FORM_TYPE" type="text-single">
<value>http://jabber.org/protocol/shakespeare</value>
</field>
<field var="light" type="list-multi">
<option label="Juliet">Sun</option>
<option lable="Maid">Moon</option>
<option label="Eyes">Stars</option>
</field>
</x>
</message>
]]></example>
</section2>
<section2 topic='Message with Bad Field' anchor='usecases-badfield'>
<p>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.</p>
<example caption='Message with bad field'><![CDATA[
<message to="juliet@capulet.com" from="romeo@montague.net/garden">
<x xmlns="jabber:x:data" type="form">
<title>Balcony Scene (Act 2, Scene 2)</title>
<instructions>But soft! What light through yonder window breaks?</instructions>
<field var="FORM_TYPE" type="hidden">
<value>http://jabber.org/protocol/shakespeare</value>
</field>
<field var="light" type="list-multi">
<option label="Juliet">Sun</option>
<option lable="Maid">Moon</option>
<option label="Eyes">Stars</option>
</field>
</x>
</message>
<message from="juliet@capulet.com" to="romeo@montague.net/garden" type="error">
<error code="406" type='modify'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>
The field "light" is not acceptable.
</text>
</error>
</message>
]]></example>
</section2>
<section2 topic='IQ Example' anchor='usecases-IQ'>
<p>The following example shows a user's interaction with a Multi-User Chat room in order to register with the room.</p>
<example caption='User Requests Registration Requirements'><![CDATA[
<iq
from='hag66@shakespeare.lit/pda'
to='darkcave@macbeth.shakespeare.lit'
type='get'
id='reg1'>
<query xmlns='jabber:iq:register'/>
</iq>
]]></example>
<example caption='Service Returns Registration Form'><![CDATA[
<iq
type='result'
from='darkcave@macbeth.shakespeare.lit'
to='hag66@shakespeare.lit/pda'
id='reg1'>
<query xmlns='jabber:iq:register'>
<instructions>
To register on the web, visit http://shakespeare.lit/
</instructions>
<x xmlns='jabber:x:data' type='form'>
<title>Dark Cave Registration</title>
<instructions>
Please provide the following information
to register with this room.
</instructions>
<field
type='hidden'
var='FORM_TYPE'>
<value>http://jabber.org/protocol/muc#user</value>
</field>
<field
type='text-single'
label='First Name'
var='muc#user_first'>
<required/>
</field>
<field
type='text-single'
label='Last Name'
var='muc#user_last'>
<required/>
</field>
<field
type='text-single'
label='Desired Nickname'
var='muc#user_roomnick'>
<required/>
</field>
<field
type='text-single'
label='Your URL'
var='muc#user_url'/>
<field
type='text-single'
label='Email Address'
var='muc#user_email'/>
<field
type='text-multi'
label='FAQ Entry'
var='muc#user_faqentry'/>
</x>
</query>
</iq>
]]></example>
<example caption='User Submits Registration Form'><![CDATA[
<iq
type='set'
from='hag66@shakespeare.lit/pda'
to='darkcave@macbeth.shakespeare.lit'
id='reg2'>
<query xmlns='jabber:iq:register'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE'>
<value>http://jabber.org/protocol/muc#user</value>
</field>
<field var='muc#user_first'>
<value>Brunhilde</value>
</field>
<field var='muc#user_last'>
<value>Entwhistle-Throckmorton</value>
</field>
<field var='muc#user_roomnick'>
<value>thirdwitch</value>
</field>
<field var='muc#user_url'>
<value>http://witchesonline/~hag66/</value>
</field>
<field var='muc#user_email'>
<value>hag66@witchesonline</value>
</field>
<field var='muc#user_faqentry'>
<value>Just another witch.</value>
</field>
</x>
</query>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<p>If the FORM_TYPE field is not type=&quot;hidden&quot;, it does not have the special meaning defined herein.</p>
<p>If the form is used in an IQ, the namespace of the &lt;query/&gt; element SHOULD match the base namespace of the FORM_TYPE. (One possible way of solving this problem would have been to reuse the &lt;query/&gt; 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.)</p>
</section1>
<section1 topic='Error Codes' anchor='errors'>
<p>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.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>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.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>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.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Registries' anchor='registrar-reg'>
<section3 topic='FORM_TYPEs Registry' anchor='registrar-reg-formtypes'>
<p>The Jabber Registrar shall maintain a registry of information about submitted FORM_TYPEs.</p>
<section4 topic='Process' anchor='registrar-reg-formtypes-process'>
&REGPROCESS;
<code><![CDATA[
<form_type>
<name>FORM_TYPE namespace or namespace derivative</name>
<doc>associated JEP or other document</doc>
<desc>natural-language description of form type</desc>
<field
var='the_field_name'
type='the_field_type'
label='natural-language description of field'/>
</form_type>
]]></code>
<p>The registrant MAY register more than one FORM_TYPE at a time, each contained in a separate &lt;form_type/&gt; element. The registrant MAY also register more than one field at a time, each contained in a separate &lt;field/&gt; 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 &lt;field/&gt; 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.</p>
<p>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:</p>
<code><![CDATA[
<form_type>
<name>FORM_TYPE namespace or namespace derivative</name>
<doc>associated JEP or other document</doc>
<desc>natural-language description of form type</desc>
<field
var='the_field_name'
type='the_field_type'
label='natural-language description of field'>
<option label='natural-language description of option'>
<value>the_value</value>
</option>
</field>
</form_type>
]]></code>
</section4>
</section3>
</section2>
</section1>
</jep>

51
xep-0069.xml Normal file
View File

@ -0,0 +1,51 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Compliance JIG</title>
<abstract>A proposal to form a JIG devoted to issues related to protocol compliance.</abstract>
&LEGALNOTICE;
<number>0069</number>
<status>Deferred</status>
<type>JIG Formation</type>
<jig>None</jig>
<author>
<firstname>Peter</firstname>
<surname>Saint-Andre</surname>
<email>stpeter@jabber.org</email>
<jid>stpeter@jabber.org</jid>
</author>
<revision>
<version>0.1</version>
<date>2003-01-29</date>
<initials>psa</initials>
<remark>Initial release</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
</section1>
<section1 topic='Scope and Role'>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Membership'>
<p>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 &lt;compliance-jig@jabber.org&gt; as well as in the &lt;foundation@conference.jabber.org&gt; chatroom.</p>
</section1>
<section1 topic='Lifetime'>
<p>The Compliance JIG shall be a standing JIG, and shall exist as long as the JSF compliance program is in operation.</p>
</section1>
<section1 topic='Deliverables'>
<p>The Compliance JIG shall produce at least the following deliverables:</p>
<ul>
<li>Documentation of the testing process</li>
<li>Compliance test plans</li>
<li>Compliance testing software</li>
<li>Logo requirements</li>
</ul>
</section1>
</jep>

385
xep-0070.xml Normal file
View File

@ -0,0 +1,385 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Verifying HTTP Requests via XMPP</title>
<abstract>This document defines a protocol that enables verification of an HTTP request via XMPP.</abstract>
&LEGALNOTICE;
<number>0070</number>
<status>Draft</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>RFC 2616</spec>
<spec>RFC 2617</spec>
<spec>JEP-0030</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>http-auth</shortname>
<schemaloc>
<url>http://jabber.org/protocol/http-auth/http-auth.xsd</url>
</schemaloc>
&linuxwolf;
&hildjj;
&dizzyd;
&stpeter;
<revision>
<version>1.0</version>
<date>2005-12-14</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
</revision>
<revision>
<version>0.10</version>
<date>2005-12-01</date>
<initials>psa</initials>
<remark>Corrected several errors in the text.</remark>
</revision>
<revision>
<version>0.9</version>
<date>2005-11-09</date>
<initials>psa</initials>
<remark>Changed use of transaction identifier from SHOULD to MUST; removed x-xmpp-auth scheme; clarified requirements, business rules, and confirm element syntax; added several more examples; more clearly specified how HTTP server communicates with XMPP server; updated schema and security considerations.</remark>
</revision>
<revision>
<version>0.8</version>
<date>2005-10-19</date>
<initials>psa</initials>
<remark>Changed use of transaction identifier from MAY to SHOULD; updated and clarified security considerations.</remark>
</revision>
<revision>
<version>0.7</version>
<date>2005-10-11</date>
<initials>psa</initials>
<remark>Added more HTTP examples to illustrate process flow; updated IANA considerations and security considerations.</remark>
</revision>
<revision>
<version>0.6</version>
<date>2005-07-21</date>
<initials>psa</initials>
<remark>Updated references; clarified several points in the text; rewrote introduction.</remark>
</revision>
<revision>
<version>0.5</version>
<date>2004-04-27</date>
<initials>psa</initials>
<remark>Added optional id attribute in order to track requests, described in new implementation note.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2004-01-14</date>
<initials>psa/dss/jh</initials>
<remark>Incorporated results of IRL and IM discussions: simplified the flow; added x-xmpp-auth authentication scheme.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-06-27</date>
<initials>lw</initials>
<remark>Removed hashing requirements; added/clarified JID fields in HTTP headers; added XML Schema; added XMPP error conditions; added more descriptions for confirm and accept tokens; fixed discrepancies in examples.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-06-26</date>
<initials>lw</initials>
<remark>Updated to reflect feedback received (moved to using standard HTTP authentication headers; included token-authority JID in HTTP header; removed example involving deprecated JEP).</remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-01-31</date>
<initials>lw</initials>
<remark>Initial draft.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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;).</p>
</section1>
<section1 topic='Terminology' anchor='terms'>
<section2 topic='HTTP Terms' anchor='terms-http'>
<p>This document inherits terminology about the HyperText Transfer Protocol from <cite>RFC 2616</cite> and <cite>RFC 2617</cite>.</p>
</section2>
<section2 topic='Entities' anchor='terms-entities'>
<table caption='Terms for Entities Described Herein'>
<tr>
<th>Term</th>
<th>Definition</th>
</tr>
<tr>
<td>HTTP Client</td>
<td>A client that implements the HyperText Transfer Protocol (HTTP)</td>
</tr>
<tr>
<td>HTTP Server</td>
<td>A server that implements the HyperText Transfer Protocol (HTTP)</td>
</tr>
<tr>
<td>XMPP Client</td>
<td>A client that implements the Extensible Messaging and Presence Protocol (XMPP) or its antecedents</td>
</tr>
<tr>
<td>XMPP Server</td>
<td>A server that implements the Extensible Messaging and Presence Protocol (XMPP) or its antecedents</td>
</tr>
</table>
<p>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.</p>
</section2>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>The motivations for this document are to:</p>
<ul>
<li>Use an existing XMPP connection to associate an HTTP request with an XMPP entity.</li>
<li>Require confirmation of the request by the XMPP entity before allowing access.</li>
<li>Ensure that the HTTP request was generated by the principal controlling the XMPP entity.</li>
</ul>
</section1>
<section1 topic='Use Case' anchor='usecase'>
<p>The process flow for this protocol is as follows:</p>
<ol>
<li>HTTP Client requests object via HTTP.</li>
<li>HTTP Server sends Authenticate Response via HTTP.</li>
<li>HTTP Client sends Authorization Request via HTTP (E1).</li>
<li>HTPP Server processes request and forwards it to XMPP Server.</li>
<li>XMPP Server requests confirmation via XMPP (E2).</li>
<li>XMPP Client confirms request via XMPP.</li>
<li>XMPP Server delivers confirmation to HTTP Server.</li>
<li>HTTP Server allows HTTP Client to access object (E3).</li>
</ol>
<p>Error cases:</p>
<ul>
<li><b>E1:</b> HTTP Client does not understand the presented authentication scheme.</li>
<li><b>E2:</b> HTTP Server does not recognize or understand the request.</li>
<li><b>E3:</b> HTTP Server denies access.</li>
</ul>
<p>This process flow is described in more detail in the following sections.</p>
<section2 topic='HTTP Client Sends Request via HTTP' anchor='http-request'>
<p>Let us stipulate that an XMPP user (say, &lt;juliet@capulet.com&gt;) learns of an HTTP URL (e.g., &lt;https://files.shakespeare.lit:9345/missive.html&gt;). 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 <cite>RFC 2616</cite>. The request method MAY be any valid HTTP request method, including user-defined methods.</p>
<p>An example is provided below:</p>
<example caption='HTTP Client Makes Request (No Credentials)'><![CDATA[
GET https://files.shakespeare.lit:9345/missive.html HTTP/1.1
]]></example>
<p>In order to avoid a round trip, the initial request MAY contain HTTP authorization credentials as described below.</p>
</section2>
<section2 topic='HTTP Server Returns Authenticate Response via HTTP' anchor='http-response'>
<p>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 <cite>RFC 2616</cite>. 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).</p>
<example caption='HTTP Server Returns Authenticate Response'><![CDATA[
401 Unauthorized HTTP/1.1
WWW-Authenticate: Basic realm="xmpp"
WWW-Authenticate: Digest realm="xmpp",
domain="files.shakespeare.lit",
stale=false,
nonce="ec2cc00f21f71acd35ab9be057970609",
qop="auth",
algorithm="MD5"
]]></example>
</section2>
<section2 topic='HTTP Client Sends Authorization Request via HTTP' anchor='http-authz'>
<p>The HTTP Client responds with an Authorization Request as defined in <cite>RFC 2616</cite>. The following rules apply:</p>
<ol>
<li>The request MUST include the Jabber Identifier (JID) of the user making the request. This SHOULD be the full JID (&lt;user@host/resource&gt;) of a client that supports the protocol defined herein, although it MAY be the user's bare JID (&lt;user@host&gt;) instead.</li>
<li>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.</li>
</ol>
<p>The Authorization Request process is described in the following subsections.</p>
<section3 topic='Basic Access Authentication Scheme' anchor='http-authz-basic'>
<p>The Basic Access Authentication scheme is defined in <cite>RFC 2617</cite>. 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;.</p>
<p>(Refer to <cite>RFC 2617</cite> for specification of the syntax of the Basic Access Authentication scheme; that information is not duplicated here.)</p>
<example caption='HTTP Client Makes Basic Authorization Request'><![CDATA[
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
]]></example>
</section3>
<section3 topic='Digest Access Authentication Scheme' anchor='http-authz-digest'>
<p>The Digest Access Authentication scheme is defined in <cite>RFC 2617</cite>. 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 <cite>RFC 3986</cite>.</p>
<p>(Refer to <cite>RFC 2617</cite> for specification of the syntax of the Digest Access Authentication scheme; that information is not duplicated here.)</p>
<example caption='HTTP Client Makes Digest Authorization Request'><![CDATA[
Authorization: Digest username="juliet@capulet.com",
realm="xmpp",
nonce="ec2cc00f21f71acd35ab9be057970609",
uri="missive.html",
qop=auth,
nc=00000001,
cnonce="0a4f113b",
response="6629fae49393a05397450978507c4ef1",
opaque="5ccc069c403ebaf9f0171e9517f40e41"
]]></example>
</section3>
<section3 topic='Additional Authentication Schemes' anchor='http-authz-add'>
<p>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.</p>
</section3>
</section2>
<section2 topic='HTPP Server Processes Request' anchor='http-process'>
<p>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.</p>
<p>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.</p>
</section2>
<section2 topic='XMPP Server Requests Confirmation via XMPP' anchor='xmpp-request'>
<p>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).</p>
<p>The confirmation request shall consist of an empty &lt;confirm/&gt; 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.</p>
<p>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.</p>
<p>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.</p>
<example caption='Confirmation Request Sent via IQ'><![CDATA[
<iq type='get'
from='files.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='ha000'>
<confirm xmlns='http://jabber.org/protocol/http-auth'
id='transaction-identifier'
method='GET'
url='https://files.shakespeare.lit:9345/missive.html'/>
</iq>
]]></example>
<example caption='Confirmation Request Sent via Message'><![CDATA[
<message type='normal'
from='files.shakespeare.lit'
to='juliet@capulet.com'>
<thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
<body>
Someone (maybe you) has requested the file
https://files.shakespeare.lit:9345/missive.html.
If you wish to confirm the request, please reply
to this message by typing "OK". If not, please
reply with "No".
</body>
<confirm xmlns='http://jabber.org/protocol/http-auth'
id='transaction-identifier'
method='GET'
url='https://files.shakespeare.lit:9345/missive.html'/>
</message>
]]></example>
</section2>
<section2 topic='XMPP Client Confirms Request via XMPP' anchor='xmpp-confirm'>
<p>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 &lt;confirm/&gt; child element (although this is not necessary since the XMPP 'id' attribute can be used for tracking purposes):</p>
<example caption='XMPP Client Confirms Request via IQ'><![CDATA[
<iq type='result'
from='juliet@capulet.com/balcony'
to='files.shakespeare.lit'
id='ha000'/>
]]></example>
<p>If the user wishes to deny the request, the &IQ; response stanza MUST be of type "error", MAY contain the original &lt;confirm/&gt; 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 &notauthorized;:</p>
<example caption='XMPP Client Denies Request via IQ'><![CDATA[
<iq type='error'
from='juliet@capulet.com/balcony'
to='files.shakespeare.lit'
id='ha000'>
<confirm xmlns='http://jabber.org/protocol/http-auth'
id='transaction-identifier'
method='GET'
url='https://files.shakespeare.lit:9345/missive.html'/>
<error code='401' type='auth'>
<not-authorized xmlns='urn:ietf:params:xml:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>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 &lt;thread/&gt; ID (if provided by the XMPP Server), and MUST contain the original &lt;confirm/&gt; child element:</p>
<example caption='XMPP Client Confirms Request via Message'><![CDATA[
<message from='juliet@capulet.com/balcony'
to='files.shakespeare.lit'>
<thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
<confirm xmlns='http://jabber.org/protocol/http-auth'
id='transaction-identifier'
method='GET'
url='https://files.shakespeare.lit:9345/missive.html'/>
</message>
]]></example>
<p>If the user wishes to deny the request, the &MESSAGE; response stanza MUST be of type "error", MUST mirror the &lt;thread/&gt; ID (if provided by the XMPP Server), MUST contain the original &lt;confirm/&gt; child element, and MUST specify an error, which SHOULD be &notauthorized;:</p>
<example caption='XMPP Client Denies Request via Message'><![CDATA[
<message type='error'
from='juliet@capulet.com/balcony'
to='files.shakespeare.lit'>
<thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
<confirm xmlns='http://jabber.org/protocol/http-auth'
id='transaction-identifier'
method='GET'
url='https://files.shakespeare.lit:9345/missive.html'/>
<error code='401' type='auth'>
<not-authorized xmlns='urn:ietf:params:xml:xmpp-stanzas'/>
</error>
</message>
]]></example>
</section2>
<section2 topic='HTTP Server Allows HTTP Client to Access Object' anchor='http-access'>
<p>Once the XMPP Client has successfully confirmed the request, the XMPP Server forwards that confirmation to the HTTP Server, which allows access:</p>
<example caption='HTTP Server Allows Access to Object'><![CDATA[
200 OK HTTP/1.1
Content-Type: text/html
Content-Length: 3032
...
]]></example>
<p>If the XMPP Client denied the request, the HTTP Server MUST return a Forbidden error:</p>
<example caption='HTTP Server Denies Access to Object'><![CDATA[
403 Forbidden HTTP/1.1
]]></example>
</section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<section2 topic='Interaction of HTTP methods' anchor='impl-methods'>
<p>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.</p>
<p>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).</p>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<section2 topic='Association of Request' anchor='security-association'>
<p>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 &lt;confirm/&gt; 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.</p>
</section2>
<section2 topic='Channel Encryption' anchor='security-channel'>
<p>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:</p>
<ol>
<li>The channel used for HTTP requests and responses SHOULD be encrypted via SSL (secure HTTP via https: URLs) or TLS (&rfc2817;).</li>
<li>If the standard binding of XMPP to TCP is used, TLS SHOULD be negotiated for the XMPP channel in accordance with <cite>RFC 3920</cite>.</li>
<li>If a binding of XMPP to HTTP is used (e.g., as specified in <cite>JEP-0124</cite>), exchanges between the XMPP Client and XMPP Server (connection manager) SHOULD be sent over a channel that is encrypted using SSL or TLS.</li>
</ol>
</section2>
<section2 topic='End-to-End Encryption' anchor='security-e2e'>
<p>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.</p>
</section2>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; includes "http://jabber.org/protocol/http-auth" in its registry of protocol namespaces.</p>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/http-auth'
xmlns='http://jabber.org/protocol/http-auth'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0070: http://www.jabber.org/jeps/jep-0070.html
</xs:documentation>
</xs:annotation>
<xs:element name='confirm'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='id' use='required' type='xs:string'/>
<xs:attribute name='method' use='required' type='xs:NCName'/>
<xs:attribute name='url' use='required' type='xs:anyURI'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
</jep>

1178
xep-0071.xml Normal file
View File

File diff suppressed because it is too large Load Diff

1204
xep-0072.xml Normal file
View File

File diff suppressed because it is too large Load Diff

160
xep-0073.xml Normal file
View File

@ -0,0 +1,160 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Basic IM Protocol Suite</title>
<abstract>This JEP defines a recommended suite of Jabber/XMPP protocols to be supported by basic instant messaging and presence applications.</abstract>
&LEGALNOTICE;
<number>0073</number>
<status>Draft</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>JEP-0030</spec>
<spec>JEP-0077</spec>
<spec>JEP-0078</spec>
<spec>JEP-0086</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>N/A</shortname>
&stpeter;
<revision>
<version>1.0</version>
<date>2004-12-09</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Active.</remark>
</revision>
<revision>
<version>0.10</version>
<date>2004-12-06</date>
<initials>psa</initials>
<remark>Per feedback from the Jabber Council, made all of RFC 3920 mandatory (no loophole allowing certain client platforms to not support TLS and SASL).</remark>
</revision>
<revision>
<version>0.9</version>
<date>2004-12-01</date>
<initials>psa</initials>
<remark>Removed reference to deployments and moved historical paragraph to a footnote.</remark>
</revision>
<revision>
<version>0.8</version>
<date>2004-11-18</date>
<initials>psa</initials>
<remark>Updated references to reflect publication of RFCs 3920 and 3921.</remark>
</revision>
<revision>
<version>0.7</version>
<date>2004-08-18</date>
<initials>psa</initials>
<remark>Changed In-Band Registration to recommended for clients; added note about SSL communications over port 5223; clarified wording throughout.</remark>
</revision>
<revision>
<version>0.6</version>
<date>2004-03-24</date>
<initials>psa</initials>
<remark>Updated to reflect approval of XMPP Core and XMPP IM.</remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-11-24</date>
<initials>psa</initials>
<remark>Updated to reflect work by the XMPP WG; changed status to Deferred.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-08-13</date>
<initials>psa</initials>
<remark>Renamed.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-05-20</date>
<initials>psa</initials>
<remark>Slight editorial revisions.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-04-06</date>
<initials>psa</initials>
<remark>Limited scope to definition of "Jabber IM Basic".</remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-03-04</date>
<initials>psa</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>Given the large number of Jabber/XMPP protocols,
<note>The protocols developed by the Jabber community have matured considerably since 1999. The core protocols were originally created by a small group of developers who worked on early Jabber-related open-source software projects such as the &jabberd; server, the Winjab, Gabber, and Jarl clients, the Net::Jabber and Jabberbeans libraries, and gateways to consumer IM services. In the summer of 2001, the &JSF; was founded to institute a formal standards process within the growing Jabber community (codified in &jep0001;). In late 2002, the &IETF; formed the &XMPPWG;, which formalized the core Jabber protocols under the name Extensible Messaging and Presence Protocol (XMPP). In early 2004, the IETF approved the main XMPP specifications as Proposed Standards within the Internet Standards Process defined by &rfc2026;, resulting in publication of <cite>RFC 3920</cite> (&xmppcore;) and <cite>RFC 3921</cite> (&xmppim;). In the meantime, the JSF has continued to develop additional protocols on top of XMPP in order to address functionality areas (such as file transfer) that were too application-specific for consideration within the IETF.</note>
it is not always clear to developers exactly which protocols they need to implement in order to interoperate over Jabber/XMPP networks. This JEP attempts to assist developers by defining a protocol suite for basic instant messaging and presence.</p>
</section1>
<section1 topic='Requirements and Approach' anchor='reqs'>
<p>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:</p>
<ul>
<li>They were not required to meet the requirements of &rfc2779; (e.g, service discovery)</li>
<li>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)</li>
</ul>
<p>The Basic IM Protocol Suite does not include more advanced IM functionality, such as groupchat or HTML message formatting; see &jep0117; for such features.</p>
</section1>
<section1 topic='Definition' anchor='def'>
<p>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:
<note>Older software also used port 5223 for SSL-enabled communications between a client and a server, rather than upgrading port 5222 as is done during TLS negotiation (the equivalent for server-to-server communications was never implemented); while support for this behavior is OPTIONAL, it may be quite desirable in order to interoperate with older software and deployments.</note>
</p>
<ul>
<li>Support for &jep0078; as a fallback method for authentication.</li>
<li>Support for the error 'code' attribute specified in &jep0086;.</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>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).</p>
<p>Thus we define the Basic IM Protocol Suite as follows:</p>
<table caption='Required and Recommended Specifications'>
<tr>
<th>Specification</th>
<th>Requirement Level</th>
</tr>
<tr>
<td><strong>RFC 3920: XMPP Core</strong></td>
<td>REQUIRED</td>
</tr>
<tr>
<td><strong>RFC 3921: XMPP IM</strong></td>
<td>REQUIRED</td>
</tr>
<tr>
<td><strong>JEP-0078: Non-SASL Authentication</strong></td>
<td>REQUIRED</td>
</tr>
<tr>
<td><strong>JEP-0086: Error Condition Mappings</strong></td>
<td>REQUIRED for servers; RECOMMENDED for clients</td>
</tr>
<tr>
<td><strong>JEP-0030: Service Discovery</strong></td>
<td>REQUIRED</td>
</tr>
<tr>
<td><strong>JEP-0077: In-Band Registration</strong></td>
<td>REQUIRED for servers; RECOMMENDED for clients</td>
</tr>
</table>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>RFC 3920 requires support for SASL and TLS as must-implement protocols, and that support is not modified herein. Refer to <cite>JEP-0078: Non-SASL Authentication</cite> 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).</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<p>No namespaces or parameters need to be registered with the &REGISTRAR; as a result of this JEP.</p>
</section1>
</jep>

169
xep-0074.xml Normal file
View File

@ -0,0 +1,169 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Simple Access Control</title>
<abstract>A simple protocol for querying information for permissions.</abstract>
&LEGALNOTICE;
<number>0074</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>JEP0-0030</dependencies>
<supersedes>None</supersedes>
<supersededby>None</supersededby>
<shortname>sac</shortname>
<schemaloc>Not yet assigned</schemaloc>
<author>
<firstname>Justin</firstname>
<surname>Kirby</surname>
<email>justin@openaether.org</email>
<jid>zion@openaether.org</jid>
</author>
<revision>
<version>0.2</version>
<date>2003-10-20</date>
<initials>psa</initials>
<remark>At the request of the author, changed status to Retracted; interested parties should refer to &lt;<link url="http://www.openaether.org/projects/sac.html">http://www.openaether.org/projects/sac.html</link>&gt; for further information.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-03-05</date>
<initials>jk</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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.</p>
<p>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.</p>
<example caption="A simple query">
<![CDATA[
<iq to="security.capulet.com"
from="inventory.capulet.com"
type="get" id="1234">
<acl xmlns="http://jabber.org/protocol/sac"
actor="juliet@capulet.com/church"
oper="uri://capulet.com/inventory#obtain"
target="poison"/>
</iq>
]]>
</example>
<p>Here we have the inventory.capulet.com component querying the security component as to whether juliet@ may obtain the requested poison.</p>
<example caption="A response to the above query">
<![CDATA[
<iq to="inventory.capulet.com"
from="security.capulet.com"
type="result" id="1234">
<acl xmlns="http://jabber.org/protocol/sac"
actor="juliet@capulet.com/church"
oper="uri://capulet.com/inventory#obtain"
target="poison">
<allowed/>
</acl>
</iq>
]]>
</example>
<p>Unfortunately, the response is in the affirmative and the romantic tragedy follows.</p>
</section1>
<section1 topic='A More Formal Tone'>
<p>The &lt;acl&gt; element provides the container for the query. It MUST have the three attributes: actor, oper, and target.</p>
<p>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.</p>
<p>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.</p>
<p>The target is the object which the actor is trying to perform the operation on. This MUST be a node queryable via &jep0030;.</p>
<p>Requests MUST be in the form of an empty &lt;acl/&gt; 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. </p>
<p>Responses MUST be in one of three forms: allowed, denied, error.</p>
<p>The response is inserted into the &lt;acl/&gt; as a child element. If the response is allowed, then &lt;allowed/&gt; is inserted. If the JID is denied then &lt;denied/&gt; is returned. If there is inadequate information then &lt;error/&gt; is used following the standard Jabber error scheme.</p>
<example caption='A positive response'>
<![CDATA[
<iq to="inventory.capulet.com"
from="security.capulet.com"
type="result" id="1234">
<acl xmlns="http://jabber.org/protocol/sac"
actor="juliet@capulet.com/church"
oper="uri://capulet.com/inventory#obtain"
target="poison">
<allowed/>
</acl>
</iq>
]]>
</example>
<example caption='Negative response (denied)'>
<![CDATA[
<iq to="inventory.capulet.com"
from="security.capulet.com"
type="result" id="1234">
<acl xmlns="http://jabber.org/protocol/sac"
actor="juliet@capulet.com/church"
oper="uri://capulet.com/inventory#obtain"
target="poison">
<denied/>
</acl>
</iq>
]]>
</example>
<example caption='Error response'>
<![CDATA[
<iq to="inventory.capulet.com"
from="security.capulet.com"
type="error" id="1234">
<acl xmlns="http://jabber.org/protocol/sac"
actor="juliet@capulet.com/church"
oper="uri://capulet.com/inventory#obtain"
target="poison"/>
<error code="404">No information available</error>
</iq>
]]>
</example>
</section1>
<section1 topic='Query List of ACL operations'>
<p>To obtain a list of acl operations that a jid supports, you must send an empty &lt;query/&gt; </p>
<example caption='querying for list of acl operations'>
<![CDATA[
<iq to="security.capulet.com"
from="inventory.capulet.com"
type="get" id="1234">
<query xmlns="http://jabber.org/protocol/sac"/>
</iq>
]]>
</example>
<p>The to jid must then respond with a list of operations, if the jid supports SAC.</p>
<example caption='response to the query'>
<![CDATA[
<iq to="inventory.capulet.com"
from="security.capulet.com"
type="result" id="1234">
<query xmlns="http://jabber.org/protocol/sac">
<oper uri="uri://capulet.com/inventory#obtain"/>
<oper uri="uri://capulet.com/inventory#add"/>
<oper uri="uri://capulet.com/inventory#remove"/>
</query>
</iq>
]]>
</example>
</section1>
<section1 topic='Integrating with Service Discovery'>
<p>To follow.</p>
</section1>
<section1 topic='Security Considerations'>
<p>To follow.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<p>As a result of this JEP, the &REGISTRAR; will need to register the 'http://jabber.org/protocol/sac' namespace.</p>
</section1>
<section1 topic='Open Issues'>
<ol>
<li>Add disco integration section.</li>
<li>Fill out error codes.</li>
<li>Add DTD and Schema.</li>
<li>Allow for query of all allowable operations for actor in relation to a target.</li>
<li>Investigate possible integration with pubsub.</li>
</ol>
</section1>
</jep>

1821
xep-0075.xml Normal file
View File

File diff suppressed because it is too large Load Diff

95
xep-0076.xml Normal file
View File

@ -0,0 +1,95 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Malicious Stanzas</title>
<abstract>This JEP defines a protocol extension for flagging malicious stanzas within Jabber/XMPP.</abstract>
&LEGALNOTICE;
<number>0076</number>
<status>Active</status>
<type>Humorous</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>RFC 3514</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>evil</shortname>
&stpeter;
&hildjj;
<revision>
<version>1.0</version>
<date>2003-04-01</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Active.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>&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.</p>
</section1>
<section1 topic='Requirements and Approach'>
<p>There are three basic Jabber stanza types that may be sent within XML streams:</p>
<ul>
<li>&lt;message/&gt; -- a "push" medium for sending information to other entities.</li>
<li>&lt;presence/&gt; -- a "broadcast" medium for publishing information to entities that have subscribed to an entity's availability status.</li>
<li>&lt;iq/&gt; -- a "request-response" medium for executing basic but structured transactions with other entities.</li>
</ul>
<p>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.</p>
</section1>
<section1 topic='Use Cases'>
<section2 topic='Evil Messages'>
<p>If a Jabber entity sends an evil message, it MUST include an appropriately namespaced extension in the message stanza:</p>
<example caption='Jabber Entity Sends Evil Message'><![CDATA[
<message
from='iago@shakespeare.lit/pda'
to='emilia@shakespeare.lit/cell'>
<body>
I told him what I thought, and told no more
Than what he found himself was apt and true.
</body>
<evil xmlns='http://jabber.org/protocol/evil'/>
</message>
]]></example>
</section2>
<section2 topic='Evil Presence'>
<p>If a Jabber entity sends evil presence information, it MUST include an appropriately namespaced extension in the presence stanza:</p>
<example caption='Jabber Entity Sends Evil Presence'><![CDATA[
<presence from='iago@shakespeare.lit/pda'>
<show>dnd</show>
<status>Fomenting dissension</status>
<evil xmlns='http://jabber.org/protocol/evil'/>
</presence>
]]></example>
</section2>
<section2 topic='Evil IQs'>
<p>If a Jabber entity provides evil information in an IQ exchange, it MUST include an appropriately namespaced extension in the IQ stanza:</p>
<example caption='Jabber Entity Sends Evil Message'><![CDATA[
<iq
from='iago@shakespeare.lit/pda'
to='emilia@shakespeare.lit/cell'
id='evil1'>
<query xmlns='jabber:iq:version'>
<name>Stabber</name>
<version>666</version>
<os>FiendOS</os>
</query>
<evil xmlns='http://jabber.org/protocol/evil'/>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Security Considerations'>
<p>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.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<p>The &REGISTRAR; shall register the 'http://jabber.org/protocol/evil' namespace as a result of this JEP.</p>
</section1>
</jep>

900
xep-0077.xml Normal file
View File

@ -0,0 +1,900 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>In-Band Registration</title>
<abstract>This JEP documents a protocol for in-band registration with instant messaging servers and associated services using the jabber:iq:register namespace.</abstract>
&LEGALNOTICE;
<number>0077</number>
<status>Final</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>iq-register</shortname>
<schemaloc>
<url>http://jabber.org/protocol/iq-register/iq-register.xsd</url>
</schemaloc>
&stpeter;
<revision>
<version>2.2</version>
<date>2006-01-24</date>
<initials>psa</initials>
<remark>Further specified integration with data forms, specifically if needed to require additional information when cancelling an existing registration (e.g., username and password) or changing a password (e.g., old password); also clarified server handling of cancelled registrations.</remark>
</revision>
<revision>
<version>2.1</version>
<date>2005-07-14</date>
<initials>psa</initials>
<remark>Clarified the extensibility rules; removed expiration date; modified schema to document optional inclusion of jabber:x:data and jabber:x:oob information.</remark>
</revision>
<revision>
<version>2.0</version>
<date>2004-08-30</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Final; also specified that by server is meant an instant messaging server.</remark>
</revision>
<revision>
<version>1.6</version>
<date>2004-08-23</date>
<initials>psa</initials>
<remark>In order to address Council concerns, clarified precedence order of x:data, iq:register, and x:oob; further specified server handling of initial registration requests from unregistered entities.</remark>
</revision>
<revision>
<version>1.5</version>
<date>2004-07-21</date>
<initials>psa</initials>
<remark>Specified server handling of requests from unregistered entities.</remark>
</revision>
<revision>
<version>1.4</version>
<date>2004-05-10</date>
<initials>psa</initials>
<remark>Removed conformance language regarding servers and services (belongs in a protocol suite specification).</remark>
</revision>
<revision>
<version>1.3</version>
<date>2004-02-24</date>
<initials>psa</initials>
<remark>Added text about redirection to web registration.</remark>
</revision>
<revision>
<version>1.2</version>
<date>2003-11-26</date>
<initials>psa</initials>
<remark>Documented use of &lt;key/&gt; element; added optional stream feature; added XMPP error handling; specified handling of empty passwords.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2003-10-02</date>
<initials>psa</initials>
<remark>Moved change password use case from JEP-0078.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2003-06-18</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
</revision>
<revision>
<version>0.9</version>
<date>2003-06-18</date>
<initials>psa</initials>
<remark>Changes to address Council concerns.</remark>
</revision>
<revision>
<version>0.8</version>
<date>2003-06-13</date>
<initials>psa</initials>
<remark>Restored the &lt;misc/&gt; and &lt;text/&gt; elements; added the old &lt;key/&gt; element; specified these three elements as obsolete.</remark>
</revision>
<revision>
<version>0.7</version>
<date>2003-06-12</date>
<initials>psa</initials>
<remark>Added &lt;registered/&gt; element; specified FORM_TYPE for x:data form; clarified that support for the extensibility mechanism is optional; removed the &lt;misc/&gt; and &lt;text/&gt; elements (not necessary given extensibility option); added &lt;nick/&gt;, &lt;first/&gt;, and &lt;last/&gt; elements that were traditionally documented as part of jabber:iq:register.</remark>
</revision>
<revision>
<version>0.6</version>
<date>2003-06-06</date>
<initials>psa</initials>
<remark>Removed XMPP-style error conditions until formats are stable.</remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-05-30</date>
<initials>psa</initials>
<remark>Removed "encrypted secret" content, added information about expiration date.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-05-28</date>
<initials>psa</initials>
<remark>Added "encrypted secret" content.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-05-20</date>
<initials>psa</initials>
<remark>Slight editorial revisions.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-04-29</date>
<initials>psa</initials>
<remark>Fixed schema, made minor editorial changes.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-04-06</date>
<initials>psa</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>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:</p>
<ol type='1' start='1'>
<li>an instant messaging server, such as described in <cite>XMPP IM</cite> and identified by the "server/im" &jep0030; category+type</li>
<li>an add-on service, such as a gateway (see &jep0100;) or a &jep0045; service</li>
</ol>
<p>If needed, extensibility with regard to information gathered should be done using &jep0004;.</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Entity Registers with a Host' anchor='usecases-register'>
<p>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.</p>
<example caption='Entity Requests Registration Fields from Host'><![CDATA[
<iq type='get' id='reg1'>
<query xmlns='jabber:iq:register'/>
</iq>
]]></example>
<p>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 &lt;instructions/&gt; element only, as shown in the <link url="#redirect">Redirection</link> section of this document.</p>
<example caption='Host Returns Registration Fields to Entity'><![CDATA[
<iq type='result' id='reg1'>
<query xmlns='jabber:iq:register'>
<instructions>
Choose a username and password for use with this service.
Please also provide your email address.
</instructions>
<username/>
<password/>
<email/>
</query>
</iq>
]]></example>
<p>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 &lt;registered/&gt; element (indicating that the entity is already registered), SHOULD contain the registration information currently on file for the entity (although the &lt;password/&gt; element MAY be empty), and SHOULD contain an &lt;instructions/&gt; element (whose XML character data MAY be modified to reflect the fact that the entity is currently registered).</p>
<p>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 <link url="#usecases-register-server">Registration with a Server</link> section below).</p>
<example caption='Host Informs Entity of Current Registration'><![CDATA[
<iq type='result' id='reg1'>
<query xmlns='jabber:iq:register'>
<registered/>
<username>juliet</username>
<password>R0m30</password>
<email>juliet@capulet.com</email>
</query>
</iq>
]]></example>
<p>If the entity is not already registered, the entity SHOULD provide the required information.</p>
<example caption='Entity Provides Required Information'><![CDATA[
<iq type='set' id='reg2'>
<query xmlns='jabber:iq:register'>
<username>bill</username>
<password>Calliope</password>
<email>bard@shakespeare.lit</email>
</query>
</iq>
]]></example>
<p>Note: The requesting entity MUST provide information for all of the elements (other than &lt;instructions/&gt;) contained in the IQ result.</p>
<example caption='Host Informs Entity of Successful Registration'><![CDATA[
<iq type='result' id='reg2'/>
]]></example>
<p>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.</p>
<example caption='Host Informs Entity of Failed Registration (Username Conflict)'><![CDATA[
<iq type='error' id='reg2'>
<query xmlns='jabber:iq:register'>
<username>bill</username>
<password>m1cro$oft</password>
<email>billg@bigcompany.com</email>
</query>
<error code='409' type='cancel'>
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>If the requesting entity does not provide all of the requested information during registration <note>This includes providing an empty password element or a password element that contains no XML character data, i.e., either &lt;password/&gt; or &lt;password&gt;&lt;/password&gt;.</note> then the server or service MUST return a &notacceptable; error to the requesting entity.</p>
<example caption='Host Informs Entity of Failed Registration (Some Required Information Not Provided)'><![CDATA[
<iq type='error' id='reg2'>
<query xmlns='jabber:iq:register'>
<username>bill</username>
<password>Calliope</password>
</query>
<error code='406' type='modify'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>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 <link url='#extensibility'>Extensibility</link> section of this document.</p>
<example caption='Entity Requests Registration Fields from Host'><![CDATA[
<iq type='get'
from='juliet@capulet.com/balcony'
to='contests.shakespeare.lit'
id='reg3'>
<query xmlns='jabber:iq:register'/>
</iq>
]]></example>
<example caption='Host Returns Registration Form to Entity'><![CDATA[
<iq type='result'
from='contests.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='reg3'>
<query xmlns='jabber:iq:register'>
<instructions>
Use the enclosed form to register. If your Jabber client does not
support Data Forms, visit http://www.shakespeare.lit/contests.php
</instructions>
<x xmlns='jabber:x:data' type='form'>
<title>Contest Registration</title>
<instructions>
Please provide the following information
to sign up for our special contests!
</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:iq:register</value>
</field>
<field type='text-single' label='Given Name' var='first'>
<required/>
</field>
<field type='text-single' label='Family Name' var='last'>
<required/>
</field>
<field type='text-single' label='Email Address' var='email'>
<required/>
</field>
<field type='list-single' label='Gender' var='x-gender'>
<option label='Male'><value>M</value></option>
<option label='Female'><value>F</value></option>
</field>
</x>
</query>
</iq>
]]></example>
<p>The user then SHOULD return the form:</p>
<example caption='User Submits Registration Form'><![CDATA[
<iq type='submit'
from='juliet@capulet.com/balcony'
to='contests.shakespeare.lit'
id='reg4'>
<query xmlns='jabber:iq:register'>
<x xmlns='jabber:x:data' type='form'>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:iq:register</value>
</field>
<field type='text-single' label='Given Name' var='first'>
<value>Juliet</value>
</field>
<field type='text-single' label='Family Name' var='last'>
<value>Capulet</value>
</field>
<field type='text-single' label='Email Address' var='email'>
<value>juliet@capulet.com</value>
</field>
<field type='list-single' label='Gender' var='x-gender'>
<value>F</value>
</field>
</x>
</query>
</iq>
]]></example>
<section3 topic='Registration with a Server' anchor='usecases-register-server'>
<p>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.</p>
<p>Depending on local service provisioning, a server MAY return a &notacceptable; 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 &lt;not-authorized/&gt; 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.</p>
</section3>
</section2>
<section2 topic='Entity Cancels an Existing Registration' anchor='usecases-cancel'>
<p>The 'jabber:iq:register' namespace also makes it possible for an entity to cancel a registration with a host by sending a &lt;remove/&gt; element in an IQ set. The host MUST determine the identity of the requesting entity based on the 'from' address of the IQ get.</p>
<example caption='Entity Requests Cancellation of Existing Registration'><![CDATA[
<iq type='set' from='bill@shakespeare.lit/globe' id='unreg1'>
<query xmlns='jabber:iq:register'>
<remove/>
</query>
</iq>
]]></example>
<example caption='Host Informs Entity of Successful Cancellation'><![CDATA[
<iq type='result' to='bill@shakespeare.lit/globe' id='unreg1'/>
]]></example>
<p>The host MUST perform the remove based on the 'from' address of the IQ set, usually matching based on bare JID (&lt;user@domain&gt;). If the entity cancels its registration with a server (not a service), the server SHOULD then return a &lt;not-authorized/&gt; 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).</p>
<p>Several error cases are possible:</p>
<table caption='Unregister Error Cases'>
<tr><th>Condition</th><th>Description</th></tr>
<tr><td>&badrequest;</td><td>The &lt;remove/&gt; element was not the only child element of the &lt;query/&gt; element.</td></tr>
<tr><td>&forbidden;</td><td>The sender does not have sufficient permissions to cancel the registration.</td></tr>
<tr><td>&notallowed;</td><td>No sender is allowed to cancel registrations in-band.</td></tr>
<tr><td>&registration;</td><td>The entity sending the remove request was not previously registered.</td></tr>
<tr><td>&unexpected;</td><td>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.</td></tr>
</table>
<example caption='Host Informs Client of Failed Cancellation (Bad Request)'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='unreg1'>
<error code='400' type='modify'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<example caption='Host Informs Client of Failed Cancellation (Not Authorized)'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='unreg1'>
<error code='401' type='cancel'>
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<example caption='Server Informs Client of Failed Cancellation (Not Allowed)'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='unreg1'>
<error code='405' type='cancel'>
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>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:</p>
<example caption='Server Returns Cancellation Form With Error'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='unreg1'>
<query xmlns='jabber:iq:register'>
<x xmlns='jabber:x:data' type='form'>
<title>Password Change</title>
<instructions>Use this form to cancel your registration.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:iq:register:cancel</value>
</field>
<field type='text-single' label='Username' var='username'>
<required/>
</field>
<field type='text-private' label='Password' var='password'>
<required/>
</field>
<field type='text-single' label='Mother&apos;s Maiden Name' var='x-mmn'>
<required/>
</field>
</x>
</query>
<error code='405' type='cancel'>
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>The user then SHOULD return the form:</p>
<example caption='User Returns Cancellation Form'><![CDATA[
<iq type='set' from='bill@shakespeare.lit/globe' to='shakespeare.lit' id='unreg2'>
<query xmlns='jabber:iq:register'>
<x xmlns='jabber:x:data' type='form'>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:iq:register:cancel</value>
</field>
<field type='text-single' var='username'>
<value>bill@shakespeare.lit</value>
</field>
<field type='text-private' var='password'>
<value>theglobe</value>
</field>
<field type='text-single' var='x-mmn'>
<value>Throckmorton</value>
</field>
</x>
</query>
</iq>
]]></example>
</section2>
<section2 topic='User Changes Password' anchor='usecases-changepw'>
<p>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:</p>
<example caption='Password Change'><![CDATA[
<iq type='set' to='shakespeare.lit' id='change1'>
<query xmlns='jabber:iq:register'>
<username>bill</username>
<password>newpass</password>
</query>
</iq>
]]></example>
<p>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.</p>
<p>If the user provides an empty password element or a password element that contains no XML character data (i.e., either &lt;password/&gt; or &lt;password&gt;&lt;/password&gt;), the server or service MUST NOT change the password to a null value, but instead MUST maintain the existing password.</p>
<example caption='Host Informs Client of Successful Password Change'><![CDATA[
<iq type='result' id='change1'/>
]]></example>
<p>Several error conditions are possible:</p>
<table caption='Password Change Error Cases'>
<tr><th>Condition</th><th>Description</th></tr>
<tr><td>&badrequest;</td><td>The password change request does not contain complete information (both &lt;username/&gt; and &lt;password/&gt; are required).</td></tr>
<tr><td>&notauthorized;</td><td>The server or service does not consider the channel safe enough to enable a password change.</td></tr>
<tr><td>&notallowed;</td><td>The server or service does not allow password changes.</td></tr>
<tr><td>&unexpected;</td><td>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.</td></tr>
</table>
<p>The server or service SHOULD NOT return the original XML sent in IQ error stanzas related to password changes.</p>
<example caption='Host Informs Client of Failed Password Change (Bad Request)'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='change1'>
<error code='400' type='modify'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<example caption='Host Informs Client of Failed Password Change (Not Authorized)'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='change1'>
<error code='401' type='cancel'>
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<example caption='Server Informs Client of Failed Password Change (Not Allowed)'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='change1'>
<query xmlns='jabber:iq:register'>
xxx
</query>
<error code='405' type='cancel'>
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>In order to require additional information before changing the password, the server or service SHOULD return a Data Form in the error stanza:</p>
<example caption='Server Returns Password Change Form With Error'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='change1'>
<query xmlns='jabber:iq:register'>
<x xmlns='jabber:x:data' type='form'>
<title>Password Change</title>
<instructions>Use this form to change your password.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:iq:register:changepassword</value>
</field>
<field type='text-single' label='Username' var='username'>
<required/>
</field>
<field type='text-private' label='Old Password' var='old_password'>
<required/>
</field>
<field type='text-private' label='New Password' var='password'>
<required/>
</field>
<field type='text-single' label='Mother&apos;s Maiden Name' var='x-mmn'>
<required/>
</field>
</x>
</query>
<error code='405' type='cancel'>
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>The user then SHOULD return the form:</p>
<example caption='User Returns Password Change Form'><![CDATA[
<iq type='set' from='bill@shakespeare.lit/globe' to='shakespeare.lit' id='change2'>
<query xmlns='jabber:iq:register'>
<x xmlns='jabber:x:data' type='form'>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:iq:register:changepassword</value>
</field>
<field type='text-single' var='username'>
<value>bill@shakespeare.lit</value>
</field>
<field type='text-private' var='old_password'>
<value>theglobe</value>
</field>
<field type='text-private' var='password'>
<value>groundlings</value>
</field>
<field type='text-single' var='x-mmn'>
<value>Throckmorton</value>
</field>
</x>
</query>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Extensibility' anchor='extensibility'>
<p>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, <cite>JEP-0004: Data Forms</cite> ("x:data") SHOULD be used according to the following rules:</p>
<ol>
<li>A host MUST NOT add new fields to the 'jabber:iq:register' namespace; instead, extensibility SHOULD be pursued via the <cite>Data Forms</cite> protocol as specified herein.</li>
<li>The x:data form shall be contained as a child element of the &lt;query xmlns='jabber:iq:register'/&gt; element (it cannot be a child of the &IQ; stanza and comply with Section 9.2.3 of &rfc3920;).</li>
<li>The x:data form SHOULD contain x:data fields that correspond to all of the iq:register fields (e.g., username and password).</li>
<li>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;.</li>
<li>The x:data form shall take precedence over the iq:register fields; if the submitting entity supports the <cite>Data Forms</cite> 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 <link url='#precedence'>Precedence Order</link> section of this document).</li>
</ol>
<p>Support for extensibility via <cite>Data Forms</cite> is RECOMMENDED but is not required for compliance with this JEP.</p>
</section1>
<section1 topic='Redirection' anchor='redirect'>
<p>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 &lt;instructions/&gt; element rather than the required fields or a data form in the IQ result, as well as a URL encoded using &jep0066; (see the <link url="#precedence">Precedence Order</link> section below for further details).</p>
<example caption='Host Redirects Entity to Web Registration'><![CDATA[
<iq type='result'
from='contests.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='reg3'>
<query xmlns='jabber:iq:register'>
<instructions>
To register, visit http://www.shakespeare.lit/contests.php
</instructions>
<x xmlns='jabber:x:oob'>
<url>http://www.shakespeare.lit/contests.php</url>
</x>
</query>
</iq>
]]></example>
</section1>
<section1 topic='Precedence Order' anchor='precedence'>
<p>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:</p>
<ol start='1'>
<li>x:data</li>
<li>iq:register</li>
<li>x:oob</li>
</ol>
<p>(Naturally, if the receiving application does not understand any of the foregoing namespaces, it MUST ignore the data qualified by that namespace.)</p>
<p>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 &lt;instructions/&gt; element only):</p>
<table caption='Recommended Processing of Namespace Combinations'>
<tr>
<th>Included Data</th>
<th>Recommended Processing</th>
<th>Notes</th>
</tr>
<tr>
<td>iq:register fields</td>
<td>Submit the completed iq:register fields.</td>
<td>This is the normal processing model for "legacy" services and clients.</td>
</tr>
<tr>
<td>x:data form + iq:register fields</td>
<td>Submit the completed x:data form if understood, otherwise submit the completed iq:register fields; however, an application MUST NOT submit both.</td>
<td>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).</td>
</tr>
<tr>
<td>x:data form + iq:register instructions</td>
<td>Submit the completed x:data form if understood, otherwise present the iq:register instructions to the user.</td>
<td>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.</td>
</tr>
<tr>
<td>x:data form + x:oob URL</td>
<td>Submit the completed x:data form if understood, otherwise present the provided URL as an alternative.</td>
<td>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.</td>
</tr>
<tr>
<td>x:data form + iq:register instructions + x:oob URL</td>
<td>Submit the completed x:data form if understood, otherwise present the iq:register instructions and provided URL as an alternative.</td>
<td>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.</td>
</tr>
<tr>
<td>iq:register instructions + x:oob URL</td>
<td>Present the iq:register instructions and provided URL as a redirect.</td>
<td>This combination MAY be returned by a host that wishes to redirect registration to a URL.</td>
</tr>
<tr>
<td>iq:register fields + x:oob URL</td>
<td>Submit the completed iq:register fields but optionally present the provided URL as an alternative.</td>
<td>This combination is NOT RECOMMENDED.</td>
</tr>
</table>
</section1>
<section1 topic='Key Element' anchor='key'>
<p><em>This element is obsolete, but is documented here for historical completeness.</em></p>
<p>The &lt;key/&gt; 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:</p>
<ol>
<li>Client sends IQ-get request to server.</li>
<li>Server returns required elements to client, including &lt;key/&gt; element containing a random string (often a SHA-1 hash).</li>
<li>Client sends registration information to server, including &lt;key/&gt; element with the same value provided by the server.</li>
<li>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.</li>
</ol>
<p>The &lt;key/&gt; element was also used during registration removal.</p>
</section1>
<section1 topic='Stream Feature' anchor='streamfeature'>
<p><cite>RFC 3920</cite> 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 &lt;stream:features/&gt; 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:</p>
<example caption='Advertising registration as a stream feature'><![CDATA[
<?xml version='1.0' encoding='utf-8'?>
<stream:stream xmlns:stream='http://etherx.jabber.org/streams/'
xmlns='jabber:client'
from='somedomain'
version='1.0'>
<stream:features>
...
<register xmlns='http://jabber.org/features/iq-register'/>
...
</stream:features>
]]></example>
<p>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).</p>
</section1>
<section1 topic='Error Handling' anchor='errors'>
<p>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;.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>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.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; includes the 'jabber:iq:register' namespace in its registry of protocol namespaces.</p>
</section2>
<section2 topic='Stream Features' anchor='registrar-stream'>
<p>The Jabber Registrar includes the 'http://jabber.org/features/iq-register' namespace in its registry of stream feature namespaces.</p>
</section2>
<section2 topic='URI Query Types' anchor='registrar-querytypes'>
<p>As authorized by &jep0147;, the Jabber Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).</p>
<p>As described below, the registered querytypes for registration management are "register" and "unregister".</p>
<section3 topic='register' anchor='registrar-querytypes-register'>
<p>The 'jabber:iq:register' namespace include a mechanism for creating a registration. The registered querytype for doing so is "register".</p>
<example caption='Register Action: IRI/URI'><![CDATA[
xmpp:marlowe.shakespeare.lit?register
]]></example>
<p>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:</p>
<example caption='Retrieving Registration Fields'><![CDATA[
<iq to='marlowe.shakespeare.lit' type='get'>
<query xmlns='jabber:iq:register'/>
</iq>
]]></example>
<example caption='Receiving Registration Fields'><![CDATA[
<iq from='marlowe.shakespeare.lit' type='result'>
<query xmlns='jabber:iq:register'>
<username/>
<password/>
</query>
</iq>
]]></example>
<p>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.</p>
<example caption='Sending Registration Information'><![CDATA[
<iq to='marlowe.shakespeare.lit' type='set'>
<query xmlns='jabber:iq:register'>
<username>juliet</username>
<password>R0m30</password>
</query>
</iq>
]]></example>
<p>The following submission registers the "register" querytype.</p>
<code><![CDATA[
<querytype>
<name>register</name>
<proto>jabber:iq:register</proto>
<desc>enables registering with a server or service</desc>
<doc>JEP-0077</doc>
</querytype>
]]></code>
</section3>
<section3 topic='unregister' anchor='registrar-querytypes-unregister'>
<p>The 'jabber:iq:register' namespace include a mechanism for cancelling an existing registration. The registered querytype for doing so is "unregister".</p>
<example caption='Unregister Action: IRI/URI'><![CDATA[
xmpp:marlowe.shakespeare.lit?unregister
]]></example>
<example caption='Unregister Action: Resulting Stanza'><![CDATA[
<iq to='marlowe.shakespeare.lit' type='get'>
<query xmlns='jabber:iq:register'>
<remove/>
</query>
</iq>
]]></example>
<p>The following submission registers the "unregister" querytype.</p>
<code><![CDATA[
<querytype>
<name>unregister</name>
<proto>jabber:iq:register</proto>
<desc>enables cancellation of a registration with a server or service</desc>
<doc>JEP-0077</doc>
</querytype>
]]></code>
</section3>
</section2>
<section2 topic='Field Standardization' anchor='registrar-formtypes'>
<p>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).</p>
<section3 topic='Registration' anchor='registrar-formtypes-register'>
<code><![CDATA[
<form_type>
<name>jabber:iq:register</name>
<doc>JEP-0077</doc>
<desc>Standardization of fields related to registration use case.</desc>
<field
var='username'
type='text-single'
label='Account name associated with the user'/>
<field
var='nick'
type='text-single'
label='Familiar name of the user'/>
<field
var='password'
type='text-private'
label='Password or secret for the user'/>
<field
var='name'
type='text-single'
label='Full name of the user'/>
<field
var='first'
type='text-single'
label='First name or given name of the user'/>
<field
var='last'
type='text-single'
label='Last name, surname, or family name of the user'/>
<field
var='email'
type='text-single'
label='Email address of the user'/>
<field
var='address'
type='text-single'
label='Street portion of a physical or mailing address'/>
<field
var='city'
type='text-single'
label='Locality portion of a physical or mailing address'/>
<field
var='state'
type='text-single'
label='Region portion of a physical or mailing address'/>
<field
var='zip'
type='text-single'
label='Postal code portion of a physical or mailing address'/>
<field
var='phone'
type='text-single'
label='Telephone number of the user'/>
<field
var='url'
type='text-single'
label='URL to web page describing the user'/>
<field
var='date'
type='text-single'
label='Some date (e.g., birth date, hire date, sign-up date)'/>
<field
var='misc'
type='text-single'
label='Free-form text field (obsolete)'/>
<field
var='text'
type='text-single'
label='Free-form text field (obsolete)'/>
<field
var='key'
type='text-single'
label='Session key for transaction (obsolete)'/>
</form_type>
]]></code>
</section3>
<section3 topic='Cancellation' anchor='registrar-formtypes-cancel'>
<code><![CDATA[
<form_type>
<name>jabber:iq:register:cancel</name>
<doc>JEP-0077</doc>
<desc>Standardization of fields related to cancellation use case.</desc>
<field
var='password'
type='text-private'
label='Password or secret for the user'/>
<field
var='username'
type='text-single'
label='Account name associated with the user'/>
</form_type>
]]></code>
</section3>
<section3 topic='Change Password' anchor='registrar-formtypes-changepassword'>
<code><![CDATA[
<form_type>
<name>jabber:iq:register:cancel</name>
<doc>JEP-0077</doc>
<desc>Standardization of fields related to change password use case.</desc>
<field
var='old_password'
type='text-private'
label='Old password for the user'/>
<field
var='password'
type='text-private'
label='Desired password for the user'/>
<field
var='username'
type='text-single'
label='Account name associated with the user'/>
</form_type>
]]></code>
</section3>
</section2>
</section1>
<section1 topic='XML Schemas' anchor='schemas'>
<section2 topic='jabber:iq:register' anchor='schemas-register'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:iq:register'
xmlns='jabber:iq:register'
elementFormDefault='qualified'>
<xs:import
namespace='jabber:x:data'
schemaLocation='http://jabber.org/protocol/x-data/x-data.xsd'/>
<xs:import
namespace='jabber:x:oob'
schemaLocation='http://jabber.org/protocol/oob/x-oob.xsd'/>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0077: http://www.jabber.org/jeps/jep-0077.html
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:sequence xmlns:xdata='jabber:x:data'
xmlns:xoob='jabber:x:oob'>
<xs:choice minOccurs='0'>
<xs:sequence minOccurs='0'>
<xs:element name='registered' type='empty' minOccurs='0'/>
<xs:element name='instructions' type='xs:string' minOccurs='0'/>
<xs:element name='username' type='xs:string' minOccurs='0'/>
<xs:element name='nick' type='xs:string' minOccurs='0'/>
<xs:element name='password' type='xs:string' minOccurs='0'/>
<xs:element name='name' type='xs:string' minOccurs='0'/>
<xs:element name='first' type='xs:string' minOccurs='0'/>
<xs:element name='last' type='xs:string' minOccurs='0'/>
<xs:element name='email' type='xs:string' minOccurs='0'/>
<xs:element name='address' type='xs:string' minOccurs='0'/>
<xs:element name='city' type='xs:string' minOccurs='0'/>
<xs:element name='state' type='xs:string' minOccurs='0'/>
<xs:element name='zip' type='xs:string' minOccurs='0'/>
<xs:element name='phone' type='xs:string' minOccurs='0'/>
<xs:element name='url' type='xs:string' minOccurs='0'/>
<xs:element name='date' type='xs:string' minOccurs='0'/>
<xs:element name='misc' type='xs:string' minOccurs='0'/>
<xs:element name='text' type='xs:string' minOccurs='0'/>
<xs:element name='key' type='xs:string' minOccurs='0'/>
</xs:sequence>
<xs:element name='remove' type='empty' minOccurs='0'/>
</xs:choice>
<xs:element ref='xdata:x' minOccurs='0'/>
<xs:element ref='xoob:x' minOccurs='0'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section2>
<section2 topic='Stream Feature' anchor='schemas-streams'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/features/iq-register'
xmlns='http://jabber.org/features/iq-register'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0077: http://www.jabber.org/jeps/jep-0077.html
</xs:documentation>
</xs:annotation>
<xs:element name='register' type='empty'/>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section2>
</section1>
</jep>

369
xep-0078.xml Normal file
View File

@ -0,0 +1,369 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Non-SASL Authentication</title>
<abstract>This document specifies a protocol for authentication with Jabber servers and services using the jabber:iq:auth namespace. Note Well: The protocol specified herein has been deprecated in favor of SASL authentication as specified in RFC 3920.</abstract>
&LEGALNOTICE;
<number>0078</number>
<status>Deprecated</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>RFC 3174</spec>
</dependencies>
<supersedes/>
<supersededby>
<spec>RFC 3920</spec>
</supersededby>
<shortname>iq-auth</shortname>
<schemaloc>
<url>http://jabber.org/protocol/iq-auth/iq-auth.xsd</url>
</schemaloc>
<expires>2007-03-13</expires>
<revision>
<version>2.3</version>
<date>2006-09-13</date>
<initials>psa</initials>
<remark><p>Per a vote of the Jabber Council, changed status to Deprecated.</p></remark>
</revision>
<revision>
<version>2.2</version>
<date>2005-06-28</date>
<initials>psa</initials>
<remark><p>Corrected error in schema and example (username is not required in IQ-get).</p></remark>
</revision>
<revision>
<version>2.1</version>
<date>2004-12-09</date>
<initials>psa</initials>
<remark><p>Changed SHOULD to MUST regarding priority of SASL (RFC 3920) over jabber:iq:auth (JEP-0078).</p></remark>
</revision>
<revision>
<version>2.0</version>
<date>2004-10-20</date>
<initials>psa</initials>
<remark><p>Per a vote of the Jabber Council, advanced status to Final.</p></remark>
</revision>
&stpeter;
<revision>
<version>1.8</version>
<date>2004-10-18</date>
<initials>psa</initials>
<remark><p>Specified advertising iq-auth stream feature is implementation-specific; clarified several small matters in the text.</p></remark>
</revision>
<revision>
<version>1.7</version>
<date>2004-07-27</date>
<initials>psa</initials>
<remark><p>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.</p></remark>
</revision>
<revision>
<version>1.6</version>
<date>2004-07-21</date>
<initials>psa</initials>
<remark><p>Removed reference to UTF-16, which is disallowed by XMPP Core; removed reference to character escaping in digest authentication pending list discussion.</p></remark>
</revision>
<revision>
<version>1.5</version>
<date>2004-02-18</date>
<initials>psa</initials>
<remark><p>Added optional stream feature.</p></remark>
</revision>
<revision>
<version>1.4</version>
<date>2004-02-03</date>
<initials>psa</initials>
<remark><p>Clarified that username and resource are required for authentication.</p></remark>
</revision>
<revision>
<version>1.3</version>
<date>2003-11-26</date>
<initials>psa</initials>
<remark><p>Added XMPP error handling.</p></remark>
</revision>
<revision>
<version>1.2</version>
<date>2003-11-06</date>
<initials>psa</initials>
<remark><p>Addressed case of attempting jabber:iq:auth after SASL failure.</p></remark>
</revision>
<revision>
<version>1.1</version>
<date>2003-10-02</date>
<initials>psa</initials>
<remark><p>Moved change password use case to JEP-0077.</p></remark>
</revision>
<revision>
<version>1.0</version>
<date>2003-06-18</date>
<initials>psa</initials>
<remark><p>Per a vote of the Jabber Council, advanced status to Draft.</p></remark>
</revision>
<revision>
<version>0.8</version>
<date>2003-06-18</date>
<initials>psa</initials>
<remark><p>Changes to address Council concerns.</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2003-06-13</date>
<initials>psa</initials>
<remark><p>Added change password use case; added more details to security considerations.</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2003-06-12</date>
<initials>psa</initials>
<remark><p>Added digest example; clarified escaping requirements; further specified error conditions; added more details to security considerations.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-06-06</date>
<initials>psa</initials>
<remark><p>Removed XMPP-style error conditions until formats are stable.</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-05-30</date>
<initials>psa</initials>
<remark><p>Removed "enhanced digest" content, added information about expiration date.</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-05-28</date>
<initials>psa</initials>
<remark><p>Added "enhanced digest" method.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-05-20</date>
<initials>psa</initials>
<remark><p>Slight editorial revisions.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-04-10</date>
<initials>psa</initials>
<remark><p>Initial version.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p><em>Note Well: The protocol specified herein has been deprecated in favor of SASL authentication as specified in &rfc3920;.</em></p>
<p>Jabber technologies have long included a wire protocol that enables a client to authenticate with a server. <note>Component authentication is out of scope for this JEP, and is specified separately in &jep0114;.</note> The method originally used in the Jabber community makes use of the 'jabber:iq:auth' namespace and has been documented variously in Internet-Drafts and elsewhere. Because the XMPP specifications required upgraded authentication methods using SASL (see &rfc4422;) in order to progress through the Internet Standards Process, documentation of the 'jabber:iq:auth' namespace was removed from those specifications.</p>
<p>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.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>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:</p>
<ol>
<li>plaintext</li>
<li>digest (using the SHA1 algorithm specified in &rfc3174;)</li>
</ol>
<p>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.</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='User Authenticates with Server' anchor='usecases-auth'>
<p>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.</p>
<example caption='Client Opens Stream to Server'><![CDATA[
<stream:stream to='shakespeare.lit'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'>
]]></example>
<example caption='Server Opens Streams to Client'><![CDATA[
<stream:stream from='shakespeare.lit'
xmlns='jabber:client'
xmlns:stream='http://etherx.jabber.org/streams'
id='3EE948B0'>
]]></example>
<example caption='Client Requests Authentication Fields from Server'><![CDATA[
<iq type='get' to='shakespeare.lit' id='auth1'>
<query xmlns='jabber:iq:auth'/>
</iq>
]]></example>
<example caption='Server Returns Authentication Fields to Client'><![CDATA[
<iq type='result' id='auth1'>
<query xmlns='jabber:iq:auth'>
<username/>
<password/>
<digest/>
<resource/>
</query>
</iq>
]]></example>
<p>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 <cite>RFC 3920</cite>), it MUST return a &unavailable; error. If the client previously attempted SASL authentication but that attempt failed, the server MUST return a &lt;policy-violation/&gt; stream error (see <cite>RFC 3920</cite> regarding stream error syntax).</p>
<p>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 <cite>RFC 3920</cite> (e.g., to enable the server to provide the resource). The &lt;username/&gt; and &lt;resource/&gt; 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.</p>
<p>The foregoing stanza shows that the server supports both plaintext authentication (via the &lt;password/&gt; element) and digest authentication with SHA1-encrypted passwords (via the &lt;digest/&gt; element).</p>
<p>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.</p>
<example caption='Client Provides Required Information (Plaintext)'><![CDATA[
<iq type='set' id='auth2'>
<query xmlns='jabber:iq:auth'>
<username>bill</username>
<password>Calli0pe</password>
<resource>globe</resource>
</query>
</iq>
]]></example>
<p>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 <cite>RFC 3920</cite>, i.e., UTF-8 as defined in &rfc3269;).</p>
<p>The value of the &lt;digest/&gt; element MUST be computed according to the following algorithm:</p>
<ol>
<li>Concatenate the Stream ID received from the server with the password. <note>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.</note></li>
<li>Hash the concatenated string according to the SHA1 algorithm, i.e., SHA1(concat(sid, password)).</li>
<li>Ensure that the hash output is in hexidecimal format, not binary or base64.</li>
<li>Convert the hash output to all lowercase characters.</li>
</ol>
<example caption='Client Provides Required Information (Digest)'><![CDATA[
<iq type='set' id='auth2'>
<query xmlns='jabber:iq:auth'>
<username>bill</username>
<digest>48fc78be9ec8f86d8ce1c39c320c97c21d62334d</digest>
<resource>globe</resource>
</query>
</iq>
]]></example>
<p>The character data shown in the &lt;digest/&gt; 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'.</p>
<p>If the credentials provided match those known by the server, the client will be successfully authenticated.</p>
<example caption='Server Informs Client of Successful Authentication'><![CDATA[
<iq type='result' id='auth2'/>
]]></example>
<p>Alternatively, authentication may fail. Possible causes of failure include:</p>
<ol>
<li>The user provided incorrect credentials.</li>
<li>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.</li>
<li>The user did not provide all of the required information (e.g., did not provide a username or resource).</li>
</ol>
<p>Although <cite>RFC 3920</cite> 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.</p>
<example caption='Server Informs Client of Failed Authentication (Incorrect Credentials)'><![CDATA[
<iq type='error' id='auth2'>
<error code='401' type='auth'>
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<example caption='Server Informs Client of Failed Authentication (Resource Conflict)'><![CDATA[
<iq type='error' id='auth2'>
<error code='409' type='cancel'>
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<example caption='Server Informs Client of Failed Authentication (Required Information Not Provided)'><![CDATA[
<iq type='error' id='auth2'>
<error code='406' type='modify'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Stream Feature' anchor='streamfeature'>
<p><cite>RFC 3920</cite> 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 &lt;stream:features/&gt; 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).</p>
<example caption='Advertising non-SASL authentication as a stream feature'><![CDATA[
<?xml version='1.0' encoding='utf-8'?>
<stream:stream xmlns:stream='http://etherx.jabber.org/streams/'
xmlns='jabber:client'
from='somedomain'
version='1.0'>
<stream:features>
...
<mechanisms xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
<mechanism>DIGEST-MD5</mechanism>
<mechanism>PLAIN</mechanism>
</mechanisms>
<auth xmlns='http://jabber.org/features/iq-auth'/>
...
</stream:features>
]]></example>
<p>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).</p>
</section1>
<section1 topic='Error Handling' anchor='errors'>
<p>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 <cite>RFC 3920</cite>. A compliant server or service implementation MUST support both old-style and new-style error handling. A compliant client implementation SHOULD support both.</p>
</section1>
<section1 topic='Expiration Date' anchor='expiration'>
<p>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.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>Use of the 'jabber:iq:auth' method for client-server authentication is not as secure as SASL authentication (defined in <cite>RFC 3920</cite>). 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 &lt;policy-violation/&gt; stream error to the client.</p>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; includes the 'jabber:iq:auth' namespace in its registry of protocol namespaces.</p>
</section2>
<section2 topic='Stream Features' anchor='registrar-stream'>
<p>The Jabber Registrar includes the 'http://jabber.org/features/iq-auth' namespace in its registry of stream feature namespaces.</p>
</section2>
</section1>
<section1 topic='XML Schemas' anchor='schemas'>
<section2 topic='jabber:iq:auth' anchor='schemas-auth'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:iq:auth'
xmlns='jabber:iq:auth'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0078: http://www.jabber.org/jeps/jep-0078.html
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:sequence>
<xs:element name='username' type='xs:string' minOccurs='0'/>
<xs:choice>
<xs:element name='password' type='xs:string' minOccurs='0'/>
<xs:element name='digest' type='xs:string' minOccurs='0'/>
</xs:choice>
<xs:element name='resource' type='xs:string' minOccurs='0'/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section2>
<section2 topic='Stream Feature' anchor='schemas-stream'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/features/iq-auth'
xmlns='http://jabber.org/features/iq-auth'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0078: http://www.jabber.org/jeps/jep-0078.html
</xs:documentation>
</xs:annotation>
<xs:element name='auth' type='empty'/>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section2>
</section1>
</jep>

1310
xep-0079.xml Normal file
View File

File diff suppressed because it is too large Load Diff

524
xep-0080.xml Normal file
View File

@ -0,0 +1,524 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>User Geolocation</title>
<abstract>This document defines an XMPP protocol extension for communicating information about the current geographical location of an entity.</abstract>
&LEGALNOTICE;
<number>0080</number>
<status>Draft</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>JEP-0060</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>geoloc</shortname>
<schemaloc>
<url>http://jabber.org/protocol/geoloc/geoloc.xsd</url>
</schemaloc>
&hildjj;
&stpeter;
<revision>
<version>1.3</version>
<date>2006-08-21</date>
<initials>psa</initials>
<remark><p>Folded in civil location from JEP-0112.</p></remark>
</revision>
<revision>
<version>1.2</version>
<date>2005-05-12</date>
<initials>psa</initials>
<remark><p>Changed xs:string to xs:decimal for bearing and specified that bearing is to be interpreted as decimal degrees relative to true north.</p></remark>
</revision>
<revision>
<version>1.1</version>
<date>2004-10-29</date>
<initials>psa</initials>
<remark><p>Changed xs:int to xs:decimal for altitude; changed MUST NOT to SHOULD NOT regarding inferences about accuracy.</p></remark>
</revision>
<revision>
<version>1.0</version>
<date>2004-10-12</date>
<initials>psa</initials>
<remark><p>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.</p></remark>
</revision>
<revision>
<version>0.9</version>
<date>2004-10-12</date>
<initials>psa</initials>
<remark><p>Clarified several points in the implementation notes.</p></remark>
</revision>
<revision>
<version>0.8</version>
<date>2004-09-15</date>
<initials>psa</initials>
<remark><p>Specified error flow for IQ example.</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2004-04-25</date>
<initials>psa</initials>
<remark><p>Corrected several errors; added reference to JEP-0033.</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2004-02-19</date>
<initials>psa</initials>
<remark><p>Reverted from infobits to geoloc elements; moved physical address protocol back to JEP-0112.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-12-16</date>
<initials>psa</initials>
<remark><p>Converted to use of infobits.</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-09-08</date>
<initials>psa</initials>
<remark><p>Merged in contents of JEP-0112.</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-08-21</date>
<initials>psa</initials>
<remark><p>Changed protocol name from 'location' to 'geoloc'.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-07-29</date>
<initials>psa</initials>
<remark><p>Incorporated Standards JIG feedback; changed JEP type to Informational.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-04-15</date>
<initials>jjh</initials>
<remark><p>Initial version.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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:</p>
<ul>
<li>Publishing location information to a set of subscribers.</li>
<li>Querying another entity for its location.</li>
<li>Sending location information to another entity.</li>
<li>Attaching location information to presence.</li>
</ul>
<p>Geographical location is captured in terms of Global Positioning System (GPS) coordinates as well as civil location (city, street, building, etc.).</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>The format defined herein was designed to address the following requirements:</p>
<ul>
<li>It shall be possible to encapsulate location in terms of Global Positioning System (GPS) coordinates as well as civil location (city, street, building, etc.).</li>
<li>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.</li>
<li>It shall be possible to specify the known amount of error in the GPS coordinates.</li>
<li>It shall be possible to include a natural-language description of the location.</li>
</ul>
</section1>
<section1 topic='Data Format' anchor='format'>
<p>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 &lt;geoloc/&gt; 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:</p>
<table caption='Child Elements'>
<tr>
<th>Element Name</th>
<th>Datatype</th>
<th>Definition</th>
<th>Example</th>
</tr>
<tr>
<td>alt</td>
<td>xs:decimal</td>
<td>Altitude in meters above or below sea level</td>
<td>1609</td>
</tr>
<tr>
<td>area</td>
<td>xs:string</td>
<td>A named area such as a campus or neighborhood</td>
<td>Central Park</td>
</tr>
<tr>
<td>bearing</td>
<td>xs:decimal</td>
<td>GPS bearing (direction in which the entity is heading to reach its next waypoint), measured in decimal degrees relative to true north <note>It is the responsibility of the receiver to translate bearing into decimal degrees relative to magnetic north, if desired.</note></td>
<td>&nbsp;</td>
</tr>
<tr>
<td>building</td>
<td>xs:string</td>
<td>A specific building on a street or in an area</td>
<td>The Empire State Building</td>
</tr>
<tr>
<td>country</td>
<td>xs:string</td>
<td>The nation where the user is located</td>
<td>USA</td>
</tr>
<tr>
<td>datum</td>
<td>xs:string</td>
<td>GPS datum <note>If datum is not included, receiver MUST assume WGS84; receivers MUST implement WGS84; senders MAY use another datum, but it is not recommended.</note></td>
<td>&nbsp;</td>
</tr>
<tr>
<td>description</td>
<td>xs:string</td>
<td>A natural-language name for or description of the location</td>
<td>Bill's house</td>
</tr>
<tr>
<td>error</td>
<td>xs:decimal</td>
<td>Horizontal GPS error in arc minutes</td>
<td>10</td>
</tr>
<tr>
<td>floor</td>
<td>xs:string</td>
<td>A particular floor in a building</td>
<td>102</td>
</tr>
<tr>
<td>lat</td>
<td>xs:decimal</td>
<td>Latitude in decimal degrees North</td>
<td>39.75</td>
</tr>
<tr>
<td>locality</td>
<td>xs:string</td>
<td>A locality within the administrative region, such as a town or city</td>
<td>New York City</td>
</tr>
<tr>
<td>lon</td>
<td>xs:decimal</td>
<td>Longitude in decimal degrees East</td>
<td>-104.99</td>
</tr>
<tr>
<td>postalcode</td>
<td>xs:string</td>
<td>A code used for postal delivery</td>
<td>10027</td>
</tr>
<tr>
<td>region</td>
<td>xs:string</td>
<td>An administrative region of the nation, such as a state or province</td>
<td>New York</td>
</tr>
<tr>
<td>room</td>
<td>xs:string</td>
<td>A particular room in a building</td>
<td>Observatory</td>
</tr>
<tr>
<td>street</td>
<td>xs:string</td>
<td>A thoroughfare within the locality, or a crossing of two thoroughfares</td>
<td>34th and Broadway</td>
</tr>
<tr>
<td>text</td>
<td>xs:string</td>
<td>A catch-all element that captures any other information about the location</td>
<td>Northwest corner of the lobby</td>
</tr>
<tr>
<td>timestamp</td>
<td>xs:datetime</td>
<td>UTC timestamp specifying the moment when the reading was taken (MUST conform to the DateTime profile of &jep0082;)</td>
<td>2004-02-19T21:12Z</td>
</tr>
</table>
<p>NOTE: The datatypes specified above are defined in &w3xmlschema2;.</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<p>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.</p>
<section2 topic='Entity publishes location via pubsub' anchor='usecases-pubsub'>
<p>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 <cite>JEP-0163</cite>).</p>
<example caption='Entity publishes location'><![CDATA[
<iq type='set' from='portia@merchantofvenice.lit/pda'> id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='n48ad4fj78zn38st734'>
<item id='a1s2d3f4g5h6bjeh936'>
<geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
<country>Italy</country>
<lat>45.44</lat>
<locality>Venice</locality>
<lon>12.33</lon>
</geoloc>
</item>
</publish>
</pubsub>
</iq>
]]></example>
<example caption='Subscriber receives event with payload'><![CDATA[
<message from='portia@merchantofvenice.lit'
to='bassanio@merchantofvenice.lit/home'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='n48ad4fj78zn38st734'>
<item id='a1s2d3f4g5h6bjeh936'>
<geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
<country>Italy</country>
<lat>45.44</lat>
<locality>Venice</locality>
<lon>12.33</lon>
</geoloc>
</item>
</items>
</event>
</message>
]]></example>
</section2>
<section2 topic='Entity requests the location of another entity' anchor='usecases-request'>
<p>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:</p>
<example caption='Location request'><![CDATA[
<iq type='get'
id='loc_1'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/garden'>
<geoloc xmlns='http://jabber.org/protocol/geoloc'/>
</iq>]]></example>
<p>The receiving entity SHOULD make a careful access control decision before returning the actual location.</p>
<example caption='Successful location response'><![CDATA[
<iq type='result'
id='loc_1'
to='juliet@capulet.com/balcony'
from='romeo@montague.net/garden'>
<geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
<country>Italy</country>
<lat>45.44</lat>
<locality>Venice</locality>
<lon>12.33</lon>
</geoloc>
</iq>]]></example>
<p>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 &notallowed;:</p>
<example caption='Access to location information denied'><![CDATA[
<iq type='error'
id='loc_1'
to='juliet@capulet.com/balcony'
from='romeo@montague.net/garden'>
<geoloc xmlns='http://jabber.org/protocol/geoloc'/>
<error code='403' type='auth'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section2>
<section2 topic='Sending location' anchor='usecases-send'>
<p>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.</p>
<example caption='Message containing location'><![CDATA[
<message
to='polonius@hamlet.lit'
from='horatio@hamlet.lit/castle'>
<body>This message contains a location.</body>
<geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
<description>Elsinore</description>
<lat>56.033</lat>
<lon>12.618</lon>
</geoloc>
<x xmlns='jabber:x:oob'>
<url>
http://www.mapquest.com/maps/map.adp?latlongtype=decimal&latitude=56.033&longitude=12.618
</url>
</x>
</message>]]></example>
</section2>
<section2 topic='Entity publishes location in presence' anchor='usecases-presence'>
<p>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):</p>
<example caption='Location in presence'><![CDATA[
<presence>
<geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
<alt>1609</alt>
<description>Jabber, Inc.</description>
<error>10</error>
<lat>39.75477</lat>
<lon>-104.99768</lon>
<timestamp>2004-02-19T21:12Z</timestamp>
</geoloc>
</presence>]]></example>
</section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<p>Avoid "Mars probe" issues: as specified in Table 1, the units for &lt;lat/&gt; and &lt;lon/&gt; MUST be decimal degrees (where South and West are negative, North and East are positive), the units for &lt;alt/&gt; MUST be meters above or below sea level, and the units for &lt;error/&gt; MUST be arc minutes.</p>
<p>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).</p>
<p>Inferences SHOULD NOT be made about accuracy from the number of digits specified in the location or altitude.</p>
<p>Why the datum madness? See &lt;<link url='http://www.jabber.org/protocol/geoloc/gps_datum.html'>http://www.jabber.org/protocol/geoloc/gps_datum.html</link>&gt; for an example.</p>
<p>An entity can provide a GPS path by publishing a series of items (i.e., multiple pubsub events) with appropriate values of the &lt;timestamp/&gt; element.</p>
</section1>
<section1 topic='Mapping to Other Formats' anchor='mapping'>
<p>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:</p>
<ol>
<li><p>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 <note>The Wireless Village Initiative: Presence Attributes v1.1 (WV-029); for further information, visit &lt;<link url='http://www.openmobilealliance.org/tech/affiliates/wv/wvindex.html'>http://www.openmobilealliance.org/tech/affiliates/wv/wvindex.html</link>&gt;.</note>.</p></li>
<li><p>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").</p></li>
</ol>
<p>The following table also maps the format defined herein to the vCard XML format specified in &jep0054;.</p>
<table caption='Mapping XMPP Physical Location to IMPS, PIDF-LO, and vCard'>
<tr>
<th>XMPP</th>
<th>Wireless Village / IMPS</th>
<th>SIMPLE (PIDF-LO)</th>
<th>vCard XML</th>
</tr>
<tr>
<td align='center'>&lt;country/&gt;</td>
<td align='center'>&lt;Country/&gt;</td>
<td align='center'>&lt;country/&gt;</td>
<td align='center'>&lt;CTRY/&gt;
<note>As noted in JEP-0054, the XML vCard format defined in draft-dawson-vcard-xml-dtd-01 specified a &lt;COUNTRY/&gt; element rather than a &lt;CTRY/&gt; element; refer to JEP-0054 for details.</note>
</td>
</tr>
<tr>
<td align='center'>&lt;region/&gt;</td>
<td align='center'>--</td>
<td align='center'>&lt;A1/&gt; and/or &lt;A2/&gt;</td>
<td align='center'>&lt;REGION/&gt;</td>
</tr>
<tr>
<td align='center'>&lt;locality/&gt;</td>
<td align='center'>&lt;City/&gt;</td>
<td align='center'>&lt;A3/&gt;</td>
<td align='center'>&lt;LOCALITY/&gt;</td>
</tr>
<tr>
<td align='center'>&lt;area/&gt;</td>
<td align='center'>&lt;NamedArea/&gt;</td>
<td align='center'>&lt;A4/&gt; and/or &lt;A5/&gt;</td>
<td align='center'>--</td>
</tr>
<tr>
<td align='center'>&lt;street/&gt;</td>
<td align='center'>&lt;Street/&gt;
<note>The IMPS specification also enables one to define an intersection (e.g., "Broadway and 34th Street") as the combination of a &lt;Crossing1/&gt; element (e.g., "Broadway") and a &lt;Crossing2/&gt; element (e.g., "34th Street"). To map from IMPS to XMPP, an application SHOULD map such a combination to one XMPP &lt;street/&gt; element.</note>
</td>
<td align='center'>&lt;A6/&gt;
<note>The PIDF-LO format provides information elements for much more granular control over a traditional street address; in PIDF-LO the &lt;A6/&gt; element is the street name only, and further information is provided in distinct elements for a leading street direction (e.g., "N"), trailing street suffix (e.g., "SW"), street suffix (e.g., "Avenue"), house number (e.g., "909"), and house number suffix (e.g., "1/2"). To map from PIDF-LO to XMPP, an application SHOULD construct the complete street address from the PIDF-LO elements (&lt;A6/&gt;, &lt;PRD/&gt;, &lt;POD/&gt;, &lt;STS/&gt;, &lt;HNO/&gt;, and &lt;HNS/&gt;) and map the result to one XMPP &lt;street/&gt; element.</note>
</td>
<td align='center'>&lt;STREET/&gt;</td>
</tr>
<tr>
<td align='center'>&lt;building/&gt;</td>
<td align='center'>&lt;Building/&gt;</td>
<td align='center'>&lt;LMK/&gt;</td>
<td align='center'>--</td>
</tr>
<tr>
<td align='center'>&lt;floor/&gt;</td>
<td align='center'>--</td>
<td align='center'>&lt;FLR/&gt;</td>
<td align='center'>--</td>
</tr>
<tr>
<td align='center'>&lt;room/&gt;</td>
<td align='center'>--</td>
<td align='center'>--</td>
<td align='center'>--</td>
</tr>
<tr>
<td align='center'>&lt;postalcode/&gt;</td>
<td align='center'>--</td>
<td align='center'>&lt;PC/&gt;</td>
<td align='center'>&lt;PCODE/&gt;</td>
</tr>
<tr>
<td align='center'>&lt;text/&gt;</td>
<td align='center'>&lt;FreeTextLocation/&gt;</td>
<td align='center'>&lt;LOC/&gt;</td>
<td align='center'>&lt;EXTADR/&gt;</td>
</tr>
<tr>
<td align='center'>--</td>
<td align='center'>&lt;Accuracy/&gt;
<note>This element provides accuracy in meters. The geolocation protocol defined in JEP-0080 specifies such an element for XMPP, which SHOULD be used when mapping from IMPS to XMPP.</note>
</td>
<td align='center'>--</td>
<td align='center'>--</td>
</tr>
<tr>
<td align='center'>--</td>
<td align='center'>--</td>
<td align='center'>&lt;NAM/&gt;
<note>This element provides a name for the location, e.g., a certain store in a building. This SHOULD be mapped to the XMPP &lt;text/&gt; element.</note>
</td>
<td align='center'>--</td>
</tr>
</table>
</section1>
<section1 topic='Internationalization Considerations' anchor='i18n'>
<p>Because the character data contained in &lt;geoloc/&gt; child elements of type 'xs:string' is intended to be readable by humans, the &lt;geoloc/&gt; element SHOULD possess an 'xml:lang' attribute specifying the natural language of such character data.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>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 &lt;error/&gt; element SHOULD NOT be included.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; includes 'http://jabber.org/protocol/geoloc' to its registry of protocol namespaces.</p>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/geoloc'
xmlns='http://jabber.org/protocol/geoloc'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0080: http://www.jabber.org/jeps/jep-0080.html
</xs:documentation>
</xs:annotation>
<xs:element name='geoloc'>
<xs:complexType>
<xs:sequence minOccur='0'>
<xs:element name='alt' minOccurs='0' type='xs:decimal'/>
<xs:element name='area' minOccurs='0' type='xs:string'/>
<xs:element name='bearing' minOccurs='0' type='xs:decimal'/>
<xs:element name='building' minOccurs='0' type='xs:string'/>
<xs:element name='country' minOccurs='0' type='xs:string'/>
<xs:element name='datum' minOccurs='0' type='xs:string'/>
<xs:element name='description' minOccurs='0' type='xs:string'/>
<xs:element name='error' minOccurs='0' type='xs:decimal'/>
<xs:element name='floor' minOccurs='0' type='xs:string'/>
<xs:element name='lat' minOccurs='0' type='xs:decimal'/>
<xs:element name='locality' minOccurs='0' type='xs:string'/>
<xs:element name='lon' minOccurs='0' type='xs:decimal'/>
<xs:element name='postalcode' minOccurs='0' type='xs:string'/>
<xs:element name='region' minOccurs='0' type='xs:string'/>
<xs:element name='room' minOccurs='0' type='xs:string'/>
<xs:element name='street' minOccurs='0' type='xs:string'/>
<xs:element name='text' minOccurs='0' type='xs:string'/>
<xs:element name='timestamp' minOccurs='0' type='xs:datetime'/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</jep>

270
xep-0081.xml Normal file
View File

@ -0,0 +1,270 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Jabber MIME Type</title>
<abstract>This JEP specifies a MIME type for launching a Jabber client as a helper application from most modern web browsers, and for completing basic use cases once the client is launched.</abstract>
&LEGALNOTICE;
<number>0081</number>
<status>Retracted</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>RFC 2045</spec>
<spec>RFC 3023</spec>
<spec>JEP-0045</spec>
<spec>JEP-0077</spec>
</dependencies>
<supersedes>None</supersedes>
<supersededby>None</supersededby>
<shortname>mimetype</shortname>
&hildjj;
&stpeter;
<revision>
<version>0.5</version>
<date>2005-07-19</date>
<initials>psa</initials>
<remark>Retracted the proposal (again) in favor of draft-saintandre-xmpp-iri.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2005-01-05</date>
<initials>psa</initials>
<remark>Reinstated the proposal since it fills a need not met by RFC 3923 and draft-saintandre-xmpp-uri; specified XML schema; specified IANA considerations, including content-type registration; further specified security considerations; removed use cases for service discovery, directory search, vCard lookup, and authentication; added more detailed descriptive text to remaining use cases.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2004-07-26</date>
<initials>psa</initials>
<remark>Formally retracted this proposal in favor of the relevant Internet-Drafts.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-08-18</date>
<initials>psa</initials>
<remark>Added authentication example.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-04-21</date>
<initials>psa</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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 &lt;xmpp:user@domain&gt;.</p>
<p>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
<note>See, for instance, &lt;<link url='http://www.mozilla.org/docs/web-developer/mimetypes.html'>http://www.mozilla.org/docs/web-developer/mimetypes.html</link>&gt; for information about MIME support in the Mozilla family of web browsers.</note>
is to define a MIME type (in accordance with &rfc2045;) and then reconfigure the relevant server and client software to correctly handle the new MIME type.</p>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<p>The solution MUST enable a user to complete the following use cases, support for which is REQUIRED:</p>
<ul>
<li>Send a single message to another user.</li>
<li>Initiate a one-to-one chat session with another user.</li>
<li>Subscribe to another user's presence.</li>
</ul>
<p>In addition, the solution SHOULD enable a user to complete the following use cases, support for which is RECOMMENDED:</p>
<ul>
<li>Join a groupchat room.</li>
<li>Register with a service.</li>
<!--
<li>Send a &jep0030; request.</li>
<li>Search a user directory (see &jep0055;).</li>
<li>Request another user's vCard.</li>
-->
</ul>
<p>These use cases are defined below.</p>
<section2 topic='Sending a Message' anchor='message'>
<p>In order to send a message to a contact, the user opens an XMPP file of the following form:</p>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<jabber>
<message jid='stpeter@jabber.org'/>
</jabber>
]]></code>
<p>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.</p>
</section2>
<section2 topic='Starting a Chat' anchor='chat'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<jabber>
<chat jid='stpeter@jabber.org'/>
</jabber>
]]></code>
<p>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 <cite>XMPP IM</cite>, first authenticating with the user's Jabber/XMPP server if necessary.</p>
</section2>
<section2 topic='Subscribing to Presence' anchor='subscribe'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<jabber>
<subscribe jid='stpeter@jabber.org'/>
</jabber>
]]></code>
<p>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 <cite>XMPP IM</cite>, 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 <cite>XMPP IM</cite>.</p>
</section2>
<section2 topic='Joining a Groupchat Room' anchor='groupchat'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<jabber>
<groupchat jid='jdev@conference.jabber.org'/>
</jabber>
]]></code>
<p>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.</p>
</section2>
<section2 topic='Registering with a Service' anchor='register'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<jabber>
<register jid='headlines.shakespeare.lit'/>
</jabber>
]]></code>
<p>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 <cite>JEP-0077</cite>.</p>
</section2>
<!--
<section2 topic='Making a Service Discovery Request' anchor='disco'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<jabber>
<disco jid='shakespeare.lit'>
<items/>
<info/>
</disco>
</jabber>
]]></code>
<p>The browser passes this file to the helper application, which shall instantiate an appropriate interface for sending a service discovery request to the JID defined in the file.</p>
</section2>
<section2 topic='Searching a Directory' anchor='search'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<jabber>
<search jid='users.jabber.org'>
<nick>stpeter</nick>
</search>
</jabber>
]]></code>
<p>The browser passes this file to the helper application, which shall instantiate an appropriate interface for searching the directory associated with the JID defined in the file, including pre-populated information as specified (e.g., nick, first name, last name).</p>
</section2>
<section2 topic='Requesting a vCard' anchor='vcard'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<jabber>
<vcard jid='stpeter@jabber.org'/>
</jabber>
]]></code>
<p>The browser passes this file to the helper application, which shall instantiate an appropriate interface for requesting the vCard of the JID defined in the file.</p>
</section2>
-->
</section1>
<!--
<section1 topic='Authentication' anchor='auth'>
<p>The solution should also enable a user to authenticate with a server using parameters defined in the file, e.g., for the purpose of single-sign-on (SSO).</p>
<code><![CDATA[
<connect>
<host>somehost</host>
<ip>10.1.1.1</ip>
<port>5222</port>
<ssl/>
<authenticate>
<username>foo</username>
<password>test</password>
<resource>Work</resource>
</authenticate>
</connect>
]]></code>
<p>The username, password, and resource are not required if there is some other extension inside authenticate, that, e.g. does SSO. Authenticate is mostly useful only for these SSO situations, anyway. If the user is already connected, the application SHOULD ignore the &lt;connect/&gt; block.</p>
</section1>
-->
<section1 topic='Security Considerations' anchor='security'>
<p>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 <cite>RFC 3920</cite> (Sections 12.1 through 12.6). In addition, all of the security considerations specified in <cite>RFC 3023</cite> apply to the "application/jabber+xml" media type.</p>
<p>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.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires registration of the "application/jabber+xml" content type with &IANA;. The registration is as follows:</p>
<code><![CDATA[
To: ietf-types@iana.org
Subject: Registration of MIME media type application/jabber+xml
MIME media type name: application
MIME subtype name: jabber+xml
Required parameters: (none)
Optional parameters: (charset) Same as charset parameter of
application/xml as specified in RFC 3023; per Section 11.5
of RFC 3920, the charset must be UTF-8.
Encoding considerations: Same as encoding considerations of
application/xml as specified in RFC 3023; per Section 11.5
of RFC 3920, the encoding must be UTF-8.
Security considerations: All of the security considerations
specified in RFC 3023 and RFC 3920 apply to this XML media
type. Refer to Section 11 of JSF JEP-0081.
Interoperability considerations: (none)
Specification: JSF JEP-0081
Applications which use this media type: non-XMPP applications
(e.g., web browsers or email clients) that wish to invoke
XMPP-compliant applications for instant messaging and
presence functionality.
Additional information: This media type is not to be confused
with the "application/xmpp+xml" media type, which is for
use by native XMPP applications.
Person and email address to contact for further information:
Jabber Registrar, <registrar@jabber.org>
Intended usage: COMMON
Author/Change controller: JSF, Jabber Registrar
]]></code>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; shall include 'http://jabber.org/protocol/mimetype' in its registry of protocol namespaces.</p>
</section2>
<section2 topic='IANA Interaction' anchor='registrar-iana'>
<p>The Jabber Registrar shall interact with the IANA in order to register the media type defined herein.</p>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/mimetype'
xmlns='http://jabber.org/protocol/mimetype'
elementFormDefault='qualified'>
<xs:element name='jabber'>
<xs:complexType>
<xs:choice>
<xs:element name='chat' type='JabberAction'/>
<xs:element name='groupchat' type='JabberAction'/>
<xs:element name='message' type='JabberAction'/>
<xs:element name='register' type='JabberAction'/>
<xs:element name='subscribe' type='JabberAction'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:complexType name='JabberAction'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
<xs:attribute name='jid' use='required'>
</xs:complexType>
</xs:schema>
]]></code>
</section1>
<section1 topic='Open Issues'>
<ol>
<li>Add implementation notes for server MIME type registration and HTTP Content-Type output.</li>
<li>Add implementation notes for client handling on various platforms (e.g., DDE messages in Windows).</li>
</ol>
</section1>
</jep>

150
xep-0082.xml Normal file
View File

@ -0,0 +1,150 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Jabber Date and Time Profiles</title>
<abstract>This JEP specifies a standardization of ISO 8601 profiles and their lexical representation for use in Jabber/XMPP protocol extensions.</abstract>
&LEGALNOTICE;
<number>0082</number>
<status>Active</status>
<type>Informational</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>ISO 8601</spec>
<spec>XML Schema Part 2</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>N/A</shortname>
&stpeter;
<revision>
<version>1.0</version>
<date>2003-05-28</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Active.</remark>
</revision>
<revision>
<version>0.6</version>
<date>2003-05-22</date>
<initials>psa</initials>
<remark>Added examples; added section on migration.</remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-05-19</date>
<initials>psa</initials>
<remark>Adjusted wording regarding several XML Schema references; added implementation notes.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-05-16</date>
<initials>psa</initials>
<remark>Updated to refer to XML Schema datatypes; removed "Precise Datetime" profile; added "Time" profile for recurring events.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-05-08</date>
<initials>psa</initials>
<remark>Clarified registration format, deleted references to undocumented protocols, removed implementation notes.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-04-28</date>
<initials>psa</initials>
<remark>Added "Precise Datetime" profile.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-04-21</date>
<initials>psa</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>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" <note>The concept of an ISO 8601 profile is used in both RFC 3339 (<link url='http://www.ietf.org/rfc/rfc3339.txt'>http://www.ietf.org/rfc/rfc3339.txt</link>) and a W3C Note (<link url='http://www.w3.org/TR/NOTE-datetime'>http://www.w3.org/TR/NOTE-datetime</link>).</note> as well as their lexical representation. While that flexibility can lead to confusion, it is also true that the Jabber community has tended to use only a few restricted profiles of ISO 8601 dates and times (albeit with inconsistent lexical representations). This JEP formalizes those profiles and their lexical representation through reference to the datatypes defined in &w3xmlschema2;.</p>
</section1>
<section1 topic="Terminology">
<section2 topic='Time Terms'>
<p>The following acronyms and characters are used herein to represent time-related concepts:</p>
<table caption='Acronyms and Characters'>
<tr><th>Term</th><th>Definition</th></tr>
<tr><td>CCYY</td><td>four-digit year portion of Date</td></tr>
<tr><td>MM</td><td>two-digit month portion of Date</td></tr>
<tr><td>DD</td><td>two-digit day portion of Date</td></tr>
<tr><td>-</td><td>ISO 8601 separator among Date portions</td></tr>
<tr><td>T</td><td>ISO 8601 separator between Date and Time</td></tr>
<tr><td>hh</td><td>two-digit hour portion of Time (00 through 23)</td></tr>
<tr><td>mm</td><td>two-digit minutes portion of Time (00 through 59)</td></tr>
<tr><td>ss</td><td>two-digit seconds portion of Time (00 through 59)</td></tr>
<tr><td>:</td><td>ISO 8601 separator among Time portions</td></tr>
<tr><td>.</td><td>ISO 8601 separator between seconds and milliseconds</td></tr>
<tr><td>sss</td><td>fractional second addendum to Time (MAY contain any number of digits)</td></tr>
<tr><td>TZD</td><td>Time Zone Definition (either "Z" for UTC or "[+|-]hh:mm" for a specific time zone)</td></tr>
</table>
</section2>
</section1>
<section1 topic='Profiles'>
<p>Three profiles are defined herein.</p>
<section2 topic='Date'>
<p>The Date profile defines a date without including the time of day. The lexical representation is as follows:</p>
<code>
CCYY-MM-DD
</code>
<p>This profile is equivalent to the 'date' datatype defined in XML Schema <note>The 'date' datatype is defined at &lt;<link url='http://www.w3.org/TR/xmlschema-2/#date'>http://www.w3.org/TR/xmlschema-2/#date</link>&gt;.</note>. When an XML schema is used to define a Jabber protocol that uses this profile, the datatype MUST be an XML Schema 'date'. If there are differences between the description in this JEP and those in XML Schema, the latter overrule.</p>
<example caption='The date of American independence'>
1776-07-04
</example>
</section2>
<section2 topic='DateTime'>
<p>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:</p>
<code>
CCYY-MM-DDThh:mm:ss[.sss]TZD
</code>
<p>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).</p>
<p>This profile is equivalent to the 'dateTime' datatype defined in XML Schema <note>The 'dateTime' datatype is defined at &lt;<link url='http://www.w3.org/TR/xmlschema-2/#dateTime'>http://www.w3.org/TR/xmlschema-2/#dateTime</link>&gt;.</note>. When an XML schema is used to define a Jabber protocol that uses this profile, the datatype MUST be an XML Schema 'dateTime'. If there are differences between the description in this JEP and those in XML Schema, the latter overrule.</p>
<example caption='Datetime of the first human steps on the Moon (UTC)'>
1969-07-21T02:56:15Z
</example>
<example caption='Datetime of the first human steps on the Moon (Houston time)'>
1969-07-20T21:56:15-05:00
</example>
</section2>
<section2 topic='Time'>
<p>The Time profile is used to specify an instant of time that recurs (e.g., every day). The lexical representation is as follows:</p>
<code>
hh:mm:ss[.sss][TZD]
</code>
<p>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).</p>
<p>This profile is equivalent to the 'time' datatype defined in XML Schema <note>The 'time' datatype is defined at &lt;<link url='http://www.w3.org/TR/xmlschema-2/#time'>http://www.w3.org/TR/xmlschema-2/#time</link>&gt;.</note>. When an XML schema is used to define a Jabber protocol that uses this profile, the datatype MUST be an XML Schema 'time'. If there are differences between the description in this JEP and those in XML Schema, the latter overrule.</p>
<example caption='Time for tea'>
16:00:00
</example>
</section2>
</section1>
<section1 topic='Migration'>
<p>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:</p>
<code>
CCYYMMDDThh:mm:ss
</code>
<p>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.</p>
<p>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.</p>
<p>New protocols approved by the Jabber Software Foundation MUST use the lexical representations defined in this JEP.</p>
</section1>
<section1 topic='Implementation Notes'>
<p>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.</p>
</section1>
<section1 topic='Security Considerations'>
<p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
<p>This JEP requires no interaction with the &REGISTRAR;.</p>
</section1>
</jep>

154
xep-0083.xml Normal file
View File

@ -0,0 +1,154 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM "../jep.ent">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Nested Roster Groups</title>
<abstract>This JEP defines a protocol extension that enables nested sub-groups to exist within the Jabber roster, while retaining backwards compatibility and ensuring that the roster remains usable by all clients.</abstract>
&LEGALNOTICE;
<number>0083</number>
<status>Active</status>
<type>Informational</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>JEP-0049</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>nestedgroups</shortname>
<schemaloc>
<url>http://jabber.org/protocol/nestedgroups/delimiter.xsd</url>
</schemaloc>
<author>
<firstname>Rachel</firstname>
<surname>Blackman</surname>
<email>rcb@ceruleanstudios.com</email>
<jid>sparks@jabber.org</jid>
</author>
<revision>
<version>1.0</version>
<date>2004-10-11</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced to a status of Active.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-05-05</date>
<initials>rcb</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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.</p>
</section1>
<section1 topic='roster:delimiter Namespace' anchor='namespace'>
<p>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. <note>If the element does not contain XML character data, a compliant client SHOULD assume that nested groups are disabled for the user's account.</note></p>
<p>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.</p>
<p>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.</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<p>Use cases for this extension are straightforward, and are shown below as examples.</p>
<section2 topic='Querying for the delimiter' anchor='usecases-query'>
<p>All compliant clients SHOULD query for an existing delimiter at login.</p>
<example caption='Querying for the Delimiter'><![CDATA[
CLIENT:
<iq type='get'
id='1'>
<query xmlns='jabber:iq:private'>
<roster xmlns='roster:delimiter'/>
</query>
</iq>
SERVER:
<iq type='result'
id='1'
from='bill@shakespeare.lit/Globe'
to='bill@shakespeare.lit/Globe'>
<query xmlns='jabber:iq:private'>
<roster xmlns='roster:delimiter'>::</roster>
</query>
</iq>
]]></example>
</section2>
<section2 topic='Retrieving the Roster' anchor='usecases-retrieve'>
<p>Now that the client has a delimiter, we can retrieve and parse the roster properly.</p>
<example caption='Retrieving a Roster with Nested Groups'><![CDATA[
CLIENT:
<iq type='get'
id='2'>
<query xmlns='jabber:iq:roster'/>
</iq>
SERVER:
<iq type='result'
to='bill@shakespeare.lit/Globe'
id='2'>
<query xmlns='jabber:iq:roster'>
<item jid='bottom@athens.gr' subscription='both'>
<group>Midsummer::Actors</group>
</item>
<item jid='quince@athens.gr' subscription='both'>
<group>Midsummer::Actors</group>
</item>
<item jid='snug@athens.gr' subscription='both'>
<group>Midsummer::Actors</group>
</item>
<item jid='theseus@athens.gr' subscription='both'>
<group>Midsummer::Royalty</group>
</item>
<item jid='hippolyta@athens.gr' subscription='both'>
<group>Midsummer::Royalty</group>
</item>
<item jid='robin@faeries.underhill.org' subscription='both'>
<group>Midsummer</group>
</item>
<item jid='hamlet@denmark.net' subscription='both'>
<group>Hamlet</group>
</item>
<item jid='gertrude@denmark.net' subscription='both'>
<group>Hamlet</group>
</item>
</query>
</iq>
]]></example>
<p>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.</p>
<p>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.</p>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>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.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; includes 'roster:delimiter' in its registry of protocol namespaces.</p>
</section2>
</section1>
<section1 topic='Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='roster:delimiter'
xmlns='roster:delimiter'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0083: http://www.jabber.org/jeps/jep-0083.html
</xs:documentation>
</xs:annotation>
<xs:element name='roster' type='xs:string'/>
]]></code>
</section1>
</jep>

561
xep-0084.xml Normal file
View File

@ -0,0 +1,561 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>User Avatar</title>
<abstract>This document defines an XMPP protocol extension for exchanging user avatars.</abstract>
&LEGALNOTICE;
<number>0084</number>
<status>Experimental</status>
<type>Standards Track</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>JEP-0030</spec>
<spec>JEP-0060</spec>
<spec>JEP-0163</spec>
</dependencies>
<supersedes>
<spec>JEP-0008</spec>
</supersedes>
<supersededby/>
<shortname>avatar</shortname>
&stpeter;
&pgmillard;
&temas;
&xvirge;
<revision>
<version>0.8</version>
<date>2006-06-19</date>
<initials>psa</initials>
<remark><p>Updated to reflect pubsub and PEP changes; added implementation notes about multiple resources and avatar synchronization.</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2006-01-17</date>
<initials>psa</initials>
<remark><p>Updated to use PEP.</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2005-04-13</date>
<initials>psa</initials>
<remark><p>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.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2005-03-28</date>
<initials>psa/pgm</initials>
<remark><p>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.</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-05-20</date>
<initials>tjm</initials>
<remark><p>Lessen the image requirements. Include the content type in info.</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-05-08</date>
<initials>tjm</initials>
<remark><p>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.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-05-07</date>
<initials>tjm</initials>
<remark><p>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.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-05-07</date>
<initials>tjm</initials>
<remark><p>Initial version.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>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;.</p>
<p>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.)</p>
<p>This protocol also allows storage of avatar data at a URL accessible via HTTP (see &rfc2616;). <note>By "accessible via HTTP" is meant that the data is available at an http: or https: URI.</note> This can be helpful as a fallback mechanism if a pubsub-aware data repository is not available. It also makes it possible for avatar images to be hosted on public websites (e.g., an end-user-oriented community site) and retrieved from that site rather than handled directly by the publishing client in any fashion.</p>
<p>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).</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>This document addresses the following use cases for avatar publishers:</p>
<ol>
<li>Publishing avatar data</li>
<li>Updating metadata about the current avatar</li>
<li>Disabling avatars</li>
</ol>
<p>This document addresses the following use cases for avatar subscribers:</p>
<ol>
<li>Discovering avatar availability</li>
<li>Receiving notification of avatar changes</li>
<li>Retrieving avatar data via pubsub</li>
<li>Retrieving avatar data via HTTP</li>
</ol>
</section1>
<section1 topic='Basic Process Flow' anchor='process'>
<p>The process for publishing and updating user avatars is as follows:</p>
<ol>
<li>User creates metadata node</li>
<li>User creates data node for "image/png" content-type</li>
<li>User publishes avatar data for "image/png" content-type to data node and optionally publishes other content-types to HTTP URLs</li>
<li>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)</li>
<li>Subscribers receive notification</li>
<li>Optionally (and if necessary), subscribers retrieve avatar data identified by ItemID from data node using pubsub get-items feature (or via HTTP)</li>
<li>Optionally, user disables avatar display.</li>
</ol>
<p>This process flow is described more fully in the following sections.</p>
<p>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 <cite>JEP-0163</cite>.</p>
<section2 topic='User Creates Metadata Node' anchor='process-createmeta'>
<p>In order to publish notifications related to its avatar, the user MUST first create a node for his or her avatar metadata:</p>
<example caption='Pubsub metadata node creation request'><![CDATA[
<iq type='set' from='juliet@capulet.com/chamber' id='create1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<create node='http://jabber.org/protocol/avatar#metadata'/>
<configure>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#node_config</value>
</field>
<field var='pubsub#access_model'>
<option><value>presence</value></option>
</field>
</x>
</configure>
</pubsub>
</iq>
]]></example>
<p>The NodeID MUST be "http://jabber.org/protocol/avatar#metadata" and the access model SHOULD be "presence". Note: If the default access model (see <cite>JEP-0163</cite>) is the same as the desired access model, the user can send an empty &lt;configure/&gt; element rather than including a data form as shown above.</p>
<example caption='Pubsub service replies with success'><![CDATA[
<iq type='result' to='juliet@capulet.com/chamber' id='create1'/>
]]></example>
</section2>
<section2 topic='User Creates Data Node' anchor='process-createdata'>
<p>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):</p>
<example caption='Pubsub data node creation request'><![CDATA[
<iq type='set' from='juliet@capulet.com/chamber' id='create2'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<create node='http://jabber.org/protocol/avatar#data'/>
<configure/>
</pubsub>
</iq>
]]></example>
<p>If the user creates a data note, the NodeID MUST be "http://jabber.org/protocol/avatar#data" and the access model SHOULD be "presence".</p>
<example caption='Pubsub service replies with success'><![CDATA[
<iq type='result' to='juliet@capulet.com/chamber' id='create2'/>
]]></example>
</section2>
<section2 topic='User Publishes Data' anchor='process-pubdata'>
<p>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).</p>
<p>The following example illustrates the XML structure to be sent when publishing avatar data to the data node.</p>
<example caption='Publishing avatar data to data node'><![CDATA[
<iq type='set' from='juliet@capulet.com/chamber' id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='http://jabber.org/protocol/avatar#data'>
<item id='111f4b3c50d7b0df729d299bc6f8e9ef9066971f'>
<data xmlns='http://jabber.org/protocol/avatar#data'>
qANQR1DBwU4DX7jmYZnncm...
</data>
</item>
</publish>
</pubsub>
</iq>
]]></example>
<example caption='Pubsub service replies with success'><![CDATA[
<iq type='result' to='juliet@capulet.com/chamber' id='publish1'/>
]]></example>
</section2>
<section2 topic='User Publishes Metadata Notification' anchor='process-pubmeta'>
<p>Whenever the publisher wishes to change its current avatar, it MUST update the metadata node.</p>
<p>The following example shows metadata specifying avatar data that is available in only one format ("image/png") and accessible only at the data node:</p>
<example caption='Publishing avatar metadata'><![CDATA[
<iq type='set' from='juliet@capulet.com/chamber' id='publish2'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='http://jabber.org/protocol/avatar#metadata'>
<item id='111f4b3c50d7b0df729d299bc6f8e9ef9066971f'>
<metadata xmlns='http://jabber.org/protocol/avatar#metadata'>
<info id='111f4b3c50d7b0df729d299bc6f8e9ef9066971f'
type='image/png'
bytes='12345'
height='64'
width='64'/>
</metadata>
</item>
</publish>
</pubsub>
</iq>
]]></example>
</section2>
<section2 topic='Subscribers Receive Metadata Notification' anchor='process-subnotify'>
<p>Subscribers to the metadata node would then receive the notification:</p>
<example caption='Subscribers receive avatar metadata notification'><![CDATA[
<message to='romeo@montague.net' from='juliet@capulet.com'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='http://jabber.org/protocol/avatar#metadata'>
<item id='111f4b3c50d7b0df729d299bc6f8e9ef9066971f'>
<metadata xmlns='http://jabber.org/protocol/avatar#metadata'>
<info id='111f4b3c50d7b0df729d299bc6f8e9ef9066971f'
type='image/png'
bytes='12345'
height='64'
width='64'/>
</metadata>
</item>
</items>
</event>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='replyto' jid='juliet@capulet.com/chamber'/>
</addresses>
</message>
]]></example>
<p>Note the inclusion of &jep0033; information about the publishing resource (see <cite>JEP-0163</cite> and <cite>JEP-0060</cite> for details).</p>
</section2>
<section2 topic='Subscribers Retrieve Data' anchor='process-subretrieve'>
<p>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.</p>
<p>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:</p>
<example caption='Subscriber requests last item by ItemID'><![CDATA[
<iq type='get'
from='romeo@montague.net/home'
to='juliet@capulet.com'
id='retrieve1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='http://jabber.org/protocol/avatar#data'>
<item id='111f4b3c50d7b0df729d299bc6f8e9ef9066971f'>
</items>
</pubsub>
</iq>
]]></example>
<p>The PEP service running at the user's server then SHOULD return the avatar data:</p>
<example caption='Publishing avatar data to data node'><![CDATA[
<iq type='result' from='juliet@capulet.com' to='romeo@montague.net/home' id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='http://jabber.org/protocol/avatar#data'>
<item id='111f4b3c50d7b0df729d299bc6f8e9ef9066971f'>
<data xmlns='http://jabber.org/protocol/avatar#data'>
qANQR1DBwU4DX7jmYZnncm...
</data>
</item>
</publish>
</pubsub>
</iq>
]]></example>
<p>If the &lt;info/&gt; 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.</p>
</section2>
<section2 topic='Publisher Disables Avatars' anchor='pub-stop'>
<p>In order to temporarily disable any avatar, the user publishes an empty &lt;stop/&gt; element to the metadata node (this item SHOULD NOT possess an ItemID):</p>
<example caption='Temporarily disabling an avatar'><![CDATA[
<iq type='set' from='juliet@capulet.com/chamber' id='publish3'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='avatar/info/juliet@capulet.com'>
<item>
<metadata xmlns='http://jabber.org/protocol/avatar#metadata'>
<stop/>
</metadata>
</item>
</publish>
</pubsub>
</iq>
]]></example>
<p>As before, subscribers to the metadata node would then receive the notification:</p>
<example caption='Subscribers receive avatar metadata notification'><![CDATA[
<message to='romeo@montague.net' from='juliet@capulet.com'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='http://jabber.org/protocol/avatar#metadata'>
<item>
<metadata xmlns='http://jabber.org/protocol/avatar#metadata'>
<stop/>
</metadata>
</item>
</items>
</event>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='replyto' jid='juliet@capulet.com/chamber'/>
</addresses>
</message>
]]></example>
</section2>
</section1>
<section1 topic='Protocol Syntax' anchor='proto'>
<p>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:</p>
<ul>
<li>&lt;data xmlns='http://jabber.org/protocol/avatar#data'/&gt;</li>
<li>&lt;metadata xmlns='http://jabber.org/protocol/avatar#metadata'/&gt;</li>
</ul>
<p>These are further specified below.</p>
<section2 topic='Data Element' anchor='proto-data'>
<p>The &lt;data/&gt; element is used to communicate the avatar data itself, and only for the "image/png" content-type (support for which is REQUIRED):</p>
<code><![CDATA[
<data xmlns='http://jabber.org/protocol/avatar#data'>
IMAGE DATA
</data>
]]></code>
<p>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.)</p>
<p>Support for the &lt;data/&gt; element is REQUIRED.</p>
</section2>
<section2 topic='Metadata Element' anchor='proto-meta'>
<p>The &lt;metadata/&gt; element is used to communicate information about the avatar. There are three allowable children of the &lt;metadata/&gt; element:</p>
<ul>
<li>&lt;info/&gt;</li>
<li>&lt;pointer/&gt;</li>
<li>&lt;stop/&gt;</li>
</ul>
<p>These are further specified below.</p>
<section3 topic='Info Element' anchor='proto-info'>
<p>The &lt;info/&gt; child element is used to communicate avatar metadata:</p>
<code><![CDATA[
<metadata xmlns='http://jabber.org/protocol/avatar#metadata'
<info id='SHA1-hash-of-image-data'
url='HTTP-URL-for-image-data'
id='SHA1-hash-of-image-data'
type='content-type-of-image-data'
bytes='size-of-image-data-in-bytes'
height='image-height-in-pixels'
width='image-width-in-pixels'/>
</metadata>
]]></code>
<p>The &lt;info/&gt; child element MUST be empty.</p>
<p>The &lt;info/&gt; child element MUST possess the following attributes:</p>
<ul>
<li><em>bytes</em> -- The size of the image data in bytes.</li>
<li><em>height</em> -- The height of the image in pixels.</li>
<li><em>id</em> -- The SHA1 hash of the image data for the specified content-type.</li>
<li><em>type</em> -- The IANA-registered content type of the image data.</li>
<li><em>width</em> -- The width of the image in pixels.</li>
</ul>
<p>The &lt;info/&gt; element MAY possess the following attribute:</p>
<ul>
<li><em>url</em> -- An http: or https: URI at which the image data file may be found.</li>
</ul>
<p>If the &lt;info/&gt; 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.</p>
<p>The &lt;metadata/&gt; root element MAY contain more than one &lt;info/&gt; element. Each &lt;info/&gt; 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". <note>The IANA registry of content types is located at &lt;<link url='http://www.iana.org/assignments/media-types/'>http://www.iana.org/assignments/media-types/</link>&gt;.</note> Support for the "image/png" content type is REQUIRED. Support for the "image/gif" and "image/jpeg" content types is RECOMMENDED. Support for any other content type is OPTIONAL.</p>
<p>The value of the 'id' attribute MUST be the SHA1 (&rfc3174;) hash of the image data for the specified content-type.</p>
<p>Support for the &lt;info/&gt; element is REQUIRED.</p>
</section3>
<section3 topic='Pointer Element' anchor='proto-pointer'>
<p>The &lt;pointer/&gt; 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:</p>
<code><![CDATA[
<avatar xmlns='http://jabber.org/protocol/avatar'>
<pointer>
... APPLICATION-SPECIFIC DATA ...
</pointer>
</avatar>
]]></code>
<p>The &lt;pointer/&gt; element MAY possess the following attributes if the publishing application has the relevant information:</p>
<ul>
<li><em>bytes</em> -- The size of the image data in bytes.</li>
<li><em>height</em> -- The height of the image in pixels.</li>
<li><em>id</em> -- The SHA1 hash of the image data for the specified content-type.</li>
<li><em>type</em> -- The IANA-registered content type of the image data.</li>
<li><em>width</em> -- The width of the image in pixels.</li>
</ul>
<p>The content of the &lt;pointer/&gt; 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.</p>
<p>Even if the &lt;pointer&gt; element is included, it MUST be preceded by at least one instance of the &lt;info/&gt; element so that implementations that do not support the &lt;pointer/&gt; element can display a "fallback" format of the avatar (at a minimum, "image/png").</p>
<p>Support for the &lt;pointer/&gt; element is OPTIONAL.</p>
</section3>
<section3 topic='Stop Element' anchor='proto-stop'>
<p>The &lt;stop/&gt; child element is used to signal that avatar publishing has been disabled:</p>
<code><![CDATA[
<metadata xmlns='http://jabber.org/protocol/avatar#metadata'>
<stop/>
</metadata>
]]></code>
<p>The &lt;stop/&gt; element MUST be empty and MUST NOT possess any attributes.</p>
<p>Support for the &lt;stop/&gt; element is REQUIRED.</p>
</section3>
</section2>
</section1>
<section1 topic='Additional Examples' anchor='examples'>
<section2 topic='Metadata With Multiple Content-Types' anchor='examples-multiple'>
<p>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:</p>
<example caption='Publishing avatar metadata (multiple formats)'><![CDATA[
<iq type='set' from='juliet@capulet.com/chamber' id='publish3'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='http://jabber.org/protocol/avatar#metadata'>
<item id='111f4b3c50d7b0df729d299bc6f8e9ef9066971f'>
<metadata xmlns='http://jabber.org/protocol/avatar#metadata'>
<info id='111f4b3c50d7b0df729d299bc6f8e9ef9066971f'
type='image/png'
bytes='12345'
height='64'
width='64'/>
<info id='222f4b3c50d7b0df729d299bc6f8e9ef9066971f'
url='http://avatars.jabberstudio.org/happy.gif'
type='image/gif'
bytes='23456'
height='64'
width='64'/>
<info id='333f4b3c50d7b0df729d299bc6f8e9ef9066971f'
url='http://avatars.jabberstudio.org/happy.mng'
type='image/mng'
bytes='78912'
height='64'
width='64'/>
</metadata>
</item>
</publish>
</pubsub>
</iq>
]]></example>
</section2>
<section2 topic='Metadata With Pointer' anchor='examples-pointer'>
<p>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.</p>
<example caption='Publishing avatar metadata (with pointer)'><![CDATA[
<iq type='set' from='juliet@capulet.com/chamber' id='publish4'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='http://jabber.org/protocol/avatar#metadata'>
<item id='111f4b3c50d7b0df729d299bc6f8e9ef9066971f'>
<metadata xmlns='http://jabber.org/protocol/avatar#metadata'>
<info id='111f4b3c50d7b0df729d299bc6f8e9ef9066971f'
type='image/png'
bytes='12345'
height='64'
width='64'/>
<pointer>
<x xmlns='http://example.com/virtualworlds'>
<game>Ancapistan</game>
<character>Kropotkin</character>
</x>
</pointer>
</metadata>
</item>
</publish>
</pubsub>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Service Discovery' anchor='disco'>
<section2 topic='Discovering Avatar Availability' anchor='disco-sub'>
<p>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;):</p>
<example caption='Disco items request'><![CDATA[
<iq type='get'
from='romeo@montague.net/orchard'
to='juliet@capulet.com'
id='items1'>
<query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
]]></example>
<p>If the user publishes avatar data to an PEP node, the result MUST contain the appropriate items:</p>
<example caption='Disco items result'><![CDATA[
<iq type='result'
from='juliet@capulet.com'
to='romeo@montague.net/orchard'
id='items1'>
<query xmlns='http://jabber.org/protocol/disco#items'>
<item jid='juliet@capulet.com' node='http://jabber.org/protocol/avatar#data'/>
<item jid='juliet@capulet.com' node='http://jabber.org/protocol/avatar#metadata'/>
</query>
</iq>
]]></example>
<p>The contact then MAY subscribe to the metadata node following the protocol specified in <cite>JEP-0060</cite>. However, the contact SHOULD NOT subscribe to the data node (instead, it SHOULD simply retrieve items from that node when needed, as described above).</p>
</section2>
</section1>
<section1 topic='Business Rules' anchor='bizrules'>
<section2 topic='Image Requirements' anchor='bizrules-images'>
<p>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.</p>
</section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<section2 topic='Multiple Resources' anchor='impl-resources'>
<p>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.</p>
</section2>
<section2 topic='Avatar Synchronization' anchor='impl-sync'>
<p>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 <cite>JEP-0060</cite>.</p>
</section2>
<section2 topic='Image Handling' anchor='impl-images'>
<p>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).</p>
<p>The receiving application SHOULD NOT scale up an image when displaying it.</p>
<p>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.</p>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document makes use of IANA-registered content types, but requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; shall include 'http://jabber.org/protocol/avatar#data' and 'http://jabber.org/protocol/avatar#metadata' in its registry of protocol namespaces.</p>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<section2 topic='Data Namespace' anchor='schema-data'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/avatar#metadata'
xmlns='http://jabber.org/protocol/avatar#metadata'
elementFormDefault='qualified'>
<xs:element name='data' type='xs:base64Binary'>
</xs:schema>
]]></code>
</section2>
<section2 topic='Metadata Namespace' anchor='schema-metadata'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/avatar#metadata'
xmlns='http://jabber.org/protocol/avatar#metadata'
elementFormDefault='qualified'>
<xs:element name='metadata'>
<xs:complexType>
<xs:choice>
<xs:sequence>
<xs:element ref='info' maxOccurs='unbounded'/>
<xs:element ref='pointer' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
<xs:element name='stop' type='empty'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name='info'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='bytes' type='xs:string' use='required'/>
<xs:attribute name='type' type='xs:string' use='required'/>
<xs:attribute name='height' type='xs:string' use='required'/>
<xs:attribute name='id' type='xs:string' use='required'/>
<xs:attribute name='url' type='xs:string' use='optional'/>
<xs:attribute name='width' type='xs:string' use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='pointer'>
<xs:complexType>
<xs:sequence>
<xs:any namespace='##other'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section2>
</section1>
<section1 topic='Author Note' anchor='authornote'>
<p>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.</p>
</section1>
</jep>

Some files were not shown because too many files have changed in this diff Show More