XEP-xxxx: SASL SCRAM Downgrade Protection

4.1 Server Indicates Support¶

The server uses the optional attribute "d" with the value "ssdp" in its server-first-message to indicate support for this specification.

A client supporting this specification but not seeing this attribute advertised by the server MAY abort the authentication. It is RECOMMENDED to wait until the whole SCRAM flow hash been completed to distinguish the case of a server not supporting this specification from a MITM stripping out this optional SCRAM attribute.

4.2 Client Sends Downgrade Protection Hash¶

If the server indicated support for this spec in the server-first-message and the client supports it, the client calculates a hash for the server-advertised list of SASL mechanisms and channel-binding types as follows.

Note: All sorting operations MUST be performed using "i;octet" collation as specified in Section 9.3 of RFC 4790 [9].

1. Initialize an empty ASCII string S
2. Sort all server-advertised SASL mechanisms and append them to string S joined by delimiter "," (%x2C)
3. If the server used SASL Channel-Binding Type Capability (XEP-0440) [4] to advertise channel-bindings, append "|" (%x7C) to S
4. If the server used SASL Channel-Binding Type Capability (XEP-0440) [4] to advertise channel-bindings, sort all server-advertised channel-binding types and append them to string S joined by delimiter "," (%x2C)
5. Hash S using the same hash mechanism as used for the SCRAM mechanism currently in use and encode the result using base64

The client then adds the optional attribute "d" with the base64 encoded hash obtained in step 5 to its client-final-message. The client MAY send this attribute even if the server did not advertise support.

Note: If the server simultaneously advertises SASL1 and SASL2, only the mechanism list of the SASL protocol the client uses for authentication MUST be considered for hashing.

4.3 Server Verifys The Downgrade Protection Hash¶

Upon receiving the client-final-message the server calculates its own base64 encoded hash using the list of SASL mechanisms and channel-binding types it advertised using SASL1 or SASL2 and SASL Channel-Binding Type Capability (XEP-0440) [4] by applying the same algorithm as defined in Client Sends Downgrade Protection Hash.

The server then extracts the base64 encoded hash presented by the client in the optional attribute "d" and compares it to its own hash. If the hashes match, the list of SASL mechanisms and channel-binding types has not been changed by an active MITM.

If the hashes do not match, the server MUST fail the authentication as specified in RFC 6120 [1] section 6.5 or Extensible SASL Profile (XEP-0388) [2] section 2.6.2 using the "aborted" error-condition. If Extensible SASL Profile (XEP-0388) [2] is used, the application-specific error-condition "downgrade-detected" in the namespace "urn:xmpp:ssdp:0" MUST be added, too. It MAY further include an optional descriptive text to further clarify this error as specified in Extensible SASL Profile (XEP-0388) [2] section 6.2.6 or RFC 6120 [1] section 6.5. If additional SCRAM data is provided, the used SCRAM "server-error-value" MUST be "downgrade-detected".

Non-XMPP implementations MAY use a SCRAM "server-error-value" of "downgrade-detected" alongside any protocol specific error-condition.

4.4 Full Example¶

This sections contains an example based on the ones provided in Extensible SASL Profile (XEP-0388) [2].

<!--
  Client sending stream header
-->
<stream:stream
  from='user@example.org'
  to='example.org'
  version='1.0'
  xml:lang='en'
  xmlns='jabber:client'
  xmlns:stream='http://etherx.jabber.org/streams'>

<!--
  Server responding with stream header and features
-->
<stream:stream
  from='example.org'
  id='++TR84Sm6A3hnt3Q065SnAbbk3Y='
  to='user@example.org'
  version='1.0'
  xml:lang='en'
  xmlns='jabber:client'
  xmlns:stream='http://etherx.jabber.org/streams'>
<stream:features>
  <authentication xmlns='urn:xmpp:sasl:2'>
    <mechanism>SCRAM-SHA-1</mechanism>
    <mechanism>SCRAM-SHA-1-PLUS</mechanism>
    <inline xmlns='urn:xmpp:sasl:2'>
      <!-- Server indicates that XEP-0198 can be negotiated "inline" -->
      <enable xmlns='urn:xmpp:sm:3'/>
      <!-- Server indicates support for XEP-0386 Bind 2 -->
      <bind xmlns='urn:xmpp:bind2:1'/>
    </inline>
  </authentication>
  <!-- Channel-binding information provided by XEP-0440 -->
  <sasl-channel-binding xmlns='urn:xmpp:sasl-cb:0'>
    <channel-binding type='tls-server-end-point'/>
    <channel-binding type='tls-exporter'/>
  </sasl-channel-binding>
</stream:features>

<!--
  Client initiates authentication using SCRAM-SHA-1-PLUS and channel-binding type "tls-exporter"
-->
<authenticate xmlns='urn:xmpp:sasl:2' mechanism='SCRAM-SHA-1-PLUS'>
  <!-- Base64 of: 'p=tls-exporter,,n=user,r=12C4CD5C-E38E-4A98-8F6D-15C38F51CCC6' -->
  <initial-response>cD10bHMtZXhwb3J0ZXIsLG49dXNlcixyPTEyQzRDRDVDLUUzOEUtNEE5OC04RjZELTE1QzM4RjUxQ0NDNg==</initial-response>
  <user-agent id='d4565fa7-4d72-4749-b3d3-740edbf87770'>
    <software>AwesomeXMPP</software>
    <device>Kiva's Phone</device>
  </user-agent>
</authenticate>

<!--
  SCRAM-SHA-1-PLUS challenge issued by the server as defined in RFC 5802
  but including the optional attribute indicating support for this specification.
  Base64 of: 'r=12C4CD5C-E38E-4A98-8F6D-15C38F51CCC6a09117a6-ac50-4f2f-93f1-93799c2bddf6,s=QSXCR+Q6sek8bf92,i=4096,d=ssdp'
-->
<challenge xmlns='urn:xmpp:sasl:2'>
  cj0xMkM0Q0Q1Qy1FMzhFLTRBOTgtOEY2RC0xNUMzOEY1MUNDQzZhMDkxMTdhNi1hYzUwLTRmMmYtOTNmMS05Mzc5OWMyYmRkZjYscz1RU1hDUitRNnNlazhiZjkyLGk9NDA5NixkPXNzZHA=
</challenge>

<!--
  The client responds with the base64 encoded SCRAM-SHA-1-PLUS client-final-message (password: 'pencil')
  including the base64 encoded SHA-1 hash of the mechanism and channel-binding lists.
  Attribute "d" contains base64 encoded SHA-1 hash of 'SCRAM-SHA-1,SCRAM-SHA-1-PLUS|tls-exporter,tls-server-end-point'
  Base64 of: 'c=cD10bHMtZXhwb3J0ZXIsLMcoQvOdBDePd4OswlmAWV3dg1a1Wh1tYPTBwVid10VU,r=12C4CD5C-E38E-4A98-8F6D-15C38F51CCC6a09117a6-ac50-4f2f-93f1-93799c2bddf6,p=UApo7xo6Pa9J+Vaejfz/dG7BomU=,d=dRc3RenuSY9ypgPpERowoaySQZY='
  The c-attribute contains the GS2-header and channel-binding data blob (32 bytes) as defined in RFC 5802.
-->
<response xmlns='urn:xmpp:sasl:2'>
  Yz1jRDEwYkhNdFpYaHdiM0owWlhJc0xNY29Rdk9kQkRlUGQ0T3N3bG1BV1YzZGcxYTFXaDF0WVBUQndWaWQxMFZVLHI9MTJDNENENUMtRTM4RS00QTk4LThGNkQtMTVDMzhGNTFDQ0M2YTA5MTE3YTYtYWM1MC00ZjJmLTkzZjEtOTM3OTljMmJkZGY2LHA9VUFwbzd4bzZQYTlKK1ZhZWpmei9kRzdCb21VPSxkPWRSYzNSZW51U1k5eXBnUHBFUm93b2F5U1FaWT0=
</response>

<!--
  The server accepted this authentication, no tampering with the advertised SASL mechanisms or channel-bindings was detected.
-->
<success xmlns='urn:xmpp:sasl:2'>
  <!-- Base64 of: 'v=sQq8A1dePL5DxWX22Sz4TJMD7t4=' -->
  <additional-data>
    dj1zUXE4QTFkZVBMNUR4V1gyMlN6NFRKTUQ3dDQ9
  </additional-data>
  <authorization-identifier>user@example.org</authorization-identifier>
</success>

Copyright

This XMPP Extension Protocol is copyright © 1999 – 2024 by the XMPP Standards Foundation (XSF).

Permissions

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.

Disclaimer of Warranty

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

Limitation of 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 from, out of, or in connection with the Specification or the implementation, deployment, or other use of 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.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).

Visual Presentation

The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.

1. RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core <http://tools.ietf.org/html/rfc6120>.

2. XEP-0388: Extensible SASL Profile <https://xmpp.org/extensions/xep-0388.html>.

3. RFC 5802: Salted Challenge Response Authentication Mechanism (SCRAM) SASL and GSS-API Mechanisms <http://tools.ietf.org/html/rfc5802>.

4. XEP-0440: SASL Channel-Binding Type Capability <https://xmpp.org/extensions/xep-0440.html>.

5. RFC 5929: Channel Bindings for TLS <http://tools.ietf.org/html/rfc5929>.

6. RFC 5705: Keying Material Exporters for Transport Layer Security (TLS) <http://tools.ietf.org/html/rfc5705>.

7. RFC 9266: Channel Bindings for TLS 1.3 <http://tools.ietf.org/html/rfc9266>.

8. RFC 7677: SCRAM-SHA-256 and SCRAM-SHA-256-PLUS Simple Authentication and Security Layer (SASL) Mechanisms <http://tools.ietf.org/html/rfc7677>.

9. RFC 4790: Internet Application Protocol Collation Registry <http://tools.ietf.org/html/rfc4790>.

10. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

11. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <https://xmpp.org/registrar/>.