Bump ISR draft to revision 0.0.2

inbox/isr.xml

@@ -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>
 
@@ -16,55 +16,55 @@
     <copyright>This XMPP Extension Protocol is copyright (c) 1999 -
     2016 by the XMPP Standards Foundation (XSF).</copyright>
 
-	<permissions>Permission is hereby granted, free of charge, to any
+  <permissions>Permission is hereby granted, free of charge, to any
-	person obtaining a copy of this specification (the
+    person obtaining a copy of this specification (the
-	&quot;Specification&quot;), to make use of the Specification
+    &quot;Specification&quot;), to make use of the Specification
-	without restriction, including without limitation the rights to
+    without restriction, including without limitation the rights to
-	implement the Specification in a software program, deploy the
+    implement the Specification in a software program, deploy the
-	Specification in a network service, and copy, modify, merge,
+    Specification in a network service, and copy, modify, merge,
-	publish, translate, distribute, sublicense, or sell copies of the
+    publish, translate, distribute, sublicense, or sell copies of the
-	Specification, and to permit persons to whom the Specification is
+    Specification, and to permit persons to whom the Specification is
-	furnished to do so, subject to the condition that the foregoing
+    furnished to do so, subject to the condition that the foregoing
-	copyright notice and this permission notice shall be included in
+    copyright notice and this permission notice shall be included in
-	all copies or substantial portions of the Specification. Unless
+    all copies or substantial portions of the Specification. Unless
-	separate permission is granted, modified works that are
+    separate permission is granted, modified works that are
-	redistributed shall not contain misleading information regarding
+    redistributed shall not contain misleading information regarding
-	the authors, title, number, or publisher of the Specification, and
+    the authors, title, number, or publisher of the Specification, and
-	shall not claim endorsement of the modified works by the authors,
+    shall not claim endorsement of the modified works by the authors,
-	any organization or project to which the authors belong, or the
+    any organization or project to which the authors belong, or the
-	XMPP Standards Foundation.</permissions>
+    XMPP Standards Foundation.</permissions>
 
-	<warranty>## NOTE WELL: This Specification is provided on an
+  <warranty>## NOTE WELL: This Specification is provided on an
-	&quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-	KIND, express or implied, including, without limitation, any
+    KIND, express or implied, including, without limitation, any
-	warranties or conditions of TITLE, NON-INFRINGEMENT,
+    warranties or conditions of TITLE, NON-INFRINGEMENT,
-	MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event
+    MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event
-	shall the XMPP Standards Foundation or the authors of this
+    shall the XMPP Standards Foundation or the authors of this
-	Specification be liable for any claim, damages, or other
+    Specification be liable for any claim, damages, or other
-	liability, whether in an action of contract, tort, or otherwise,
+    liability, whether in an action of contract, tort, or otherwise,
-	arising from, out of, or in connection with the Specification or
+    arising from, out of, or in connection with the Specification or
-	the implementation, deployment, or other use of the
+    the implementation, deployment, or other use of the
-	Specification. ##</warranty>
+    Specification. ##</warranty>
 
-	<liability>In no event and under no legal theory, whether in tort
+  <liability>In no event and under no legal theory, whether in tort
-	(including negligence), contract, or otherwise, unless required by
+    (including negligence), contract, or otherwise, unless required by
-	applicable law (such as deliberate and grossly negligent acts) or
+    applicable law (such as deliberate and grossly negligent acts) or
-	agreed to in writing, shall the XMPP Standards Foundation or any
+    agreed to in writing, shall the XMPP Standards Foundation or any
-	author of this Specification be liable for damages, including any
+    author of this Specification be liable for damages, including any
-	direct, indirect, special, incidental, or consequential damages of
+    direct, indirect, special, incidental, or consequential damages of
-	any character arising out of the use or inability to use the
+    any character arising out of the use or inability to use the
-	Specification (including but not limited to damages for loss of
+    Specification (including but not limited to damages for loss of
-	goodwill, work stoppage, computer failure or malfunction, or any
+    goodwill, work stoppage, computer failure or malfunction, or any
-	and all other commercial damages or losses), even if the XMPP
+    and all other commercial damages or losses), even if the XMPP
-	Standards Foundation or such author has been advised of the
+    Standards Foundation or such author has been advised of the
-	possibility of such damages.</liability>
+    possibility of such damages.</liability>
 
-	<conformance>This XMPP Extension Protocol has been contributed in
+  <conformance>This XMPP Extension Protocol has been contributed in
-	full conformance with the XSF's Intellectual Property Rights
+    full conformance with the XSF's Intellectual Property Rights
-	Policy (a copy of which may be found at &lt;<link
+    Policy (a copy of which may be found at &lt;<link
-	url='http://xmpp.org/extensions/ipr-policy.shtml'>http://xmpp.org/extensions/ipr-policy.shtml</link>&gt;
+      url='http://xmpp.org/extensions/ipr-policy.shtml'>http://xmpp.org/extensions/ipr-policy.shtml</link>&gt;
-	or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201
+    or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201
-	USA).</conformance>
+    USA).</conformance>
   </legal>
 
   <number>xxxx</number>
@@ -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,26 +108,31 @@
   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 §
+  url='http://xmpp.org/extensions/xep-0198.html#resumption'><cite>XEP-0198</cite>
-  5</link>, the approach defined herein reduces the round trips
+  § 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>
 
 <section1 topic='Glossary' anchor='glossary'>
 
   <dl>
-	<di>
+  <di>
-	  <dt>ISR</dt>
+    <dt>ISR</dt>
-	  <dd>Instant Stream Resumption.</dd>
+    <dd>Instant Stream Resumption.</dd>
-	</di>
+  </di>
-	<di>
+  <di>
-	  <dt>Instant Stream Resumption Token (ISR Token)</dt>
+    <dt>Instant Stream Resumption Key (ISR Key)</dt>
-	  <dd>A string token with at least 128 bits of entropy generated
+    <dd>A key, represented as string, which contains at least 128
-	  by a cryptographically secure random number generator.</dd>
+    bits of entropy generated by a cryptographically secure random
-	</di>
+    number generator.</dd>
+  </di>
+  <di>
+    <dt>TLS</dt>
+    <dd>Transport Layer Security (&rfc5246;).</dd>
+  </di>
   </dl>
 
 </section1>
@@ -131,99 +143,124 @@
 </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
+  Management, MUST contain an 'key' attribute qualified by the
-  'urn:xmpp:isr:0' namespace containing a ISR Token. The Nonza MAY
+  '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
+  <p>In order to instantaneously resume an XMPP stream the initiating
-  trying to do so must posses a valid ISR token. If it then needs to
+  entity, which is either an XMPP client or server, must posses a
-  perform ISR, it first determines the host for resumption, and after
+  valid ISR key. After it has obtained the ISR key, using the process
-  that, tries to perform the instant stream resumption.</p>
+  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'>
 
-	<p>The lookup mechanism order to determine host candidates for ISR
+  <p>The lookup mechanism order to determine host candidates for ISR
-	resumption is as follows:</p>
+  resumption is as follows:</p>
 
-	<ol>
+  <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
+    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
-	  </li>
+    "isr:location").
-	  <li>The hosts determined by means of &xep0368;.</li>
+    </li>
-	  <li>The host announced in the 'location' attribute of the &lt;enabled/&gt; Nonza defined in XEP-0198.</li>
+    <li>The hosts determined by means of &xep0368;.</li>
-	  <li>Standard host lookup mechanisms.</li>
+    <li>The host announced in the 'location' attribute of the
-	</ol>
+    &lt;enabled/&gt; Nonza defined in <cite>XEP-0198</cite>.</li>
+    <li>Standard host lookup mechanisms.</li>
+  </ol>
 
-	<p>The host candidates retrieved by those mechanisms SHOULD be
+  <p>The host candidates retrieved by those mechanisms SHOULD be
-	tried by the initiating entity in this order.</p>
+  tried by the initiating entity in this order.</p>
 
-	<p>Note that the hosts announced by the 'location' attribute
+  <p>Note that the hosts announced by the 'location' attribute
-	qualified by the 'urn:xmpp:isr:0' namespace MUST be connected to
+  qualified by the 'urn:xmpp:isr:0' namespace MUST be connected to
-	using Transport Layer Security (TLS, see &rfc5246;) from the
+  using TLS from the beginning, i.e. &lt;starttls/&gt; MUST NOT be
-	beginning, i.e. &lt;starttls/&gt; MUST NOT be used, instead the
+  used, instead the TLS handshake is performed right after
-	TLS Handshake is performed right after establishing the
+  establishing the connection.</p>
-	connection.</p>
 
-	<p>The order prefers hosts which allow connections where TLS is
+  <p>This order prefers hosts which allow connections where TLS is
-	enabled from the beginning. This is desirable in order to reduce
+  enabled from the beginning. This is desirable to reduce the
-	the required round trips by skipping the &lt;starttls/&gt;
+  required round trips by skipping the &lt;starttls/&gt; step.</p>
-	step.</p>
 
   </section2>
 
   <section2 topic='Performing Instant Stream Resumption' anchor='resume'>
 
-	<p>After the host on which the instant stream resumption should be
+  <p>After the remote host on which the instant stream resumption
-	performed was determined, the entity connects to, and establishes
+  should be performed was determined, the initiating entity connects
-	TLS by either</p>
+  to the host, and establishes TLS by either</p>
 
-	<ol>
+  <ol>
-	  <li>establishing a TLS session right away, or</li>
+    <li>establishing a TLS session right away, or</li>
-	  <li>performing STARTTLS (&rfc6120; § 5).</li>
+    <li>performing STARTTLS (&rfc6120; § 5).</li>
-	</ol>
+  </ol>
 
-	<p>After the connection has been secured, the
+  <p>Next, the initiating entity sends an XMPP &lt;stream&gt; open
-	initiating entity sends an XMPP &lt;stream&gt; open element
+  element followed by a &lt;instant-resume/&gt; Nonza qualified by
-	followed by a &lt;instant-resume/&gt; Nonza qualified by the
+  the 'urn:xmpp:isr:0' namespace which MUST contain the previous
-	'urn:xmpp:isr:0' namespace which MUST contain the ISR token in the
+  stream identifier, the <cite>XEP-0198</cite> "SM-ID", in the
-	'tok' attribute and the sequence number of the last by Stream
+  'previd' attribute, the sequence number of the last by Stream
-	Management handled stanza in the 'h' attribute.</p>
+  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>Note that the initiating entity SHOULD pipeline the instant
+  <p>The initiator-hmac is defined as follows:</p>
-	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
-	support ISR by including an &lt;isr/&gt; element qualified by the
-	'urn:xmpp:isr:0' namespace in their stream features.</p>
 
-	<example caption='Initiating entity requests instant stream resumption'><![CDATA[
+  <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. 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>
+
+  <example caption='Initiating entity requests instant stream resumption'><![CDATA[
 <stream:stream
  from='juliet@im.example.com'
  to='im.example.com'
@@ -233,22 +270,44 @@
  xmlns:stream='http://etherx.jabber.org/streams'>
 <inst-resume
   xmlns='urn:xmpp:isr:0'
-  tok='a0b9162d-0981-4c7d-9174-1f55aedd1f52'
+  previd='some-long-sm-id'
-  h='42'/>]]></example>
+  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
+  <p>ISR MUST only be performed over TLS secured sessions. What
-	follows is that the ISR feature MUST only be announced after
+  follows is that the ISR feature MUST only be announced after
-	STARTTLS has been successfully performed or on streams where TLS
+  STARTTLS has been successfully performed or on streams where TLS
-	was established from the beginning.</p>
+  was established from the beginning.</p>
 
-	<section3 topic='Successful Stream Resumption' anchor='isr-success'>
+  <section3 topic='Successful Stream Resumption' anchor='isr-success'>
 
-	  <p>On success the server replies with &lt;inst-resumed/&gt;
+  <p>On success the server replies with &lt;inst-resumed/&gt;
-	  Nonza which MUST contain a <em>new</em> ISR Token found in the
+  Nonza which MUST contain a <em>new</em> ISR Key found in the
-	  'tok' attribute and the sequence number of the last by Stream
+  'key' attribute, the sequence number of the last by Stream
-	  Mangement handled stanza in the 'h' attribute.</p>
+  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>
 
-	  <example caption='Server acknowledges instant stream resumption'><![CDATA[
+  <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
   from='im.example.com'
   id='t7AMCin9zjMNwQKDnplntZPIDEI='
@@ -262,45 +321,51 @@
 </stream:features>
 <inst-resumed
   xmlns='urn:xmpp:isr:0'
-  tok='006b1a29-c549-41c7-a12c-2a931822f8c0'
+  key='006b1a29-c549-41c7-a12c-2a931822f8c0'
-  h='21'/>]]></example>
+  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
+  <p>After the &lt;inst-resumed/&gt; was received and has been
-	  MUST consider the resumed stream to re-established. This
+  verified both entities MUST consider the resumed stream to be
-	  includes all previously negotiated stream features like
+  re-established. This includes all previously negotiated stream
-	  &xep0138;. It does however not include the specific state of the
+  features like &xep0138;. It does however not include the
-	  features: For example in case of stream compression, the
+  specific state of the features: For example in case of Stream
-	  dictionary used by the compression mechanism of the resumed
+  Compression, the dictionary used by the compression mechanism of
-	  stream MUST NOT be considered to be restored after instant
+  the resumed stream MUST NOT be considered to be restored after
-	  stream resumption.</p>
+  instant stream resumption.</p>
 
-	</section3>
+  </section3>
 
-	<section3 topic='Failed Stream Resumptino' anchor='isr-failed'>
+  <section3 topic='Failed Stream Resumptino' anchor='isr-failed'>
 
-	  <p>If the server is unable to resume the stream instantly it
+    <p>If the server is unable to resume the stream instantly it
-	  MUST reply with a &lt;failed/&gt; Nonza qualified by the
+      MUST reply with a &lt;failed/&gt; Nonza qualified by the
-	  'urn:xmpp:isr:0' namespace.</p>
+      'urn:xmpp:isr:0' namespace.</p>
 
-	  <example caption='Server indicates instant stream resumption failure'><![CDATA[
+    <example caption='Server indicates instant stream resumption failure'><![CDATA[
 <failed
   xmlns='urn:xmpp:isr:0'/>]]></example>
 
-	  <p>The server MAY also include a 'h' attribute in the
+    <p>The server MAY also include a 'h' attribute in the
-	  &lt;failed/&gt; element indicating the number of handled
+      &lt;failed/&gt; element indicating the number of stanzas it has
-	  stanzas.</p>
+      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>
 
-	  <p>Instant stream resumption errors SHOULD be considered
+    <p>Instant stream resumption errors SHOULD be considered
-	  recoverable, the initiating entity MAY continue with normal
+      recoverable, the initiating entity MAY continue with normal
-	  session establishment; however, misuse of stream management MAY
+      session establishment; however, misuse of stream management MAY
-	  result in termination of the stream.</p>
+      result in termination of the stream.</p>
 
-	</section3>
+  </section3>
 
   </section2>
 
@@ -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>