Browse Source

Accept isr-sasl2 as XEP-0397

Jonas Wielicki 1 year ago
parent
commit
5a20476576
1 changed files with 473 additions and 0 deletions
  1. 473
    0
      xep-0397.xml

+ 473
- 0
xep-0397.xml View File

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

Loading…
Cancel
Save