com.ongres.scram.common

Class ScramFunctions

java.lang.Object

com.ongres.scram.common.ScramFunctions

public final class ScramFunctions
extends Object

Utility functions (mostly crypto) for SCRAM.

Method Summary

Modifier and Type	Method and Description
static String	authMessage(ClientFirstMessage clientFirstMessage, ServerFirstMessage serverFirstMessage, byte[] cbindData) The AuthMessage is computed by concatenating messages from the authentication exchange.
static byte[]	clientKey(@NotNull ScramMechanism scramMechanism, byte[] saltedPassword) Generates a client key, from the salted password.
static byte[]	clientProof(byte[] clientKey, byte[] clientSignature) Computes the SCRAM client proof to be sent to the server on the client-final-message.
static byte[]	clientSignature(@NotNull ScramMechanism scramMechanism, byte[] storedKey, @NotNull String authMessage) Computes the SCRAM client signature.
static byte[]	hash(@NotNull ScramMechanism scramMechanism, byte[] message) Computes the hash function of a given value, based on the SCRAM mechanism hash function.
static byte[]	hmac(@NotNull ScramMechanism scramMechanism, byte[] key, byte[] message) Computes the HMAC of the message and key, using the given SCRAM mechanism.
static String	nonce(int nonceSize, SecureRandom random) Generates a random string (called a 'nonce'), composed of ASCII printable characters, except comma (',').
static byte[]	salt(int saltSize, @NotNull SecureRandom random) Generates a random salt that can be used to generate a salted password.
static byte[]	saltedPassword(@NotNull ScramMechanism scramMechanism, @NotNull StringPreparation stringPreparation, char[] password, byte[] salt, int iterationCount) Compute the salted password, based on the given SCRAM mechanism, the String preparation algorithm, the provided salt and the number of iterations.
static byte[]	serverKey(@NotNull ScramMechanism scramMechanism, byte[] saltedPassword) Generates a server key, from the salted password.
static byte[]	serverSignature(@NotNull ScramMechanism scramMechanism, byte[] serverKey, @NotNull String authMessage) Compute the SCRAM server signature.
static byte[]	storedKey(@NotNull ScramMechanism scramMechanism, byte[] clientKey) Generates a stored key, from the salted password.
static boolean	verifyClientProof(@NotNull ScramMechanism scramMechanism, byte[] clientProof, byte[] storedKey, @NotNull String authMessage) Verifies that a provided client proof is correct.
static boolean	verifyServerSignature(ScramMechanism scramMechanism, byte[] serverKey, String authMessage, byte[] serverSignature) Verifies that a provided server proof is correct.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

saltedPassword

public static byte[] saltedPassword(@NotNull
                                    @NotNull ScramMechanism scramMechanism,
                                    @NotNull
                                    @NotNull StringPreparation stringPreparation,
                                    char[] password,
                                    byte[] salt,
                                    int iterationCount)

Compute the salted password, based on the given SCRAM mechanism, the String preparation algorithm, the provided salt and the number of iterations.

      SaltedPassword  := Hi(Normalize(password), salt, i)
  

Parameters:

scramMechanism - The SCRAM mechanism

stringPreparation - The String preparation

password - The non-salted password

salt - The bytes representing the salt

iterationCount - The number of iterations

Returns:

The salted password

hmac

public static byte[] hmac(@NotNull
                          @NotNull ScramMechanism scramMechanism,
                          byte[] key,
                          byte[] message)

Computes the HMAC of the message and key, using the given SCRAM mechanism.

     HMAC(key, str)
 

Parameters:

scramMechanism - The SCRAM mechanism

message - The message to compute the HMAC

key - The key used to initialize the MAC

Returns:

The computed HMAC

clientKey

public static byte[] clientKey(@NotNull
                               @NotNull ScramMechanism scramMechanism,
                               byte[] saltedPassword)

Generates a client key, from the salted password.

      ClientKey := HMAC(SaltedPassword, "Client Key")
  

Parameters:

scramMechanism - The SCRAM mechanism

saltedPassword - The salted password

Returns:

The client key

serverKey

public static byte[] serverKey(@NotNull
                               @NotNull ScramMechanism scramMechanism,
                               byte[] saltedPassword)

Generates a server key, from the salted password.

      ServerKey := HMAC(SaltedPassword, "Server Key")
 

Parameters:

scramMechanism - The SCRAM mechanism

saltedPassword - The salted password

Returns:

The server key

hash

public static byte[] hash(@NotNull
                          @NotNull ScramMechanism scramMechanism,
                          byte[] message)

Computes the hash function of a given value, based on the SCRAM mechanism hash function.

     H(str)
 

Parameters:

scramMechanism - The SCRAM mechanism

message - The message to hash

Returns:

The hashed value

storedKey

public static byte[] storedKey(@NotNull
                               @NotNull ScramMechanism scramMechanism,
                               byte[] clientKey)

Generates a stored key, from the salted password.

      StoredKey := H(ClientKey)
 

Parameters:

scramMechanism - The SCRAM mechanism

clientKey - The client key

Returns:

The stored key

clientSignature

public static byte[] clientSignature(@NotNull
                                     @NotNull ScramMechanism scramMechanism,
                                     byte[] storedKey,
                                     @NotNull
                                     @NotNull String authMessage)

Computes the SCRAM client signature.

      ClientSignature := HMAC(StoredKey, AuthMessage)
 

Parameters:

scramMechanism - The SCRAM mechanism

storedKey - The stored key

authMessage - The auth message

Returns:

The client signature

clientProof

public static byte[] clientProof(byte[] clientKey,
                                 byte[] clientSignature)

Computes the SCRAM client proof to be sent to the server on the client-final-message.

      ClientProof := ClientKey XOR ClientSignature
 

Parameters:

clientKey - The client key

clientSignature - The client signature

Returns:

The client proof

serverSignature

public static byte[] serverSignature(@NotNull
                                     @NotNull ScramMechanism scramMechanism,
                                     byte[] serverKey,
                                     @NotNull
                                     @NotNull String authMessage)

Compute the SCRAM server signature.

      ServerSignature := HMAC(ServerKey, AuthMessage)
 

Parameters:

scramMechanism - The SCRAM mechanism

serverKey - The server key

authMessage - The auth message

Returns:

The server signature

verifyClientProof

public static boolean verifyClientProof(@NotNull
                                        @NotNull ScramMechanism scramMechanism,
                                        byte[] clientProof,
                                        byte[] storedKey,
                                        @NotNull
                                        @NotNull String authMessage)

Verifies that a provided client proof is correct.

Parameters:

scramMechanism - The SCRAM mechanism

clientProof - The provided client proof

storedKey - The stored key

authMessage - The auth message

Returns:

True if the client proof is correct

verifyServerSignature

public static boolean verifyServerSignature(ScramMechanism scramMechanism,
                                            byte[] serverKey,
                                            String authMessage,
                                            byte[] serverSignature)

Verifies that a provided server proof is correct.

Parameters:

scramMechanism - The SCRAM mechanism

serverKey - The server key

authMessage - The auth message

serverSignature - The provided server signature

Returns:

True if the server signature is correct

nonce

public static String nonce(int nonceSize,
                           SecureRandom random)

Generates a random string (called a 'nonce'), composed of ASCII printable characters, except comma (',').

Parameters:

nonceSize - The length of the nonce, in characters/bytes

random - The SecureRandom to use

Returns:

The String representing the nonce

Throws:

IllegalArgumentException - if the nonceSize is not positive, or if random is null

salt

public static byte[] salt(int saltSize,
                          @NotNull
                          @NotNull SecureRandom random)

Generates a random salt that can be used to generate a salted password.

Parameters:

saltSize - The length of the salt, in bytes

random - The SecureRandom to use

Returns:

The bye[] representing the salt

Throws:

IllegalArgumentException - if the saltSize is not positive, or if random is null

authMessage

public static String authMessage(ClientFirstMessage clientFirstMessage,
                                 ServerFirstMessage serverFirstMessage,
                                 byte[] cbindData)

The AuthMessage is computed by concatenating messages from the authentication exchange.

      AuthMessage := client-first-message-bare + "," +
                                    server-first-message + "," +
                                    client-final-message-without-proof
 

Parameters:

clientFirstMessage - the ClientFirstMessage

serverFirstMessage - the ServerFirstMessage

cbindData - the channel binding data, or null

Returns:

the AuthMessage