---

5.7 The SCRAM mechanisms

SCRAM is a family of mechanisms and we support SCRAM-SHA-1 and SCRAM-SHA-256. They differ only in the use of underlying hash function, SHA-1 and SHA-256 respectively. Channel bindings are supported through the SCRAM-SHA-1-PLUS and SCRAM-SHA-256-PLUS mechanisms, and will bind the authentication to a particular TLS channel. SCRAM provides mutual authentication, i.e., after a succesful authentication the client will know that the server knows the password, and the server will know that the client knows the password. Further, this can be achieved without storing the password in clear text on either side.

The SCRAM family is designed to provide the same capabilities that CRAM-MD5 and DIGEST-MD5 provides but with modern cryptographic techniques such as HMAC hashing and PKCS#5 PBKDF2 key derivation. SCRAM supports authorization identities. Like CRAM-MD5 and DIGEST-MD5, only a hashed password is transferred. Consequently, SCRAM servers needs access to the correct password, the salted password, or the derived ServerKey/StoredKey values, to verify the client response.

In the client, the non-PLUS mechanism is always enabled, and it requires the GSASL_AUTHID property, and either GSASL_PASSWORD or GSASL_SCRAM_SALTED_PASSWORD. When the GSASL_CB_TLS_UNIQUE property is available, the SCRAM-SHA-1-PLUS mechanism is also available and it will negotiate channel bindings when the server also supports it. If set, GSASL_AUTHZID will be used by the client. To be able to return the proper GSASL_SCRAM_SALTED_PASSWORD value, the callback needs to check the GSASL_SCRAM_ITER and GSASL_SCRAM_SALT values which are available when the GSASL_SCRAM_SALTED_PASSWORD property is queried for. The client/server may retrieve the calculated GSASL_SCRAM_SALTED_PASSWORD value by retrieving it after the final authentication step. The GSASL_SCRAM_SALTED_PASSWORD value can also be derived by using the gsasl_scram_secrets_from_password function (see Utilities), or through the --mkpasswd parameter for the gsasl utility (see Invoking gsasl).

In the server, the GSASL_AUTHID property (and, when provided by the client, the GSASL_AUTHZID property) will be set in order for the callback to retrieve the user credentials. The server mechanism will request the GSASL_SERVERKEY and GSASL_STOREDKEY properties first, and will use them to complete authentication. Using ServerKey/StoredKey on the server make it possible for the server to avoid storing the clear-text password. If ServerKey/StoredKey is not available, the GSASL_SCRAM_SALTED_PASSWORD property is request, and used to derive the ServetKey/StoredKey secrets. When GSASL_SCRAM_SALTED_PASSWORD is not available, the GSASL_PASSWORD property is requested, which will be used to derive the ServetKey/StoredKey secrets. The mechanism uses the credentials to authenticate the user. The application may set the GSASL_SCRAM_ITER and GSASL_SCRAM_SALT properties which allow the server to tell the clients what values to use for deriving a key from a password. When the application do not supply them, the SCRAM server will default to using a fresh random salt and an iteration count of 4096. After the final authentication step, the application may retrieve the GSASL_SCRAM_ITER, GSASL_SCRAM_SALT, GSASL_SCRAM_SALTED_PASSWORD, GSASL_SERVERKEY, and GSASL_STOREDKEY properties for potential storage in a database to avoid the need to store the cleartext password. When the GSASL_CB_TLS_UNIQUE property is set, the SCRAM-*-PLUS mechanism is supported and is used to negotiate channel bindings.

It is recommended for servers to stored ServerKey/StoredKey in a database instead of GSASL_SCRAM_SALTED_PASSWORD, when possible, since the latter is a password-equivalent but the former cannot directly be used to impersonate the client (although one failed authentication exchange against the server is sufficient to recover a plaintext-equivalent from ServerKey/StoredKey).

The GSASL_CB_TLS_UNIQUE property signal that this side of the authentication supports channel bindings. Setting the property will enable the SCRAM-SHA-1-PLUS and SCRAM-SHA-256-PLUS mechanisms. For clients, this also instructs the SCRAM-SHA-1 and SCRAM-SHA-256 mechanism to tell servers that the client believes the server does not support channel bindings if it is used (remember that clients should otherwise have chosen the SCRAM-SHA-1-PLUS mechanism instead of the SCRAM-SHA-1 mechanism). For servers, it means the SCRAM-SHA-1/SCRAM-SHA-256 mechanism will refuse to authenticate against a client that signals that it believes the server does not support channel bindings.

The SCRAM-SHA-*-PLUS mechanisms will never complete authentication successfully if channel bindings are not confirmed.

To offer the intended security, the SCRAM-SHA-*-PLUS mechanisms MUST be used over a TLS channel that has had the session hash extension (RFC 7627) negotiated, or session resumption MUST NOT have been used. The library cannot enforce this, so it is up to the application to only provide the GSASL_CB_TLS_UNIQUE property when this condition holds.

The SCRAM-SHA-1 mechanism is specified in RFC 5802 and SCRAM-SHA-256 is specified in RFC 7677. How to store SCRAM credentials in LDAP on the server side is described in RFC 5803.