RFC 7804

Salted Challenge Response HTTP Authentication Mechanism

📅 published March 2016, from ietf

RFC 7804: Salted Challenge Response HTTP Authentication Mechanism 🎀

Okay bestie, here's the vibe check first 💅. This is RFC 7804, titled Salted Challenge Response HTTP Authentication Mechanism. It came out of the Internet Engineering Task Force (IETF), and the author is A. Melnikov from Isode Ltd. It's dated March 2016, its category is Experimental, and its ISSN is 2070-1721. The title block doesn't list anything it obsoletes or updates, so no drama there 🦋.

Abstract 🌸

This spec describes a family of HTTP authentication mechanisms called the Salted Challenge Response Authentication Mechanism (SCRAM) ✨. It's a sturdier option than just sending a plaintext password that's protected by Transport Layer Security (TLS), and it dodges the deployment headaches that earlier TLS-protected challenge response mechanisms ran into 🔐.

Status of This Memo 🧚

Heads up, this document is not an Internet Standards Track spec. It's published so people can examine it, try it out in experimental implementations, and evaluate it 🔬.

It defines an Experimental Protocol for the Internet community. It's an IETF product and it reflects IETF community consensus. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). Not every IESG-approved document is a candidate for any level of Internet Standard, so check Section 2 of RFC 5741 for the details 📚.

For the current status, any errata, and how to send feedback, head to http://www.rfc-editor.org/info/rfc7804 💜.

Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stand on the publication date. Please read these carefully, because they spell out your rights and restrictions for this document. Code Components pulled out of this document need to include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions. They come with no warranty, as described in the Simplified BSD License 🫶.

Table of Contents 📖

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
2.  Conventions Used in This Document . . . . . . . . . . . . . .   3
  2.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   4
  2.2.  Notation  . . . . . . . . . . . . . . . . . . . . . . . .   4
3.  SCRAM Algorithm Overview  . . . . . . . . . . . . . . . . . .   6
4.  SCRAM Mechanism Names . . . . . . . . . . . . . . . . . . . .   7
5.  SCRAM Authentication Exchange . . . . . . . . . . . . . . . .   7
  5.1.  One Round-Trip Reauthentication . . . . . . . . . . . . .  10
6.  Use of the Authentication-Info Header Field with SCRAM  . . .  12
7.  Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . .  13
8.  Security Considerations . . . . . . . . . . . . . . . . . . .  14
9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  15
10. Design Motivations  . . . . . . . . . . . . . . . . . . . . .  15
11. References  . . . . . . . . . . . . . . . . . . . . . . . . .  16
  11.1.  Normative References . . . . . . . . . . . . . . . . . .  16
  11.2.  Informative References . . . . . . . . . . . . . . . . .  17
Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  18
Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  18

1. Introduction ✨

Okay so the auth method that basically every internet application protocol uses is sending clear-text passwords over a channel protected by TLS 🔐. That comes with some serious security concerns. A challenge response mechanism, protected by TLS, could fix those. The catch is that HTTP Digest, the challenge response mechanism that was on the Standards Track, never got widespread deployment and only had limited success 😭.

This spec describes a family of authentication mechanisms called SCRAM. It's built to meet the requirements for deploying a challenge response mechanism more widely than past attempts did (see [RFC5802]) 💖. It also tackles some of the HTTP Digest problems described in [RFC6331], like how complicated it is to implement, and protecting the whole authentication exchange so it can guard against certain man-in-the-middle attacks 🕵️‍♀️.

HTTP SCRAM is an adaptation of [RFC5802] for use in HTTP. The SCRAM data exchanged is identical to what [RFC5802] defines. This document also adds a 1 round-trip reauthentication mode 🦋.

HTTP SCRAM provides the following protocol features:

  • The authentication information stored in the authentication database is not sufficient by itself (without a dictionary attack) to impersonate the client. The information is salted to make it harder to do a pre-stored dictionary attack if the database is stolen 🔒.
  • The server does not gain the ability to impersonate the client to other servers (with an exception for server-authorized proxies), unless it performs a dictionary attack 👀.
  • The mechanism permits the use of a server-authorized proxy without requiring that proxy to have super-user rights with the back-end server 👑.
  • Mutual authentication is supported, but only the client is named (i.e., the server has no name) 🫶.

2. Conventions Used in This Document 💅

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

Formal syntax is defined by [RFC5234] including the core rules defined in Appendix B of [RFC5234].

Example lines prefaced by "C:" are sent by the client and ones prefaced by "S:" by the server. If a single "C:" or "S:" label applies to multiple lines, then the line breaks between those lines are for editorial clarity only and are not part of the actual protocol exchange 🎀.

2.1. Terminology 📚

This document uses several terms defined in the "Internet Security Glossary" [RFC4949], including the following: authentication, authentication exchange, authentication information, brute force, challenge-response, cryptographic hash function, dictionary attack, eavesdropping, hash result, keyed hash, man-in-the-middle, nonce, one-way encryption function, password, replay attack, and salt. If these terms are new to you, use that glossary as your reference 🤓.

Some clarifications and additional definitions follow:

  • Authentication information: Information used to verify an identity claimed by a SCRAM client. The authentication information for a SCRAM identity consists of salt, iteration count, the StoredKey, and the ServerKey (as defined in the algorithm overview) for each supported cryptographic hash function 🍓.
  • Authentication database: The database used to look up the authentication information associated with a particular identity. For application protocols, LDAPv3 (see [RFC4510]) is frequently used as the authentication database. For lower-layer protocols such as PPP or 802.11x, the use of RADIUS [RFC2865] is more common 🧚.
  • Base64: An encoding mechanism defined in Section 4 of [RFC4648] that converts an octet string input to a textual output string that can be easily displayed to a human. The use of base64 in SCRAM is restricted to the canonical form with no whitespace 🌸.
  • Octet: An 8-bit byte.
  • Octet string: A sequence of 8-bit bytes.
  • Salt: A random octet string that is combined with a password before applying a one-way encryption function. This value is used to protect passwords that are stored in an authentication database 🧂.

2.2. Notation 🧮

The pseudocode description of the algorithm uses the following notation:

  • ":=": The variable on the left-hand side represents the octet string resulting from the expression on the right-hand side.
  • "+": Octet string concatenation.
  • "[ ]": A portion of an expression enclosed in "[" and "]" is optional in the result under some circumstances. See the associated text for a description of those circumstances.
  • Normalize(str): Apply the Preparation and Enforcement steps according to the OpaqueString profile (see [RFC7613]) to a UTF-8 [RFC3629] encoded "str". The resulting string is also in UTF-8. Note that implementations MUST either implement OpaqueString profile operations from [RFC7613] or disallow the use of non US-ASCII Unicode codepoints in "str". The latter is a particular case of compliance with [RFC7613] 🚨.
  • HMAC(key, str): Apply the HMAC-keyed hash algorithm (defined in [RFC2104]) using the octet string represented by "key" as the key and the octet string "str" as the input string. The size of the result is the hash result size for the hash function in use. For example, it is 32 octets for SHA-256 and 20 octets for SHA-1 (see [RFC6234]) 🔑.
  • H(str): Apply the cryptographic hash function to the octet string "str", producing an octet string as a result. The size of the result depends on the hash result size for the hash function in use.
  • XOR: Apply the exclusive-or operation to combine the octet string on the left of this operator with the octet string on the right of this operator. The length of the output and each of the two inputs will be the same for this use 🌈.

Hi(str, salt, i):

U1   := HMAC(str, salt + INT(1))
U2   := HMAC(str, U1)
...
Ui-1 := HMAC(str, Ui-2)
Ui   := HMAC(str, Ui-1)

Hi := U1 XOR U2 XOR ... XOR Ui

In that snippet, "i" is the iteration count, "+" is the string concatenation operator, and INT(g) is a four-octet encoding of the integer g, most significant octet first 🤌.

Hi() is, essentially, PBKDF2 [RFC2898] with HMAC() as the Pseudorandom Function (PRF) and with dkLen == output length of HMAC() == output length of H() ✨.

Part 1 of 4 is done, bestie 🧚💜 Part 2 is coming up next, so stay tuned 🦋

3. SCRAM Algorithm Overview ✨

Okay bestie, here's the full play-by-play of an HTTP SCRAM exchange 💅 Heads up: this part skips some bits like the client and server nonces, which you'll find in Section 5 🫶

To start, the SCRAM client has a username and password, both encoded in UTF-8 [RFC3629] (or a ClientKey/ServerKey, or SaltedPassword) 🔐. It sends the username to the server, which pulls up the matching auth info: a salt, a StoredKey, a ServerKey, and an iteration count ("i") 🧚. (Fun fact: a server is allowed to use the same iteration count for every account, so no pressure ✨) The server sends the salt and the iteration count back, and then the client computes these values and sends a ClientProof to the server:

Informative Note: Implementors are encouraged to create test cases that use both usernames and passwords with non-ASCII codepoints. In particular, it is useful to test codepoints whose Unicode Normalization Canonical Composition (NFC) and Unicode Normalization Form Compatibility Composition (NFKC) are different (see [Unicode-UAX15]). Some examples of such codepoints include Vulgar Fraction One Half (U+00BD) and Acute Accent (U+00B4). 🌈

   SaltedPassword  := Hi(Normalize(password), salt, i)
   ClientKey       := HMAC(SaltedPassword, "Client Key")
   StoredKey       := H(ClientKey)
   AuthMessage     := client-first-message-bare + "," +
                      server-first-message + "," +
                      client-final-message-without-proof
   ClientSignature := HMAC(StoredKey, AuthMessage)
   ClientProof     := ClientKey XOR ClientSignature
   ServerKey       := HMAC(SaltedPassword, "Server Key")
   ServerSignature := HMAC(ServerKey, AuthMessage)

The server authenticates the client by computing the ClientSignature, exclusive-ORing that with the ClientProof to recover the ClientKey, and then verifying the ClientKey by applying the hash function and comparing the result to the StoredKey. If the ClientKey is correct, this proves that the client has access to the user's password. 🔥

The client authenticates the server in the same spirit, by computing the ServerSignature and comparing it to the value the server sent. If the two are equal, this proves that the server had access to the user's ServerKey. 💜

For initial authentication, the AuthMessage is computed by concatenating the decoded "data" attribute values from the authentication exchange. The format of each of these 3 decoded "data" attributes is defined in [RFC5802]. 🎀

4. SCRAM Mechanism Names

A SCRAM mechanism name (authentication scheme) is a string "SCRAM-" followed by the uppercased name of the underlying hash function, taken from the IANA "Hash Function Textual Names" registry (see <http://www.iana.org/assignments/hash-function-text-names>). 🍓

For interoperability, all HTTP clients and servers supporting SCRAM MUST implement the SCRAM-SHA-256 authentication mechanism, i.e., an authentication mechanism from the SCRAM family that uses the SHA-256 hash function as defined in [RFC7677]. This is the one everybody needs to have, so it's non-negotiable bestie 👑

5. SCRAM Authentication Exchange

HTTP SCRAM is an HTTP Authentication mechanism whose client response (<credentials-scram>) and server challenge (<challenge-scram>) messages are text-based messages containing one or more attribute-value pairs separated by commas. The messages and their attributes are described below and defined in Section 7. 🦋

  challenge-scram   = scram-name [1*SP 1#auth-param]
        ; Complies with <challenge> ABNF from RFC 7235.
        ; Included in the WWW-Authenticate header field.

  credentials-scram = scram-name [1*SP 1#auth-param]
        ; Complies with <credentials> from RFC 7235.
        ; Included in the Authorization header field.

  scram-name = "SCRAM-SHA-256" / "SCRAM-SHA-1" / other-scram-name
        ; SCRAM-SHA-256 and SCRAM-SHA-1 are registered by this RFC.
        ;
        ; SCRAM-SHA-1 is registered for database compatibility
        ; with implementations of RFC 5802 (such as IMAP or Extensible
          Messaging and Presence Protocol (XMPP)
        ; servers), but it is not recommended for new deployments.

  other-scram-name = "SCRAM-" hash-name
        ; hash-name is a capitalized form of names from IANA.
        ; "Hash Function Textual Names" registry.
        ; Additional SCRAM names must be registered in both
        ; the IANA "SASL Mechanisms" registry
        ; and the IANA "HTTP Authentication Schemes" registry.

This is a simple example of a SCRAM-SHA-256 authentication exchange (no support for channel bindings, since HTTP doesn't currently support this feature 🙈). The username 'user' and password 'pencil' are used. Long lines are folded for readability, so don't panic about the line breaks 💖

C: GET /resource HTTP/1.1
C: Host: server.example.com
C: [...]

S: HTTP/1.1 401 Unauthorized
S: WWW-Authenticate: Digest realm="realm1@example.com",
       Digest realm="realm2@example.com",
       Digest realm="realm3@example.com",
       SCRAM-SHA-256 realm="realm3@example.com",
       SCRAM-SHA-256 realm="testrealm@example.com"
S: [...]

C: GET /resource HTTP/1.1
C: Host: server.example.com
C: Authorization: SCRAM-SHA-256 realm="testrealm@example.com",
       data=biwsbj11c2VyLHI9ck9wck5HZndFYmVSV2diTkVrcU8K
C: [...]

S: HTTP/1.1 401 Unauthorized
S: WWW-Authenticate: SCRAM-SHA-256
        sid=AAAABBBBCCCCDDDD,
        data=cj1yT3ByTkdmd0ViZVJXZ2JORWtxTyVodllEcFdVYTJSYVRDQWZ1eEZJ
           bGopaE5sRixzPVcyMlphSjBTTlk3c29Fc1VFamI2Z1E9PSxpPTQwOTYK
S: [...]

C: GET /resource HTTP/1.1
C: Host: server.example.com
C: Authorization: SCRAM-SHA-256 sid=AAAABBBBCCCCDDDD,
       data=Yz1iaXdzLHI9ck9wck5HZndFYmVSV2diTkVrcU8laHZZRHBXVWEyUmFUQ
          0FmdXhGSWxqKWhObEYscD1kSHpiWmFwV0lrNGpVaE4rVXRlOXl0YWc5empm
          TUhnc3FtbWl6N0FuZFZRPQo=
C: [...]

S: HTTP/1.1 200 Ok
S: Authentication-Info: sid=AAAABBBBCCCCDDDD,
       data=dj02cnJpVFJCaTIzV3BSUi93dHVwK21NaFVaVW4vZEI1bkxUSlJzamw5N
          Uc0PQo=
S: [...Other header fields and resource body...]

In the above example, the first client request contains a "data" attribute that base64 decodes as follows:

n,,n=user,r=rOprNGfwEbeRWgbNEkqO

The server then responds with a "data" attribute that base64 decodes as follows:

r=rOprNGfwEbeRWgbNEkqO%hvYDpWUa2RaTCAfuxFIlj)hNlF,s=W22ZaJ0SNY7soE
sUEjb6gQ==,i=4096

The next client request contains a "data" attribute that base64 decodes as follows:

c=biws,r=rOprNGfwEbeRWgbNEkqO%hvYDpWUa2RaTCAfuxFIlj)hNlF,p=dHzbZap
WIk4jUhN+Ute9ytag9zjfMHgsqmmiz7AndVQ=

The final server response contains a "data" attribute that base64 decodes as follows:

v=6rriTRBi23WpRR/wtup+mMhUZUn/dB5nLTJRsjl95G4=

Note that in the example above, the client can also initiate SCRAM authentication without first being prompted by the server. Plot twist, it can just go first 🧚✨

Initial "SCRAM-SHA-256" authentication starts with sending the Authorization request header field (defined by HTTP/1.1, Part 7 [RFC7235]), which contains the "SCRAM-SHA-256" authentication scheme and the following attributes: 🎀

  • A "realm" attribute MAY be included to indicate the scope of protection, in the manner described in HTTP/1.1, Part 7 [RFC7235]. As specified in [RFC7235], the "realm" attribute MUST NOT appear more than once. The "realm" attribute only appears in the first SCRAM message to the server and in the first SCRAM response from the server. 🌸
  • The client also includes the "data" attribute, which contains the base64-encoded "client-first-message" [RFC5802] containing:
    • a header consisting of a flag indicating whether channel binding is supported-but-not-used, not supported, or used. Note that this version of SCRAM doesn't support HTTP channel bindings, so this header always starts with "n". Otherwise, the message is invalid and authentication MUST fail. 💀
    • SCRAM username and a random, unique "nonce" attribute.

In an HTTP response, the server sends the WWW-Authenticate header field containing a unique session identifier (the "sid" attribute), plus the "data" attribute containing the base64-encoded "server-first-message" [RFC5802]. The "server-first-message" contains the user's iteration count i, the user's salt, and the nonce, which is a concatenation of the client-specified one (taken from the "client-first-message") with a freshly generated server nonce. ⭐

The client then responds with another HTTP request with the Authorization header field, which includes the "sid" attribute received in the previous server response, together with the "data" attribute containing the base64-encoded "client-final-message" data. The latter has the same nonce as in "server-first-message" and a ClientProof computed using the selected hash function (e.g., SHA-256), as explained earlier. 🔥

The server verifies the nonce and the proof. Finally, it responds with a 200 HTTP response with the Authentication-Info header field [RFC7615], containing the "sid" attribute (as received from the client) and the "data" attribute containing the base64-encoded "server-final-message", which concludes the authentication exchange. 👑

The client then authenticates the server by computing the ServerSignature and comparing it to the value sent by the server. If the two are different, the client MUST consider the authentication exchange to be unsuccessful, and it might have to drop the connection. Not the vibe, but that's just how it goes sometimes 🥺💜

5.1. One Round-Trip Reauthentication ✨

okay so if the server supports SCRAM reauthentication 💅, it slips a WWW-Authenticate header field into its first HTTP response. That header has the "realm" attribute (we already covered that 🙈), an sr attribute with the server half of the r attribute (that's the s-nonce from [RFC5802]) 🧩, and an optional ttl attribute, which tells you how many seconds that sr value stays valid ⏰.

If the client already authenticated to the same realm (so it still remembers the "i" and "s" attributes for that user from earlier exchanges with the server) 🧠, it can just answer with "client-final-message". When the client builds that, the c-nonce part of "r" gets made like it was on the initial authentication. The s-nonce part is different: it's a concatenation of nonce-count and the "sr" attribute, in that order 🎀. The nonce-count is a positive integer. It equals the user's "i" attribute on the first reauthentication, and it goes up by 1 on each successful reauthentication 📈.

The whole point of the nonce-count is to let the server catch replays 🕵️‍♀️. The server keeps its own copy of the count, so if it sees the same nonce-count value twice, that request is a replay. Bestie, that's so smart 😭.

If the server still considers the s-nonce part of the "nonce" attribute (the "r" attribute) valid 🌸, which means the nonce-count is what it expects (see above) and the "sr" part is still fresh, it gives access to the requested resource 🔓. (Assuming the client hash verifies correctly, obviously 🙃.) But if the server decides its part of the nonce is stale, like if the "sr" value gets used after the "ttl" seconds have passed 💀, the server returns 401 Unauthorized with the SCRAM mechanism name and these attributes: a new "sr", "stale=true", and an optional "ttl". The "stale" attribute tells the client there's no need to bug the user for the password again 🙌.

Formally, "stale" is a flag. It says the client's previous request got rejected because the nonce value was stale 🥹. If stale is TRUE (case-insensitive), the client may wish to just retry the request with a new encrypted response, without reprompting the user for a new username and password 🫶. The server should only set stale to TRUE if it gets a request where the nonce is invalid but the digest for that nonce is valid (which means the client knows the correct username and password 🔑). If stale is FALSE or anything other than TRUE, or if the stale directive isn't there at all, then the username and/or password are invalid, and new values must be obtained 🚫.

When the client and server build the AuthMessage (see Section 3) that they use to calculate the client and server proofs 🧮, the "client-first-message-bare" and "server-first-message" get rebuilt from data both sides already know 🪄.

Reauthentication can look like this 👀:

C: GET /resource HTTP/1.1
C: Host: server.example.com
C: [...]

S: HTTP/1.1 401 Unauthorized
S: WWW-Authenticate: Digest realm="realm1@example.com",
       Digest realm="realm2@example.com",
       Digest realm="realm3@example.com",
       SCRAM-SHA-256 realm="realm3@example.com",
       SCRAM-SHA-256 realm="testrealm@example.com", sr=%hvYDpWUa2RaTC
        AfuxFIlj)hNlF
       SCRAM-SHA-256 realm="testrealm2@example.com", sr=AAABBBCCCDDD,
        ttl=120
S: [...]

[The client authenticates as usual to realm "testrealm@example.com"]
[Some time later, client decides to reauthenticate.
It will use the cached "i" (4096) and "s" (W22ZaJ0SNY7soEsUEjb6gQ==)
from earlier exchanges.  It will use the nonce-value of 4096 together
with the server advertised "sr" value as the server part of the "r".]

C: GET /resource HTTP/1.1
C: Host: server.example.com
C: Authorization: SCRAM-SHA-256 realm="testrealm@example.com",
       data=Yz1iaXdzLHI9ck9wck5HZndFYmVSV2diTkVrcU80MDk2JWh2WURwV1VhM
        lJhVENBZnV4RklsailoTmxGLHA9ZEh6YlphcFdJazRqVWhOK1V0ZTl5dGFnOX
        pqZk1IZ3NxbW1pejdBbmRWUT0K

C: [...]

S: HTTP/1.1 200 Ok
S: Authentication-Info: sid=AAAABBBBCCCCDDDD,
       data=dj02cnJpVFJCaTIzV3BSUi93dHVwK21NaFVaVW4vZEI1bkxUSlJzamw5N
        Uc0PQo=
S: [...Other header fields and resource body...]

6. Use of the Authentication-Info Header Field with SCRAM 🎀

When SCRAM is in use, the Authentication-Info header field is allowed in the trailer of an HTTP message that's sent with chunked transfer-coding 🧁.

7. Formal Syntax 📜

Here's the grammar, written in the Augmented Backus-Naur Form (ABNF) notation from [RFC5234] 🤓.

   ALPHA = <as defined in RFC 5234 Appendix B.1>
   DIGIT = <as defined in RFC 5234 Appendix B.1>

   base64-char     = ALPHA / DIGIT / "/" / "+"

   base64-4        = 4base64-char

   base64-3        = 3base64-char "="

   base64-2        = 2base64-char "=="

   base64          = *base64-4 [base64-3 / base64-2]

   sr              = "sr=" s-nonce
                     ;; s-nonce is defined in RFC 5802.

   data            = "data=" base64
                     ;; The "data" attribute value is base64-encoded
                     ;; SCRAM challenge or response defined in
                     ;; RFC 5802.

   ttl             = "ttl=" 1*DIGIT
                     ;; "sr" value validity in seconds.
                     ;; No leading 0s.

   reauth-s-nonce  = nonce-count s-nonce

   nonce-count     = posit-number
                     ;; posit-number is defined in RFC 5802.
                     ;; The initial value is taken from the "i"
                     ;; attribute for the user and is incremented
                     ;; by 1 on each successful reauthentication.

   sid             = "sid=" token
                     ;; See token definition in RFC 7235.

   stale           = "stale=" ( "true" / "false" )

   realm           = "realm=" <as defined in RFC 7235>

8. Security Considerations 🚨

Read this part carefully, bestie. It's the serious bit 🫣.

If the authentication exchange happens without strong session encryption (like TLS with data confidentiality), then a passive eavesdropper can gather enough info to run an offline dictionary or brute-force attack and recover the user's password 😱. How long that attack takes depends on the cryptographic hash function selected, how strong the password is, and the iteration count the server supplies. SCRAM lets the server, or the server administrator, raise the iteration count over time to slow those attacks down 🐢. (Heads up: a server that only has StoredKey and ServerKey can't raise the iteration count automatically after a successful authentication. That change would mean resetting the user's password 🔁.) An external security layer with strong encryption will stop these attacks 🛡️.

If the authentication information gets stolen from the authentication database, an offline dictionary or brute-force attack can recover the user's password 💔. Salt helps a bit here, because the attacker has to run a separate attack for each password 🧂. Authentication mechanisms that protect against this attack do exist, like the Encrypted Key Exchange (EKE) class of mechanisms. RFC 2945 [RFC2945] is one example of that technology 🔐.

If an attacker gets the authentication information from the authentication repository and also either eavesdrops on one authentication exchange or impersonates a server, the attacker can impersonate that user to every server that offers SCRAM access, as long as those servers use the same hash function, password, iteration count, and salt 😵. That's why it's important to use randomly generated salt values 🎲.

SCRAM doesn't negotiate which hash function gets used. Hash function negotiation is left to the HTTP authentication mechanism negotiation 🤝. It's important that clients can sort a locally available list of mechanisms by preference, so the client can pick the most preferred one from the server's advertised list 📋. This preference order isn't specified here, because it's a local matter 🏠. The preference order should include objective and subjective notions of mechanism cryptographic strength (for example, SCRAM with SHA-256 should be preferred over SCRAM with SHA-1) 💪.

This document recommends using SCRAM with the SHA-256 hash 💖. SCRAM-SHA-1 is registered for database compatibility with implementations of RFC 5802 (like IMAP or XMPP servers) that also want to expose HTTP access to a related service, but it's not recommended for new deployments 🙅‍♀️.

A hostile server can run a computational denial-of-service attack on clients by sending a huge iteration count value 🥵. To defend against that, a client implementation can pick a maximum iteration count it's willing to use, and reject any values above that threshold. In those cases, the client has to fail the authentication, of course 🙃.

See [RFC4086] for more information about generating randomness 🎰.

9. IANA Considerations 🗂️

New mechanisms in the SCRAM family get registered according to the IANA procedure specified in [RFC5802] ✅.

Note to future "SCRAM-" mechanism designers: Each new "SCRAM-" HTTP authentication mechanism MUST be explicitly registered with IANA and MUST comply with "SCRAM-" mechanism naming convention defined in Section 4 of this document. 📣

IANA has added the following entries to the "HTTP Authentication Schemes" registry defined in HTTP/1.1, Part 7 [RFC7235] 🎉:

   Authentication Scheme Name: SCRAM-SHA-256
   Pointer to specification text: RFC 7804
   Notes (optional): (none)

   Authentication Scheme Name: SCRAM-SHA-1
   Pointer to specification text: RFC 7804
   Notes (optional): (none)

10. Design Motivations 🌈

The following design goals shaped this document 🧚. Some of the goals have changed since the initial draft version of the document, so keep that in mind 🙈.

  • The HTTP authentication mechanism has all the modern features: support for internationalized usernames and passwords 🌍.
  • The protocol supports mutual authentication 🤝.
  • The authentication information stored in the authentication database is not sufficient by itself to impersonate the client 🔒.
  • The server doesn't gain the ability to impersonate the client to other servers (with an exception for server-authorized proxies), unless those other servers allow SCRAM authentication and use the same salt and iteration count for the user 👀.
  • The mechanism is extensible, but (hopefully) not over-engineered in this respect 🧁.
  • The mechanism is easier to implement than HTTP Digest, in both clients and servers 💅.
  • The protocol supports 1 round-trip reauthentication ⚡.

11. References 📚

11.1. Normative References 📚

These are the must-read docs the spec leans on, bestie 💅

11.2. Informative References 🦋

These ones are extra reading, the vibes-and-context section 💜

Acknowledgements 🫶

Okay, big shoutout time 🌸 This doc got so much love from the HTTPAuth, SASL, and Kitten working groups, because their mailing list chats helped shape it. The author also wants to give a super special thank you to the co-authors of [RFC5802], because a huge chunk of text in here was basically borrowed from them 💖

Thank you to Martin Thomson for the idea of adding the "ttl" attribute 🧚

Thank you to Julian F. Reschke for corrections about using the Authentication-Info header field ✨

A special thank you to Tony Hansen, who did an early implementation and left extensive comments on the document 👑

Thank you to Russ Housley, Stephen Farrell, Barry Leiba, and Tim Chown for doing detailed reviews of the document 🎀

Author's Address 💌

Alexey Melnikov

Isode Ltd

Email: Alexey.Melnikov@isode.com

📦 where this page comes from