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

added all existing inbox items available in XML format

This commit is contained in:
stpeter 2010-07-21 14:33:01 -06:00
parent 7b355e9105
commit 068338ca6d
34 changed files with 15164 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1174
inbox/calendaring.xml Executable file
View File

File diff suppressed because it is too large Load Diff

429
inbox/carbons.xml Normal file
View File

@ -0,0 +1,429 @@
<?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>Message Carbons</title>
<abstract>In order to keep all IM clients for a user engaged in a conversation, outbound messages are carbon-copied to all interested resources.</abstract>
<legal>
<copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2010 by the XMPP Standards Foundation (XSF).</copyright>
<permissions>Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the &quot;Specification&quot;), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.</permissions>
<warranty>## NOTE WELL: This Specification is provided on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##</warranty>
<liability>In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.</liability>
<conformance>This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at &lt;<link url='http://www.xmpp.org/extensions/ipr-policy.shtml'>http://www.xmpp.org/extensions/ipr-policy.shtml</link>&gt; or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).</conformance>
</legal>
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0001</spec>
<spec>XEP-0030</spec>
<spec>XEP-0085</spec>
</dependencies>
<supersedes>
<spec>XEP-0259</spec>
</supersedes>
<supersededby/>
<shortname>carbons</shortname>
<author>
<firstname>Joe</firstname>
<surname>Hildebrand</surname>
<email>jhildebr@cisco.com</email>
<jid>jhildebr@cisco.com</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2010-02-25</date>
<initials>jjh</initials>
<remark><p>First draft.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2010-04-21</date>
<initials>jjh</initials>
<remark><p>Updated after further analysis of edge cases.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>At the time of original writing of this XEP, many XMPP servers
handle message stanzas sent to a user@host (or "bare") JID with no
resource by delivering that message only to the resource with the
highest priority for the target user. Some server implementations,
however, have chosen to send these messages to all of the online
resources for the target user. If the target user is online with
multiple resources when the original message is sent, a conversation
ensues on one of the user's devices; if the user subsequently
switches devices, parts of the conversation may end up on the
alternate device, causing the user to be confused, misled, or
annoyed.</p>
<p>This XEP defines an approach for ensuring that all of my devices
get both sides of all conversations in order to avoid user
confusion. As a pleasant side-effect, information about the current
state of a conversation is shared between all of a user's clients
that implement this protocol.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<ul>
<li>Large changes SHOULD NOT be required to existing servers</li>
<li>Clients that do not implement the new protocol MUST be able
participate in conversations</li>
<li>Clients that do not implement the new protocol MUST NOT
receive a large number of new partial conversations</li>
<li>Clients that do not implement the new protocol MUST NOT
receive protocol they do not expect</li>
<li>All clients that turn on the new protocol MUST be able to see
all inbound chat-type messages.</li>
<li>All clients that turn on the new protocol MUST be able to see
all outbound chat-type messages from all of the resources of the
user, regardless of whether the clients for the other resources
have implemented the new protocol.</li>
</ul>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Discovering Support' anchor='disco'>
<p>If a server implements the Message Carbons capability, it MUST specify the
'urn:xmpp:carbons:0' feature in its service discovery
information features as specified in &xep0030; or section 6.3 of &xep0115;.
Clients MUST NOT enable or disable Carbons if their server does
not support this feature.</p>
<example caption='Client requests information about its own server'><![CDATA[
<iq type='get'
from='romeo@montague.net/orchard'
id='info1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
<example caption='Server responds with Carbons feature'><![CDATA[
<iq type='get'
to='romeo@montague.net/home'
from='montague.net'
id='info1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='urn:xmpp:carbons:0'/>
...
</query>
</iq>]]></example>
</section2>
<section2 topic='Enabling Carbons' anchor='enabling'>
<p>Servers MUST NOT enable the Carbons protocol for a client by
default, since unmodified clients might be confused by the new
protocol. When a client wants to participate in the Carbons
protocol, it sends an IQ set to enable the protocol.</p>
<example caption='Client enables Carbons'><![CDATA[
<iq type='set' id='enable1'>
<carbons var='urn:xmpp:carbons:0' mode='enable'/>
</iq>]]></example>
<p>Carbons will generally be enabled before the client sends the
first undirected presence, to ensure that all inbound messages
will be delivered according to the Carbon rules. The server will
respond with an IQ result when Carbons are enabled:</p>
<example caption='Server acknowledges Carbons enablement'><![CDATA[
<iq type='result' id='enable1'/>]]></example>
</section2>
<section2 topic='Disabling Carbons' anchor='disabling'>
<p>Some clients might want to disable Carbons. An example of this
might be a mobile client that wants Carbons when the application
is in the foreground, and disabled when it is in the background.
To disable Carbons, clients send an IQ set:</p>
<example caption='Client disables Carbons'><![CDATA[
<iq type='set' id='disable1'>
<carbons var='urn:xmpp:carbons:0' mode='disable'/>
</iq>]]></example>
<p>The server will respond with an IQ result when Carbons are disabled:</p>
<example caption='Server acknowledges Carbons enablement'><![CDATA[
<iq type='result' id='disable1'/>]]></example>
</section2>
<section2 topic='Error Cases' anchor='errors'>
<p>Enabling or disabling Carbons may fail in the several ways. If
one of these errors is returned, the server MUST keep the previous
state, where the initial state is Carbons disabled. For example,
if the first enable returns an error, the server MUST NOT enable
Carbons.</p>
<section3 topic='bad-request' anchor='bad-request'>
<p>The sender has sent a stanza containing XML that does not
conform to the appropriate schema or that cannot be processed.
One example is an IQ stanza that includes an unrecognized value
of the 'type' attribute. Another is changing to the state that
is already in effect (enabling Carbons a second time).</p>
<example caption='Error: bad-request'><![CDATA[<iq id='enable1'
type='error'>
<error type='modify'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>]]></example>
</section3>
<section3 topic='feature-not-implemented' anchor='feature-not-implemented'>
<p>The sender has sent an enable or disable request to a server
that does not support the protocol. This SHOULD NOT happen in
practice, because clients MUST check for server support before
sending their request.</p>
<example caption='Error: feature-not-implemented'><![CDATA[<iq id='enable1'
type='error'>
<error type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>]]></example>
</section3>
<section3 topic='forbidden' anchor='forbidden'>
<p>The sender does is forbidden by policy from enabling or
disabling Carbons.</p>
<example caption='Error: forbidden'><![CDATA[<iq id='enable1'
type='error'>
<error type='auth'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>]]></example>
</section3>
<section3 topic='not-allowed' anchor='not-allowed'>
<p>The receiver does not allow any entity to turn on Carbons.
This might occur in a multi-domain deployment, where
administrators of one domain allow Carbons, but another does
not.</p>
<example caption='Error: not-allowed'><![CDATA[<iq id='enable1'
type='error'>
<error type='cancel'>
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>]]></example>
</section3>
</section2>
<section2 topic='Inbound Messages' anchor='inbound'>
<p>Messages of type chat that are addressed to the bare JID
(localpart@domain) MUST be copied by the receiving server to all of the
resources for that user that have non-negative presence priority
and have not filtered messages through some other means. The
process of making copies is known as "forking." The receiving
server SHOULD NOT modify the 'to' address of the forked
messages.</p>
<example caption='Juliet sends Romeo an undirected message, which is forked'><![CDATA[
<message
from='juliet@example.com/balcony'
to='romeo@example.net'
type='chat'>
<body>Wherefore art thou, Romeo?</body>
<thread>0e3141cd80894871a68e6fe6b1ec56fa</thread>
</message>
... each of romeo@example.net's resources receives this stanza verbatim
]]></example>
<p>Messages of type "chat" that are addressed to a full JID
(localpart@domain/resource) MUST be sent by the receiving server to the
addressed resource, and MUST also be sent to all of the
Carbons-enabled resources for the receiving user. The goal of
the copies to Carbons-enabled resources is to allow those clients
to have both halves of *all* IM conversations, including messages
that are sent from clients that lock in to particular resources.</p>
</section2>
<section2 topic='Sending Messages' anchor='sending'>
<p>Once most of the clients that are deployed have implemented
Carbons, clients MAY choose to always send chat type messages to
the bare JID. Until then, traditional resource locking is
RECOMMENDED. (Note: another XEP might be written to document
traditional resource locking, if the documentation in &rfc3921bis;
is not sufficient.)</p>
<p>Also note that &xep0085; recommends sending chat state
notifications as chat type messages, which means that they will be
subject to Carbon-copying. This is intentional.</p>
</section2>
<section2 topic='Outbound Message Carbon Copies' anchor='outbound'>
<p>Carbons clients want to have copies of messages going in
<em>both</em> directions for other resources associated with the
same user. To that end, messages of type chat that are sent from
any resource MUST be copied by the sending server to each of the
resources that have enabled Carbons, but are not the sending
resource. Note that the 'to' address will be the original target of
the message (bare JID, as above), and the 'from' address will
contain the full JID (localpart@domain/resource) of the sending
resource. The 'to' address not matching the JID of the session is
somewhat unprecedented in XMPP, which is why Carbons must be
explicitly enabled.</p>
<p>Messages that have carbon copies sent back to Carbons-enabled
resources MUST NOT be copied back to the originating client. The
copies MUST have the full JID (localpart@domain/resource) of the sender
as the 'from' address. The copies MUST include a sent element in
the urn:xmpp:carbons:0 namespace.</p>
<example caption='Romeo responds to Juliet, which is Carboned'><![CDATA[
<message
to='juliet@example.com/balcony'
from='romeo@example.net/home'
type='chat'>
<body>Neither, fair saint, if either thee dislike.</body>
<thread>0e3141cd80894871a68e6fe6b1ec56fa</thread>
</message>]]></example>
<example caption='Romeo&apos;s OTHER Carbons-enabled clients
receive a copy'><![CDATA[
<message
to='juliet@example.com/balcony'
from='romeo@example.net/home'
type='chat'>
<body>Neither, fair saint, if either thee dislike.</body>
<thread>0e3141cd80894871a68e6fe6b1ec56fa</thread>
<sent xmlns='urn:xmpp:carbons:0'/>
</message>]]></example>
</section2>
<section2 topic='Avoiding Carbons for a single message' anchor='avoiding'>
<p>Some clients might want to avoid carbons on a single message,
while still keeping all of the other semantics of Carbon support.
This might be useful for clients sending end-to-end encrypted
messages, for example.</p>
<p>To avoid a message being Carbon-copied to its other resources,
the sending client MUST add a private element in the
urn:xmpp:carbons:0 namespace. When the sending server receives
the message, it MUST NOT make carbon copies to the other
Carbons-enabled resources, and MUST remove the private element
before forwarding the message to the intended recipient.</p>
<p>Note: use of the private mechanism will lead to partial
conversations on other devices. This is the intended effect.</p>
<example caption='Romeo sends to Juliet, avoiding Carbon copies'><![CDATA[
<message
to='juliet@example.com'
from='romeo@example.net/home'
type='chat'>
<body>Neither, fair saint, if either thee dislike.</body>
<thread>0e3141cd80894871a68e6fe6b1ec56fa</thread>
<private xmlns='urn:xmpp:carbons:0'/>
</message>]]></example>
<example caption='Romeo&apos;s server removes the private tag before forwarding, and does NOT send carbon copies to Romeo&apos;s other resources'><![CDATA[
<message
to='juliet@example.com'
from='romeo@example.net/home'
type='chat'>
<body>Neither, fair saint, if either thee dislike.</body>
<thread>0e3141cd80894871a68e6fe6b1ec56fa</thread>
</message>]]></example>
</section2>
</section1>
<section1 topic='Business Rules' anchor='rules'>
<section2 topic='Interaction with Chat States' anchor='chatstates'>
<p>Clients that implement Carbons MAY take special use of
&xep0085; notifications.</p>
<p>It is RECOMMENDED that upon receiving an outbound <em>gone</em>
chat state (as a carbon copy) for a given conversation, that
conversation be removed from user display as if the user on the
copied client had terminated the conversation. In order to
prevent unwanted termination of conversations on other resources,
clients SHOULD NOT send <em>gone</em> chat states on logout, but
instead SHOULD count on the unavailable presence to convey the change
in attention.</p>
<p>Upon receiving an outbound notification of any chat state other
than <em>gone</em>, the copied client MAY conclude that the
sending client has taken responsibility for the conversation, and
make appropriate user interface modifications. For example,
notifications could be muted on non-primary devices.</p>
</section2>
<section2 topic='Handling of errors' anchor='errors'>
<p>When a receiving server attempts to deliver a forked message,
and that message bounces with an error for any reason, the
receiving server MUST NOT forward that error back to the original
sender. The receiving server SHOULD use the sent element in the
bounce to determine that an error is from a forked message.</p>
<p>This rule is used to prevent some of the half-failure modes
that have been an issue in other prototocols.</p>
</section2>
<section2 topic='Auto-responses' anchor='auto-responses'>
<p>Clients that automatically respond to messages for any reason
(e.g. when in DND presence state) MUST take adequate care when
enabling Carbons in order to prevent storms or loops. Carbon
copies of outbound messages MUST NOT be auto-replied to under any
circumstances. Forked inbound messages SHOULD NOT be auto-replied
to, unless the client has some way of knowing that the receiver
will not receive more than one auto-reply from other similar
clients for the same user.</p>
</section2>
<section2 topic='Mobile Considerations' anchor='mobile'>
<p>Since mobile devices often must pay for network traffic based
on usage, the enablement of Carbons for such devices should be
undertaken advisedly. More complicated mechanisms for controlling
the Carbon-copying or forking of individual conversations may need
to be added to deal with mobile clients in the future.</p>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>The security model assumed by this document is that all of the
resources for a single user are in the same trust boundary.</p>
<p>Outbound chat messages that are encrypted end-to-end are not often
useful to receive on other resources. As such, they should use the
private element specified above to avoid such copying, unless the
encryption mechanism is adjusted to have knowledge of Carbons.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='reg'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:carbons:0</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2>
<section2 topic='Protocol Versioning' anchor='registrar-versioning'>
&NSVER;
</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:carbons:0'
xmlns='urn:xmpp:carbons:0'
elementFormDefault='qualified'>
<xs:element name='carbons'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='mode' use='required'>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="enable"/>
<xs:enumeration value="disable"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='sent' type='empty'/>
<xs:element name='private' type='empty'/>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>]]>
</code>
</section1>
</xep>

223
inbox/decloak.xml Executable file
View File

@ -0,0 +1,223 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
<!ENTITY TYBALTCAPS "&lt;c ver=&quot;[Tybalt's client's caps hash]&quot; .../&gt;">
<!ENTITY JULIETCAPS "&lt;c ver=&quot;[Juliet's client's caps hash]&quot; .../&gt;">
<!ENTITY GWCAPS "&lt;c ver=&quot;[SIP gateway's caps hash]&quot; .../&gt;">
<!ENTITY DECLOAK "http://telepathy.freedesktop.org/xmpp/protocol/decloak">
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Presence Decloaking</title>
<abstract>This specification defines an XMPP protocol extension that enables a user to send directed presence with a request for the target to reciprocate.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards track</type>
<sig>None</sig>
<approver>Council</approver>
<dependencies/>
<supersedes/>
<supersededby/>
<shortname>NOT YET ASSIGNED</shortname>
<author>
<firstname>Simon</firstname>
<surname>McVittie</surname>
<email>simon.mcvittie@collabora.co.uk</email>
<jid>simon.mcvittie@collabora.co.uk</jid>
</author>
&stpeter;
&robmcqueen;
<revision>
<version>0.0.2</version>
<date>2010-01-17</date>
<initials>psa</initials>
<remark><p>Rewrote the introduction, clarified the security considerations, requested issuance of an appropriate URN from the XMPP Registrar.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2010-01-05</date>
<initials>smcv/psa/rm</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>Various XMPP extensions, such as &xep0166;, require additional support from clients, advertised in presence via &xep0115;, or require that IQ stanzas are sent to a particular resource. For instance, Jingle calls can be made only by sending an IQ to a particular resource. However, two parties who wish to communicate do not always shared presence information and therefore cannot use &xep0115; to determine the correct resource (full JID) for communication. Indeed, one of the parties might not even use XMPP: e.g., a remote user on the other side of a gateway to a network based on the Session Initiation Protocol (SIP; &rfc3261;) or to the Public Switched Telephone Network (PSTN). It would be helpful if a user could make a call through such a gateway by typing the SIP URI or telephone number of an arbitrary contact, without first exchanging presence.</p>
<p>This document defines an XML protocol extension to request that enables two parties to temporarily reveal their presence to each other through an intentional presence leak that we call "decloaking".</p>
<p>Note: This protocol has already been implemented using an XML namespace of "&DECLOAK;" but the &REGISTRAR; is requested to issue the XMPP URN "urn:xmpp:decloak:0" upon publication of this proposal in the &xep0001; series.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>An entity should be able to attempt to initiate a communication session that requires IQs and/or capability negotiation (Jingle, a file transfer, end-to-end encryption, or other similar communication modes) with an arbitrary entity.</p>
<p>If the receiving entity agrees to divulge their presence in this way, minimal presence (with no 'type' attribute, &SHOW; element, avatar hash, etc.) and capabilities should be communicated to the initiating entity, so that the initiating entity can continue to initiate the communication session.</p>
</section1>
<section1 topic='Scenario' anchor='scenario'>
<p>Suppose that Juliet wishes to make a media call to Tybalt, but the two parties do not share presence information in accordance with &xmppim;. Suppose also that Juliet and Tybalt have the following presence, although neither can initially see the other's presence:</p>
<example caption="Initial state">
<![CDATA[
<presence from='juliet@shakespeare.lit/balcony'>
<show>dnd</show>
<status>on the phone</status>
]]>&JULIETCAPS;<![CDATA[
</presence>
<presence from='tybalt@shakespeare.lit/library'>
<show>dnd</show>
<status>researching</status>
]]>&TYBALTCAPS;<![CDATA[
</presence>
<presence from='tybalt@shakespeare.lit/garden'>
<show>xa</show>
<status>gone to the library</status>
]]>&TYBALTCAPS;<![CDATA[
</presence>
]]></example>
<p>Juliet requests that Tybalt divulges his availability and capabilities, by sending directed presence to his bare JID &lt;tybalt@shakespeare.lit&gt;, where the presence stanza contains a &lt;decloak/&gt; element.</p>
<example caption="Requesting that a peer decloaks"><![CDATA[
<presence from='juliet@shakespeare.lit/balcony'
to='tybalt@shakespeare.lit'>
]]>&JULIETCAPS;<![CDATA[
<decloak xmlns='urn:xmpp:decloak:0' reason='media'/>
</presence>
]]></example>
<p>Tybalt MAY decloak one or more resources in response, by sending directed presence from those resource(s) to Juliet's bare JID.</p>
<example caption="Decloaking in response to a request">
<![CDATA[
<presence from='tybalt@shakespeare.lit/library'
to='juliet@shakespeare.lit'>
]]>&TYBALTCAPS;<![CDATA[
</presence>
<presence from='tybalt@shakespeare.lit/garden'
to='juliet@shakespeare.lit'>
]]>&TYBALTCAPS;<![CDATA[
</presence>
]]></example>
<p>Once Juliet has received the decloaked presence from Tybalt, if necessary she can perform service discovery to find out the meaning of the entity capabilities hashes (if unknown), then proceed to make a Jingle call, initiate a file transfer, or complete some other use case.</p>
<p>Alternatively, Tybalt MAY ignore the request (in particular, this will happen for any resource that does not implement this specification).</p>
</section1>
<section1 topic='Decloaking with a Gateway' anchor='gateway'>
<p>Let us now suppose that Juliet wishes to make a media call to Romeo, who does not use XMPP but who has a SIP URI of sip:romeo@shakespeare.lit, which can be called via an XMPP-to-SIP gateway.</p>
<p>Juliet requests that the SIP contact representing Romeo on the gateway shall divulge its availability and capabilities, by sending directed presence to its bare JID at the gateway containing a &lt;decloak/&gt; element.</p>
<example caption="Requesting that a gateway contact shall decloak">
<![CDATA[
<presence from='juliet@shakespeare.lit/balcony'
to='romeo%shakespeare.lit@sip.shakespeare.lit'>
]]>&JULIETCAPS;<![CDATA[
<decloak xmlns='urn:xmpp:decloak:0' reason='media'/>
</presence>
]]></example>
<p>In response, the SIP gateway automatically decloaks on behalf of that JID, in order to tell Juliet what the gateway's capabilities are.</p>
<example caption="Decloaking in response to a request">
<![CDATA[
<presence from='romeo%shakespeare.lit@sip.shakespeare.lit'
to='juliet@shakespeare.lit'>
]]>&GWCAPS;<![CDATA[
</presence>
]]></example>
<p>As above, Juliet can now complete service discovery and any protocol-specific use cases.</p>
</section1>
<section1 topic='The reason Attibute' anchor='reason'>
<p>To signal the type of communication that is desired, the entity that first decloaks MAY include a 'reason' attribute on the &lt;decloak/&gt; element. The following values for the 'reason' attribute are defined:</p>
<dl>
<dt>media</dt>
<dd>Presence is requested for a voice and/or video call, e.g. via &xep0167;.</dd>
<dt>text</dt>
<dd>Presence is requested for a plaintext or &xep0071; conversation, e.g. with end-to-end encryption (which requires capabilities to be disclosed).</dd>
<dt>file</dt>
<dd>Presence is requested for one or more file transfers, e.g. via &xep0234; or &xep0095;.</dd>
</dl>
<p>Inclusion of the 'reason' attribute can be interpreted by the receiving client as a signal that communication is about to start; for instance, a call accept/reject dialog could double as a UI for accepting or rejecting a decloaking request.</p>
</section1>
<section1 topic='Business Rules' anchor='bizrules'>
<p>To limit the extent of the presence leak, the receiving entity SHOULD send only bare presence without the XMPP &PRIORITY;, &SHOW;, or &STATUS; element. Unfortunately, this has two implications:</p>
<ol>
<li><p>The initiating entity cannot know which of the receiving entity's resources is more likely to engage in communication. This might imply that the initiating entity will need to send a session initiation request or other communication to more than one of the receiving entity's resources (and then retract the session initiation requests that are not answered by the receiving entity). Solutions to that problem are out of scope for this specification.</p></li>
<li><p>Set up of a session might be delayed (e.g., because in Jingle it is desirable to start negotiating candidates as soon as possible but a user interface that prompts the receiving entity to explicitly approve of divulging presence will tend to delay call setup). As a result, it may be advantageous to have a way to configure unconditional decloaking in certain deployments, at least within the same trust domain.</p></li>
</ol>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>Because decloaking is a presence leak (albeit intentional), an XMPP client that implements the receiving side of this specification MUST disable decloaking by default and MUST enable the feature only as a result of explicit user configuration. (Gateways and other non-user entities MAY divulge their own presence and capabilities unconditionally, if that is appropriate for the service policy at the gateway.)</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'>
<p>The XMPP Registrar is requested to issue an initial namespace of "urn:xmpp:decloak:0".</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:decloak:0'
xmlns='urn:xmpp:decloak:0'
elementFormDefault='qualified'>
<xs:element name='decloak'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='reason' 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>The need for this protocol extension, and a rough proposal for solving the problem, were originally determined at XMPP Summit 5 in the summer of 2007. Thanks to Diana Cionoiu, Justin Karneges, and Justin Uberti for their input to those discussions.</p>
</section1>
</xep>

383
inbox/distributedmuc.xml Executable file
View File

@ -0,0 +1,383 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
<!ENTITY ROOM "&lt;room@service&gt;">
<!ENTITY ROOMJID "&lt;room@service/nick&gt;">
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Distributed Multi-User Chat</title>
<abstract>This document defines methods for distributing Multi-User Chat (MUC) rooms across multiple services.</abstract>
&LEGALNOTICE;
<number>XXXX</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies>
<spec>XEP-0045</spec>
<spec>XEP-0030</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>dmuc</shortname>
&stpeter;
<revision>
<version>0.0.2</version>
<date>2010-02-05</date>
<initials>psa</initials>
<remark><p>Simplified the protocol to use a master-slave approach; modified terminology.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2007-06-01</date>
<initials>psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<section2 topic='Motivation' anchor='motivation'>
<p>&xep0045; defines a full-featured technology for multi-user text conferencing in XMPP. By design, <cite>XEP-0045</cite> assumes that a conference room is hosted at a single service, which can be accessed from any point on the network. However, this assumption introduces a single point of failure for the conference room, since if occupants at a using domain lose connectivity to the hosting domain then they also lose connectivity to the room. In some deployment scenarios (and even on the open Internet) this behavior is suboptimal. Therefore, this document attempts to define a technology for distributing MUC rooms across multiple services.</p>
</section2>
<section2 topic='Requirements' anchor='requirements'>
<p>This specification addresses the following requirements:</p>
<ol start="1">
<li>Enable distribution of a MUC room across multiple services.</li>
<li>Enable a service to determine which other services it will peer with.</li>
<li>Enable the room creator to specify if distribution is allowed.</li>
<li>Enable occupants to remain in an instance of the conference if connectivity is lost to other instances.</li>
<li>Enable syncing of history, configuration, and room rosters on reconnect.</li>
</ol>
</section2>
<section2 topic='Approach' anchor='approach'>
<p>The basic approach to distribution of MUC rooms is as follows:</p>
<ol start="1">
<li>A user creates a room on a service and configures it as "distributed" (or the service assumes that the room is distributed based on local service policy); this first instance of the room is called a SOURCE and the service on which it is created is called a FIRSTHOST.</li>
<li>The firsthost can immediately request that other services (called PEERHOSTS) replicate the room by creating their own local instances (called SHADOWS); alternatively, the firsthost can wait to send the replication request until users from the peerhost have joined the room.</li>
<li>If a user from the peerhost attempts to join the source room after replication is established, the firsthost invites the user to join the shadow rather than the source by sending a direct invitation to the user.</li>
<li>As long as the peerhost and firsthost have connectivity, they share room messages, room rosters, and room configuration changes in real time. If any conflict arises, the firsthost's information rules since it is "first among equals".</li>
<li>If the peerhost loses connectivity to the firsthost, it maintains the shadow, including local room history, room roster, and room configuration, and if possible also maintains connectivity with other peerhosts.</li>
<li>Upon reconnecting to the firsthost, a peerhost exchanges room history and room rosters with the firsthost and receives room configuration data (if modified).</li>
</ol>
<p>The room IDs of source rooms SHOULD be opaque to users and unique across all possible peerhosts, for example by generating a UUID in accordance with &rfc4122; or by hashing the human-readable name of the room using the SHA-256 algorithm in accordance with &nistfips180-2;.</p>
</section2>
</section1>
<section1 topic='Terminology' anchor='terms'>
<section2 topic='General Terms' anchor='terms-general'>
<p>This document adds the following terms to those defined in <cite>XEP-0045</cite>:</p>
<ul>
<li>Firsthost -- The MUC service at which a room is created.</li>
<li>Peerhost -- Any MUC service (other than the firsthost) that hosts an instance of the room.</li>
<li>Shadow -- An instance of the room at a peerhost.</li>
<li>Source -- The canonical instance of the room at the firsthost.</li>
</ul>
</section2>
<section2 topic='Entities' anchor='terms-entities'>
<p>In this document, the examples use the following entities.</p>
<ul>
<li>Firsthost: firsthost.example.com</li>
<li>Peerhosts: peer1.example.net and peer2.example.org</li>
<li>Shadows: f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net and f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer2.example.org</li>
<li>Source: f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com</li>
</ul>
</section2>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Creating a Room' anchor='create'>
<p>When the original room owner creates the room (or subsequently configures the room), the service MAY offer the option of making the room a "distributed room". This is done by including the "muc#roomconfig_distributed" feature in the room configuration form:</p>
<example caption='Service Sends Configuration Form'><![CDATA[
<iq from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com'
id='create1'
to='scott@example.com/desktop'
type='result'>
<query xmlns='http://jabber.org/protocol/muc#owner'>
<x xmlns='jabber:x:data' type='form'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/muc#roomconfig</value>
</field>
...
<field
label='Distribute Room Across Multiple Services?'
type='boolean'
var='muc#roomconfig_distributed'>
<value>0</value>
</field>
...
</x>
</query>
</iq>
]]></example>
<p>The room owner specifies a value of "1" or "true" &BOOLEANNOTE; if room distribution is desired:</p>
<example caption='Room Owner Submits Configuration Form'><![CDATA[
<iq from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com'
id='configure1'
to='scott@example.com/desktop'
type='set'>
<query xmlns='http://jabber.org/protocol/muc#owner'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/muc#roomconfig</value>
</field>
...
<field var='muc#roomconfig_distributed'>
<value>true</value>
</field>
...
</x>
</query>
</iq>
]]></example>
<p>Alternatively, the firsthost can choose to perform room distribution in the background, rather than exposing the 'muc#roomconfig_distributed' option to the user.</p>
</section2>
<section2 topic='Replicating a Room' anchor='replication'>
<p>When a firsthost would like a peerhost to provide a shadow, it sends a replication request to the peerhost.</p>
<example caption='Firsthost Requests Replication of Room'><![CDATA[
<iq from='firsthost.example.com'
id='replicate1'
to='peer1.example.net'
type='set'>
<replicate xmlns='urn:xmpp:dmuc:0'>
<room id='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39'/>
</replicate>
</iq>
]]></example>
<p>If the peerhost is willing and able to replicate the room, it returns an IQ-result:</p>
<example caption='Peerhost Acknowledges Replication Request'><![CDATA[
<iq to='peer1.example.net'
id='replicate1'
from='firsthost.example.com'
type='result'/>
]]></example>
<p>Several error cases are possible (the peerhost is resource constrained, the firsthost is forbidden to peer with the peerhost, etc.); these will be specified more fully in a future version of this specification.</p>
<p>Once the peerhost acknowledges that it is willing and able to replicate the room, four things happen:</p>
<ol start="1">
<li>The source sends the room configuration to the shadow.</li>
<li>The source sends the room roster to the shadow.</li>
<li>The shadow optinoally requests the room history from the source.</li>
<li>The firsthost informs other peerhosts about the new peerhost.</li>
</ol>
<example caption='Source Sends Room Configuration to Shadow'><![CDATA[
<iq from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com'
id='config1'
to='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net'
type='set'>
<config xmlns='urn:xmpp:dmuc:0'>
<x xmlns='jabber:x:data' type='form'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/muc#roomconfig</value>
</field>
...
</x>
</config>
</iq>
]]></example>
<example caption='Shadow Acknowledges Receipt of Room Configuration'><![CDATA[
<iq to='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net'
id='config1'
from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com'
type='result'/>
]]></example>
<example caption='Source Sends Room Roster to Shadow'><![CDATA[
<iq from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com'
id='roster1'
to='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net'
type='set'>
<roster xmlns='urn:xmpp:dmuc:0'>
<item affiliation='owner' jid='scott@example.com/desktop' name='foo'/>
<item affiliation='admin' jid='boyd@example.com/laptop' name='bar'/>
<item affiliation='none' jid='lorraine@example.com/pda' name='baz'/>
</roster>
</iq>
]]></example>
<example caption='Shadow Acknowledges Receipt of Room Roster'><![CDATA[
<iq to='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net'
id='roster1'
from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com'
type='result'/>
]]></example>
<p>The new shadow SHOULD request the room history. This is done by sending an IQ-get from the shadow to the source, containing a &lt;history/&gt; element qualified by the 'http://jabber.org/protocol/muc' namespace (the syntax and semantics of this element are described in <cite>XEP-0045</cite>).</p>
<example caption='Peerhost Requests Room History'><![CDATA[
<iq to='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net'
id='history1'
from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com'
type='get'>
<room xmlns='urn:xmpp:dmuc:0'
id='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39'>
<history xmlns='http://jabber.org/protocol/muc'/>
</room>
</iq>
]]></example>
<p>The history request MAY include any of the attributes specified in <cite>XEP-0045:</cite>: 'maxchars', 'maxstanzas', 'seconds', and 'since'.</p>
<example caption='Firsthost Sends Room History to Peerhost'><![CDATA[
<iq from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com'
id='history1'
to='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net'
type='result'/>
<history xmlns='http://jabber.org/protocol/muc'>
<message
xmlns='jabber:client'
from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com/foo'
type='groupchat'>
<body>Message 1.</body>
<delay xmlns='urn:xmpp:delay'
from='scott@example.com/desktop'
stamp='2002-10-13T23:58:37Z'/>
</message>
<message
xmlns='jabber:client'
from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com/bar'
type='groupchat'>
<body>Message 2.</body>
<delay xmlns='urn:xmpp:delay'
from='boyd@example.com/laptop'
stamp='2002-10-13T23:58:43Z'/>
</message>
<message
xmlns='jabber:client'
from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com/baz'
type='groupchat'>
<body>Message 3.</body>
<delay xmlns='urn:xmpp:delay'
from='lorraine@example.com/pda'
stamp='2002-10-13T23:58:49Z'/>
</message>
</history>
</iq>
]]></example>
<example caption='Peerhost Acknowledges Receipt of Room History'><![CDATA[
<iq to='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net'
id='history1'
from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com'
type='result'/>
]]></example>
<p>The firsthost also informs other connected peerhosts about the new peerhost.</p>
<example caption='Firsthost Reports New Peerhost'><![CDATA[
<iq from='firsthost.example.com'
id='ph1'
to='peer2.example.org'
type='set'>
<peerhost xmlns='urn:xmpp:dmuc:0'>
<room id='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39'/>
</peerhost>
</iq>
]]></example>
<example caption='Peerhost Acknowledges Notification of New Peerhost'><![CDATA[
<iq from='peer2.example.org'
id='ph1'
to='firsthost.example.com'
type='result'/>
]]></example>
</section2>
<section2 topic='Joining a Room' anchor='join'>
<p>When a user attempts to join a source room, the firsthost determines if it will invite the user to join a shadow at a peerhost instead. The process for determining when to send invitations is implementation specific and might be subject to configuration at the firsthost (e.g., the firsthost might send invitations only to users of a domain associated with the peerhost and only after a certain number of such users have joined the room at the firsthost).</p>
<p>To begin, a user at the peerhost attempts to join the source room at the firsthost:</p>
<example caption='User Seeks to Join Source Room'><![CDATA[
<presence
from='mike@example.net/office'
to='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com/krutsch'>
<x xmlns='http://jabber.org/protocol/muc'/>
</presence>
]]></example>
<p>The source room returns a &lt;redirect/&gt; presence error to the user and invites the user to join a shadow room instead.</p>
<example caption='Source Informs User of a Shadow'><![CDATA[
<presence
from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com/baz'
to='mike@example.net/office'
type='error'>
<error type='cancel'>
<redirect xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>peer1.example.net</redirect>
</error>
</presence>
]]></example>
<p>Then the source invites the user to the shadow using the protocol defined in &xep0249;.</p>
<example caption='Source Invites User to a Shadow'><![CDATA[
<message
from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com'
to='mike@example.net/office'
<x xmlns='jabber:x:conference'
jid='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net'/>
</message>
]]></example>
<p>The user then joins the shadow.</p>
<example caption='User Joins Shadow'><![CDATA[
<presence
from='mike@example.net/office'
to='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net/krutsch'>
<x xmlns='http://jabber.org/protocol/muc'/>
</presence>
]]></example>
<p>The shadow then informs the source (and any other shadows) of the user's presence; it does so by sending presence from the roomjid of the user at the shadow to a roomjid with the same roomnick at the source and shadow(s).</p>
<example caption='Shadow Informs Source of New Occupant'><![CDATA[
<presence
from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net/krutsch'
to='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com/krutsch'>
<x xmlns='http://jabber.org/protocol/muc#user'>
<item affiliation='none' role='participant'/>
</x>
</presence>
]]></example>
<p>The source then delivers that presence stanza to its local users. (Note: The shadow needs to send only one presence stanza to the source, thus reducing the number of stanzas sent over the server-to-server link between the peerhost and the firsthost.)</p>
</section2>
<section2 topic='Sending a Message' anchor='send'>
<p>When a user sends a message to an instance, the instance sends the message to its local occupants and to other instances.</p>
<example caption='User Sends Message'><![CDATA[
<message
from='mike@example.net/office'
to='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net'
type='groupchat'>
<body>Message 4.</body>
</message>
]]></example>
<example caption='Instance Distributes Message'><![CDATA[
<message
from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net/krutsch'
to='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer2.example.org/krutsch'
type='groupchat'>
<body>Message 4.</body>
</message>
<message
from='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@peer1.example.net/krutsch'
to='f609923deb78718a125b93d32609bd5265dd927242ac93a99eb366109df2bd39@firsthost.example.com/krutsch'
type='groupchat'>
<body>Message 4.</body>
</message>
]]></example>
<p>The source then delivers that message stanza to its local users. (Note: The shadow needs to send only one message stanza to the source, thus reducing the number of stanzas sent over the server-to-server link between the peerhost and the firsthost.)</p>
</section2>
<section2 topic='sync' anchor='Re-Syncing after Connectivity Loss'>
<p>To follow.</p>
</section2>
</section1>
<section1 topic='Determining Support' anchor='support'>
<p>If a MUC service supports distributed rooms, it MUST return a feature of "urn:xmpp:dmuc:0" &NSVER; in response to &xep0030; information requests.</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='reg'>
<p>This document requires no interaction with the &REGISTRAR;.</p>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Jay Carlson, Boyd Fletcher, and Michael Krutsch for their early conversations regarding distributed chatrooms.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>To follow.</p>
</section1>
</xep>

328
inbox/dna.xml Executable file
View File

@ -0,0 +1,328 @@
<?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>Domain Name Assertions</title>
<abstract>An application-level approach to asserting and proving the delegated ownership of a domain name for server-to-server XMPP federation.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>RFC 3920</spec>
<spec>RFC 3281</spec>
</dependencies>
<supersedes>
<spec>XEP-0220</spec>
<spec>XEP-0238</spec>
</supersedes>
<supersededby/>
<shortname>dna</shortname>
<author>
<firstname>Joe</firstname>
<surname>Hildebrand</surname>
<email>jhildebrand@jabber.com</email>
<jid>jhildebrand@cor.jabber.com</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2009-07-27</date>
<initials>jjh</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>As large hosting providers begin providing XMPP services for multiple domains, several issues with previous mechanisms for server-to-server federation have become apparent.</p>
<p>A large number of sockets are currently required between hosting providers. Although servers MAY attempt to piggyback whenever possible, the possibility exists that 2*N*M sockets will be created (where N is the number of domains on one hosting provider, and M is the number of domains on another hosting provider). The goal would be that the number of sockets was dependent on load or deployment considerations.</p>
<p>In order to enable or require encryption, the hosting provider needs to create a separate socket for each hostname pair and have access to a X.509 certificate that is signed by a widely-trusted CA and includes both the public and private keys. Customers of hosting providers might be uncomfortable with the level of trust this requires.</p>
<p>This document describes an approach known as Domain Name Assertions (DNA) that allows providers to effectively host XMPP services on behalf of other companies, and might be expanded later to support other protocols.</p>
</section1>
<section1 topic='Glossary' anchor='glossary'>
<dl>
<di>
<dt>Hosted domain</dt>
<dd>An XMPP domain whose network services are delegated to a third party.</dd>
</di>
<di>
<dt>Hosting provider</dt>
<dd>A business entity that provides services for one or more domains that it does not directly and fully control.</dd>
</di>
<di>
<dt>Self-hosted domain</dt>
<dd>A domain whose owner acts as its hosting provider.</dd>
</di>
<di>
<dt>Delegation</dt>
<dd>A ceremony that acts as proof of the intent of the owner of a hosted domain to cede control to a hosting provider for a given protocol.</dd>
</di>
<di>
<dt>Widely-trusted CA</dt>
<dd>For open communities, a Certificate Authority whose certificate that is trusted by multiple web browsers by default. For closed communities, a Certificate Authority that is trusted by all members of that community.</dd>
</di>
<di>
<dt>Sender Domain</dt>
<dd>The domain associated with the <strong>"from"</strong> address on a stanza to be sent across a federation boundary.</dd>
</di>
<di>
<dt>Target Domain</dt>
<dd>The domain associated with the <strong>"to"</strong> address on a stanza to be sent across a federation boundary.</dd>
</di>
<di>
<dt>Originating Server</dt>
<dd>The machine that wants to send a message from an entity at the Sender Domain to an entity at the Target Domain and thus is attempting to establish a connection between the two servers.</dd>
</di>
<di>
<dt>Receiving Server</dt>
<dd>The machine to which the Originating Server has opened a connection for the purpose of sending a message from the Sender Domain to the Target Domain.</dd>
</di>
<di>
<dt>Asserting Entity</dt>
<dd>A system element (such as a server) asserting a given domain name as an identity.</dd>
</di>
<di>
<dt>Validating Entity</dt>
<dd>A system element (such as a client or server) that checks a given identity asserted by an asserting entity.</dd>
</di>
<di>
<dt>Asserted Domain</dt>
<dd>A domain name asserted by either side of a conversation. Validating entities MAY require assertions to be backed up with proof.</dd>
</di>
<di>
<dt>Proof</dt>
<dd>A secure mechanism through which a validating entity can ascertain that an asserting entity has authority for the asserted domain, either directly or indirectly (by delegation).</dd>
</di>
</dl>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<ol>
<li>A hosting provider MUST be able to service domains for which it cannot obtain certificates signed by a widely-trusted CA.</li>
<li>All server-to-server (except for initial handshakes) MUST be encrypted in a manner not subject to man-in-the-middle attacks.</li>
<li>The number of socket connections between hosting providers MUST NOT be a function of the number of domains hosted by either provider.</li>
<li>Connections MUST be usable in either direction, if allowed by policy and deployment considerations.</li>
<li>The owners of the hosted domain MUST NOT be required to give out private keying material associated with any certificate they own that has been signed by a widely-trusted CA.</li>
<li>The owners of the hosted domain MUST be allowed to choose the frequency with which they wish to perform the delegation ceremony.</li>
<li>The owners of the hosted domain MUST be allowed to revoke their delegation at any time.</li>
<li>Multiple mechanisms for proving delegation MUST be possible.</li>
<li>It MUST be possible for new assertions to be added to a stream at any point after the stream is fully established, but before the stream is closed</li>
</ol>
</section1>
<section1 topic='Generic Use Cases' anchor='genericusecases'>
<p>The DNA mechanism can be used for multiple different protocols. In particular, client-to-server XMPP and server-to-server XMPP are discussed herein, but the general approach could be used for non-XMPP protocols such as SMTP. As such, the protocol syntax offered here is normative for XMPP, but merely illustrative for other protocols, which will need their own protocol bindings.</p>
<p>The following domain names are used in the examples:</p>
<dl>
<di>
<dt>asserted.tld</dt>
<dd>The domain name being asserted.</dd>
</di>
</dl>
<section2 topic='Assertions' anchor='assert'>
<p>The asserting entity asserts a domain name through the use of an assert element. Assertions MUST contain a <strong>"from"</strong> attribute naming the domain name that is being asserted.</p>
<example caption='Assertion'><![CDATA[<assert xmlns='urn:xmpp:dna:0' from='asserted.tld'/>
]]></example>
</section2>
<section2 topic='Validation' anchor='valid'>
<p>When the validating entity has been satisified that the asserting entity is authoritative for the domain name asserted, it MUST send a &lt;valid/&gt; element. At this point, the asserting entity can send stanzas to the validating entity containing <strong>"from"</strong> addresses in the asserted and validated domain.</p>
<p>Validating entities SHOULD respond to a domain name assertion without asking for further proof when the domain name asserted is represented in the certificate offered by the asserting entity according to the rules set out in &rfc3920bis;.</p>
<p>Validating entities MAY respond to a domain name assertion without asking for further proof when the domain name asserted is known to be associated with the asserting entity through some other secure means such as DNSSEC (&rfc4033;), caching, or local knowledge. In the DNSSEC case, the server hostname in the SRV record used to connect SHOULD be looked for in the certificate offered by the asserting entity, according to the rules set out in <strong>rfc3920bis</strong>.</p>
<example caption='Valid'><![CDATA[<valid xmlns='urn:xmpp:dna:0' to='asserted.tld'/>
]]></example>
</section2>
<section2 topic='Invalidation' anchor='invalid'>
<p>When the validating entity does not accept proof offered by the asserting entity, or it no longer trusts the proof (for example due to the proof timing out or being revoked), it sends the asserting entity an &lt;invalid/&gt; element. The asserting entity MUST NOT send any stanzas to the validating entity containing <strong>"from"</strong> addresses in the invalidated domain without performing another validation.</p>
<p>Invalid responses MAY be given in direct response to an assertion if the validating entity has reason to believe that no proof is possible. Examples that would cause this response include a blocking list or a negative cache.</p>
<example caption='Invalid proof'><![CDATA[<invalid xmlns='urn:xmpp:dna:0' to='asserted.tld'/>
]]></example>
</section2>
<section2 topic='Requesting proof with a challenge' anchor='challenge'>
<p>If an assertion cannot be validated immediately, the validating entity MAY ask for further proof. In the "prove-it" request, at least one form of proof that will be acceptable MUST be disclosed to the asserting entity.</p>
<p>A proof type MUST be a valid URI. A registry of proof types will be created. Standard proof types will begin with "urn:xmpp:dna:proof:". Custom proofs SHOULD be signaled with a type attribute value containing a full URI under the control of the defining party. Proof types MUST be compared for equality using the rules for URIs (see &rfc3986;).</p>
<p>Some proof types MAY require information or nonces from the validating entity. If so, the specification for that proof type MUST specify extensions to the proof element in a new namespace.</p>
<p>In some protocols, a challenge MAY be sent without an assertion, if the validating entity has reason to believe that the entity with which it is talking is authoritative for a given domain (for example, through a DNS lookup).</p>
<example caption='Prove your assertion, one of these ways'><![CDATA[<challenge xmlns='urn:xmpp:dna:0' to='asserted.tld'>
<proof type='urn:xmpp:dna:proof:attribute-cert'/>
<proof type='http://example.com/proof/custom'/>
</challenge>
]]></example>
</section2>
<section2 topic='No proof possible' anchor='impossible'>
<p>If the validating entity requires proof, but will not accept proof by a means that the asserting entity has available for the asserted domain, the asserting entity MUST respond with an &lt;impossible/&gt; element. The validating entity MUST NOT send a &lt;valid/&gt; or &lt;invalid/&gt; element in response, and MUST NOT accept stanzas from the asserted domain on this connection unless some other assertion works in the future.</p>
<p>The &lt;impossible/&gt; element MAY be sent after full validation, if the asserting entity would like to retract the assertion.</p>
<example caption='Impossible response'><![CDATA[<impossible xmlns='urn:xmpp:dna:0' from='asserted.tld'/>
]]></example>
</section2>
<section2 topic='Proving a challenge' anchor='proof'>
<p>If an asserting entity thinks it can prove a given assertion when challenged, it sends that proof in a &lt;proof/&gt; element. The REQUIRED 'type' attribute specifies the chosen proof type, and the REQUIRED 'from' attribute specifies the domain being proved. Each proof type MUST specify the format of the contents of the proof element. Suggestions for formats include base64-encoded binary as character data or structured XML in a new namespace.</p>
<example caption='Proof'><![CDATA[<proof xmlns='urn:xmpp:dna:0' from='asserted.tld' type='urn:xmpp:dna:proof:attribute-cert'>
(ascii-armored attribute certificate)
</proof>
]]></example>
</section2>
</section1>
<section1 topic='Attribute Certificate Proof' anchor='attribute-cert'>
<p><em>This section is preliminary.</em></p>
<p>When an asserting entity has been delegated responsibility for hosting a given domain, an Attribute Certificate (as specified in &rfc3281;) can be used to prove the delegation. The proof type URI associated with attribute certificates SHALL be 'urn:xmpp:dna:proof:attribute-cert' (EDITOR'S NOTE: let's come up with a new, good URN prefix for these. If we move this to an I-D, it should be an IETF URN.)</p>
<p>Each protocol that is delegated will be assigned its own OID for an attribute type. (EDITOR's NOTE: fill in OIDs for xmpp-server and xmpp-client delegation). The values associated with a given attribute are a list of references to hosting provider certificates, one of which MUST have been offered by the asserting entity and accepted by the validating entity (except for name) during the TLS certificate exchange. (EDITOR's NOTE: normative language required for the form of certificate references).</p>
<p>The certificate that signed the attribute certificate MUST have been acceptable as proof of ownership of a given domain for the protocol in question, according to the rules in <strong>rfc3920bis</strong>. Validating entities SHOULD try prepending the asserted domain with "www." and re-checking for name matches before rejecting the signing certificate, in order to allow for easier deployments using existing web certificates as proof.</p>
<p>The attribute certificate is encoded as PKCS12 (see <link url='http://www.rsa.com/rsalabs/node.asp?id=2138'>http://www.rsa.com/rsalabs/node.asp?id=2138</link>), including the signing certificate and all of the CA certificates in the trust chain of the signing certificate, back to a trust anchor. The certificate is then ascii-armored according to (?), and transmitted as the character data of a proof element.</p>
</section1>
<section1 topic='DNA for XMPP Federation' anchor='federation'>
<p>Two XMPP servers, each of which hosts multiple domains that they do not directly control, desire to connect in order to exchange traffic for at least two of those domains, one on either side (we call this a "dimain pair").</p>
<p>The following domain names are used in the examples:</p>
<dl>
<di>
<dt>target.tld</dt>
<dd>The domain portion of the JID in the <strong>"to"</strong> address of the stanza that caused this connection to be initiated.</dd>
</di>
<di>
<dt>othertarget.tld</dt>
<dd>The domain portion of the JID in the <strong>"to"</strong> address of a stanza being sent across a stream that was originally started to talk to target.tld.</dd>
</di>
<di>
<dt>targetprovider.tld</dt>
<dd>The hosting provider for target.tld.</dd>
</di>
<di>
<dt>server.targetprovider.tld</dt>
<dd>A server with XMPP federation services at the target's hosting provider.</dd>
</di>
<di>
<dt>originator.tld</dt>
<dd>The domain portion of the JID in the <strong>"from"</strong> address of the stanza that caused this connection to be initiated.</dd>
</di>
<di>
<dt>originatingprovider.tld</dt>
<dd>The hosting provider for target.tld.</dd>
</di>
<di>
<dt>server.originatingprovider.tld</dt>
<dd>A server with XMPP federation services at the originator's hosting provider.</dd>
</di>
</dl>
<section2 topic='DNS SRV lookups' anchor='dnssrv'>
<p>In a delegated hosting scenario, DNS SRV records are REQUIRED, since otherwise the hosting provider will never be contacted for the target domain. As specified by &rfc3920; the originating server looks up the target domain to find a list of receiving servers. If the originating server already has a connection to the IP address represented by one of these servers (perhaps because it is communicating with another domain hosted by this provider), it MAY reuse that stream (see Stream Reuse). If the originating server does not have a connection it wants to reuse, it performs the SRV algorithm to select an SRV record and makes a TCP connection to the server and port specified by the selected SRV record.</p>
<p>Unless assured by a mechanism such as DNSSEC, the originating server MUST NOT trust the information received from the DNS SRV as proof that the target domain has been delegated to the receiving server.</p>
<example caption='SRV lookup for target domain'><![CDATA[% dig +short -t SRV _xmpp-server._tcp.target.tld
0 1 5269 server.targetprovider.tld
]]></example>
</section2>
<section2 topic='Certificates during Start-TLS' anchor='tls'>
<p>The first step during stream negotiation MUST be Start-TLS. The receiving server MUST offer a certificate signed by a widely-trusted CA. The receiving server MUST require a client certificate. The certificate offered by the originating server MUST be signed be a widely-trusted CA. Each side MUST check the certificate offered to it for validity (e.g. time period, signatures, and trust anchor), but MUST NOT disconnect when the certificate received does not contain a name matching its expectations.</p>
<p>The names on these certificates SHOULD be associated with the relevant hosting provider, and need not be related to the domains being hosted. If the certificates have the name of the server offered in the SRV record, it MAY be possible to use DNSSEC for proof in the future.</p>
<example caption='Server certificate'><![CDATA[
CN=server.targetprovider.tld
]]></example>
<example caption='Client certificate'><![CDATA[
CN=server.originatingprovider.tld
]]></example>
</section2>
<section2 topic='Discovering Support' anchor='disco'>
<p>The <strong>"to"</strong> and <strong>"from"</strong> addresses are REQUIRED on the stream:stream tag. These represent the first domain pair associated with this stream, and are the domain names from the stanza that caused this connection to be established.</p>
<p>To announce its support for DNA, the receiving server asserts its identity in the stream features following TLS negotiation. </p>
<example caption='Domain name assertion in stream features'><![CDATA[<stream:features>
<assert xmlns='urn:xmpp:dna:0' from='target.tld'/>
</stream:features>
]]></example>
</section2>
<section2 topic='Turning on DNA' anchor='initiation'>
<p>If the originating server supports DNA, it looks for an assertion in the stream features. If it finds none, it MAY fall back on another means of verifying the identity of the target server, if allowed by local policy.</p>
<p>Originating servers that support DNA talking to target servers that declare support for DNA MUST NOT send protocol other than DNA negotations until they are able to validate the assertion offered by the target server in the stream features. The first validation proves to the originating server that it is talking to a server authoritative for the target domain, so that it is safe to use this domain in <strong>"to"</strong> addresses on this stream.</p>
<p>Once an originating server completes this first validation it signals that it is willing and able to participate in bi-directional XMPP federation traffic, as long as all of the domains required have been asserted and validated at least once on this stream.</p>
<p>If the originating server does not require more proof (due to a certificate match or DNSSEC-verified delegation), it MAY send a valid element without requesting proof first, as in all DNA interactions.</p>
<example caption='Originating server asks for proof, if required'><![CDATA[<challenge xmlns='urn:xmpp:dna:0' to='target.tld'>
<proof type='urn:xmpp:dna:proof:attribute-cert'/>
</challenge>
]]></example>
<example caption='Target server provides proof'><![CDATA[<proof xmlns='urn:xmpp:dna:0' from='target.tld' type='urn:xmpp:dna:proof:attribute-cert'>
(ascii-armored attribute certificate)
</proof>
]]></example>
<example caption='Originating server accepts proof, turns on DNA'><![CDATA[<valid xmlns='urn:xmpp:dna:0' to='target.tld'/>
]]></example>
</section2>
<section2 topic='Asserting new domains' anchor='origin'>
<p>Before either side sends stanzas on a given stream, it MUST ensure that the other side will accept those stanzas by asserting the domain in the <strong>"from"</strong> attribute of those stanzas, and waiting for a &lt;valid/&gt; response before sending the stanzas in question.</p>
<p>The originating server MUST therefore send its own assertion after accepting the target domain's assertion.</p>
<example caption=''><![CDATA[<assert xmlns='urn:xmpp:dna:0' from='originator.tld'/>
]]></example>
</section2>
<section2 topic='Proactive challenges' anchor='proactive-challenge'>
<p>Before either side sends stanzas on a given stream, it MUST ensure that the other side is authoritative for the domain in the <strong>"to"</strong> attribute on those stanzas. If the sender has already accepted an assertion on this stream, and that assertion has not been revoked with an &lt;impossible/&gt; element, no action is required. Otherwise, the sender can proactively request proof for that domain by sending a challenge even though the other side has not sent an assertion for that domain yet.</p>
<example caption='Proactive challenge'><![CDATA[<challenge xmlns='urn:xmpp:dna:0' to='othertarget.tld'>
<proof type='urn:xmpp:dna:proof:attribute-cert'/>
</challenge>
]]></example>
</section2>
<section2 topic='Proactive validation' anchor='proactive-validation'>
<p>When two hosting providers connect, they might have previous knowledge (perhaps from a cache) of which domains they will trust on the new connection. If so, either side MAY send as many &lt;valid/&gt; elements as desired, even though the other side has not sent assertions for those domains.</p>
<p>The server receiving these proactive validations MUST NOT change its self-image (i.e., the list of domains for which it is authoritative), but SHOULD NOT send assertions for these domains on this stream. If the server receiving a proactive validation is no long authoritative for a given domain, it MUST send an &lt;impossible/&gt; element, at which point the sender MUST remove the receiver from any cache and not send any stanzas on this stream to the given domain.</p>
<p>Any cache of DNA information SHOULD be associated with the certificate offerred by the relevant server, and SHOULD be checked for revocation if possible, according to local policy.</p>
<example caption='Proactive validations'><![CDATA[<valid xmlns='urn:xmpp:dna:0' to='target1.tld'/>
<valid xmlns='urn:xmpp:dna:0' to='target2.tld'/>
<valid xmlns='urn:xmpp:dna:0' to='target3.tld'/>
]]></example>
</section2>
<section2 topic='Reusing streams' anchor='reuse'>
<p>DNA streams are bi-directional, and might have an arbitrary number of domains validated in either direction, at any point in the lifetime of the stream. Before sending a stanza on a given stream, the sender MUST ensure that &lt;valid/&gt; elements have been exchanged according to the above rules for both the <strong>"to"</strong> and <strong>"from"</strong> address, and that no &lt;invalid/&gt; or &lt;impossible/&gt; element has revoked an assertion.</p>
<p>An &lt;impossible/&gt; or &lt;invalid/&gt; element SHOULD NOT cause the rest of the stream to become invalidated in either directions. When these elements are seen, they SHOULD merely change the list of domains that are valid on that stream. If no domains are valid on the stream, the stream MAY be closed immediately, or MAY be left open if desired. If left open, the stream MUST NOT be used for stanza traffic until domains are asserted as needed for the desired domains.</p>
<p>Domains that are marked as &lt;invalid/&gt; or &lt;impossible/&gt; SHOULD NOT be retried on the same stream unless new information has become available, in order to prevent assertion storms.</p>
</section2>
<section2 topic='Implementation notes' anchor='impl'>
<p>If the first server-to-server validation exchange fails, the parties MAY keep the connection open (perhaps for a shorter period than is usual) in case another domain pair would need a connection between these servers.</p>
<p>The parties SHOULD ensure that only one challenge is outstanding on a given connection for a given domain, and that only one assertion or one proof is outstanding on a given connection for a given domain.</p>
</section2>
</section1>
<section1 topic='DNA for XMPP client connections' anchor='clients'>
<p>Hosting providers have a similar problem for client-to-server connections. Clients need to ensure that they are talking to an authoritative server for the domain they intend to log in to. Typically, this is done by examining the certificate offered by the server during TLS negotiation, according to the rules in <strong>rfc3920bis</strong>. However, hosting providers will typically not have access to a valid certificate for the target domain and its associated private key. DNA can be used for the hosting provider to prove that hosting services have been delegated to it.</p>
<section2 topic='Announcing Support' anchor='announce'>
<p>To announce its support for DNA, the server asserts its identity in the stream features following TLS negotiation. The server MUST offer the identity of the domain specified in the client's stream header <strong>"to"</strong> attribute.</p>
<example caption='Server assertion'><![CDATA[<stream:features>
<assert xmlns='urn:xmpp:dna:0' from='target.tld'/>
</stream:features>
]]></example>
</section2>
<section2 topic='Client challenges for proof' anchor='clientchallenge'>
<p>To utilize the server's DNA assertion, the client performs Start-TLS per <strong>rfc3920bis</strong>, however, if the client does not find a name match on the offered certificate, it does not disconnect immediately. Instead, if the server offers an assertion, it can use the name from that assertion to ask the server for proof of delegation.</p>
<p>Subsequent protocol follows the generic use cases above, with the exception that alternate or additional domain names MUST NOT be asserted. If the server returns an &lt;impossible/&gt; element, the server MUST terminate the stream. If the client sends an &lt;invalid/&gt; element, the client MUST terminate the stream.</p>
<example caption='Client challenges for proof'><![CDATA[<challenge xmlns='urn:xmpp:dna:0' to='asserted.tld'>
<proof type='urn:xmpp:dna:proof:attribute-cert'/>
</challenge>
]]></example>
</section2>
</section1>
<section1 topic='Internationalization Considerations' anchor='i18n'>
<p>The domains offered are International Domain Names, as specified in <strong>rfc3920bis</strong>.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>For the urn:xmpp:dna:proof:attribute-cert proof type, the trust path for an assertion flows from two different trust anchors, one that proves the identity of the hosting provider, and another that proves the identity of the delegating party.</p>
<p>All proof types SHALL have a mechanism to limit the period of availability.</p>
<p>All proof types SHALL include a mechanism for revocation.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>A new registry of proof types will be required, which might be maintained by the &REGISTRAR; or by &IANA;. These proof types have URI syntax.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>To follow.</p>
</section1>
</xep>

536
inbox/dsig-design.xml Executable file
View File

@ -0,0 +1,536 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
<!ENTITY SIGNATURE "&lt;Signature/&gt;">
<!ENTITY REFERENCE "&lt;Reference/&gt;">
<!ENTITY SIGNEDINFO "&lt;SignedInfo/&gt;">
<!ENTITY KEYINFO "&lt;KeyInfo/&gt;">
<!ENTITY SIGNATUREPROPERTIES "&lt;SignatureProperties/&gt;">
<!ENTITY MANIFEST "&lt;Manifest/&gt;">
<!ENTITY XMPPprop "&lt;XMPPproperties/&gt;">
<!ENTITY SMIME "<span class='ref'><link url='http://tools.ietf.org/html/rfc3851'>S/MIME</link></span> <note>RFC 3851: Secure/Multipurpose Internet Mail Extensions (S/MIME) &lt;<link url='http://tools.ietf.org/html/rfc3851'>http://tools.ietf.org/html/rfc3851</link>&gt;.</note>" >
<!ENTITY CMS "<span class='ref'><link url='http://tools.ietf.org/html/rfc3852'>CMS</link></span> <note>RFC 3852: Cryptographic Message Syntax (CMS) &lt;<link url='http://tools.ietf.org/html/rfc3852'>http://tools.ietf.org/html/rfc3852</link>&gt;.</note>" >
<!ENTITY CDCIE "<span class='ref'><link url='http://www.jfcom.mil/about/facts_prt/MNIS.pdf'>CDCIE</link></span> <note>USFCOM fact sheet: Multinational Information Sharing and the Cross Domain Collaborative Information Environment &lt;<link url='http://www.jfcom.mil/about/facts_prt/MNIS.pdf'>http://www.jfcom.mil/about/facts_prt/MNIS.pdf</link>&gt;.</note>" >
<!ENTITY CDCIE-CCP "<span class='ref'>CDCIE-CCP</span> <note>Cross Domain Collaborative Information Environment (CDCIE) Chat Client Protocol Specification, Version 2.0, Trident Systems, Inc., 12 March 2008</note>" >
<!ENTITY XMLDSIG "<span class='ref'><link url='http://www.w3.org/TR/xmldsig-core/'>XMLDSIG</link></span> <note>XML Signature Syntax and Processing, W3C Recommendation, 10 June 2008 &lt;<link url='http://www.w3.org/TR/xmldsig-core/'>http://www.w3.org/TR/xmldsig-core/</link>&gt;.</note>" >
<!ENTITY XPointer "<span class='ref'><link url='http://www.w3.org/TR/xptr'>XPointer</link></span> <note>XML Pointer Language (XPointer), W3C Recommendation, 8 June 2001 &lt;<link url='http://www.w3.org/TR/xptr'>http://www.w3.org/TR/xptr</link>&gt;.</note>" >
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Design Considerations for Digital Signatures in XMPP</title>
<abstract>This document discusses considerations for the design of Digital Signatures in XMPP,
including use cases and requirements. The document also discusses various ways XML Digital
Signatures could be used in XMPP.</abstract> &LEGALNOTICE; <number>xxxx</number>
<status>ProtoXEP</status>
<type>Informational</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0001</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>xmpp-dsig-design</shortname> &kdz; <revision>
<version>0.0.090820</version>
<date>2009-08-20</date>
<initials>kdz</initials>
<remark>
<p>Proto-XEP draft.</p>
</remark>
</revision>
</header>
<section1 topic="Introduction" anchor="intro">
<p>Digital signatures may be used to provide a number of security services, including message
authentication, message integrity and non-repudiation. There are many use cases for Digital
Signatures in the Extensible Messaging and Presence Protocol (&xmpp;).</p>
<p>XMPP can be described as a mean for exchanging structured information or stanzas between two
or more entities. To accomplish this exchange, a number of other entities may be involved. For
instance, communication of a stanza between two client entities will typically involve one or
more server entities. Entities may exchange stanzas through service entities, such as a chat
room service, to effect one-to-many communications.</p>
<p>Any entity involved in the exchange of a stanza may have wish to include one or more digital
signatures for the benefit of any entity involved in the exchange:</p>
<ul>
<li>A client might wish to sign information it exchanges with another client for the benefit
of this client (e.g, to provide message origin authentication service and content integrity
service)</li>
<li>A client might wish to sign a message in order to bind a Security Label to that
message.</li>
<li>A client may wish to sign information it sends to a chat room for the benefit of the chat
room service and/or for the benefit of room occupants.</li>
<li>The chat room service may wish to sign information it forwards to room occupants for the
benefit of room occupants, such as to bind the client's JID to the client's room JID.</li>
<li>A server involved in the exchange of a stanza between two clients may wish to sign
information for the benefit of another server involved in the exchange (e.g., to provide
delivery path validation).</li>
<li>A server may wish to add additional data to a message, for example a Security Label, and
bind that data to the message with a digital signature.</li>
</ul>
<p>Digital signatures are provided to serve specific purposes. These purposes might include
authentication of a particular entity involved in the exchange and integrity of information
that entity provided.</p>
<p>This document discusses <link url="#design">considerations for the design</link> of
general-purpose digital signature extension for XMPP. The document discusses <link url="#uses"
>use cases</link> and <link url="#requires">requirements</link>, as well as explores the
solution space. The document also discusses <link url="#existing">existing solutions</link> in
this area.</p>
<p>This document contains a numerous examples intended to aide in the discussion of design
issues. The examples are examples generally abbreviated and often use informal syntaxes.</p>
</section1>
<section1 topic="Use Cases" anchor="uses">
<section2 topic="Use in directed one-to-one stanzas" anchor="direct-1to1-use">
<p>Directed one-to-one stanzas are stanzas which are exchanged between two entities, the
originator of the stanza and intended recipient of that stanza, without exchanging through
services which provide re-direction of stanzas (such as a groupchat service). The stanza may
be handled by one or more other entities.</p>
<p>Examples of directed one-to-one stanzas include chat &MESSAGE; used in one-to-one chat
sessions and &IQ; stanzas (excepting those exchanged through services providing <link
url="redirect-1to1-use">re-direction</link>).</p>
<p>The originator may wish to provide a signature for the benefit of the intended recipient.
The intended recipient could use this signature to authenticate the originator and to ensure
integrity of originator provided information.</p>
<p>Entities handling the stanza may wish to provide a signature for the benefit of the
intended recipient. For instance, where a originator is a client and does not provide a
signature, the client's server may wish to provide a signature for the benefit of the
intended recipient. The intended recipient could use this signature to authenticate this
server and to ensure integrity of the information as forwarded by this server. </p>
</section2>
<section2 topic="Use in redirected one-to-one stanzas" anchor="redirect-1to1-use">
<p>Redirected one-to-one stanzas which are exchanged between two entities, the originator of
the stanza and intended recipient of that stanza, through a service which provides
re-direction of stanzas. The stanza may be handled by one or more other entities. </p>
<p>A multi-user chat (MUC) 'private message' is an example of redirected one-to-one
stanza.</p>
<p>The originator's server may wish to provide a signature for the benefit of the re-direction
service. The service could use this signature to authenticate the originator and to ensure
integrity of originator provided information.</p>
<p>The originator may wish to provide a signature for the benefit of the intended recipient.
The intended recipient could use this signature to authenticate the originator and to ensure
integrity of originator provided information. However, this signature would by itself not
establish any relationship between the signer and 'from' address in the stanza as received,
nor does it establish this signature establish that the stanza was processed by the
re-direction service. As in the <link url="#direct-1to1-use">directed one-to-one
stanza</link>, a originating client's server may wish to provide a signature for the
benefit of the intended recipient.</p>
<p>The re-direction service may wish to provide a signature for the benefit of the intended
recipient. The intended recipient could use this signature to authenticate the service and
hence establish the service processed the stanza. The intended recipient could also use the
signature to ensure the integrity of the information as redirected by the service.</p>
</section2>
<section2 topic="Use in redirected one-to-group stanzas" anchor="redirect-1toG-use">
<p>Redirected one-to-many stanzas which are exchanged between two or more entities, the
originator of the stanza and a group of recipients, through a service which provides
re-direction of stanzas of a single stanza to a set of recipients. The stanza may be handled
by one or more other entities. </p>
<p>A multi-user chat (MUC) message to all occupants is an example of redirected one-to-group
stanza.</p>
<p>The originator's server may wish to provide a signature for the benefit of the re-direction
service. The service could use this signature to authenticate the originator and to ensure
integrity of originator provided information.</p>
<p>The originator may wish to provide a signature for the benefit of each recipient in the
group. Each recipient could use this signature to authenticate the originator and to ensure
integrity of originator provided information. However, this signature would by itself not
establish any relationship between the signer and the 'from' address in the stanza as
received, nor does it establish this signature establish that the stanza was processed by
the re-direction service. As in the <link url="#direct-1to1-use">directed one-to-one
stanza</link>, a originating client's server may wish to provide a signature for the
benefit of the each recipient.</p>
<p>The re-direction service may wish to provide a signature for the benefit of each recipient
in the group. Each recipient could use this signature to authenticate the service and hence
establish the service processed the stanza. Each could also use the signature to ensure the
integrity of the information as redirected by the service.</p>
</section2>
<section2 topic="Use in presence stanzas" anchor="presence-use">
<p>The presence can be viewed as a specialized "publish-subscribe" mechanism. Commonly the
publishing entity sends a &PRESENCE; stanza to a presence service and the presence
service than forwards the stanza to each subscriber. In basic user presence, the publishing
entity is the user's client and the presence service is presence service is the provided by
this client's server. In this case, the 'to' address is empty.</p>
<p>The publisher may wish to sign the signature for the benefit of each subscriber. Each
subscriber could use this signature to authenticate the publisher and to ensure integrity of
publisher provided information.</p>
<p>The presence service may wish to provide a signature for the benefit of each subscriber.
Each subscriber could use this signature to authenticate the service and hence establish the
service processed the stanza. Each could also use the signature to ensure the integrity of
the information as redirected by the service.</p>
<p>A presence stanza may also directed to another entity, possibly through a re-direction
service. This use is similar to the <link url="#direct-1to1-use">directed one-to-one</link>
and <link url="#redirect-1to1-use">redirected one-to-one</link> cases detailed above.</p>
</section2>
</section1>
<section1 topic="Requirements" anchor="requires">
<p>For the purposes of this memo, the following requirements are stipulated: </p>
<ol start="1">
<li>The extension shall support client signing of stanzas.</li>
<li>The extension shall support service (e.g., multi-user chat service) signing of
stanzas.</li>
<li>The extension shall support server signing stanzas.</li>
<li>The extension shall support multiple signatures in a stanza. That is, multiple entities
can sign a stanza.</li>
<li>The extension shall support signing of &IQ; stanzas.</li>
<li>The extension shall support signing of &MESSAGE; stanzas, including chat and
groupchat.</li>
<li>The extension shall support signing of &PRESENCE; stanzas.</li>
<li>The extension shall support selective signing of stanzas. That is, a signer can sign
select portions of a stanza.</li>
<li>The extension shall support signing of externally referenced object. That is, the
signature may include a message digest of an external object, such as an HTTP accessible
content.</li>
<li>The extension shall allow selective verification of signed elements. </li>
<li>The extension shall allow independent handling of verification errors in signed
content.</li>
<li>The extension shall allow signers to provide signed copies of data likely to be modified
by intermediate entities, such as stanza 'to' and 'from' attributes.</li>
<li>The extension should avoid duplication of content.</li>
<li>The extension must provide a means for relating signed content with unsigned content.</li>
<li>The extension should support querying for key information in XMPP (e.g., &IQ;).</li>
<li>The extension should support communicating key information through their XMPP-published
vCard.</li>
<li>The extension should be designed such that the successful verification of a signature is
independent of the extension support in entities involved in the exchange.</li>
</ol>
</section1>
<section1 topic="Existing Solutions" anchor="existing">
<section2 topic="XMPP E2E" anchor="xmpp-e2e">
<p>The &IETF; standardized a signing and encryption facility for XMPP known as
&xmppe2e;. XMPP E2E is based upon Secure/Multipurpose Internet Message Extensions
(&SMIME;) and the Cryptographic Message Syntax (&CMS;). As it's name implies, XMPP
E2E is intended to be an end-to-end solution. That is, it enables a sender to sign content
sent to a specific recipient.</p>
<p>An advantage of the XMPP E2E approach is that it uses an encapsulating signature which
protects the signed content from alteration as it is exchanged over an XMPP network. A
disadvantage is that implementations which do not support XMPP E2E cannot make use of the
signed content.</p>
<p>At the time of this writing, XMPP E2E has not been widely implemented. XMPP E2E appears to
have limited applicability. </p>
</section2>
<section2 topic="CDCIE-CCP" anchor="cdcie-ccp">
<p>Alternative approaches have been developed. For instance, the Cross Domain Collaborative
Information Environment (&CDCIE;) Client Chat Protocol (&CDCIE-CCP;), an XMPP-based
protocol, supports signing of XMPP stanzas utilizes XML digital signatures (&XMLDSIG;)
"enveloped" signatures over the whole stanza.</p>
<p>An advantage of the CDCIE-CCP approach is that, because it uses an encapsulated signature,
implementations need not support CDCIE-CPP to make use of the stanza. The disadvantage is
that the signature always over the entire stanza. Alteration of the stanza, as is common
(often required) when exchanging stanzas over an XMPP network, will invalidate the
signature.</p>
<p>While this approach has been implemented and deployed to some extent, the approach appears
to have applicability limited to the CDCIE.</p>
</section2>
</section1>
<section1 topic="Protocol Design Discussion" anchor="design">
<section2 topic="Encapsulated v. Encapsulating Signatures" anchor="encap">
<p>An encapsulating signature is a signature approach that encapsulates the signed content
within the signature syntax. An encapsulated signature is a signature approach where the
signature syntax in encapsulated within the structure of the signed content. XMPP E2E is an
example of the former. CDCIE-CCP is an example of the latter.</p>
<p>The following example illustrates, using pseudo language, an encapsulating signature over a
&MESSAGE; stanza.</p>
<example caption="Encapsulating Signature"><![CDATA[
<encapslating-signature>
<signedInfo>
<message to='romeo@example.net' type='chat'>
<body>Art thou not Romeo, and a Montague?</body>
</message>
</signedInfo>
<signature-over-signedInfo/>
</encapslating-signature>
]]></example>
<p>To transfer a signed &MESSAGE; using an encapsulating signature, one needs to send it
within &MESSAGE; stanza. </p>
<example caption="Transfer of an Encapsulating Signature"><![CDATA[
<message to='romeo@example.net' type='chat'>
<encapslating-signature>
<signedInfo>
<message to='romeo@example.net' type='chat'>
<body>Art thou not Romeo, and a Montague?</body>
</message>
</signedInfo>
<signature-over-signedInfo/>
</encapslating-signature>
</message>
]]></example>
<p>The following example illustrates, using pseudo language, an encapsulated signature over a
&MESSAGE; stanza. </p>
<example caption="Encapsulated Signature"><![CDATA[
<message to='romeo@example.net' type='chat'>
<body>Art thou not Romeo, and a Montague?</body>
<encapsulated-signature>
<signature-over-message/>
</encapsulated-signature>
</message>
]]></example>
<p>Applicability of a simple (non-nesting) encapsulating signatures, such as in XMPP E2E, are
generally limited to end-to-end use cases. That is, cases where the originator of a stanza
signs the stanza and send it through the XMPP network to its intended recipient, and only
the intended recipient is expected to make use of the signed content. Entities between the
signer and the intended recipient are expected to forward of the stanza without regard to
the encapsulating signature, and without themselves signing the stanza. The approach does
not require forwarding entities to support the signing extension.</p>
<p>Simple encapsulating signatures have limited applicability in MUC and PubSub use cases. For
instance, an occupant can sign its submissions to the service for the benefit of the service
and the service can sign reflected stanzas to occupants. In providing non-anonymous chat
rooms, in addition to signing the reflected content, the service should include and sign the
stanza it received when it was signed. This allows the occupants verify the content the
service purports to have received, and to determine whether the reflected content is
consistent given this. The following example illustrates an encapsulating signature over a
groupchat &MESSAGE; stanza.</p>
<example caption="MUC submission with Encapsulating Signature"><![CDATA[
<message from='hag66@shakespeare.lit/pda' to='darkcave@chat.shakespeare.lit'
type='groupchat' xml:lang='en'>
<encapslating-signature>
<signed-info>
<message
to='darkcave@chat.shakespeare.lit'
type='groupchat'
xml:lang='en'>
<body>Harpier cries: 'tis time, 'tis time.</body>
</message>
</signed-info>
<signature-value>...</signature-value>
</encapslating-signature>
</message>
]]></example>
<p>The following examples illustrates the signed reflection of the above stanza.</p>
<example caption="MUC reflection with Encapsulating Signature"><![CDATA[
<message from='darkcave@chat.shakespeare.lit/thirdwitch'
to='crone1@shakespeare.lit/desktop' type='groupchat' xml:lang='en'>
<encapslating-signature>
<signed-info>
<message
from='darkcave@chat.shakespeare.lit/thirdwitch'
to='crone1@shakespeare.lit/desktop' type='groupchat' xml:lang='en'>
<body>Harpier cries: 'tis time, 'tis time.</body>
</message>
<derived-from>
<message from='hag66@shakespeare.lit/pda'
to='darkcave@chat.shakespeare.lit' type='groupchat' xml:lang='en'>
<encapslating-signature>
<signedInfo>
<message to='darkcave@chat.shakespeare.lit'
type='groupchat' xml:lang='en'>
<body>Harpier cries: 'tis time, 'tis time.</body>
</message>
</signedInfo>
<signature/>
</encapslating-signature>
</message>
</derived-from>
</signed-info>
<signature-value>...</signature-value>
</encapslating-signature>
</message>
]]></example>
<p>In encapsulated signature solutions, as in CDCIE-CCP, any entities can make use of the
signed content even if they do not support the signing extension. If the signature is over
the entire stanza, as in CDCIE-CCP, the signature is likely not to be valid when the stanza
is passed through multiple entities prior to verification. Hence, when the signature is over
the entire stanza, the encapsulating signature approach applicability is generally limited
to cases where there no entities between the signer and verifier. However, as discussed
<link url="#stanza-siging">below</link>, encapsulated selective signatures are generally
more applicable.</p>
</section2>
<section2 topic="Selective Signing" anchor="select">
<p>While an entity could provide a signature to be over the entire stanza, such signatures are
likely be invalidated as the stanza exchanged over the XMPP. This is because XMPP allows
and, in many cases, requires stanza to be modified as they are forwarded.</p>
<p>For instance, a client with the JID "juliet@example.com/Balcony" might send the following
signed stanza:</p>
<example caption="Signature over entire stanza"><![CDATA[
<message to='romeo@example.net' type='chat' xml:lang='en'>
<subject>Love</subject>
<body>Art thou not Romeo, and a Montague?</body>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
...
<Reference URI="">
<Transforms>
<Transform
Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
</Transforms>
...
</Reference>
</SignedInfo>
<SignatureValue>...</SignatureValue>
...
</Signature>
</message>
]]></example>
<p>The example.com server is required, per &rfc3920;, to add a 'from' attribute to the
&MESSAGE; element before forwarding it to the example.net server. The example.net server
is required to replace the 'to' attribute with the full JID of the romeo@example.net client
it intends to forward the message to. These alternatations will "break" the signature.</p>
<p>XMLDSIG provides for a facility to selective sign XML content. For instance, the client
could sign the &SUBJECT; and &BODY; element and their content. However, this by
itself would not cover key aspects of the stanza, such that it was a chat &MESSAGE;
addressed to a particular JID and sent from a particular JID. XMLDSIG allows for enveloping
signatures, that is a signature that signs a data object contained within the
&SIGNATURE; element. The solution could define an element, such as &XMPPprop; used
below, for including properties of the stanza in the signature. </p>
</section2>
<section2 topic="Replay attack protection" anchor="replay">
<p>The signature in Example 1 does not provide any protection against replay attack. To
address replay attack, as well as other concerns, XMLDSIG defines the
&SIGNATUREPROPERTIES; element for including information items about the generation of
the Signature, such as the date/time the signature was generated. </p>
</section2>
<section2 topic="Manifest Signing" anchor="manifest">
<p>While one could have &SIGNATURE; which included a &REFERENCE; element for each of
four elements discussed above within its &SIGNEDINFO; element, this would require
reference validation for each &REFERENCE; (See 2.3 of XMLDSIG). To provide greater
flexibility over handling of absent references and broken digest values, a &MANIFEST;
can be constructed and only it signed.</p>
<p>Putting all of the above together, the client might send the following signed stanza:</p>
<example caption="Client signed message"><![CDATA[
<message to='romeo@example.net' type='chat' xml:lang='en'>
<subject id='X-subj'>Love</subject>
<body id='X-body'>Art thou not Romeo, and a Montague?</body>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#" Id="sig">
<SignedInfo>
...
<Reference URI="#X-manifest">...</Reference>
</SignedInfo>
<SignatureValue>...</SignatureValue>
<Object>
<Manifest id='X-manifest'>
<Reference URI="#X-subj">...</Reference>
<Reference URI="#X-body">...</Reference>
<Reference URI="#X-xmppprop">...</Reference>
<Reference URI="#X-sigprop">...</Reference>
</Manifest>
</Object>
<Object>
<XMPPprop id='X-xmppprop'>
<stanza>message</stanza>
<type>chat</type>
<from>juliet@example.com</from>
<to>romeo@example.net</to>
</XMPPStanza>
</Object>
<Object>
<SignatureProperties id="X-sigprop" Target="#X-sig">
<SignatureProperty Target="#timestamp">
<timestamp>2009-08-03T13:33:00Z</timestamp>
</SignatureProperty>
</SignatureProperties>
</Object>
</Signature>
</message>
]]></example>
</section2>
<section2 topic="Unambigious identification of content" anchor="id">
<p>The signature references needs to unambiguously identify content in stanza even in face of
subsequent modification of that stanza. Failure to unambiguously identify signed content
would also be problematic.</p>
<p>In the above example, signed child elements of the stanza were identified by 'id'
attribute. As stanzas may be forwarded into any XMPP stream, such identifiers needs to
remain unique.</p>
<p>Use of an extension attribute to identify elements may be problematic. In particular, the
XMPP specifications provide no assurance that this attribute would be forwarded with
element. While one could identify signed content by other means, such as &XPointer;,
these means would not unambiguously identify the signed content in the face of subsequent
stanza modification. </p>
<p>The an 'id' attribute is could be used (or possibly 'xml:id'), it may be appropriate for
the XMPP entity inserting a child element into a stanza to provide an 'xml:id' attribute
regardless of what stanza content it might sign.</p>
</section2>
<section2 topic="Multiple Signatures" anchor="multisig">
<p>Multiple entities can sign a stanza. A single entity may sign a stanza multiple times,
typically on different occasions.</p>
<p>Each signer simply adds their &SIGNATURE; element to the stanza, typically as the last
element. A &SIGNATURE; may sign other signatures, or portions thereof.</p>
<p>While a simple chat &MESSAGE; typically transits through only one or two XMPP servers
and a groupchat &MESSAGE; may typically transits one to three XMPP servers, a stanza
might include far more than four &SIGNATURE; elements.</p>
</section2>
<section2 topic="Dual content" anchor="dual">
<p>One possible signing solution is for stanzas to carry alternative sets of content, an
unsigned content alternative and a signed content alternative. An entity supporting the
signing extension could make use of the signed content alternative while an entity not
supporting the signing extension could make use of the unsigned content alternative. The
following example not only illustrate this approach, but a significant issue with this
approach:</p>
<example caption="Dual content message"><![CDATA[
<message from='hag66@shakespeare.lit/pda' to='darkcave@chat.shakespeare.lit/laptop'
type='groupchat' xml:lang='en'>
<body>No.</body>
<encapslating-signature>
<signed-info>
<message to='darkcave@chat.shakespeare.lit' type='groupchat' xml:lang='en'>
<body>Yes.</body>
</message>
</signed-info>
<signature-value>...</signature-value>
</encapslating-signature>
</message>
]]></example>
<p>Note that the &BODY; element values differ in the two alternatives.</p>
<p>An attacker could alter the unsigned content without alerting entities making use the
signed content.</p>
<p>Instead of treating the signed and unsigned content as alternatives, the solution could
limit use of the signed content to the validation of the unsigned data. However this
solution suffers from many same issues encapsulated signatures suffer from, as well as
suffering from unnecessary bloat.</p>
<p>Dual content approaches should be avoided.</p>
</section2>
<section2 topic="Key Info" anchor="key-info">
<p>While a signer may provide a &KEYINFO; element within the &SIGNATURE;, doing so
will significantly increase the size of the &SIGNATURE; element. As implementations may
enforce a maximum stanza size as small as 10,000 bytes, use of &KEYINFO; in stanza
signatures should be limited.</p>
<p>It is also noted there are cases where the signer may not want to expose the key
information to all entities involved in the exchange of stanza.</p>
<p>There are a number of ways key information may be published, such as in user's vCard. Key
information can also be provided at request, such as by &IQ;.</p>
</section2>
</section1>
<section1 topic="Security Considerations" anchor="seccon">
<p>Care must be taken in the design of not only ensure it provides an effective digital
signature solution for XMPP, but is designed itself with security in mind. This section
discussions some security issues in providing a digital signature solution. The design should
consider a general digital signature issues as well issues specific to the technologies
used/involved, and particulars of the solution.</p>
<p>Due to the nature of XML and XMPP, an effective general digital signing solution for XMPP is
likely to be quite complex. This document suggests nothing less. With complexity comes
significant security risk. To minimize this risk, the solutions should avoid reinvention of
needed technology, such as signature and key information syntaxes, by reusing well established
and understood technologies such as XMLDSIG. Solutions should also favor simple and widely
used features of such technologies over esoteric or rarely used features</p>
<p>Designers of the solution should be mind full of security considerations discussed in XMLDSIG
(regardless of whether XMLDSIG is used in the solution)</p>
<p>If XMLDSIG is used, a number of security considerations would be introduced into the
solution. Implementations need to take special care in processing XMLDSIG &SIGNATURE;
elements to avoid a wide range of attacks. For instance, an attacker could attempt to mount a
Denial of Service attack by sending a &SIGNATURE; purporting to sign arbitrary large and
complex content. Or an attacker could attempt to mount a Distributed Denial of Service sending
a message to a chatroom that containing &SIGNATURE; with multiple references to large
content hosted at the attack target in hopes that each room participant will repeated fetch
it. A &SIGNATURE; element might also contain circler references.</p>
</section1>
</xep>

313
inbox/dsig.xml Normal file
View File

@ -0,0 +1,313 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
<!ENTITY BASE64 "<span class='ref'><link url='http://tools.ietf.org/html/rfc4648'>BASE64</link></span> <note>RFC 4648: The Base16, Base32, and Base64 Data &lt;<link url='http://tools.ietf.org/html/rfc4648'>http://tools.ietf.org/html/rfc4648</link>&gt;.</note>" >
<!ENTITY DATETIME "<span class='ref'><link url='http://tools.ietf.org/html/rfc3339'>DATETIME</link></span> <note>RFC 3339: Date and Time on the Internet Timestamps &lt;<link url='http://tools.ietf.org/html/rfc3339'>http://tools.ietf.org/html/rfc3339</link>&gt;.</note>" >
<!ENTITY XMLDSIG "<span class='ref'><link url='http://www.w3.org/TR/xmldsig-core/'>XMLDSIG</link></span> <note>XML Signature Syntax and Processing, W3C Recommendation, 10 June 2008 &lt;<link url='http://www.w3.org/TR/xmldsig-core/'>http://www.w3.org/TR/xmldsig-core/</link>&gt;.</note>" >
<!ENTITY E2EEncrypt "<span class='ref'><link url='http://datatracker.ietf.org/doc/draft-miller-3923bis'>E2EEncrypt</link></span> <note>End-to-End Object Encryption for the Extensible Messaging and Presence Protocol (XMPP), Miller, M. and P. Saint-Andre, work in progress &lt;<link url='http://datatracker.ietf.org/doc/draft-miller-3923bis'>http://datatracker.ietf.org/doc/draft-miller-3923bis</link>&gt;.</note>" >
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Digital Signatures in XMPP</title>
<abstract>This document provides a technical specification for Digital Signatures in the
Extensible Messaging and Presence Protocol (XMPP).</abstract> &LEGALNOTICE;
<number>XXXX</number>
<status>Proto</status>
<type>Technical Specification</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0001</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>N/A</shortname> &kdz; <revision>
<version>0.0</version>
<date>2010-03-10</date>
<initials>kdz</initials>
<remark>
<p>Proto-XEP draft.</p>
</remark>
</revision>
</header>
<section1 topic="Introduction" anchor="intro">
<p>This document provides a technical specification for Digital Signatures in Extensible
Messaging and Presence Protocol (&xmpp;) based upon End-to-End Object Encryption
(&E2EEncrypt;) "work in progress".</p>
<p>The S/MIME approach defined in &rfc3923; has never been implemented in XMPP clients to the
best of our knowledge, but has some attractive features, especially the ability to
store-and-forward a signed message at a user's server if the user is not online when the
message is received (in the XMPP community this is called "offline storage" and the message is
referred to as an "offline message"). The authors surmise that RFC 3923 has not been
implemented mainly because it adds several new dependencies to XMPP clients, especially MIME
(along with the CPIM and MSGFMT media types). This document explores the possibility of an
approach that is similar to but simpler than RFC 3923.</p>
</section1>
<section1 topic="Signing XMPP Stanzas" anchor="stanza">
<p>The process that a sending agent follows for securing stanzas is very similar regardless of
the form of stanza (i.e., &lt;iq/&gt;, &lt;message/&gt;, or &lt;presence/&gt;).</p>
<ol>
<li>Constructs a cleartext version of the stanza, S.</li>
<li>Notes the current UTC date and time N when this stanza is constructed, formatted as
described in Section 5.</li>
<li>Converts the stanza to a UTF-8, as defined by &rfc3269;, encoded string, optionally
removing line breaks and other insignificant whitespace between elements and attributes,
i.e., UTF8-encode(S) = S'. We call S' a "stanza-string" because for purposes of signing and
verification it is treated not as XML but as an opaque string (this avoids the need for
complex canonicalization of the XML input).</li>
<li>Constructs a plaintext envelope (E) &lt;plain/&gt; qualified by the "urn:xmpp:signed:0"
namespace as follows: <ul>
<li>The attribute 'timestamp' set to the UTC date and time value N</li>
<li>The XML character data set to the base64-encoded form of S' (where the encoding
adheres to the definition in Section 4 of &BASE64; and where the padding bits are set to
zero). This encoding is necessary to preserve a canonicalized form of S'.</li>
</ul>
</li>
<li>Converts the envelope (E) to a UTF-8 encoded string, optionally removing line breaks and
other insignificant whitespace between elements and attributes, i.e., E' =
UTF8-encode(E).</li>
<li>Produce a signature of UTF8-encoded envelope (E') using the intended signature algorithm.
T = signature(E'). (This step is underspecified and will be expanded upon in later revision
of this document.)</li>
<li>Base64-encodes T to produce the signature data T'.</li>
<li>Constructs an &lt;signed/&gt; element qualified by the "urn:xmpp:signed:0" namespace as
follows: <ul>
<li>The child element &lt;signature&gt; (implicitly qualified by the "urn:xmpp:signed:0"
namespace) as follows: <ul>
<li>The attribute 'algorithm' set to a string identifying the signature algorithm
used.</li>
<li>The XML character data T'.</li>
</ul></li>
<li>The child element &lt;data&gt; (implicitly qualified by the "urn:xmpp:signed:0"
namespace) as follows: <ul>
<li>The XML character data E'.</li>
</ul>
</li>
</ul>
</li>
<li>Sends the &lt;signed&gt; element as the payload of a stanza that SHOULD match the stanza
from step 1 in kind (e.g., &lt;message/&gt;), type (e.g., "chat"), and addressing (e.g.
to="romeo@montague.net" from="juliet@capulet.net/balcony"). If the original stanza (S) has a
value for the "id" attribute, this stanza MUST NOT use the same value for its "id"
attribute.</li>
</ol>
<section2 topic="Example of Signing Messages" anchor="ex-message">
<p>The sender begins with the cleartext version of the &lt;message/&gt; stanza "S":</p>
<example><![CDATA[
<message xmlns='jabber:client'
from='juliet@capulet.net/balcony'
id='183ef129'
to='romeo@montague.net'
type='chat'>
<thread>8996aef0-061d-012d-347a-549a200771aa</thread>
<body>Wherefore art thou, Romeo?</body>
</message>
]]></example>
<p>The sender then performs the steps 1 through 4 from above to generate:</p>
<example><![CDATA[
<plain xmlns="urn:xmpp:signed:0"
timestamp="2010-06-29T02:15:21.012Z">
PG1lc3NhZ2UgeG1sbnM9ImphYmJlcjpjbGllbnQiIGZyb209Imp1bGlldEBjYXB
1bGV0Lm5ldC9iYWxjb255IiB0bz0icm9tZW9AbW9udGVndWUubmV0IiB0eXBlPS
JjaGF0Ij48dGhyZWFkPmM2MzczODI0LWEzMDctNDBkZC04ZmUwLWJhZDZlNzI5O
WFkMDwvdGhyZWFkPjxib2R5PldoZXJlZm9yZSBhcnQgdGhvdSwgUm9tZW8/PC9i
b2R5PjwvbWVzc2FnZT4=
</plain>
]]></example>
<p>And then performs steps 5 through 9 steps, causing the following to be sent:</p>
<example><![CDATA[
<message xmlns='jabber:client'
from='juliet@capulet.net/balcony'
id='6410ed123'
to='romeo@montague.net'
type='chat'>
<signed xmlns="urn:xmpp:signed:0">
<signature algorithm="RSA-SHA1">
DxbxIziY1C1Ytcxkj0IFLsfmDLMv96JMlMAQZ7jh49IbsOIPsxI2LyLmqhKH/994UXDJKQLHvLJz
gAmw8V2b+zmyZeItJzSmB+HHiLFVXkD2Dd4JfetsafsfIcB7uNWg0gAeiKrTHfFgiyEC/2WxwOj3
JUMRyQ9ykEPIzS0GZ/k=
</signature>
<data>
PHBsYWluIHhtbG5zPSJ1cm46eG1wcDpzaWduZWQ6MCIgdGltZXN0YW1wPSIyMDEwLTA2LTI5VDAy
OjE1OjIxLjAxMloiPgogIFBHMWxjM05oWjJVZ2VHMXNibk05SW1waFltSmxjanBqYkdsbGJuUWlJ
R1p5YjIwOUltcDFiR2xsZEVCallYQgogIDFiR1YwTG01bGRDOWlZV3hqYjI1NUlpQjBiejBpY205
dFpXOUFiVzl1ZEdWbmRXVXVibVYwSWlCMGVYQmxQUwogIEpqYUdGMElqNDhkR2h5WldGa1BtTTJN
emN6T0RJMExXRXpNRGN0TkRCa1pDMDRabVV3TFdKaFpEWmxOekk1TwogIFdGa01Ed3ZkR2h5WldG
a1BqeGliMlI1UGxkb1pYSmxabTl5WlNCaGNuUWdkR2h2ZFN3Z1VtOXRaVzgvUEM5aQogIGIyUjVQ
and2YldWemMyRm5aVDQ9CjwvcGxhaW4+Cg==
</data>
</signed>
</message>
]]></example>
</section2>
<section2 topic="Example of Securing IQs" anchor="ex-iq">
<p>To be added....</p>
</section2>
</section1>
<section1 topic="Interaction with Stanza Semantics" anchor="interact">
<p>The following limitations and caveats apply:</p>
<ul>
<li>Undirected &lt;presence/&gt; stanzas SHOULD NOT be signed.</li>
<li>Stanzas directed to multiplexing services (e.g. multi-user chat) SHOULD NOT be signed,
unless the sender has established the service supports the handling of signed stanzas.</li>
</ul>
</section1>
<section1 topic="Handling of Inbound Stanzas" anchor="inbound">
<p>Several scenarios are possible when an entity receives an encrypted stanza:</p>
<dl>
<di>
<dt>Case #1:</dt>
<dd>The receiving application does not understand the protocol.</dd>
</di>
<di>
<dt>Case #2:</dt>
<dd>The receiving application understands the protocol and is able to verify the
signature.</dd>
</di>
<di>
<dt>Case #3:</dt>
<dd>The receiving application understands the protocol and is able to verify the signature,
but the timestamps fail the checks specified under Checking of Timestamps.</dd>
</di>
<di>
<dt>Case #4:</dt>
<dd>The receiving application understands the protocol and is unable to verify the
signature.</dd>
</di>
</dl>
<p>In Case #1, the receiving application MUST do one and only one of the following: (1) ignore
the &lt;signed/&gt; extension, (2) ignore the entire stanza, or (3), except where precluded by
the protocol (&rfc3920bis;), return a &lt;service-unavailable/&gt; error to the sender.</p>
<p>In Case #2, the receiving application MUST NOT return a stanza error to the sender, since
this is the success case.</p>
<p>In Case #3, the receiving application MAY, except where precluded by the protocol, return a
&lt;not-acceptable/&gt; error to the sender, optionally supplemented by an
application-specific error condition element of &lt;bad-timestamp/&gt; as shown below:</p>
<example><![CDATA[
<message from='romeo@example.net/orchard'
id='6410ed123'
to='juliet@capulet.net/balcony'
type='error'>
<signed xmlns='urn:xmpp:signed:0'>
XML-character-data-here
</signed>
<error type='modify'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<bad-timestamp xmlns='urn:xmpp:signed:0'/>
</error>
</message>
]]></example>
<p>In Case #4, the receiving application SHOULD, except as precluded by the protocol, return a
&lt;bad-request/&gt; error to the sender, optionally supplemented by an application-specific
error condition element of &lt;bad-signature/&gt; as shown below:</p>
<example><![CDATA[
<message from='romeo@example.net/orchard'
id='6410ed123'
to='juliet@capulet.net/balcony'
type='error'>
<e2e xmlns='urn:xmpp:signed:0'>
XML-character-data-here
</e2e>
<error type='modify'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<bad-signature xmlns='urn:ietf:params:xml:xmpp-signed:0'/>
</error>
</message>
]]></example>
<p>Additionally in Case #4, the receiving application SHOULD NOT present the stanza to the
intended recipient (human or application) and SHOULD provide some explicit alternate
processing of the stanza (which may be to display a message informing the recipient that it
has received a stanza that cannot be verified).</p>
</section1>
<section1 topic="Inclusion and Checking of Timestamps" anchor="timestamps">
<p>Timestamps are included to help prevent replay attacks. All timestamps MUST conform to
&DATETIME; and be presented as UTC with no offset, always including the seconds and fractions
of a second to three digits (resulting in a datetime 24 characters in length). Absent a local
adjustment to the sending agent's perceived time or the underlying clock time, the sending
agent MUST ensure that the timestamps it sends to the receiver increase monotonically (if
necessary by incrementing the seconds fraction in the timestamp if the clock returns the same
time for multiple requests). The following rules apply to the receiving application:</p>
<ul style="symbols">
<li>It MUST verify that the timestamp received is within five minutes of the current time,
except as described below for offline messages.</li>
<li>If the foregoing check fails, the timestamp SHOULD be presented to the receiving entity
(human or application) marked with descriptive text indicating "old timestamp" or "future
timestamp" and the receiving entity MAY return a stanza error to the sender (except as
precluded in the protocol).</li>
</ul>
<p>The foregoing timestamp checks assume that the recipient is online when the message is
received. However, if the recipient is offline then the server will probably store the message
for delivery when the recipient is next online (offline storage does not apply to &lt;iq/&gt;
or &lt;presence/&gt; stanzas, only &lt;message/&gt; stanzas). As described in &xep0160;, when
sending an offline message to the recipient, the server SHOULD include delayed delivery data
as specified in &xep0203; so that the recipient knows that this is an offline message and also
knows the original time of receipt at the server. In this case, the recipient SHOULD verify
that the timestamp received in the encrypted message is within five minutes of the time
stamped by the recipient's server in the &lt;delay/&gt; element.</p>
</section1>
<section1 topic="Mandatory-to-Implement Cryptographic Algorithms" anchor="mti">
<p>All implementations MUST support the following algorithms. Implementations MAY support other
algorithms as well.</p>
<ul>
<li>TBD (RSA/SHA1? RSASSA-RKCS1-v1_5? RSASSA-PSS?)</li>
</ul>
</section1>
<section1 topic="Certificates" anchor="certs">
<p>To participate in end-to-end signing using the methods defined in this document, a client
needs to possess an X.509 certificate. It is expected that many clients will generate their
own (self-signed) certificates rather than obtain a certificate issued by a certification
authority (CA). In any case the certificate MUST include an XMPP address that is represented
using the ASN.1 Object Identifier "id-on-xmppAddr" as specified in Section 5.1.1 of
RFC 3920bis.</p>
</section1>
<section1 topic="Security Considerations" anchor="security">
<p>TBD.</p>
</section1>
<section1 topic="XMPP Registrar Considerations" anchor="reg">
<section2 topic="XML Namespace Name for Signed Data in XMPP" anchor="ns">
<p>A URN sub-namespace of signed content for the Extensible Messaging and Presence Protocol
(XMPP) is defined as follows.</p>
<dl>
<di>
<dt>URI:</dt>
<dd>urn:xmpp:signed</dd>
</di>
<di>
<dt>Specification:</dt>
<dd>ProtoXEP</dd>
</di>
<di>
<dt>Description:</dt>
<dd>This is an XML namespace name of signed content for the Extensible Messaging and
Presence Protocol as defined by ProtoXEP.</dd>
</di>
<di>
<dt>Registrant Contact:</dt>
<dd>XSF</dd>
</di>
</dl>
</section2>
</section1>
<section1 topic="Acknowledgements" anchor="ack">
<p>This document borrows ideas and text from End-to-End Object Encryption "work in progress" by
Matthew Miller and Peter Saint-Andre.</p>
</section1>
</xep>

141
inbox/forwarding-delivery.xml Executable file
View File

@ -0,0 +1,141 @@
<?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>Stanza Forwarding</title>
<abstract>This specification defines best practices for delivery of XMPP stanzas that are forwarded from one address to another.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>forwarding</shortname>
&stpeter;
<revision>
<version>0.0.5</version>
<date>2009-04-10</date>
<initials>psa</initials>
<remark><p>Changed service discovery feature to urn:xmpp:forwarding:0 in compliance with XMPP Registrar processes.</p></remark>
</revision>
<revision>
<version>0.0.4</version>
<date>2006-03-13</date>
<initials>psa</initials>
<remark><p>Specified that from address of forwarded stanza must be JID of forwarding address (not server).</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2006-01-24</date>
<initials>psa</initials>
<remark><p>Split forwarding semantics and forwarding request process into separate specifications; defined security considerations.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2005-04-08</date>
<initials>psa</initials>
<remark><p>Added confirmation protocol flow.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2005-03-03</date>
<initials>psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>The concept of communications forwarding is familiar from email and, before that, from postal mail: communications sent to one address are automatically re-directed to another address. Such forwarding can help make communications smoother when, for instance, people or applications move to new locations. In postal mail systems, such functionality is usually implemented by the entity responsible for delivery of communications within the locality of the original address (e.g., a local post office), as initiated by the person or organization that requires the change of address. The model is similar in electronic mail systems, often implemented by means of a .forward file.</p>
<p>This document specifies syntax and semantics for delivery of forwarding stanzas in XMPP systems. A companion document defines a method for setting up forwarding at a server.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>This proposal addresses the following requirements:</p>
<ol start="1">
<li>Define syntax and semantics for stanza forwarding.</li>
<li>Prevent infinite forwarding loops.</li>
</ol>
</section1>
<section1 topic='Protocol' anchor='protocol'>
<p>Before stanzas can be forwarded, forwarding needs to be established from an old address to a new address. Methods for doing so are out of scope for this specification.</p>
<p>Once forwarding is established, the server MUST redirect all stanzas sent to the old address (including any resource thereof) to the new address.</p>
<example caption="A sender communicates with a forwarded address"><![CDATA[
<message from='entity@example.org/resource' to='oldaccount@example.com'>
<body>Hi!</body>
</message>
]]></example>
<p>Before the server forwards the stanza, it MUST add a NumForwards &xep0131; header to the stanza (whose character data is the number "1") if there is no such header already included in the stanza, or if the stanza already includes such a header it MUST increment the value of the NumForwards header by 1 and include the revised NumForwards header in the stanza. (Inclusion and incrementing of the NumForwards header helps to prevent infinite forwarding loops; see the <link url="#security">Security Considerations</link>.)</p>
<p>In addition, the server MUST include 'oto' and 'ofrom' &xep0033; addresses so that the final recipient can determine the provenance of the stanza.</p>
<example caption="Server forwards stanza"><![CDATA[
<message from='oldaccount@example.com' to='newaccount@example.net'>
<body>Hi!</body>
<headers xmlns='http://jabber.org/protocol/shim'>
<header name='NumForwards'>1</header>
</headers>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='oto' jid='oldaccount@example.com'/>
<address type='ofrom' jid='entity@example.org/resource'/>
</addresses>
</message>
]]></example>
<p class='box'>Note: The 'oto' and 'ofrom' address types are not yet specified in the <cite>Extended Stanza Addressing</cite> specification; they will be added if this document advances to a status of Draft within the standards process of the &XSF;.</p>
</section1>
<section1 topic='Determining Support' anchor='support'>
<p>If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:forwarding:1" in response to &xep0030; information requests &NSNOTE;.</p>
<example caption="Service discovery information request"><![CDATA[
<iq type='get'
to='example.com'
from='oldaccount@example.com'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption="Service discovery information response"><![CDATA[
<iq type='result'
from='example.com'
to='oldaccount@example.com'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='http://jabber.org/protocol/forwarding'/>
</query>
</iq>
]]></example>
<p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>Deployment of stanza forwarding introduces the possibility of a denial of service attack if infinite loops occur; therefore, a server that implements stanza forwarding MUST also implement checking and incrementing of the NumForwards header. In particular, a server MUST be configured with a reasonable default limit for the maximum number of acceptable forwards (e.g., 10), which MAY be further configurable by the server administrator but which MUST NOT be removable (or changeable to an unreasonable value).</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This specification requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Service Discovery Features' anchor='registrar-disco'>
<p>The &REGISTRAR; shall include 'urn:xmpp:forwarding' in its registry of service discovery features.</p>
</section2>
<section2 topic='SHIM Headers' anchor='registrar-shim'>
<p>The XMPP Registrar shall include the following entry in its registry of SHIM headers.</p>
<code><![CDATA[
<header>
<name>NumForwards</name>
<desc>The number of times a stanza has been forwarded (must be a positive integer).</desc>
<doc>XEP-xxxx</doc>
</header>
]]></code>
</section2>
</section1>
</xep>

206
inbox/incident-reporting.xml Executable file
View File

@ -0,0 +1,206 @@
<?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>Incident Reporting</title>
<abstract>This specification defines methods for incident reporting among XMPP server deployments.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
<discuss>operators</discuss>
<author>
<firstname>Artur</firstname>
<surname>Hefczyc</surname>
<email>artur.hefczyc@gmail.com</email>
<jid>artur.hefczyc@tigase.org</jid>
</author>
<author>
<firstname>Florian</firstname>
<surname>Jensen</surname>
<email>admin@flosoft.biz</email>
<jid>admin@im.flosoft.biz</jid>
</author>
<author>
<firstname>Mickaël</firstname>
<surname>Rémond</surname>
<email>mickael.remond@process-one.net</email>
<jid>mremond@process-one.net</jid>
</author>
&stpeter;
<author>
<firstname>Matthew</firstname>
<surname>Wild</surname>
<email>mwild1@gmail.com</email>
<jid>mwild1@jaim.at</jid>
</author>
<revision>
<version>0.0.3</version>
<date>2009-04-30</date>
<initials>psa</initials>
<remark><p>Per Council feedback, moved server rosters to a separate specification.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2009-04-27</date>
<initials>psa/fj</initials>
<remark><p>Refactored XML format; added elements for sub-categories, locations, related incidents, solutions, and suggestions.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2009-04-13</date>
<initials>ah/fj/psa/mr/mw</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>As XMPP technologies have been deployed more widely, the open XMPP network has become a more significant target for attacks. This specification defines ways for XMPP server deployments to share information with each other and therefore handle such attacks in a more real-time fashion. In particular, it defines a format for sharing incident reports among XMPP server deployments. (For some related considerations, see &rfc2350;, &rfc3067;, and &rfc5070;.)</p>
</section1>
<section1 topic='Incident Reports' anchor='reports'>
<p>An incident report consists of an XMPP &MESSAGE; stanza containing an &lt;incident/&gt; child element that includes an 'id' attribute whose value is a UUID as described in &rfc4122;. An example is shown below. A server deployment SHOULD send incident reports only to peer servers that it trusts, for example peers that are in its "server roster".</p>
<example caption="An incident report"><![CDATA[
<message from='jabber.org' to='im.flosoft.biz'>
<incident xmlns='urn:xmpp:incident:0'
id='BA51A035-7710-4558-9BBF-34838A4C5B24'>
<description>
<discuss>
<admin>stpeter@jabber.org</admin>
<muc>operators@conference.jabber.org</muc>
</discuss>
<info>
<category>muc</category>
<type>presence</type>
<type>long-messages</type>
</info>
<locs>
<loc>jdev@conference.jabber.org</loc>
<loc>jabber@conference.jabber.org</loc>
</locs>
<rels>
<rel>133BCE2E-E669-4ECE-B0F8-766B9E65630D</rel>
</rels>
<severity>2</severity>
<source>
<ips>
<ip>192.0.2.1</ip>
</ips>
<jids>
<jid>abuser@abuse.lit</jid>
<jid>loser@abuse.lit</jid>
</jids>
</source>
<text xml:lang='en'>lots of MUC spammers from abuse.lit!</text>
<time>
<begin>2009-04-13T19:05:20Z</begin>
<end>2009-04-13T19:27:22Z</end>
<report>2009-04-13T19:31:07Z</report>
</time>
</description>
</incident>
</message>
]]></example>
<p>The defined children of the &lt;description/&gt; element are as follows:</p>
<table caption='&lt;description/&gt; children'>
<tr>
<th>Element Name</th>
<th>Description</th>
</tr>
<tr>
<td>&lt;discuss/&gt;</td>
<td>This element contains the JID of the server admin who generated the incident report (&lt;admin/&gt;), as well as a &xep0045; room where the incident can be discussed (&lt;muc/&gt;).</td>
</tr>
<tr>
<td>&lt;info/&gt;</td>
<td>Structured information about the incident. The defined values of the &lt;category/&gt; and &lt;type/&gt; elements shall be provided via a registry. It is envisioned that the &lt;category/&gt; values shall be "muc" for &xep0045; incidents, "pubsub" for &xep0060; incidents, "reg" for account registration (&xep0077;) incidents, and "stanzas" for general XMPP traffic incidents.</td>
</tr>
<tr>
<td>&lt;locs/&gt;</td>
<td>The place or places on the XMPP network where the incident has occurred (such as a multi-user chat room, a publish-subscribe service, or a general XMPP server), each contained in a separate &lt;loc/&gt; element.</td>
</tr>
<tr>
<td>&lt;rels/&gt;</td>
<td>The IDs of one or more incidents to which this incident might be related, each contained in a separate &lt;rel/&gt; element.</td>
</tr>
<tr>
<td>&lt;severity/&gt;</td>
<td>The seriousness of the problem, from 5 (least serious) to 1 (most serious).</td>
</tr>
<tr>
<td>&lt;source/&gt;</td>
<td>The IP address(es) and JabberID(s) where the incident originated.</td>
</tr>
<tr>
<td>&lt;text/&gt;</td>
<td>A natural-language description of the event. This element SHOULD possess an 'xml:lang' attribute. Multiple &lt;text/&gt; elements MAY be included, each with a different 'xml:lang' value.</td>
</tr>
<tr>
<td>&lt;time/&gt;</td>
<td>The time when the incident began and ended (include an empty &lt;end/&gt; element if the incident is still happening) and, optionally, was reported. The dates MUST conform to the DateTime profile specified in &xep0082;</td>
</tr>
</table>
</section1>
<section1 topic='Incident Solutions' anchor='solutions'>
<p>If the reporting entity determines a solution to the problem, it MAY send out a revised incident report containing a &lt;solution/&gt; element.</p>
<example caption="An incident solution"><![CDATA[
<message from='jabber.org' to='im.flosoft.biz'>
<incident xmlns='urn:xmpp:incident:0'
id='BA51A035-7710-4558-9BBF-34838A4C5B24'>
<description>
...
</description>
<solution>
<text xml:lang='en'>banned the offenders</text>
</solution>
</incident>
</message>
]]></example>
<p>Further definition of the &lt;solution/&gt; element will be provided in a future version of this specification.</p>
</section1>
<section1 topic='Incident Suggestions' anchor='suggestions'>
<p>If an entity that receives an incident report has a suggested solution to the problem, it MAY send an incident message containing a &lt;suggestion/&gt; element.</p>
<example caption="An incident solution"><![CDATA[
<message from='im.flosoft.biz' to='jabber.org'>
<incident xmlns='urn:xmpp:incident:0'
id='BA51A035-7710-4558-9BBF-34838A4C5B24'>
<suggestion>
<text xml:lang='en'>here is how we solved the problem...</text>
</suggestion>
</incident>
</message>
]]></example>
<p>Further definition of the &lt;suggestion/&gt; element will be provided in a future version of this specification.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>To follow.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>To follow.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>To follow.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>To follow.</p>
</section1>
</xep>

637
inbox/instant-gaming.xml Executable file
View File

@ -0,0 +1,637 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
<!ENTITY INVITE "&lt;invite/&gt;">
<!ENTITY JOIN "&lt;join/&gt;">
<!ENTITY ERROR "&lt;error/&gt;">
<!ENTITY TEXT "&lt;text/&gt;">
<!ENTITY GAME "&lt;game/&gt;">
<!ENTITY TURN "&lt;turn/&gt;">
<!ENTITY MOVE "&lt;move/&gt;">
<!ENTITY SAVE "&lt;save/&gt;">
<!ENTITY SAVED "&lt;saved/&gt;">
<!ENTITY FEATURE "&lt;feature/&gt;">
<!ENTITY NAME "&lt;name/&gt;">
<!ENTITY SET "&lt;set/&gt;">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Instant Gaming</title>
<abstract>This document defines an XMPP protocol extension for serverless instant gaming in a one-to-one context.</abstract>
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>XEP-0004</spec>
<spec>XEP-0030</spec>
<spec>XEP-0045</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT YET ASSIGNED</shortname>
<author>
<firstname>Torsten</firstname>
<surname>Grote</surname>
<email>Torsten.Grote(&#228;t)fsfe.org</email>
<jid>Torsten.Grote(&#228;t)jabber.fsfe.org</jid>
</author>
<author>
<firstname>Arne</firstname>
<surname>K&#246;nig</surname>
<email>arne.ko(&#228;t)23inch.de</email>
<jid>arne++(&#228;t)jabber.ccc.de</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2009-03-14</date>
<initials>tg</initials>
<remark><p>First draft.</p></remark>
</revision>
&LEGALNOTICE;
</header>
<section1 topic='Introduction' anchor='intro'>
<p>
Many modern instant messenger networks support playing games.
Still, XMPP mostly lacks this kind of support.
Therefore, this document describes a base protocol for game playing over XMPP.
</p>
<p>
This protocol is not by itself sufficient to play games.
It just describes a basic protocol framework which game-specific protocols can use.
</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>
This document addresses the functionality which is needed to play games over the XMPP.
In particular this functionality consists of:
</p>
<ol start='1'>
<li>discovering support for games in general and for particular games</li>
<li>inviting users to matches</li>
<li>exchanging match information (moves, states, etc.)</li>
<li>saving and loading of matches</li>
<li>terminating matches</li>
</ol>
<!--
<p>In addition to these requirements, additional requirements are addressed by Multi-User Gaming</p>
<ol start='6'>
<li>joining existing games</li>
<li>allow spectators to watch the game</li>
<li>enable players and spectators to chat</li>
<li>validate game moves independently</li>
</ol>
-->
</section1>
<section1 topic='One-to-One Gaming Use Cases' anchor='1to1usecases'>
<p>
The following section describes the use cases associated with one-to-one instant gaming.
It is not supposed to provide professional gaming capabilites with independent move validation, spectators, etc.
Instead, it only supports two player games without spectators and no move validation.
</p>
<p>
Despite the existence of Multi-User Gaming, Instant Gaming is considered important for making gaming over XMPP popular.
Rapid deployment of new two-player games is possible without waiting for server support or finding a suitable server.
<!--Move validation is done by the clients and allows the theoretical possibillity of transfering illegal moves.//-->
</p>
<section2 topic='Discovering Client Game Support' anchor='1to1use-disco'>
<p>An implementation of Instant Gaming MUST support &xep0030;.</p>
<p>
A Jabber entity may wish to discover if another entity implements the Instant Gaming protocol;
in order to do so, it sends a service discovery information ("disco#info") query to the other entity's full JID:
</p>
<example caption='User Queries Another User for Instant Gaming via Disco'><![CDATA[
<iq from='romeo@montague.net/garden'
to='juliet@capulet.com/balcony'
id='req1'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
<p>
The entity MUST return the features it supports.
Game protocols SHOULD include a &FEATURE; element with their namespace in the response, too.
</p>
<example caption='Entity Returns Disco Info Results'><![CDATA[
<iq from='juliet@capulet.com/garden'
to='romeo@montague.net/balcony'
id='req1'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://jabber.org/protocol/games'/>
<feature var='http://jabber.org/protocol/games/tictactoe'/>
<feature var='http://jabber.org/protocol/games/chess'/>
...
</query>
</iq>]]></example>
</section2>
<section2 topic='Invitation' anchor='1to1-invite'>
<p>
In order to invite someone to a game, the initiator sends a message to her/his opponent containing an &INVITE; element,
which MUST specify the invitation type (see <link url='#table-1'>Table 1</link>).
</p>
<p>
Furthermore, a &GAME; element with a "var" attribute containing the namespace of the game protocol is REQUIRED.
It MAY also contain additional information which SHOULD then be specified using &xep0004;.
Such information might be used to state the rules or other slight variations for the particular game.
If an invitation with unsupported rules or options is received,
a &notacceptable; error of type "modify" SHOULD be send to the inviting entity.
</p>
<p>
The &THREAD; element MUST be present and it MUST contain a unique ID which identifies the current match.
The ID MAY for example consist of the initiator's and the opponent's (bare) JID,
the game name, the current datetime (which then SHOULD conform to the DateTime profile specified in &xep0082;) and
a random number, all separated by hyphens.
It is not supposed to get parsed and is only used to uniquely identify the game.
</p>
<example caption='Romeo Invites Juliet to a Game of Checkers'><![CDATA[
<message
from='romeo@montague.net/garden'
to='juliet@capulet.com/balcony'>
<thread>romeo@montague.net-juliet@capulet.com-checkers-1591-02-21T12:56:15Z-1234</thread>
<invite xmlns='http://jabber.org/protocol/games'
type='new'>
<reason>
Hello Juliet,
would you like to play a little game?
</reason>
<game var='http://jabber.org/protocol/games/checkers'/>
</invite>
</message>]]></example>
<table caption='Invitation types'>
<tr>
<th>Invitation Type</th>
<th>Meaning</th>
</tr>
<tr>
<td>new</td>
<td>The game is totally new and contains no data of previous games.</td>
</tr>
<tr>
<td>renew</td>
<td>The game is over and shall be recreated from the beginning with the same match ID.</td>
</tr>
<tr>
<td>adjourned</td>
<td>
This invitation is to resume an adjourned game.
It MUST only be send to the same opponent as from the beginning of the game and MUST contain the same game id.
Further information provides <link url='#1to1-load'>Game Loading</link>
</td>
</tr>
<tr>
<td>constructed</td>
<td>This type states that the game will start with a state which is different from the state new games have.</td>
</tr>
<!--
<tr>
<td>cancel</td>
<td>A previous invitation with the same match ID in the &THREAD; element is no longer valid.</td>
</tr>
--> </table>
<p>
An invitation of type "renew" SHOULD contain the same match ID and &GAME; element as the initial "new" invitation.
It MUST only be send when the previous match with the same match ID has been terminated.
If it is received earlier, an &unexpected; error SOULD be send to the sender of the premature invitation.
Game protocols SHOULD switch the beginning player and leave all other options the same.
</p>
<p>
In the unlikely but possible event
that an invitation of type "renew" is received immediately after one has been send with the same match ID,
this invitation SHOULD be treated as if it were a &MESSAGE; with a &JOIN; element.
Invitations with match IDs that are already assigned to a running game SHOULD be ignored.
</p>
<!--
<p>
An invitation might be canceled by the initiator at any time by sending an invitation with 'type' "cancel" and the same game id.
Mirroring the &GAME; element is OPTIONAL.
Any implementation SHOULD cancel invitations before closing games in a way that nobody can join them anymore.
They also MUST NOT send two invitations with the same game id.
</p>
<example caption='Romeo Cancels His Invitation to Juliet'><![CDATA[
<message
from='romeo@montague.net/garden'
to='juliet@capulet.com/balcony'>
<thread>romeo@montague.net-juliet@capulet.com-checkers-1591-02-21T12:56:15Z-1234</thread>
<invite xmlns='http://jabber.org/protocol/games'
type='cancel'>
<reason>Sorry, I decided not to play, now.</reason>
</invite>
</message>]]></example>
-->
<p>
The opponent SHOULD NOT ignore the invitation.
If she/he does not want to play, the invitation SHOULD be declined.
In order to decline the invitation, the opponent MUST send a message of the following form to the initiator.
</p>
<example caption='Juliet Declines Romeo&#8217;s Invitation'><![CDATA[
<message
from='juliet@capulet.com/balcony'
to='romeo@montague.net/garden'>
<thread>romeo@montague.net-juliet@capulet.com-checkers-1591-02-21T12:56:15Z-1234</thread>
<decline xmlns='http://jabber.org/protocol/games'>
<reason>I won't fight you.</reason>
</decline>
</message>]]></example>
</section2>
<section2 topic='Joining a Game' anchor='1to1-join'>
<p>
In order to join a game, a &MESSAGE; stanza has to be send to the initiator's full JID.
The &MESSAGE; stanza MUST contain the ID of the match to which the opponent wants to join in the &THREAD; element.
Besides that, a &JOIN; element qualified by the namespace 'http://jabber.org/protocol/games' is REQUIRED
and the &BODY; element is OPTIONAL.
</p>
<example caption='Juliet Joins the Game'><![CDATA[
<message
from='juliet@capulet.com/balcony'
to='romeo@montague.net/garden'>
<thread>romeo@montague.net-juliet@capulet.com-checkers-1591-02-21T12:56:15Z-1234</thread>
<join xmlns='http://jabber.org/protocol/games'/>
</message>]]></example>
<p>
A successful join MUST be confirmed by sending the same message (with different sender and recipient) back to the opponent.
</p>
<p>
The initiator might refuse the join by sending a &MESSAGE; stanza of 'type' "error".
It then MUST mirror the &THREAD; ID and the original &JOIN; child element.
The &ERROR; element MAY contain a &TEXT; element with a human-readable description of the error.
</p>
<example caption='Romeo Refuses Juliet'><![CDATA[
<message from='romeo@montague.net/garden'
to='juliet@capulet.com/balcony'
type='error'/>
<thread>romeo@montague.net-juliet@capulet.com-checkers-1591-02-21T12:56:15Z-1234</thread>
<join xmlns='http://jabber.org/protocol/games'/>
<error type='cancel'>
<not-allowed xmlns='urn:ietf:params:xml:xmpp-stanzas'/>
<text>You are not welcome here!</text>
</error>
</message>]]></example>
</section2>
<section2 topic='Game Play' anchor='1to1-play'>
<p>
A turn in a game is sent in a message (of type "chat") to the other player's full JID.
The &MESSAGE; stanza contains a &TURN; element which contains the element, representing the desired action (e.g. &MOVE;) qualified by the namespace of the particular game.
The action itself can be further described by attributes or child elements (see corresponding game protocol).
</p>
<p>
A human-readable comment MAY be sent with the move in the &BODY; element of the &MESSAGE;.
In order to track the game to which the move belongs, the match ID is REQUIRED to be in the &THREAD; element.
</p>
<example caption='Juliet Sends a Game Move to Romeo'><![CDATA[
<message
from='juliet@capulet.com/balcony'
to='romeo@montague.net/garden'
type='chat'>
<thread>juliet@capulet.com-romeo@montague.net-tictactoe-1591-02-23T11:36:25Z-4321</thread>
<body>What do you say to this?</body>
<turn xmlns='http://jabber.org/protocol/games'>
<move xmlns='http://jabber.org/protocol/games/tictactoe'
id='1'
row='2'
col='2'/>
</turn>
</message>]]></example>
<p>A receipt for each message MAY be requested in accordance with &xep0184;.</p>
</section2>
<section2 topic='Game Saving' anchor='1to1-save'>
<p>
While playing a game, it might be desirable to interrupt playing and resume it at a later time.
Games with complete knowledge can be saved at any time by each of the players without sending messages.
But the client of the saving player SHOULD inform the other player that the game was saved by sending the following message.
</p>
<example caption='Romeo Informs Juliet that he Saved the Game'><![CDATA[
<message
from='romeo@montague.net/garden'>
to='juliet@capulet.com/balcony'
<thread>juliet@capulet.com-romeo@montague.net-tictactoe-1591-02-23T11:36:25Z-4321</thread>
<saved xmlns='http://jabber.org/protocol/games'/>
</message>]]></example>
<p>After receiving such an notification, an implementation MAY decide to save the game, too.</p>
<p>
When playing games with incomplete knowledge,
it is desirable that both players save the game at the same time in order to save a clean game state.
The game protocol MUST define whether its game has to be saved independently or mutually.
</p>
<p>
If a game needs to be saved mutually by both players,
one of the players requests the game to be saved by sending a message with a &SAVE; child element as follows.
</p>
<example caption='Juliet Issues a Game Saving Process'><![CDATA[
<message
from='juliet@capulet.com/balcony'
to='romeo@montague.net/garden'>
<thread>juliet@capulet.com-romeo@montague.net-tictactoe-1591-02-23T11:36:25Z-4321</thread>
<save xmlns='http://jabber.org/protocol/games'/>
</message>]]></example>
<p>
The recipient of the above message MUST confirm a successful saving process
using a &SAVED; element as above.
</p>
<p>
To ensure that both players save the same game state,
the sender MUST NOT send any game moves until he receives confirmation from the other player and
the receiver MUST NOT send any game moves after receiving the request for saving until he has responded to it.
</p>
<p>
If the sender of the saving request receives a game move before getting confirmation of a successful saving process,
she/he MUST NOT save the game and MUST send the following error message.
</p>
<example caption='A Mutual Game Save between Romeo and Juliet Fails'><![CDATA[
<message
from='juliet@capulet.com/balcony'
to='romeo@montague.net/garden'
type='error'>
<thread>juliet@capulet.com-romeo@montague.net-tictactoe-1591-02-23T11:36:25Z-4321</thread>
<save xmlns='http://jabber.org/protocol/games'/>
<error type='cancel'>
<conflict/>
</error>
</message>]]></example>
<p>
If one of the player's client encounters an error during the saving process, it MUST send an error message, too.
This time it SHOULD NOT use a &conflict;, but an &undefined; error condition.
</p>
</section2>
<section2 topic='Game Loading' anchor='1to1-load'>
<p>
An XMPP entity that wishes to resume a saved game has to send an invitation
of "type" 'adjourned' to the same opponent it began playing with.
It MAY also resume the game with another opponent, but then it MUST use the "type" 'constructed' and a new match ID.
</p>
<p>
In case the game requires mutual saving by both players and the game was saved this way,
one of the players simply sends an invitation of "type" 'adjourned' with the match ID of the saved game to the other player.
After the invitee has successfully joined the game, it begins at the point where it was saved.
</p>
<p>
If the game was only saved by one of the players, the inviting player MUST send the saved game state in the invitation.
This SHOULD be done by including an &X; element in the &MESSAGE; stanza of the 'jabber:x:data' namespace.
The exact representation of the game state is up to the game protocol, but SHOULD use &xep0004;.
E.g. the state MAY also be encoded in a history of game moves.
</p>
<example caption='Romeo Invites Juliet to a Saved Game'><![CDATA[
<message
from='romeo@montague.net/garden'
to='juliet@capulet.com/balcony'>
<thread>romeo@montague.net-juliet@capulet.com-tictactoe-1591-02-21T12:56:15Z-1234</thread>
<invite xmlns='http://jabber.org/protocol/games'
type='adjourned'>
<reason>
Hello Juliet,
would you like to resume our little game?
</reason>
<game var='http://jabber.org/protocol/games/tictactoe'/>
<x xmlns='jabber:x:data'
type='submit'>
<title>Game of Tic Tac Toe saved on 21st of February 1591 at 1 o'clock</title>
<field var='x-player' type='jid-single'>
<value>juliet@capulet.com/balcony</value>
</field>
<field var='o-player' type='jid-single'>
<value>romeo@montague.net/garden</value>
</field>
<field var='move-id'>
<value>5</value>
</field>
<field var='1-1'/>
<field var='1-2'/>
<field var='1-3'/>
<value>o</value>
</field>
<field var='2-1'>
<value>o</value>
</field>
<field var='2-2'>
<value>x</value>
</field>
<field var='2-3'>
<value>x</value>
</field>
<field var='3-1'/>
<field var='3-2'/>
<field var='3-3'/>
</x>
</invite>
</message>]]></example>
<p>
The Tic Tac Toe game state information in this example is entirely fictional and only for demonstration purposes.
</p>
<p>
An implementation MAY present the game in the saved state to the user along with the invitation.
It MAY also compare the state it received with the state it saved by its own and
inform the user about any mismatches.
</p>
</section2>
<section2 topic='Termination' anchor='1to1-term'>
<p>
An implementation SHOULD send the following &MESSAGE; to end the game.
The "reason" attribute is always REQUIRED.
</p>
<example caption='Romeo Terminates the Game and Accuses Juliet of Cheating'><![CDATA[
<message
from='romeo@montague.net/garden'
to='juliet@capulet.com/balcony'>
<thread>juliet@capulet.com-romeo@montague.net-checkers-1591-02-23T11:36:25Z-4321</thread>
<body>What devil art thou, that dost torment me thus?</body>
<terminate xmlns='http://jabber.org/protocol/games'
reason='resign'/>
</message>
]]></example>
<p>
This &MESSAGE; SHOULD also be send by one of the players
before she/he changes her/his presence to unavailable,
though a different "reason" MAY be used.
For a list of possible reasons and their meaning see <link url='#table-2'>Table 2</link>.
</p>
<p>
In case one player changes her/his presence to unavailable without sending a termination message,
the other player might just wait or MAY save the game (if possible) and
send a termination message with reason 'adjourn'.
</p>
<p>
A terminating &MESSAGE; with reason 'cheating' SHOULD be send, if an illegal move is received.
If one entity receives a terminating &MESSAGE; although it already send one by it's own, it MUST ignore it.
</p>
<table caption='Termination reasons'>
<tr>
<th>Reason</th>
<th>Meaning</th>
</tr>
<tr>
<td>won</td>
<td>The player sending the message has won the game.</td>
</tr>
<tr>
<td>lost</td>
<td>The player sending the message has lost the game.</td>
</tr>
<tr>
<td>draw</td>
<td>The game is over and nobody has won.</td>
</tr>
<tr>
<td>resign</td>
<td>The player sending the message capitulates and quits.</td>
</tr>
<tr>
<td>adjourn</td>
<td>The game is not over and might be resumed at a later time.</td>
</tr>
<tr>
<td>cheating</td>
<td>The player receiving the message has submitted an illegel game move.</td>
</tr>
</table>
</section2>
</section1>
<section1 topic='Glossary' anchor='glossary'>
<p>Initiator -- an entity who started a game.</p>
<p>Opponent -- in an One-to-One gaming context, the entity who was invited to play and did not start the game.</p>
<p>Spectator -- an entity who does not actually plays the game but watches it.</p>
</section1>
<section1 topic='Business Rules' anchor='rules'>
<p>OPTIONAL.</p>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<p>OPTIONAL.</p>
</section1>
<section1 topic='Internationalization Considerations' anchor='i18n'>
<p>OPTIONAL.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>REQUIRED.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>REQUIRED.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>REQUIRED.</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/games'
xmlns='http://jabber.org/protocol/games'
elementFormDefault='qualified'>
<xs:import
namespace='jabber:x:data'
schemaLocation='http://www.xmpp.org/schemas/x-data.xsd'/>
<xs:element name='invite'>
<xs:complexType>
<xs:sequence>
<xs:element name='reason' type='xs:string' minOccurs='0'/>
<xs:element name='game' type='Game'/>
<xs:element ref='xdata:x' minOccurs='0'/>
</xs:sequence>
<xs:attribute name='type'>
<xs:simpleType>
<xs:restriction base='xs:string'>
<xsd:enumeration value='new'/>
<xsd:enumeration value='renew'/>
<xsd:enumeration value='adjourned'/>
<xsd:enumeration value='constructed'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name='decline'>
<xs:complexType>
<xs:sequence>
<xs:element name='reason' type='xs:string'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='join'>
<xs:complexType>
<xs:complexContent/>
</xs:complexType>
</xs:element>
<xs:element name='turn'>
<xs:complexType>
<xs:complexContent/>
</xs:complexType>
</xs:element>
<xs:element name='save'>
<xs:complexType>
<xs:complexContent/>
</xs:complexType>
</xs:element>
<xs:element name='saved'>
<xs:complexType>
<xs:complexContent/>
</xs:complexType>
</xs:element>
<xs:element name='terminate'>
<xs:complexType>
<xs:attribute name='reason'>
<xs:simpleType>
<xs:restriction base='xs:string'>
<xs:enumeration value='won'/>
<xs:enumeration value='lost'/>
<xs:enumeration value='draw'/>
<xs:enumeration value='resign'/>
<xs:enumeration value='adjourn'/>
<xs:enumeration value='cheating'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:complexType name='Game'>
<xs:sequence>
<xs:element ref='xdata:x' minOccurs='0'/>
</xs:sequence>
<xs:attribute name='var' type='xs:string'/>
</xs:complexType>
</xs:schema>
]]></code>
</section1>
</xep>

235
inbox/jingle-ibb.xml Executable file
View File

@ -0,0 +1,235 @@
<?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 In-Band Bytestreams Transport</title>
<abstract>This specification defines a Jingle transport method that results in sending data via the In-Band Bytestreams (IBB) protocol defined in XEP-0047. Essentially this transport method reuses XEP-0047 semantics for sending the data and defines native Jingle methods for starting and ending an IBB session.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0047</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>jingle-ibb</shortname>
&stpeter;
<revision>
<version>0.0.1</version>
<date>2009-02-10</date>
<initials>psa</initials>
<remark>Rough draft.</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>&xep0166; defines a framework for negotiating and managing data sessions over XMPP. In order to provide a flexible framework, the base Jingle specification defines neither data transport methods nor application formats, leaving that up to separate specifications. The current document defines a transport method for establishing and managing data exchanges between XMPP entities using the existing In-Band Bytestreams (IBB) protocol specified in &xep0047;. This "jingle-ibb" method results in a streaming transport method suitable for use in Jingle application types where packet loss cannot be tolerated (e.g., file transfer); however, because the "jingle-ibb" transport method sends data over the XMPP channel itself (albeit not the Jingle signalling channel), it is intended as a transport of last resort when other streaming transports cannot be negotiated.</p>
<p>The approach taken in this specification is to use the existing IBB mechanisms described in XEP-0047 for transporting the data, and to define Jingle-specific methods only to start and end the in-band bytestream.</p>
</section1>
<section1 topic='Protocol'>
<para>The basic flow is as follows.</para>
<code><![CDATA[
Initiator Responder
| |
| session-initiate |
| (with IBB info) |
|--------------------------->|
| ack |
|<---------------------------|
| session-accept |
|<---------------------------|
| ack |
|--------------------------->|
| IBB "SESSION" |
|<==========================>|
| session-terminate |
|<---------------------------|
| ack |
|--------------------------->|
| |
]]></code>
<p>This flow is illustrated in the following examples (to prevent confusion these use a "stub" transport instead of a real application type).</p>
<p>First the initiator sends a Jingle session-initiate request.</p>
<example caption="Initiator sends session-initiate (stub)"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='xn28s7gk'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'>
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='stub'>
<description xmlns='urn:xmpp:jingle:apps:stub:0'/>
<transport xmlns='urn:xmpp:jingle:transports:ibb:0'
block-size='4096'
sid='ch3d9s71'
stanza='iq'/>
</content>
</jingle>
</iq>
]]></example>
<p class='box'>Note: The Jingle IBB Transport Method defines one attribute in addition to those defined in XEP-0047: the 'stanza' attribute. This attribute specifies whether the initiator intends to send IBB data using &MESSAGE; or &IQ; stanzas, but is purely advisory. The default value is "iq", and it is RECOMMENDED to send IBB data using IQ stanzas instead of message stanzas because IQ stanzas provide feedback to the sender regarding delivery to the recipient (e.g., if the recipient is on a small pipe and cannot handle a large volume of IBB packets in quick succession).</p>
<p>The responder immediately acknowledges receipt (but does not yet accept the session).</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='xn28s7gk'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
<p>If the offer is acceptable, the responder returns a Jingle session-accept and the initiator acknowledges the session-accept.</p>
<example caption="Responder definitively accepts the session"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='bsa91h5'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='session-accept'
initiator='romeo@montague.lit/orchard'
responder='juliet@capulet.lit/balcony'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='stub'>
<description xmlns='urn:xmpp:jingle:apps:stub:0'/>
<transport xmlns='urn:xmpp:jingle:transports:ibb:0'
block-size='4096'
sid='ch3d9s71'
stanza='iq'/>
</content>
</jingle>
</iq>
]]></example>
<example caption="Initiator acknowledges session-accept"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='bsa91h5'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>The initiator then immediately begins sending IBB packets using an IQ-set for each chunk as described in XEP-0047, and the responder acknowledges each IQ-set.</p>
<example caption='An IBB packet'><![CDATA[
<iq from='romeo@montague.net/orchard'
id='ls72b58f'
to='juliet@capulet.com/balcony'
type='set'>
<data xmlns='http://jabber.org/protocol/ibb' seq='0' sid='ch3d9s71'>
qANQR1DBwU4DX7jmYZnncmUQB/9KuKBddzQH+tZ1ZywKK0yHKnq57kWq+RFtQdCJ
WpdWpR0uQsuJe7+vh3NWn59/gTc5MDlX8dS9p0ovStmNcyLhxVgmqS8ZKhsblVeu
IpQ0JgavABqibJolc3BKrVtVV1igKiX/N7Pi8RtY1K18toaMDhdEfhBRzO/XB0+P
AQhYlRjNacGcslkhXqNjK5Va4tuOAPy2n1Q8UUrHbUd0g+xJ9Bm0G0LZXyvCWyKH
kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA
</data>
</iq>
]]></example>
<example caption='An IBB ack'><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='ls72b58f'
to='romeo@montague.net/orchard'
type='result'/>
]]></example>
<p>Once the parties have finished using the bytestream (e.g., because a complete file has been sent), either party can send a Jingle session-terminate action.</p>
<example caption="Initiator terminates the session"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='hz81vf48'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason><success/></reason>
</jingle>
</iq>
]]></example>
<p>The other party then acknowledges the session-terminate and the Jingle session is finished.</p>
<example caption="Responder acknowledges session-terminate"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='hz81vf48'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
</section1>
<section1 topic='Processing Rules and Usage Guidelines'>
<p>The same processing rules and usage guidelines defined in XEP-0047 apply to the Jingle IBB Transport Method.</p>
</section1>
<section1 topic='Security Considerations'>
<p>The same security considerations defined in XEP-0047 apply to the Jingle IBB Transport Method.</p>
</section1>
<section1 topic='IANA Considerations'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:jingle:transports:raw-udp:1</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2>
<section2 topic='Protocol Versioning' anchor='registrar-versioning'>
&NSVER;
</section2>
<section2 topic='Jingle Transport Methods' anchor='registrar-transports'>
<p>The XMPP Registrar shall add to its registry of Jingle transport methods a definition for the "jingle-ibb" transport method. The registry submission is as follows:</p>
<code><![CDATA[
<transport>
<name>ibb</name>
<desc>A method for exchanging data over In-Band Bytestreams.</desc>
<type>streaming</type>
<doc>XEP-xxxx</doc>
</transport>
]]></code>
</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='urn:xmpp:jingle:transports:ibb:0'
xmlns='urn:xmpp:jingle:transports:ibb:0'
elementFormDefault='qualified'>
<xs:element name='transport'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='block-size' type='xs:short' use='required'/>
<xs:attribute name='sid' type='xs:string' use='required'/>
<xs:attribute name='stanza' use='optional' default='iq'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='iq'>
<xs:enumeration value='message'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</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>
</xep>

477
inbox/jingle-nodes.xml Executable file
View File

@ -0,0 +1,477 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
<!ENTITY CHANNEL "&lt;channel/&gt;">
<!ENTITY RELAY "&lt;relay/&gt;">
<!ENTITY SERVICES "&lt;services/&gt;">
<!ENTITY TRACKER "&lt;tracker/&gt;">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Jingle Relay Nodes</title>
<abstract>This documents specifies how Jingle Clients can interact with Jingle Relay Nodes Services and how XMPP entities can provide, search and list available Jingle Relay Nodes.</abstract>
<legal>
<copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2009 by the XMPP Standards Foundation (XSF).</copyright>
<permissions>Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the &quot;"Specification&quot;"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.</permissions>
<warranty>## NOTE WELL: This Specification is provided on an &quot;"AS IS&quot;" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##</warranty>
<liability>In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.</liability>
<conformance>This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at &lt;<link url="http://www.xmpp.org/extensions/ipr-policy.shtml">http://www.xmpp.org/extensions/ipr-policy.shtml</link>&gt; or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).</conformance>
</legal>
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0166</spec>
<spec>XEP-0177</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname/>Jingle Nodes <author>
<firstname>Thiago</firstname>
<surname>Camargo</surname>
<email>thiago@xmppjingle.com</email>
<jid>barata7@gmail.com</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2009-12-17</date>
<initials>psa</initials>
<remark>
<p>First draft.</p>
</remark>
</revision>
</header>
<section1 topic="Introduction" anchor="intro">
<p>
Jingle Nodes is an XMPP Based Relay Service providing standard UDP/TCP Relay, but negotiated via XMPP.
Jingle Relay Nodes are intend to provide easy to use Jingle Relay Type Candidates that can be used in ICE-UDP, RAW-UDP, TCP Jingle Sessions.
Relay Candidates can provide NAT Traversal for Jingle users with or without STUN/TURN Support.
The main benefits of Jingle Relay Nodes is the easy to use candidates, Jingle Clients can became a Node and Jingle Relay Nodes are published via XMPP, meaning every Client or Server can also act as a tracker of another Nodes.</p>
</section1>
<section1 topic="Requirements" anchor="reqs">
<p>Jingle Relay Nodes MUST be binded directly to a Public IP address without firewall for traffic on the port range reserved to be used by relay candidates. This is the main and unique requirement for a peer provide Relay Nodes Service.
All signalling, request, response and publishing is done via XMPP, not requiring any extra stack or protocol in the Client or Server, for usage and discoveral of Nodes.</p>
</section1>
<section1 topic="Terminology" anchor="terminology">
<section2 topic="Glossary" anchor="terms-glossary">
<table caption="Glossary">
<tr>
<th>Term</th>
<th>Definition</th>
</tr>
<tr>
<td>Relay</td>
<td>Relays are mainly used to transfer traffic to servers located on a NAT:ed (masqueraded) network, where the IP addresses on the NAT:ed network cannot be accessed from the outside. When you use an IP address that is for local use only, you must use NAT and relays because these IP addresses cannot be accessed in any other way. Relays can also be used for non-NAT:ed networks.</td>
</tr>
<tr>
<td>Jingle Relay Node</td>
<td>Is an instance of a Relay Service that is negotiable via XMPP, following the procedures described on this Extension.</td>
</tr>
<tr>
<td>Tracker</td>
<td>Is the entity that trackers Jingle Relay Nodes and also publishes the list upon request. Potentially all Jingle Clients might act as a Node Tracker.</td>
</tr>
<tr>
<td>Channel</td>
<td>Is the UDP/TCP Relay Channel, provided by the a Jingle Relay Node. The channel act as a NAT Traversal Channel in order to delivery and receive media.</td>
</tr>
<tr>
<td>Requester</td>
<td>Is the Jingle Client that makes requests and make use of a Channel. The Requester receives a relay <link url="#transports">Transport Candidate</link> that can be used with <link url="http://xmpp.org/extensions/xep-0176.html">Jingle ICE-UDP Transport Method</link> or <link url="http://xmpp.org/extensions/xep-0177.html">Jingle Raw UDP Transport Method</link>.</td>
</tr>
</table>
</section2>
<section2 topic="Conventions" anchor="terms-conventions">
<p>In diagrams, the following conventions are used:</p>
<ul>
<li>Single-dashed lines (---) represent Jingle stanzas that are sent via the XMPP signalling channel.</li>
<li>Double-dashed lines (===) represent media packets that are sent via the data channel, which typically is not an XMPP channel (although the <cite>Jingle In-Band Bytestreams Transport Method</cite> is an exception) but instead is a direct or mediated channel between the endpoints.</li>
</ul>
</section2>
</section1>
<section1 topic="Flow Example" anchor="rules">
<p>After the Jingle Clients gets succesfully connected to the XMPP Server, it MAY want to start discoverying available Relay Services in order to cache some entries. Having cached Relay Service Addresses is recommended as it speeds up the session setup time as the Client don't need to search for available Relay Services right before a session is started or received.</p>
<section2 topic="Jingle Client Checks for Tracker or Relay Services on its own Server Domain" anchor="clientcheckownserver">
<p>A Jingle Client MAY start the search for Relay Services by querying his own XMPP Server Domain.</p>
<p>
<em>Note: This is a good implementation practice.</em>
</p>
<example caption="Service List Request"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='uw72g176'
to='montague.lit'
type='get'>
<services xmlns='http://jabber.org/protocol/jinglenodes'/>
</iq>
]]></example>
<example caption="Tracker Returned Known Public Relay Services"><![CDATA[
<iq from='montague.lit'
id='uw72g176'
to='romeo@montague.lit/orchard'
type='result'>
<services xmlns='http://jabber.org/protocol/jinglenodes'>
<relay policy='public' address='montague.lit' protocol='udp'/>
<tracker policy='public' address='capulet.lit' protocol='udp'/>
</services>
</iq> ]]></example>
<em>In this example 'montague.lit' XMPP Domain a Relay Service and a Tracker Service. The Relay Service can be contacted in order to retrieve Relay Channels. The Tracker Service can be contacted in order to retrieve its known services.</em>
</section2>
<section2 topic="Jingle Client Searches for Services on a Retrieved Tracker Service" anchor="clientcheckownserver">
<p>A Jingle Client MAY NOT be satisfied with only one Relay Service entry found. So it keeps the search on the known Tracker Services.</p>
<example caption="Service List Request"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='uw72g177'
to='capulet.lit'
type='get'>
<services xmlns='http://jabber.org/protocol/jinglenodes'/>
</iq>
]]></example>
<example caption="Tracker Returned Known Public Relay Services"><![CDATA[
<iq from='capulet.lit'
id='uw72g177'
to='romeo@montague.lit/orchard'
type='result'>
<services xmlns='http://jabber.org/protocol/jinglenodes'/>
</iq> ]]></example>
<em>In this example 'capulet.lit' returned an empty service list, meaning that it does NOT known ANY Relay or Tracker Services.</em>
</section2>
<section2 topic="Jingle Client Searches for Services on online Roster Entries" anchor="clientcheckownserver">
<p>A Jingle Client MAY NOT be satisfied with only one Relay Service entry found. So it keeps the search on his Roster Items until find the desired amount of Relay Services, or while it does NOT exceed a search depth or ANY other Client implementation policy. The Client SHOULD keep a list of visited Tracker Services in order to avoid searching twice in same Service Entity.</p>
<example caption="Service List Request"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='uw72g177'
to='juliet@capulet.lit/balcony'
type='get'>
<services xmlns='http://jabber.org/protocol/jinglenodes'/>
</iq>
]]></example>
<example caption="Tracker Returned Known Public Relay Services"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='uw72g177'
to='romeo@montague.lit/orchard'
type='result'>
<services xmlns='http://jabber.org/protocol/jinglenodes'>
<relay policy='roster' address='juliet@capulet.lit/balcony' protocol='udp'/>
</services>
</iq> ]]></example>
<p>In this example 'juliet@capulet.lit/balcony' returned a Relay Service entry that is restricted to its roster. This Service is usable as the requester has 'juliet@capulet.lit/balcony' on its roster. Although, services with policy 'roster' MUST NOT be listed in Tracker Responses expects in Tracker Responses that comes from the Service Entity itself, in this case 'juliet@capulet.lit/balcony'.</p>
<em>In the presented example 'romeo@montague.lit/orchard' knows that 'juliet@capulet.lit/balcony' provides Relay Service, but if another entity requests 'romeo@montague.lit/orchard' its known services, it MUST NOT include 'juliet@capulet.lit/balcony' as it is a roster restricted entry.</em>
</section2>
<section2 topic="Jingle Client Consuming the Relay Service" anchor="clientconsumingrelay">
<p>A Jingle Client with direct access to a public IP can potentially provide the Relay Service becaming itself a Jingle Relay Node. The service can intend to provide a public service, or a restricted services based on user preferences, like buddylist, whitelist, blacklist, domain, etc...</p>
<p>
<em>Note: It is NOT mandatory to became a Jingle Relay Node it is OPTIONAL and SHOULD be done ONLY under user awareness and concentiment.</em>
</p>
<example caption="UDP Relay Channel request"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='uw72g176'
to='juliet@capulet.lit/balcony'
type='get'>
<channel xmlns='http://jabber.org/protocol/jinglenodes#channel' protocol='udp'/>
</iq>
]]></example>
<p>After receiving the &CHANNEL; the requester MUST send his stream to 'host' and 'localport' pair and send a &CANDIDATE; containing the 'host' and 'remoteport' values.</p>
<example caption="Candidate Returned by a Node with channel bandwidth throttle"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='uw72g176'
to='romeo@montague.lit/orchard'
type='result'>
<channel component='1'
id='el0747fg11'
host='200.20.2.10'
localport='35800'
remoteport='35802'
protocol='udp'
maxkbps='120'
expire='60'/>
</iq> ]]></example>
</section2>
</section1>
<section1 topic="Services Definitions" anchor="servicesdefinition">
<section2 topic="Relay Channel Service" anchor="relaychannelservice">
<p>A Relay Channel Service is responsible for providing the actual Relay Services. It will receive Channel Requests, allocate the Relay Channel and return the ready to use details. If a Jingle Client knows the service address of one valid and reliable Relay Service, that is enough for place and receive Jingle Calls and transmit both ways media streams based on UDP.</p>
<p>Relay Channel Services support can be discovered by searching using <link url='#trackerservice'>Tracker Services</link>. It can also be discovered by <link url='#support'>service discovery described in this document</link>.</p>
<p>
<em>Note: Jingle Relay Channels can be used with RAW-UDP and ICE-UDP Jingle Transports.</em>
</p>
</section2>
<section2 topic="Tracker Service" anchor="trackerservice">
<p>A Tracker Service is responsible for providing addresses of known Relay Channel Services and other Tracker Services as well.</p>
<section3 topic="Services Types" anchor="servicetypes">
<p>Tracker entries MUST contain a 'type' attribute that represents the usage policy according to the table below:</p>
<table caption="Types of Service Usage Policy">
<tr>
<th>Type</th>
<th>Definition</th>
</tr>
<tr>
<td>public</td>
<td>Relays Services that are meant and opened for public usage, SHOULD use the type 'public'. Meaning that every user can make use of its services. This type SHOULD be published by Tracker Services.</td>
</tr>
<tr>
<td>roster</td>
<td>Relay Services that only provides Channels for users that are in it own roster, SHOULD use the type 'roster'. Meaning that only presence subscribed buddies can make use of its service. Common usage is XMPP Clients with Relay Services Capabilities. This type SHOULD NOT be published by Tracker Services as if it is roster only, the requester SHOULD have the entity already added to his roster, which also mean that it SHOULD be discoverable on roster level.</td>
</tr>
</table>
</section3>
</section2>
</section1>
<section1 topic="Formal Definition" anchor="def">
<section2 topic="Channel Element" anchor="def-channel">
<p>The &CHANNEL; element MUST be empty.</p>
<p>The attributes of the &CHANNEL; element are as follows.</p>
<table caption="Attributes of Channel Element">
<tr>
<th>Attribute</th>
<th>Definition</th>
<th>Inclusion</th>
</tr>
<tr>
<td>id</td>
<td>A random candidate identifier generated by the Relay Service, which effectively maps to the created Channel; this SHOULD match the XML Nmtoken production <note>See &lt;<link url='http://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Nmtoken'>http://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Nmtoken</link>&gt;</note> so that XML character escaping is not needed for characters such as '&amp;'. In some situations the Jingle session identifier might have security implications. See &rfc4086; regarding requirements for randomness.</td>
<td>REQUIRED on response, NOT RECOMMENDED on requests</td>
</tr>
<tr>
<td>host</td>
<td>The IP address or Host address of the Relay Channel.</td>
<td>REQUIRED on response</td>
</tr>
<tr>
<td>localport</td>
<td>The port number to be used by the channel requester.</td>
<td>REQUIRED on response</td>
</tr>
<tr>
<td>remoteport</td>
<td>The port number to be offered to the remote party.</td>
<td>REQUIRED on response</td>
</tr>
<tr>
<td>protocol</td>
<td>The protocol supported by the retrieved channel.</td>
<td>REQUIRED on response</td>
</tr>
<tr>
<td>maxkbps</td>
<td>The maximum bandwidth supported by the channel.</td>
<td>OPTIONAL on response, NOT RECOMMENDED on requests.</td>
</tr>
<tr>
<td>expire</td>
<td>The maximum amount of seconds that the channel can stay without receiving packets, without being deactivated and closed.</td>
<td>REQUIRED</td>
</tr>
</table>
<section3 topic="Host Attribute" anchor="def-host">
<p>The value of the 'host' attribute MUST be one IP address or a DNS resolvable address. That is the address to be used on candidate offering and also the IP to be used when sending out the media traffic.</p>
</section3>
<section3 topic="Localport Attribute" anchor="def-localport">
<p>The value of the 'localport' attribute MUST be a valid IP Port number. This port MUST be used as the media traffic destination port of the channel requester. Session Initiator and responder MUST NOT offer this port.</p>
<p>The rule is simple and unique, the requester of the channel MUST send the media streams to 'localport' and use 'remoteport' in the 'candidate' element to be offered in the Jingle Session.</p>
<p>For transparent compatibility with major RTP Proxy Deployments, an RCTP Port is allocated and defined by default at Localport Attribute Value plus one. (Localport + 1)</p>
</section3>
<section3 topic='Remoteport Attribute' anchor='def-remoteport'>
<p>The value of the 'remoteport' attribute MUST be a valid IP Port number. This port MUST be used as media traffic destination port of the other party. Channel requester MUST use this port value in the candidate offer in combination with the 'host' attribute. Channel requester MUST NOT send any media stream to this port.</p>
<p>For transparent compatibility with major RTP Proxy Deployments, an RCTP Port is allocated and defined by default at Remoteport Attribute Value plus one. (Localport + 1)</p>
</section3>
<section3 topic='Protocol Attribute' anchor='def-protocol'>
<p>The value of the 'protocol' attribute MUST be a valid protocol value: 'udp' or 'tcp' as also defined in the <link url='#schema'>XML Schema</link></p>
</section3>
<section3 topic='Maxkbps Attribute' anchor='def-maxkbps'>
<p>The value of the 'maxkbps' attribute MUST be a valid integer value representing the maximum kilobits per seconds the channel supports. This attribute is optional and MAY be used in Relay Channel with bandwidth limitation.</p>
</section3>
<section3 topic='Expire Attribute' anchor='def-expire'>
<p>The value of the 'expire' attribute MUST be a valid integer value representing the maximum seconds that the channel can stay without receiving any traffic without being deactivated and closed. This attribute is required and SHOULD be used in all Relay Channels.</p>
</section3>
</section2>
<section2 topic="Services Element" anchor="def-services">
<p>The &SERVICES; element MAY be empty or contain &RELAY; and/or &TRACKER; elements.</p>
<p>The attributes of the &RELAY; and &TRACKER; element are as follows.</p>
<table caption="Attributes of Relay and Tracker Elements">
<tr>
<th>Attribute</th>
<th>Definition</th>
<th>Inclusion</th>
</tr>
<tr>
<td>policy</td>
<td>The policy of the service. If the service is public, MUST be 'public' if it is restricted to roster, MUST be 'roster'.</td>
<td>REQUIRED</td>
</tr>
<tr>
<td>address</td>
<td>The IP address or Host address of the Relay Channel.</td>
<td>REQUIRED</td>
</tr>
<tr>
<td>protocol</td>
<td>The protocol supported by the retrieved service.</td>
<td>REQUIRED</td>
</tr>
</table>
</section2>
</section1>
<section1 topic="Determining Support" anchor="support">
<p>To advertise its support for the Jingle Nodes support, when replying to &xep0030; information requests an entity MUST return URNs for any version of this protocol that the entity supports -- e.g., "http://jabber.org/protocol/jinglenodes" for this version&VNOTE;.</p>
<p>If the entity supports, Jingle Nodes as a Tracker, it MUST reply to &xep0030; with "http://jabber.org/protocol/jinglenodes". If it also provides the Jingle Nodes Relay Services, it MUST reply with the URN "http://jabber.org/protocol/jinglenodes#channel".</p>
<p>For optimization purpose the Client SHOULD check for Jingle Nodes support based on entity presence capabilities &xep0115;, which SHOULD contain the keywork "jn-v0".</p>
<example caption="Service discovery information request"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='uw72g176'
to='juliet@capulet.lit/balcony'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption="Service discovery information response"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='uw72g176'
to='romeo@montague.lit/orchard'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='http://jabber.org/protocol/jinglenodes'/>
<feature var='http://jabber.org/protocol/jinglenodes#channel'/>
</query>
</iq>
]]></example>
<p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>
<section1 topic="Recommended Use Cases" anchor="usecases">
<section2 topic="Jingle Client with RAW-UDP Transport without any NAT detection mechanism" anchor="rawudpnostun">
<p>A Jingle Client with only RAW-UDP support and any NAT detection mechanism can make use of Jingle Nodes. Although the traversal is not guarantee due problem with NAT configuration or firewalls, this method is fairly efficient as most SIP legacy services still provides their services in a similar way, meaning that this has the exactly same accertivity and reliability than regular SIP Services. This method is extremelly useful specially for simple platforms like mobile and clients in early stage of development that still wants to offer voice and video support.</p>
<p>
<em>Note: This use case is also similar to a Jingle to SIP Interoperability Service.</em>
</p>
</section2>
<section2 topic="Jingle Client with ICE-UDP Transport with STUN support but no TURN support" anchor="iceudpnoturn">
<p>A Jingle Client with STUN support but no TURN support can use Relay Node Services as the fallback candidate instead of a TURN candidate. For instance, after a connectivity check proccess, none of the direct candidates worked. The Client can use the Relay Node Candidate as the fallback candidate(the lowest priority candidate).</p>
</section2>
<section2 topic="Jingle Client with ICE-UDP Transport with STUN and TURN support" anchor="iceudpstunturn">
<p>A Jingle Client with STUN and TURN support still might need a Relay Candidate, specially as TURN servers are not widely deployed and don't have any mechanism to publish available services for users. TURN servers also requires specific UDP traffic in specific port ranges which can be blocked by users networks. In this case is very useful to have an extra fallback candidate that can be negotiated via XMPP rather than over UDP.</p>
<p>
<em>Note: Jingle Relay Nodes Services are much more likely to be found and be available than TURN servers, as users can also provide Jingle Relay Nodes services themselves or provide a list of known and available services, in this last case behaving a tracker. Is very likely that Jingle Relay Nodes will be available and discovered more easily and often than TURN servers.</em>
</p>
</section2>
<section2 topic="XMPP Client or Component in a Public IP" anchor="clientonpublicip">
<p>A XMPP Client or Component with direct access to a public IP can potentially provide the UDP Relay Service becaming itself a Jingle Relay Node. The service can intend to provide a public service, or a restricted services based on user preferences, like buddylist, whitelist, blacklist, domain, etc...</p>
<p>
<em>Note: It is NOT mandatory to became a Jingle Relay Node. This is OPTIONAL and SHOULD be done with user awareness and concentiment.</em>
</p>
</section2>
</section1>
<section1 topic="Implementation Notes" anchor="impl">
<p>When using a candidate provided by a Jingle Relay Service, the Jingle Client MUST set the candidate attribute to 'relay'. In order to make sure the other client won't allocate another channel as well. Which would lead in audio connectivity issues. In brief, if the caller is using a Relay Candidate the calle MUST NOT use another Relay Candidate discovered by itself. If a caller is not using a Relay Candidate(which can be determined by the candidate 'type' attribute) the callee MAY use a Relay Candidate in order to ensure communication.</p>
</section1>
<section1 topic="Security Considerations" anchor="security">
<p>Relay Channels auto expires MUST expire on traffic inactivity. The inactivity timeout recommended is 60 seconds.</p>
<p>It is heavily recommended that the Super Node implements throttle:</p>
<ul>
<p>
<li>Based on JID, allowing the control of how many concurrent channels an specific JID can have.</li>
</p>
<p>
<li>Based on JID, allowing the control of how many channel requests an specific JID can request in a time period.</li>
</p>
<p>
<li>Based on Bandwidth, allowing the control of how much bandwidth a channel can use. The maximum bandwidth SHOULD be included on the candidate element provided by a Super Node on the attribute maxkbps. If no attribute is present, it means that it has no bandwidth control.</li>
</p>
<example caption="Channel Returned by a Node with bandwidth throttle (stub)"><![CDATA[
<channel component='1'
id='el0747fg11'
host='200.20.2.10'
localport='35800'
remoteport='35802'
protocol='udp'
maxkbps='120'/>
]]></example>
</ul>
</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/jinglenodes'
xmlns='http://jabber.org/protocol/jinglenodes'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
XEP-0177: http://www.xmpp.org/extensions/xep-0177.html
</xs:documentation>
</xs:annotation>
<xs:element name='channel'>
<xs:attribute name='id' type='xs:string' use='required'/>
<xs:attribute name='host' type='xs:string' use='required'/>
<xs:attribute name='localport' type='xs:string' use='required'/>
<xs:attribute name='remoteport' type='xs:string' use='required'/>
<xs:attribute name='protocol' use='required'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='udp'/>
<xs:enumeration value='tpc'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name='maxkbps' type='xs:string' use='optional'/>
<xs:attribute name='expire' type='xs:string' use='required'/>
</xs:element>
<xs:element name='services'>
<xs:complexType>
<xs:sequence>
<xs:element name='relay'
type='serviceElementType'
minOccurs='0'
maxOccurs='unbounded'/>
<xs:element name='tracker'
type='serviceElementType'
minOccurs='0'
maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name='serviceElementType'>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='address' type='xs:string' use='required'/>
<xs:attribute name='policy' use='required'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='public'/>
<xs:enumeration value='roster'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name='protocol' use='required'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='udp'/>
<xs:enumeration value='tpc'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</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>
</xep>

170
inbox/jingle-rtp-codecs.xml Executable file
View File

@ -0,0 +1,170 @@
<?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>Codecs for Jingle RTP Sessions</title>
<abstract>This document describes implementation considerations related to voice and video codecs for use in Jingle RTP sessions.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Informational</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0167</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>N/A</shortname>
<discuss>jingle</discuss>
&stpeter;
<revision>
<version>0.0.4</version>
<date>2009-04-04</date>
<initials>psa</initials>
<remark><p>Clarified status of H.264.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2009-04-02</date>
<initials>psa</initials>
<remark><p>Rewrote document based on developer feedback and Council discussion.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2009-03-04</date>
<initials>psa</initials>
<remark><p>Added more information about video codecs.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2009-03-04</date>
<initials>psa</initials>
<remark><p>First draft, copied from XEP-0167 with slight revisions and addition of requirements section.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>&xep0167; defines the &xep0166; signalling exchanges needed to establish voice and video chat using the Real-time Transport Protocol &rfc3550;; however, it does not discuss the matter of voice and video codecs, since the state of codec technologies is more fluid than the signalling interactions. This document fills that gap by providing guidance to Jingle developers regarding voice and video codecs.</p>
<p>Because codec technologies are typically subject to patents, the topics discussed here are controversial. This document attempts to steer a middle path between (1) specifying mandatory-to-implement technologies that realistically will not be implemented and deployed and (2) providing guidelines that, while realistic, do not encourage the implementation and deployment of patent-clear technologies.</p>
<p class='box'>Please note that this document is strictly informational and does not (yet) provide binding recommendations to the XMPP developer community regarding mandatory-to-implement technologies; however, it is expected that this document will provide input that the &XSF; could use in making such recommendations. Furthermore, it is expected that any recommendations that might be made by the XSF would need to be modified over time as the technology landscape changes.</p>
</section1>
<section1 topic='Basic Considerations' anchor='basics'>
<p>The ideal codec would meet the following criteria:</p>
<dl>
<di><dt>Quality</dt><dd>The encoding quality is acceptable for deployment among XMPP users.</dd></di>
<di><dt>Packetization</dt><dd>The specification of the codec clearly defines packetization of data for sending over RTP.</dd></di>
<di><dt>Availability</dt><dd>The codec can be implemented on a wide variety of computing platforms and is commonly used in Internet or other systems.</dd></di>
<di><dt>Patents</dt><dd>The codec is patent-clear. <note>The term patent-clear does not necessarily mean that no patents have ever been applied for or granted regarding a technology, or that the technology is completely free from patents (since such a judgment is nearly impossible to make, and is outside the purview of the XMPP developer community and the XMPP Standards Foundation); the term means only that those who implement the technology are generally understood to be relatively safe from the threat of patent litigation, either because any relevant patents have expired, were filed in a defensive manner, or are made available under suitable royalty-free licenses.</note></dd></di>
</dl>
<p>Unfortunately, not all codecs are ideal. In the next section we discuss the audio and video codecs that are most attractive for implementation in Jingle RTP applications.</p>
<p>Note: In general, audio codecs are more mature than video codecs. As a result, there are more patent-clear options for audio than for video. Although most XMPP developers would prefer to implement codecs that are patent-clear (both for ethical reasons and to produce free or at least affordable software), such options are not always widely implemented and deployed. This document takes these factors into account.</p>
</section1>
<section1 topic='Codec Summary' anchor='summary'>
<section2 topic='Audio' anchor='audio'>
<section3 topic='Speex' anchor='audio-speex'>
<p>According to the speex.org website, the Speex codec is "an Open Source/Free Software patent-free audio compression format designed for speech". Speex was developed by Jean-Marc Valin and is maintained by the <link url='http://www.xiph.org/'>Xiph.org Foundation</link>. The following table summarizes the available information about Speex.</p>
<table caption='Codec Considerations for Speex'>
<tr>
<th>Quality</th>
<th>Packetization</th>
<th>Availability</th>
<th>Patents</th>
</tr>
<tr>
<td>Good quality; optimized for voice; can be used for wide-band audio.</td>
<td>See &rtpspeex;.</td>
<td>Freely downloadable under a revised BSD license at &lt;<link url='http://speex.org/'>http://speex.org/</link>&gt; and commonly deployed on Internet (VoIP) systems; not commonly deployed on non-Internet systems.</td>
<td>Designed to be patent-clear.</td>
</tr>
</table>
</section3>
<section3 topic='G.711' anchor='audio-g711'>
<p>G.711 refers to the Pulse Code Modulation (PCM) codec defined in &ITU; recommendation G.711, which is widely used on the public switched telephone network (PSTN) and by many voice over Internet Protocol (VoIP) providers. There are two versions: the &#956;-law ("U-law") version is widely deployed in North America and in Japan and the A-law version is widely deployed in the rest of the world. The following table summarizes the available information about G.711.</p>
<table caption='Codec Considerations for G.711'>
<tr>
<th>Quality</th>
<th>Packetization</th>
<th>Availability</th>
<th>Patents</th>
</tr>
<tr>
<td>Good quality; no wide-band mode.</td>
<td>See &rfc5391;.</td>
<td>Commonly deployed in both PSTN and VoIP systems.</td>
<td>Developed in 1972; patents have expired.</td>
</tr>
</table>
</section3>
</section2>
<section2 topic='Video' anchor='video'>
<section3 topic='Theora' anchor='audio-speex'>
<p>According to the theora.org website, the Theora codec is "a free and open video compression format". Theora is based on the VP3 codec originally developed by On2 Technologies and is now maintained by the <link url='http://www.xiph.org/'>Xiph.org Foundation</link>. The following table summarizes the available information about Theora.</p>
<table caption='Codec Considerations for Theora'>
<tr>
<th>Quality</th>
<th>Packetization</th>
<th>Availability</th>
<th>Patents</th>
</tr>
<tr>
<td>Acceptable quality.</td>
<td>See &rtptheora;.</td>
<td>Freely downloadable under a revised BSD license at &lt;<link url='http://theora.org/'>http://theora.org/</link>&gt;; not yet commonly deployed, especially on devices that have deployed H.264 instead.</td>
<td>On2's patents over VP3 were contributed to the Xiph.org Foundation in 2001.</td>
</tr>
</table>
</section3>
<section3 topic='H.264' anchor='audio-h264'>
<p>H.264 is a technology for video compression jointly designed by the ITU and the &ISO;. The following table summarizes the available information about H.264.</p>
<table caption='Codec Considerations for H.264'>
<tr>
<th>Quality</th>
<th>Packetization</th>
<th>Availability</th>
<th>Patents</th>
</tr>
<tr>
<td>High quality.</td>
<td>See &rfc3984;.</td>
<td>Commonly deployed in commercial video systems. Not freely downloadable; both software implementations and service deployments can be subject to royalty payments for commercial use.</td>
<td>Patented.</td>
</tr>
</table>
</section3>
</section2>
</section1>
<section1 topic='Guidance for Implementors' anchor='guidance'>
<p>Given that both Speex and G.711 are patent-clear, freely implementable, and commonly deployed, this document suggests that implementors strongly consider including support for both codecs in audio applications of Jingle RTP sessions.</p>
<p>The situation regarding video codecs is more murky, and implementors face difficult tradeoffs. While Theora is patent-clear and freely implementable, it is not yet commonly deployed. On the other hand, deployment of H.264 is fairly common, but it is not patent-clear or freely implementable. For many open-source / free software projects and smaller technology vendors, implementation of H.264 is either impossible (because of patents and licensing restrictions) or prohibitively expensive (because of royalty payments). These developers are strongly encouraged to implement Theora and also to urge wider adoption of Theora among larger technology vendors. However, this document acknowledges that it may take some time before Theora is commonly deployed (especially on mobile devices) and that systems based on H.264 might be dominant in the marketplace for several years. This situation is unfortunate but cannot be directly changed by the XMPP developer community.</p>
</section1>
<section1 topic='Recommendations to the XSF' anchor='recommendations'>
<p>This document suggests that both Speex and G.711 could be recommended as mandatory-to-implement technologies for audio codecs, should the XSF decide to make such recommendations.</p>
<p>This document suggests that at this time it is not possible for the XSF to recommend a mandatory-to-implement technology for video codecs, but that it might be possible for the XSF to recommend Theora in the future if Theora is more widely adopted.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>For security considerations related to Jingle RTP sessions, refer to XEP-0167. This document introduces no new security considerations. See also the security considerations sections of the relevant codec specifications.</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'>
<p>This document requires no interaction with the &REGISTRAR;.</p>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Olivier Crête, Dave Cridland, Justin Karneges, Tobias Markmann, Jack Moffitt, Jeff Muller, Arc Riley, Kevin Smith, Justin Uberti, and Paul Witty for their feedback.</p>
</section1>
</xep>

144
inbox/jingle-rtp-mti.xml Executable file
View File

@ -0,0 +1,144 @@
<?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>Mandatory-to-Implement Technologies for Jingle RTP Sessions</title>
<abstract>This specification defines mandatory-to-implement technologies for Jingle RTP sessions, in particular codecs for voice and video chat.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0167</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>N/A</shortname>
<discuss>jingle</discuss>
&stpeter;
<revision>
<version>0.0.2</version>
<date>2009-03-04</date>
<initials>psa</initials>
<remark><p>Added more information about video codecs.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2009-03-04</date>
<initials>psa</initials>
<remark><p>First draft, copied from XEP-0167 with slight revisions and addition of requirements section.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>&xep0167; defines the &xep0166; signalling exchanges needed to establish voice and video chat using the Real-time Transport Protocol &rfc3550;; however, it does not specify the recommended voice and video codecs, since the state of codec technologies is more fluid than the signalling interactions. This specification defines the recommended codecs for the sake of interoperability between Jingle voice and video applications.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>The following requirements apply to codec recommendations.</p>
<ol>
<li>The encoding quality of the codec MUST be acceptable for use among XMPP users.</li>
<li>The codec specification MUST clearly define packetization of data for sending over the Realtime Transport Protocol (RTP).</li>
<li>The codec SHOULD be widely used in Internet or other systems, thus enabling interoperability between Jingle applications and non-Jingle applications.</li>
<li>The codec SHOULD NOT be patent-encumbered or, at the least, SHOULD be available under royalty-free licenses.</li>
</ol>
</section1>
<section1 topic='Summary of Considered Codecs' anchor='summary'>
<section2 topic='Audio' anchor='audio'>
<section3 topic='Speex' anchor='audio-speex'>
<p>The Speex codec is an open source / free software, patent-free, audio compression format for the encoding of human speech; it is developed and maintained by <link url='http://www.xiph.org/'>xiph.org</link>. The following table summarizes the available information about Speex.</p>
<table caption='Requirements Conformance of the Speex Codec'>
<tr>
<th>Quality</th>
<th>RTP Packetization</th>
<th>Availability</th>
<th>Patent Encumbrance</th>
</tr>
<tr>
<td>Good quality; optimized for voice; can be used for wide-band audio.</td>
<td>See &rtpspeex;.</td>
<td>Widely available and freely downloadable under a revised BSD license at &lt;<link url='http://speex.org/'>http://speex.org/</link>&gt;.</td>
<td>Designed to be patent-free.</td>
</tr>
</table>
</section3>
<section3 topic='G.711' anchor='audio-g711'>
<p>G.711 refers to the Pulse Code Modulation (PCM) codec defined in &ITU; recommendation G.711, which is widely used on the public switched telephone network (PSTN) and by many voice over Internet Protocol (VoIP) providers. There are two versions: the &#956;-law ("U-law") version is widely deployed in North America and in Japan and the A-law version is widely deployed in the rest of the world. The following table summarizes the available information about G.711.</p>
<table caption='Requirements Conformance of the G.711 Codec'>
<tr>
<th>Quality</th>
<th>RTP Packetization</th>
<th>Availability</th>
<th>Patent Encumbrance</th>
</tr>
<tr>
<td>Good quality; no wide-band mode.</td>
<td>See &rfc5391;.</td>
<td>Widely supported in PSTN and VoIP systems.</td>
<td>Developed in 1972; patents have expired.</td>
</tr>
</table>
</section3>
</section2>
<section2 topic='Video' anchor='video'>
<section3 topic='Theora' anchor='audio-speex'>
<p>The Theora codec is an open source / free software, patent-free, video compression format developed and maintained by <link url='http://www.xiph.org/'>xiph.org</link>. The following table summarizes the available information about Theora.</p>
<table caption='Requirements Conformance of the Theora Codec'>
<tr>
<th>Quality</th>
<th>RTP Packetization</th>
<th>Availability</th>
<th>Patent Encumbrance</th>
</tr>
<tr>
<td>Unknown.</td>
<td>See &rtptheora;.</td>
<td>Widely available and freely downloadable under a revised BSD license at &lt;<link url='http://theora.org/'>http://theora.org/</link>&gt;.</td>
<td>Designed to be patent-free.</td>
</tr>
</table>
</section3>
<section3 topic='H.264' anchor='audio-h264'>
<p>H.264 is a technology for video compression jointly designed by the ITU and the &ISO;. The following table summarizes the available information about Theora.</p>
<table caption='Requirements Conformance of the H.264 Codec'>
<tr>
<th>Quality</th>
<th>RTP Packetization</th>
<th>Availability</th>
<th>Patent Encumbrance</th>
</tr>
<tr>
<td>Unknown.</td>
<td>See &rfc3984;.</td>
<td>Unknown.</td>
<td>Patented.</td>
</tr>
</table>
</section3>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>For security considerations, refer to XEP-0167.</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'>
<p>This document requires no interaction with the &REGISTRAR;.</p>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Olivier Crête, Dave Cridland, Justin Karneges, Tobias Markmann, Jeff Muller, Arc Riley, Kevin Smith, Justin Uberti, and Paul Witty for their feedback.</p>
</section1>
</xep>

493
inbox/jingle-s5b.xml Executable file
View File

@ -0,0 +1,493 @@
<?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 SOCKS5 Bytestreams Transport Method</title>
<abstract>This specification defines a Jingle transport method that results in sending data via the SOCKS5 Bytestreams (S5B) protocol defined in XEP-0065. Essentially this transport method reuses XEP-0065 semantics for sending the data and defines native Jingle methods for starting and ending an S5B session.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0030</spec>
<spec>XEP-0065</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>jingle-s5b</shortname>
&stpeter;
<author>
<firstname>Dirk</firstname>
<surname>Meyer</surname>
<email>dmeyer@tzi.de</email>
<jid>dmeyer@jabber.org</jid>
</author>
<revision>
<version>0.0.3</version>
<date>2009-02-18</date>
<initials>psa</initials>
<remark><p>Clarified order of events to be consistent with raw-udp and ice-udp.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2009-02-11</date>
<initials>dm</initials>
<remark><p>Add additional text to use NAT assisting protocols and allow the responder to also send &lt;streamhost/&gt; information. This change required the introduction of streamhost-used and streamhost-error.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2009-02-10</date>
<initials>psa</initials>
<remark><p>Rough draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>&xep0166; defines a framework for negotiating and managing data sessions over XMPP. In order to provide a flexible framework, the base Jingle specification defines neither data transport methods nor application formats, leaving that up to separate specifications. The current document defines a transport method for establishing and managing data exchanges between XMPP entities using the existing SOCKS5 Bytestreams (S5B) protocol specified in &xep0065;. This "jingle-s5b" method results in a streaming transport method suitable for use in Jingle application types where packet loss cannot be tolerated (e.g., file transfer).</p>
<p>It is RECOMMENDED that a client offers as much &lt;streamhost/&gt; elements with itself as StreamHost as possible. This includes opening the TCP port on all available interfaces the user wants to use (e.g. maybe not an expensive UMTS link), both the IPv4 and IPv6 of that interface (if available), and using an assisting NAT protocol if possible. If the client knows it is behind and the router announces UPnP IGD or NAT-PMP support, the client SHOULD map the open port to the external interface of the router and include the public IP address and port information in the &lt;streamhost/&gt; offers. To increase the chance of success without using a proxy, this specification allows the responder to also send offers.</p>
</section1>
<section1 topic='Protocol' anchor='protocol'>
<para>The basic flow is as follows.</para>
<code><![CDATA[
Romeo Juliet
| |
| session-initiate |
| (with S5B info) |
|--------------------------------->|
| ack |
|<---------------------------------|
| session-accept |
| (with S5B info) |
|<---------------------------------|
| ack |
|--------------------------------->|
| streamhost transport-info |
|<---------------------------------|
| ack |
|--------------------------------->|
| streamhost-used transport-info |
|--------------------------------->|
| ack |
|<---------------------------------|
| S5B "SESSION" |
|<================================>|
| session-terminate |
|<---------------------------------|
| ack |
|--------------------------------->|
| |
]]></code>
<p>This flow is illustrated in the following examples (to prevent confusion these use a "stub" transport instead of a real application type).</p>
<p>First the initiator sends a Jingle session-initiate request that contains one or more transport candidates, which in jingle-s5b are XEP-0065 streamhosts.</p>
<example caption="Initiator sends session-initiate (stub)"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='xn28s7gk'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'>
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='stub'>
<description xmlns='urn:xmpp:jingle:apps:stub:0'/>
<transport xmlns='urn:xmpp:jingle:transports:s5b:0'
sid='vj3hs98y'
mode='tcp'>
<streamhost
jid='romeo@montague.lit/orchard'
host='192.168.4.1'
port='5086'/>
<streamhost
jid='streamhostproxy.example.net'
host='24.24.24.1'
zeroconf='_jabber.bytestreams'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<p>The responder immediately acknowledges receipt.</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='xn28s7gk'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
<p>Depending on the application type, a user agent controlled by a human user might need to wait for the user to affirm a desire to proceed with the session before continuing. When the user agent has received such affirmation (or if the user agent can automatically proceed for any reason, e.g. because no human intervention is expected or because a human user has configured the user agent to automatically accept sessions with a given entity), it returns a Jingle session-accept message. This message MUST contain a &TRANSPORT; element qualified by the 'urn:xmpp:jingle:transports:s5b:0' namespace, which SHOULD in turn contain one &lt;streamhost/&gt; element for each SOCKS5 Bytestreams candidate generated by or known to the responder, but MAY instead be empty if the responder does not wish to offer any streamhosts or wishes to send each candidate as the payload of a transport-info message.</p>
<p>Note: If the responder sends streamhost candidates, the chances of a successful connection are increased. For example, the initiator might be behind a NAT or might have no access to a proxy, whereas the responder might have a public IP address, might know about a streamhost proxy, or might have NAT penetration support like NAT-PMP in the router.</p>
<p>In the following example, Juliet's client is the StreamHost and opens one port. The provided &lt;streamhost/&gt; elements are the (private) IPv4 address of the interface, a (public) IPv6 address, and the public IPv4 address created by mapping the private IP address/port using NAT-PMP.</p>
<example caption="Responder sends session-accept with streamhost candidates"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='hwd987h'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'>
action='session-accept'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='stub'>
<description xmlns='urn:xmpp:jingle:apps:stub:0'/>
<transport xmlns='urn:xmpp:jingle:transports:s5b:0'
sid='vj3hs98y'
mode='tcp'>
<streamhost
jid='juliet@capulet.lit/balcony'
host='192.169.1.10'
port='6539'/>
<streamhost
jid='juliet@capulet.lit/balcony'
host='134.102.201.180'
port='16453'/>
<streamhost
jid='juliet@capulet.lit/balcony'
host='2001:638:708:30c9:219:d1ff:fea4:a17d'
port='6539'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<p>The initiator acknowledges receipt and tries to connect to the offered StreamHosts.</p>
<example caption="Initiator acknowledges streamhost transport-info"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='hwd987h'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>Once one client has successfully created a connection with a StreamHost, it sends the &lt;streamhost-used/&gt; element defined in XEP-0065 to the peer; as a result, both clients will stop trying to connect to other candidates. <note>If both clients happen to send the streamhost-used message at the same time (two connections are open), the StreamHost chosen by the initiator wins (consistent with the rules in <cite>XEP-0166</cite>) and the responder closes the streamhost connection it was able to establish.</note></p>
<example caption="Initiator sends streamhost-used in Jingle transport-info"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='hjdi8'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'>
action='transport-info'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='stub'>
<transport xmlns='urn:xmpp:jingle:transports:s5b:0'
sid='vj3hs98y'
mode='tcp'>
<streamhost-used
jid='juliet@capulet.lit/balcony'
host='134.102.201.180'
port='16453'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<p>The peer immediately acknowledges receipt.</p>
<example caption="Responder acknowledges streamhost-used message"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='hjdi8'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
<p>The initiator can then immediately begin sending data over the SOCKS5 bytestream as described in XEP-0065 (in fact the streamhost is bidirectional, so the responder can use it as well).</p>
<p>Once the parties have finished using the bytestream (e.g., because a complete file has been sent), either party can send a Jingle session-terminate action.</p>
<example caption="Initiator terminates the session"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='hz81vf48'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason><success/></reason>
</jingle>
</iq>
]]></example>
<p>The other party then acknowledges the session-terminate and the Jingle session is finished.</p>
<example caption="Responder acknowledges session-terminate"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='hz81vf48'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
</section1>
<section1 topic='Fallback to IBB' anchor='fallback'>
<p>The session flow is as follows.</p>
<code><![CDATA[
Romeo Juliet
| |
| session-initiate |
| (with S5B info) |
|--------------------------------->|
| ack |
|<---------------------------------|
| session-accept |
| (with S5B info) |
|<---------------------------------|
| [ SOCKS5 failure! ] |
|x--------------------------------x|
| transport-replace (IBB) |
|--------------------------------->|
| ack |
|<---------------------------------|
| IBB "SESSION" |
|=================================>|
| terminate |
|<---------------------------------|
| ack |
|--------------------------------->|
| |
]]></code>
<p>The protocol flow is as follows.</p>
<p>First the initiator sends a Jingle session-initiate, in this case with a transport of SOCKS5 Bytestreams.</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='jingle1'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:jingle:apps:stub:0'/>
<transport xmlns='urn:xmpp:jingle:transports:s5b:0'
sid='vj3hs98y'
mode='tcp'>
<streamhost
jid='romeo@montague.lit/orchard'
host='192.168.4.1'
port='5086'/>
<streamhost
jid='streamer.shakespeare.lit'
host='24.24.24.1'
zeroconf='_jabber.bytestreams'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<p>The responder acknowledges receipt of the session-initiate and sends a session-accept.</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='jingle1'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
<example caption="Responder sends session-accept with streamhost candidates"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='hwd987h'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'>
action='session-accept'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='stub'>
<description xmlns='urn:xmpp:jingle:apps:stub:0'/>
<transport xmlns='urn:xmpp:jingle:transports:s5b:0'
sid='vj3hs98y'
mode='tcp'>
<streamhost
jid='juliet@capulet.lit/balcony'
host='192.169.1.10'
port='6539'/>
<streamhost
jid='juliet@capulet.lit/balcony'
host='134.102.201.180'
port='16453'/>
<streamhost
jid='juliet@capulet.lit/balcony'
host='2001:638:708:30c9:219:d1ff:fea4:a17d'
port='6539'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<p>The initiator acknowledges receipt and tries to connect to the offered StreamHosts.</p>
<example caption="Initiator acknowledges streamhost transport-info"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='hwd987h'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>If initiator or responder is unable to connect to any of the StreamHosts, it MUST send a &lt;streamhost-error/&gt; transport-info to the peer.</p>
<example caption="Responder was unable to connect to any StreamHosts"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='jfd75jk'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='transport-info'
initiator='romeo@montague.lit/orchard'
responder='juliet@capulet.lit/balcony'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='stub'>
<transport xmlns='urn:xmpp:jingle:transports:s5b:0'
sid='vj3hs98y'
mode='tcp'>
<streamhost-error/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<p>The peer immediately acknowledges receipt.</p>
<example caption="Initiator acknowledges streamhost-error"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='jfd75jk'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>If the initiator receives such an error message from the responder and was also unable to connect to any StreamHosts (or did not receive any from the responder), it MUST either terminate the Jingle session with a Jingle reason of &lt;connectivity-error/&gt; or replace the transport by something else using the transport-replace action. Typically the fallback option is &xep0047;. Therefore the initiator sends a transport-replace action including a transport of IBB.</p>
<example caption="Initiator replaces transport with IBB"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='hs92n57'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='transport-replace'
initiator='romeo@montague.lit/orchard'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<transport xmlns='urn:xmpp:jingle:transports:ibb:0'
block-size='4096'
sid='ch3d9s71'/>
</content>
</jingle>
</iq>
]]></example>
<p>The responder then acknowledges the transport-replace action.</p>
<example caption="Responder acknowledges transport-replace"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='hs92n57'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
<p>If the transport replacement is acceptable, the responder then sends a transport-accept action to the initiator (if not, the responder sends a transport-reject action).</p>
<example caption="Responder sends session-accept"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='is71ns63'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='transport-accept'
initiator='romeo@montague.lit/orchard'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<transport xmlns='urn:xmpp:jingle:transports:ibb:0'
block-size='4096'
sid='ch3d9s71'/>
</content>
</jingle>
</iq>
]]></example>
<p>The initiator acknowledges the Jingle transport-accept action.</p>
<example caption="Initiator acknowledges transport-accept"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='is71ns63'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
<p>Now the initiator sends data using In-Band Bytestreams as defined in <cite>XEP-0047</cite>.</p>
</section1>
<section1 topic='Processing Rules and Usage Guidelines' anchor='rules'>
<p>The same processing rules and usage guidelines defined in XEP-0065 apply to the Jingle S5B Transport Method. Additional implementation suggestions are:</p>
<ol>
<li>A client should try the offered StreamHosts in the given order.</li>
<li>If more than one &lt;streamhost/&gt; element is present a client should wait 200ms before trying the next one.</li>
<li>If the JID of a StreamHosts is not the one of the peer it indicates the usage of a proxy. If the client had offered direct connection information it MAY want to wait a little bit longer than 200ms before trying the first proxy to allow the peer to connect without the usage of a proxy.</li>
<li>A client should NOT wait for a TCP timeout on connect. If it is unable to connect to any StreamHost within 5 seconds it should send the streamhost-error.</li>
</ol>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>The same security considerations defined in XEP-0065 apply to the Jingle S5B Transport Method.</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='Jingle Transport Methods' anchor='registrar-transports'>
<p>The XMPP Registrar shall add to its registry of Jingle transport methods a definition for the "jingle-s5b" transport method. The registry submission is as follows:</p>
<code><![CDATA[
<transport>
<name>s5b</name>
<desc>A method for exchanging data over SOCKS5 Bytestreams.</desc>
<type>streaming</type>
<doc>XEP-xxxx</doc>
</transport>
]]></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='urn:xmpp:jingle:transports:s5b:0'
xmlns='urn:xmpp:jingle:transports:s5b:0'
elementFormDefault='qualified'>
<xs:element name='transport'>
<xs:complexType>
<xs:choice>
<xs:element ref='streamhost' minOccurs='0' maxOccurs='unbounded'/>
</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='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:element name='streamhost-error'/>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
]]></code>
</section1>
</xep>

442
inbox/jingle-xtls.xml Executable file
View File

@ -0,0 +1,442 @@
<?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>XMPP Transport Layer Security</title>
<abstract>This document specifies the XMPP Transport Layer Security (XTLS) protocol. XTLS, which provides communications privacy for the Extensible Messaging and Presence Protocol (XMPP), enables XMPP applications to communicate in a way that is designed to prevent eavesdropping, tampering, and forgery of XML stanzas. XTLS is based on Transport Layer Security (TLS) and integrated as security layer into Jingle. The protocol can be used for secure end-to-end messages as well as any other Jingle application like file file transfer.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>RFC 4346</spec>
<spec>XEP-0250</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
<author>
<firstname>Dirk</firstname>
<surname>Meyer</surname>
<email>dmeyer@tzi.de</email>
<jid>dmeyer@jabber.org</jid>
</author>
&stpeter;
<revision>
<version>0.0.4</version>
<date>2009-02-21</date>
<initials>dm</initials>
<remark><p>Improved the documentation about exchanging passwords and certificates.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2009-02-20</date>
<initials>psa/dm</initials>
<remark><p>Simplified the syntax; added sections on requirements and approach; more clearly specified methods of bootstrapping trust on the first communication session.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2009-02-20</date>
<initials>dm</initials>
<remark><p>Clarified order of events to be consistent with jingle-s5b; used TLS-SRP for password based authentication; added some documentation about password authentication in general.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2009-02-12</date>
<initials>dm</initials>
<remark><p>First draft, based on previous attempts for end-to-end security.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>End-to-end encryption of traffic sent over the Extensible Messaging and Presence Protocol (XMPP) is a desirable goal. The Jabber/XMPP developer community has experimented with several such technologies, including OpenPGP (&xep0027;), S/MIME (&rfc3923;), and encrypted sessions or "ESessions" (&xep0218;). For various reasons, these technologies have not been widely implemented and deployed. When the &XSF; asked various Internet security experts to complete a security review of encrypted sessions, it was recommended to explore the possibility of instead using the Transport Layer Security (TLS; see &rfc4346;) as the base technology for XMPP. That possibility is explored in this document.</p>
<p>TLS is the most widely implemented protocol for securing network traffic. In addition to applications in the email infrastructure, the World Wide Web (HTTP Over TLS; see &rfc2818;), and datagram transport for multimedia session negotiation (DTLS; see &rfc4347;), TLS is used in XMPP to secure TCP connections from client to server and from server to server, as specified in &xmppcore;. Therefore TLS is already familiar to XMPP developers.</p>
<p>This specification, called "XTLS", defines a method whereby any &xep0166; application can use TLS semantics for end-to-end encryption, whether the application data is sent over a streaming transport (like TCP) or a datagram transport (like UDP). The most common use case is to tunnel XMPP stanzas between two clients for end-to-end secure chat with &xep0247;. However, XTLS is not limited to client-to-client encryption, since it can be used between two XMPP clients, between an XMPP client and a remote XMPP service (i.e., a service with which a client does not have a direct XML stream, such as a &xep0045; chatroom), or between two remote XMPP services. Furthermore, XTLS can be used for encrypted file transfer (see &xep0234;), for encrypted voice or video sessions using &xep0167; and &dtlssrtp;, and other applications.</p>
<p><em>Note: This specification is a work in progress and does not yet define all uses of XTLS.</em></p>
</section1>
<section1 topic='Requirements' anchor='req'>
<p>This specification is intended to meet the requirements defined in &xep0210; using building blocks that are already widely supported in XMPP clients, such as TLS, Jingle, and &xep0047;. It is possible that some of those requirements can be met only with particular TLS cipher suites, or cannot be met at all without defining extensions to TLS itself. A full gap analysis has not yet been completed.</p>
</section1>
<section1 topic='Approach' anchor='approach'>
<p>In broad outline, XTLS takes the following approach to end-to-end encryption of XMPP traffic:</p>
<ol>
<li><p>We assume that all XMPP entities will have X.509 certificates, typically self-signed and automatically generated by an XMPP client (although CA-issued certificates are acceptable).</p></li>
<li><p>We use the XMPP Jingle extensions as the negotiation framework.</p></li>
<li><p>We define a &lt;security/&gt; element that can be included in any Jingle negotiation, and a new "security-info" Jingle action for sending security-related information.</p></li>
<li><p>When an entity wishes to encrypt its communications with a second entity, it sends a Jingle session-initiate request that specifies the desired application type (e.g., file transfer), a possible transport (e.g., SOCKS5 bytestreams), and security information such as the sender's X.509 fingerprint and supported TLS methods (e.g., secure remote password).</p></li>
<li><p>If both parties support XTLS, the first data sent over the negotiated transport is TLS handshake data, not application data. Once the TLS handshake has finished, the parties can then send application data over the now-encrypted transport.</p></li>
<li><p>The simplest scenario is end-to-end encryption of traditional XMPP text chat using end-to-end XML streams, in-band bytestreams, and previously-accepted X.509 certificates.</p></li>
<li><p>On first use of end-to-end encryption between two entities, it is encouraged to use secure remote passwords rather than leap-of-faith to bootstrap the subsequent use of the client-generated X.509 certificates.</p></li>
<li><p>More complex scenarios are theoretically supported (e.g., encrypted file transfer using SOCKS5 bytestreams and encrypted voice chat using DTLS-SRTP) but have not yet been fully defined.</p></li>
<li><p>XTLS theoretically can be used to establish a TLS-encrypted streaming transport or a DTLS-encrypted datagram transport, but integration with DTLS (&rfc4347;) has not yet been prototyped so use with streaming transports is the more stable scenario.</p></li>
</ol>
<p>We expand on this approach in the following section.</p>
</section1>
<section1 topic='Basic Protocol' anchor='proto'>
<p>The basic flow for an XTLS session is as follows, where traffic represented by single dashes (---) is sent over the XMPP signalling channel and traffic represented by double lines (===) is sent over the negotiated transport.</p>
<code><![CDATA[
Initiator Responder
| |
| session-initiate |
| (with security info) |
|--------------------------->|
| ack |
|<---------------------------|
| session-accept |
|<---------------------------|
| ack |
|--------------------------->|
| open transport |
|<==========================>|
| TLS ClientHello |
|===========================>|
| TLS ServerHello, [...] |
|<===========================|
| TLS [...], Finished |
|===========================>|
| TLS [...], Finished |
|<===========================|
| application data |
|<==========================>|
| session-terminate |
|<---------------------------|
| ack |
|--------------------------->|
| |
]]></code>
<p>To simplify the description we assume here that the parties already trust each other's certificates. See the next section for information about bootstrapping of certificate trust on the first communication.</p>
<p>First the initiator sends a Jingle session-initiate request (here the simple case of an end-to-end text chat session using the &xep0261;). This request includes a &lt;security/&gt; element that contains the fingerprint of the certificate that the initiator will use during the TLS negotiation.</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='xn28s7gk'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'>
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='xmlstream'>
<description xmlns='urn:xmpp:jingle:apps:xmlstream:0'/>
<transport xmlns='urn:xmpp:jingle:transports:ibb:0'
block-size='4096'
sid='ch3d9s71'/>
<security xmlns='urn:xmpp:jingle:security:xtls:0'>
<fingerprint>RomeoX509CertificateHash</fingerprint>
<method name='x509'/>
<method name='srp'/>
</security>
</content>
</jingle>
</iq>
]]></example>
<p>The responder immediately acknowledges receipt of the session-initiate.</p>
<example caption='Responder acknowledges session-initiate'><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='xn28s7gk'
to='romeo@montague.net/orchard'
type='result'/>
]]></example>
<p>Depending on the application type, a user agent controlled by a human user might need to wait for the user to affirm a desire to proceed with the session before continuing. When the user agent has received such affirmation (or if the user agent can automatically proceed for any reason, e.g. because no human intervention is expected or because a human user has configured the user agent to automatically accept sessions with a given entity), it returns a Jingle session-accept message. This message will typically contain the offered application type, transport method, and a &lt;security/&gt; element that includes the fingerprint of the responder's X.509 certificate as well as the responder's supported TLS methods.</p>
<example caption='Responder accepts the session and agrees to use XTLS'><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='hf64hl'
to='romeo@montague.net/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'>
action='session-accept'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='xmlstream'>
<description xmlns='urn:xmpp:jingle:apps:xmlstream:0'/>
<transport xmlns='urn:xmpp:jingle:transports:ibb:0'
block-size='4096'
sid='ch3d9s71'/>
<security xmlns='urn:xmpp:jingle:security:xtls:0'/>
<fingerprint>JulietX509CertificateHash</fingerprint>
<method name='x509'/>
<method name='srp'/>
</security>
</content>
</jingle>
</iq>
]]></example>
<p>The following rules apply to the responder's handling of the session-initiate message:</p>
<ol>
<li><p>If the responder does not support Jingle-XTLS it will silently ignore the &lt;security/&gt; element in the offer and therefore will return a session-accept message without a &lt;security/&gt; element.</p></li>
<li><p>If the responder supports Jingle-XTLS it SHOULD return a session-accept message that contains a &lt;security/&gt; element.</p></li>
<li><p>If the responder thinks it will be able to verify the initiator's certificate, it MUST include the fingerprint for the responder's certificate in the &lt;security/&gt; element of the session-accept message. This is the "happy path" and will occur when the parties have already verified each other's certificates.</p></li>
<li><p>If the responder thinks it will not be able to verify the initiator's certificate, it MAY omit the fingerprint for the responder's certificate in the &lt;security/&gt; element of the session-accept message. This indicates that certificate-based authentication is not possible. In this case the responder SHOULD signal that it wishes to use some other authentication method, such as secure remote passwords (see the next section).</p></li>
<li><p>If the responding client cannot verify the initiator's certificate, it SHOULD ask the responding user if a password was exchanged between the parties that can be used for TLS-SRP. If this is not the case, setting up a mutually-authenticated link will fail and the responder MAY terminate the session. Alternatively it could send its own fingerprint knowing it cannot authenticate the initiator, in which case the responder has to trust that there is no man-in-the-middle (see next section).</p></li>
</ol>
<p>When the responder sends the session-accept message, the initiator acknowledges receipt.</p>
<example caption='Initiator acknowledges session-accept'><![CDATA[
<iq from='romeo@montague.net/orchard'
id='hf64hl'
to='juliet@capulet.com/balcony'
type='result'/>
]]></example>
<p>The following rules apply to the initiator's handling of the session-accept message:</p>
<ol>
<li><p>If the initiator receives a session-accept without a &lt;security/&gt; element, setting up a secure transport layer has failed. The initiator MAY terminate the session at this point or instead proceed without securing the transport. The client SHOULD ask the initiating user how to processed. This depends on the Jingle application and the initiator's preferences: it makes no sense to use end-to-end XML streams without encryption, but the initiator might continue a file transfer without encryption.</p></li>
<li><p>If the initiating client cannot verify the responder's certificate it SHOULD ask the initiating user if a password was exchanged between the parties that can be used for TLS-SRP. If this is not the case, setting up a mutually-authenticated link will fail and the responder MAY terminate the session or proceed with leap-of-faith (see next section).</p></li>
</ol>
<p>The initiator can now determine if X.509 certificate based authentication will work or if TLS-SRP will be used. It sends an additional security-info message to the responder to signal its choice. This step is not really necessary because the responder will see the initiator's choice in the first message of the TLS handshake, but it can help an implementation to set up its TLS library properly. Because in this section we assume that the parties already have validated each other's certificates, the security method signalled here is "x509".</p>
<example caption="Initiator sends security-info"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='hf749j'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'>
action='security-info'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='xmlstream'>
<security xmlns='urn:xmpp:jingle:security:xtls:0'>
<method name='x509'/>
</security>
</content>
</jingle>
</iq>
]]></example>
<p>The responder acknowledges receipt.</p>
<example caption='Responder acknowledges security-info'><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='hf749j'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
<p>Parallel to the security-info exchange the clients set up a transport for the Jingle session. This example uses &xep0261; which does not require any additional messages (other transport like &xep0260; and &xep0176;) need more time to set up). Each transport MUST define a specific time when both cients know that the transport is ready. When XTLS is not used, the Jingle implementation would signal to the using application that the transport is open when the session-accept is sent or received, or when connectivity checks determine media can flow over one of the transport candidates. When XTLS is used, the Jingle implementation starts a TLS handshake on the transport and signals to the using application that the transport is open only after the four-way TLS handshake is finished successfully.</p>
<p>During the TLS handshake, the responder MUST take the role of the TLS server and the initiator MUST take the role of the TLS client. During the handshake, the responder (acting as the TLS server) MUST send a CertificateRequest.</p>
<p>If either client cannot verify the certificate of the peer or receives an invalid message on the TLS layer, it shall terminate the Jingle session immediately, including a Jingle reason of &lt;security-error/&gt;.</p>
<example caption="Initiator terminates the session"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='hz81vf48'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason><security-error/></reason>
</jingle>
</iq>
]]></example>
<p>The other party then acknowledges the session-terminate and the Jingle session is finished.</p>
<example caption="Responder acknowledges session-terminate"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='hz81vf48'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
<p>If the TLS negotiation succeeds, then the Jingle implementation shall signal to the using application that the transport is open. The parties can then exchange application data over the encrypted transport.</p>
</section1>
<section1 topic='Bootstrapping Trust on First Communication' anchor='bootstrapping'>
<p>When two parties first attempt to use XTLS, their certificates might not be accepted (e.g., because they are self-signed or issued by unknown certification authorities). Therefore each party needs to accept the other's certificate for use in future communication sessions. There are several ways to do so:</p>
<ul>
<li><p>Leap of faith. The recipient can hope that there is no man-in-the-middle during the first communication session. If the certificate does not change in future sessions, the recipient at least knows that it is talking with the same entity it talked with during the first session. However, that entity might be a man-in-the-middle rather than the assumed communication partner. Therefore, leap of faith is discouraged.</p></li>
<li><p>Check fingerprints. The parties could validate the certificate fingerprints via some trusted means outside the XMPP band, such as in person, via encrypted email, or over the phone. This is not user-friendly because certificate fingerprints consist of long strings of letters and numbers. As a result, few humans check certificate fingerprints in protocols such as Secure Shell.</p></li>
<li><p>One-time password. The parties can exchange a user-friendly password known only to themselves and verify it out of band before the TLS handshake finishes. For this purpose, it is REQUIRED for implementations to support at least one TLS cipher that uses Secure Remote Password (SRP) as defined in &rfc5054;.</p></li>
<li><p>Channel binding. It is possible that a future version will describe how to use an appropriate Simple Authentication and Security Layer (SASL) mechanism, such as &scram;, to authenticate the XTLS channel after the TLS handshake finishes using the concept of channel bindings (see &rfc5056;).</p></li>
</ul>
<p>If the parties use a password or channel binding via SASL, the process needs to be completed only once. After the clients have authenticated with the shared secret, they can exchange their certificates for future communication.</p>
<section2 topic='Exchanging Certificates' anchor='exchange'>
<p>To retrieve the certificate of the peer for future communications, a client SHOULD request the certificate according to <cite>XEP-0189</cite> over the secure connection. This only works if XTLS was used to set up an end-to-end secure XML stream defined in <cite>XEP-0247</cite>; exchanging certificates if XTLS was used for other purposes like file transfer is not possible. A client MUST NOT request the certificate over the insecure stream based on the connection to the XMPP server.</p>
<example caption='Public keys request'><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='hf7634k'
to='juliet@capulet.lit/balcony'
type='get'>
<pubkeys xmlns='urn:xmpp:tmp:pubkey'/>
</iq>
]]></example>
<p>The peer MUST return its own client certificate. If the user has different clients with different client certificates and one user certificate, the user certificate SHOULD also be returned. The user certificate allows it to verify other client certificates using public key retrieval described in <cite>XEP-0189</cite>.</p>
<example caption='Successful public keys response'><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='hf7634k'
to='romeo@montague.lit/orchard'
type='result'>
<pubkeys xmlns='urn:xmpp:tmp:pubkey'>
<keyinfo>
<name>JulietX509CertificateHash</name>
<x509cert>
MIICCTCCAXKgAwIBAgIJALhU0Id6xxwQMA0GCSqGSIb3DQEBBQUAMA4xDDAKBgNV
BAMTA2ZvbzAeFw0wNzEyMjgyMDA1MTRaFw0wODEyMjcyMDA1MTRaMA4xDDAKBgNV
BAMTA2ZvbzCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA0DPcfeJzKWLGE22p
RMINLKr+CxqozF14DqkXkLUwGzTqYRi49yK6aebZ9ssFspTTjqa2uNpw1U32748t
qU6bpACWHbcC+eZ/hm5KymXBhL3Vjfb/dW0xrtxjI9JRFgrgWAyxndlNZUpN2s3D
hKDfVgpPSx/Zp8d/ubbARxqZZZkCAwEAAaNvMG0wHQYDVR0OBBYEFJWwFqmSRGcx
YXmQfdF+XBWkeML4MD4GA1UdIwQ3MDWAFJWwFqmSRGcxYXmQfdF+XBWkeML4oRKk
EDAOMQwwCgYDVQQDEwNmb2+CCQC4VNCHesccEDAMBgNVHRMEBTADAQH/MA0GCSqG
SIb3DQEBBQUAA4GBAIhlUeGZ0d0msNVxYWAXg2lRsJt9INHJQTCJMmoUeTtaRjyp
ffJtuopguNNBDn+MjrEp2/+zLNMahDYLXaTVmBf6zvY0hzB9Ih0kNTh23Fb5j+yK
QChPXQUo0EGCaODWhfhKRNdseUozfNWOz9iTgMGw8eYNLllQRL//iAOfOr/8
</x509cert>
</keyinfo>
</pubkeys>
</iq>
]]></example>
</section2>
<section2 topic='Verification of Non-Human Parties' anchor='bootstrap-bot'>
<p>If one of the parties is a "bot" (e.g., an automated service or a device such as a set-top box), the password exchange is a bit more complicated. It is similar to Bluetooth peering if the user has access to both clients at the same time. One of the following scenarios might apply:</p>
<ol>
<li><p>The bot can be controlled via a remote control input device. The human user can enter the same password or "PIN" on both the bot and the XMPP client.</p></li>
<li><p>If the bot has no user input but does have a small display, it could display a random password. The human user can then enter the provided password on the XMPP client.</p></li>
<li><p>The bot might have not enough buttons for input and has no output device. In that case the password is fixed. Similar to Bluetooth peering with simple devices such as a headset, the password will be written in the manual or printed on the device. For security reasons the device SHOULD NOT use password-based authentication without any user input. Many Bluetooth devices have at least one button to set the device into peering mode.</p></li>
<li><p>A bot may be associated with a web service and could display a random password when the user has logged in to the web site using HTTPS. This assumes that an attacker does not have control over the web server and can perform a man-in-the-middle attack on XMPP level at the same time. If the web service knows the GPG-key of the user (e.g. launchpad) it could send an encrypted email.</p></li>
</ol>
<p>A user might have different X.509 certificates for each device. &xep0189; can be used to manage the user's certificates. A client SHOULD check the peer's PubSub node for certificates. This makes it possible to use the password method only once between two users even if one or both users switch clients. This makes it also possible for a user to communicate with a friend's bots. They first open a secure link between two chat clients with a password and exchange the user certificates. After that each user can verify all devices of the other without the need of a password.</p>
<p>The retrieved certificate from the PubSub node may be signed by a CA the client can verify. In that case the client MAY skip the password authentication and rely on the X.509 certificate chain. The client SHOULD ask the user if the certificate should be accepted or if a password exchange is desired.</p>
</section2>
</section1>
<!--
<section1 topic='Password-Based Certificate Verification' anchor='password'>
<p>This specification uses TLS-SRP for password based authentication. This section describes two possible other methods that might replace the usage of TLS-SRP in future versions of this document. There are included here to give input for future discussions.</p>
<section2 topic='SASL Channel Bindings'>
<p>The second idea is to use SASL channel bindings. The clients set up the TLS link using X.509 certificates. If a client cannot verify the other's certificate, it has no initiate SASL using security-info Jingle messages. The used SASL mechanism will be bound to the TLS link (channel binding) and provide mutal authentication. <link url='http://tools.ietf.org/html/draft-newman-auth-scram-08'>SCRAM</link> provides these features. See <link url='http://blog.dave.cridland.net/?p=43'>Dave Cridland's blog</link> for additional information about channel bindings.</p>
<ul>
<li>Pros: Based on SASL and therefore also works for link-local communication. It is possible to start the SASL procedure at any time during the communication. An XMPP client already has SASL support and only needs to support an additional SASL method.</li>
<li>Cons: Current SASL libraries do not support SCRAM, it is only a draft. Additionally it requires special support from the used TLS library. The 'Finished' message from the TLS handshake is required for the channel binding. Most TLS libraries do not provide this information.</li>
</ul>
</section2>
<section2 topic='Something Self-made'>
<p>Both previous solutions require special support from the TLS library and they are designed for a different purpose: not reveal the user's password. Since the password is only used to verify the X.509 certificates, we have a different requirement here. The following solution does not prevent a man-in-the-middle to get the password, a brute force attack will reveal it. This method keeps the password hidden until the clients exchanged their X.509 certificates over an insecure link. If the TLS channel is created with the same X.509 certificates, there is no man-in-the-middle.</p>
<p>Each client generates two salt strings to prevent dictionary attacks (challengeSalt and respondSalt). One client starts the authentication request (if both clients do it at the same time it does not matter). It sends the challengeSalt to the peer. The peer creates a SHA1 hash sum of its public key (the part to prove to the other side), the password (shared secret), the received challengeSalt, and its respondSalt. It sends this hash plus its challengeSalt to the initiator. The initiator will do the same calculation with its public key and salts and send the hash back.</p>
<code><![CDATA[
A B
| |
| challengeSaltA |
|=========================>|
| challengeSaltB + hashB |
|<=========================|
| hashA |
|=========================>|
hashB = sha1(publicKeyB + password + challengeSaltA + respondSaltB)
hashA = sha1(publicKeyA + password + challengeSaltB + respondSaltA)
]]></code>
<p>At this point both client have a hash from the other, but they have no way to verify it because A is missing respondSaltB and B is missing respondSaltA. But if there is a man-in-the-middle, it had to send something at this point without any chance to get the password. Even with brute force it is not possible to get the password because the respondSalt is missing.</p>
<p>In the next step B sends A the missing respondSaltB and A answers with respondSaltA. Now the two clients can do the calculation the other did to verify the hash. If the public key used for the TLS channel and the shared secret is correct, a client can be sure there is no man-in-the-middle.</p>
<code><![CDATA[
A B
| |
| respondSaltB |
|<=========================|
| respondSaltA |
|=========================>|
]]></code>
<p>The man-in-the-middle can get the password using brute-force. Both public keys and the four salt strings are now known. To keep hidden as man-in-the-middle, the attacker needs to create a respondSalt for both peers that matches its public key, the password, the challengeSalt, and the hash sum it send. The problem for the attacking client is that it had to send out a hash sum at a point where it is not possible to get the shared key (the respondSalt is missing). If the hash sum is secure against creating collisions this is not possible. The man-in-the-middle has to use brute force and create two collisions in a very short time frame.</p>
<ul>
<li>Pros: Works with any TLS implementation.</li>
<li>Cons: Someone smart has to look at it if I missed something. It needs to be adapted to link-local somehow.</li>
</ul>
</section2>
</section1>
-->
<section1 topic='Determining Support' anchor='support'>
<p>If an entity wishes to request the use of XTLS, it SHOULD first determine whether the intended responder supports the protocol. This can be done directly via &xep0030; or indirectly via &xep0115;.</p>
<p>If an entity supports XTLS, it MUST report that by including a service discovery feature of "urn:xmpp:jingle:security:xtls:0" in response to disco#info requests &NSNOTE;.</p>
<example caption="Initial Service Discovery Information Request"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='disco1'
to='juliet@capulet.lit/chamber'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption="Service Discovery Information Response"><![CDATA[
<iq from='juliet@capulet.lit/chamber'
id='disco1'
to='romeo@montague.lit/orchard'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='urn:xmpp:jingle:security:xtls:0'/>
</query>
</iq>
]]></example>
<p>Both service discovery and entity capabilities information could be corrupted or intercepted; for details, see the <link url='#security-dos'>Denial of Service</link> section of this document.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>This entire document addresses security. Particular security-related issues are discussed in the following sections.</p>
<section2 topic='Mandatory-to-Implement Technologies' anchor='security-mti'>
<p>An implementation MUST at a minimum support the "srp" and "x509" methods. A future version of this specification will document mandatory-to-implement TLS ciphers.</p>
</section2>
<section2 topic='Certificates' anchor='security-certs'>
<p>As noted, XTLS can be used between XMPP clients, between an XMPP client and a remote XMPP service (i.e., a service with which a client does not have a direct XML stream), or between remote XMPP services. Therefore, a party to an XTLS bytestream will present either a client certificate or a server certificate as appropriate. Such certificates MUST be generated and validated in accordance with the certificate guidelines guidelines provided in &rfc3920bis;.</p>
<p>A future version of this specification might provide additional guidelines regarding certificate validation in the context of client-to-client encryption.</p>
</section2>
<section2 topic='Denial of Service' anchor='security-dos'>
<p>The Jingle stanzas are not encrypted or signed; the same is true of service discovery exchanges and entity capabilities data. Therefore it is possible for an attacker to intercept these stanzas and modify them, thus convincing the initiator that the responder does not support XTLS and therefore denying the parties an opportunity to use XTLS.</p>
<p>A future version of this specification might address this problem.</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='registrar-ns'>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:jingle:security:xtls:0</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2>
<section2 topic='Protocol Versioning' anchor='registrar-versioning'>
&NSVER;
</section2>
<section2 topic='XTLS Methods Registry' anchor='registrar-xtls'>
<p>The XMPP Registrar shall create a registry of TLS methods that can be used in the context of XTLS.</p>
<section3 topic='Process' anchor='registrar-xtls-process'>
&REGPROCESS;
<code><![CDATA[
<method>
<name>the XML character data of the TLS method name</name>
<desc>a natural-language description of the method</desc>
<doc>the document that specifies or registers the method</doc>
</method>
]]></code>
<p>The registrant can register more than one TLS method at a time, each contained in a separate &lt;method/&gt; element.</p>
</section3>
<section3 topic='Registration' anchor='registrar-xtls-init'>
<p>The initial registration is as follows.</p>
<code><![CDATA[
<method>
<name>openpgp</name>
<desc>exchange of OpenPGP keys</desc>
<doc>RFC 5081</doc>
</method>
<method>
<name>srp</name>
<desc>exchange of secure remote passwords</desc>
<doc>RFC 5054</doc>
</method>
<method>
<name>x509</name>
<desc>exchange of X.509 certificates</desc>
<doc>RFC 5246</doc>
</method>
]]></code>
</section3>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>The XML schema will be provided in a later version of this document.</p>
</section1>
</xep>

151
inbox/jingle-zrtp.xml Executable file
View File

@ -0,0 +1,151 @@
<?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>Use of ZRTP in Jingle RTP Sessions</title>
<abstract>This specification defines a Jingle application type for negotiating one or more sessions that use the Real-time Transport Protocol (RTP) to exchange media such as voice or video. The application type includes a straightforward mapping to Session Description Protocol (SDP) for interworking with SIP media endpoints.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0166</spec>
<spec>XEP-0167</spec>
<spec>draft-zimmermann-avt-zrtp</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>N/A</shortname>
<discuss>jingle</discuss>
&stpeter;
<revision>
<version>0.0.2</version>
<date>2009-02-24</date>
<initials>psa</initials>
<remark><p>Defined dedicated namespace for the zrtp-hash element to improve service discovery and handling of session-info message; clarified protocol flow and security considerations.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2009-02-17</date>
<initials>psa</initials>
<remark><p>First draft, copied from XEP-0167.</p></remark>
</revision>
</header>
<section1 topic='Protocol' anchor='protocol'>
<p>&xep0167; recommends the use of the Secure Real-time Transport Protocol (SRTP) for end-to-end encryption of RTP sessions negotiated using &xep0166;. An alternative approach to end-to-end encryption of RTP traffic is provided by &zrtp;. Although negotiation of ZRTP mainly occurs in the media channel rather than the signalling channel, the ZRTP specification defines one SDP attribute called "zrtp-hash" (this communicates the ZRTP version supported as well as a hash of the Hello message).</p>
<p>The SDP format is shown below.</p>
<code>
a=zrtp-hash:zrtp-version zrtp-hash-value
</code>
<p>An example follows.</p>
<code>
a=zrtp-hash:1.10 fe30efd02423cb054e50efd0248742ac7a52c8f91bc2df881ae642c371ba46df
</code>
<p>This SDP attribute can be translated into Jingle as a &lt;zrtp-hash/&gt; element, as shown below.</p>
<code><![CDATA[
<zrtp-hash version='zrtp-version'>zrtp-hash-value</zrtp-hash>
]]></code>
<p>An example follows.</p>
<code><![CDATA[
<zrtp-hash version='1.10'>fe30efd02423cb054e50efd0248742ac7a52c8f91bc2df881ae642c371ba46df</zrtp-hash>
]]></code>
<p>If either party to a Jingle RTP session wishes to use ZRTP, the party SHOULD send a Jingle session-info message that includes a &lt;zrtp-hash/&gt; element qualified by the 'urn:xmpp:jingle:apps:rtp:zrtp:0' namespace, as shown in the following example.</p>
<example caption="Initiator sends session-info message with zrtp-hash"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='vna13b9a'
from='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='session-info'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<zrtp-hash xmlns='urn:xmpp:jingle:apps:rtp:zrtp:0'
version='1.10'>fe30efd02423cb054e50efd0248742ac7a52c8f91bc2df881ae642c371ba46df</zrtp-hash>
</jingle>
</iq>
]]></example>
<p>In accordance with <cite>XEP-0166</cite>, if the receiving party does not understand the payload of the session-info message then it MUST return a &feature; error.</p>
<example caption="Receiver returns feature-not-implemented error"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='ringing1'
to='romeo@montague.lit/orchard'
type='error'>
<error type='modify'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<unsupported-info xmlns='urn:xmpp:jingle:errors:0'/>
</error>
</iq>
]]></example>
<p>However, if the receiving party also supports and wishes to use ZRTP, it too SHOULD send a session-info message containing a zrtp-hash element.</p>
</section1>
<section1 topic='Determining Support' anchor='disco'>
<p>If an entity supports the zrtp-hash session-info message, it MUST advertise that fact in its responses to &xep0030; information ("disco#info") requests by returning a feature of "urn:xmpp:jingle:apps:rtp:zrtp:0":</p>
<example caption='A disco#info query'><![CDATA[
<iq type='get'
from='calvin@usrobots.lit/lab'
to='herbie@usrobots.lit/home'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption='A disco#info response'><![CDATA[
<iq type='result'
from='herbie@usrobots.lit/home'
to='calvin@usrobots.lit/lab'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='urn:xmpp:jingle:apps:rtp:zrtp:0'/>
</query>
</iq>
]]></example>
<p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>Security considerations for ZRTP itself are provided in <cite>draft-zimmermann-avt-zrtp</cite>.</p>
<p>XMPP stanzas such as Jingle session-info messages and service discovery exchanges are not encrypted or signed. As a result, it is possible for an attacker to intercept these stanzas and modify them, thus convincing one party that the other party does not support ZRTP and therefore denying the parties an opportunity to use ZRTP. However, because the zrtp-hash is mostly advisory, the parties could still use ZRTP even if the signalling channel is compromised.</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'>
<p>See the <link url='#schema'>XML Schemas</link> section of this document.</p>
</section1>
<section1 topic='XML Schemas' anchor='schema'>
<p>If this specification is advanced to a status of Draft, the XMPP Registrar shall add the following element definition to the schema for the 'urn:xmpp:jingle:apps:rtp:info:1' namespace defined in XEP-0167:</p>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:jingle:apps:rtp:zrtp:0'
xmlns='urn:xmpp:jingle:apps:rtp:zrtp:0'
elementFormDefault='qualified'>
<xs:element name='zrtp-hash'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='version' type='xs:string' use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</xep>

1041
inbox/lop.xml Executable file
View File

File diff suppressed because it is too large Load Diff

155
inbox/mobile.xml Normal file
View File

@ -0,0 +1,155 @@
<?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>XMPP on Mobile Devices</title>
<abstract>This document provides background information for XMPP implementors concerned with mobile devices operating in a cellular network such as 3G.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Informational</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
<author>
<firstname>Dave</firstname>
<surname>Cridland</surname>
<email>dave.cridland@isode.com</email>
<jid>dave.cridland@isode.com</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2010-07-13</date>
<initials>dwd</initials>
<remark><p>First draft. Also John's birthday.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>The use of XMPP on mobile devices is little understood, since few XMPP implementors have good mobile knowledge, and few mobile engineers have good XMPP knowledge. In addition, as the mobile landscape has changed, optimal protocol designs and usage patterns have also changed. This has led to the sub-optimal combination of a large amount of mostly undocumented lore, as well as several outdated concepts being discussed as fact.</p>
<p>This XEP aims to provide useful background knowledge of mobile handset behaviours, and essentially distills a number of conversations with experienced mobile engineers and XMPP implementors, providing useful background as general suggestions.</p>
</section1>
<section1 topic='Overview' anchor='overview'>
<p>Mobile handsets typically have two constraints - power and bandwidth. The advent of 3G technology and beyond has tended to mean that bandwidth is radically higher, and comparable to broadband speeds - however many operators still charge based on transferred data, hence bandwidth remains an important issue for cost purposes.</p>
<p>The major cost of power in the handset for our purposes is the radio - here, too, bandwidth plays a part, but as this document will show, the time the radio is forced to be available to receive also costs substantially.</p>
<p>Whilst this document refers to &xmppcore;, implementors are advised to take note of &rfc3920bis;.</p>
</section1>
<section1 topic='Compression'>
<p>XMPP is known to compress well. Both TLS, part of &xmppcore;, and &xep0138; can provide access to the DEFLATE codec (<span class='ref'><link url='http://tools.ietf.org/html/rfc1951'>RFC 1951</link></span> <note>RFC 1951 DEFLATE Compressed Data Format Specification version 1.3
&lt;<link url='http://tools.ietf.org/html/rfc1951'>http://tools.ietf.org/html/rfc1951</link>&gt;.</note>), which provides access to simple stream compression.</p>
<p>Compression ratios vary with usage, however, typical usage by a general client appears to show a 20% ratio (an 80% reduction in bandwidth) in longer sessions<note>Fixed-purpose clients, such as the Buddycloud client, do see even lower ratios, approaching 10%.</note>. Server implementors should note that there is a substantial memory cost per codec of 300KB assuming maximum settings - this may be dramatically reduced by reducing the memory level and window bits of the implementation - lowering memory level primarily causes increased CPU usage, whereas lowering the window bits directly degrade compression.</p>
<p>At an exemplary point in one experiment, the author found the following figures<note>The compression ratio is here given as Original/Compressed, hence a 100% compression ratio is no compression at all, and 0% would represent infinite compression.</note>:</p>
<table>
<tr>
<th>Window Bits</th>
<th>Compression Ratio (approx)</th>
</tr>
<tr>
<td>15</td>
<td>20%</td>
</tr>
<tr>
<td>14</td>
<td>22%</td>
</tr>
<tr>
<td>13</td>
<td>25%</td>
</tr>
<tr>
<td>12</td>
<td>30%</td>
</tr>
<tr>
<td>11</td>
<td>38%</td>
</tr>
<tr>
<td>10</td>
<td>43%</td>
</tr>
<tr>
<td>9</td>
<td>60%</td>
</tr>
</table>
<p>Although there is an equal cost for the mobile device to compress, it is considered that the compression codec memory and CPU costs - while certainly translating into power cost - are outweighed by two factors. Firstly, they're likely to reduce the transmission cost by a greater amount, and secondly they will also reduce the encryption cost in TLS.</p>
<p>Care, however, should be taken not to use XEP-0138 compression when TLS compression is in effect.</p>
</section1>
<section1 topic='Radio Power'>
<p>Mobile handsets have a number of levels for radio activity. 3G radios can be either Idle, or else in an increasingly capable - and increasingly power-hungry - series of levels, through FACH to DCH.</p>
<p>For the purposes of investigating this, power consumption (or rather battery depletion rate, as current) and timeouts where measured on the 3UK network, with a Nokia E71, using the Energy Profiler. A "typical handset" mentioned here has a 1000mAh battery - some smartphones have up to 1500mAh. Note that all timeouts are under the control of the network operator, not the handset or application.</p>
<section2 topic='Idle'>
<p>Idle state is when the radio is neither receiving nor transmitting. It may have live (although silent) TCP connections. The cost is low. There is also a PCH level, which is similarly low-power, and again is only used when the radio is silent.</p>
<p>The current here was measured as 8mA - likely affected more by the energy profiler than much else.</p>
</section2>
<section2 topic='FACH'>
<p>FACH uses a shared channel for low-bandwidth communications. Packet sizes must be small - around 128 octets maximum, although this is operator controlled. Raising to this state takes around 2.5 seconds before the data can flow - although the power cost rises instantly - and after the session has returned to silence, it will remain at FACH level for some time.</p>
<p>Note that this threshold includes the overheads from TCP and TLS, which are 52 and 5 octets respectively, leaving around 70 octets for the payload data.</p>
<p>Here, the current was measured as 140mA, and a timeout of 8 seconds - this timeout is at the lower end of the expected range, which could be up to around 2 minutes. On a typical handset, this will exhaust the battery in around 7 hours.</p>
</section2>
<section2 topic='DCH'>
<p>DCH uses a dedicated channel for high bandwidth communications. Again, raising to this state takes 2.5 seconds at the DCH power level, and there is a timeout before dropping back. Some operators will drop back to FACH for the duration fo the FACH timeout - others will drop back to Idle/PCH.</p>
<p>Sending more than the FACH threshold will raise the radio all the way to DCH - taking, again, 2.5 seconds.</p>
<p>The measurements here were 380mA and 8 seconds - this is sufficient to flatten a typical handset battery in less than 3 hours, and the figures are considered normal.</p>
</section2>
<p>Transmission of data can use up to 2W<note>The author's hazy recollection of P=IV suggests around a 570mA current</note>, and raising the level itself takes between 2 and 3 seconds to take effect - during which time the handset cannot receive or transmit, but still incurs the power cost. There are packets sent from and to the handset during this time.</p>
<p>Experimentation suggests that uncompressed XMPP will never trigger the FACH state, leaping directly into the more costly DCH state. However, compression does make FACH possible, if rare.</p>
</section1>
<section1 topic='Conclusions'>
<p>As with anything, there are no hard and fast rules. If there were, they might look like these. First, for devices:</p>
<dl>
<dt>Transmit no data.</dt>
<dd>Transmitting costs significant power, and moreover raises the radio state. Not transmitting will allow it to maximize the time spent in the low-cost Idle state.</dd>
<dt>If you must transmit, then transmit only a small volume.</dt>
<dd>If there is only a small amount of data transmitted - less than 128 octets typically - the radio will only raise to FACH, which is significantly cheaper than DCH.</dd>
<dt>If you must transmit, then compress as hard as possible.</dt>
<dd>Since individual octets have an associate power - and often financial - cost, it's worth maximizing the compression algorithm, even if the volume of traffic will raise to DCH.</dd>
<dt>If you have transmit a lot, then do a lot</dt>
<dd>If the radio is raised to DCH anyway, then you may as well go fetch that avatar you were missing, since you're chewing through power anyway.</dd>
<dt>If you receive, then transmit</dt>
<dd>If your peer raises the radio state, you may as well use it.</dd>
</dl>
<p>And for servers, similar rules apply:</p>
<dl>
<dt>Send no data.</dt>
<dd>Sending data will cause the handset to be raised out of Idle. This immediately costs massively higher power.</dd>
<dt>If you must send, send tiny bits.</dt>
<dd>Sending small enough data maximizes the likelyhood that the devices radio will only be raised to FACH levels.</dd>
<dt>If you receive, then send anything you have.</dt>
<dd>Receiving data indicates that the radio is active - it'll stay active for some time, so sending data doesn't incur the overhead of raising the radio state, and won't increase power drain on the handset.</dd>
<dt>If you must send when not receiving, send plenty.</dt>
<dd>Sending data will raise the radio's state - unless you can tell this will only raise it to FACH, it's worth sending as much as possible.</dd>
</dl>
<p>Finally, protocol designers should aim to minimize any responses required from the handset, and ensure keepalive traffic, if any, fits inside FACH wherever possible.</p>
</section1>
<section1 topic='Notable Extensions'>
<p>This section provides pointers to other documents which may be of interest to those developing mobile clients, or considering support for them in servers.</p>
<p>&xep0138; provides application stream level compression, useful if the device TLS stack does not support TLS-based compression.</p>
<p>&xep0115; provides a mechanism for caching, and hence eliding, the disco#info requests needed to negotiate optional features.</p>
<p>&xep0237; provides a relatively widely deployed extension for reducing the roster fetch bandwidth, in most cases reducing it to a simple affirmation that the client has the current roster. This saves not only bandwidth, but also reduces local storage writes.</p>
<p>&xep0198; provides session resumption over TCP, enabling a client to handle the case where the coverage is patchy. The &lt;r/> and &lt;a/> elements also provide a keepalive facility in a small number of octets.</p>
<p>&xep0273; provides a mechanism which, amongst other things, would allow a presence "hush", buffering presence during certain states.</p>
</section1>
<section1 topic='Acknowledgements' anchor='acks'>
<p>The author is not a mobile expert, and relied on the knowledge and patient help of several others. In particular, thanks are due to Jussi Laako, Markku Vampari, and Markus Isomaki of Nokia, and Simon Tennant of Buddycloud.</p>
<p>The attribution of any mistakes herein is zealously guarded by the author, however.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>This document does not discuss a protocol, thus introduces no new security considerations.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>None.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>None.</p>
</section1>
</xep>

459
inbox/moved.xml Normal file
View File

@ -0,0 +1,459 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
<!ENTITY MOVED "&lt;moved/&gt;">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Moved</title>
<abstract>This document defines an XMPP protocol extension that enables a user to inform its contacts about a change in JID.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes>
</supersedes>
<supersededby/>
<shortname>moved</shortname>
<author>
<firstname>Tory</firstname>
<surname>Patnoe</surname>
<email>tpatnoe@cisco.com</email>
<jid>tpatnoe@cisco.com</jid>
</author>
<revision>
<version>0.0.7</version>
<date>2010-06-09</date>
<initials>tp</initials>
<remark>
<p>Modified syntax to use 'old' and 'new' attributes.</p>
</remark>
</revision>
<revision>
<version>0.0.6</version>
<date>2010-06-07</date>
<initials>tp</initials>
<remark>
<ul>
<li>Update ordering so that it recommends sending the unsubscribe/unsubscribed, before, sending the subscribe</li>
<li>Add section documenting what happens when a contact is offline when the unsubscribe/unsubscribed/subscribe stanzas are sent.</li>
<li>Added an example about a hacker sending an unsolicited subscribe by guessing a roster entry.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.0.5</version>
<date>2010-06-02</date>
<initials>tp</initials>
<remark>
<p>Added one-way subscription section</p>
</remark>
</revision>
<revision>
<version>0.0.4</version>
<date>2010-05-30</date>
<initials>tp</initials>
<remark>
<p>Change MUST NOT to SHOULD NOT for clients auto-subscribing back; differentiate between inbound and outbound subscriptions.</p>
</remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2010-06-02</date>
<initials>tp</initials>
<remark><p>Add one-way subscription comments.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2010-05-25</date>
<initials>tp</initials>
<remark><p>Minor tweaks.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2010-05-22</date>
<initials>tp</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>There are a variety of reasons why a user may wish to change
their JID. For example, a surname change because of marriage or simply
an easier JID to remember.
</p>
<p>This XEP defines an approach for communicating that your JID has
moved to a new JID, extending the existing subscription protocol documented
in &rfc3921;. The steps outlined here may be done either through a client
or automated by a server.
</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<ul>
<li>The methods described here maintain compatibility with &rfc3920; and
&rfc3921;</li>
</ul>
</section1>
<section1 topic='The Move'>
<p>In this scenario user@example.com moves to user2@example2.com.
Both the user@example.com and user2@example2.com accounts have been
created and still exist. The roster for user@example2.com is empty
and the user wants to populate it with their entries from
user@example.com.</p>
<dl>
<dt><strong>original JID</strong></dt>
<dd>user@example.com</dd>
<dt><strong>new JID</strong></dt>
<dd>user2@example2.com</dd>
</dl>
<section2 topic='Unsubscribing the original JID from outbound subscriptions'
anchor='unsubscribe'>
<p>Because the original JID is no longer going to be used, the user SHOULD
unsubscribe from all the outbound subscriptions user@example.com had.
These can be identified as those in the 'to' or 'ask' states as
defined in the 'jabber:iq:roster' protocol in &rfc3921;.</p>
<p>To unsubscribe all outbound subscriptions for the original JID send an
unsubscribe &PRESENCE; stanza to all the old contacts with a &MOVED;
element containing the new JID.</p>
<p>There is the potential for other users to send a malicious unsubscribe
containing a spoofed &MOVED; JID. Therefore, clients SHOULD NOT
automatically subscribe to the JID contained in the &MOVED; stanza when
receiving a subscribe &PRESENCE; stanza without displaying the &MOVED;
JID to the user. See the Security Considerations section for
details.</p>
<example caption='Client unsubscribes outbound subscriptions from original JID'>
<![CDATA[
<presence from='user@example.com' to='contact@example.com' type='unsubscribe'>
<status>I've changed JIDs from user@example.com to user2@example2.com</status>
<moved xmlns='urn:xmpp:moved:0' new='user2@example2.com'/>
</presence>
]]>
</example>
</section2>
<section2 topic='Unsubscribing the original JID from inbound subscriptions'
anchor='unsubscribed'>
<p>Because the original JID is no longer going to be used, the user SHOULD
unsubscribe from all contacts the user@example.com had an inbound
subscription from. These can be identified as those in the 'from'
subscription state as defined in in the 'jabber:iq:roster' protocol
in &rfc3921;.</p>
<p>To unsubscribe all inbound subscriptions send an unsubscribed
&PRESENCE; stanza to all the old contacts with a &MOVED; element
containing the new JID.</p>
<p>There is the potential for other users to send a malicious unsubscribed
containing a spoofed &MOVED; JID. Therefore, clients SHOULD NOT
automatically subscribe to the JID contained in the &MOVED; stanza
without displaying the &MOVED; JID to the user. See the Security
Considerations section for details.</p>
<example caption='Client unsubscribes inbound subscriptions from original JID'>
<![CDATA[
<presence from='user@example.com' to='contact@example.com' type='unsubscribed'>
<status>I've changed JIDs from user@example.com to user2@example2.com</status>
<moved xmlns='urn:xmpp:moved:0' new='user2@example2.com'/>
</presence>
]]>
</example>
</section2>
<section2 topic='Subscribing the new JID to all your existing contacts'
anchor='subscribe'>
<p>Once the new JID has been created on a server it is possible for the
new JID to subscribe to the contacts they had on the original JID's
roster. This is done by sending a new subscription request with a
&MOVED; element containing the new JID.
</p>
<p>The new subscription MUST come from the new JID's server.</p>
<p>There is the potential for other users to send a malicious subscribe
request and spoof the content of the &MOVED; element identifying an
original JID. Therefore, clients SHOULD NOT automatically unsubscribe
an existing roster entry if is listed as the target in the &MOVED;
element when a subscribe is received. See the Security
Consideration section for details.</p>
<p>Clients accepting the moved subscription SHOULD indicate to the
user that that this subscription request was the result of a move
operation and because of potential malicious behavior SHOULD NOT
auto-accept the subscription without displaying the &MOVED; JID to the
user.</p>
<example caption='Client requests subscription from new JID'>
<![CDATA[
<presence from='user2@example2.com' to='contact@example.com' type='subscribe'>
<status>I've changed JIDs from user@example.com to user2@example2.com</status>
<moved xmlns='urn:xmpp:moved:0' old='user@example.com'/>
</presence>
]]>
</example>
</section2>
<section2 topic='Contacts Offline at the Time the Rename Occurs'
anchor='offline'>
<p>&rfc3920bis; clarifies that an incoming subscribe &PRESENCE; stanza
MUST be preserved by the server and &PRESENCE; stanzas of type
unsubscribe and unsubscribed are not preserved on the server.
Therefore, for a contact who is offline, their servers MAY have
automatically removed the original roster entry when seeing the
unsubscribe and unsubscribed stanzas. At the time of writing this XEP,
NOT saving and forwarding the presence stanzas will be the default
behavior of most servers.
</p>
<p>What this means is that a contact coming online after the rename
outlined above MAY only see the &PRESENCE; of type 'subscribe' with
the &MOVED; element. Clients should be aware of this behavior.
</p>
</section2>
<section2 topic='Presence Ordering' anchor='ordering'>
<p>In following the principle of least surprise, it is considered good
practice to send the subscribe stanza after the unsubscribe and unsubscribed
stanzas.
</p>
</section2>
<section2 topic='Preservation of Groups' anchor='grouping'>
<p>One of the side effects of this scheme is the potential for a contact
to lose the groups to which it had organized the original JID. Clients
aware of the &MOVED; element can mitigate this with the following rules.
</p>
<ul>
<li>If the contacts client receives an unsubscribed with a &MOVED;
element, remove the subscription but initiate a roster push for the
original JID with the subscription set to 'none'. When the new
subscription is received the new JID MAY be placed into the roster
in the same groups as the original JID and the original JID can then be
removed from the roster.
</li>
<li>If a subscribe is received with a &MOVED; element, the client MAY
automatically place the new JID into the same groups as the original JID.
</li>
</ul>
<p>As discussed in 'Contacts Offline at the Time the Rename Occurs', a
server MAY automatically handle the unsubscribe and unsubscribed stanzas.
If this occurs it will be impossible to preserve the original groups.
</p>
</section2>
<section2 topic='One-way subcriptions and full roster state' anchor='one-way'>
<section3 topic='One-way Inbound subscription' anchor='from_subs'>
<p>If the original JID, user@example.com, had only an inbound subscription
(from or pending in), then the contact will only receive an
unsubscribed &PRESENCE; stanza. The contact's client, knowing the
state of the subscription (which is 'to' or 'none' with 'ask='subscribe'
from the contact's perspective), at that point MAY choose to prompt the
user to subscribe to the new JID listed in the &MOVED; element.</p>
<p>Because of the ability to spoof the &MOVED; element, the client SHOULD
NOT automatically subscribe to the &MOVED; element target, but SHOULD
present the new JID to the contact before sending out a subscription
request.</p>
</section3>
<section3 topic='One-way Outbound subscription' anchor='to_subs'>
<p>If the original JID, user@example.com, had only an outbound
subscription (to or ask), then the contact SHOULD only receive an
unsubscribe &PRESENCE; stanza. The contact's client, knowing the
state of the subscription (which is 'from' from the contact's perspective),
at that point MAY choose to prompt
the user to subscribe to the new JID listed in the &MOVED; element.</p>
<p>Because of the ability to spoof the &MOVED; element, the client SHOULD
NOT automatically subscribe to the &MOVED; element target</p>.
</section3>
<section3 topic='Roster state and action table' anchor='actions'>
<table caption="Roster states and actios from the renamed user's perspective">
<tr>
<td>Server state</td>
<td>Client state (jabber:iq:roster)</td>
<td>Send unsubscribe from original JID</td>
<td>Send unsubscribed from original JID</td>
<td>Send subscribe from new JID</td>
</tr>
<tr>
<td>none</td>
<td>none</td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td>none + pending out</td>
<td>none + ask='subscribe'</td>
<td>yes</td>
<td></td>
<td>yes</td>
</tr>
<tr>
<td>none + pending in</td>
<td>n/a</td>
<td></td>
<td>yes - server only</td>
<td></td>
</tr>
<tr>
<td>none + pending in/out</td>
<td>none + ask='subscribe'</td>
<td>yes</td>
<td>yes - server only</td>
<td>yes</td>
</tr>
<tr>
<td>to</td>
<td>to</td>
<td>yes</td>
<td></td>
<td>yes</td>
</tr>
<tr>
<td>to + pending in</td>
<td>to</td>
<td>yes</td>
<td>yes - server only</td>
<td>yes</td>
</tr>
<tr>
<td>from</td>
<td>from</td>
<td></td>
<td>yes</td>
<td></td>
</tr>
<tr>
<td>from + pending out</td>
<td>from/none + ask='subscribe'</td>
<td>yes</td>
<td>yes</td>
<td>yes</td>
</tr>
<tr>
<td>both</td>
<td>both</td>
<td>yes</td>
<td>yes</td>
<td>yes</td>
</tr>
</table>
</section3>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>It is not intended for servers to strip any &MOVED; elements from
&PRESENCE; stanzas sent in from a client. This allows clients as well as
servers to implement these same procedures.</p>
<p>In order to prevent other users from maliciously altering contacts
the client SHOULD NOT automatically subscribe to a &MOVED; JID when it
receives an unsubscribe and SHOULD NOT automatically unsubscribe to
a &MOVED; JID when it receives a subscribe.</p>
<p>The following illustrates an example malicious attack.</p>
<ol>
<li>userA@example.com subscribes to userB@example.com</li>
<li>The userB@example.com automatically accepts the subscription from
userA@example.com. (Automatically done by the client using a simple
domain trust).</li>
<li>userA@example.com unsubscribes with the &MOVED; 'new' JID set to
companyCEO@example.com.</li>
<li>The previous steps can be repeated and have userB@example.com subscribe
to a large number of people.</li>
</ol>
<p>A similar attack can be done with a new subscribe request causing users
by guessing which users are subscribed to a contact.</p>
<ol>
<li>hacker@example.com subscribes to userB@example.com guessing that
userA@example.com is on userB's roster.
<![CDATA[
<presence from='hacker@example.com' to='userB@example.com' type='subscribe'>
<status>Subscribe to me!</status>
<moved xmlns='urn:xmpp:moved:0' old='userA@example.com'/>
</presence>
]]>
</li>
<li>If userB's client automatically accepted the subscription without
displaying at prompt to userB showing the new JID to be hacker@example.com,
then the user has no idea that hacker@example.com was just added to
the roster.
</li>
</ol>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='reg'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:moved:0</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental
to a status of Draft, the &REGISTRAR; shall add the foregoing namespace
to the registry located at &NAMESPACES;, as described in Section 4 of
&xep0053;.
</p>
</section2>
<section2 topic='Protocol Versioning' anchor='registrar-versioning'>
&NSVER;
</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:moved:0'
xmlns='urn:xmpp:moved:0'
elementFormDefault='qualified'>
<xs:element name='moved'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='new' type='xs:string' use='optional'/>
<xs:attribute name='old' type='xs:string' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>The author wishes to thank Doug Abbink, Mikhail Belov, Peter Saint-Andre, and Peter Sheu for their feedback.</p>
</section1>
</xep>

258
inbox/muji.xml Executable file
View File

@ -0,0 +1,258 @@
<?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>Muji</title>
<abstract>
This specification defines an XMPP protocol extension for initiating and
managing multiparty voice and video conferences within an XMPP MUC
</abstract>
&LEGALNOTICE;
<number>proto-muji0.2</number>
<status>ProtoXep</status>
<type>Extension</type>
<sig>Standards</sig>
<approver>Telepathy project</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0045</spec>
<spec>XEP-0166</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>muji</shortname>
<author>
<firstname>Sjoerd</firstname>
<surname>Simons</surname>
<email>sjoerd.simons@collabora.co.uk</email>
<jid>sjoerd.simons@collabora.co.uk</jid>
</author>
<author>
<firstname>Dafydd</firstname>
<surname>Harries</surname>
<email>dafydd.harries@collabora.co.uk</email>
<jid>dafydd.harries@collabora.co.uk</jid>
</author>
<revision>
<version>0.0.0.2</version>
<date>2009-06-09</date>
<initials>sjoerd</initials>
<remark><p>Second rough draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
Jingle <cite>XEP-0166</cite> is used to negotiate peer to peer media sessions.
Muji is a way to coordinate Jingle sessions between a group of people.
Muji conferences are held in <cite>XEP-0045</cite> rooms.
</section1>
<section1 topic="How it works" anchor="howitworks">
A Muji conference has a number of contents, each of which has unique name.
content type, and an encoding. Each participant may provide a stream for each
content, and communicates which contents they are willing to provide streams
for, along with encoding information, in their MUC presence. This serves two
purposes. Firstly, so that each participant knows which contents every other
participant provides. Secondly, so that there is a global payload type (PT)
mapping for the various contents, so that clients only need to encode and
payload each content that they provide once.
Participants are not required to participate all the contents that are
available. For example, a Muji client might choose to only request audio
streams.
</section1>
<section1 topic='Joining a conference' anchor='joining'>
<p>
Joining a conference is done in two stages. The first step is to
declare that preparations are being done to either join or start a muji
session inside the MUC. This is indicated by the client sending a presence
stanza to the MUC with a preparing element in muji section.
<code><![CDATA[
<presence from='wiccarocks@shakespeare.lit/laptop'
to='darkcave@chat.shakespeare.lit/oldhag'>
<c xmlns="http://jabber.org/protocol/caps"
node="http://telepathy.freedesktop.org/wiki/Muji"
ver="48QdBuXRCJFb8qIzgy1FOHSGO0U="
hash="sha-1" />
<muji xmlns='http://telepathy.freedesktop.org/muji>
<preparing />
</muji>
</presence>
]]></code>
The client MUST then wait until the MUC rebroadcasts its presence message,
after which it MUST wait for all other participants that had a preparing
element in their presence to finish preparation. Afterwards it should finish
it's own preparation by updating its presence with the contents it wants to
take part in.
<code><![CDATA[
<presence from='wiccarocks@shakespeare.lit/laptop'
to='darkcave@chat.shakespeare.lit/oldhag'>
<c xmlns="http://jabber.org/protocol/caps"
node="http://telepathy.freedesktop.org/wiki/Muji"
ver="48QdBuXRCJFb8qIzgy1FOHSGO0U="
hash="sha-1" />
<muji xmlns='http://telepathy.freedesktop.org/muji'>
<content name='video'>
<description xmlns='urn:xmpp:jingle:apps:rtp:0' media='video'>
<payload-type id='97' name='theora' clockrate='90000'/>
</description>
</content>
<content creator='initiator' name='voice'>
<description xmlns='urn:xmpp:jingle:apps:rtp:0' media='audio'>
<payload-type id='97' name='speex' clockrate='8000'/>
<payload-type id='18' name='G729'/>
</description>
</content>
</muji>
</presence>
]]></code>
</p>
<p>
When a client adds a payload ID to a content description, it MUST have the
same codec name and receiving parameters as the corresponding entries in
other participants' payload maps for that content. For instance, if Alice
defines a payload type with ID 98, codec Speex and a a clock rate of 8000
for a content called “voice0”, then Bob must define payload type 98
identically or not at all for that content.
</p>
<p>
Furthermore, each content description MUST include at least one payload type
that every other participant supports. In other words, the intersection of
payload type mappings in descriptions for a content must not be the empty
set. This avoids clients having to encode the same stream multiple times,
which can be very costly, and also allows sending the encoded data only once
where the transport makes this possible (e.g. IP multicast).
</p>
<p>
Once a client has constructed content descriptions and advertised them in
its MUC presence, it MUST initiate a Jingle session with every other
participant. The requirement that it is the joining participant that
initiates sessions avoids race conditions.
</p>
<p>
Jingle sessions are initiated between the MUC JIDs of participants. That is,
the Jingle session-initiate stanza is sent from one MUC JID to another. This
allows participants to easily identify sessions as belonging to a Muji
conference. Content names inside Muji-related Jingle sessions always refer
to the content with the same name inside the Muji conference.
</p>
</section1>
<section1 topic='Leaving a conference' anchor='leaving'>
<p>
To leave a conference the Muji information MUST first be removed from the
participant's presence; subsequently it SHOULD terminate all Jingle sessions
related to that conference. Updating the presence first reduces the
likelihood of situations where new participants initiate sessions with
participants who are leaving the conference.
</p>
</section1>
<section1 topic='Adding a content' anchor='addcontent'>
<p>
Adding a stream follows a process similar to the joining a conference. As a
first step an updated presence stanza MUST be send which contains a preparing
element as part of the Muji section.
<code><![CDATA[
<presence from='wiccarocks@shakespeare.lit/laptop'
to='darkcave@chat.shakespeare.lit/oldhag'>
<c xmlns="http://jabber.org/protocol/caps"
node="http://telepathy.freedesktop.org/wiki/Muji"
ver="48QdBuXRCJFb8qIzgy1FOHSGO0U="
hash="sha-1" />
<muji xmlns='http://telepathy.freedesktop.org/muji'>
<content creator='initiator' name='voice'>
<description xmlns='urn:xmpp:jingle:apps:rtp:0' media='audio'>
<payload-type id='97' name='speex' clockrate='8000'/>
<payload-type id='18' name='G729'/>
</description>
</content>
<preparing/>
</muji>
</presence>
]]></code>
The client MUST then wait until the MUC rebroadcasts its presence message,
after which it MUST wait for all other participants that had a preparing
element in their presence to finish their changes.
Afterwards the client should add the new content to the muji section of its
presence and add the content to all the jingle sessions it had with
participants it shared the content with.
<code><![CDATA[
<presence from='wiccarocks@shakespeare.lit/laptop'
to='darkcave@chat.shakespeare.lit/oldhag'>
<c xmlns="http://jabber.org/protocol/caps"
node="http://telepathy.freedesktop.org/wiki/Muji"
ver="48QdBuXRCJFb8qIzgy1FOHSGO0U="
hash="sha-1" />
<muji xmlns='http://telepathy.freedesktop.org/muji'>
<content name='video'>
<description xmlns='urn:xmpp:jingle:apps:rtp:0' media='video'>
<payload-type id='97' name='theora' clockrate='90000'/>
</description>
</content>
<content creator='initiator' name='voice'>
<description xmlns='urn:xmpp:jingle:apps:rtp:0' media='audio'>
<payload-type id='97' name='speex' clockrate='8000'/>
<payload-type id='18' name='G729'/>
</description>
</content>
</muji>
</presence>
]]></code>
</p>
</section1>
<section1 topic='Removing a content' anchor='removecontent'>
<p>
To remove a content the participant SHOULD first sent an updated presence
without the content in its muji section. Afterwards it MUST the content from
all the jingle sessions it has open.
</p>
</section1>
<section1 topic='relays and mixers' anchor='relaysmixer'>
<p>
When scaling to conferences with a big number of participants or when
clients it's no longer viable for all participants to have direct
connections.
On connections where upstream bandwidth is the limiting factor an RTP a
RTP relay which is able to relay the stream to multiple participants on
the behalf of the clients and which forwards the streams of other
participants back to the client can be used.
If the limiting factor is either CPU or downstream bandwidth then a mixer
can be used, which receives the media streams from other participants and
mixes them on behalf of the client, so that the client only has to deal
with receiving and decoding a single stream for each media type. On the
sending side a mixer acts like a relay and relays the clients stream to all
other participants.
Both these services can either be provided by dedicated services or by
other clients.
</p>
</section1>
</xep>

3029
inbox/multi-user_gaming.xml Executable file
View File

File diff suppressed because it is too large Load Diff

163
inbox/outofband.xml Executable file
View File

@ -0,0 +1,163 @@
<?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>Out-of-Band Stream Data</title>
<abstract>This specification defines how to send parts of an XML stream over a direct connection between peers. This allows to send large stanzas or binary data without blocking the XML stream for other stanzas.</abstract>
<legal>
<copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2009 by the XMPP Standards Foundation (XSF).</copyright>
<permissions>Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the &quot;Specification&quot;), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.</permissions>
<warranty>## NOTE WELL: This Specification is provided on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##</warranty>
<liability>In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.</liability>
<conformance>This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at &lt;<link url='http://www.xmpp.org/extensions/ipr-policy.shtml'>http://www.xmpp.org/extensions/ipr-policy.shtml</link>&gt; or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).</conformance>
</legal>
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0166</spec>
<spec>XEP-0260</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
&dmeyer;
<revision>
<version>0.0.2</version>
<date>2009-03-30</date>
<initials>dm</initials>
<remark><p>Simplify Example; Restrict Usage; Add abort</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2009-03-08</date>
<initials>dm</initials>
<remark><p>First draft</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>XMPP uses one XML stream between two peers, either between client and server, between servers, or between clients directly. If a client sends a stanza to a client, either routed over the server or directly, it can not send another stanza at the same time. If an XMPP extension defines very large stanzas, the communication is blocked until this stanza is fully sent to the server. A client or server may also define a maximum stanza size for communication. A future extension to query a remote file server could create such huge stanzas: a directory listing with thousands of photos, each with additional metadata, could produce stanzas of one megabyte or longer. The same is true for TV listings of a remote TV tuner device. Besides text data, a stanza may also contain binary data Base64 encoded. This also increases the stanza size.</p>
<p>This document defines a mechanism to transmit parts of a stanza over a separate end-to-end connection using Jingle. XML data and binary data (without being Base64 encoded) can be transmitted over the external link to keep the actual XML stanza small.</p>
</section1>
<section1 topic='Protocol Flow' anchor='proto'>
<p>If a client wants to send a large stanza to a peer, it can remove large elements from the stanza and replace it with a &lt;oob/&gt; element of the 'urn:xmpp:jingle:apps:out-of-band:0' namespace. The definition of "large" depends on the use case and available bandwidth of the stream to the server. It is RECOMMENDED to send stanzas smaller than 4096 Bytes directly because the overhead of the additional stream is too high. If a client knows in advance that it will send or receive several large stanzas or binary data it SHOULD open the out-of-band data stream. One larger chunk may not be worth opening a Jingle session. A client MUST NOT send In-Band Bytestream stanzas out of band because there may be a reason why it is an In-Band Bytestream and not something else such as SOCKS5.</p>
<p>Before a client sends such a stanza to its peer, it MUST open the out of band stream first. It has to initiate a Jingle session and MUST NOT send the stanza it wants to send until the out-of-band stream is open. The following example is based on 'Discovering the Items Associated with a Jabber Entity' &xep0030;.</p>
<example caption="Requesting All Items"><![CDATA[
<iq from='hamlet@example.com/denmark'
to='hamlet@example.com/bot'
id='hfgte45w'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
]]></example>
<p>Normally we would expect the peer to answer with an IQ return stanza with the list of items. But if the listing is very large, the client may decide to send it over an extra stream. Instead of sending the IQ result, it opens a Jingle session.</p>
<example caption="Home Server Initiates Jingle Session"><![CDATA[
<iq from='hamlet@example.com/bot'
to='hamlet@example.com/denmark'
id='xn28s7gk'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'>
action='session-initiate'
initiator='hamlet@example.com/bot'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='oob'>
<description xmlns='urn:xmpp:jingle:apps:out-of-band:0'/>
<transport xmlns='urn:xmpp:jingle:transports:s5b:0'
sid='vj3hs98y'
mode='tcp'>
<streamhost
jid='hamlet@example.com/bot'
host='192.168.4.1'
port='5086'/>
</transport>
<security xmlns='urn:xmpp:jingle:security:xtls:0'>
<fingerprint>RomeoX509CertificateHash</fingerprint>
<method name='x509'/>
</security>
</content>
</jingle>
</iq>
]]></example>
<p>The clients open a Jingle session according to &xep0166; with a &xep0260;. For the sake of simplicity this protocol flow is not described here. If the clients opened the Out-of-Band Data Stream, the listing is sent over that stream and a reference is returned in the IQ result of the original request.</p>
<example caption="IQ Result with Out-of-Band Stream Data Reference"><![CDATA[
<iq from='hamlet@example.com/bot'
to='hamlet@example.com/denmark'
id='hfgte45w'
type='result'>
<oob xmlns='urn:xmpp:jingle:apps:out-of-band:0'
id='hfgte45w-1'
size='6022'
hash='sha1+552da749930852c69ae5d2141d3766b1'
type='text/xml'/>
</iq>
]]></example>
<p>The receiver MUST replace the &lt;oob/&gt; element with the content with the given id from the Out-of-Band Data Stream. The size and hash arguments are optional, the type MUST be 'text/xml' since an IQ stanza MUST have one child element. The content send out of band MUST have a valid XML header &lt;?xml version='1.0' ?&gt; with one root element. The XML header is ignored and the root element MUST replace the &lt;oob&gt; element.</p>
<p>It is possible to use out of band data everywhere in the XML stream and not only as first element child of the IQ stanza. The XML schema MUST explicit allow the usage of the &lt;oob/&gt; element; it is not possible to replace any arbitrarily part of a stanza with the &lt;oob/&gt; element. The reason for this restriction is to keep implementations simpler if they do not have to expect out of band data everywhere and to keep the stream compliant to the XML schemas.</p>
<p>If the &lt;oob/&gt; element is not the top level child of an IQ or message stanza, the type attribute does not has to be 'text/xml' and may even be omitted. In that case the content with the given id send out of band MUST be treated as if it was embedded in the XML stream using Base64 encoding. This is useful for sending larger chunks of binary data.</p>
</section1>
<section1 topic='Out-of-Band Data Stream' anchor='proto'>
<p>The Out-of-Band Data Stream multiplexes several items into one stream to re-use the stream for several XML elements or binary data without blocking the out-of-band stream with one large item. This avoids negotiating a new Jingle session for each piece of data. The syntax is similar to HTTP 1.1 chunked transfer. Each chunk of data has a one line header with the number of bytes in hex of the data and the content identifier. The last chunk of each piece of content is always a chunk with a length of 0.</p>
<example caption="Stream Data Definition"><![CDATA[
stream = *(chunk | last-chunk)
chunk = chunk-size id CRLF chunk-data CRLF
hexdig-nonzero = %x31-39 ; "1"-"9"
chunk-size = hexdig-nonzero *HEXDIG
id = *(ALPHA | DIGIT)
last-chunk = 1*("0") id CRLF CRLF
]]></example>
<p>In the given example the &lt;oob/&gt; element specifies that the query result is sent out of band and has a size of 6022 bytes. The out of band content requires a valid XML header which adds another 23 bytes. If each chunk has 4096 bytes (0x1000 in hex) the data is split into two chunks (4096 and 1949 bytes). The following data is sent over the out of band stream:</p>
<example caption="Stream Data with XEP-0030 Items"><![CDATA[
1000 hfgte45w CRLF
<?xml version='1.0' ?>
<query xmlns='http://jabber.org/protocol/disco#items'>
... 4096 Bytes including the XML header ... CRLF
79d hfgte45w CRLF
... Last 1949 Bytes ... CRLF
0 hfgte45w CRLF CRLF
]]></example>
</section1>
<section1 topic='Abort Content Sending' anchor='abort'>
<p>If a client is not not interested in the out of band data (anymore) it MAY abort the sending of a content with a given identifier to save bandwidth. This may happen for large binary data and the client was only interested in the first bytes, e.g. to detect the file type and that it can not decode it.</p>
<example caption="Abort Content"><![CDATA[
<iq from='hamlet@example.com/denmark'
to='hamlet@example.com/bot'
id='hfytewp9'
type='set'>
<abort xmlns='urn:xmpp:jingle:apps:out-of-band:0'
id='hfgte45w'/>
</iq>
]]></example>
<p>The peer SHOULD send a last chunk with the length of zero out of band and acknowledge the abortion.</p>
<example caption="Acknowledge Abort"><![CDATA[
<iq from='hamlet@example.com/bot'
to='hamlet@example.com/denmark'
id='hfytewp9'
type='result'/>
]]></example>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>The Jingle session SHOULD include TLS as specified in &xtls;. Even if the peers can not verify each others certificates, the leap of faith approach provides at least the same amount of security as if the data where send inside the XML stream.</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'>
<p>XMPP Registrar considerations will be provided in a later version of
this document.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>The XML schema will be provided in a later version of this document.</p>
</section1>
</xep>

153
inbox/problem-reporting.xml Executable file
View File

@ -0,0 +1,153 @@
<?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>Problem Reporting</title>
<abstract>This specification defines methods for reporting of network problems between XMPP server deployments.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
<discuss>operators</discuss>
<author>
<firstname>Artur</firstname>
<surname>Hefczyc</surname>
<email>artur.hefczyc@gmail.com</email>
<jid>artur.hefczyc@tigase.org</jid>
</author>
<author>
<firstname>Florian</firstname>
<surname>Jensen</surname>
<email>admin@flosoft.biz</email>
<jid>admin@im.flosoft.biz</jid>
</author>
<author>
<firstname>Mickaël</firstname>
<surname>Rémond</surname>
<email>mickael.remond@process-one.net</email>
<jid>mremond@process-one.net</jid>
</author>
&stpeter;
<author>
<firstname>Matthew</firstname>
<surname>Wild</surname>
<email>mwild1@gmail.com</email>
<jid>mwild1@jaim.at</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2009-04-13</date>
<initials>psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>As XMPP technologies have been deployed more widely, the open XMPP network has become a more significant target for attacks. This specification defines ways for XMPP server deployments to share information with each other and therefore handle such attacks in a more real-time fashion.</p>
<p>The basic approach is two-fold:</p>
<ol start='1'>
<li>Each server SHOULD mantain a list of other servers that it trusts for the purpose of problem reporting. We can think of this list as the server-to-server equivalent of a user-oriented XMPP roster.</li>
<li>When a server encounters problems (e.g., suspicious account registrations), it SHOULD send a problem report to the servers on its "roster".</li>
</ol>
</section1>
<section1 topic='Server Rosters' anchor='roster'>
<p>To establish a trust relationship with a peer, a server shall send a presence subscription request to the peer, just as is done between XMPP users.</p>
<example caption="Service sends subscription request to peer"><![CDATA[
<presence from='montague.lit'
to='capulet.lit'
type='subscribe'/>
]]></example>
<p>The XMPP server software running at the peer MUST prompt the server administrators to approve the request. Methods for doing so are out of scope for this specification.</p>
</section1>
<section1 topic='Problem Reports' anchor='report'>
<p>A problem report consists of an XMPP &MESSAGE; stanza containing a &lt;problem/&gt; child element. The following is an example.</p>
<example caption="A problem report"><![CDATA[
<message from='jabber.org' to='im.flosoft.biz'>
<problem xmlns='urn:xmpp:problem:0'
<contact>stpeter@jabber.org</contact>
<end>2009-04-13T19:27:22Z</end>
<incident>cc7b247b-18b4-4301-b6d0-e9e4016d802f</incident>
<ip>192.0.2.0</ip>
<jids>
<jid>abuser@spam.lit</jid>
<jid>loser@spam.lit</jid>
</jids>
<room>operators@conference.jabber.org</room>
<severity>2</severity>
<start>2009-04-13T19:05:20Z</start>
<text xml:lang='en'>lots of MUC spammers from abuse.lit!</text>
<type>muc</type>
</message>
]]></example>
<p>The defined child elements are as follows:</p>
<table caption='Child elements'>
<tr>
<th>Element Name</th>
<th>Description</th>
</tr>
<tr>
<td>&lt;contact/&gt;</td>
<td>The JID of a person to contact directly.</td>
</tr>
<tr>
<td>&lt;end/&gt;</td>
<td>The time when the problem ended. Send empty element if still happening. Must conform to &xep0082;</td>
</tr>
<tr>
<td>&lt;incident/&gt;</td>
<td>An incident number. MUST be a UUID as described in &rfc4122;.</td>
</tr>
<tr>
<td>&lt;ip/&gt;</td>
<td>The IP address where the problem originates.</td>
</tr>
<tr>
<td>&lt;jids/&gt;</td>
<td>Each &lt;jid/&gt; child contains the JabberID of an entity that is causing trouble.</td>
</tr>
<tr>
<td>&lt;room/&gt;</td>
<td>A chatroom where the problem can be discussed.</td>
</tr>
<tr>
<td>&lt;severity/&gt;</td>
<td>The seriousness of the problem, from 5 (least serious) to 1 (most serious).</td>
</tr>
<tr>
<td>&lt;start/&gt;</td>
<td>The time when the problem started. Send empty element if unknown.</td>
</tr>
<tr>
<td>&lt;text/&gt;</td>
<td>A natural-language description of the event. This element SHOULD possess an 'xml:lang' attribute. Multiple &lt;text/&gt; elements MAY be included, each with a different 'xml:lang' value.</td>
</tr>
<tr>
<td>&lt;type/&gt;</td>
<td>The type of problem. Defined values are "muc" for &xep0045; abuse, "pubsub" for &xep0060; abuse, "reg" for account registrations (e.g., via &xep0077;), "spam" for </td>
</tr>
</table>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>To follow.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>To follow.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>To follow.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>To follow.</p>
</section1>
</xep>

224
inbox/reputation.xml Executable file
View File

@ -0,0 +1,224 @@
<?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>Entity Reputation</title>
<abstract>This specification defines an XMPP protocol extension for communicating the reputation of any entity on the network.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</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.0.1</version>
<date>2010-01-11</date>
<initials>psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>Reputation systems are used in many online communities to increase trust and to encourage communication, commerce, and other forms of interaction. The public XMPP network might benefit from instituting a reputation system for servers, for end users, or both. The benefits might include fast blacklisting of rogue servers and other bad actors, differential quality of service based on reputation, delayed entry to &xep0045; rooms for low-reputation users, integration with &xep0016;, and the like.</p>
</section1>
<section1 topic='Terminology' anchor='terminology'>
<p>The following terms identify the entities mentioned in this document:</p>
<ul>
<li>Relying Party -- the entity that queries a Vouching Party about the reputation score of a Subject</li>
<li>Subject -- the entity whose reputation is vouched for by a Vouching Party</li>
<li>Vouching Party -- an entity that maintains a reputation score about a Subject, such as a server vouching for an account, a server vouching for a chatroom at a chat service associated with the server, a third party vouching service, etc.</li>
</ul>
</section1>
<section1 topic='Approach' anchor='approach'>
<p>The approach taken here is that an XMPP entity (a "Subject") is innocent until proven guilty, so it starts out with a score of zero. Good behaviors will increase a Subject's score (up to a maximum of +127), whereas bad behaviors will decrease a Subject's score (potentially down to a minimum of -128). Any entity (a "Relying Party") can query another entity (a "Vouching Party") about the reputation score of a Subject. A Vouching Party might be a fellow IM user (e.g., a buddy in one's roster as defined in &xmppim;), the server to which a client connects, a fellow server to which a server connects (see &xep0267;), or a specialized reputation service (similar to a DNSBL on the email network). Changes in reputation scores can also be sent in real time to Relying Parties, either as part of &xep0268; or as separate notifications.</p>
<p>To determine reputation in an objective way, it is important to define the specific behaviors that are used as measurable dimensions of good or bad reputation. The following sections attempt to do so for XMPP servers and XMPP users, with some rough point values.</p>
<section2 topic='Server Reputation' anchor='approach-server'>
<p>On the theory that it is more important to reward positive behavior than to punish negative behavior, we first define a number of criteria for increasing the reputation score of an XMPP server (naturally this list of criteria is not meant to be exclusive).</p>
<table caption='Positive Server Behaviors'>
<tr>
<th>Criterion</th>
<th>Suggested Point Value</th>
</tr>
<tr>
<td>Presents a certificate issued by a recognized certification authority.</td>
<td>+15</td>
</tr>
<tr>
<td>Requires CAPTCHAs or other hurdles for account registration (see &xep0158;).</td>
<td>+5</td>
</tr>
<tr>
<td>Supports <cite>XEP-0268: Incident Reporting</cite>.</td>
<td>+5</td>
</tr>
<tr>
<td>Supports reputation scores for its users (i.e., this protocol).</td>
<td>+5</td>
</tr>
<tr>
<td>Requires use of Transport Layer Security (TLS) for client-to-server connections.</td>
<td>+5</td>
</tr>
<tr>
<td>Provides the _xmpp-client DNS SRV record.</td>
<td>+5</td>
</tr>
<tr>
<td>Provides the _xmpp-server DNS SRV record.</td>
<td>+5</td>
</tr>
<tr>
<td>Provides a website with accurate information and contact addresses.</td>
<td>+5</td>
</tr>
<tr>
<td>Service answers &xep0030; information requests sent to bare JIDs, including identification of admin accounts and anonymous users.</td>
<td>+5</td>
</tr>
<tr>
<td>Administrator answers email sent to mailto:xmpp@domain.tld (see &xmppcore;) and takes appropriate actions to solve reported issues.</td>
<td>+5</td>
</tr>
<tr>
<td>Time online (e.g., based on whois lookup or known deployment of an XMPP service).</td>
<td>+3 for each year</td>
</tr>
<tr>
<td>Admin factor (average of admins' reputation scores, divided by ten and rounded up).</td>
<td>Varies</td>
</tr>
</table>
<p>For example, a server that (1) meets all of the foregoing criteria, (2) has been online for 7 years, and (3) whose admins have an average score of 37 would have a reputation number of 15+5+5+5+5+5+5+5+5+5+4+21 = 85.</p>
<p>By constrast, a server that does not have a CA-issued cert, does not require CAPTCHAs for account registration, does not support incident reporting, does not support reputation scores, does not require TLS, does have SRV records (+10), has no website, does not answer service discovery requests about its users, has not verified the xmpp@domain.tld email address, has been online for 1 week, and whose administrators are unknown would have a reputation score of 10.</p>
</section2>
<section2 topic='Account Reputation' anchor='approach-account'>
<p>The reputation associated with an XMPP account (typically but not always a user) is harder to quantify and easier to fake than server reputation. The following are some possible criteria.</p>
<table caption='Positive Account Behaviors'>
<tr>
<th>Criterion</th>
<th>Suggested Point Value</th>
</tr>
<tr>
<td>Account has service discovery identity of account/admin</td>
<td>+15</td>
</tr>
<tr>
<td>Account has service discovery identity of account/registered</td>
<td>+5</td>
</tr>
<tr>
<td>Age of account</td>
<td>+5 for each year</td>
</tr>
<tr>
<td>Verified email address</td>
<td>+5</td>
</tr>
<tr>
<td>Verified website</td>
<td>+5</td>
</tr>
<tr>
<td>Password strength</td>
<td>Measured on a scale from 0 (e.g., "password") to 5</td>
</tr>
<tr>
<td>Reputation of buddies known to server</td>
<td>Divide average reputation by 10</td>
</tr>
<tr>
<td>User has PGP key, X.509 certificate, or other public key</td>
<td>+10</td>
</tr>
<tr>
<td>User has passed a CAPTCHA test (e.g., during account provisioning)</td>
<td>+5</td>
</tr>
<tr>
<td>Chatroom ownership / administration</td>
<td>For each room owned, divide room's reputation by 10; for each room administered, divide room's reputation by 20 (e.g., +6 and +3 for a room with a reputation of 60).</td>
</tr>
<tr>
<td>Chatroom banning</td>
<td>For each room in which the user is banned (XEP-0045 "outcast"), divide the room's reputation by 10 and decrement the user's score by the result (e.g., -6 for a room with a reputation of 60).</td>
</tr>
<tr>
<td>Rate limiting</td>
<td>For each rate limiting incident, -5.</td>
</tr>
<tr>
<td>Incident reports</td>
<td>For each validated incident report, -10.</td>
</tr>
</table>
<p>For example, an account that is an admin of a server (+15), has been online for 5 years (+25), has a verified email address (+5) and website (+5), has a strong password (+5), has a "buddy reputation average" of 40 (+4), uses a public key (+10), has passed a CAPTCHA test (+5), owns 3 chatrooms with an average reputation of 30 (+9), and has not been banned from any chatrooms, rate limited, or been the subject of any incident reports would have a reputation number of 83.</p>
<p>By contrast, an account that is registered (+5), was just created, has no verified email address or website, has a strong password (+5), has a "buddy reputation average" of 10 (+1), does not use a public key, has not passed a CAPTCHA test, owns or administers no chatrooms, has been banned from 3 chatrooms with an average reputation of 30 (-9), has been rate limited twice (-10), and has been the subject of 2 incident reports (-20) would have a reputation number of -28.</p>
</section2>
<section2 topic='Other Entities' anchor='approach-other'>
<p>Any entity can have a reputation score: servers, end-user accounts, chatrooms, chatroom servers, publish-subscribe servers, vouching services, etc. Criteria for entities other than servers and accounts are yet to be described.</p>
</section2>
</section1>
<section1 topic='Protocol' anchor='protocol'>
<p>In order to query a Vouching Party about the reputation of a Subject, a Relying Party sends an IQ stanza of type "get" containing a &lt;score/&gt; element qualified by the 'urn:xmpp:reputation:0' namespace &VNOTE;.</p>
<example caption='Score request'><![CDATA[
<iq from='juliet@capulet.lit/chamber'
to='shakespeare.lit'
id='bn4c297j'
type='get'>
<score xmlns='urn:xmpp:reputation:0' jid='romeo@montague.lit'/>
</iq>
]]></example>
<p>The Vouching Party would then return an error or a score.</p>
<example caption='Score response'><![CDATA[
<iq from='shakespeare.lit'
to='juliet@capulet.lit/chamber'
id='bn4c297j'
type='result'>
<score xmlns='urn:xmpp:reputation:0'
jid='romeo@montague.lit'
num='65'/>
</iq>
]]></example>
<p>Any XMPP error might be appropriate (e.g., &forbidden; if the Relying Party is not trusted at all by the Vouching Party).</p>
</section1>
<section1 topic='Determining Support' anchor='support'>
<p>To advertise its support for reputation scores, when replying to &xep0030; information requests an entity MUST return a feature for 'urn:xmpp:reputation:0'.</p>
<p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>Any entity can keep a reputation score for any other entity. Although some entities might be considered more knowledgeable than others, that judgment is up to the entity that makes a request for a reputation score and is not a feature of the network itself.</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'>
<p>To follow.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>To follow.</p>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Dan Brickley, Kevin Smith, Mike Taylor, and Matthew Wild for their feedback.</p>
</section1>
</xep>

90
inbox/server-rosters.xml Executable file
View File

@ -0,0 +1,90 @@
<?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>Server Rosters</title>
<abstract>This specification defines a convention for trust between XMPP server deployments.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
<discuss>operators</discuss>
<author>
<firstname>Artur</firstname>
<surname>Hefczyc</surname>
<email>artur.hefczyc@gmail.com</email>
<jid>artur.hefczyc@tigase.org</jid>
</author>
<author>
<firstname>Florian</firstname>
<surname>Jensen</surname>
<email>admin@flosoft.biz</email>
<jid>admin@im.flosoft.biz</jid>
</author>
<author>
<firstname>Mickaël</firstname>
<surname>Rémond</surname>
<email>mickael.remond@process-one.net</email>
<jid>mremond@process-one.net</jid>
</author>
&stpeter;
<author>
<firstname>Matthew</firstname>
<surname>Wild</surname>
<email>mwild1@gmail.com</email>
<jid>mwild1@jaim.at</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2009-04-30</date>
<initials>ah/fj/psa/mr/mw</initials>
<remark><p>First draft, split from the incident reporting proposal.</p></remark>
</revision>
</header>
<section1 topic='Description' anchor='description'>
<p>In XMPP, rosters and presence subscriptions have been used to date only among IM users (see &xmppim;). However, nothing prevents the application of these concepts to other XMPP entities, such as components and servers. Given that a presence subscription typically indicates some level of trust in a peer, server deployments can use the sharing of XMPP presence information as a way to indicate that a given server has a trust relationship with a peer server. The server might then share certain kinds of additional information only with trusted peers (for example, incident reports).</p>
<p>To establish a trust relationship with a peer, a server shall send a presence subscription request to the peer, just as is done between XMPP users.</p>
<example caption="Service sends subscription request to peer"><![CDATA[
<presence from='montague.lit'
to='capulet.lit'
type='subscribe'/>
]]></example>
<p>A server MUST NOT send such a presence subscription request unless explicitly requested to do so by the server administrator(s).</p>
<p>Upon receiving such a presence subscription request, the XMPP server software running at the peer MUST prompt the server administrator(s) to approve the request, rather than automatically approving it. Methods for doing so are out of scope for this specification.</p>
<p>If the server administrator(s) approve the request, the peer server shall then inform the originating server that the request has been approved.</p>
<example caption="Peer sends approval to server"><![CDATA[
<presence from='capulet.lit'
to='montague.lit'
type='subscribed'/>
]]></example>
<p>The peer SHOULD also send a subscription request to the originating server.</p>
<example caption="Peer sends subscription request to server"><![CDATA[
<presence from='capulet.lit'
to='montague.lit'
type='subscribe'/>
]]></example>
<p>If an XMPP server implementation supports this usage of presence subscriptions, it MUST keep a list of approved entities, which we denote a "server roster". The implementation MAY use that roster for access control purposes defined in other specifications.</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>
</xep>

170
inbox/shared-bosh.xml Executable file
View File

@ -0,0 +1,170 @@
<?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>Shared BOSH</title>
<abstract>This specification defines an extension to BOSH that allows multiple clients to share the same underlying XMPP connection.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0124</spec>
<spec>XEP-0206</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
<author>
<firstname>Jack</firstname>
<surname>Moffitt</surname>
<email>jack@metajack.im</email>
<jid>metajack@gmail.com</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2009-05-13</date>
<initials>Jack</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>XMPP-powered applications which run inside of Web browsers typically use &xep0124; to create a link to an XMPP server. Unfortunately Web applications do not have control over some interactions, such as a user opening a link in a new tab. This means that an application can end up with multiple simultaneous BOSH connections, each of which is a fully addressable XMPP endpoint. Complex applications often need to share some state, and managing this over an arbitrary number of individual connections can be problematic.</p>
<p>This specification defines a mechanism for a connection manager to allow multiple clients to share the same underlying XMPP connection. Additionally, the connection manager will notify all clients of inbound stanzas. Similar functionality exists in specific areas of the XMPP protocol; for example, roster changes are broadcast to all connected resources so each resource can keep roster state synchronized.</p>
<p>As an example, consider an application which is open in two tabs (or two windows) in a Web browser. In the first tab, the application subscribes to some pubsub node it is interested in. The BOSH connection manager would send this subscription request to the other connected clients (in this case, just the second tab) so that they are aware that a subscription has been requested. When the subscription acknowledgement is received by the connection manager, it will broadcast it to all clients.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>Shared BOSH must meet the following requirements:</p>
<ul>
<li>Broadcast outgoing stanzas to all shared clients</li>
<li>Broadcast incoming stanzas from a shared client to the other shared clients</li>
<li>Protect against unauthorized or uninteded sharing of the underlying connection</li>
</ul>
<p>In addition to these, the intention is for this extension to be easy to implement in current BOSH implementations.</p>
</section1>
<section1 topic='Protocol Flow' anchor='protoflow'>
<p>In order to establish a sharable connection which is then shared across two clients, the following steps take place. The mechanism for sharing the secret below is just one possible mechanism.</p>
<ol start='1'>
<li>Client A initiates a BOSH session and indicates that this session is sharable via the 'shared:key' attribute.</li>
<li>Client A authenticates with the XMPP server and publishes the secret key to a private PEP node.</li>
<li>Client B initiates a BOSH sesion and indicates that this session is sharable via the 'shared:key' attribute.</li>
<li>Client B authenticates with the XMPP server and discovers Client A's existing secret key in the PEP node.</li>
<li>Client B terminates the BOSH connection and initiates a new one, using the discovered secret key as the value of the 'shared:key' attribute in the initial &lt;body/&gt; tag.</li>
<li>The connection manager verifies the key and allows Client B to share Client A's XMPP connection.</li>
</ol>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Creating a Sharable Connection' anchor='creation'>
<p>A client can create a sharable BOSH connection by providing the 'shared:key' attribue to the connection manager in the initial &lt;body/&gt; element.</p>
<example caption='Creating the connection'>
<![CDATA[POST /webclient HTTP/1.1
Host: www.example.com
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 304
<body content='text/xml; charset=utf-8'
hold='1'
rid='1573741820'
to='example.com'
ver='1.6'
wait='60'
shared:key='3c1d69981b65bfbd641dcb64c82bb613'
xmlns:shared='urn:xmpp:tmp:shared-bosh:0'
xml:lang='en'
xmlns='http://jabber.org/protocol/httpbind'/>]]>
</example>
<p>If the connection manager supports sharable connections, it will include the 'shared:result' attribute in its response. Since this is a new sharable connection and not an attachment to an existing sharable connection, the value of the 'shared:result' attribute is 'created'.</p>
<example caption='Sharable connection created succesfully'>
<![CDATA[HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 354
<body wait='60'
inactivity='30'
polling='5'
requests='2'
hold='1'
accept='deflate,gzip'
maxpause='120'
sid='d96c53d08d0d7b96d5d4ac0e402424ab'
ver='1.6'
from='example.com'
shared:result='created'
xmlns:shared='urn:xmpp:tmp:shared-bosh:0'
xmlns='http://jabber.org/protocol/httpbind'/>]]>
</example>
<p>If the connection manager does not support this extension, it will ignore the 'shared:key' attribute and will not include one in its response.</p>
</section2>
<section2 topic='Attaching to a Shared Connection' anchor='attaching'>
<p>Attaching to a connection is performed in the same manner as creating a sharable connection. The client provides the secret key of an existing connection as the value of the 'shared:key' attribute. If the key matches, the connection manager will respond with a 'shared:result' attribute with a value of 'attached'.</p>
<example caption='Attached to a Shared Connection'>
<![CDATA[HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 355
<body wait='60'
inactivity='30'
polling='5'
requests='2'
hold='1'
accept='deflate,gzip'
maxpause='120'
sid='d96c53d08d0d7b96d5d4ac0e402424ab'
ver='1.6'
from='example.com'
shared:result='attached'
xmlns:shared='urn:xmpp:tmp:shared-bosh:0'
xmlns='http://jabber.org/protocol/httpbind'/>]]>
</example>
</section2>
</section1>
<section1 topic='Inbound Traffic Delivery' anchor='inbound-delivery'>
<p>In order to easily maintain state across shared BOSH clients, the connection manager must deliver inbound traffic to the server from one client to all the other clients sharing the connection. Applications which use shared connections must be written so that they can deal with this extra traffic; they cannot assume that all stanzas received are outbound.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<section2 topic='Shared Secrets' anchor='shared-secret'>
<p>In order to protect against unauthorized or unintended connection sharing, this specification uses a shared secret. It is important that this secret be hard to guess and long enough that it is resistant to brute force attack.</p>
</section2>
<section2 topic='Storage of the Secret' anchor='store-secret'>
<p>It is necessary for a client to communicate the shared secret to the other clients. Since Web browser security policy prevents most ways of achieving this, it is necessary to store the secret somewhere the other clients can find this. Implementors must be care that this storage is robust to attack.</p>
<p>Two options are recommended for secret storage:</p>
<ol start='1'>
<li><p>Generate the secret on the server side (for example, in the Web application framework that generates your HTML pages). Please note that the secret should not be transmitted alongside the HTML as this would allow anyone reading the HTML to share the connection. Instead, the BOSH connection should be bootstrapped before page delivery.</p></li>
<li><p>Generate the secret on the client side, and store it within the XMPP server using some available mechanism. For example, a client could use &xep0049; or a private &xep0163; node.</p></li>
</ol>
</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'>
<p>This XEP proposes the namespace 'urn:xmpp:tmp:shared-bosh:0' be added to the registry.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>To follow.</p>
</section1>
</xep>

132
inbox/sic.xml Executable file
View File

@ -0,0 +1,132 @@
<?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>Server IP Check</title>
<abstract>This specification defines a simple XMPP extension that enables a client to discover its external IP address.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>sic</shortname>
&stpeter;
<revision>
<version>0.0.2</version>
<date>2009-03-10</date>
<initials>psa</initials>
<remark><p>Removed client inclusion of its IP address; added IPv6 example.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2009-03-10</date>
<initials>psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>There are times when a client might want or need to discover what its external Internet Protocol (IP) address is, e.g. when gathering transport candidates for &xep0065; or &xep0176;. One way to do so is for the client to ask the XMPP server to which it has connected. This simple specification defines such a method.</p>
</section1>
<section1 topic='Protocol' anchor='proto'>
<p>First the client sends an IQ-get request to its server.</p>
<example caption="Client requests its IP address from the server"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='ik2s7159'
type='get'>
<ip xmlns='urn:xmpp:sic:0'/>
</iq>
]]></example>
<p>The server then returns an IQ-result containing an &lt;ip/&gt; element whose XML character data specifies the client's IP address according to the server.</p>
<example caption="Server returns IP address"><![CDATA[
<iq id='ik2s7159'
to='romeo@montague.lit/orchard'
type='result'>
<ip xmlns='urn:xmpp:sic:0'>192.168.4.1</ip>
</iq>
]]></example>
<p>The IP address could be IPv4 or IPv6.</p>
<example caption="Server returns IPv6 address"><![CDATA[
<iq id='ik2s7159'
to='romeo@montague.lit/orchard'
type='result'>
<ip xmlns='urn:xmpp:sic:0'>2001:db8::9:1</ip>
</iq>
]]></example>
</section1>
<section1 topic='Determining Support' anchor='support'>
<p>If an entity supports this protocol, it MUST report that by including a service discovery feature of "urn:xmpp:sic:0" in response to disco#info requests &NSNOTE;.</p>
<example caption="Service discovery information request"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='ux71f395'
to='montague.lit'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption="Service discovery information response"><![CDATA[
<iq from='montague.lit'
id='ux71f395'
to='romeo@montague.lit/orchard'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='urn:xmpp:sic:0'/>
</query>
</iq>
]]></example>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>&rfc3920; specifies that client IP addresses shall not be made public. If a client requests its own IP address, that policy is not violated. However, a server MUST NOT return the IP address of another client (e.g., if a connected client sends a SIC request to the bare JID of another user); instead, it MUST return a &forbidden; error.</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='registrar-ns'>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:sic:0</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2>
<section2 topic='Protocol Versioning' anchor='registrar-versioning'>
&NSVER;
</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:sic:0'
xmlns='urn:xmpp:sic:0'
elementFormDefault='qualified'>
<xs:element name='ip' type='xs:string'/>
</xs:schema>
]]></code>
</section1>
<section1 topic='Acknowledgements' anchor='acks'>
<p>Thanks to Thiago Camargo and Diana Cionoiu for their prodding to define this extension.</p>
</section1>
</xep>

608
inbox/sift.xml Executable file
View File

@ -0,0 +1,608 @@
<?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>Stanza Interception and Filtering Technology</title>
<abstract>This specification defines an XMPP protocol extension that enables a client to exercise control over the XML stanzas it will receive from the server by instructing the server to intercept and filter inbound stanzas.</abstract>
&LEGALNOTICE;
<number>XXXX</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
&hildjj;
&metajack;
&stpeter;
<revision>
<version>0.0.8</version>
<date>2009-08-14</date>
<initials>psa</initials>
<remark><p>Clarified service and feature discovery processes, error flows, and other small matters in the text.</p></remark>
</revision>
<revision>
<version>0.0.7</version>
<date>2009-08-11</date>
<initials>psa</initials>
<remark><p>Defined IQ-get for retrieving supported SIFT features; added support for sifting based on sender type; removed restriction on matching against only the bare JID of the recipient and defined support for sifting on the bare JID, full JID, or both.</p></remark>
</revision>
<revision>
<version>0.0.6</version>
<date>2009-05-19</date>
<initials>jjh/psa</initials>
<remark><p>Added requirements section; clarified relation to negative presence priorities.</p></remark>
</revision>
<revision>
<version>0.0.5</version>
<date>2009-05-18</date>
<initials>jjh/psa</initials>
<remark><p>More clearly distinguished between interception and filtering usages; clarified business rules.</p></remark>
</revision>
<revision>
<version>0.0.4</version>
<date>2009-05-18</date>
<initials>psa/jjh</initials>
<remark><p>Added information about service discovery; clarified several small matters in the text.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2009-05-15</date>
<initials>psa/jjh</initials>
<remark><p>Clarified that SIFT applies to interception of message and presence stanzas directed to the bare JID and to filtering of IQ stanzas directed to the full JID; corrected syntax to match those semantics; added use cases; defined XML schema.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2009-05-14</date>
<initials>psa</initials>
<remark><p>Slight clarifications and corrections.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2009-05-14</date>
<initials>jjh/jm/psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>In some scenarios a client might want to control the XML stanzas it will receive over its stream with the server. Some potential use cases include:</p>
<ul>
<li>A mobile client might want to receive messages but not presence notifications, since the latter are quite "chatty" and can run down the battery.</li>
<li>A softphone might want to receive IQ stanzas only if the payload is qualified by an XML namespace related to the use of &xep0166; for Internet telephony.</li>
<li>A presence compositor might want to receive presence updates but not message stanzas or IQ stanzas, and only from the user's own resources (i.e., not from other entities).</li>
</ul>
<p>The following taxonomy of client types is not exhaustive but might assist developers in understanding the scenarios in which SIFT might be useful.</p>
<table caption='Client Types Categorized by Sending Presence, Receiving Presence, and Receiving Messages'>
<tr>
<th>Type</th>
<th>Sends Presence</th>
<th>Receives Presence</th>
<th>Receives Messages</th>
</tr>
<tr>
<td>Normal User</td>
<td align='center'>Yes</td>
<td align='center'>Yes</td>
<td align='center'>Yes</td>
</tr>
<tr>
<td>Invisible User</td>
<td align='center'>No</td>
<td align='center'>Yes</td>
<td align='center'>Yes</td>
</tr>
<tr>
<td>Large-Scale Bot</td>
<td align='center'>Yes</td>
<td align='center'>No</td>
<td align='center'>Yes</td>
</tr>
<tr>
<td>Presentity</td>
<td align='center'>Yes</td>
<td align='center'>Yes</td>
<td align='center'>No</td>
</tr>
<tr>
<td>Presence Watcher</td>
<td align='center'>No</td>
<td align='center'>Yes</td>
<td align='center'>No</td>
</tr>
<tr>
<td>Presence Publisher</td>
<td align='center'>Yes</td>
<td align='center'>No</td>
<td align='center'>No</td>
</tr>
<tr>
<td>Message Subscriber</td>
<td align='center'>No</td>
<td align='center'>No</td>
<td align='center'>Yes</td>
</tr>
<tr>
<td>Message Publisher</td>
<td align='center'>No</td>
<td align='center'>No</td>
<td align='center'>No</td>
</tr>
</table>
<p>Note: Although &rfc3921; specifies the use of a negative presence priority to block inbound message delivery, it does not enable the client to block inbound presence notifications, filter inbound IQ stanzas, or otherwise exercise fine-grained control over the delivery of inbound stanzas. While it would be possible to define particular values of negative presence priorities for some delivery control methods (e.g., &lt;priority&gt;-2&lt;priority&gt; could be hardcoded to mean "don't send me messages or presence"), that would be an ugly hack and thus inconsistent with &xep0134;. Therefore, this specification defines a stanza interception and filtering technology (a.k.a. "SIFT") that is more consistent with the underlying design of XMPP.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>The SIFT protocol is designed to meet the following requirements.</p>
<ol start='1'>
<li>Make it possible for a client to disable receipt of all inbound presence notifications while still receiving message and IQ stanzas if desired.</li>
<li>Make it possible for a client to disable receipt of all inbound message stanzas while still receiving presence and IQ stanzas if desired.</li>
<li>Make it possible for a client to disable receipt of all inbound IQ stanzas while still receiving presence and message stanzas if desired.</li>
<li>Make it possible for a client to receive only inbound presence, message, or IQ stanzas that contain a payload matching a particular element name and XML namespace.</li>
<li>Make it possible for a client to "sift" based on all senders, local vs. remote senders, or other senders vs. oneself.</li>
<li>Make it possible for a client to "sift" based on whether the recipient is the user's bare JID or the particular client's full JID.</li>
<li>Enable future extensibility based on regular expressions, XPath expressions, etc.</li>
</ol>
</section1>
<section1 topic='Protocol' anchor='protocol'>
<p>The SIFT protocol is used to <em>intercept</em> or <em>filter</em> inbound stanzas only, not outbound stanzas sent by the client to the server or other entities. By "intercept" is meant that the server will not deliver any such stanza kind (message, presence, or IQ) to the client, and by "filter" is meant that the server will apply a rule to determine if the specific stanza will be delivered to the client (e.g., matching against a payload namespace); in general we refer to these actions as "sifting". The SIFT protocol enables the server to support only basic interception (even here to support interception only for particular kinds of stanzas), basic filtering as defined by the rules described in this specification, or advanced filtering using extensions to SIFT defined in other specifications. Each of the features supported by the server can be discovered by the client for maximum interoperability. The features, the process for discovering them, and the process for enabling them are described in the following sections.</p>
<section2 topic='Features' anchor='features'>
<p>SIFT supports the following features.</p>
<section3 topic='Stanza Kinds' anchor='features-stanzas'>
<p>A server MAY support any combination of sifting IQ, message, or presence stanzas. For each kind of stanza that can be sifted, the server shall include in the features discovery result an &lt;iq-sift/&gt;, &lt;message-sift/&gt;, or &lt;presence-sift/&gt; element, respectively.</p>
<dl>
<di>
<dt>iq-sift</dt>
<dd>The server enables the client to sift all &IQ; stanzas or ones that match the specified criteria.</dd>
<dt>message-sift</dt>
<dd>The server enables the client to sift all &MESSAGE; stanzas or ones that match the specified criteria.</dd>
<dt>presence-sift</dt>
<dd>The server enables the client to sift all &PRESENCE; stanzas or ones that match the specified criteria.</dd>
</di>
</dl>
</section3>
<section3 topic='Sender' anchor='features-sender'>
<p>A server MAY enable the client to sift based on sender. The following values are supported.</p>
<dl>
<di>
<dt>all</dt>
<dd>The server shall sift this kind of stanza no matter who the sender is. This is the <strong>default</strong>.</dd>
<dt>local</dt>
<dd>The server shall sift this kind of stanza only from entities associated with the same local domain as the user itself (not from remote domains).</dd>
<dt>others</dt>
<dd>The server shall sift this kind of stanza only from other entities (not from the user itself).</dd>
<dt>remote</dt>
<dd>The server shall sift this kind of stanza only from entities associated with remote domains (not from the same local domain as the user itself).</dd>
<dt>self</dt>
<dd>The server shall sift this kind of stanza only from the user itself (not from other entities).</dd>
</di>
</dl>
<p>These values are child elements of the &lt;iq-sift/&gt;, &lt;message-sift/&gt;, and &lt;presence-sift/&gt; elements when the server returns a features discovery result, whereas they are values of the 'sender' attribute when the client enables sift support.</p>
</section3>
<section3 topic='Recipient' anchor='features-recipient'>
<p>A server MAY enable the client to filter based on recipient. The following values are supported.</p>
<dl>
<di>
<dt>all</dt>
<dd>The server shall sift this kind of stanza if the recipient is the bare JID &LOCALBARE; of the user or the full JID &LOCALFULL; of the particular resource. This is the <strong>default</strong>.</dd>
<dt>bare</dt>
<dd>The server shall sift this kind of stanza only if the recipient is the bare JID &LOCALBARE; of the user.</dd>
<dt>full</dt>
<dd>The server shall sift this kind of stanza only if the recipient is the full JID &LOCALFULL; of the particular resource.</dd>
</di>
</dl>
<p>These values are child elements of the &lt;iq-sift/&gt;, &lt;message-sift/&gt;, and &lt;presence-sift/&gt; elements when the server returns a features discovery result, whereas they are values of the 'recipient' attribute when the client enables sift support.</p>
</section3>
<section3 topic='Payload' anchor='features-payload'>
<p>A server MAY enable the client to sift based on the XML namespace and element name of the payload(s) that the client allows for delivery. If so, the server shall include in the features discovery result an &lt;allow/&gt; element for the relevant kind of stanza.</p>
</section3>
<section3 topic='Advanced Matching' anchor='features-advanced'>
<p>A server could match based on more complex criteria, e.g. Regular Expressions or XPath Expressions; such functionality is implicitly allowed because the XML schema specifies the &lt;xs:any/&gt; notation, but any such advanced matching shall be defined in separate specifications.</p>
</section3>
</section2>
<section2 topic='Discovering Supported Features' anchor='discovering'>
<p>If a server supports the SIFT protocol, it MUST advertise that fact in its responses to &xep0030; information ("disco#info") requests by returning a feature of "urn:xmpp:sift:1":</p>
<example caption='A disco#info query'><![CDATA[
<iq type='get'
from='romeo@montague.lit/pda'
to='montague.lit'
id='bf4vb167'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption='A disco#info response'><![CDATA[
<iq type='result'
from='montague.lit'
to='romeo@montague.lit/pda'
id='bf4vb167'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='urn:xmpp:sift:1'/>
</query>
</iq>
]]></example>
<p>This response enables the client to know that the server supports SIFT in general, but particular SIFT features. In order to discover which SIFT features are supported, a client sends an IQ-get containing a &lt;features/&gt; element qualified by the 'urn:xmpp:sift:1' namespace.</p>
<example caption="Client requests SIFT support details"><![CDATA[
<iq from='romeo@montague.lit/pda'
id='bn4hf91g'
to='montague.lit'
type='get'>
<features xmlns='urn:xmpp:sift:1'/>
</iq>
]]></example>
<p>The server then returns a list of the particular SIFT features it supports.</p>
<example caption="Server provides details regarding SIFT support"><![CDATA[
<iq from='montague.lit'
id='bn4hf91g'
to='romeo@montague.lit/pda'
type='result'>
<features xmlns='urn:xmpp:sift:1'>
<message-sift>
<recipient>
<all/>
</recipient>
<senders>
<all/>
<others/>
</senders>
</message-sift>
<presence-sift>
<recipient>
<all/>
</recipient>
<senders>
<all/>
<others/>
</senders>
</presence-sift>
</features>
</iq>
]]></example>
<p>The foregoing IQ-result indicates that montague.net supports only message and presence sifting, allows the client to filter those kinds of stanzas only from all entities or from other entities (but not from local entities, remote entities, or itself), allows the client to filter those kinds of stanzas only to <em>both</em> the bare JID and full JID (but not to the bare JID or the full JID alone), and does not support filtering based on payload.</p>
<p>Naturally, the server could return the typical XMPP error conditions, such as &unavailable; if the server does not support the SIFT protocol or the version specified by the client.</p>
</section2>
<section2 topic='Enabling SIFT' anchor='enabling'>
<p>To enable sifting of stanzas, the client sends an IQ-set to the server containing a &lt;sift/&gt; child element that in turn contains an &lt;iq/&gt; element, a &lt;message/&gt; element, a &lt;presence/&gt; element, or some combination of those elements. Each of these elements MAY include a 'recipient' attribute whose value is "all", "bare", or "full" (defaulting to "all"). Each of these elements MAY also include a 'sender' attribute whose value is "all", "local", "others", "remote", or "self" (defaulting to "all").</p>
<p>Note: The last SIFT request sent from the client to the server overrides all previous SIFT requests; SIFT requests are not cumulative. Therefore, each SIFT request needs to contain all the SIFT rules that the client wishes the server to enforce, not a delta from the previous request.</p>
<example caption="Sifting of message and presence stanzas"><![CDATA[
<iq from='romeo@montague.lit/pda'
id='rv491g37'
to='romeo@montague.lit'
type='set'>
<sift xmlns='urn:xmpp:sift:1'>
<message sender='others'/>
<presence/>
</sift>
</iq>
]]></example>
<p>The foregoing IQ-set means "sift messages from others and presence from all senders, no matter if the recipient is my bare JID or my full JID".</p>
<p>Each of the child elements &IQ;, &MESSAGE;, and &PRESENCE; MAY also contain one or more &lt;allow/&gt; children whose 'name' attribute specifies the element name and whose 'ns' attribute specifies the XML namespace of stanza payloads the client would like to allow. If no &lt;allow/&gt; elements are included, then sifting of that kind of stanza is completed without reference to the payload.</p>
<example caption="Sifting for particular IQ payloads"><![CDATA[
<iq from='romeo@montague.lit/pda'
id='bs01jg75'
to='romeo@montague.lit'
type='set'>
<sift xmlns='urn:xmpp:sift:1'>
<iq>
<allow name='jingle' ns='urn:xmpp:jingle:1'/>
<allow name='query' ns='http://jabber.org/protocol/disco#info'/>
</iq>
<message/>
</sift>
</iq>
]]></example>
<p>The foregoing IQ-set means "filter out inbound IQ stanzas except if the payload matches &lt;jingle xmlns='urn:xmpp:jingle:1'/&gt; or &lt;query xmlns='http://jabber.org/protocol/disco#info'/&gt;".</p>
<p>In XMPP, an IQ stanza can contain only one payload element, so the filtering logic is straightforward. However, a message or presence stanza can contain multiple payload elements (cf. &xep0226;). Therefore, filtering for message and presence stanzas means that if the stanza contains the defined payload or payloads (perhaps in addition to other payloads), the server shall deliver it to the client.</p>
<p>For instance, the following example shows how a client would filter inbound messages and IQs to only receive SOAP payloads as specified in &xep0072;.</p>
<example caption="Sifting for SOAP"><![CDATA[
<iq from='romeo@montague.lit/pda'
id='cid143n9'
to='romeo@montague.lit'
type='set'>
<sift xmlns='urn:xmpp:sift:1'>
<iq>
<allow name='Envelope' ns='http://www.w3.org/2003/05/soap-envelope'/>
</iq>
<message>
<allow name='Envelope' ns='http://www.w3.org/2003/05/soap-envelope'/>
</message>
</sift>
</iq>
]]></example>
<p>Similarly, the following example shows how a client would filter inbound presence notifications to only receive notifications that contain entity capabilities data as specified in &xep0115;.</p>
<example caption="Sifting for entity capabilities"><![CDATA[
<iq from='romeo@montague.lit/pda'
id='zl2f36d8'
to='romeo@montague.lit'
type='set'>
<sift xmlns='urn:xmpp:sift:1'>
<presence>
<allow name='c' ns='http://jabber.org/protocol/caps'/>
</presence>
</sift>
</iq>
]]></example>
<p>Naturally, the server could return the typical XMPP error conditions, such as &unavailable; if the server does not support the SIFT protocol or the version specified by the client, &feature; if the server does not support a particular feature (e.g., &IQ; sifting) requested by the client, &badrequest; if the request is malformed, &internalserver; if the server experiences a malfunction while attempting to process the request, and so on.</p>
</section2>
</section1>
<section1 topic='Business Rules' anchor='rules'>
<section2 topic='Handling Presence Stanzas' anchor='rules-presence'>
<p>When the client indicates that it wishes to receive inbound presence notifications, the server SHOULD send outbound presence probes on the client's behalf. Responses to these presence probes are addressed to the bare JID of the account and then broadcasted to all of the resources that have expressed interest in receiving inbound presence notifications.</p>
<p>If the client subsequently indicates that it wants the server to intercept inbound presence notifications, the server MUST NOT deliver to the client presence notifications that are addressed to the bare JID or full JID as defined by the 'recipient' attribute.</p>
<p>If the client then indicates again that it wishes to receive inbound presence notifications, the server shall resynchronize the client regarding the presence states of its contacts (how it does so is implementation-specific, e.g. whether it queues received presence notifications or re-probes the user's contacts).</p>
</section2>
<section2 topic='Handling Message Stanzas' anchor='rules-message'>
<p>When a client indicates that it wishes to receive messages, the server SHOULD deliver to the client all messages in the offline message queue and MUST deliver to the client any subsequent messages that would normally be delivered to the client in accordance with the rules defined in &xmppcore; and &xmppim;.</p>
<p>If the client subsequently indicates that it wants the server to intercept inbound messages (and there are no other connected or available resources that have expressed interest in receiving inbound messages), the server SHOULD treat messages as if there were no connected or available resources (e.g., storing them offline for later delivery); if the client then indicates again that it wishes to receive inbound messages, the server SHOULD send those queued messages to the client so that it can get back in sync regarding messages received from its contacts.</p>
</section2>
<section2 topic='Handling IQ Stanzas' anchor='rules-iq'>
<p>If the client does not request filtering of inbound IQ stanzas, the server MUST pass through to the client all IQ stanzas that are addressed to the full JID of the client (subject to appropriate security controls as defined in the relevant RFCs and XEPs).</p>
<p>If the client requests filtering of inbound IQ stanzas, for unfiltered payload name+namespace combinations the server MUST pass through to the client all IQ stanzas that are addressed to the full JID of the client (subject to appropriate security controls as defined in the relevant RFCs and XEPs), whereas for filtered payload name+namespace combinations the server MUST respond to all IQ stanzas in a way consistent with the specification for the given payload namespace (if defined) or as specified in &xmppcore; and &xmppim; for IQs where no full JID &LOCALFULL; matches; typically that means returning a &unavailable; error.</p>
</section2>
<section2 topic='Lack of Sifting' anchor='rules-none'>
<p>Naturally, if the server advertises support for the SIFT protocol but the client does not send any IQ-set stanzas containing SIFT payloads, the server MUST proceed as it normally would in accordance with the core XMPP specifications.</p>
</section2>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Invisibility' anchor='invisibility'>
<p>In order to be invisible at the start of a session, a client can register for (i.e., not request interception of) inbound messages and presence notifications without sending initial presence.</p>
<example caption="Staying invisible"><![CDATA[
<iq from='romeo@montague.lit/pda'
id='mxi371g9'
to='romeo@montague.lit'
type='set'>
<sift xmlns='urn:xmpp:sift:1'/>
</iq>
]]></example>
<p>The server would then probe the user's contacts and return the resulting presence notifications to the client, as well as allow inbound message and IQ stanzas.</p>
<p>If the user wants to "go visible", the client will send initial presence.</p>
<example caption="Going visible"><![CDATA[
<presence/>
]]></example>
<p>The user can later go invisible again by sending presence of type "unavailable" without modifying the SIFT rules or closing the stream.</p>
<example caption="Going invisible"><![CDATA[
<presence type='unavailable'/>
]]></example>
</section2>
<section2 topic='Negative Presence Priority' anchor='priority'>
<p>RFC 3921 defines the concept of negative values for the presence &lt;priority/&gt; element, where a negative value instructs the server to not deliver to the client any messages that are directed to the bare JID of the user. This behavior can be emulated using SIFT by asking the server to intercept inbound message stanzas for the bare JID, but not presence notifications or IQ stanzas.</p>
<example caption="Emulating negative presence priority"><![CDATA[
<iq from='romeo@montague.lit/pda'
id='zkd71d37'
to='romeo@montague.lit'
type='set'>
<sift xmlns='urn:xmpp:sift:1'>
<message recipient='bare'/>
</sift>
</iq>
]]></example>
<p>If a client requests message sifting, but sends presence, it SHOULD specify a negative priority as a hint to contacts.</p>
</section2>
<section2 topic='Presence Hush' anchor='nopresence'>
<p>Because inbound presence notifications can be "chatty", mobile clients and other entities with limited battery life might want to "hush" the presence session by asking the server to intercept inbound presence notifications but not message stanzas.</p>
<example caption="Hushing the presence session"><![CDATA[
<iq from='romeo@montague.lit/pda'
id='uh2s64g9'
to='romeo@montague.lit'
type='set'>
<sift xmlns='urn:xmpp:sift:1'>
<presence/>
</sift>
</iq>
]]></example>
</section2>
</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='reg'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:sift:1</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2>
<section2 topic='Protocol Versioning' anchor='registrar-versioning'>
&NSVER;
</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:sift:1'
xmlns='urn:xmpp:sift:1'
elementFormDefault='qualified'>
<xs:element name='features'>
<xs:complexType>
<xs:sequence>
<xs:element name='iq-sift'
type='featureElementType'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='message-sift'
type='featureElementType'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='presence-sift'
type='featureElementType'
minOccurs='0'
maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='sift'>
<xs:complexType>
<xs:sequence>
<xs:element name='iq'
type='siftElementType'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='message'
type='siftElementType'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='presence'
type='siftElementType'
minOccurs='0'
maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='featureElementType'>
<xs:complexType>
<xs:sequence>
<xs:element name='recipient'
type='recipientElementType'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='sender'
type='senderElementType'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='allow'
type='allowElementType'
minOccurs='0'
maxOccurs='unbounded'/>
<xs:any namespace='##other'
minOccurs='0'
maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='siftElementType'>
<xs:complexType>
<xs:sequence>
<xs:element name='allow'
type='allowElementType'
minOccurs='0'
maxOccurs='unbounded'/>
<xs:any namespace='##other'
minOccurs='0'
maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='recipient'
use='optional'
default='all'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='all'/>
<xs:enumeration value='bare'/>
<xs:enumeration value='full'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name='sender'
use='optional'
default='all'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='all'/>
<xs:enumeration value='local'/>
<xs:enumeration value='others'/>
<xs:enumeration value='remote'/>
<xs:enumeration value='self'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name='recipientElementType'>
<xs:complexType>
<xs:sequence>
<xs:element name='all'
type='empty'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='bare'
type='empty'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='full'
type='empty'
minOccurs='0'
maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='senderElementType'>
<xs:complexType>
<xs:sequence>
<xs:element name='all'
type='empty'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='local'
type='empty'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='others'
type='empty'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='remote'
type='empty'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='self'
type='empty'
minOccurs='0'
maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name='allowElementType'>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='name'
type='xs:NCName'
use='required'/>
<xs:attribute name='ns'
type='xs:anyURI'
use='required'/>
</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>
<section1 topic='Acknowledgements' anchor='acks'>
<p>The authors wish to acknowledge feedback received from Dave Cridland, Jack Erwin, Waqas Hussein, Craig Kaes, Dirk Meyer, Robert Quattlebaum, Mike Taylor, Matthew Wild, and Jiří Zárevúcký, as well as from the participants at XMPP Summit 7 on July 20-21, 2009.</p>
</section1>
</xep>

1044
inbox/sxe.xml Executable file
View File

File diff suppressed because it is too large Load Diff

211
inbox/thumbs.xml Executable file
View File

@ -0,0 +1,211 @@
<?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>File Transfer Thumbnails</title>
<abstract>This specification defines a way for a client supply a preview image for a file transfer.</abstract>
<legal>
<copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2009 by the XMPP Standards Foundation (XSF).</copyright>
<permissions>Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the &quot;Specification&quot;), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.</permissions>
<warranty>## NOTE WELL: This Specification is provided on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##</warranty>
<liability>In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.</liability>
<conformance>This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at &lt;<link url='http://www.xmpp.org/extensions/ipr-policy.shtml'>http://www.xmpp.org/extensions/ipr-policy.shtml</link>&gt; or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).</conformance>
</legal>
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0001</spec>
<spec>XEP-0096</spec>
<spec>XEP-0231</spec>
<spec>XEP-0234</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>thumbs</shortname>
<author>
<firstname>Marcus</firstname>
<surname>Ludblad</surname>
<email>ml@update.uu.se</email>
<jid>mlundblad@jabber.org</jid>
</author>
<revision>
<version>0.0.3</version>
<date>2009-03-10</date>
<initials>ml</initials>
<remark><p>Split use-case section into "Introduction", "Requirements", and "Use case".</p>
</remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2009-02-25</date>
<initials>ml</initials>
<remark><p>Removed service disovery.
Added missing namespace on thumnail elements.</p>
</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2009-02-23</date>
<initials>ml</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='introduction'>
<p>The current methods for file transfers include basic meta data about the
file being offered (name, size, and date). There currently is no way to provide an image thumbnail for files such as photos.</p>
</section1>
<section1 topic='Requirements' anchor='requirements'>
<p>This documents defines a way to include a thumbnail image as an additional metadata in a file transfer.</p>
</section1>
<section1 topic='Use Case' anchor='usecase'>
<p>When a client wishes to supply a thumbnail in a transfer offer, it can do so by including an extra <![CDATA[<thumbnail/>]]> element as show in the following exaples.</p>
<example caption='Inclusion of a thumbnail in SI file transfer offer'><![CDATA[
<iq type='set' id='offer1' to='receiver@jabber.org/resource'>
<si xmlns='http://jabber.org/protocol/si'
id='a0'
mime-type='image/jpeg'
profile='http://jabber.org/protocol/si/profile/file-transfer'>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='image.jpg'
size='3032449'>
<thumbnail xmlns='urn:xmpp:thumbs:0'
cid='sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org'
mime-type='image/png'
width='128'
height='96'/>
</file>
<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>
</field>
</x>
</feature>
</si>
</iq>
]]>
</example>
<p>The receiver MAY now request the data using the protocol defined in XEP-0231.</p>
<example caption='Inclusion of a thumbnail in a Jingle file transfer offer'><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='nzu25s8'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:1'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='image.jpg'
size='3032449'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
<thumbnail xmlns='urn:xmpp:thumbs:0'
cid='sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org'
mime-type='image/png'
width='128'
height='96'/>
</file>
</offer>
</description>
...
</content>
</jingle>
</iq>
]]>
</example>
<section2 topic='Definition of the thumbnail Element'
anchor='thumbnail_element'>
<p>The following attributes are defined for the &lt;thumbnail/&gt; element.</p>
<table caption='Attributes of the thumbnail Element'>
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Inclusion</th>
</tr>
<tr>
<td>cid</td>
<td>A Content-ID that can be mapped to a cid: URL as specified in &rfc2111;. The 'cid' value SHOULD be of the form algo+hash@bob.xmpp.org, where the "algo" is the hashing algorithm used (e.g., "sha1" for the SHA-1 algorithm as specified in &rfc3174;) and the "hash" is the hex output of the algorithm applied to the binary data itself.</td>
<td>REQUIRED</td>
</tr>
<tr>
<td>mime-type</td>
<td>The value of the 'mime-type' attribute MUST match the syntax specified in &rfc2045;. That is, the value MUST include a top-level media type, the "/" character, and a subtype; in addition, it MAY include one or more optional parameters (e.g., the "audio/ogg" MIME type in the example shown below includes a "codecs" parameter as specified in &rfc4281;). The "type/subtype" string SHOULD be registered in the &ianamedia;, but MAY be an unregistered or yet-to-be-registered value.</td>
<td>RECOMMENDED</td>
</tr>
<tr>
<td>width</td>
<td>The intended display width of the thumbnail image. Used as a hint for the receiving client to prepare i.e. a dialog window.</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>height</td>
<td>The intended display height of the thumbnail image. Used as a hint for the receiving client to prepare i.e. a dialog window.</td>
<td>OPTIONAL</td>
</tr>
</table>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>The inclusion of an image thumbnail may leak information about a transfer
otherwise taking place on an e2e encrypted file transfer stream. A client MAY
wish to not include a thumbnail.</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='registrar-ns'>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:thumbs:0</li>
</ul>
<p>The &REGISTRAR; includes this namespace in the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2>
<section2 topic='Protocol Versioning' anchor='registrar-versioning'>
<p>If the protocol defined in this specification undergoes a major revision that is not fully backward-compatible with an older version, or that contains significant new features, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of <cite>XEP-0053</cite>.</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:thumbs:0'
xmlns='urn:xmpp:thumbs:0'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
xxx
</xs:documentation>
</xs:annotation>
<xs:element name='thumbnail'>
<xs:complexType>
<xs:attribute name='cid' type='xs:string' use='required'/>
<xs:attribute name='mime-type' type='xs:string' use='optional'/>
<xs:attribute name='width' type='xs:integer' use='optional'/>
<xs:attribute name='height' type='xs:integer' use='optional'/>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</xep>

321
inbox/tictactoe-mug.xml Executable file
View File

@ -0,0 +1,321 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
<!ENTITY FEATURE "&lt;feature/&gt;">
<!ENTITY NAME "&lt;name/&gt;">
<!ENTITY MOVE "&lt;move/&gt;">
<!ENTITY TURN "&lt;turn/&gt;">
<!ENTITY GAME "&lt;game/&gt;">
<!ENTITY xep-mug "<span class='ref'><link url='http://pidgin-games.sourceforge.net/xep/multi-user_gaming.html'>Multi-User Gaming</link></span> <note>XEP-xxxx: Multi-User Gaming &lt;<link url='http://pidgin-games.sourceforge.net/xep/multi-user_gaming.html'>http://pidgin-games.sourceforge.net/xep/multi-user_gaming.html</link>&gt;.</note>" >
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Server-based Tic-tac-toe</title>
<abstract>This document defines how to play a Tic-tac-toe game over XMPP</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-xxxx</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>Not yet assigned</shortname>
<author>
<firstname>Arne</firstname>
<surname>König</surname>
<email>arne.ko(&#228;t)23inch.de</email>
<jid>arne++(&#228;t)jabber.ccc.de</jid>
</author>
<author>
<firstname>G&#252;nther</firstname>
<surname>Nie&#223;</surname>
<email>guenther.niess(&#228;t)web.de</email>
<jid>niess(&#228;t)jabber.ccc.de</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2009-03-14</date>
<initials>ak</initials>
<remark>
<p>First Draft.</p>
</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>
It is quite common to play games over IM networks.
Since Tic-tac-toe is a well-known and simple game,
it's a good example for a server-based game protocol.
</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>
This document addresses the requirements for a game protocol as defined by &xep-mug;.
In particular this consists of:
</p>
<ol start='1'>
<li>game roles</li>
<li>match state</li>
<li>turns</li>
<li>match configuration</li>
<li>conditions for interrupting and terminating a match</li>
</ol>
<p>
The extensions needed to implement these requirements are qualified by the 'http://jabber.org/protocol/mug/tictactoe' namespace.
</p>
</section1>
<section1 topic='Discovering Support' anchor='support'>
<p>
An entity implementing this protocol MUST also support &xep-mug; and answer to disco requests accordingly
including both the Multi-User Gaming and the game &FEATURE; elements in the response.
</p>
<example caption='Service Informs Juliet That It is Capable of Hosting Tic-tac-toe'><![CDATA[
<iq type='result'
from='games.shakespeare.lit'
id='disco1'
to='juliet@capulet.com/garden'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://jabber.org/protocol/mug'/>
<feature var='http://jabber.org/protocol/mug/tictactoe'/>
...
</query>
</iq>
]]></example>
</section1>
<section1 topic='Game Roles' anchor='roles'>
<p>
A Tic-tac-toe game uses two game roles, "x" and "o".
Both roles have to be assigned to exactly one player to start a match.
If one role gets unassigned or a player gets unavailable the match has to be paused.
</p>
</section1>
<section1 topic='Match Configuration' anchor='config'>
<p>
A service SHOULD offer a configuration form with the following options:
</p>
<ol start='1'>
<li>starting role ("mug/tictactoe#config_first")</li>
<li>size of the board ("mug/tictactoe#config_rows" and "mug/tictactoe#config_cols")</li>
<li>the number of marks in a row needed to win ("mug/tictactoe#config_first")</li>
</ol>
<p>
An implementation MUST be able to handle the a board with three cols and rows
and three respective marks to win.
Everything beyond that is OPTIONAL.
</p>
<example caption='Service Sends Configuration Form'><![CDATA[
<iq from='tictactoe@games.shakespeare.lit'
id='config1'
to='juliet@capulet.com/garden'
type='result'>
<query xmlns='http://jabber.org/protocol/mug#owner'>
<options>
<x xmlns='jabber:x:data' type='form'>
<title>Tic-tac-toe Room</title>
...
</x>
<options xmlns='http://jabber.org/protocol/mug/tictactoe'>
<x xmlns='jabber:x:data' type='form'>
<title>Configuration for Tic-tac-toe</title>
<instructions>
Below you can see the default configuration.
To accept the default configuration, click OK.
To select a different configuration, please complete this form.
</instructions>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/mug/tictactoe#tictactoeconfig</value>
</field>
<field label='Number of rows' var='mug/tictactoe#config_rows' type='list-single'>
<value>3</value>
<option label='3'><value>3</value></option>
<option label='4'><value>4</value></option>
<option label='5'><value>5</value></option>
<option label='6'><value>6</value></option>
<option label='7'><value>7</value></option>
<option label='8'><value>8</value></option>
<option label='9'><value>9</value></option>
<option label='10'><value>10</value></option>
</field>
<field label='Number of cols' var='mug/tictactoe#config_cols' type='list-single'>
<value>3</value>
<option label='3'><value>3</value></option>
<option label='4'><value>4</value></option>
<option label='5'><value>5</value></option>
<option label='6'><value>6</value></option>
<option label='7'><value>7</value></option>
<option label='8'><value>8</value></option>
<option label='9'><value>9</value></option>
<option label='10'><value>10</value></option>
</field>
<field label='Strike' var='mug/tictactoe#config_strike' type='list-single'>
<value>3</value>
<option label='3'><value>3</value></option>
<option label='4'><value>4</value></option>
<option label='5'><value>5</value></option>
<option label='6'><value>6</value></option>
<option label='7'><value>7</value></option>
<option label='8'><value>8</value></option>
<option label='9'><value>9</value></option>
<option label='10'><value>10</value></option>
</field>
<field label='Select a role who start the game' var='mug/tictactoe#config_first' type='list-single'>
<value>x</value>
<option label='x'><value>x</value></option>
<option label='o'><value>o</value></option>
</field>
</x>
</options>
</options>
</query>
</iq>
]]></example>
<p>
Submitting a strike option value bigger than the number of rows or columns SHOULD
result in &notacceptable; error.
</p>
</section1>
<section1 topic='Match State' anchor='state'>
<p>
The state in a Tic-tac-toe match represents the match configuration,
the player who makes the next turn
and the current state of the board. Every state is distributed to all occupants.
</p>
<example caption='Service Sends Start State'><![CDATA[
<presence
from='tictactoe@games.shakespeare.lit'
to='juliet@capulet.com/garden'>
<game xmlns='http://jabber.org/protocol/mug'>
<status>inactive</status>
<state xmlns='http://jabber.org/protocol/mug/tictactoe'>
<rows>3</rows>
<cols>3</cols>
<strike>3</strike>
<next>x</next>
<board/>
</state>
</game>
</presence>
]]></example>
<p>
After a valid turn, the state gets updated with the corresponding mark.
</p>
<example caption='Service Sends Mid-Game State'><![CDATA[
<presence
from='tictactoe@games.shakespeare.lit'
to='juliet@capulet.com/garden'>
<game xmlns='http://jabber.org/protocol/mug'>
<status>active</status>
<state xmlns='http://jabber.org/protocol/mug/tictactoe'>
<rows>3</rows>
<cols>3</cols>
<strike>3</strike>
<next>o</next>
<board>
<field row='1' col='1'>x</field>
<field row='2' col='1'>o</field>
<field row='2' col='2'>x</field>
<field row='1' col='3'>o</field>
<field row='2' col='3'>x</field>
</board>
</state>
</game>
]]></example>
<p>
The match is considered terminated when the board is full or
when one player reaches the number of respective marks as defined by the strike option.
After termination the service broadcasts the final state including either a &lt;draw&gt;
or &lt;won&gt; (including a game role) element to indicate the resulting score
and the initial state of the next round.
</p>
<example caption='Service Sends Draw State'><![CDATA[
<presence
from='tictactoe@games.shakespeare.lit'
to='juliet@capulet.com/garden'>
<game xmlns='http://jabber.org/protocol/mug'>
<status>inactive</status>
<state xmlns='http://jabber.org/protocol/mug/tictactoe'>
<rows>3</rows>
<cols>3</cols>
<strike>3</strike>
<next>o</next>
<board/>
<won>x</won>
</state>
</game>
</presence>
]]></example>
</section1>
<section1 topic='Turns' anchor='turn'>
<p>
During the game, players change in turn, each of them MUST send only one move at a time.
It MUST possess these attributes:
<table caption='&MOVE; attributes'>
<tr>
<td><strong>Name</strong></td>
<td><strong>Type</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>'id'</td>
<td>REQUIRED</td>
<td>The number of the move. First move is 1.</td>
</tr>
<tr>
<td>'row'</td>
<td>REQUIRED</td>
<td>The horizontal position of the mark.</td>
</tr>
<tr>
<td>'col'</td>
<td>REQUIRED</td>
<td>The vertical position of the mark.</td>
</tr>
</table>
</p>
<example caption='Juliet Sends a Move'><![CDATA[
<message
to='tictactoe@games.shakespeare.lit'
from='juliet@capulet.com/garden'
type='chat'>
<turn xmlns='http://jabber.org/protocol/mug#user'>
<move
xmlns='http://jabber.org/protocol/mug/tictactoe'
row='3'
col='2'
id='7'/>
</turn>
</message>
]]></example>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>
The author is not aware of any security issues introduced by this protocol extension.
</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'>
<p>The &REGISTRAR; shall include 'http://jabber.org/protocol/mug/tictactoe' in its registry of protocols.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
</section1>
</xep>

230
inbox/tictactoe.xml Executable file
View File

@ -0,0 +1,230 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
<!ENTITY FEATURE "&lt;feature/&gt;">
<!ENTITY NAME "&lt;name/&gt;">
<!ENTITY MOVE "&lt;move/&gt;">
<!ENTITY TURN "&lt;turn/&gt;">
<!ENTITY GAME "&lt;game/&gt;">
<!ENTITY xep-game "<span class='ref'><link url='http://pidgin-games.sourceforge.net/xep/instant-gaming.html'>Instant Gaming</link></span> <note>XEP-xxxx: Instant Gaming &lt;<link url='http://pidgin-games.sourceforge.net/xep/instant-gaming.html'>http://pidgin-games.sourceforge.net/xep/instant-gaming.html</link>&gt;.</note>" >
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Tic-tac-toe</title>
<abstract>This document defines how to play a Tic-tac-toe game over XMPP</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-xxxx</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>Not yet assigned</shortname>
<author>
<firstname>Torsten</firstname>
<surname>Grote</surname>
<email>Torsten.Grote(&#228;t)fsfe.de</email>
<jid>Torsten.Grote(&#228;t)jabber.fsfe.org</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2009-03-14</date>
<initials>tg</initials>
<remark>
<p>First Draft.</p>
</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>
It is quite common to play games over IM networks.
Since Tic-tac-toe is a well known game, XMPP needs a protocol to support it.
</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>
This protocol should provide all means to play a regular game of Tic-tac-toe over XMPP.
</p>
<p>
Tic-tac-toe is also one of the simplest games and played "just for fun".
Therefore no validation support is needed.
The typical duration is below one minute and the matches are not of great interest for non-players.
Therefore spectators do not have to be supported as well.
That is why this document only describes the protocol to play a Tic-tac-toe as a One-to-One match
without support for game saving and resuming.
</p>
</section1>
<section1 topic='Discovering Support' anchor='support'>
<p>
An entity implementing this protocol MUST also support &xep-game; and answer to disco requests accordingly
including both the Instant Gaming and the game &FEATURE; elements in the response.
</p>
<example caption='Juliet Informs Romeo That She is Capable of Playing Tic-tac-toe'><![CDATA[
<iq type='result'
from='juliet@capulet.com/garden'
to='romeo@montague.net/balcony'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://jabber.org/protocol/games'/>
<feature var='http://jabber.org/protocol/games/tictactoe'/>
...
</query>
</iq>]]></example>
</section1>
<section1 topic='Invitation' anchor='invite'>
<p>
When inviting to a game of Tic-tac-toe, an entity SHOULD use &xep0004; to specify game options in the REQUIRED &GAME; element.
Possible options are "role" (of the inviting player), "rows" (height), "cols" (width) and "strike" (number of marks in a row needed to win).
If these options are missing, all but role default to '3' and role defaults to 'x'.
An implementation MUST be able to handle the default values.
Everything beyond that is OPTIONAL.
</p>
<example caption='Romeo Invites Juliet'><![CDATA[
<message
from='romeo@montague.net/garden'
to='juliet@capulet.com/balcony'>
<thread>juliet@capulet.com-romeo@montague.net-tictactoe-1591-02-23T11:36:25Z-4321</thread>
<invite xmlns='http://jabber.org/protocol/games'
transport='one-to-one'
type='new'>
<reason>
Hello Juliet,
would you like to play a little game?
</reason>
<game var='http://jabber.org/protocol/games/tictactoe'>
<x xmlns='jabber:x:data' type='submit'>
<field type='list-single' var='role'>
<value>x</value>
</field>
<field type='text-single' var='rows'>
<value>3</value>
</field>
<field type='text-single' var='cols'>
<value>3</value>
</field>
<field type='text-single' var='strike'>
<value>3</value>
</field>
</x>
</game>
</invite>
</message>]]></example>
<p>
When sending an invitation of type "renew",
the role option MUST be changed to the opposite of the role the inviting player had in the previous match with that match ID.
So both players essentially switch their roles.
All other options MUST stay the same.
</p>
</section1>
<section1 topic='Game Flow' anchor='flow'>
<p>
During the game, players change in turn, each of them sending one move at a time.
The player with the role 'x' makes the first move.
A game move is represented as a &MESSAGE; stanza addressed to the full JID of the other player.
It MUST have a &THREAD; child element which specifies the match ID.
Furthermore, the &MESSAGE; stanza contains a &TURN; element which in turn contains exactly one &MOVE; element
qualified by 'http://jabber.org/protocol/games/tictactoe'.
It MUST possess these attributes:
<table caption='&MOVE; attributes'>
<tr>
<td><strong>Name</strong></td>
<td><strong>Type</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>'id'</td>
<td>REQUIRED</td>
<td>The number of the move. First move is 1.</td>
</tr>
<tr>
<td>'row'</td>
<td>REQUIRED</td>
<td>The horizontal position of the mark.</td>
</tr>
<tr>
<td>'col'</td>
<td>REQUIRED</td>
<td>The vertical position of the mark.</td>
</tr>
</table>
</p>
<example caption='Part of the Match Between Romeo and Juliet'><![CDATA[
<message
from='romeo@montague.net/room'
to='juliet@capulet.com/room'
type='chat'>
<thread>juliet@capulet.com-romeo@montague.net-tictactoe-1591-02-23T11:36:25Z-4321</thread>
<turn xmlns='http://jabber.org/protocol/games'>
<move xmlns='http://jabber.org/protocol/games/tictactoe'
row='2'
col='2'
id='1'/>
</turn>
</message>
<message
from='juliet@capulet.com/room'
to='romeo@montague.net/room'
type='chat'>
<thread>juliet@capulet.com-romeo@montague.net-tictactoe-1591-02-23T11:36:25Z-4321</thread>
<turn xmlns='http://jabber.org/protocol/games'>
<move xmlns='http://jabber.org/protocol/games/tictactoe'
row='2'
col='3'
id='2'/>
</turn>
</message>]]></example>
</section1>
<section1 topic='Game Termination' anchor='term'>
<p>
Notifying the players whether they have won or lost is in responsibility of the game client.
The game is considered terminated when the board is full, i.e. nine moves have been made.
For further termination conditions see the appropriate section of &xep-game;.
</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>
The author is not aware of any security issues introduced by this protocol extension.
</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'>
<p>The &REGISTRAR; shall include 'http://jabber.org/protocol/games/tictactoe' in its registry of protocols.</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/games/tictactoe'
xmlns='http://jabber.org/protocol/games/tictactoe'
elementFormDefault='qualified'>
<xs:element name='move'>
<xs:complexType>
<xs:attribute name='col' type='positiveInteger'/>
<xs:attribute name='row' type='positiveInteger'/>
<xs:attribute name='id' type='positiveInteger'/>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</xep>

394
inbox/xtls.xml Executable file
View File

@ -0,0 +1,394 @@
<?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>XMPP Transport Layer Security</title>
<abstract>This document specifies the XMPP Transport Layer Security (XTLS) protocol. XTLS, which provides communications privacy for the Extensible Messaging and Presence Protocol (XMPP), enables XMPP applications to communicate in a way that is designed to prevent eavesdropping, tampering, and forgery of XMPP stanzas. XTLS is based on Transport Layer Security (TLS) and provides equivalent security guarantees. The protocol sends standard TLS handshake and application data encoded as Base64, similar to the XMPP In-Band Bytestreams (IBB) extension but qualified by a dedicated namespace.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>RFC 4346</spec>
<spec>XEP-0250</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
<author>
<firstname>Dirk</firstname>
<surname>Meyer</surname>
<email>dmeyer@tzi.de</email>
<jid>dmeyer@jabber.org</jid>
</author>
&stpeter;
&infiniti;
<revision>
<version>0.0.5</version>
<date>2008-12-11</date>
<initials>dm/psa</initials>
<remark>
<ul>
<li>By popular demand, resurrected the proposal.</li>
<li>Removed IBB dependency and replaced it with a similar method in the XTLS namespace.</li>
<li>Added explicit proceed and closed elements in the IQ-result stanzas.</li>
<li>Removed seq attribute.</li>
<li>Moved offer semantics from XEP-0250 to this specification.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.0.4</version>
<date>2008-06-06</date>
<initials>psa</initials>
<remark>
<ul>
<li>Modified initial handshake to use dedicated namespace instead of child of IBB &lt;open/&gt; element.</li>
<li>Referred to rfc3920bis for certificate generation and validation guidelines.</li>
<li>Added security considerations regarding denial of service attacks.</li>
<li>Completed editorial review.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2008-06-06</date>
<initials>dm</initials>
<remark>
<ul>
<li>Removed harcoding of the IBB sid.</li>
<li>Added conflict handling on open.</li>
<li>Added close.</li>
<li>Updated text regarding CertificateRequest.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2008-06-05</date>
<initials>dm/jk</initials>
<remark>
<ul>
<li>Modified to use In-Band Bytestreams as the transport.</li>
<li>Use IQ result for some messages during the handshake.</li>
<li>Added alternative handshake for TLS session resume.</li>
<li>Added TLS error handling.</li>
<li>Changed the namespace.</li>
<li>Added note that Offline Sessions are not supported.</li>
<li>Added note that a user can verify the fingerprint later.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2007-10-30</date>
<initials>psa</initials>
<remark><p>First draft, based on suggestions from Eric Rescorla.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>End-to-end encryption of traffic sent over the Extensible Messaging and Presence Protocol (XMPP) is a desirable goal. The Jabber/XMPP developer community has experimented with several such technologies, including OpenPGP (&xep0027;), S/MIME (&rfc3923;), and encrypted sessions or "ESessions" (&xep0218;). For various reasons, these technologies have not been widely implemented and deployed. When the &XSF; asked various Internet security experts to complete a security review of encrypted sessions, it was recommended to explore the possibility of instead using the Transport Layer Security (TLS; see &rfc4346;) as the base technology for end-to-end encryption XMPP traffic. That possibility is explored in this document.</p>
<p>TLS is the most widely implemented protocol for securing network traffic. In addition to applications in the email infrastructure, the World Wide Web (HTTP Over TLS; see &rfc2818;), and datagram transport for multimedia session negotiation (DTLS; see &rfc4347;), TLS is used in XMPP to secure TCP connections from client to server and from server to server, as specified in &xmppcore;. Therefore TLS is already a familiar technology for many XMPP developers.</p>
<p>The basic idea behind XTLS is that two XMPP entities negotiate an encrypted "tunnel" between themselves over XMPP. The tunnel is negotiated using standard TLS handshake data, contained in XMPP &IQ; stanzas and encapsulated as Base64-encoded payloads of a &lt;data/&gt; element qualified by a dedicated namespace. The entities can then exchange TLS-encrypted XMPP stanzas over that tunnel.</p>
<p>XTLS is not limited to client-to-client encryption, since it can be used between two XMPP clients, between an XMPP client and a remote XMPP service (i.e., a service with which a client does not have a direct XML stream, such as a &xep0045; chatroom), or between two remote XMPP services.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>It is intended that this specification will address the requirements specified in &xep0210;, or some reasonable subset thereof (yet to be defined). However, there is no guarantee that this specification addresses those requirements in its current form. Detailed analysis will need to be performed in order to determine whether XTLS meets the full requirements for end-to-end encryption of XMPP traffic.</p>
</section1>
<section1 topic='Glossary' anchor='glossary'>
<p>In XTLS, the initiator functions as a TLS client and the responder functions as a TLS server.</p>
</section1>
<section1 topic='Protocol' anchor='proto'>
<section2 topic='Agreeing to Use XTLS' anchor='start'>
<p>To start the use of XTLS, the initiator sends an IQ-set containing a &lt;start/&gt; element qualified by the 'urn:xmpp:tmp:xtls' namespace &NSNOTE;.</p>
<example caption='Initiating XTLS'><![CDATA[
<iq from='romeo@montague.net/orchard'
id='xtls_1'
to='juliet@capulet.com/balcony'
type='set'>
<start xmlns='urn:xmpp:tmp:xtls'/>
</iq>
]]></example>
<p>(Note: This is the functional equivalent of the &lt;starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'/&gt; command for direct XML streams as specified in <cite>RFC 3920</cite>.)</p>
<p>If the responder supports XTLS and agrees to start the use of XTLS, it returns an IQ-result containing a &lt;proceed/&gt; element qualified by the 'urn:xmpp:tmp:xtls' namespace &NSNOTE;.</p>
<example caption='Responder Agrees to Use XTLS'><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='xtls_1'
to='romeo@montague.net/orchard'
type='result'>
<proceed xmlns='urn:xmpp:tmp:xtls'/>
</iq>
]]></example>
<p>(Note: This is the functional equivalent of the &lt;proceed xmlns='urn:ietf:params:xml:ns:xmpp-tls'/&gt; command for direct XML streams as specified in <cite>RFC 3920</cite>.)</p>
<p>If the responder does not support XTLS, in accordance with core XMPP semantics it MUST return a &unavailable; error.</p>
<example caption='Responder Does Not Support XTLS'><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='xtls_1'
to='romeo@montague.net/orchard'
type='error'>
<error type='cancel'>
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>If the responder supports XTLS but does not wish to proceed with the use of XTLS, it MUST return a &notacceptable; error.</p>
<example caption='Responder Does Not Wish to Use XTLS'><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='xtls_1'
to='romeo@montague.net/orchard'
type='error'>
<error type='cancel'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>It is possible that both parties will attempt to start the use of XTLS at the same time <note>For example, the applications might automatically open an XTLS tunnel based on presence information.</note>, in which case one party might receive an XTLS start stanza from the other party after it has sent such an XTLS start stanza but before receiving a response. In this case, one of the initiation requests shall be considered to have higher priority than the other, and the party that receives the lower priority initiation request shall return a &conflict; stanza error in response to the lower priority request. The higher priority request MUST be considered the request that is generated by the party whose JID is sorted before the other party when the JIDs of both parties are sorted using "i;octet" collation as specified in Section 9.3 of &rfc4790;.</p>
<p>In this example, juliet@capulet.com/balcony is sorted before romeo@montague.net/orchard and therefore her XTLS start stanza has a higher priority. Therefore she would return a conflict error to Romeo if they both send an XTLS start stanza at the same time.</p>
<example caption='Higher Priority Party Returns Conflict Error'><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='xtls_1'
to='romeo@montague.net/orchard'
type='error'/>
<error type='cancel'>
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section2>
<section2 topic='Offer Details' anchor='offer'>
<p>&xep0250; defines an IQ stanza to determine which TLS method shall be used for client-to-client STARTTLS as described in &xep0246;. The initiator MAY exchange the XEP-0250 offers first, but MAY instead include the offers in the XTLS &lt;start/&gt; stanza to save a round trip. A client supporting XTLS and XEP-0250 MUST support offer exchange in the XTLS &lt;start/&gt; stanza.</p>
<example caption='Initiating XTLS with XEP-0250 Offer'><![CDATA[
<iq from='romeo@montague.net/orchard'
id='xtls_1'
to='juliet@capulet.com/balcony'
type='set'>
<start xmlns='urn:xmpp:tmp:xtls'>
<offer xmlns='urn:xmpp:tmp:c2ctls'>
<keyinfo xmlns='urn:xmpp:tmp:pubkey'>
<name>RomeoX509CertificateHash</name>
</keyinfo>
<srp/>
</offer>
</start>
</iq>
]]></example>
<p>If the responder supports XTLS, agrees to start the use of XTLS, and can verify the X.509 fingerprint, it returns an IQ-result containing a &lt;proceed/&gt; element with its offer.</p>
<example caption='Responder Agrees to Use XTLS and Returns its XEP-0250 Offer'><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='xtls_1'
to='romeo@montague.net/orchard'
type='result'>
<proceed xmlns='urn:xmpp:tmp:xtls'>
<offer xmlns='urn:xmpp:tmp:c2ctls'>
<keyinfo xmlns='urn:xmpp:tmp:pubkey'>
<name>JulietX509CertificateHash</name>
</keyinfo>
<srp/>
</offer>
</proceed>
</iq>
]]></example>
<p>If the initiator detects that a TLS handshake will fail based on the received offers (e.g. the peer only supports X.509 certificates and the client is unable to verify the certificate), the initiator MUST close the tunnel immediately (see <link url='#close'>Closing the XTLS Tunnel</link>).</p>
</section2>
<section2 topic='TLS Handshake' anchor='handshake'>
<p>Before sending encrypted data, the parties MUST perform a TLS handshake to establish the the XTLS tunnel. The TLS library sends the handshake and all encrypted data in-band as Base64-encoded payload of a &lt;data&gt; element qualified by the 'urn:xmpp:tmp:xtls' namespace &NSNOTE;. (This is similar to how data is sent in-band using &xep0047;, but in a dedicated namespace to work around the potential blockage of IBB exchanges by server administrators.) During the handshake, the responder (which functions as the TLS server) SHOULD send a CertificateRequest if X.509 certificates are used, since mutual authentication is desired. The first stanza MUST include a 'method' attribute defining the TLS method to be used. Possible values are 'x509', 'openpgp', and 'srp'. While this information is also included in the TLS handshake message itself, it can be useful for the recipient to know this before sending the data to the TLS library in use, e.g. when SRP is used the client might need to provide the password to the TLS library before decoding any data.</p>
<p>Note: It is possible that XTLS stanzas will not respect TLS message boundaries; therefore the number of IQ stanzas depends on the TLS implementation.</p>
<example caption='TLS Handshake (1)'><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='xtls_3'
to='juliet@capulet.lit/chamber'
type='set'>
<data xmlns='urn:xmpp:tmp:xtls' method='x509'>
base_64(TLS-Handshake-Messages)
</data>
</iq>
]]></example>
<p>The responder then acknowledges the stanza and, if the stream contains the complete ClientHello message, it continues with the TLS handshake. Otherwise it will wait for more messages from the initiator.</p>
<example caption='TLS Handshake (2)'><![CDATA[
<iq from='juliet@capulet.lit/chamber'
id='xtls_3'
to='romeo@montague.lit/orchard'
type='result'/>
<iq from='juliet@capulet.lit/chamber'
id='xtls_4'
to='romeo@montague.lit/orchard'
type='set'>
<data xmlns='urn:xmpp:tmp:xtls'>
base_64(TLS-Server-Handshake-Messages)
</data>
</iq>
]]></example>
</section2>
<section2 topic='Sending Encrypted Stanzas' anchor='stanzas'>
<p>After the TLS handshake has been completed, the parties exchange encrypted data over the tunnel. Because the routing information is already present in the IQ stanzas used by XTLS, it is OPTIONAL for the stanzas encapsulated in the XTLS stream to include routing information (i.e., the 'from' and 'to' attributes). In that case, the entity receiving the data MUST supply the 'from' and 'to' addresses of the IQ stanza that contains the encrypted data.</p>
<example caption='A Stanza to Send'><![CDATA[
<message
from='romeo@montague.lit/orchard'
to='juliet@capulet.lit//chamber'
type='chat'>
<thread>act2scene2chat1</thread>
<body>
I take thee at thy word:
Call me but love, and I'll be new baptized;
Henceforth I never will be Romeo.
</body>
<active xmlns='http://jabber.org/protocol/chatstates'/>
</message>
]]></example>
<p>The sender's client would strip off the routing information.</p>
<example caption='A Stanza to Send (No Routing)'><![CDATA[
<message type='chat'>
<thread>act2scene2chat1</thread>
<body>
I take thee at thy word:
Call me but love, and I'll be new baptized;
Henceforth I never will be Romeo.
</body>
<active xmlns='http://jabber.org/protocol/chatstates'/>
</message>
]]></example>
<p>This message is then encrypted and sent in one or more stanzas over the XTLS tunnel.</p>
<example caption='Sender Generates XTLS Tunnel Data'><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='xtls_3'
to='juliet@capulet.lit/chamber'
type='set'>
<data xmlns='urn:xmpp:tmp:xtls'>
base_64(TLS-Encrypted-Message)
</data>
</iq>
]]></example>
</section2>
<section2 topic='Closing the XTLS Tunnel' anchor='close'>
<p>Either party can close the XTLS tunnel; this is done by sending an IQ-set containing an empty &lt;close/&gt; element qualified by the 'urn:xmpp:tmp:xtls' namespace &NSNOTE;. However, if the entities have a mutual presence subscription then it is RECOMMENDED for the entities to maintain the tunnel until one entity becomes unavailable. Keeping the XTLS tunnel open does not require significant resources and prevents the need for a new TLS handshake.</p>
<example caption='One Party Closes the XTLS Tunnel'><![CDATA[
<iq type='set'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='xtls_10'>
<close xmlns='urn:xmpp:tmp:xtls'/>
</iq>
]]></example>
<p>The other party then acknowledges that the tunnel is closed by sending an IQ-result containing an empty &lt;closed/&gt; element qualified by the 'urn:xmpp:tmp:xtls' namespace &NSNOTE;.</p>
<example caption='Other Party Acknowledges Closing of the Tunnel'><![CDATA[
<iq type='result'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='xtls_10'>
<closed xmlns='urn:xmpp:tmp:xtls'/>
</iq>
]]></example>
<p>If the tunnel is unknown to the receiving party, it MUST return an &notfound; error.</p>
<example caption='Unknown Tunnel'><![CDATA[
<iq type='error'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='xtls_10'>
<error code='404' type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>If an error is detected, the tunnel MUST be considered closed and invalid.</p>
</section2>
</section1>
<section1 topic='Requirements Analysis' anchor='analysis'>
<p>As mentioned, XTLS is intended to address the requirements specified in <cite>XEP-0210</cite> (or a reasonable subset thereof). This section compares XTLS against the requirements and points out gaps that might need to be filled with changes to XTLS or to TLS itself.</p>
<ol>
<li><strong>Offline Sessions</strong> are not supported because XTLS tunnels use IQ stanzas, which are not stored offline.</li>
</ol>
</section1>
<section1 topic='Determining Support' anchor='disco'>
<p>If an entity wishes to request the use of XTLS, it SHOULD first determine whether the intended responder supports the protocol. This can be done directly via &xep0030; or indirectly via &xep0115;.</p>
<p>If an entity supports XTLS, it MUST report that by including a service discovery feature of "urn:xmpp:tmp:xtls" in response to disco#info requests &NSNOTE;.</p>
<example caption="Initial Service Discovery Information Request"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='disco1'
to='juliet@capulet.lit/chamber'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption="Service Discovery Information Response"><![CDATA[
<iq from='juliet@capulet.lit/chamber'
id='disco1'
to='romeo@montague.lit/orchard'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='urn:xmpp:tmp:xtls'/>
</query>
</iq>
]]></example>
<p>Both service discovery and entity capabilities information could be corrupted or intercepted; for details, see the <link url='#security-dos'>Denial of Service</link> section of this document.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>This entire document addresses security. Particular security-related issues are discussed in the following sections.</p>
<section2 topic='Mandatory-to-Implement Technologies' anchor='security-mti'>
<p>An implementation MUST at a minimum support the TLS_RSA_WITH_3DES_EDE_CBC_SHA and TLS_DH_RSA_WITH_AES_256_CBC_SHA ciphers. An implementation MAY support other ciphers as well.</p>
</section2>
<section2 topic='Certificates' anchor='security-certs'>
<p>As noted, XTLS can be used between XMPP clients, between an XMPP client and a remote XMPP service (i.e., a service with which a client does not have a direct XML stream), or between remote XMPP services. Therefore, a party to an XTLS tunnel will present either a client certificate or a server certificate as appropriate. Such certificates MUST be generated and validated in accordance with the certificate guidelines guidelines provided in &rfc3920bis;.</p>
<p>A future version of this specification might provide additional guidelines regarding certificate validation in the context of client-to-client encryption.</p>
</section2>
<section2 topic='Denial of Service' anchor='security-dos'>
<p>The XTLS start stanzas and proceed stanzas are not encrypted or signed; the same is true of service discovery exchanges and entity capabilities data. Therefore it is possible for an attacker to intercept these stanzas and modify them (e.g., by spuriously returning a &unavailable; error), thus convincing the initiator that the responder does not support XTLS and therefore denying the parties an opportunity to use XTLS.</p>
<p>A future version of this specification might address this problem.</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 proposal is accepted for publication by the XSF, its associated namespace shall be "urn:xmpp:tmp:xtls". Upon publication as a XEP, the &REGISTRAR; shall issue an initial namespace in accordance with the process defined in Section 4 of &xep0053;. The namespace "urn:xmpp:xtls:0" is requested and is thought to be unique per the XMPP Registrar's requirements.</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:xtls'
xmlns='urn:xmpp:tmp:xtls'
elementFormDefault='qualified'>
<xs:element name='start' type='empty'/>
<xs:element name='proceed' type='empty'/>
<xs:element name='data'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='method' type='xs:string' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='close' type='empty'/>
<xs:element name='closed' type='empty'/>
<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>The authors wish to thank Eric Rescorla for initial suggestions regarding the use of TLS for application-layer encryption in XMPP. Thanks also to Joe Hildebrand and Remko Tron&#231;on for their comments and suggestions.</p>
</section1>
</xep>