View source for SASL and SCRAM-SHA-1(-PLUS) / SCRAM-SHA-256(-PLUS)

== Introduction ==
=== SCRAM-SHA-1(-PLUS) ===
[https://tools.ietf.org/html/rfc5802 Salted Challenge Response Authentication Mechanism (SCRAM) SASL and GSS-API Mechanisms (SCRAM-SHA-1(-PLUS)] is a SASL mechanism improving on [[SASL and DIGEST-MD5|DIGEST-MD5]].

* [https://tools.ietf.org/html/rfc6331 RFC6331: Moving DIGEST-MD5 to Historic]
* CRAM-MD5 to Historic ([https://tools.ietf.org/html/draft-ietf-sasl-crammd5-to-historic-00 draft-ietf-sasl-crammd5-to-historic-00] + [https://tools.ietf.org/html/draft-zeilenga-luis140219-crammd5-to-historic-00 draft-zeilenga-luis140219-crammd5-to-historic-00])

Its main benefits are in offering both a method to salt and hash the password in storage and in transit. This page aims to give a short introduction on how to implement it in a client.

With changes from TLS 1.2 to TLS 1.3, an Internet-Draft is in progress for TLS Binding and TLS 1.3: [https://tools.ietf.org/html/draft-ietf-kitten-tls-channel-bindings-for-tls13 Channel Bindings for TLS 1.3: draft-ietf-kitten-tls-channel-bindings-for-tls13].

=== SCRAM-SHA-256(-PLUS) ===
Please note that there is now [https://tools.ietf.org/html/rfc7677 RFC7677: SCRAM-SHA-256 and SCRAM-SHA-256-PLUS Simple Authentication and Security Layer (SASL) Mechanisms] (since November 2015).

Already integrated by several XMPP softwares:
* Servers: DJabberd 0.90+, Erlang Solutions MongooseIM 3.7+, Isode M-Link, Jackal IM, Metronome IM, Prosody IM 0.12.x, Tigase XMPP Server 8.0+
* Clients: Conversations, CoyIM, eyeCU, Gajim 1.2.0+, KDE Kaidan, Miranda NG, Psi/Psi+ (with QCA), Tigase Beagle IM, Tigase Siskin IM, Tigase Stork IM, UWPX, Vacuum IM
* Libraries: cr-xmpp, libstrophe, Mellium XMPP, python-nbxmpp, QXmpp, Tigase JaXMPP, TigaseSwift, Stanza, Wocky, xmpp-rs

Others:
* aiokafka, aiosasl, Atheme, Auth_SASL/Auth_SASL2, Authen-SCRAM, cassandra-secure-plugin, ba0f3/scram.nim, Couchbase, Cyrus SASL, Dovecot, Erlang Solutions Escalus, esl/fast_scram, Exim (with gsasl), fast_scram, GNU SASL (gsasl) 1.9.1+, Haystack, Kafka, ldaptive, MailKit, Mellium SASL, Memcached, MongoDB, MySQL 8.0.23+, NeoMutt, ongres/scram, OpenDJ, passlib.hash.scram, PhysoTronic/SASL-SCRAM-SHA256, PostgreSQL 10+, pwithnall/libscram, PyMongo 3.7, Rust SASL, Rust SCRAM, Skyspark, SquirelMail, tlocke/scramp, trondn/java-sasl-scram-sha1, Thunderbird 71+, UnboundID LDAP SDK, Vert.x SCRAM, WildFly Elytron, xdg-go/scram, xmpp-webhook

=== SCRAM-SHA-512(-PLUS) ===

Possibly, also adding [https://tools.ietf.org/html/draft-melnikov-scram-sha-512 SCRAM-SHA-512 and SCRAM-SHA-512-PLUS Simple Authentication and Security Layer (SASL) Mechanisms: draft-melnikov-scram-sha-512]

=== SCRAM-SHA3-512(-PLUS) ===

Possibly, also adding [https://tools.ietf.org/html/draft-melnikov-scram-sha3-512 SCRAM-SHA3-512 and SCRAM-SHA3-512-PLUS Simple Authentication and Security Layer (SASL) Mechanisms: draft-melnikov-scram-sha3-512]

=== Order ===
<span style="color:#FF0000">Warning:</span> In [https://tools.ietf.org/html/rfc8600 RFC8600: Using Extensible Messaging and Presence Protocol (XMPP) for Security Information Exchange] (June 2019):

"When using the SASL SCRAM mechanism, the SCRAM-SHA-256-PLUS variant SHOULD be preferred over the SCRAM-SHA-256 variant, and SHA-256 variants [RFC7677] SHOULD be preferred over SHA-1 variants [RFC5802]".

<span style="color:#FF0000">But it has been changed</span> in [https://tools.ietf.org/html/draft-ietf-kitten-password-storage-02 draft-ietf-kitten-password-storage-02] (2020)
* SCRAM-SHA-256-PLUS
* SCRAM-SHA-1-PLUS
* SCRAM-SHA-256
* SCRAM-SHA-1

== SCRAM-SHA-1(-PLUS) ==
=== Overview ===

The basic overview of how this mechanism works is:

# The client sends the username it wants to authenticate as.
# The server sends back the salt for that user and the number of iterations (either by generating them or looking them up in its database for the given username).
# The client hashes the password with the given salt for the given number of iterations.
# The client sends the result back.
# The server does a variation of the hashing and sends it result back to the client, so the client can also verify that the server had the password/a hash of the password.

The cryptographic algorithms needed are [https://tools.ietf.org/html/rfc3174 SHA-1], [https://tools.ietf.org/html/rfc2104 HMAC] with SHA-1 and [https://tools.ietf.org/html/rfc2898 PBKDF2] with SHA-1. It is advised to find libraries to use these algorithms instead of implementing them from scratch.

=== In detail ===

<ol>
<li>First normalize the password (using [https://tools.ietf.org/html/rfc4013 SASLprep]), this will be <code>normalizedPassword</code>. This is to ensure the UTF8 encoding can't contain variations of the same password.</li>
<li>Pick a random string (for example 32 hex encoded bytes). This will be <code>clientNonce</code>.</li>
<li>The initialMessage is:

<pre>"n=" .. username .. ",r=" .. clientNonce</pre>

</li>
<li>The client prepends the GS2 header (<code>"n,,"</code>) to the initialMessage and base64-encodes the result. It sends this as its first message:

<pre>
<auth xmlns="urn:ietf:params:xml:ns:xmpp-sasl" mechanism="SCRAM-SHA-1">
    biwsbj1yb21lbyxyPTZkNDQyYjVkOWU1MWE3NDBmMzY5ZTNkY2VjZjMxNzhl
</auth>
</pre>

</li>

<li>The server responds with a challenge. The data of the challenge is base64 encoded:

<pre>
<challenge xmlns="urn:ietf:params:xml:ns:xmpp-sasl">
    cj02ZDQ0MmI1ZDllNTFhNzQwZjM2OWUzZGNlY2YzMTc4ZWMxMmIzOTg1YmJkNGE4ZTZmODE0YjQyMmFiNzY2NTczLHM9UVNYQ1IrUTZzZWs4YmY5MixpPTQwOTY=
</challenge>
</pre>
</li>

<li>The client base64 decodes it:

<pre>
r=6d442b5d9e51a740f369e3dcecf3178ec12b3985bbd4a8e6f814b422ab766573,s=QSXCR+Q6sek8bf92,i=4096
</pre>
</li>

<li>The client parses this:
    <ul>
    <li>r = This is the serverNonce. The client MUST ensure that it starts with the clientNonce it sent in its initial message.</li>
    <li>s = This is the salt, base64 encoded (yes, this is base64-encoded twice!)</li>
    <li>i = This is the number of iterations, i.</li>
    </ul>

</li>
<li>The client computes:

<pre>
clientFinalMessageBare = "c=biws,r=" .. serverNonce
saltedPassword = PBKDF2-SHA-1(normalizedPassword, salt, i)
clientKey = HMAC-SHA-1(saltedPassword, "Client Key")
storedKey = SHA-1(clientKey)
authMessage = initialMessage .. "," .. serverFirstMessage .. "," .. clientFinalMessageBare
clientSignature = HMAC-SHA-1(storedKey, authMessage)
clientProof = clientKey XOR clientSignature
serverKey = HMAC-SHA-1(saltedPassword, "Server Key")
serverSignature = HMAC-SHA-1(serverKey, authMessage)
clientFinalMessage = clientFinalMessageBare .. ",p=" .. base64(clientProof)
</pre>
</li>

<li>The client base64 encodes the <code>clientFinalMessage</code> and sends it as a response:

<pre>
<response xmlns="urn:ietf:params:xml:ns:xmpp-sasl">
    Yz1iaXdzLHI9NmQ0NDJiNWQ5ZTUxYTc0MGYzNjllM2RjZWNmMzE3OGVjMTJiMzk4NWJiZDRhOGU2ZjgxNGI0MjJhYjc2NjU3MyxwPXlxbTcyWWxmc2hFTmpQUjFYeGFucG5IUVA4bz0=
</response>
</pre>
</li>

<li>
If everything went well, you'll get a <code><success></code> response from the server:

<pre>
<success xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
    dj1wTk5ERlZFUXh1WHhDb1NFaVc4R0VaKzFSU289
</success>
</pre>

Base64 decoded this contains:

<pre>
v=pNNDFVEQxuXxCoSEiW8GEZ+1RSo=
</pre>

</li>
<li>The client MUST make sure the value of v is the base64 encoding of the <code>serverSignature</code> (yes, this value is also base64-encoded twice).</li>
</ol>

=== Extras ===

This is the basic version of the algorithm. You can extend it to do:

* Channel binding. This mixes in some information from the TLS connection to the procedure to prevent MitM attacks.
* Hashed storage. If the server always sends the same salt and i values, then the client can store only <code>clientKey</code>, instead of the user's password. This is more secure (as the client doesn't need to store the password, just a hard to reverse salt) and faster, as the client doesn't need to do all the hashing every time.

=== Common pitfalls ===

* Don't assume anything about the length of the nonces or salt (though if you generate them, make sure they are long enough and cryptographically random).
* The salt is base64 encoded and can contain any data (embedded NULs).
* Not using SASLprep may work fine for people using ASCII passwords, but it may completely break logging in for people using other scripts.
* The <code>initialMessage</code> part of the <code>authMessage</code> does not include the GS2 header (in most situations, this is <code>"n,,"</code>).

=== Test vectors ===

Here is a complete example:

Username: <code>user</code>

Password: <code>pencil</code>

Client generates the random nonce <code>fyko+d2lbbFgONRv9qkxdawL</code>

Initial message: <code>n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL</code>

Server generates the random nonce <code>3rfcNHYJY1ZVvWVs7j</code>

Server replies: <code>r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,s=QSXCR+Q6sek8bf92,i=4096</code>

The salt (hex): <code>4125c247e43ab1e93c6dff76</code>

Client final message bare: <code>c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j</code>

Salted password (hex): <code>1d96ee3a529b5a5f9e47c01f229a2cb8a6e15f7d</code>

Client key (hex): <code>e234c47bf6c36696dd6d852b99aaa2ba26555728</code>

Stored key (hex): <code>e9d94660c39d65c38fbad91c358f14da0eef2bd6</code>

Auth message: <code>n=user,r=fyko+d2lbbFgONRv9qkxdawL,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,s=QSXCR+Q6sek8bf92,i=4096,c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j</code>

Client signature (hex): <code>5d7138c486b0bfabdf49e3e2da8bd6e5c79db613</code>

Client proof (hex): <code>bf45fcbf7073d93d022466c94321745fe1c8e13b</code>

Server key (hex): <code>0fe09258b3ac852ba502cc62ba903eaacdbf7d31</code>

Server signature (hex): <code>ae617da6a57c4bbb2e0286568dae1d251905b0a4</code>

Client final message: <code>c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts=</code>

Server final message: <code>v=rmF9pqV8S7suAoZWja4dJRkFsKQ=</code>

Server's server signature (hex): <code>ae617da6a57c4bbb2e0286568dae1d251905b0a4</code>

== SCRAM-SHA-256(-PLUS) ==

Possibly, also adding [https://tools.ietf.org/html/rfc7677 RFC7677: SCRAM-SHA-256 and SCRAM-SHA-256-PLUS Simple Authentication and Security Layer (SASL) Mechanisms]

=== Overview ===

=== In detail ===

=== Extras ===

=== Common pitfalls ===

=== Test vectors ===

== SCRAM-SHA-512(-PLUS) ==

Possibly, also adding [https://tools.ietf.org/html/draft-melnikov-scram-sha-512 SCRAM-SHA-512 and SCRAM-SHA-512-PLUS Simple Authentication and Security Layer (SASL) Mechanisms: draft-melnikov-scram-sha-512]

=== Overview ===

=== In detail ===

=== Extras ===

=== Common pitfalls ===

=== Test vectors ===

== SCRAM-SHA3-512(-PLUS) ==

Possibly, also adding [https://tools.ietf.org/html/draft-melnikov-scram-sha3-512 SCRAM-SHA3-512 and SCRAM-SHA3-512-PLUS Simple Authentication and Security Layer (SASL) Mechanisms: draft-melnikov-scram-sha3-512]

=== Overview ===

=== In detail ===

=== Extras ===

=== Common pitfalls ===

=== Test vectors ===

== Channel Bindings ==

* [https://tools.ietf.org/html/rfc5056 RFC5056: On the Use of Channel Bindings to Secure Channels]
* [https://tools.ietf.org/html/rfc5929 RFC5929: Channel Bindings for TLS]
* [https://www.iana.org/assignments/channel-binding-types/channel-binding-types.xhtml Channel-Binding Types]
* [https://tools.ietf.org/html/draft-ietf-kitten-tls-channel-bindings-for-tls13 Channel Bindings for TLS 1.3: draft-ietf-kitten-tls-channel-bindings-for-tls13]

== IANA ==

* [https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml Simple Authentication and Security Layer (SASL) Mechanisms]

== LDAP ==

* [https://tools.ietf.org/html/rfc5803 RFC5803: Lightweight Directory Access Protocol (LDAP) Schema for Storing Salted: Challenge Response Authentication Mechanism (SCRAM) Secrets]

== HTTP ==

* [https://tools.ietf.org/html/rfc7804 RFC7804: Salted Challenge Response HTTP Authentication Mechanism]

== 2FA ==

* [https://tools.ietf.org/html/draft-melnikov-scram-2fa Extensions to Salted Challenge Response (SCRAM) for 2 factor authentication: draft-melnikov-scram-2fa]