Package 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
    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 @NotNull [] saltedPassword)
    Generates a client key, from the salted password.
    static byte[]
    clientProof(byte @NotNull [] clientKey, byte @NotNull [] clientSignature)
    Computes the SCRAM client proof to be sent to the server on the client-final-message.
    static byte @NotNull []
    clientSignature(@NotNull ScramMechanism scramMechanism, byte @NotNull [] storedKey, @NotNull String authMessage)
    Computes the SCRAM client signature.
    static byte[]
    hash(@NotNull ScramMechanism scramMechanism, byte @NotNull [] message)
    Computes the hash function of a given value, based on the SCRAM mechanism hash function.
    static byte @NotNull []
    hmac(@NotNull ScramMechanism scramMechanism, byte @NotNull [] key, byte @NotNull [] 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 @NotNull []
    salt(int saltSize, @NotNull SecureRandom random)
    Generates a random salt that can be used to generate a salted password.
    static byte @NotNull []
    saltedPassword(@NotNull ScramMechanism scramMechanism, @NotNull StringPreparation stringPreparation, char @NotNull [] password, byte @NotNull [] 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 @NotNull [] saltedPassword)
    Generates a server key, from the salted password.
    static byte @NotNull []
    serverSignature(@NotNull ScramMechanism scramMechanism, byte @NotNull [] serverKey, @NotNull String authMessage)
    Compute the SCRAM server signature.
    static byte[]
    storedKey(@NotNull ScramMechanism scramMechanism, byte @NotNull [] clientKey)
    Generates a stored key, from the salted password.
    static boolean
    verifyClientProof(@NotNull ScramMechanism scramMechanism, byte @NotNull [] clientProof, byte @NotNull [] 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 Details

    • saltedPassword

      public static byte @NotNull [] saltedPassword(@NotNull @NotNull ScramMechanism scramMechanism, @NotNull @NotNull StringPreparation stringPreparation, char @NotNull [] password, byte @NotNull [] 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 @NotNull [] hmac(@NotNull @NotNull ScramMechanism scramMechanism, byte @NotNull [] key, byte @NotNull [] message)
      Computes the HMAC of the message and key, using the given SCRAM mechanism. 
      
     HMAC(key, str)
      Parameters:
      scramMechanism - The SCRAM mechanism
      key - The key used to initialize the MAC
      message - The message to compute the HMAC
      Returns:
      The computed HMAC

    • clientKey

      public static byte[] clientKey(@NotNull @NotNull ScramMechanism scramMechanism, byte @NotNull [] 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 @NotNull [] 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 @NotNull [] 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 @NotNull [] 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 @NotNull [] clientSignature(@NotNull @NotNull ScramMechanism scramMechanism, byte @NotNull [] 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 @NotNull [] clientKey, byte @NotNull [] 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 @NotNull [] serverSignature(@NotNull @NotNull ScramMechanism scramMechanism, byte @NotNull [] 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 @NotNull [] clientProof, byte @NotNull [] 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 @NotNull [] 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