No Description
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

xep-0397.xml 18KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473
  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY % ents SYSTEM 'xep.ent'>
  4. <!ENTITY tls13 "<span class='ref'><link url='https://tools.ietf.org/html/draft-ietf-tls-tls13-21'>draft-ietf-tls-tls13-21</link></span> <note>The Transport Layer Security (TLS) Protocol Version 1.3 &lt;<link url='https://tools.ietf.org/html/draft-ietf-tls-tls13-21'>https://tools.ietf.org/html/draft-ietf-tls-tls13-21</link>&gt;.</note>" >
  5. <!ENTITY sasl-ht "<span class='ref'><link url='https://tools.ietf.org/html/draft-schmaus-kitten-sasl-ht-03'>draft-schmaus-sasl-ht-03</link></span><note>draft-schmaus-sasl-ht-03: The Hashed Token SASL Mechanism &lt;<link url='https://tools.ietf.org/html/draft-schmaus-kitten-sasl-ht-03'>https://tools.ietf.org/html/draft-schmaus-kitten-sasl-ht-03</link>&gt;.</note>" >
  6. %ents;
  7. ]>
  8. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  9. <xep>
  10. <header>
  11. <title>Instant Stream Resumption</title>
  12. <abstract>This specification introduces a mechanism for instant
  13. stream resumption, based on Stream Management (XEP-0198), allowing
  14. XMPP entities to instantaneously resume an XMPP stream.</abstract>
  15. &LEGALNOTICE;
  16. <number>0397</number>
  17. <status>Experimental</status>
  18. <type>Standards Track</type>
  19. <sig>Standards</sig>
  20. <approver>Council</approver>
  21. <dependencies>
  22. <spec>XMPP Core</spec>
  23. <spec>XEP-0198</spec>
  24. <spec>XEP-0388</spec>
  25. </dependencies>
  26. <supersedes/>
  27. <supersededby/>
  28. <shortname>isr</shortname>
  29. <author>
  30. <firstname>Florian</firstname>
  31. <surname>Schmaus</surname>
  32. <email>flo@geekplace.eu</email>
  33. <jid>flo@geekplace.eu</jid>
  34. </author>
  35. <revision>
  36. <version>0.1.0</version>
  37. <date>2018-01-22</date>
  38. <initials>XEP Editor (jwi)</initials>
  39. <remark><p>Accepted by council vote from 2017-12-13.</p></remark>
  40. </revision>
  41. <revision>
  42. <version>0.0.5</version>
  43. <date>2017-11-30</date>
  44. <initials>fs</initials>
  45. <remark><p>Minor changes</p></remark>
  46. </revision>
  47. <revision>
  48. <version>0.0.4</version>
  49. <date>2017-10-15</date>
  50. <initials>fs</initials>
  51. <remark>
  52. <ul>
  53. <li>Bump SASL2 namespace to urn:xmpp:sasl:1, and as result:</li>
  54. <li>Rename 'key' to 'token'</li>
  55. </ul>
  56. </remark>
  57. </revision>
  58. <revision>
  59. <version>0.0.3</version>
  60. <date>2017-03-17</date>
  61. <initials>fs</initials>
  62. <remark><p>Based ISR on SASL2.</p></remark>
  63. </revision>
  64. <revision>
  65. <version>0.0.2</version>
  66. <date>2016-03-11</date>
  67. <initials>fs</initials>
  68. <remark><p>Second draft.</p></remark>
  69. </revision>
  70. <revision>
  71. <version>0.0.1</version>
  72. <date>2016-02-12</date>
  73. <initials>fs</initials>
  74. <remark><p>First draft.</p></remark>
  75. </revision>
  76. </header>
  77. <section1 topic='Introduction' anchor='intro'>
  78. <p>This XEP specifies an instant stream resumption mechanism based
  79. on &xep0198;, allowing XMPP entities to instantaneously resume an
  80. XMPP stream. This can be seen as the complementary part to &xep0305;
  81. allowing for fast XMPP session (re-)establishment.</p>
  82. <p>Compared to the existing stream resumption mechanism of <link
  83. url='http://xmpp.org/extensions/xep-0198.html#resumption'><cite>XEP-0198</cite>
  84. § 5</link>, the approach defined herein reduces the round trips
  85. required to resume a stream to exactly <em>one</em>. This is
  86. achieved by using just a secure short-lived token to resume the
  87. stream.</p>
  88. </section1>
  89. <section1 topic='Glossary' anchor='glossary'>
  90. <dl>
  91. <di>
  92. <dt>ISR</dt>
  93. <dd>Instant Stream Resumption.</dd>
  94. </di>
  95. <di>
  96. <dt>Instant Stream Resumption Token (ISR Token)</dt>
  97. <dd>A shared secret that is exclusively ephemeral and represented as string.</dd>
  98. </di>
  99. <di>
  100. <dt>TLS</dt>
  101. <dd>Transport Layer Security (&rfc5246;).</dd>
  102. </di>
  103. </dl>
  104. </section1>
  105. <!--
  106. <section1 topic='Use Cases' anchor='usecases'>
  107. <p>STRONGLY RECOMMENDED.</p>
  108. </section1>
  109. -->
  110. <section1 topic='Stream Feature'>
  111. <p>XMPP entities providing Instant Stream Resumption MUST announce
  112. that functionality as stream feature, but only if an instant stream
  113. resumption is possible at this stage. The ISR stream future consists
  114. of an &lt;isr/&gt; element qualified by the 'htpps://xmpp.org/extensions/isr/0'
  115. namespace. And since ISR requires TLS, this means that the
  116. &lt;isr/&gt; stream feature only appears on TLS secured
  117. connections.</p>
  118. <p>The ISR stream feature element MUST contain a &lt;mechanisms/&gt;
  119. element as defined in &rfc6120;. This element contains the SASL
  120. mechanism which are available to be used for instant stream
  121. resumption.</p>
  122. <example caption='Server announces the Instant Stream Resumption Stream Feature'><![CDATA[
  123. <stream:stream
  124. from='example.com'
  125. xmlns='jabber:client'
  126. xmlns:stream='http://etherx.jabber.org/stream'
  127. version='1.0'>
  128. <stream:features>
  129. <bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'/>
  130. <sm xmlns='urn:xmpp:sm:3'/>
  131. <isr xmlns='https://xmpp.org/extensions/isr/0'>
  132. <mechanisms xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
  133. <mechanism>HT-SHA-256-ENDP</mechanism>
  134. </mechaisms>
  135. </isr>
  136. </stream:features>
  137. ]]></example>
  138. <p>Every ISR enabled entity SHOULD support the HT-SHA-256-ENDP
  139. mechanism, support for HT-SHA-256-UNIQ is RECOMMENDED. The family
  140. of <cite>HT SASL</cite> mechanisms is specified in &sasl-ht;.</p>
  141. </section1>
  142. <section1 topic='Obtaining a Instant Stream Resumption Token' anchor='obtain'>
  143. <p>In order to obtain an ISR token, the requesting entity must add an
  144. 'isr-enable' element qualified by the 'htpps://xmpp.org/extensions/isr/0' namespace to the
  145. &lt;enable/&gt; element as defined in &xep0198; when attempting to
  146. enable Stream Management. This &lt;isr-enable/&gt; element MUST contain a
  147. 'mechanism' attribute containing the name of the SASL mechanism the
  148. requesting entity will use when performing ISR with the returned
  149. token. The entities involved in ISR MUST only use or allow this
  150. mechanism when performing ISR with the according token. This
  151. effectively pins the SASL mechanism <note>Pinning the SASL mechanism
  152. is believed to increase the security</note>.</p>
  153. <example caption='An &lt;enable/&gt; Nonza with the ISR &apos;mechanism&apos; element'><![CDATA[
  154. <enable xmlns='urn:xmpp:sm:3'>
  155. <isr-enable xmlns='https://xmpp.org/extensions/isr/0' mechanism='HT-SHA-256-ENDP'/>
  156. </enable>
  157. ]]></example>
  158. <p>Next, the &lt;enabled/&gt; Nonza (see &xep0360;) which is send as
  159. positive reply upon a request to enable Stream Management, MUST
  160. contain an 'isr-enabled' element qualified by the 'htpps://xmpp.org/extensions/isr/0'
  161. namespace containing a ISR token as value of its 'token' attribute. The
  162. token MUST be newly generated by a cryptographically secure random
  163. number generator and MUST contain at least 128 bit of entropy. The
  164. &lt;isr-enabled/&gt; element can optionally also contain a
  165. 'location' attribute
  166. which specifies the preferred IP address or hostname, and a TCP port
  167. number of the host which should be used for instant stream
  168. resumption.</p>
  169. <example caption='An &lt;enabled/&gt; Nonza with a ISR token'><![CDATA[
  170. <enabled xmlns='urn:xmpp:sm:3'>
  171. <isr-enabled xmlns='https://xmpp.org/extensions/isr/0' token='a0b9162d-0981-4c7d-9174-1f55aedd1f52'/>
  172. </enabled>]]></example>
  173. <example caption='An &lt;enabled/&gt; Nonza with a ISR token and location'><![CDATA[
  174. <enabled xmlns='urn:xmpp:sm:3'>
  175. <isr-enabled xmlns='https://xmpp.org/extensions/isr/0'
  176. token='a0b9162d-0981-4c7d-9174-1f55aedd1f52'
  177. location='isr.example.org:5222'/>
  178. </enabled>]]></example>
  179. <p>The &lt;enabled/&gt; Nonza containing an ISR token MUST only be
  180. sent over TLS secured connections.</p>
  181. </section1>
  182. <section1 topic='Instant Stream Resumption' anchor='isr'>
  183. <p>In order to instantaneously resume an XMPP stream the initiating
  184. entity, which is either an XMPP client or server, must posses a
  185. valid ISR token. After it has obtained the ISR token, using the process
  186. described in the previous section, it first determines the host for
  187. resumption, and after that, tries to perform the instant stream
  188. resumption.</p>
  189. <section2 topic='Determing the Host for Resumption' anchor='host'>
  190. <p>The lookup mechanism order to determine host candidates for ISR
  191. resumption is as follows:</p>
  192. <ol>
  193. <li>The host provided in the optional 'location' attribute
  194. qualified by the 'htpps://xmpp.org/extensions/isr/0' namespace found in the
  195. &lt;enabled/&gt; element of <cite>XEP-0198</cite> (the
  196. "isr:location").
  197. </li>
  198. <li>The hosts determined by means of &xep0368;.</li>
  199. <li>The host announced in the 'location' attribute of the
  200. &lt;enabled/&gt; Nonza defined in <cite>XEP-0198</cite>.</li>
  201. <li>Standard host lookup mechanisms.</li>
  202. </ol>
  203. <p>The host candidates retrieved by those mechanisms SHOULD be
  204. tried by the initiating entity in this order.</p>
  205. <p>Note that the hosts announced by the 'location' attribute
  206. qualified by the 'htpps://xmpp.org/extensions/isr/0' namespace MUST be connected to
  207. using TLS from the beginning, i.e. &lt;starttls/&gt; MUST NOT be
  208. used, instead the TLS handshake is performed right after
  209. establishing the connection.</p>
  210. <p>This order prefers hosts which allow connections where TLS is
  211. enabled from the beginning. This is desirable to reduce the
  212. required round trips by skipping the &lt;starttls/&gt; step.</p>
  213. </section2>
  214. <section2 topic='Performing Instant Stream Resumption' anchor='resume'>
  215. <p>After the remote host on which the instant stream resumption
  216. should be performed was determined, the initiating entity connects
  217. to the host, and establishes TLS by either</p>
  218. <ol>
  219. <li>establishing a TLS session right away, or</li>
  220. <li>performing STARTTLS (&rfc6120; § 5).</li>
  221. </ol>
  222. <p>Now the initiating entity sends an XMPP &lt;stream&gt; open
  223. element followed by a &lt;authenticate/&gt; Nonza as specified in
  224. the &xep0388;. The initiating entity must also provide a
  225. &lt;inst-resume/&gt; element qualified by the 'htpps://xmpp.org/extensions/isr/0'
  226. namespace, which must contain a &lt;resume/&gt; element as defined
  227. in &xep0198;.</p>
  228. <p>If the with-isr-token' attribute is set to 'false', then the
  229. SASL mechanism is performed as when traditionally authenticating
  230. the XMPP session. If the value of the attribute is 'true', which is
  231. the default value for this attribute, then the "password" given to
  232. the SASL mechanism is the ISR token. Note that this implies that only
  233. SASL mechanisms which take a password/token can be used this
  234. way.</p>
  235. <example caption='Initiating entity requests instant stream resumption via the Extensible SASL Profile (XEP-0388)'><![CDATA[
  236. <?xml version='1.0'?>
  237. <stream:stream
  238. from='juliet@im.example.com'
  239. to='im.example.com'
  240. version='1.0'
  241. xml:lang='en'
  242. xmlns='jabber:client'
  243. xmlns:stream='http://etherx.jabber.org/streams'>
  244. <authenticate xmlns='urn:xmpp:sasl:1' mechanism='HT-SHA-256-ENDP'>
  245. <initial-response>[base64 encoded SASL data]</initial-response>
  246. <inst-resume xmlns='https://xmpp.org/extensions/isr/0' with-isr-token='true'/>
  247. <resume xmlns='urn:xmpp:sm:3'
  248. h='some-sequence-number'
  249. previd='some-long-sm-id'/>
  250. </inst-resume>
  251. </authenticate>
  252. ]]></example>
  253. <p>Note that the initiating entity SHOULD pipeline the instant
  254. stream resumption request together with then initial
  255. &lt;stream&gt; open element. The initiating entity is able to do
  256. so since it already knows that the service supports ISR because it
  257. announced an ISR token.</p>
  258. <p>Servers MUST destroy the ISR token of a stream after an instant
  259. stream resumption was attempted for that stream with an invalid ISR
  260. token. Server implementations MUST implement the ISR token comparision in
  261. linear runtime.</p>
  262. <section3 topic='Successful Stream Resumption' anchor='isr-success'>
  263. <example caption='Successful Instant Stream Resumption'><![CDATA[
  264. <success xmlns='urn:xmpp:sasl:1'>z
  265. <additional-data></additional-data>
  266. <inst-resumed xmlns='https://xmpp.org/extensions/isr/0'
  267. token='006b1a29-c549-41c7-a12c-2a931822f8c0'>
  268. <resumed xmlns='urn:xmpp:sm:3' h='354' previd='123'/>
  269. </inst-resumed>
  270. </success>
  271. ]]></example>
  272. <p>On success the server replies with a &lt;success/&gt; nonza as
  273. specified in the &xep0388;, which must include a
  274. &lt;inst-resumed/&gt; element qualified by the 'htpps://xmpp.org/extensions/isr/0'
  275. namespace. This element MUST contain a <em>new</em> ISR Token found in
  276. the 'token' attribute. It also MUST include a &lt;resumed/&gt; as
  277. specified in &xep0198; containing the sequence number of the last by
  278. Stream Management handled stanza in the 'h' attribute and the
  279. 'previd' attribute.</p>
  280. <p>In case of an successful Instant Stream Resumption authenticated
  281. by an ISR token, the server MUST immediately destroy the ISR token after
  282. authentication, i.e., it MUST no longer be possible to perform an
  283. ISR using that ISR token and Stream Management ID (SM-ID, see
  284. &xep0198;) tuple.</p>
  285. <p>After the &lt;inst-resumed/&gt; was received and has been
  286. verified both entities MUST consider the resumed stream to be
  287. re-established. This includes all previously negotiated stream
  288. features like &xep0138;. It does however not include the specific
  289. state of the features: For example in case of Stream Compression,
  290. the dictionary used by the compression mechanism of the resumed
  291. stream MUST NOT be considered to be restored after instant stream
  292. resumption.</p>
  293. <p class='box'>Note that this behavior is different from &xep0198;
  294. stream resumption, where "outer stream" features like compression
  295. are not restored. Since such a behavior would be counterproductive
  296. towards the goal of this XEP, it specifies that the negotiation
  297. state of such "outer stream" features is also restored (besides the
  298. features which where already negotiated at ISR-time, i.e. TLS).</p>
  299. </section3>
  300. <section3 topic='Successful Authentication but failed Stream Resumption' anchor='isr-auth-success-resumption-failed'>
  301. <p>If the server was able to authenticate the initiating entity
  302. but is unable to resume the stream instantly it MUST reply with a
  303. &lt;success/&gt; Nonza as defined in the &xep0388; containing
  304. a &lt;inst-resume-failed/&gt; element qualified by the
  305. 'htpps://xmpp.org/extensions/isr/0' namespace. This
  306. &lt;inst-resume-failed/&gt; MUST contain a &lt;failed/&gt;
  307. element as defined in &xep0198;.</p>
  308. <example caption='Server indicates instant stream resumption failure'><![CDATA[
  309. <success xmlns='urn:xmpp:sasl:1'>
  310. <inst-resume-failed xmlns='https://xmpp.org/extensions/isr/0'>
  311. <failed xmlns='urn:xmpp:sm:3'
  312. h='another-sequence-number'>
  313. <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  314. </failed>
  315. </inst-resume-failed>
  316. </sucess>
  317. ]]></example>
  318. <p>Instant stream resumption errors SHOULD be considered
  319. recoverable, the initiating entity MAY continue with normal
  320. session establishment; however, misuse of stream management MAY
  321. result in termination of the stream. Since the initiating entity is
  322. authenticated, it could continue with resource binding by using
  323. &rfc6120; § 7. or &xep0386;.</p>
  324. </section3>
  325. <section3 topic='Multi step authentication ISR' anchor='multi-step-auth-isr'>
  326. <p>As specified in the &xep0388; § 2.6.3, sole SASL authentication
  327. may not be sufficient for authentication. In this case, the remote
  328. entity sends a &lt;continue/&gt; element as defined in &xep0388;
  329. to request the local entity to perform another
  330. task.</p>
  331. <example caption='Server requires Multi SASL Mechanism ISR'><![CDATA[
  332. <continue xmlns='urn:xmpp:sasl:1'>
  333. <additional-data>
  334. T3B0aW9uYWwgQmFzZSA2NCBlbmNvZGVkIFNBU0wgc3VjY2VzcyBkYXRh
  335. </additional-data>
  336. <tasks>
  337. <task>HOTP-EXAMPLE</task>
  338. <task>TOTP-EXAMPLE</task>
  339. <tasks>
  340. </continue>
  341. ]]></example>
  342. </section3>
  343. <section3 topic='Failed ISR Authentication' anchor='isr-auth-failed'>
  344. <p>If the server is unable to authenticate the initiating entity
  345. it replies with a &lt;failure/&gt; Nonza as defined in
  346. &xep0388;. The server MUST delete any state of the stream which
  347. was attempted to resume in case the SM-ID was correct but the
  348. authentication failed.<note>This is to prevent brute force
  349. attacks.</note></p>
  350. <example caption='Server indicates instant stream resumption failure'><![CDATA[
  351. <failure xmlns='urn:xmpp:sasl:1'>
  352. <not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/>
  353. </failure>
  354. ]]></example>
  355. <p>After the ISR authentication has failed, the initiating entity
  356. could continue with normal authentication (&xep0388;,
  357. …).</p>
  358. </section3>
  359. </section2>
  360. </section1>
  361. <section1 topic='Security Considerations' anchor='security'>
  362. <p>Any ISR data SHALL NOT be part of <cite>TLS 1.3</cite> 0-RTT
  363. early data. (TODO: Shall we weaken this requirement to allow early
  364. data?. It would be technically possible if the sender does not add
  365. additional data, for example Stanzas, after the ISR/XEP-0388 data at
  366. the end of the early data. And if the receiver does ensure that the
  367. existence of such additional data is causing an ISR failure.)</p>
  368. <p>It is of vital importance that the Instant Stream Resumption
  369. Token is generated by a cryptographically secure random
  370. generator. See &rfc4086; for more information about Randomness
  371. Requirements for Security.</p>
  372. </section1>
  373. <section1 topic='IANA Considerations' anchor='iana'>
  374. <p>This document requires no interaction with &IANA;.</p>
  375. </section1>
  376. <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  377. <p>The &REGISTRAR; includes 'htpps://xmpp.org/extensions/isr/0' in its registry of protocol namespaces (see &NAMESPACES;).</p>
  378. </section1>
  379. <section1 topic='XML Schema' anchor='schema'>
  380. <p>TODO: Add after the XEP leaves the 'experimental' state.</p>
  381. </section1>
  382. <section1 topic='Acknowledgements' anchor='acknowledgements'>
  383. <p>Thanks to Jonas Wielicki, Thijs Alkemade, Dave Cridland, Maxime
  384. Buquet, Alexander Würstlein and Sam Whited for their feedback.</p>
  385. </section1>
  386. </xep>
  387. <!-- Local Variables: -->
  388. <!-- fill-column: 100 -->
  389. <!-- indent-tabs-mode: nil -->
  390. <!-- End: -->