Next: The NTLM mechanism, Previous: The DIGEST-MD5 mechanism, Up: Mechanisms [Contents][Index]
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.
Next: The NTLM mechanism, Previous: The DIGEST-MD5 mechanism, Up: Mechanisms [Contents][Index]