xeps/inbox/isr.xml

<?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>Instant Stream Resumption</title>

  <abstract>This specification introduces an mechanism for instant
  stream resumption, based on Stream Management (XEP-0198), allowing
  XMPP entities to instantaneously resume an XMPP stream.</abstract>

  <legal>
    <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
	person obtaining a copy of this specification (the
	&quot;Specification&quot;), to make use of the Specification
	without restriction, including without limitation the rights to
	implement the Specification in a software program, deploy the
	Specification in a network service, and copy, modify, merge,
	publish, translate, distribute, sublicense, or sell copies of the
	Specification, and to permit persons to whom the Specification is
	furnished to do so, subject to the condition that the foregoing
	copyright notice and this permission notice shall be included in
	all copies or substantial portions of the Specification. Unless
	separate permission is granted, modified works that are
	redistributed shall not contain misleading information regarding
	the authors, title, number, or publisher of the Specification, and
	shall not claim endorsement of the modified works by the authors,
	any organization or project to which the authors belong, or the
	XMPP Standards Foundation.</permissions>

	<warranty>## NOTE WELL: This Specification is provided on an
	&quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, express or implied, including, without limitation, any
	warranties or conditions of TITLE, NON-INFRINGEMENT,
	MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event
	shall the XMPP Standards Foundation or the authors of this
	Specification be liable for any claim, damages, or other
	liability, whether in an action of contract, tort, or otherwise,
	arising from, out of, or in connection with the Specification or
	the implementation, deployment, or other use of the
	Specification. ##</warranty>

	<liability>In no event and under no legal theory, whether in tort
	(including negligence), contract, or otherwise, unless required by
	applicable law (such as deliberate and grossly negligent acts) or
	agreed to in writing, shall the XMPP Standards Foundation or any
	author of this Specification be liable for damages, including any
	direct, indirect, special, incidental, or consequential damages of
	any character arising out of the use or inability to use the
	Specification (including but not limited to damages for loss of
	goodwill, work stoppage, computer failure or malfunction, or any
	and all other commercial damages or losses), even if the XMPP
	Standards Foundation or such author has been advised of the
	possibility of such damages.</liability>

	<conformance>This XMPP Extension Protocol has been contributed in
	full conformance with the XSF's Intellectual Property Rights
	Policy (a copy of which may be found at &lt;<link
	url='http://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
	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-0198</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>isr</shortname>
  <author>
    <firstname>Florian</firstname>
    <surname>Schmaus</surname>
    <email>flo@geekplace.eu</email>
    <jid>flo@geekplace.eu</jid>
  </author>
  <revision>
    <version>0.0.1</version>
    <date>2016-02-12</date>
    <initials>fs</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>

  <p>This XEP specifies an instant stream resumption mechanism based
  on &xep0198;, allowing XMPP entities to instantaneously resume an
  XMPP stream. This can be seen as the complementary part to &xep0305;
  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
  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>
  
</section1>

<section1 topic='Glossary' anchor='glossary'>

  <dl>
	<di>
	  <dt>ISR</dt>
	  <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>
	</di>
  </dl>

</section1>

<!--
<section1 topic='Use Cases' anchor='usecases'>
  <p>STRONGLY RECOMMENDED.</p>
</section1>
-->

<section1 topic='Obtaining a Instant Stream Resumption Token' 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
  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[
<enabled
  xmlns='urn:xmpp:sm:3'
  xmlns:isr='urn:xmpp:isr:0'
  isr:tok='a0b9162d-0981-4c7d-9174-1f55aedd1f52'/>]]></example>

	<example caption='An &lt;enabled/&gt; Nonza with a ISR token and location'><![CDATA[
<enabled
  xmlns='urn:xmpp:sm:3'
  xmlns:isr='urn:xmpp:isr:0'
  isr:tok='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>

  <section2 topic='Determing the Host for Resumption' anchor='host'>

	<p>The lookup mechanism order to determine host candidates for ISR
	resumption is as follows:</p>

	<ol>
	  <li>The host specified in the optional 'location' attribute
	  qualified by the 'urn:xmpp:isr:0' namespace found in the
	  &lt;enabled/&gt; element of XEP-0198.
	  </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>Standard host lookup mechanisms.</li>
	</ol>

	<p>The host candidates retrieved by those mechanisms SHOULD be
	tried by the initiating entity in this order.</p>

	<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>

	<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>

  </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>

	<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>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
	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'
 version='1.0'
 xml:lang='en'
 xmlns='jabber:client'
 xmlns:stream='http://etherx.jabber.org/streams'>
<inst-resume
  xmlns='urn:xmpp:isr:0'
  tok='a0b9162d-0981-4c7d-9174-1f55aedd1f52'
  h='42'/>]]></example>

	<p>ISR MUST only be performed over TLS secured sessions. What
	follows is that the ISR feature MUST only be announced after
	STARTTLS has been successfully performed or on streams where TLS
	was established from the beginning.</p>

	<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>

	  <example caption='Server acknowledges instant stream resumption'><![CDATA[
<stream:stream
  from='im.example.com'
  id='t7AMCin9zjMNwQKDnplntZPIDEI='
  to='juliet@im.example.com'
  version='1.0'
  xml:lang='en'
  xmlns='jabber:client'
  xmlns:stream='http://etherx.jabber.org/streams'>
<stream:features>
 <isr xmlns='urn:xmpp:isr:0'/>
</stream:features>
<inst-resumed
  xmlns='urn:xmpp:isr:0'
  tok='006b1a29-c549-41c7-a12c-2a931822f8c0'
  h='21'/>]]></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>

	</section3>

	<section3 topic='Failed Stream Resumptino' anchor='isr-failed'>
	  
	  <p>If the server is unable to resume the stream instantly it
	  MUST reply with a &lt;failed/&gt; Nonza qualified by the
	  'urn:xmpp:isr:0' namespace.</p>

	  <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
	  &lt;failed/&gt; element indicating the number of handled
	  stanzas.</p>

	  <example caption='Server indicates instant stream resumption failure'><![CDATA[
<failed
  xmlns='urn:xmpp:isr:0'
  h='22'/>]]></example>

	  <p>Instant stream resumption errors SHOULD be considered
	  recoverable, the initiating entity MAY continue with normal
	  session establishment; however, misuse of stream management MAY
	  result in termination of the stream.</p>

	</section3>

  </section2>

</section1>

<section1 topic='Security Considerations' anchor='security'>

  <p>It is of vital importance that the Instant Stream Resumption Token
  is generated by a cryptographically secure random generator. See
  &rfc4086; for more information about Randomness Requirements for
  Security</p>

</section1>

<section1 topic='IANA Considerations' anchor='iana'>

  <p>This document requires no interaction with &IANA;.</p>

</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>

  <p>The &REGISTRAR; includes 'urn:xmpp:isr:0' in its registry of protocol namespaces (see &NAMESPACES;).</p>


</section1>

<section1 topic='XML Schema' anchor='schema'>

  <p>TODO: Add after the XEP leaves the 'experimental' state.</p>

</section1>

<section1 topic='Acknowledgements' anchor='acknowledgements'>

  <p>Thanks to Jonas Wielicki for his feedback.</p>

</section1>

</xep>