moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-24 10:12:19 -05:00
Code Issues Releases Wiki Activity

SASL2 Updates

Browse Source 
Updated according to implementation experience:
* Updated namespace
* Continue "mechanisms" are not; changed these to "tasks".
* Added stream features after Success.
* Don't need complexity of "=" encoding; removed.
* Fixed internal links.
* Updated examples.
This commit is contained in:
Dave Cridland 2017-08-15 09:13:20 +01:00
parent 7b4d1252b2
commit 0dc187d16c
1 changed files with 59 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
xep-0388.xml
View File

@ -20,6 +20,22 @@
<supersededby/>
<shortname>sasl2</shortname>
&dcridland;
<revision>
<version>0.2.0</version>
<date>2017-08-14</date>
<initials>dwd</initials>
<remark>
<p>Updated according to implementation experience:</p>
<ul>
<li>Updated namespace</li>
<li>Continue "mechanisms" are not; changed these to "tasks".</li>
<li>Added stream features after Success.</li>
<li>Don't need complexity of "=" encoding; removed.</li>
<li>Fixed internal links.</li>
<li>Updated examples.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.1.0</version>
<date>2017-03-16</date>
@ -60,28 +76,28 @@
<section1 topic='Overview' anchor="overview">
<section2 topic="Discovering Support" anchor="feature">
<p>Servers capable of SASL2 offer a stream feature of &lt;mechanisms/>, qualified by the "urn:xmpp:sasl:0" namespace. This in turn contains one or more &lt;mechanism/> elements in the same namespace, and potentially other elements (for example, the &lt;hostname/> element defined within XEP-0233).</p>
<p>Servers capable of SASL2 offer a stream feature of &lt;mechanisms/>, qualified by the "urn:xmpp:sasl:1" namespace. This in turn contains one or more &lt;mechanism/> elements in the same namespace, and potentially other elements (for example, the &lt;hostname/> element defined within XEP-0233).</p>
<p>Note that SASL2 is impossible for clients to initiate without at least one mechanism being available, and therefore MUST NOT be offered.</p>
<p>The feature so advertised, and its child content, SHOULD be stable for the given stream to and from attributes and encryption state, and therefore MAY be cached by clients for later connections.</p>
<p>The Service Name used by XMPP is unchanged from RFC 6120.</p>
</section2>
<section2 topic="SASL Data Encoding">
<p>In all cases, both Clients and Servers encode SASL exchanges using Base 64 encoding. This SHOULD NOT include any line wrapping or other whitespace. As the form &lt;element/> is equivalent to &lt;element>&lt;/element>, these both indicate an empty string, which is used to indicate no data (ie, the absence of the data). In order to explicitly transmit a zero-length SASL challenge or response, the sending party sends a single equals sign character ("=").</p>
<p>In all cases, both Clients and Servers encode SASL exchanges using Base 64 encoding. This SHOULD NOT include any line wrapping or other whitespace. As the form &lt;element/> is equivalent to &lt;element>&lt;/element>, these both indicate an empty string. Challenges and responses with no data do not occur in SASL, and so require no special handling. To indicate the absence of an initial response, or the absence of success data, the element is simply not included.</p>
</section2>
<section2 topic="Initiation">
<p>Clients, upon observing this stream feature, initiate the authentication by the use of the &lt;authenticate/> top-level element, within the same namespace. The nature of this element is to inform the server about properties of the final stream state, as well as initiate authentication itself. To achieve the latter, it has a single mandatory attribute of "mechanism", with a string value of a mechanism name offered by the Server in the stream feature, and an optional child element of &lt;initial-response/>, containing a base64-encoded SASL Initial Response.</p>
<p>On subsequent connections, if a Client has previously cache the stream feature, the Client MAY choose to send it before seeing the stream features - sending it "pipelined" with the Stream Open tag for example.</p>
<example caption="An authentication request"><![CDATA[
<authenticate xmlns='urn:xmpp:sasl:0' mechanism="BLURDLYBLOOP">
<initial-response>SW1wcm92ZWQgZW5jYXNwdWxhdGlvbiBvZiBvcHRpb25hbCBTQVNMLUlSIGRhdGE=</initial-response>
<authenticate xmlns='urn:xmpp:sasl:1' mechanism="BLURDLYBLOOP">
<initial-response>Tm9ib2R5IGV2ZXIgZGVjb2RlcyB0aGUgZXhhbXBsZXMu</initial-response>
</authenticate>
]]>
</example>
<p>In order to provide support for other desired stream states beyond authentication, additional child elements are used. For example, a hypothetical XEP-0198 session resumption element might be included, and/or Resource Binding requests.</p>
<example caption="An authentication request with a (hypothetical) bind request"><![CDATA[
<authenticate xmlns='urn:xmpp:sasl:0' mechanism='BLURDYBLOOP'>
<authenticate xmlns='urn:xmpp:sasl:1' mechanism='BLURDYBLOOP'>
<initial-response>
U0FTTC1JUiBlbmNvZGVkIGFsb25nc2lkZSBiaW5kIHJlcXVlc3Q=
SSBzaG91bGQgbWFrZSB0aGlzIGEgY29tcGV0aXRpb24=
</initial-response>
<bind xmlns='urn:xmpp:bind:example'/>
</authenticate>
@ -92,13 +108,13 @@
<p>Server Challenges MAY then be sent. Each Challenge MUST be responded to by a Client in a Client Response. These are not extensible, and contain the corresponding base64 encoded SASL data:</p>
<example caption="A challenge and response exchange"><![CDATA[
<!-- A server might send: -->
<challenge xmlns='urn:xmpp:sasl:0'>
QmFzZSA2NCBlbmNvZGVkIFNBU0wgY2hhbGxlbmdlIGRhdGE=
<challenge xmlns='urn:xmpp:sasl:1'>
U28sIG5leHQgRk9TREVNIC0gMjAxOCwgdGhhdCBpcy4uLg==
</challenge>
<!-- A client might respond: -->
<response xmlns='urn:xmpp:sasl:0'>
QmFzZSA2NCBlbmNvZGVkIFNBU0wgcmVzcG9uc2UgZGF0YQ==
<response xmlns='urn:xmpp:sasl:1'>
Li4uSSdsbCBidXkgYSBiZWVyIGZvciB0aGUgZmlyc3QgcGVyc29uIHdoby4uLg==
</response>
]]>
</example>
@ -112,29 +128,30 @@
<section3 topic="Success">
<p>If the Client is now authenticated, the Server sends a &lt;success/> element, which contains an OPTIONAL &lt;additional-data/> element containing SASL additional data. It also contains a &lt;authorization-identity/> element containing the negotiated identity - this is a bare JID, unless resource binding has occurred, in which case it is a full JID.</p>
<example caption="Successful authentication"><![CDATA[
<success xmlns='urn:xmpp:sasl:0'>
<success xmlns='urn:xmpp:sasl:1'>
<success-data>
T3B0aW9uYWwgQmFzZSA2NCBlbmNvZGVkIFNBU0wgc3VjY2VzcyBkYXRh
ip/AeIOfZXKBV+fW2smE0GUB3I//nnrrLCYkt0Vj
</success-data>
<authorization-identifier>juliet@montague.example/Balcony/a987dsh9a87sdh</authorization-identifier>
</success>
]]></example>
<p>Other extension elements MAY also be contained by the &lt;success/> element.</p>
<example caption="Successful re-authentication and resumption"><![CDATA[
<success xmlns='urn:xmpp:sasl:0'>
<success xmlns='urn:xmpp:sasl:1'>
<additional-data>
T3B0aW9uYWwgQmFzZSA2NCBlbmNvZGVkIFNBU0wgc3VjY2VzcyBkYXRh
SGFkIHlvdSBnb2luZywgdGhlcmUsIGRpZG4ndCBJPw==
</additional-data>
<authorization-identifier>juliet@montague.example/Balcony/a987dsh9a87sdh</authorization-identifier>
<sm:resumed xmlns='urn:xmpp:sm:3:example' h='345' previd='124'/>
</success>
]]></example>
<p>Any security layer negotiated SHALL take effect after the ">" octet of the closing tag (ie, immediately after "&lt;/success>").</p>
<p>Any security layer negotiated SHALL take effect after the ">" octet of the closing tag (ie, immediately after "&lt;/success>"), if it has not already taken effect at a &lt;continue> - see <link url='#continue'>Continue</link> below.</p>
<p>The &lt;success> element is immediately followed by a &lt;features> element containing the applicable stream features of the newly authenticated stream. Note that no stream restart occurs.</p>
</section3>
<section3 topic="Failure">
<p>A &lt;failure/> element is used by the server to terminate the authentication attempt. It MAY contain application-specific error codes, and MAY contain a textual error. It MUST contain one of the SASL error codes from RFC 6120 Section 6.5.</p>
<example caption="Failure"><![CDATA[
<failure xmlns='urn:xmpp:sasl:0'>
<failure xmlns='urn:xmpp:sasl:1'>
<aborted xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/>
<optional-application-specific xmlns='urn:something:else'/>
<text>This is a terrible example.</text>
@ -143,25 +160,28 @@
</section3>
<section3 topic="Continue" anchor="continue">
<p>A &lt;continue/> element is used to indicate that while the SASL exchange was successful, it is insufficient to allow authentication at this time.</p>
<p>This can be used to indicate that the Client needs to perform a Second Factor Authentication ("2FA"), or is required to change password. These are conducted as additional SASL mechanisms. Such SASL mechanisms MUST NOT change the authorization identifier, or introduce any security layer. The authorization identifer transmitted during the subsequent &lt;success/>, and any security layer which comes into effect after the eventual &lt;success/>, therefore MUST be that of the first mechanism.</p>
<p>The element contains a &lt;mechanisms/> element, as defined above as a stream feature, containing suitable mechanisms. It MAY contain an &lt;additional-data/> element, as the &lt;success/> element does.</p>
<p>This can be used to indicate that the Client needs to perform a Second Factor Authentication ("2FA"), or is required to change password.</p>
<p>Such tasks are presented within a &lt;tasks> element, which contains a sequence of &lt;task> elements, each containing a name. These tasks are analogous to a SASL mechanism, but have a number of differences - they may never attempt to negotiate a new authorization identifier, nor a new security layer.</p>
<p>A client MAY choose any one of the offered tasks; if multiple are required a sequence of &lt;continue> exchanges will occur until all mandatory tasks are complete.</p>
<p>The &lt;continue element therefore always contains a &lt;tasks/> element, as defined above. It MAY contain an &lt;additional-data/> element, as the &lt;success/> element does.</p>
<p>Finally, it MAY contain a &lt;text/> element, which can contain human-readable data explaining the nature of the step required.</p>
<example caption="Continue Required"><![CDATA[
<continue xmlns='urn:xmpp:sasl:0'>
<continue xmlns='urn:xmpp:sasl:1'>
<additional-data>
T3B0aW9uYWwgQmFzZSA2NCBlbmNvZGVkIFNBU0wgc3VjY2VzcyBkYXRh
SSdtIGJvcmVkIG5vdy4=
</additional-data>
<mechanisms>
<mechanism>HOTP-EXAMPLE</mechanism>
<mechanism>TOTP-EXAMPLE</mechanism>
<mechanisms>
<tasks>
<task>HOTP-EXAMPLE</task>
<task>TOTP-EXAMPLE</task>
<tasks>
<text>This account requires 2FA</text>
</continue>
]]></example>
<p>Clients respond with a &lt;next-authenticate/> element, which has a single mandatory attribute of "mechanism", containing the selected mechanism name, and contains an OPTIONAL base64 encoded initial response.</p>
<p>After the final octet of the first &lt;continue> element, any SASL security layer negotiated in the preceding exchange SHALL be immediately in effect.</p>
<p>Clients respond with a &lt;next/> element, which has a single mandatory attribute of "task", containing the selected task name, and contains an OPTIONAL base64 encoded initial response.</p>
<example caption="Client Continues"><![CDATA[
<next-authenticate xmlns='urn:xmpp:sasl' mechanism='TOTP-EXAMPLE'>
MkZBIG9yIHBhc3N3b3JkIGNoYW5nZSBvciBzb21ldGhpbmc=
<next xmlns='urn:xmpp:sasl:1' task='TOTP-EXAMPLE'>
SSd2ZSBydW4gb3V0IG9mIGlkZWFzIGhlcmUu
</next-authenticate>
]]></example>
</section3>
@ -169,46 +189,48 @@
</section1>
<section1 topic="SASL Profile Definition">
<p>This provides pointers and/or clarifications to the <link url="#overview"/> in the order and manner defined in RFC 4422, section 4.</p>
<p>This provides pointers and/or clarifications to the <link url="#overview">Overview</link> in the order and manner defined in RFC 4422, section 4.</p>
<section2 topic="Service Name">
<p>The service name SHALL be "xmpp", as defined by RFC 6120.</p>
</section2>
<section2 topic="Mechanism negotiation">
<p>Servers list mechanisms during stream features (See <link url="#features"/>) and within the &lt;continue/> element (See <link url="#continue"/>).</p>
<p>TODO: Neither this specification nor RFC 6120 allow clients access to the mechanism list after SASL negotiation...?</p>
<p>Servers list mechanisms during stream features (See <link url="#features">Discovering Support</link>).</p>
</section2>
<section2 topic="Message Definitions">
<section3 topic="Initiation">
<p>Clients initiate using the &lt;authenticate/> top level element (See <link url="#auth"/>, and after any &lt;continue/> with the &lt;next-authenticate/> message (See <link url="#continue"/>).</p>
<p>Clients initiate using the &lt;authenticate/> top level element (See <link url="#auth">Initiation</link>.</p>
</section3>
<section3 topic="Server Challenges and Client Responses">
<p>See <link url="#challenge"/>.</p>
<p>See <link url="#challenge">Challenges and Responses</link>.</p>
</section3>
<section3 topic="Outcome">
<p>See <link url="#outcome"/>.</p>
<p>See <link url="#outcome">Completing Authentication</link>.</p>
</section3>
</section2>
<section2 topic="Non-Empty Authorization Strings">
<p>If a Client specifies an authorization string which is non-empty, the identifier is normalized by treating it as a JID, and performing normalization as described in RFC 7622.</p>
<p>In general, implementors are advised that a non-empty authorization string MAY be considered an error if the stream's from attribute (if present) does not match.</p>
</section2>
<section2 topic="Aborting">
<p>Clients MAY abort unilaterally by sending &lt;abort/> as specified in <link url="#abort"/>.</p>
<p>Servers MAY abort unliterally by sending &lt;failure/> with the &lt;aborted/> error code as defined in <link url="#failure"/>.</p>
<p>Clients MAY abort unilaterally by sending &lt;abort/> as specified in <link url="#abort">Client Aborts</link>.</p>
<p>Servers MAY abort unliterally by sending &lt;failure/> with the &lt;aborted/> error code as defined in <link url="#failure">Failure</link>.</p>
</section2>
<section2 topic="Security Layer Effect">
<p>See <link url="#success"/>.</p>
<p>Security Layers take effect after the SASL mechanism itself (ie, the first negotiation) has completed successfully, after the final octet of the server's &lt;success> or &lt;continue>. See <link url="#success">Success</link> and <link url="#continue">Continue</link>.</p>
</section2>
<section2 topic="Security Layer Order">
<p>Option (a) is used - any SASL Security Layer is applied first to data being sent, and TLS applied last.</p>
</section2>
<section2 topic="Multiple Authentication">
<p>Although the &lt;continue/> concept does use multiple SASL sequences, only the first SASL mechanism used is considered an authentication, and only the first can negotiate a security layer.</p>
<p>Although the &lt;continue/> concept does use tasks analogous to multiple SASL sequences, only the first SASL mechanism used is considered an authentication, and only the first can negotiate a security layer.</p>
<p>In particular, once &lt;success/> has been sent by the server, any further &lt;authenticate/> element MUST result in a stream error.</p>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>Relative to the SASL profile documented in RFC 6120, this introduces more data unprotected by any security layer negotiated by SASL itself.</p>
<p>While no actual exchanges are introduced that are unprotected, the nature of this exchange might allow for (for example) a resource binding extension to be introduced.</p>
<p>SASL security layers are sparingly used in the field, however., so this is thought to be a theoretical, rather than practical, concern.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>