mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-28 12:12:22 -05:00
ProtoXEP
This commit is contained in:
Peter Saint-Andre
parent
ced8effb0e
commit
e60d680e9f
274
inbox/dtls-fingerprint.xml
Normal file
274
inbox/dtls-fingerprint.xml
Normal file
@ -0,0 +1,274 @@
|
|||||||
|
<?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 DTLS-SRTP in Jingle Sessions</title>
|
||||||
|
<abstract>This specification defines how to use DTLS-SRTP (RFC 5763) in the Jingle application type for the Real-time Transport Protocol (RTP) as a way to negotiate media path key agreement for secure RTP in one-to-one media sessions.</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>RFC 4572</spec>
|
||||||
|
<spec>RFC 5763</spec>
|
||||||
|
</dependencies>
|
||||||
|
<supersedes/>
|
||||||
|
<supersededby/>
|
||||||
|
<shortname>NOT_YET_ASSIGNED</shortname>
|
||||||
|
<!--
|
||||||
|
<schemaloc>
|
||||||
|
<url>TBD</url>
|
||||||
|
</schemaloc>
|
||||||
|
-->
|
||||||
|
<discuss>jingle</discuss>
|
||||||
|
&fippo;
|
||||||
|
<revision>
|
||||||
|
<version>0.0.2</version>
|
||||||
|
<date>2013-02-18</date>
|
||||||
|
<initials>ph</initials>
|
||||||
|
<remark><p>Second draft, rewrite no longer based on XEP-0262.</p></remark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<version>0.0.1</version>
|
||||||
|
<date>2012-12-13</date>
|
||||||
|
<initials>ph</initials>
|
||||||
|
<remark><p>First draft, copied from XEP-0262.</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;. &rfc5763; provides an approach to establish a Secure Real-time Transport Protocol (SRTP) security context using the Datagram Transport Layer Security (DTLS) protocol. A mechanism of transporting the fingerprint attribute that identifies the key that will be presented during the DTLS handshake in Jingle is defined herein. Inclusion of this information is OPTIONAL in both SIP/SDP and Jingle.</p>
|
||||||
|
<p>Note that while this specification only describes the use in the context of DTLS-SRTP, the fingerprint transported can be used in other contexts like for example establishing connections using SCTP over DTLS.</p>
|
||||||
|
<p>The SDP format (defined in &rfc4572;) is shown below.</p>
|
||||||
|
<code>
|
||||||
|
a=fingerprint:hash-func fingerprint
|
||||||
|
</code>
|
||||||
|
<p>An example follows.</p>
|
||||||
|
<code>
|
||||||
|
a=fingerprint:sha-256 02:1A:CC:54:27:AB:EB:9C:53:3F:3E:4B:65:2E:7D:46:3F:54:42:CD:54:F1:7A:03:A2:7D:F9:B0:7F:46:19:B2
|
||||||
|
</code>
|
||||||
|
<p>This SDP attribute can be translated into Jingle as a <fingerprint/> element qualified by the 'urn:xmpp:tmp:jingle:apps:dtls:0' namespace, as shown below.</p>
|
||||||
|
<code><![CDATA[
|
||||||
|
<fingerprint xmlns='urn:xmpp:tmp:jingle:apps:dtls:0' hash='hash-func'>fingerprint</fingerprint>
|
||||||
|
]]></code>
|
||||||
|
<p>An example follows.</p>
|
||||||
|
<code><![CDATA[
|
||||||
|
<fingerprint mlns='urn:xmpp:tmp:jingle:apps:dtls:0' hash='sha-256'>
|
||||||
|
02:1A:CC:54:27:AB:EB:9C:53:3F:3E:4B:65:2E:7D:46:3F:54:42:CD:54:F1:7A:03:A2:7D:F9:B0:7F:46:19:B2
|
||||||
|
</fingerprint>
|
||||||
|
]]></code>
|
||||||
|
<p>Note: since DTLS can be used to protect non-RTP sessions like SCTP including the fingerprint in the <encryption/> element defined in &xep0167; was deemed inappropriate. Also, the <encryption/> element defined there only applies to the encryption of the RTP data part, whereas DTLS (and DTLS-SRTP) protects the whole message.</p>
|
||||||
|
<p>If the Jingle initiator wishes to use DTLS-SRTP, it includes the <fingerprint/> element in its session invitation. If the initiator requires the use of DTLS, the <fingerprint/> element MUST include a 'required' attribute whose logical value is TRUE and whose lexical value is "true" or "1" &BOOLEANNOTE;, where this attribute defaults to a logical value of FALSE (i.e., a lexical value of "false" or "0").</p>
|
||||||
|
<example caption="Initiator sends session invitation with DTLS fingerprint"><![CDATA[
|
||||||
|
<iq from='romeo@montague.lit/orchard'
|
||||||
|
id='uz61v4m4'
|
||||||
|
to='juliet@capulet.lit/balcony'
|
||||||
|
type='set'>
|
||||||
|
<jingle xmlns='urn:xmpp:jingle:1'
|
||||||
|
action='session-initiate'
|
||||||
|
initiator='romeo@montague.lit/orchard'
|
||||||
|
sid='a73sjjvkla37jfea'>
|
||||||
|
<content creator='initiator' name='voice'>
|
||||||
|
<description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
|
||||||
|
<payload-type id='96' name='speex' clockrate='16000'/>
|
||||||
|
<payload-type id='97' name='speex' clockrate='8000'/>
|
||||||
|
<payload-type id='18' name='G729'/>
|
||||||
|
<payload-type id='103' name='L16' clockrate='16000' channels='2'/>
|
||||||
|
<payload-type id='98' name='x-ISAC' clockrate='8000'/>
|
||||||
|
</description>
|
||||||
|
<transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'
|
||||||
|
pwd='asd88fgpdd777uzjYhagZg'
|
||||||
|
ufrag='8hhy'>
|
||||||
|
<fingerprint xmlns='urn:xmpp:tmp:jingle:apps:dtls:0' hash='sha-256' required='true'>
|
||||||
|
02:1A:CC:54:27:AB:EB:9C:53:3F:3E:4B:65:2E:7D:46:3F:54:42:CD:54:F1:7A:03:A2:7D:F9:B0:7F:46:19:B2
|
||||||
|
</fingerprint>
|
||||||
|
<candidate component='1'
|
||||||
|
foundation='1'
|
||||||
|
generation='0'
|
||||||
|
id='el0747fg11'
|
||||||
|
ip='10.0.1.1'
|
||||||
|
network='1'
|
||||||
|
port='8998'
|
||||||
|
priority='2130706431'
|
||||||
|
protocol='udp'
|
||||||
|
type='host'/>
|
||||||
|
<candidate component='1'
|
||||||
|
foundation='2'
|
||||||
|
generation='0'
|
||||||
|
id='y3s2b30v3r'
|
||||||
|
ip='192.0.2.3'
|
||||||
|
network='1'
|
||||||
|
port='45664'
|
||||||
|
priority='1694498815'
|
||||||
|
protocol='udp'
|
||||||
|
rel-addr='10.0.1.1'
|
||||||
|
rel-port='8998'
|
||||||
|
type='srflx'/>
|
||||||
|
</transport>
|
||||||
|
</content>
|
||||||
|
</jingle>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>If the receiving party wishes to use DTLS, it also includes the <fingerprint/> element in its session-accept message.</p>
|
||||||
|
<example caption="Responder sends session-accept"><![CDATA[
|
||||||
|
<iq from='juliet@capulet.lit/balcony'
|
||||||
|
id='pn2va48j'
|
||||||
|
to='romeo@montague.lit/orchard'
|
||||||
|
type='set'>
|
||||||
|
<jingle xmlns='urn:xmpp:jingle:1'
|
||||||
|
action='session-accept'
|
||||||
|
initiator='romeo@montague.lit/orchard'
|
||||||
|
responder='juliet@capulet.lit/balcony'
|
||||||
|
sid='a73sjjvkla37jfea'>
|
||||||
|
<content creator='initiator' name='voice'>
|
||||||
|
<description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
|
||||||
|
<payload-type id='97' name='speex' clockrate='8000'/>
|
||||||
|
<payload-type id='18' name='G729'/>
|
||||||
|
</description>
|
||||||
|
<transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'
|
||||||
|
pwd='YH75Fviy6338Vbrhrlp8Yh'
|
||||||
|
ufrag='9uB6'>
|
||||||
|
<fingerprint xmlns='urn:xmpp:tmp:jingle:apps:dtls:0' hash='sha-256' required='1'>
|
||||||
|
BD:E8:2C:D3:BD:B6:98:50:45:7D:5B:36:89:53:31:15:52:25:88:82:06:95:88:A3:3D:A5:43:8D:5C:21:21:66
|
||||||
|
</fingerprint>
|
||||||
|
<candidate component='1'
|
||||||
|
foundation='1'
|
||||||
|
generation='0'
|
||||||
|
id='or2ii2syr1'
|
||||||
|
ip='192.0.2.1'
|
||||||
|
network='0'
|
||||||
|
port='3478'
|
||||||
|
priority='2130706431'
|
||||||
|
protocol='udp'
|
||||||
|
type='host'/>
|
||||||
|
</transport>
|
||||||
|
</content>
|
||||||
|
</jingle>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>Alternatively, if the receiving party wishes to expedite with ICE and DTLS negotiation without accepting the session, it MAY include the <fingerprint/> element when sending a transport-info message:</p>
|
||||||
|
<example caption="A transport-info containing a DTLS fingerprint"><![CDATA[
|
||||||
|
<iq from='juliet@capulet.lit/balcony'
|
||||||
|
id='pn2va48j'
|
||||||
|
to='romeo@montague.lit/orchard'
|
||||||
|
type='set'>
|
||||||
|
<jingle xmlns='urn:xmpp:jingle:1'
|
||||||
|
action='transport-info'
|
||||||
|
initiator='romeo@montague.lit/orchard'
|
||||||
|
responder='juliet@capulet.lit/balcony'
|
||||||
|
sid='a73sjjvkla37jfea'>
|
||||||
|
<content creator='initiator' name='voice'>
|
||||||
|
<transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'
|
||||||
|
pwd='YH75Fviy6338Vbrhrlp8Yh'
|
||||||
|
ufrag='9uB6'>
|
||||||
|
<fingerprint xmlns='urn:xmpp:tmp:jingle:apps:dtls:0' hash='sha-256' required='1'>
|
||||||
|
BD:E8:2C:D3:BD:B6:98:50:45:7D:5B:36:89:53:31:15:52:25:88:82:06:95:88:A3:3D:A5:43:8D:5C:21:21:66
|
||||||
|
</fingerprint>
|
||||||
|
<candidate component='1'
|
||||||
|
foundation='1'
|
||||||
|
generation='0'
|
||||||
|
id='or2ii2syr1'
|
||||||
|
ip='192.0.2.1'
|
||||||
|
network='0'
|
||||||
|
port='3478'
|
||||||
|
priority='2130706431'
|
||||||
|
protocol='udp'
|
||||||
|
type='host'/>
|
||||||
|
</transport>
|
||||||
|
</content>
|
||||||
|
</jingle>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Determining Support' anchor='disco'>
|
||||||
|
<p>If an entity supports establishing a Secure Real-time Transport Protocol security context using the Datagram Transport Layer Security protocol, it MUST advertise that fact in its responses to &xep0030; information ("disco#info") requests by returning a feature of "urn:xmpp:jingle:apps:dtls: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:1'/>
|
||||||
|
<feature var='urn:xmpp:jingle:apps:dtls: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 DTLS-SRTP itself are provided in <cite>RFC 5763</cite>.</p>
|
||||||
|
<p>XMPP stanzas such as Jingle 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 DTLS-SRTP and therefore denying the parties an opportunity to use DTLS-SRTP.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='IANA Considerations' anchor='iana'>
|
||||||
|
<p>This document requires no interaction with &IANA;.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Acknowledgements' anchor='acks'>
|
||||||
|
<p>Thanks to Justin Uberti.</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:apps:dtls:0</li>
|
||||||
|
</ul>
|
||||||
|
<p>The ®ISTRAR; includes 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 Schemas' anchor='schema'>
|
||||||
|
<code><![CDATA[
|
||||||
|
<?xml version='1.0' encoding='UTF-8'?>
|
||||||
|
|
||||||
|
<xs:schema
|
||||||
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
||||||
|
targetNamespace='urn:xmpp:tmp:jingle:apps:dtls:0'
|
||||||
|
xmlns='urn:xmpp:tmp:jingle:apps:dtls:0'
|
||||||
|
elementFormDefault='qualified'>
|
||||||
|
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>
|
||||||
|
The protocol documented by this schema is defined in
|
||||||
|
XEP-xxxx: http://www.xmpp.org/extensions/xep-xxxx.html
|
||||||
|
</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
|
||||||
|
<xs:element name='fingerprint'>
|
||||||
|
<xs:complexType>
|
||||||
|
<xs:simpleContent>
|
||||||
|
<xs:extension base='xs:string'>
|
||||||
|
<xs:attribute name='hash' type='xs:string' use='required'/>
|
||||||
|
<xs:attribute name='required' type='xs:boolean' default='false'/>
|
||||||
|
</xs:extension>
|
||||||
|
</xs:simpleContent>
|
||||||
|
</xs:complexType>
|
||||||
|
</xs:element>
|
||||||
|
|
||||||
|
</xs:schema>
|
||||||
|
]]></code>
|
||||||
|
</section1>
|
||||||
|
</xep>
|
||||||
638
inbox/exi.xml
Normal file
638
inbox/exi.xml
Normal file
@ -0,0 +1,638 @@
|
|||||||
|
<?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>Using Efficient XML Interchange (EXI) Format in XMPP</title>
|
||||||
|
<abstract>This specification describes how EXI compression can be used in XMPP networks.</abstract>
|
||||||
|
<legal>
|
||||||
|
<copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2013 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 "Specification"), 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 "AS IS" 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 <<link url='http://www.xmpp.org/extensions/ipr-policy.shtml'>http://www.xmpp.org/extensions/ipr-policy.shtml</link>> 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-0138</spec>
|
||||||
|
</dependencies>
|
||||||
|
<supersedes/>
|
||||||
|
<supersededby/>
|
||||||
|
<shortname>NOT_YET_ASSIGNED</shortname>
|
||||||
|
<author>
|
||||||
|
<firstname>Peter</firstname>
|
||||||
|
<surname>Waher</surname>
|
||||||
|
<email>peter.waher@clayster.com</email>
|
||||||
|
<jid>peter.waher@jabber.org</jid>
|
||||||
|
<uri>http://se.linkedin.com/pub/peter-waher/1a/71b/a29/</uri>
|
||||||
|
</author>
|
||||||
|
<revision>
|
||||||
|
<version>0.0.1</version>
|
||||||
|
<date>2013-03-12</date>
|
||||||
|
<initials>pwa</initials>
|
||||||
|
<remark>
|
||||||
|
<p>First draft.</p>
|
||||||
|
</remark>
|
||||||
|
</revision>
|
||||||
|
</header>
|
||||||
|
<section1 topic='Introduction' anchor='intro'>
|
||||||
|
<p>
|
||||||
|
The Efficient XML Interchange (EXI) Format <note>Efficient XML Interchange (EXI) Format <<link url='http://www.w3.org/TR/exi/'>http://www.w3.org/TR/exi/</link>>.</note> is an
|
||||||
|
efficient way to compress XML documents and XML fragments. This document provides information on how EXI can be used in XMPP streams to efficiently compress data transmitted between
|
||||||
|
the server and the client. For certain applications (like applications in sensor networks) EXI is a vital component, decreasing packet size enabling sensors with limited memory to
|
||||||
|
communicate efficiently. The strong support in EXI for generating efficient stubcodes is also vital to build efficient code in constrained devices.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Activating EXI compression requires a handshake to take place prior, where the server and client agrees on a set of parameters. Some of these parameters may increase compression ratio,
|
||||||
|
at the cost of processing power and readability. These parameters include:
|
||||||
|
</p>
|
||||||
|
<ul>
|
||||||
|
<li>Schemas to use.</li>
|
||||||
|
<li>EXI version number.</li>
|
||||||
|
<li>Data alignment (bit-packed, byte-alignment, pre-compression).</li>
|
||||||
|
<li>If EXI-compressed data should be further compressed using additional compression.</li>
|
||||||
|
<li>Strict or loose adherence to schemas.</li>
|
||||||
|
<li>If comments, processing instructions, dtd:s, prefixes, lexical values, etc. should be preserved.</li>
|
||||||
|
<li>If self-contained elements should be allowed.</li>
|
||||||
|
<li>Alternate data type representations for types values.</li>
|
||||||
|
<li>Block size for EXI compression.</li>
|
||||||
|
<li>Maximum string length of value content items in string tables.</li>
|
||||||
|
<li>Value partition capacity.</li>
|
||||||
|
</ul>
|
||||||
|
<p>
|
||||||
|
These parameters will be discussed deeper in the following sections. There are also default values users can use to commence evaluating EXI compression.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The single most important property to agree on however, is the set of schemas to use during EXI compression. EXI compresses XML much more efficiently if there exist schemas
|
||||||
|
describing the format of the expected XML. Since the server is not supposed to know all possible XML schemas, a mechanism is provided in this document whereby schemas can be
|
||||||
|
interchanged, so that the server can adapt its compression to the needs of the client.
|
||||||
|
</p>
|
||||||
|
</section1>
|
||||||
|
<section1 topic='Use Cases' anchor='usecases'>
|
||||||
|
<section2 topic='Detecting support'>
|
||||||
|
<p>
|
||||||
|
This XEP is based on &xep0138;. When the client connects to the XMPP Server, it will receive a list of features supported by the server:
|
||||||
|
</p>
|
||||||
|
<example caption='Search Features'>
|
||||||
|
<![CDATA[
|
||||||
|
<stream:features>
|
||||||
|
<starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>
|
||||||
|
<compression xmlns='http://jabber.org/features/compress'>
|
||||||
|
<method>zlib</method>
|
||||||
|
<method>lzw</method>
|
||||||
|
<method>exi</method>
|
||||||
|
</compression>
|
||||||
|
</stream:features>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
Support for EXI compression is detected by the existance of the <strong>exi</strong> compression method in the <strong>features</strong> stanza.
|
||||||
|
</p>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Invalid setup'>
|
||||||
|
<p>
|
||||||
|
If the client attempts to activate EXI stream at this point, before negotiation of EXI properties have been performed, the server must respond with a
|
||||||
|
<strong>setup-failed</strong> response.
|
||||||
|
</p>
|
||||||
|
<example caption='Invalid setup'>
|
||||||
|
<![CDATA[
|
||||||
|
<compress xmlns='http://jabber.org/protocol/compress'>
|
||||||
|
<method>exi</method>
|
||||||
|
</compress>
|
||||||
|
|
||||||
|
<failure xmlns='http://jabber.org/protocol/compress'>
|
||||||
|
<setup-failed/>
|
||||||
|
</failure>]]>
|
||||||
|
</example>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Proposing compression parameters'>
|
||||||
|
<p>
|
||||||
|
When the client decides to activate EXI compression, it sends a <strong>setup</strong> stanza containing parameter proposals to the server as follows:
|
||||||
|
</p>
|
||||||
|
<example caption='Proposing compression parameters'>
|
||||||
|
<![CDATA[
|
||||||
|
<setup xmlns='http://jabber.org/protocol/compress/exi' version='1' strict='true' blockSize='1024' valueMaxLength='32' valuePartitionCapacity='100'>
|
||||||
|
<schema ns='urn:xmpp:sn' bytes='8092' md5Hash='18829242ca7a72a552a7e15af5b9e44d'/>
|
||||||
|
<schema ns='urn:xmpp:sn:provisioning' bytes='6303' md5Hash='e5301add51f3b24c15a71256b53daa47'/>
|
||||||
|
</setup>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
The server in turn responds with a <strong>setupResponse</strong> stanza containing the parameters it can accept, based on the initial values provided by the client.
|
||||||
|
Any buffer sizes, etc., may have been changed, but only lowered, never raised.
|
||||||
|
</p>
|
||||||
|
<example caption='Unable to accommodate parameters'>
|
||||||
|
<![CDATA[
|
||||||
|
<setupResponse xmlns='http://jabber.org/protocol/compress/exi' version='1' strict='true'
|
||||||
|
blockSize='1024' valueMaxLength='32' valuePartitionCapacity='100'>
|
||||||
|
<schema ns='urn:xmpp:sn' bytes='8092' md5Hash='18829242ca7a72a552a7e15af5b9e44d'/>
|
||||||
|
<missingSchema ns='urn:xmpp:sn:provisioning' bytes='6303' md5Hash='e5301add51f3b24c15a71256b53daa47'/>
|
||||||
|
</setupResponse>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
<strong>Note:</strong> Schema files are identified using three properties: Its <strong>target namespace</strong>, its <strong>byte size</strong> and its
|
||||||
|
<strong>MD5 hash</strong>. The <strong>MD5 hash</strong> provides a way to detect small changes in the file, even if the byte size and namespace are the same.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Schema files that the server does not have, based on namespace, byte size and MD5 hash, are marked with the <strong>missingSchema</strong> element instead of the
|
||||||
|
normal <strong>schema</strong> element.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The client can, at this point, choose to abort the EXI enablement sequence, if it cannot accommodate itself with the proposed parameter settings provided by the server.
|
||||||
|
The XMPP session will continue to work in its current state.
|
||||||
|
</p>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Uploading new schema files'>
|
||||||
|
<p>
|
||||||
|
If the server lacks information about a schema file, this is specified in the response through the <strong>missingSchema</strong> elements. The client can at this point
|
||||||
|
either choose to accept that these schema files are not available, making compression less efficient, or choose to upload the missing schema files to the server. Of course,
|
||||||
|
uploading schema files would require the device to have sufficient buffers and memory to store and upload the schema files in the first place. (If not possible to upload the
|
||||||
|
schema files, consideration should be taken to install the schema files manually at the server.)
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
To upload a schema file, the client simply sends the schema file using an <strong>uploadSchema</strong> element, as follows:
|
||||||
|
</p>
|
||||||
|
<example caption='Uploading schema file'>
|
||||||
|
<![CDATA[
|
||||||
|
<uploadSchema xmlns='http://jabber.org/protocol/compress/exi'>
|
||||||
|
PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4NCjx4czpzY2hlbWENCiAgICB4
|
||||||
|
bWxuczp4cz0naHR0cDovL3d3dy53My5vcmcvMjAwMS9YTUxTY2hlbWEnDQogICAgdGFyZ2V0TmFt
|
||||||
|
ZXNwYWNlPSd1cm46eG1wcDpzbjpwcm92aXNpb25pbmcnDQogICAgeG1sbnM9J3Vybjp4bXBwOnNu
|
||||||
|
|
||||||
|
...
|
||||||
|
|
||||||
|
dmlsZWdlJz4NCgkJPHhzOmF0dHJpYnV0ZSBuYW1lPSdpZCcgdHlwZT0nUHJpdmlsZWdlSWQnIHVz
|
||||||
|
ZT0ncmVxdWlyZWQnLz4NCgk8L3hzOmNvbXBsZXhUeXBlPg0KIA0KPC94czpzY2hlbWE+DQo=
|
||||||
|
</uploadSchema>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
The schema itself is sent using base64 encoding to the server. This, to make sure a binary exact copy is transferred, maintaining encoding, processing instructions, etc. The
|
||||||
|
server then computes the <strong>target namespace</strong>, <strong>byte size</strong> and <strong>MD5 Hash</strong> from this schema file sent.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
If the client desires, it can test the EXI setup again. This is however optional, but can be used to test that uploading the schema files, and any new property values
|
||||||
|
are accepted by the server.
|
||||||
|
</p>
|
||||||
|
<example caption='Testing newly uploaded schema files'>
|
||||||
|
<![CDATA[
|
||||||
|
<setup xmlns='http://jabber.org/protocol/compress/exi' version='1' strict='true' blockSize='1024' valueMaxLength='32' valuePartitionCapacity='100'>
|
||||||
|
<schema ns='urn:xmpp:sn' bytes='8092' md5Hash='18829242ca7a72a552a7e15af5b9e44d'/>
|
||||||
|
<schema ns='urn:xmpp:sn:provisioning' bytes='6303' md5Hash='e5301add51f3b24c15a71256b53daa47'/>
|
||||||
|
</setup>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
And the server should now respond:
|
||||||
|
</p>
|
||||||
|
<example caption='Agreement between client and server'>
|
||||||
|
<![CDATA[
|
||||||
|
<setupResponse xmlns='http://jabber.org/protocol/compress/exi' version='1' strict='true'
|
||||||
|
blockSize='1024' valueMaxLength='32' valuePartitionCapacity='100' agreement='true'>
|
||||||
|
<schema ns='urn:xmpp:sn' bytes='8092' md5Hash='18829242ca7a72a552a7e15af5b9e44d'/>
|
||||||
|
<schema ns='urn:xmpp:sn:provisioning' bytes='6303' md5Hash='e5301add51f3b24c15a71256b53daa47'/>
|
||||||
|
</setupResponse>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
Note the <strong>agreement</strong> attribute in the response this time. The server must set this attribute to true if it agrees with the proposal from the client.
|
||||||
|
The client in turn can check this attribute as a quick way to check if agreement exists.
|
||||||
|
</p>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Downloading new schema files on server'>
|
||||||
|
<p>
|
||||||
|
As an alternative to uploading a schema file to the server, the client can ask the server to download a schema file by itself. This is done using the <strong>downloadSchema</strong>
|
||||||
|
command, as follows:
|
||||||
|
</p>
|
||||||
|
<example caption='Downloading new schema files on server'>
|
||||||
|
<![CDATA[
|
||||||
|
<downloadSchema xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.se/compress/sn/provisioning.xsd'/>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
The server tries to download the schema by itself, and then computes the <strong>target namespace</strong>, <strong>byte size</strong> and <strong>MD5 Hash</strong>
|
||||||
|
from the downloaded schema.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
When the schema has been downloaded, a successful download response is returned, as follows:
|
||||||
|
</p>
|
||||||
|
<example caption='Schema successfully downloaded'>
|
||||||
|
<![CDATA[
|
||||||
|
<downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.se/compress/sn/provisioning.xsd' result='true'/>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
If an HTTP error occurred while trying to download the schema, a response as follows is returned:
|
||||||
|
</p>
|
||||||
|
<example caption='HTTP Error'>
|
||||||
|
<![CDATA[
|
||||||
|
<downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.se/compress/sn/provisioning.xsd' result='false'>
|
||||||
|
<httpError code='404' message='NotFound'/>
|
||||||
|
</downloadSchemaResponse>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
If the URL could not be resolved, a response as follows is returned:
|
||||||
|
</p>
|
||||||
|
<example caption='Invalid URL'>
|
||||||
|
<![CDATA[
|
||||||
|
<downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='urk://example.com/schema.xsd' result='false'>
|
||||||
|
<invalidUrl message='Unrecognized schema.'/>
|
||||||
|
</downloadSchemaResponse>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
If a timeout occurred during the download attempt, a response as follows is returned:
|
||||||
|
</p>
|
||||||
|
<example caption='Timeout'>
|
||||||
|
<![CDATA[
|
||||||
|
<downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.se/compress/sn/provisioning.xsd' result='false'>
|
||||||
|
<timeout message='No response returned.'/>
|
||||||
|
</downloadSchemaResponse>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
If the url points to something that is not a schema, a response as follows is returned:
|
||||||
|
</p>
|
||||||
|
<example caption='Invalid Content Type'>
|
||||||
|
<![CDATA[
|
||||||
|
<downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.se/compress/sn/provisioning.xsd' result='false'>
|
||||||
|
<invalidContentType contentTypeReturned='text/html'/>
|
||||||
|
</downloadSchemaResponse>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
If some other error occurs, unforseen by this specification, the server can simply respond with a generic error message, as follows:
|
||||||
|
</p>
|
||||||
|
<example caption='Other types of errors'>
|
||||||
|
<![CDATA[
|
||||||
|
<downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.se/compress/sn/provisioning.xsd' result='false'>
|
||||||
|
<error message='No free space left.'/>
|
||||||
|
</downloadSchemaResponse>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
<strong>Note:</strong> Downloading a schema, might download a version which does not correspond to the desired version
|
||||||
|
of the schema. So, it's more important in this case, the client checks that the server actually has the version of the schema required by the client.
|
||||||
|
</p>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Starting compression'>
|
||||||
|
<p>
|
||||||
|
When EXI option negotiation has been completed, the client can tell the server that it is ready to start compression. It does this using the normal <strong>compress</strong>
|
||||||
|
stanza, as follows:
|
||||||
|
</p>
|
||||||
|
<example>
|
||||||
|
<![CDATA[
|
||||||
|
<compress xmlns='http://jabber.org/protocol/compress'>
|
||||||
|
<method>exi</method>
|
||||||
|
</compress>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
The server now having necessary knowledge on how the EXI engine should be configured for the current session, responds:
|
||||||
|
</p>
|
||||||
|
<example>
|
||||||
|
<![CDATA[
|
||||||
|
<compressed xmlns='http://jabber.org/protocol/compress'/>]]>
|
||||||
|
</example>
|
||||||
|
<p>
|
||||||
|
When the client receives acknowledgement that the compression method has been accepted, it restarts the stream, as explained in
|
||||||
|
<link url='http://xmpp.org/extensions/xep-0138.html#usecase'>XEP 0138</link>.
|
||||||
|
</p>
|
||||||
|
</section2>
|
||||||
|
</section1>
|
||||||
|
<section1 topic='Implementation Notes' anchor='impl'>
|
||||||
|
<section2 topic='EXI options'>
|
||||||
|
<p>
|
||||||
|
The following segment is taken from the <link url='http://www.w3.org/TR/exi/#options'>EXI specification</link>. It describes the different EXI options that need to be negotiated before enabling EXI.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <strong>alignment option</strong> is used to control the alignment of event codes and content items. The value is one of bit-packed, byte-alignment or pre-compression, of which bit-packed is the default value assumed when the "alignment" element is absent in the EXI Options document. The option values byte-alignment and pre-compression are effected when "byte" and "pre-compress" elements are present in the EXI Options document, respectively. When the value of compression option is set to true, alignment of the EXI Body is governed by the rules specified in <link url='http://www.w3.org/TR/exi/#compression'>9. EXI Compression</link> instead of the alignment option value. The "alignment" element MUST NOT appear in an EXI options document when the "compression" element is present.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The alignment option value <strong>bit-packed</strong> indicates that the event codes and associated content are packed in bits without any padding in-between.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The alignment option value <strong>byte-alignment</strong> indicates that the event codes and associated content are aligned on byte boundaries. While byte-alignment generally results in EXI streams of larger sizes compared with their bit-packed equivalents, byte-alignment may provide a help in some use cases that involve frequent copying of large arrays of scalar data directly out of the stream. It can also make it possible to work with data in-place and can make it easier to debug encoded data by allowing items on aligned boundaries to be easily located in the stream.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The alignment option value <strong>pre-compression</strong> indicates that all steps involved in compression (see section <link url='http://www.w3.org/TR/exi/#compression'>9. EXI Compression</link>) are to be done with the exception of the final step of applying the DEFLATE algorithm. The primary use case of pre-compression is to avoid a duplicate compression step when compression capability is built into the transport protocol. In this case, pre-compression just prepares the stream for later compression.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <strong>compression option</strong> is a Boolean used to increase compactness using additional computational resources. The default value "false" is assumed when the "compression" element is absent in the EXI Options document whereas its presence denotes the value "true". When set to true, the event codes and associated content are compressed according to <link url='http://www.w3.org/TR/exi/#compression'>9. EXI Compression</link> regardless of the alignment option value. As mentioned above, the "compression" element MUST NOT appear in an EXI options document when the "alignment" element is present.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <strong>strict option</strong> is a Boolean used to increase compactness by using a strict interpretation of the schemas and omitting preservation of certain items, such as comments, processing instructions and namespace prefixes. The default value "false" is assumed when the "strict" element is absent in the EXI Options document whereas its presence denotes the value "true". When set to true, those productions that have NS, CM, PI, ER, and SC terminal symbols are omitted from the EXI grammars, and schema-informed element and type grammars are restricted to only permit items declared in the schemas. A note in section <link url='http://www.w3.org/TR/exi/#addingProductionsStrict'>8.5.4.4.2 Adding Productions when Strict is True</link> describes some additional restrictions consequential of the use of this option. The "strict" element MUST NOT appear in an EXI options document when one of "dtd", "prefixes", "comments", "pis" or "selfContained" element is present in the same options document.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <strong>preserve option</strong> is a set of Booleans that can be set independently to each enable or disable a share of the format's capacity determining whether or how certain information items can be preserved in the EXI stream. Section <link url='http://www.w3.org/TR/exi/#fidelityOptions'>6.3 Fidelity Options</link> describes the set of information items affected by the preserve option. The presence of "dtd", "prefixes", "lexicalValues", "comments" and "pis" in the EXI Options document each turns on fidelity options Preserve.comments, Preserve.pis, Preserve.dtd, Preserve.prefixes and Preserve.lexicalValues whereas the absence denotes turning each off. The elements "dtd", "prefixes", "comments" and "pis" MUST NOT appear in an EXI options document when the "strict" element is present in the same options document. The element "lexicalValues", on the other hand, is permitted to occur in the presence of "strict" element.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <strong>selfContained option</strong> is a Boolean used to enable the use of self-contained elements in the EXI stream. Self-contained elements may be read independently from the rest of the EXI body, allowing them to be indexed for random access. The "selfContained" element MUST NOT appear in an EXI options document when one of "compression", "pre-compression" or "strict" elements are present in the same options document. The default value "false" is assumed when the "selfContained" element is absent from the EXI Options document whereas its presence denotes the value "true".
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <strong>datatypeRepresentationMap option</strong> specifies an alternate set of datatype representations for typed values in the EXI body as described in <link url='http://www.w3.org/TR/exi/#datatypeRepresentationMap'>7.4 Datatype Representation Map</link>. When there are no "datatypeRepresentationMap" elements in the EXI Options document, no Datatype Representation Map is used for processing the EXI body. This option does not take effect when the value of the Preserve.lexicalValues fidelity option is true (see <link url='http://www.w3.org/TR/exi/#fidelityOptions'>6.3 Fidelity Options</link>), or when the EXI stream is a schema-less EXI stream.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <strong>blockSize option</strong> specifies the block size used for EXI compression. When the "blockSize" element is absent in the EXI Options document, the default blocksize of 1,000,000 is used. The default blockSize is intentionally large but can be reduced for processing large documents on devices with limited memory.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <strong>valueMaxLength option</strong> specifies the maximum length of value content items to be considered for addition to the string table. The default value "unbounded" is assumed when the "valueMaxLength" element is absent in the EXI Options document.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <strong>valuePartitionCapacity option</strong> specifies the maximum number of value content items in the string table at any given time. The default value "unbounded" is assumed when the "valuePartitionCapacity" element is absent in the EXI Options document. Section <link url='http://www.w3.org/TR/exi/#encodingOptimizedForMisses'>7.3.3 Partitions Optimized for Frequent use of String Literals</link> specifies the behavior of the string table when this capacity is reached.
|
||||||
|
</p>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Networks containing clients having limited memory'>
|
||||||
|
<p>
|
||||||
|
To successfully implement a network with clients having limited memory, such as sensor networks, care should be taken to make sure necessary schema files are
|
||||||
|
preinstalled on the server, to avoid the necessity to upload schema files from the clients. Clients with limited memory might be unable to perform this task.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
An alternative may be to install a richer client, that can upload the schema files to the server dynamically, and installing it into the network. Any client uploading
|
||||||
|
a schema file, will make that schema file available for EXI compression to any other client in the network.
|
||||||
|
</p>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Caching schema files'>
|
||||||
|
<p>
|
||||||
|
Schema files uploaded to the server should be cached on the server in some kind of schema repository. If memory is limited on the server, schema files should be
|
||||||
|
sorted by last access. Schema files with the oldest last access timestamp could be removed to maintain the cache within an approved cache size.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Note that schema files have three keys: <strong>Target namespace</strong>, <strong>byte size</strong> and <strong>MD5 Hash</strong>. Multiple versions of a schema file
|
||||||
|
may exist (that is, with the same target namespace but different byte sizes or MD5 hash codes). Note also, that for any practical purpose, schema files can be stored
|
||||||
|
using only the MD5 hash as a key, since it is highly improbable that two different schema files will have the same MD5 hash (unless consciously created that way). MD5 hash
|
||||||
|
values are always in <strong>lower case</strong>.
|
||||||
|
</p>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Uploading vs. Downloading schemas'>
|
||||||
|
<p>
|
||||||
|
When the server lacks information about a given XML schema, the client has two options for updating the server. Either it uploads the schema, or it asks the server to
|
||||||
|
download one.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Uloading a schema has the advantage, that the client knows exactly the version that the server requires. It has the disadvantage, that the client needs to store the schema
|
||||||
|
and send a possible large schema to the server. If EXI is used because the device has limited memory, uploading a schema might not be an option.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Downloading a schema has the advantage, that size of schema does not matter. The disadvantage is that asynchronous errors might occur, so the client needs to pay respect
|
||||||
|
to the responses returned by the server when downloading schemas. Also, downloading a schema, might download a version which does not correspond to the desired version
|
||||||
|
of the schema. So, it's more important in this case, the client checks that the server actually has the version of the schema required by the client.
|
||||||
|
</p>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Server decompression and recompression vs. binary forwarding'>
|
||||||
|
<p>
|
||||||
|
If two XMPP clients communicate with each other through an XMPP server, and both clients use EXI compression, the server must only forward
|
||||||
|
binary packets if both EXI compressed channels have exactly the same setup. If any parameter is different, the server MUST always recompress
|
||||||
|
packets sent through it.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Since the server always needs to decompress incoming EXI compressed packets to decode headers, omitting the compression part might save the server
|
||||||
|
some processing power, but not all. Note that, in some networks it might be common using similar compression settings, while in others different compression
|
||||||
|
settings are most common.
|
||||||
|
</p>
|
||||||
|
</section2>
|
||||||
|
</section1>
|
||||||
|
<section1 topic='Security Considerations' anchor='security'>
|
||||||
|
<p>
|
||||||
|
Note that EXI compressed information, even though it is hard to decode by humans, is by no means encrypted. If sensitive data is to be sent over an EXI compressed
|
||||||
|
channel, encryption should be considered as well.
|
||||||
|
</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>REQUIRED.</p>
|
||||||
|
<!-- TODO -->
|
||||||
|
</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/compress/exi'
|
||||||
|
xmlns='http://jabber.org/protocol/compress/exi'
|
||||||
|
elementFormDefault='qualified'>
|
||||||
|
|
||||||
|
<xs:element name='setup' type='Setup'/>
|
||||||
|
<xs:element name='setupResponse' type='SetupResponse'/>
|
||||||
|
|
||||||
|
<xs:complexType name='Setup'>
|
||||||
|
<xs:choice minOccurs='0' maxOccurs='unbounded'>
|
||||||
|
<xs:element name='schema' type='Schema'/>
|
||||||
|
<xs:element name='datatypeRepresentationMap' type='DatatypeRepresentationMap'/>
|
||||||
|
</xs:choice>
|
||||||
|
<xs:attributeGroup ref='Options'/>
|
||||||
|
</xs:complexType>
|
||||||
|
|
||||||
|
<xs:complexType name='SetupResponse'>
|
||||||
|
<xs:complexContent>
|
||||||
|
<xs:extension base='Setup'>
|
||||||
|
<xs:choice minOccurs='0' maxOccurs='unbounded'>
|
||||||
|
<xs:element name='missingSchema' type='Schema'/>
|
||||||
|
</xs:choice>
|
||||||
|
<xs:attribute name='agreement' type='xs:boolean' use='optional' default='false'/>
|
||||||
|
</xs:extension>
|
||||||
|
</xs:complexContent>
|
||||||
|
</xs:complexType>
|
||||||
|
|
||||||
|
<xs:complexType name='Schema'>
|
||||||
|
<xs:attribute name='ns' type='xs:string' use='required'/>
|
||||||
|
<xs:attribute name='bytes' type='xs:positiveInteger' use='required'/>
|
||||||
|
<xs:attribute name='md5Hash' type='MD5Hash' use='required'/>
|
||||||
|
</xs:complexType>
|
||||||
|
|
||||||
|
<xs:complexType name='DatatypeRepresentationMap'>
|
||||||
|
<xs:attribute name='type' type='xs:string' use='required'/>
|
||||||
|
<xs:attribute name='representAs' type='xs:string' use='required'/>
|
||||||
|
</xs:complexType>
|
||||||
|
|
||||||
|
<xs:attributeGroup name='Options'>
|
||||||
|
<xs:attribute name='version' type='xs:positiveInteger' use='optional' default='1'/>
|
||||||
|
<xs:attribute name='alignment' type='Alignment' use='optional' default='bit-packed'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>The alignment option is used to control the alignment of event codes and content items.
|
||||||
|
The value is one of bit-packed, byte-alignment or pre-compression, of which bit-packed is the default value
|
||||||
|
assumed when the "alignment" element is absent in the EXI Options document. The option values byte-alignment
|
||||||
|
and pre-compression are effected when "byte" and "pre-compress" elements are present in the EXI Options
|
||||||
|
document, respectively. When the value of compression option is set to true, alignment of the EXI Body is
|
||||||
|
governed by the rules specified in 9. EXI Compression instead of the alignment option value. The "alignment"
|
||||||
|
element MUST NOT appear in an EXI options document when the "compression" element is present.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='compression' type='xs:boolean' use='optional' default='false'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>The compression option is a Boolean used to increase compactness using additional
|
||||||
|
computational resources. The default value "false" is assumed when the "compression" element is absent in
|
||||||
|
the EXI Options document whereas its presence denotes the value "true". When set to true, the event codes
|
||||||
|
and associated content are compressed according to 9. EXI Compression regardless of the alignment option
|
||||||
|
value. As mentioned above, the "compression" element MUST NOT appear in an EXI options document when the
|
||||||
|
"alignment" element is present.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='strict' type='xs:boolean' use='optional' default='false'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>The strict option is a Boolean used to increase compactness by using a strict
|
||||||
|
interpretation of the schemas and omitting preservation of certain items, such as comments, processing
|
||||||
|
instructions and namespace prefixes. The default value "false" is assumed when the "strict" element is
|
||||||
|
absent in the EXI Options document whereas its presence denotes the value "true". When set to true, those
|
||||||
|
productions that have NS, CM, PI, ER, and SC terminal symbols are omitted from the EXI grammars, and
|
||||||
|
schema-informed element and type grammars are restricted to only permit items declared in the schemas.
|
||||||
|
A note in section 8.5.4.4.2 Adding Productions when Strict is True describes some additional restrictions
|
||||||
|
consequential of the use of this option. The "strict" element MUST NOT appear in an EXI options document
|
||||||
|
when one of "dtd", "prefixes", "comments", "pis" or "selfContained" element is present in the same
|
||||||
|
options document.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='preserveComments' type='xs:boolean' use='optional' default='false'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>Comments are preserved. Must not be used together with the strict option.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='preservePIs' type='xs:boolean' use='optional' default='false'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>Processing instructions are preserved. Must not be used together with the strict
|
||||||
|
option.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='preserveDTD' type='xs:boolean' use='optional' default='false'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>DTD is preserved. Must not be used together with the strict option.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='preservePrefixes' type='xs:boolean' use='optional' default='false'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>Prefixes are preserved. Must not be used together with the strict option.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='preserveLexical' type='xs:boolean' use='optional' default='false'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>Lexical form of element and attribute values can be preserved in value content items.
|
||||||
|
Can be used together with the strict option.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='selfContained' type='xs:boolean' use='optional' default='false'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>The selfContained option is a Boolean used to enable the use of self-contained elements
|
||||||
|
in the EXI stream. Self-contained elements may be read independently from the rest of the EXI body,
|
||||||
|
allowing them to be indexed for random access. The "selfContained" element MUST NOT appear in an EXI
|
||||||
|
options document when one of "compression", "pre-compression" or "strict" elements are present in the
|
||||||
|
same options document. The default value "false" is assumed when the "selfContained" element is absent
|
||||||
|
from the EXI Options document whereas its presence denotes the value "true".</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='blockSize' type='xs:positiveInteger' use='optional' default='1000000'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>The blockSize option specifies the block size used for EXI compression. When the
|
||||||
|
"blockSize" element is absent in the EXI Options document, the default blocksize of 1,000,000 is used.
|
||||||
|
The default blockSize is intentionally large but can be reduced for processing large documents on
|
||||||
|
devices with limited memory.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='valueMaxLength' type='xs:positiveInteger' use='optional'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>The valueMaxLength option specifies the maximum length of value content items to be
|
||||||
|
considered for addition to the string table. The default value "unbounded" is assumed when the
|
||||||
|
"valueMaxLength" element is absent in the EXI Options document.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='valuePartitionCapacity' type='xs:positiveInteger' use='optional'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>The valuePartitionCapacity option specifies the maximum number of value content
|
||||||
|
items in the string table at any given time. The default value "unbounded" is assumed when the
|
||||||
|
"valuePartitionCapacity" element is absent in the EXI Options document. Section 7.3.3 Partitions
|
||||||
|
Optimized for Frequent use of String Literals specifies the behavior of the string table when this
|
||||||
|
capacity is reached.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:attribute>
|
||||||
|
</xs:attributeGroup>
|
||||||
|
|
||||||
|
<xs:simpleType name='MD5Hash'>
|
||||||
|
<xs:restriction base='xs:string'>
|
||||||
|
<xs:pattern value='^[0-9a-f]{32}$'/>
|
||||||
|
</xs:restriction>
|
||||||
|
</xs:simpleType>
|
||||||
|
|
||||||
|
<xs:simpleType name='Alignment'>
|
||||||
|
<xs:restriction base='xs:string'>
|
||||||
|
<xs:enumeration value='bit-packed'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>The alignment option value bit-packed indicates that the event codes and associated
|
||||||
|
content are packed in bits without any padding in-between.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:enumeration>
|
||||||
|
<xs:enumeration value='byte-alignment'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>The alignment option value byte-alignment indicates that the event codes and
|
||||||
|
associated content are aligned on byte boundaries. While byte-alignment generally results in EXI
|
||||||
|
streams of larger sizes compared with their bit-packed equivalents, byte-alignment may provide a
|
||||||
|
help in some use cases that involve frequent copying of large arrays of scalar data directly out
|
||||||
|
of the stream. It can also make it possible to work with data in-place and can make it easier to
|
||||||
|
debug encoded data by allowing items on aligned boundaries to be easily located in the stream.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:enumeration>
|
||||||
|
<xs:enumeration value='pre-compression'>
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>The alignment option value pre-compression indicates that all steps involved
|
||||||
|
in compression (see section 9. EXI Compression) are to be done with the exception of the final
|
||||||
|
step of applying the DEFLATE algorithm. The primary use case of pre-compression is to avoid a
|
||||||
|
duplicate compression step when compression capability is built into the transport protocol. In
|
||||||
|
this case, pre-compression just prepares the stream for later compression.</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
</xs:enumeration>
|
||||||
|
</xs:restriction>
|
||||||
|
</xs:simpleType>
|
||||||
|
|
||||||
|
<xs:element name='uploadSchema' type='xs:base64Binary'/>
|
||||||
|
|
||||||
|
<xs:element name='downloadSchema' type='DownloadSchema'/>
|
||||||
|
<xs:element name='downloadSchemaResponse' type='DownloadSchemaResponse'/>
|
||||||
|
|
||||||
|
<xs:complexType name='DownloadSchema'>
|
||||||
|
<xs:attribute name='url' type='xs:string' use='required'/>
|
||||||
|
</xs:complexType>
|
||||||
|
|
||||||
|
<xs:complexType name='DownloadSchemaResponse'>
|
||||||
|
<xs:complexContent>
|
||||||
|
<xs:extension base='DownloadSchema'>
|
||||||
|
<xs:choice minOccurs='0' maxOccurs='1'>
|
||||||
|
<xs:element name='httpError'>
|
||||||
|
<xs:complexType>
|
||||||
|
<xs:attribute name='code' type='xs:positiveInteger' use='required'/>
|
||||||
|
<xs:attribute name='message' type='xs:string' use='required'/>
|
||||||
|
</xs:complexType>
|
||||||
|
</xs:element>
|
||||||
|
<xs:element name='invalidUrl'>
|
||||||
|
<xs:complexType>
|
||||||
|
<xs:attribute name='message' type='xs:string' use='required'/>
|
||||||
|
</xs:complexType>
|
||||||
|
</xs:element>
|
||||||
|
<xs:element name='timeout'>
|
||||||
|
<xs:complexType>
|
||||||
|
<xs:attribute name='message' type='xs:string' use='required'/>
|
||||||
|
</xs:complexType>
|
||||||
|
</xs:element>
|
||||||
|
<xs:element name='invalidContentType'>
|
||||||
|
<xs:complexType>
|
||||||
|
<xs:attribute name='contentTypeReturned' type='xs:string' use='required'/>
|
||||||
|
</xs:complexType>
|
||||||
|
</xs:element>
|
||||||
|
<xs:element name='error'>
|
||||||
|
<xs:complexType>
|
||||||
|
<xs:attribute name='message' type='xs:string' use='required'/>
|
||||||
|
</xs:complexType>
|
||||||
|
</xs:element>
|
||||||
|
</xs:choice>
|
||||||
|
<xs:attribute name='result' type='xs:boolean' use='required'/>
|
||||||
|
</xs:extension>
|
||||||
|
</xs:complexContent>
|
||||||
|
</xs:complexType>
|
||||||
|
|
||||||
|
</xs:schema>
|
||||||
|
]]>
|
||||||
|
</code>
|
||||||
|
</section1>
|
||||||
|
<section1 topic='Acknowledgements' anchor='ack'>
|
||||||
|
<p>Thanks to Joachim Lindborg for all valuable feedback.</p>
|
||||||
|
</section1>
|
||||||
|
</xep>
|
||||||
295
inbox/roster-management.xml
Normal file
295
inbox/roster-management.xml
Normal file
@ -0,0 +1,295 @@
|
|||||||
|
<?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>Remote Roster Management</title>
|
||||||
|
<abstract>This document defines a way remote entities may manage user's roster to provide a simple way to keep rosters in sync.</abstract>
|
||||||
|
<legal>
|
||||||
|
<copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2012 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 'Specification'), 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 'AS IS' 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 <<link url='http://www.xmpp.org/extensions/ipr-policy.shtml'>http://www.xmpp.org/extensions/ipr-policy.shtml</link>> 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-0004</spec>
|
||||||
|
<spec>XEP-0100</spec>
|
||||||
|
</dependencies>
|
||||||
|
<supersedes/>
|
||||||
|
<supersededby/>
|
||||||
|
<shortname>NOT_YET_ASSIGNED</shortname>
|
||||||
|
<author>
|
||||||
|
<firstname>Sergey</firstname>
|
||||||
|
<surname>Dobrov</surname>
|
||||||
|
<email>binary@jrudevels.org</email>
|
||||||
|
<jid>binary@jrudevels.org</jid>
|
||||||
|
</author>
|
||||||
|
<author>
|
||||||
|
<firstname>Jan</firstname>
|
||||||
|
<surname>Kaluža</surname>
|
||||||
|
<email>hanzz.k@gmail.com</email>
|
||||||
|
<jid>hanzz@njs.netlab.cz</jid>
|
||||||
|
</author>
|
||||||
|
<revision>
|
||||||
|
<version>0.0.1</version>
|
||||||
|
<date>2012-12-07</date>
|
||||||
|
<initials>snd</initials>
|
||||||
|
<remark><p>First draft.</p></remark>
|
||||||
|
</revision>
|
||||||
|
</header>
|
||||||
|
<section1 topic='Introduction' anchor='intro'>
|
||||||
|
<p>It's often desirable for some XMPP based services to make it possible to manage user's roster to provide some contacts there. The most obvious example of such kind of service is a gateway to some legacy IM system (see &xep0100;). The current way that's recommended by the &xep0100; is to use the &xep0144; to synchronize items that's not sutiable in certain situations.</p>
|
||||||
|
</section1>
|
||||||
|
<section1 topic='Requirements' anchor='reqs'>
|
||||||
|
<p>This document addresses the following requirements:</p>
|
||||||
|
<ol>
|
||||||
|
<li>Make it possible for remote services or entities to manage user's roster by the same mechanisms that descibed in the &rfc6121;.</li>
|
||||||
|
<li>Provide a way for user to control which services have permission to manage his roster.</li>
|
||||||
|
</ol>
|
||||||
|
</section1>
|
||||||
|
<section1 topic='Glossary' anchor='glossary'>
|
||||||
|
<ul>
|
||||||
|
<li><strong>Remote entity</strong> — the entity that wants to modify user's roster.</li>
|
||||||
|
<li><strong>User</strong> — the entity which roster the remote entity wants to have access to.</li>
|
||||||
|
<li><strong>User's server</strong> — the XMPP server User connected to.</li>
|
||||||
|
<li><strong>Roster</strong> — the list of User's contacts as defined in the &rfc6121;.</li>
|
||||||
|
</ul>
|
||||||
|
</section1>
|
||||||
|
<section1 topic='Use Cases' anchor='usecases'>
|
||||||
|
<section2 topic='Remote entity asks for permission to manage user's roster' anchor='ask_permission'>
|
||||||
|
<p>In order to be able to make any changes to the user's roster the remote entity MUST ask permission to do so first.</p>
|
||||||
|
<p>NOTE: in order to be able to perform the query, the remote entity MUST have a presence subscription to the User</p>
|
||||||
|
<example caption='Remote entity asks for permission'><![CDATA[
|
||||||
|
<iq from='icq.example.com' to='juliet@example.com' type='set' id='roster_1'>
|
||||||
|
<query xmlns='urn:xmpp:tmp:roster-management:0' reason='Manage contacts in the ICQ contact list' type='request'/>
|
||||||
|
</iq>]]></example>
|
||||||
|
<p>If the presence subscription is absent, the server MUST NOT proceed with the request but MUST respond with the "forbidden" error:</p>
|
||||||
|
<example caption="The remote entity has no presence subscription"><![CDATA[
|
||||||
|
<iq from='juliet@example.com' to='icq.example.com' type='error' id='roster_1'>
|
||||||
|
<error type='modify'>
|
||||||
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
||||||
|
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>You must have a presence subscription to be able to request remote roster management service.</text>
|
||||||
|
</error>
|
||||||
|
</iq>]]></example>
|
||||||
|
<p>The user's server SHOULD then generate a form request using &xep0004; to client in order to ask user if he's OK with granting the permission to the remote entity. The "challenge" form field is generated by the server and is used to identify the client's response. The server also MUST immediatly answer to the request IQ.</p>
|
||||||
|
<p>NOTE: if the entity is already granted with the permission, the server SHOULD immediatly answer with a success response and skip querying the user.</p>
|
||||||
|
<example caption='Server asks user for the permission'><![CDATA[
|
||||||
|
<message from='example.com'
|
||||||
|
to='juliet@example.com'>
|
||||||
|
<body>icq.example.com wants to be able to manage your roster with following reason:
|
||||||
|
Manage contacts in the ICQ contact list
|
||||||
|
Do you want to allow it? Send "yes 5439123" or "no 5439123" back, pleas.</body>
|
||||||
|
<x xmlns='jabber:x:data' type='form'>
|
||||||
|
<title>Roster management permission request</title>
|
||||||
|
<instructions>icq.example.com wants to be able to manage your roster with following reason:
|
||||||
|
Manage contacts in the ICQ contact list.
|
||||||
|
Do you allow it?</instructions>
|
||||||
|
<field type='hidden' var='challenge'><value>5439123</value></field>
|
||||||
|
<field type='hidden' var='FORM_TYPE'>
|
||||||
|
<value>urn:xmpp:tmp:roster-management:0</value>
|
||||||
|
</field>
|
||||||
|
<field type='boolean'
|
||||||
|
label='Allow icq.example.com to edit roster?'
|
||||||
|
var='answer'>
|
||||||
|
<value>1</value>
|
||||||
|
</field>
|
||||||
|
</x>
|
||||||
|
</message>]]></example>
|
||||||
|
<p>The client can answer by submit the form or with a text message response:</p>
|
||||||
|
<example caption='Client responds with to the data form'><![CDATA[
|
||||||
|
<message from='juliet@example.com/home'
|
||||||
|
to='example.com'
|
||||||
|
xml:lang='en'>
|
||||||
|
<x xmlns='jabber:x:data' type='submit'>
|
||||||
|
<field var='FORM_TYPE'>
|
||||||
|
<value>urn:xmpp:tmp:roster-management:0</value>
|
||||||
|
</field>
|
||||||
|
<field var='challenge'><value>5439123</value></field>
|
||||||
|
<field var='answer'><value>1</value></field>
|
||||||
|
</x>
|
||||||
|
</message>]]></example>
|
||||||
|
<example caption='Client responds with a text message response'><![CDATA[
|
||||||
|
<message from='juliet@example.com/home'
|
||||||
|
to='example.com'
|
||||||
|
xml:lang='en'>
|
||||||
|
<body>yes 5439123</body>
|
||||||
|
</message>]]></example>
|
||||||
|
<section3 topic='The remote entity is allowed to manage roster' anchor='pemission_granted'>
|
||||||
|
<p>If the user allowed the roster management then the server MUST inform the remote entity that it has been granted the permission:</p>
|
||||||
|
<example caption='The server informs the remote entity that it's allowed to manage the User's roster'><![CDATA[
|
||||||
|
<iq from='juliet@example.com' to='icq.example.com' type='set' id='roster_2'>
|
||||||
|
<query xmlns='urn:xmpp:tmp:roster-management:0' type="allowed"/>
|
||||||
|
</iq>]]></example>
|
||||||
|
</section3>
|
||||||
|
<section3 topic='The remote entity is allowed to manage roster' anchor='pemission_granted'>
|
||||||
|
<p>If the user disallowed the roster management then the server MUST inform the remote entity that it hasn't been granted the permission:</p>
|
||||||
|
<example caption='The server informs the remote entity that it's allowed to manage the User's roster'><![CDATA[
|
||||||
|
<iq from='juliet@example.com' to='icq.example.com' type='set' id='roster_2'>
|
||||||
|
<query xmlns='urn:xmpp:tmp:roster-management:0' type="rejected"/>
|
||||||
|
</iq>]]></example>
|
||||||
|
</section3>
|
||||||
|
<section3 topic="Reject the permission to manage roster">
|
||||||
|
<p>In order to reject the permission to manage roster it's enough to reject entity's presence subscription:</p>
|
||||||
|
<example caption='The user rejects entity's presence subscription'><![CDATA[
|
||||||
|
<presence to='icq.ecample.com' type='unsubscribed'/>]]></example>
|
||||||
|
<p>If the presence subscription is restored then the permission is needed to be rerequested as defined above.</p>
|
||||||
|
</section3>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='The remote entity requests current user's roster' anchor='request_roster'>
|
||||||
|
<p>The remote entity being granted the permission to manage roster can request it from the User's server using usual jabber:iq:roster protocol to be able to edit it:</p>
|
||||||
|
<example caption='The remote entity requests current roster'><![CDATA[
|
||||||
|
<iq from='icq.example.com' to='juliet@example.com' type='get' id='roster_5'>
|
||||||
|
<query xmlns='jabber:iq:roster'/>
|
||||||
|
</iq>]]></example>
|
||||||
|
<p>The server MUST then answer with User's roster including there only the items that belongs to the entity's hostname:</p>
|
||||||
|
<example caption='The server responds with the roster'><![CDATA[
|
||||||
|
<iq to='icq.exampel.com' from='juliet@example.com' type='result' id='roster_5'>
|
||||||
|
<query xmlns='jabber:iq:roster'>
|
||||||
|
<item jid='123456789@icq.example.com'
|
||||||
|
name='Romeo'
|
||||||
|
subscription='both'>
|
||||||
|
<group>Friends</group>
|
||||||
|
</item>
|
||||||
|
<item jid='554323654@icq.example.com'
|
||||||
|
name='Mercutio'
|
||||||
|
subscription='from'>
|
||||||
|
<group>Friends</group>
|
||||||
|
</item>
|
||||||
|
<item jid='997665667@icq.example.com'
|
||||||
|
name='Benvolio'
|
||||||
|
subscription='both'>
|
||||||
|
<group>Friends</group>
|
||||||
|
</item>
|
||||||
|
</query>
|
||||||
|
</iq>]]></example>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='The user updates roster' anchor='user_update'>
|
||||||
|
<p>If client updates roster and this update affects the remote entity's contacts (i.e. belongs to it's hostname) then the server MUST forward these items to the remote entity:</p>
|
||||||
|
<example caption='The user updates roster'><![CDATA[
|
||||||
|
<iq from='juliet@example.com/chamber' type='set' id='roster_3'>
|
||||||
|
<query xmlns='jabber:iq:roster'>
|
||||||
|
<item jid='123456789@icq.example.net'
|
||||||
|
name='Romeo'
|
||||||
|
subscription='both'>
|
||||||
|
<group>Friends</group>
|
||||||
|
<group>Lovers</group>
|
||||||
|
</item>
|
||||||
|
</query>
|
||||||
|
</iq>]]></example>
|
||||||
|
<example caption='The server sends push roster request to the remote entity'><![CDATA[
|
||||||
|
<iq from='juliet@example.com' to='icq.example.com' type='set' id='roster_3'>
|
||||||
|
<query xmlns='jabber:iq:roster'>
|
||||||
|
<item jid='123456789@icq.example.net'
|
||||||
|
name='Romeo'
|
||||||
|
subscription='both'>
|
||||||
|
<group>Friends</group>
|
||||||
|
<group>Lovers</group>
|
||||||
|
</item>
|
||||||
|
</query>
|
||||||
|
</iq>]]></example>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='The remote entity updates the user's roster' anchor='entity_update'>
|
||||||
|
<p>The remote entity can also send the push query to the roster with the same semantics as specified for the jabber:iq:roster protocol described in the &rfc6121;:</p>
|
||||||
|
<example caption='The remote entity sends push roster request'><![CDATA[
|
||||||
|
<iq to='juliet@example.com' type='set' id='roster_3'>
|
||||||
|
<query xmlns='jabber:iq:roster'>
|
||||||
|
<item jid='123456789@icq.example.net'
|
||||||
|
name='Romeo'
|
||||||
|
subscription='both'>
|
||||||
|
<group>Friends</group>
|
||||||
|
<group>Lovers</group>
|
||||||
|
</item>
|
||||||
|
</query>
|
||||||
|
</iq>]]></example>
|
||||||
|
<p>The server MUST then inform the remote entity of success or an error and in the case of success also forward the push request to all connected User's resources.</p>
|
||||||
|
<p>If the entity tries to make changes into the items it's not allowed to, the server MUST NOT do any changes in the User's roster but respond to the entity with an error:</p>
|
||||||
|
<example caption='The server responds with an error'><![CDATA[
|
||||||
|
<iq from='juliet@example.com' type='set' id='roster_3'>
|
||||||
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
||||||
|
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>You have tried to modify the item you don't allowed to.</text>
|
||||||
|
</iq>]]></example>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Client requests list of components with permissions to edit his roster'>
|
||||||
|
<p>User can ask the server to provide a list of components or servers which have permissions to edit their roster.</p>
|
||||||
|
<example caption='User asks the server to get list of components which can edit their roster'><![CDATA[
|
||||||
|
<iq from='juliet@example.com/home' to='icq.example.com' type='get' id='roster_5'>
|
||||||
|
<query xmlns='urn:xmpp:tmp:roster-management:0'/>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>In this case, server responds with list of components or servers which can edit user's roster.</p>
|
||||||
|
<example caption='Server responds with list of componentss which can edit user's roster'><![CDATA[
|
||||||
|
<iq from='juliet@example.com/home' to='icq.example.com' type='result' id='roster_5'>
|
||||||
|
<query xmlns='urn:xmpp:tmp:roster-management:0'>
|
||||||
|
<item jid='icq.example.com' reason='Manage ICQ contacts.'/>
|
||||||
|
<item jid='j2j.example.com' reason='Manage Jabber gateway contacts.'/>
|
||||||
|
</query>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>Eventually, user can reject permission granted to component to edit their roster.</p>
|
||||||
|
|
||||||
|
<example caption='User rejects permissions to edit his roster'><![CDATA[
|
||||||
|
<iq from='juliet@example.com/home' to='icq.example.com' type='set' id='roster_6'>
|
||||||
|
<query xmlns='urn:xmpp:tmp:roster-management:0' type="reject"/>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
</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:roster-management:0'
|
||||||
|
xmlns='urn:xmpp:tmp:roster-management:0'
|
||||||
|
elementFormDefault='qualified'>
|
||||||
|
|
||||||
|
<xs:annotation>
|
||||||
|
<xs:documentation>
|
||||||
|
The protocol documented by this schema is defined in
|
||||||
|
XEP-XXXX: http://www.xmpp.org/extensions/xep-xxxx.html
|
||||||
|
</xs:documentation>
|
||||||
|
</xs:annotation>
|
||||||
|
|
||||||
|
<xs:element name='query'>
|
||||||
|
<xs:complexType>
|
||||||
|
<xs:attribute name='type' use='required'>
|
||||||
|
<xs:simpleType base='xs:NMTOKEN'>
|
||||||
|
<xs:enumeration value='request'/>
|
||||||
|
<xs:enumeration value='allowed'/>
|
||||||
|
<xs:enumeration value='rejected'/>
|
||||||
|
</xs:simpleType>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='reason' use='optional' type='xs:string'/>
|
||||||
|
<xs:sequence minOccurs='0'>
|
||||||
|
<xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
|
||||||
|
</xs:sequence>
|
||||||
|
</xs:complexType>
|
||||||
|
</xs:element>
|
||||||
|
|
||||||
|
<xs:element name='item'>
|
||||||
|
<xs:complexType>
|
||||||
|
<xs:simpleContent>
|
||||||
|
<xs:extension base='empty'>
|
||||||
|
<xs:attribute name='jid' type='fullJIDType' use='required'/>
|
||||||
|
<xs:attribute name='reason' type='xs:string' use='optional'/>
|
||||||
|
</xs:extension>
|
||||||
|
</xs:simpleContent>
|
||||||
|
</xs:complexType>
|
||||||
|
</xs:element>
|
||||||
|
|
||||||
|
</xs:schema>
|
||||||
|
]]></code>
|
||||||
|
</section1>
|
||||||
|
</xep>
|
||||||
1257
inbox/sensor-data.xml
Normal file
1257
inbox/sensor-data.xml
Normal file
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user