moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-23 17:52:15 -05:00
Code Issues Releases Wiki Activity

Bump ISR draft to revision 0.0.2

Browse Source
This commit is contained in:
Sam Whited 2016-03-15 11:24:29 -05:00
parent 3265193bab
commit 067e3ca4d7
1 changed files with 219 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
inbox/isr.xml
View File

@ -8,7 +8,7 @@
<header>
<title>Instant Stream Resumption</title>
<abstract>This specification introduces an mechanism for instant
<abstract>This specification introduces a mechanism for instant
stream resumption, based on Stream Management (XEP-0198), allowing
XMPP entities to instantaneously resume an XMPP stream.</abstract>
@ -75,6 +75,7 @@
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0198</spec>
<spec>XEP-0300</spec>
</dependencies>
<supersedes/>
<supersededby/>
@ -85,6 +86,12 @@
<email>flo@geekplace.eu</email>
<jid>flo@geekplace.eu</jid>
</author>
<revision>
<version>0.0.2</version>
<date>2016-03-11</date>
<initials>fs</initials>
<remark><p>Second draft.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2016-02-12</date>
@ -101,11 +108,11 @@
allowing for fast XMPP session (re-)establishment.</p>
<p>Compared to the existing stream resumption mechanism of <link
url='http://xmpp.org/extensions/xep-0198.html#resumption'>XEP-0198 §
5</link>, the approach defined herein reduces the round trips
url='http://xmpp.org/extensions/xep-0198.html#resumption'><cite>XEP-0198</cite>
§ 5</link>, the approach defined herein reduces the round trips
required to resume a stream to exactly <em>one</em> (besides the
round trips required by the TLS handshake). This is achieved by
using only a secure token to resume the stream.</p>
using just a secure key to resume the stream.</p>
</section1>
@ -117,9 +124,14 @@
<dd>Instant Stream Resumption.</dd>
</di>
<di>
<dt>Instant Stream Resumption Token (ISR Token)</dt>
<dd>A string token with at least 128 bits of entropy generated
by a cryptographically secure random number generator.</dd>
<dt>Instant Stream Resumption Key (ISR Key)</dt>
<dd>A key, represented as string, which contains at least 128
bits of entropy generated by a cryptographically secure random
number generator.</dd>
</di>
<di>
<dt>TLS</dt>
<dd>Transport Layer Security (&rfc5246;).</dd>
</di>
</dl>
@ -131,40 +143,42 @@
</section1>
-->
<section1 topic='Obtaining a Instant Stream Resumption Token' anchor='obtain'>
<section1 topic='Obtaining a Instant Stream Resumption Key' anchor='obtain'>
<p>If an entity supports ISR, then the &lt;enabled/&gt;
Nonza<note>XEP-0360: Nonzas (are not Stanzas) &lt;<link
url='https://xmpp.org/extensions/xep-0360.html'>https://xmpp.org/extensions/xep-0360.html</link>&gt;.</note>,
which is send as positive reply upon a request to enable Stream
Management, MUST contain an 'tok' attribute qualified by the
'urn:xmpp:isr:0' namespace containing a ISR Token. The Nonza MAY
Management, MUST contain an 'key' attribute qualified by the
'urn:xmpp:isr:0' namespace containing a ISR Key. The Nonza MAY
also contain a 'location' attribute qualified by the
'urn:xmpp:isr:0' namespace which specifies the preferred IP address
or hostname, and a TCP port number of the host which should be used
for instant stream resumption.</p>
<example caption='An &lt;enabled/&gt; Nonza with a ISR token'><![CDATA[
<example caption='An &lt;enabled/&gt; Nonza with a ISR key'><![CDATA[
<enabled
xmlns='urn:xmpp:sm:3'
xmlns:isr='urn:xmpp:isr:0'
isr:tok='a0b9162d-0981-4c7d-9174-1f55aedd1f52'/>]]></example>
isr:key='a0b9162d-0981-4c7d-9174-1f55aedd1f52'/>]]></example>
<example caption='An &lt;enabled/&gt; Nonza with a ISR token and location'><![CDATA[
<example caption='An &lt;enabled/&gt; Nonza with a ISR key and location'><![CDATA[
<enabled
xmlns='urn:xmpp:sm:3'
xmlns:isr='urn:xmpp:isr:0'
isr:tok='a0b9162d-0981-4c7d-9174-1f55aedd1f52'
isr:key='a0b9162d-0981-4c7d-9174-1f55aedd1f52'
isr:location='isr.example.org:5222'/>]]></example>
</section1>
<section1 topic='Instant Stream Resumption' anchor='isr'>
<p>In order to instantaneously resume an XMPP stream the entity
trying to do so must posses a valid ISR token. If it then needs to
perform ISR, it first determines the host for resumption, and after
that, tries to perform the instant stream resumption.</p>
<p>In order to instantaneously resume an XMPP stream the initiating
entity, which is either an XMPP client or server, must posses a
valid ISR key. After it has obtained the ISR key, using the process
described in the previous section, it first determines the host for
resumption, and after that, tries to perform the instant stream
resumption.</p>
<section2 topic='Determing the Host for Resumption' anchor='host'>
@ -172,12 +186,14 @@
resumption is as follows:</p>
<ol>
<li>The host specified in the optional 'location' attribute
<li>The host provided in the optional 'location' attribute
qualified by the 'urn:xmpp:isr:0' namespace found in the
&lt;enabled/&gt; element of XEP-0198.
&lt;enabled/&gt; element of <cite>XEP-0198</cite> (the
"isr:location").
</li>
<li>The hosts determined by means of &xep0368;.</li>
<li>The host announced in the 'location' attribute of the &lt;enabled/&gt; Nonza defined in XEP-0198.</li>
<li>The host announced in the 'location' attribute of the
&lt;enabled/&gt; Nonza defined in <cite>XEP-0198</cite>.</li>
<li>Standard host lookup mechanisms.</li>
</ol>
@ -186,40 +202,61 @@
<p>Note that the hosts announced by the 'location' attribute
qualified by the 'urn:xmpp:isr:0' namespace MUST be connected to
using Transport Layer Security (TLS, see &rfc5246;) from the
beginning, i.e. &lt;starttls/&gt; MUST NOT be used, instead the
TLS Handshake is performed right after establishing the
connection.</p>
using TLS from the beginning, i.e. &lt;starttls/&gt; MUST NOT be
used, instead the TLS handshake is performed right after
establishing the connection.</p>
<p>The order prefers hosts which allow connections where TLS is
enabled from the beginning. This is desirable in order to reduce
the required round trips by skipping the &lt;starttls/&gt;
step.</p>
<p>This order prefers hosts which allow connections where TLS is
enabled from the beginning. This is desirable to reduce the
required round trips by skipping the &lt;starttls/&gt; step.</p>
</section2>
<section2 topic='Performing Instant Stream Resumption' anchor='resume'>
<p>After the host on which the instant stream resumption should be
performed was determined, the entity connects to, and establishes
TLS by either</p>
<p>After the remote host on which the instant stream resumption
should be performed was determined, the initiating entity connects
to the host, and establishes TLS by either</p>
<ol>
<li>establishing a TLS session right away, or</li>
<li>performing STARTTLS (&rfc6120; § 5).</li>
</ol>
<p>After the connection has been secured, the
initiating entity sends an XMPP &lt;stream&gt; open element
followed by a &lt;instant-resume/&gt; Nonza qualified by the
'urn:xmpp:isr:0' namespace which MUST contain the ISR token in the
'tok' attribute and the sequence number of the last by Stream
Management handled stanza in the 'h' attribute.</p>
<p>Next, the initiating entity sends an XMPP &lt;stream&gt; open
element followed by a &lt;instant-resume/&gt; Nonza qualified by
the 'urn:xmpp:isr:0' namespace which MUST contain the previous
stream identifier, the <cite>XEP-0198</cite> "SM-ID", in the
'previd' attribute, the sequence number of the last by Stream
Management handled stanza in the 'h' attribute and the
initiator-hmac as value of at least one &lt;hash/&gt; element as
specified by &xep0300;, which are put as child elements under the
&lt;hmac/&gt; element.</p>
<p>The initiator-hmac is defined as follows:</p>
<p class='box'>
initiator-hamc = Base64(HMAC(key, "Initiator" ||
tls-server-end-point))
</p>
<p>The function defined in &rfc2104; is used to compute the HMAC
using the hash algorithm specified in the 'algo' attribute of the
&lt;hash/&gt; element as the cryptographic hash function H. The
ISR Key is used as key of the HMAC. And the bytewise concatnation
of the ASCII String "Initiator" and the bytes from
tls-server-end-point, which a TLS Channel Binding defined in
&rfc5929; § 4, is used a the HMAC text. The resulting bytes of the
HMAC function are encoded using Base64 as defined in &rfc4648;
<link url='https://tools.ietf.org/html/rfc4648#section-4'>§
4</link> and resulting string is used as text value of the
&lt;hash/&gt; element.</p>
<p>Note that the initiating entity SHOULD pipeline the instant
stream resumption request together with then initial
&lt;stream&gt; open element since it already has determined that
the service supports this feature. Servers MUST announce that they
&lt;stream&gt; open element. The initiating entity is able to do
so since it already knows that the service supports ISR because it
announced an ISR key. Servers MUST nevertheless announce that they
support ISR by including an &lt;isr/&gt; element qualified by the
'urn:xmpp:isr:0' namespace in their stream features.</p>
@ -233,8 +270,14 @@
xmlns:stream='http://etherx.jabber.org/streams'>
<inst-resume
xmlns='urn:xmpp:isr:0'
tok='a0b9162d-0981-4c7d-9174-1f55aedd1f52'
h='42'/>]]></example>
previd='some-long-sm-id'
h='42'>
<hmac>
<hash xmlns='urn:xmpp:hashes:1' algo='sha256'>
initator-hmac
</hash>
</hmac>
</inst-resume>]]></example>
<p>ISR MUST only be performed over TLS secured sessions. What
follows is that the ISR feature MUST only be announced after
@ -244,9 +287,25 @@
<section3 topic='Successful Stream Resumption' anchor='isr-success'>
<p>On success the server replies with &lt;inst-resumed/&gt;
Nonza which MUST contain a <em>new</em> ISR Token found in the
'tok' attribute and the sequence number of the last by Stream
Mangement handled stanza in the 'h' attribute.</p>
Nonza which MUST contain a <em>new</em> ISR Key found in the
'key' attribute, the sequence number of the last by Stream
Mangement handled stanza in the 'h' attribute and the
'responder-hmac' as value of the &lt;hash/&gt; element being a
child of the &lt;hamc/&gt; element.</p>
<p>The responder-hmac is defined as follows:</p>
<p class='box'>
responder-hmac = Base64(HMAC(key, "Responder" ||
tls-server-end-point))
</p>
<p>That is, it is the same as the initiator-hamc, but instead of
using the ASCII string "Initiator", the ASCII string "Responder"
is used.</p>
<p>The initiating entity is required to verify the
responder-hmac achieve mutual authentication.</p>
<example caption='Server acknowledges instant stream resumption'><![CDATA[
<stream:stream
@ -262,17 +321,23 @@
</stream:features>
<inst-resumed
xmlns='urn:xmpp:isr:0'
tok='006b1a29-c549-41c7-a12c-2a931822f8c0'
h='21'/>]]></example>
key='006b1a29-c549-41c7-a12c-2a931822f8c0'
h='21'>
<hmac>
<hash xmlns='urn:xmpp:hashes:1' algo='sha-256'>
responder-hmac
</hash>
</hmac>
</inst-resumed>]]></example>
<p>After the &lt;inst-resumed/&gt; was received both entities
MUST consider the resumed stream to re-established. This
includes all previously negotiated stream features like
&xep0138;. It does however not include the specific state of the
features: For example in case of stream compression, the
dictionary used by the compression mechanism of the resumed
stream MUST NOT be considered to be restored after instant
stream resumption.</p>
<p>After the &lt;inst-resumed/&gt; was received and has been
verified both entities MUST consider the resumed stream to be
re-established. This includes all previously negotiated stream
features like &xep0138;. It does however not include the
specific state of the features: For example in case of Stream
Compression, the dictionary used by the compression mechanism of
the resumed stream MUST NOT be considered to be restored after
instant stream resumption.</p>
</section3>
@ -287,10 +352,10 @@
xmlns='urn:xmpp:isr:0'/>]]></example>
<p>The server MAY also include a 'h' attribute in the
&lt;failed/&gt; element indicating the number of handled
stanzas.</p>
&lt;failed/&gt; element indicating the number of stanzas it has
handled so far.</p>
<example caption='Server indicates instant stream resumption failure'><![CDATA[
<example caption='Server indicates failure with handled stanzas count'><![CDATA[
<failed
xmlns='urn:xmpp:isr:0'
h='22'/>]]></example>
@ -308,7 +373,7 @@
<section1 topic='Security Considerations' anchor='security'>
<p>It is of vital importance that the Instant Stream Resumption Token
<p>It is of vital importance that the Instant Stream Resumption Key
is generated by a cryptographically secure random generator. See
&rfc4086; for more information about Randomness Requirements for
Security</p>
@ -336,7 +401,7 @@
<section1 topic='Acknowledgements' anchor='acknowledgements'>
<p>Thanks to Jonas Wielicki for his feedback.</p>
<p>Thanks to Jonas Wielicki and Thijs Alkemade for their feedback.</p>
</section1>