moparisthebest
/
xeps
mirror of https://github.com/moparisthebest/xeps
1
0
Fork 0
Code Issues Releases Wiki Activity

initial version 

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1746 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2008-03-05 22:06:46 +00:00
parent 3047a389a8
commit 5d6f916f99
4 changed files with 1056 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

359
xep-0234.xml Normal file
View File

@ -0,0 +1,359 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Jingle File Transfer</title>
<abstract>This specification defines a Jingle application type for transferring files between two entities. The protocol provides a modular framework that enables the exchange of information about the file to be transferred as well as the negotiation of parameters such as the transport to be used.</abstract>
&LEGALNOTICE;
<number>0234</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0096</spec>
<spec>XEP-0166</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT YET ASSIGNED</shortname>
&stpeter;
<revision>
<version>0.1</version>
<date>2008-03-05</date>
<initials>psa</initials>
<remark><p>Initial published version.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2008-02-29</date>
<initials>psa</initials>
<remark><p>Corrected use of content-replace action; specified that the In-Band Bytestreams transport method is mandatory-to-implement but must have the lowest preference order.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2008-02-28</date>
<initials>psa</initials>
<remark>Modified negotiation flow to use new content-replace action.</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2008-01-29</date>
<initials>psa</initials>
<remark>First draft.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>&xep0096; defines the current XMPP protocol extension for file transfer. However, that protocol has several drawbacks, most related to the &xep0095; protocol on which it depends:</p>
<ol>
<li>It does not enable a true, bidirectional negotiation; instead, the initiator sets the terms for the file transfer and the receiver either accepts the terms or cancels the negotiation.</li>
<li>It is the only technology in the Jabber/XMPP protocol "stack" that uses <cite>XEP-095: Stream Initiation</cite>. More modern technologies such as voice and video session negotiation use &xep0166;, and it would be helpful if implementors could use the same code for all negotiation use cases.</li>
</ol>
<p>To overcome these drawbacks, this specification defines a file transfer negotiation method that meets the following requirements:</p>
<ul>
<li>Reuse the session negotiation semantics from <cite>XEP-0166</cite>.</li>
<li>Reuse the file description format from <cite>XEP-0096</cite>.</li>
<li>Define a clear upgrade path from <cite>XEP-0096</cite> to this specification.</li>
</ul>
</section1>
<section1 topic='How It Works' anchor='protocol'>
<p>This section provides a friendly introduction to Jingle file transfer.</p>
<p>First, the party that wishes to initiate the file transfer determines the receiver's capabilities (via &xep0030; or &xep0115;). In this example, we assume that the receiver supports the following service discovery features (note: these features may not reflect final namespace assignments):</p>
<ul>
<li>urn:xmpp:tmp:jingle</li>
<li>urn:xmpp:tmp:jingle:apps:file-transfer</li>
<li>urn:xmpp:tmp:jingle:transports:bytestreams</li>
<li>urn:xmpp:tmp:jingle:transports:ibb</li>
</ul>
<p>The initiator then sends a Jingle session-initiation request to a potential receiver. The content-type of the request specifies two things:</p>
<ol>
<li>An application type of "urn:xmpp:tmp:jingle:apps:file-transfer" &NSNOTE;. In particular, the &lt;description/&gt; element contains an &lt;offer/&gt; or &lt;request/&gt; element that in turn contains a &lt;file/&gt; element qualified by the existing 'http://jabber.org/protocol/si/profile/file-transfer' namespace from <cite>XEP-0096</cite>.</li>
<li>An appropriate transport method. Because the existing transport methods used in <cite>XEP-0096</cite> (i.e., &xep0065; and &xep0047;) are not yet defined as Jingle transport methods, this specification registers those definitions.</li>
</ol>
<p>In this example, the initiation request specifies a file offer and a transport method of bytestreams (i.e., XEP-065).</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
id='jingle1'
to='laertes@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-initiate'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
</content>
</jingle>
</iq>
]]></example>
<p>The responder immediately acknowledges receipt of the session-initiate.</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='jingle1'
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>The parties would then attempt to negotiate use of the SOCKS5 Bytestreams transport method, as described in <cite>XEP-0065</cite>.</p>
<p>More detailed scenarios follow.</p>
</section1>
<section1 topic='Scenarios' anchor='scenarios'>
<section2 topic='Fallback' anchor='fallback'>
<p>Currently, <cite>XEP-0096</cite> does not enable the parties to fall back to a second method (e.g., In-Band Bytestreams) if the first method tried (e.g., SOCKS5 Bytestreams) does not work. This problem is addressed by Jingle. Consider the following protocol flow.</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
id='jingle1'
to='laertes@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-initiate'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
</content>
</jingle>
</iq>
]]></example>
<p>The responder immediately acknowledges receipt of the session-initiate.</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='jingle1'
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>The receiver would then send a session-accept.</p>
<example caption="Receiver sends session-accept"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='accept1'
to='kingclaudius@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-accept'
initiator='kingclaudius@shakespeare.lit/castle'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:ibb'/>
</content>
</jingle>
</iq>
]]></example>
<p>The initiator acknowledges the session-accept action.</p>
<example caption="Responder acknowledges session-accept"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='accept1'
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>Now the parties attempt to negotiate use of SOCKS5 Bytestreams as defined in <cite>XEP-0065</cite>.</p>
<p>However, let us imagine that the SOCKS5 Bytestreams negotiation fails. The initiator or responder can then suggest the use of In-Band Bytestreams by sending a content-replace action. Here we assume that the responder sends a content-replace action including a request for the file originally offered and a transport of IBB.</p>
<example caption="Responder requests content-replace"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='replace1'
to='kingclaudius@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='content-replace'
initiator='kingclaudius@shakespeare.lit/castle'
sid='a73sjjvkla37jfea'>
<content creator='responder' name='a-file-request'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<request>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
hash='552da749930852c69ae5d2141d3766b1'
name='test.txt'/>
</file>
</request>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:ibb'/>
</content>
</jingle>
</iq>
]]></example>
<p>The initiator then acknowledges the content-replace action.</p>
<example caption="Initiator acknowledges content-replace"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
id='replace1'
to='laertes@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>If the content definition is acceptable, the initiator then sends a content-accept action to the responder.</p>
<example caption="Initiator sends content-accept"><![CDATA[
<iq to='kingclaudius@shakespeare.lit/castle'
id='accept2'
to='laertes@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='content-accept'
initiator='kingclaudius@shakespeare.lit/castle'
sid='a73sjjvkla37jfea'>
<content creator='responder' name='a-file-request'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<request>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
hash='552da749930852c69ae5d2141d3766b1'
name='test.txt'/>
</file>
</request>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:ibb'/>
</content>
</jingle>
</iq>
]]></example>
<p>The responder then acknowledges the content-accept action.</p>
<example caption="Responder acknowledges content-accept"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='accept2'
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>The parties then attempt to use In-Band Bytestreams.</p>
</section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<section2 topic='Mandatory to Implement Technologies' anchor='impl-mti'>
<p>All implementations MUST support the In-Band Bytestreams transport method.</p>
</section2>
<section2 topic='Preference Order of Transport Methods' anchor='impl-pref'>
<p>An application MAY present transport methods in any order, except that the In-Band Bytestreams method MUST be the lowest preference.</p>
</section2>
<section2 topic='Migration from XEP-0096' anchor='impl-migration'>
<p>Support for Jingle file transfer can be determined through discovery of the 'urn:xmpp:tmp:jingle:apps:file-transfer' namespace &NSNOTE;, via either service discovery or entity capabilities. If the initiator knows that the receiver supports Jingle file transfer, it SHOULD attempt negotiation using XEP-0166 rather than XEP-0095.</p>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>In order to secure the data stream, implementations SHOULD use encryption methods appropriate to the transport method being used. For details, refer to the specifications for those transport methods.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>No interaction with &IANA; is required as a result of this document.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='ns'>
<p>Until this specification advances to a status of Draft, its associated namespaces shall be:</p>
<ul>
<li>urn:xmpp:tmp:jingle:apps:file-transfer</li>
</ul>
<p>Upon advancement of this specification, the &REGISTRAR; shall issue permanent namespaces in accordance with the process defined in Section 4 of &xep0053;.</p>
<p>The following namespaces are requested, and are thought to be unique per the XMPP Registrar's requirements:</p>
<ul>
<li>urn:xmpp:jingle:apps:file-transfer</li>
</ul>
</section2>
<section2 topic='Jingle Application Formats' anchor='registrar-content'>
<p>The XMPP Registrar shall include "file-transfer" in its registry of Jingle application formats. The registry submission is as follows:</p>
<code><![CDATA[
<application>
<name>file-transfer</name>
<desc>Jingle sessions for the transfer of a file</desc>
<transport>reliable</transport>
<doc>XEP-xxxx</doc>
</application>
]]></code>
</section2>
<section2 topic='Jingle Transport Methods' anchor='registrar-transports'>
<p>The XMPP Registrar shall add to its registry of Jingle transport methods definitions for the reliable transport methods defined in <cite>XEP-0047</cite> and <cite>XEP-0065</cite>. The registry submissions are as follows:</p>
<code><![CDATA[
<transport>
<name>bytestreams</name>
<desc>A method for exchanging data over SOCKS5 Bytestreams.</desc>
<type>reliable</type>
<doc>XEP-0065</doc>
</transport>
<transport>
<name>ibb</name>
<desc>A method for exchanging data over In-Band Bytestreams.</desc>
<type>reliable</type>
<doc>XEP-0047</doc>
</transport>
]]></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='urn:xmpp:tmp:jingle:apps:file-transfer'
xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'
elementFormDefault='qualified'>
<xs:import
namespace='http://jabber.org/protocol/si/profile/file-transfer'
schemaLocation='http://www.xmpp.org/schemas/file-transfer.xsd'/>
<xs:element name='description'>
<xs:complexType>
<xs:choice>
<xs:element ref='offer'/>
<xs:element ref='request'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name='offer'>
<xs:complexType>
<xs:sequence xmlns:ft='http://jabber.org/protocol/si/profile/file-transfer'>
<xs:element ref='ft:file'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='request'>
<xs:complexType>
<xs:sequence xmlns:ft='http://jabber.org/protocol/si/profile/file-transfer'>
<xs:element ref='ft:file'/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</xep>

142
xep-0235.xml Normal file
View File

@ -0,0 +1,142 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Direct Invitations</title>
<abstract>This specification defines an XMPP extension for generating, requesting, and providing invitations, which can be used in the context of Multi-User Chat rooms and other services.</abstract>
&LEGALNOTICE;
<number>0235</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT YET ASSIGNED</shortname>
&stpeter;
<revision>
<version>0.1</version>
<date>2008-03-05</date>
<initials>psa</initials>
<remark><p>Initial published version.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2008-02-20</date>
<initials>psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>&xep0045; includes a protocol for inviting a contact to a chatroom. That protocol results in the sending of an invitation from the chatroom to the contact (a "mediated invitation"), not from the inviting user to the contact (a "direct invitation"). Because use of &xep0016; may result in blocking of XML stanzas from entities that are not in the contact's roster, mediated invitations may never be delivered to the contact. Therefore, this specification defines an XMPP extension that enables a user to directly send an invitation to a contact, thus routing around the blocking of mediated invitations. While the main use case for this protocol is multi-user chat, nothing in the protocol prevents it from being used to invite contacts to other types of services, such as &xep0060; services or future collaboration services.</p>
</section1>
<section1 topic='Obtaining an Invitation' anchor='obtain'>
<p>In order to obtain an invitation that can be directly sent to a contact, a user requests an invitation token from the relevant service. For example, let us imagine that the user &lt;crone1@shakespeare.lit&gt; wishes to invite the contact &lt;hecate@shakespeare.lit&gt; to the chatroom &lt;darkcave@macbeth.shakespeare.lit&gt;. The user would send the following request to the room &NSNOTE;.</p>
<example caption='Token request'><![CDATA[
<iq from='crone1@shakespeare.lit/desktop'
id='request1'
to='darkcave@macbeth.shakespeare.lit'
type='get'>
<invitation
for='hecate@shakespeare.lit'
xmlns='urn:xmpp:tmp:invite'/>
</iq>
]]></example>
<p>If the room supports the direct invitation protocol and the user is allowed to invite contacts to the room, the room returns an invitation token to the user.</p>
<example caption='Token response'><![CDATA[
<iq from='darkcave@macbeth.shakespeare.lit'
id='request1'
to='crone1@shakespeare.lit/desktop'
type='result'>
<invitation
expires='2007-02-21T23:59:59Z'
for='hecate@shakespeare.lit'
jid='darkcave@macbeth.shakespeare.lit'
xmlns='urn:xmpp:tmp:invite'>
37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
</invitation>
</iq>
]]></example>
<p>The syntax of the invitation is as follows.</p>
<ul>
<li>The 'expires' attribute defines a date and time when the invitation expires. Inclusion of this attribute is OPTIONAL. If included, it MUST be a DateTime as specified in &xep0082;.</li>
<li>The 'for' attribute defines the JabberID of the invitee. Inclusion of this attribute is REQUIRED.</li>
<li>The 'jid' attribute defines the JabberID of the service to which the invitee is being invited. Inclusion of this attribute is REQUIRED.</li>
<li>The XML character data of the &lt;invitation/&gt; element is the invitation token itself. The token MAY be generated according to any method deemed appropriate by the service implementation. It is RECOMMENED that the token be the hexadecimal representation of a Keyed-Hash Message Authentication Code (see &nistfips198a;) generated using the SHA256 hashing algorithm (see &nistfips180-2;), as described elsewhere in this document.</li>
</ul>
</section1>
<section1 topic='Sharing an Invitation' anchor='share'>
<p>The user can then send the invitation to the contact in an XMPP message stanza:</p>
<example caption='Sharing the invitation'><![CDATA[
<message from='crone1@shakespeare.lit/desktop' to='hecate@shakespeare.lit'>
<invitation
expires='2007-02-21T23:59:59Z'
for='hecate@shakespeare.lit'
jid='darkcave@macbeth.shakespeare.lit'
xmlns='urn:xmpp:tmp:invite'>
37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
</invitation>
</message>
]]></example>
</section1>
<section1 topic='Using an Invitation' anchor='use'>
<p>The contact then MUST then determine the identity of the service (via &xep0030;) so that it can determine how to use the invitation.</p>
<p>In this example, the service is a multi-user chat service. Therefore if the contact wishes to join the designated chatroom, it will include the invitation in its join request.</p>
<example caption='Chatroom join with invitation'><![CDATA[
<presence from='hecate@shakespeare.lit/broom' to='darkcave@macbeth.shakespeare.lit/Hecate'
<invitation xmlns='urn:xmpp:tmp:invite'>
37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
</invitation>
</iq>
]]></example>
<p>If the invitation is acceptable, the service will then allow the contact to enter the room.</p>
<p><em>Note: Detailed error flows will be added to a future version of this specification.</em></p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>To follow.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='ns'>
<p>Until this specification advances to a status of Draft, its associated namespace shall be "urn:xmpp:tmp:invite"; upon advancement of this specification, the &REGISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</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='urn:xmpp:tmp:invite'
xmlns='urn:xmpp:tmp:invite'
elementFormDefault='qualified'>
<xs:element name='invitation'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='expires' type='xs:string' use='optional'/>
<xs:attribute name='for' type='xs:string' use='optional'/>
<xs:attribute name='jid' type='xs:string' use='optional'/>
<xs:attribute name='node' type='xs:string' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Dave Cridland for his suggestions. Aspects of this specification were inspired by &rfc4467;.</p>
</section1>
</xep>

342
xep-0236.xml Normal file
View File

@ -0,0 +1,342 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Abuse Reporting</title>
<abstract>This specification defines an XMPP protocol extension for reporting abusive traffic between two XMPP servers.</abstract>
&LEGALNOTICE;
<number>0236</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0030</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT YET ASSIGNED</shortname>
&stpeter;
<revision>
<version>0.1</version>
<date>2008-03-05</date>
<initials>psa</initials>
<remark><p>Initial published version.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2008-02-29</date>
<initials>psa</initials>
<remark><p>Added reason element containing machine-readable conditions and optional human-readable text; added note about forwarding of abuse reports.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2008-02-26</date>
<initials>psa</initials>
<remark><p>Limited scope to reporting between two servers; more clearly defined what is abusive; changed protocol to use IQ request-response exchange; limited use of error condition to stream termination.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2008-02-19</date>
<initials>psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>Unfortunately, not all XMPP entities are well-behaved. Currently, if an XMPP entity sends abusive stanzas over a server-to-server connection, there is no way for the receiving server to inform the sending server that the sender is generating abusive traffic. In practice, the receiving server may need to terminate the server-to-server connection (again without explicitly informing the sending server about the reason for the termination) rather than continue to accept the abusive traffic.</p>
<p>This situation is far from desirable. Therefore, this specification defines three small XMPP protocol functions that can help to improve the reliability of server-to-server connections:</p>
<ol>
<li>A method by which the receiving server can send an abuse report to the sending server, including the JID(s) of the sender(s).</li>
<li>An application-specific stanza error condition that can be combined with the standard &notacceptable; stanza error condition to inform the sending server that a particular XMPP stanza is considered abusive.</li>
<li>An application-specific stream error condition that can be combined with the standard &policy; stream error condition to inform the sending server about the reason for termination of an XML stream.</li>
</ol>
</section1>
<section1 topic='Syntax' anchor='syntax'>
<p>An abuse report MUST be sent in an IQ stanza of type "set" containing an &lt;abuse/&gt; element qualified by the 'urn:xmpp:tmp:abuse' namespace &NSNOTE;. The allowable children of the &lt;abuse/&gt; element are:</p>
<ul>
<li>One or more &lt;jid/&gt; elements whose XML character data specifies the JID(s) of the abusive sender(s)</li>
<li>An optional &lt;reason/&gt; element that specifies the reason for the abuse report, via a machine-readable abuse condition defined in this specification, (optionally) human-readable text about the report, and (optionally) an application-specific condition defined outside this specification.</li>
</ul>
<p>This specification intentionally does not define exactly what constitutes abuse, since "abuse is in the eye of the beholder". However, the following machine-readable conditions are defined as children of the &lt;reason/&gt; element.</p>
<table caption='Abuse Conditions'>
<tr>
<th>Condition</th>
<th>Definition</th>
</tr>
<tr>
<td>&lt;gateway/&gt;</td>
<td>Attempting to inappropriately use a gateway on the receiving server (see &xep0100;)</td>
</tr>
<tr>
<td>&lt;muc/&gt;</td>
<td>Attempting to take over or otherwise abuse &xep0045; rooms on the receiving server</td>
</tr>
<tr>
<td>&lt;proxy/&gt;</td>
<td>Attempting to inappropriately use a &xep0065; proxy, TURN server, or other proxy on the receiving server</td>
</tr>
<tr>
<td>&lt;pubsub/&gt;</td>
<td>Attempting to inappropriately use a &xep0060; service on the receiving server</td>
</tr>
<tr>
<td>&lt;service/&gt;</td>
<td>Attempting to inappropriately use any other kind of service on the receiving server</td>
</tr>
<tr>
<td>&lt;spam/&gt;</td>
<td>Sending spam (unsolicited bulk messages)</td>
</tr>
<tr>
<td>&lt;stanza-too-big/&gt;</td>
<td>Sending extremely large stanzas</td>
</tr>
<tr>
<td>&lt;too-many-recipients/&gt;</td>
<td>Sending messages that contain too many recipients (see &xep0033;)</td>
</tr>
<tr>
<td>&lt;too-many-stanzas/&gt;</td>
<td>Sending an extremely large number of stanzas</td>
</tr>
<tr>
<td>&lt;unacceptable-payload/&gt;</td>
<td>Sending messages that contain unacceptable payloads such as malicious executables</td>
</tr>
<tr>
<td>&lt;unacceptable-text/&gt;</td>
<td>Sending messages that contain unacceptable human-readable text</td>
</tr>
<tr>
<td>&lt;undefined-abuse/&gt;</td>
<td>The abuse condition is undefined (should be used with an application-specific condition)</td>
</tr>
</table>
<p>Note: The foregoing list of conditions is not exhaustive. The list may be augmented or otherwise modified in a future version of this specification as a result of implementation and deployment experience.</p>
</section1>
<section1 topic='Abuse Report' anchor='report'>
<section2 topic='Generation' anchor='generation'>
<p>If an XMPP server receives abusive stanzas over a server-to-server connection, the receiving server SHOULD send an abuse report to the sending server.</p>
<example caption='Abuse Report'><![CDATA[
<iq from='example.org'
id='rep1'
to='example.com'
type='set'>
<abuse xmlns='urn:xmpp:tmp:abuse'>
<jid>abuser@example.com/foo</jid>
<reason>
<condition>
<muc/>
</condition>
</reason>
</abuse>
</iq>
]]></example>
</section2>
<section2 topic='Processing' anchor='processing'>
<p>Upon receiving the abuse report, the sending server MUST proceed as follows.</p>
<section3 topic='Abuse Reporting Not Supported' anchor='processing-notsupported'>
<p>If the sending server does not understand the abuse reporting protocol, it MUST return a &unavailable; error to the receiving server.</p>
<example caption='Abuse reporting not supported'><![CDATA[
<iq from='example.com'
id='rep1'
to='example.org'
type='error'>
<error type='cancel'>
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section3>
<section3 topic='Sender(s) Not Found' anchor='processing-notfound'>
<p>If none of the JIDs contained in the abuse report exist at the sending server, the sending server MUST return an &notfound; error to the receiving server.</p>
<example caption='Senders not found'><![CDATA[
<iq from='example.com'
id='rep1'
to='example.org'
type='error'>
<error type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section3>
<section3 topic='Abuse Report Accepted' anchor='processing-accept'>
<p>If the sending server accepts the abuse report for one or more JIDs, it MUST return an IQ stanza of type "result" to the receiving server.</p>
<example caption='Abuse report accepted'><![CDATA[
<iq from='example.com'
id='rep1'
to='example.org'
type='result'/>
]]></example>
<p>This specification does not define how a sending server shall behave when it receives an abuse report. In general it is expected that the sending server (1) will notify the human administrators of the server in some implementation-specific or deployment-specific fashion, and (2) may use the abuse report in an automated fashion (e.g., as input to a rate-limiting algorithm, reputation system, or decision about temporarily suspending the privileges of the sending entity or entities). In addition, the sending server MAY the report to trusted parties such as third-party reporting services.</p>
</section3>
</section2>
</section1>
<section1 topic='Stanza Error' anchor='stanza'>
<p>The receiving server MAY report that a particular stanza is considered abusive. The stanza error condition MUST be &notacceptable; and the error stanza MUST include an application-specific error condition of &lt;abuse/&gt; qualified by the 'urn:xmpp:tmp:abuse' &NSNOTE;. The &lt;abuse/&gt; element MUST include one or more &lt;jid/&gt; elements whose XML character data specifies the JID(s) of the abusive sender(s).</p>
<example caption='Abusive stanza'><![CDATA[
<message from='abuser@example.org/foo'
to='victim@example.org'>
[ ... some abusive payload here ... ]
</message>
]]></example>
<example caption='Stanza error'><![CDATA[
<message from='example.com'
to='example.org'>
<error type='cancel'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
<abuse xmlns='urn:xmpp:tmp:abuse'>
<jid>abuser@example.com/foo</jid>
<reason>
<condition>
<unacceptable-payload/>
</condition>
</reason>
</abuse>
</message>
]]></example>
</section1>
<section1 topic='Stream Error' anchor='stream'>
<p>If the sending entity continues to generate abusive stanzas via the sending server, the receiving server MAY close the stream between the receiving server and the sending server. The stream error condition MUST be &policy; and the stream error MUST include an application-specific error condition of &lt;abuse/&gt; qualified by the 'urn:xmpp:tmp:abuse'. The &lt;abuse/&gt; element MUST include one or more &lt;jid/&gt; elements whose XML character data specifies the JID(s) of the abusive sender(s).</p>
<example caption='Stream Error'><![CDATA[
<stream:error>
<policy-violation xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
<abuse xmlns='urn:xmpp:tmp:abuse'>
<jid>abuser@example.com/foo</jid>
<reason>
<condition>
<too-many-stanzas/>
</condition>
</reason>
</abuse>
</stream:error>
</stream:stream>
]]></example>
<p>The receiving entity then SHOULD terminate the TCP connection between the receiving server and the sending server.</p>
</section1>
<section1 topic='Discovering Support' anchor='disco'>
<p>If a server supports the abuse reporting protocol, it MUST report that fact by including a service discovery feature of "urn:xmpp:tmp:abuse" &NSNOTE; in response to a &xep0030; information request:</p>
<example caption="Service Discovery information request"><![CDATA[
<iq from='example.org'
id='disco1'
to='example.com'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption="Service Discovery information response"><![CDATA[
<iq from='example.com'
id='disco1'
to='example.org'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='urn:xmpp:tmp:abuse'/>
...
</query>
</iq>
]]></example>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<section2 topic='Denial of Service Attacks' anchor='security-dos'>
<p>It is possible for an abusive sender to launch a denial of service attack against legitimate users of the sending server by generating abusive traffic over the server-to-server connection (in fact such attacks have already been observed on XMPP networks). Although use of the abuse reporting protocol does not completely prevent such attacks, it may at least enable sending servers to react to abusive traffic in close to real time, thus helping to "heal" the network when denial of service attacks are launched.</p>
</section2>
<section2 topic='Man in the Middle Attacks' anchor='security-mitm'>
<p>If a malicious entity can inject information into the server-to-server connection, it can falsely send abuse reports to the sending server. Therefore the connection SHOULD be encrypted using Transport Layer Security as specified in &xmppcore;.</p>
</section2>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='ns'>
<p>Until this specification advances to a status of Draft, its associated namespace shall be "urn:xmpp:tmp:abuse"; upon advancement of this specification, the &REGISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</p>
</section2>
<section2 topic='Application-Specific Errors' anchor='registrar-apperror'>
<p>The XMPP Registrar shall add &lt;abuse/&gt; to its registry of application-specific error conditions (see &APPERRORS;), where the element is qualified by the 'urn:xmpp:tmp:abuse' namespace &NSNOTE;.</p>
<p>The registry submission is as follows:</p>
<code><![CDATA[
<condition>
<ns>urn:xmpp:tmp:abuse</ns>
<element>abuse</element>
<desc>the sending entity has generated traffic that the receiving server considers abusive</desc>
<doc>XEP-xxxx</doc>
</condition>
]]></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='urn:xmpp:tmp:abuse'
xmlns='urn:xmpp:tmp:abuse'
elementFormDefault='qualified'>
<xs:element name='abuse'>
<xs:complexType>
<xs:sequence>
<xs:element name='jid' type='xs:string' minOccurs='1' maxOccurs='unbounded'/>
<xs:element ref='reason' minOccurs='0'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='reason'>
<xs:complexType>
<xs:sequence>
<xs:element ref='condition' minOccurs='0' maxOccurs='1'/>
<xs:element name='text' type='xs:string' minOccurs='0' maxOccurs='1'/>
<xs:any namespace='##other' minOccurs='0' maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='condition'>
<xs:complexType>
<xs:choice>
<xs:element name='gateway' type='empty'/>
<xs:element name='muc' type='empty'/>
<xs:element name='proxy' type='empty'/>
<xs:element name='pubsub' type='empty'/>
<xs:element name='service' type='empty'/>
<xs:element name='spam' type='empty'/>
<xs:element name='stanza-too-big' type='empty'/>
<xs:element name='too-many-recipients' type='empty'/>
<xs:element name='too-many-stanzas' type='empty'/>
<xs:element name='unacceptable-payload' type='empty'/>
<xs:element name='unacceptable-text' type='empty'/>
<xs:element name='undefined-abuse' type='empty'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
</xep>

213
xep-0237.xml Normal file
View File

@ -0,0 +1,213 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Roster Versioning</title>
<abstract>This specification proposes a modification to the XMPP roster management protocol to support versioning of rosters for more efficient downloading of the roster information.</abstract>
&LEGALNOTICE;
<number>0237</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT YET ASSIGNED</shortname>
&stpeter;
<revision>
<version>0.1</version>
<date>2008-03-05</date>
<initials>psa</initials>
<remark><p>Initial published version; per Council consensus, removed optionality regarding semantics of the version attribute.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2008-03-05</date>
<initials>psa</initials>
<remark><p>Corrected semantics of version attribute (should be a strictly increasing sequence number but may be any unique identifier).</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2008-03-04</date>
<initials>psa</initials>
<remark><p>Clarified description of roster diff; added diff attribute and specified its use in roster results; specified use of version attribute in roster pushes.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2008-03-04</date>
<initials>psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
&RFC3921BISNOTE;
<p><cite>RFC 3921</cite> specifies that an XMPP client must retrieve the entire roster on login. However, XMPP rosters can be quite large and often the roster has not changed since it was last retrieved. If the client could cache the roster and retrieve only changes to the roster, the login process could be significantly streamlined, which could be especially valuable over low-bandwidth connections such as those common in mobile environments. This document defines a method for such streamlining, via the concept of roster versioning.</p>
<p>Note: This document is provided for discussion purposes in order to improve roster management in XMPP systems. It is not meant to supersede the text in <cite>RFC 3921</cite>. However, the recommendations in this document may be folded into <cite>rfc3921bis</cite>.</p>
</section1>
<section1 topic='Protocol' anchor='proto'>
<p>This document specifies the addition of a 'version' attribute to the &QUERY; element qualified by the 'jabber:iq:roster' namespace, as well as a 'diff' attribute for use in roster results.</p>
<p>The value of the 'version' attribute MUST be a non-negative integer representing a strictly increasing sequence number that is increased with any change to the roster (whether or not the client supports this extension) but MAY be a unique identifer that is opaque to the client but understood by the server. In any case, the 'version' attribute contained in <link url='#push'>roster pushes</link> MUST be unique. A "change to the roster" is any addition, update, or removal of a roster item that would result in a roster push, including changes in subscription states, as described in <cite>RFC 3921</cite> or <cite>rfc3921bis</cite>.</p>
<p>The attribute is used as described in the following sections.</p>
<section2 topic='Advertising Support' anchor='feature'>
<p>If a server supports roster versioning, it MUST inform the client when returning stream features during the stream setup process, at the latest when informing the client that resource binding is required. This is done by including a &lt;roster-versioning/&gt; element qualified by the 'urn:xmpp:tmp:roster-versioning' namespace &NSNOTE;.</p>
<example caption="Stream features"><![CDATA[
<stream:features>
<bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'>
<required/>
</bind>
<roster-versioning xmlns='urn:xmpp:tmp:roster-versioning'>
</stream:features>
]]></example>
</section2>
<section2 topic='Roster Get' anchor='get'>
<p>If a client supports roster versioning and knows that the server does so, it SHOULD include the 'version' attribute in its request for the roster, set to the last version it has cached.</p>
<example caption="Roster get with version number"><![CDATA[
<iq id='r1' type='get'>
<query xmlns='jabber:iq:roster' version='305'/>
</iq>
]]></example>
<p>If the client has not yet cached the roster or the cache is lost or corrupted, but the client wishes to bootstrap the use of roster versioning, it SHOULD include the 'version' attribute set to a value of zero (0).</p>
</section2>
<section2 topic='Roster Result (Unchanged)' anchor='result-unchanged'>
<p>If the roster has not changed since the version enumerated by the client, the server MUST return an empty IQ-result.</p>
<example caption="Roster result (unchanged)"><![CDATA[
<iq id='r1' type='result'/>
]]></example>
</section2>
<section2 topic='Roster Result (Changed)' anchor='result-changed'>
<p>If the roster version has increased since the version enumerated by the client, the server MUST return a &QUERY; element that includes the latest version number.</p>
<p>The &QUERY; element SHOULD include the effective "diff" since the roster version enumerated by the client (including the complete roster item with name, group, and subscription state). If the roster result is a diff and not the complete roster, the server MUST include a 'diff' attribute set to a value of "true" or "1" &BOOLEANNOTE;. If the roster result is the complete roster and not a diff, the server SHOULD NOT include the 'diff' attribute (which defaults to "false" or "0").</p>
<example caption="Roster result (changed)"><![CDATA[
<iq id='r1' type='result'>
<query xmlns='jabber:iq:roster' version='317'>
<item jid='bill@shakespeare.lit' subscription='both'/>
<item jid='nurse@capulet.lit' name='Nurse' subscription='both'>
<group>Servants</group>
</item
<item jid='shylock@shakespeare.lit' subscription='remove'/>
</query>
</iq>
]]></example>
<p>The "roster diff" can be understood as follows:</p>
<ol>
<li>Imagine that the client had an active presence session for the entire time between its cached roster version (in this case, 305) and the new roster version (317).</li>
<li>During that time, the client would have received roster pushes related to roster versions 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 316, and 317.</li>
<li>However, some of those roster pushes might have contained intermediate updates to the same roster item (e.g., changes in the subscription state for bill@shakespeare.lit from "none" to "to" and from "to" to "both").</li>
<li>The roster result would not include all of the intermediate steps, only the final result of all changes applied while the client was in fact offline.</li>
</ol>
</section2>
<section2 topic='Roster Pushes' anchor='push'>
<p>When the server sends subsequent roster pushes to the client, it MUST include the updated roster version number.</p>
<example caption="Roster push"><![CDATA[
<iq id='p1' type='set'>
<query xmlns='jabber:iq:roster' version='318'>
<item jid='bill@shakespeare.lit' name='The Bard' subscription='both'/>
</query>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>It is possible that caching of the roster (rather than holding it in memory only for the life of the session) could introduce new vulnerabilities. Client implementations should take care to appropriately protect the cached roster information.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='ns'>
<p>Until this specification advances to a status of Draft, the associated namespace for its stream feature shall be "urn:xmpp:tmp:roster-versioning"; upon advancement of this specification, the &REGISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</p>
</section2>
</section1>
<section1 topic='XML Schemas' anchor='schemas'>
<section2 topic='Roster Management' anchor='schemas-roster'>
<p>If this modification to the roster management protocol is added to rfc3921bis and approved by the IESG in the speficiation that supersedes RFC 3921, the schema for the roster management namespace would be changed as follows.</p>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:iq:roster'
xmlns='jabber:iq:roster'
elementFormDefault='qualified'>
<xs:element name='query'>
<xs:complexType>
<xs:sequence>
<xs:element ref='item'
minOccurs='0'
maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='diff' use='optional' type='xs:boolean' default='false'>
<xs:attribute name='version' use='optional' type='xs:nonNegativeInteger'>
</xs:complexType>
</xs:element>
<xs:element name='item'>
<xs:complexType>
<xs:sequence>
<xs:element ref='group'
minOccurs='0'
maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='ask' use='optional'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='subscribe'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name='jid' type='xs:string' use='required'/>
<xs:attribute name='name' type='xs:string' use='optional'/>
<xs:attribute name='subscription' use='optional'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='both'/>
<xs:enumeration value='from'/>
<xs:enumeration value='none'/>
<xs:enumeration value='remove'/>
<xs:enumeration value='to'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name='group' type='xs:string'/>
</xs:schema>
]]></code>
</section2>
<section2 topic='Stream Feature' anchor='schemas-feature'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:tmp:roster-versioning'
xmlns='urn:xmpp:tmp:roster-versioning'
elementFormDefault='qualified'>
<xs:element name='roster-versioning' type='empty'>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section2>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Dave Cridland, Richard Dobson, Alexander Gnauck, and Pedro Melo for their comments.</p>
</section1>
</xep>