Package org.forgerock.opendj.security

Class ScramMechanism

  • public final class ScramMechanism
extends Object
    SASL/SCRAM client and server implementations as specified in RFC 5802. The implementations have the following features and limitations:
    • two mechanisms: SCRAM-SHA-256 and SCRAM-SHA-512
    • does not support channel bindings
    • does not support extensions (they are silently ignored)
    Thread-safety: instances of this class are thread-safe and may be used concurrently across multiple threads.
    See Also:
    RFC 5802

    • Field Detail

      • SCRAM_SHA_256

        public static final String SCRAM_SHA_256
        The SCRAM-SHA-256 algorithm.

      • SCRAM_SHA_512

        public static final String SCRAM_SHA_512
        The SCRAM-SHA-512 algorithm.

    • Method Detail

      • getInstance

        public static ScramMechanism getInstance​(String algorithm)
                                  throws NoSuchAlgorithmException
        Returns a ScramMechanism object that implements the specified SCRAM mechanism using a new SecureRandom for generating salts and nonce values.
        Parameters:
        algorithm - The name of the SCRAM mechanism, such as SCRAM-SHA-256.
        Returns:
        The new ScramMechanism object that implements the specified SCRAM mechanism.
        Throws:
        NoSuchAlgorithmException - If the algorithm is not a recognized SCRAM mechanism name, or if this JVM does not support the digest or MAC function required by the SCRAM mechanism. Note that SCRAM-SHA-256 should be supported in all JVMs because SHA-256 and HmacSHA256 are required algorithms.

      • getInstance

        public static ScramMechanism getInstance​(String algorithm,
                                         int minIterations)
                                  throws NoSuchAlgorithmException
        Returns a ScramMechanism object that implements the specified SCRAM mechanism using a new SecureRandom for generating salts and nonce values.
        Parameters:
        algorithm - The name of the SCRAM mechanism, such as SCRAM-SHA-256.
        minIterations - The minimum number of iterations accepted by the client. 0 means to use the algorithm default value.
        Returns:
        The new ScramMechanism object that implements the specified SCRAM mechanism.
        Throws:
        NoSuchAlgorithmException - If the algorithm is not a recognized SCRAM mechanism name, or if this JVM does not support the digest or MAC function required by the SCRAM mechanism. Note that SCRAM-SHA-256 should be supported in all JVMs because SHA-256 and HmacSHA256 are required algorithms.

      • getInstance

        public static ScramMechanism getInstance​(String algorithm,
                                         SecureRandom random)
                                  throws NoSuchAlgorithmException
        Returns a ScramMechanism object that implements the specified SCRAM mechanism.
        Parameters:
        algorithm - The name of the SCRAM mechanism, such as SCRAM-SHA-256.
        random - The random number generator which will be used for generating salt and nonce values.
        Returns:
        The new ScramMechanism object that implements the specified SCRAM mechanism.
        Throws:
        NoSuchAlgorithmException - If the algorithm is not a recognized SCRAM mechanism name, or if this JVM does not support the digest or MAC function required by the SCRAM mechanism. Note that SCRAM-SHA-256 should be supported in all JVMs because SHA-256 and HmacSHA256 are required algorithms.

      • getInstance

        public static ScramMechanism getInstance​(String algorithm,
                                         SecureRandom random,
                                         int minIterations)
                                  throws NoSuchAlgorithmException
        Returns a ScramMechanism object that implements the specified SCRAM mechanism.
        Parameters:
        algorithm - The name of the SCRAM mechanism, such as SCRAM-SHA-256.
        random - The random number generator which will be used for generating salt and nonce values.
        minIterations - The minimum number of iterations accepted by the client. 0 means to use the algorithm default value.
        Returns:
        The new ScramMechanism object that implements the specified SCRAM mechanism.
        Throws:
        NoSuchAlgorithmException - If the algorithm is not a recognized SCRAM mechanism name, or if this JVM does not support the digest or MAC function required by the SCRAM mechanism. Note that SCRAM-SHA-256 should be supported in all JVMs because SHA-256 and HmacSHA256 are required algorithms.

      • newScramCredential

        public ScramCredential newScramCredential​(ByteString password)
        Generates a new SCRAM credential suitable for storage in the server, using an iteration count of 10000. This operation is computationally expensive.
        Parameters:
        password - The password for which to generate the SCRAM credential.
        Returns:
        The SCRAM credential suitable for storage in the server.

      • newScramCredential

        public ScramCredential newScramCredential​(ByteString password,
                                          int iterations)
        Generates a new SCRAM credential suitable for storage in the server. This operation is computationally expensive.
        Parameters:
        password - The password for which to generate the SCRAM credential.
        iterations - The number of iterations that should be used when generating new SCRAM credentials.
        Returns:
        The SCRAM credential suitable for storage in the server.

      • passwordMatches

        public boolean passwordMatches​(ScramCredential scramCredential,
                               ByteString password)
        Returns true if the password matches the stored SCRAM credentials. This method is intended for interoperability with non-SCRAM based authentication mechanisms, such as LDAP simple bind, where the client presents their password. It is computationally expensive.
        Parameters:
        scramCredential - The stored SCRAM credentials.
        password - The user's plaintext password.
        Returns:
        true if the password matches the stored SCRAM credentials.

      • newScramSaslClient

        public SaslClient newScramSaslClient​(String authorizationId,
                                     CallbackHandler callbackHandler)
        Returns a new SaslClient for this SCRAM mechanism.
        Parameters:
        authorizationId - The optional authorization ID of the user which represents an alternate authorization identity which should be used for subsequent operations performed on the connection. The authorization ID usually has the form "dn:" immediately followed by the distinguished name of the user, or "u:" followed by a user ID string, but other forms are permitted.
        callbackHandler - A callback handler which will be used for obtaining the user name and password or cached pre-computed credentials. Implementations should expect to receive two callbacks, a NameCallback which will be used for obtaining the username, and a PasswordCallback for retrieving the user's password.
        Returns:
        The new SCRAM SASL client.

      • newScramSaslServer

        public SaslServer newScramSaslServer​(CallbackHandler callbackHandler)
        Returns a new SaslServer for this SCRAM mechanism.
        Parameters:
        callbackHandler - A callback handler which will be used for obtaining the user's credentials stored in the server. Implementations should expect to receive three callbacks, a NameCallback whose default name will be the requested user name (authentication ID), then a ScramCredentialCallback callback for retrieving the ScramCredential for the named user, and finally a AuthorizeCallback for containing both the authentication ID and the authorization ID, which will be the same as the authentication ID if none was provided.
        Returns:
        The new SCRAM SASL server.

      • newScramSaslServer

        public SaslServer newScramSaslServer​(CallbackHandler callbackHandler,
                                     ByteString pepper)
        Returns a new SaslServer for this SCRAM mechanism.
        Parameters:
        callbackHandler - A callback handler which will be used for obtaining the user's credentials stored in the server. Implementations should expect to receive three callbacks, a NameCallback whose default name will be the requested user name (authentication ID), then a ScramCredentialCallback callback for retrieving the ScramCredential for the named user, and finally a AuthorizeCallback for containing both the authentication ID and the authorization ID, which will be the same as the authentication ID if none was provided.
        pepper - The secret pepper which will be combined with unrecognized user-names when generating fake SCRAM credentials. The pepper should be the same on all servers in the deployment.
        Returns:
        The new SCRAM SASL server.

      • toString

        public String toString()
        Returns the algorithm name of this SCRAM mechanism.
        Overrides:
        toString in class Object
        Returns:
        The algorithm name of this SCRAM mechanism.