From 067e3ca4d7df81a7b986dc43a3d5501c607b6a49 Mon Sep 17 00:00:00 2001 From: Sam Whited Date: Tue, 15 Mar 2016 11:24:29 -0500 Subject: [PATCH] Bump ISR draft to revision 0.0.2 --- inbox/isr.xml | 373 +++++++++++++++++++++++++++++--------------------- 1 file changed, 219 insertions(+), 154 deletions(-) diff --git a/inbox/isr.xml b/inbox/isr.xml index 5d6a8d3f..53884d73 100644 --- a/inbox/isr.xml +++ b/inbox/isr.xml @@ -8,7 +8,7 @@
Instant Stream Resumption - This specification introduces an mechanism for instant + This specification introduces a mechanism for instant stream resumption, based on Stream Management (XEP-0198), allowing XMPP entities to instantaneously resume an XMPP stream. @@ -16,55 +16,55 @@ This XMPP Extension Protocol is copyright (c) 1999 - 2016 by the XMPP Standards Foundation (XSF). - Permission is hereby granted, free of charge, to any - person obtaining a copy of this specification (the - "Specification"), 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. + Permission is hereby granted, free of charge, to any + person obtaining a copy of this specification (the + "Specification"), 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. - ## NOTE WELL: This Specification is provided on an - "AS IS" 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. ## + ## NOTE WELL: This Specification is provided on an + "AS IS" 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. ## - 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. + 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. - 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 <http://xmpp.org/extensions/ipr-policy.shtml> - or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 - USA). + 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 <http://xmpp.org/extensions/ipr-policy.shtml> + or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 + USA). xxxx @@ -75,6 +75,7 @@ XMPP Core XEP-0198 + XEP-0300 @@ -85,6 +86,12 @@ flo@geekplace.eu flo@geekplace.eu + + 0.0.2 + 2016-03-11 + fs +

Second draft.

 + 0.0.1 2016-02-12 @@ -101,26 +108,31 @@ allowing for fast XMPP session (re-)establishment.

Compared to the existing stream resumption mechanism of XEP-0198 § - 5, the approach defined herein reduces the round trips + url='http://xmpp.org/extensions/xep-0198.html#resumption'>XEP-0198 + § 5, the approach defined herein reduces the round trips required to resume a stream to exactly one (besides the round trips required by the TLS handshake). This is achieved by - using only a secure token to resume the stream.

- + using just a secure key to resume the stream.

+
- -
ISR
-
Instant Stream Resumption.
- - -
Instant Stream Resumption Token (ISR Token)
-
A string token with at least 128 bits of entropy generated - by a cryptographically secure random number generator.
- + +
ISR
+
Instant Stream Resumption.
+ + +
Instant Stream Resumption Key (ISR Key)
+
A key, represented as string, which contains at least 128 + bits of entropy generated by a cryptographically secure random + number generator.
+ + +
TLS
+
Transport Layer Security (&rfc5246;).
+
@@ -131,99 +143,124 @@ --> - +

If an entity supports ISR, then the <enabled/> NonzaXEP-0360: Nonzas (are not Stanzas) <https://xmpp.org/extensions/xep-0360.html>., 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.

- ]]> + isr:key='a0b9162d-0981-4c7d-9174-1f55aedd1f52'/>]]> - ]]> -

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.

+

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.

-

The lookup mechanism order to determine host candidates for ISR - resumption is as follows:

+

The lookup mechanism order to determine host candidates for ISR + resumption is as follows:

-
    -
  1. The host specified in the optional 'location' attribute - qualified by the 'urn:xmpp:isr:0' namespace found in the - <enabled/> element of XEP-0198. -
    2. -
  2. The hosts determined by means of &xep0368;.
    3. -
  3. The host announced in the 'location' attribute of the <enabled/> Nonza defined in XEP-0198.
    4. -
  4. Standard host lookup mechanisms.
    5. -
+
    +
  1. The host provided in the optional 'location' attribute + qualified by the 'urn:xmpp:isr:0' namespace found in the + <enabled/> element of XEP-0198 (the + "isr:location"). +
    2. +
  2. The hosts determined by means of &xep0368;.
    3. +
  3. The host announced in the 'location' attribute of the + <enabled/> Nonza defined in XEP-0198.
    4. +
  4. Standard host lookup mechanisms.
    5. +
-

The host candidates retrieved by those mechanisms SHOULD be - tried by the initiating entity in this order.

+

The host candidates retrieved by those mechanisms SHOULD be + tried by the initiating entity in this order.

-

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. <starttls/> MUST NOT be used, instead the - TLS Handshake is performed right after establishing the - connection.

+

Note that the hosts announced by the 'location' attribute + qualified by the 'urn:xmpp:isr:0' namespace MUST be connected to + using TLS from the beginning, i.e. <starttls/> MUST NOT be + used, instead the TLS handshake is performed right after + establishing the connection.

-

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 <starttls/> - step.

+

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 <starttls/> step.

 -

After the host on which the instant stream resumption should be - performed was determined, the entity connects to, and establishes - TLS by either

+

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

-
    -
  1. establishing a TLS session right away, or
    2. -
  2. performing STARTTLS (&rfc6120; § 5).
    3. -
+
    +
  1. establishing a TLS session right away, or
    2. +
  2. performing STARTTLS (&rfc6120; § 5).
    3. +
-

After the connection has been secured, the - initiating entity sends an XMPP <stream> open element - followed by a <instant-resume/> 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.

+

Next, the initiating entity sends an XMPP <stream> open + element followed by a <instant-resume/> Nonza qualified by + the 'urn:xmpp:isr:0' namespace which MUST contain the previous + stream identifier, the XEP-0198 "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 <hash/> element as + specified by &xep0300;, which are put as child elements under the + <hmac/> element.

-

Note that the initiating entity SHOULD pipeline the instant - stream resumption request together with then initial - <stream> open element since it already has determined that - the service supports this feature. Servers MUST announce that they - support ISR by including an <isr/> element qualified by the - 'urn:xmpp:isr:0' namespace in their stream features.

+

The initiator-hmac is defined as follows:

- + initiator-hamc = Base64(HMAC(key, "Initiator" || + tls-server-end-point)) +

+ +

The function defined in &rfc2104; is used to compute the HMAC + using the hash algorithm specified in the 'algo' attribute of the + <hash/> 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; + § + 4 and resulting string is used as text value of the + <hash/> element.

+ +

Note that the initiating entity SHOULD pipeline the instant + stream resumption request together with then initial + <stream> 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 <isr/> element qualified by the + 'urn:xmpp:isr:0' namespace in their stream features.

+ + ]]> + previd='some-long-sm-id' + h='42'> + + + initator-hmac + + +]]> -

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.

+

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.

- + -

On success the server replies with <inst-resumed/> - Nonza which MUST contain a new ISR Token found in the - 'tok' attribute and the sequence number of the last by Stream - Mangement handled stanza in the 'h' attribute.

+

On success the server replies with <inst-resumed/> + Nonza which MUST contain a new 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 <hash/> element being a + child of the <hamc/> element.

- The responder-hmac is defined as follows:

+ +

+ responder-hmac = Base64(HMAC(key, "Responder" || + tls-server-end-point)) +

+ +

That is, it is the same as the initiator-hamc, but instead of + using the ASCII string "Initiator", the ASCII string "Responder" + is used.

+ +

The initiating entity is required to verify the + responder-hmac achieve mutual authentication.

+ + ]]> + key='006b1a29-c549-41c7-a12c-2a931822f8c0' + h='21'> + + + responder-hmac + + +]]> -

After the <inst-resumed/> 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.

+

After the <inst-resumed/> 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.

- + - - -

If the server is unable to resume the stream instantly it - MUST reply with a <failed/> Nonza qualified by the - 'urn:xmpp:isr:0' namespace.

+ - If the server is unable to resume the stream instantly it + MUST reply with a <failed/> Nonza qualified by the + 'urn:xmpp:isr:0' namespace.

+ + ]]> -

The server MAY also include a 'h' attribute in the - <failed/> element indicating the number of handled - stanzas.

+

The server MAY also include a 'h' attribute in the + <failed/> element indicating the number of stanzas it has + handled so far.

- ]]> -

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.

+

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.

- + @@ -308,7 +373,7 @@ -

It is of vital importance that the Instant Stream Resumption Token +

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

@@ -336,7 +401,7 @@ -

Thanks to Jonas Wielicki for his feedback.

+

Thanks to Jonas Wielicki and Thijs Alkemade for their feedback.