Class ScramFunctions


  • public final class ScramFunctions
    extends java.lang.Object
    Utility functions (mostly crypto) for SCRAM.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private ScramFunctions()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.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 java.lang.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 java.lang.String nonce​(int nonceSize, java.security.SecureRandom random)
      Generates a random string (called a 'nonce'), composed of ASCII printable characters, except comma (',').
      static byte @NotNull [] salt​(int saltSize, @NotNull java.security.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 java.lang.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 java.lang.String authMessage)
      Verifies that a provided client proof is correct.
      static boolean verifyServerSignature​(ScramMechanism scramMechanism, byte[] serverKey, java.lang.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
    • Field Detail

      • CLIENT_KEY_HMAC_MESSAGE

        private static final byte @NotNull [] CLIENT_KEY_HMAC_MESSAGE
      • SERVER_KEY_HMAC_MESSAGE

        private static final byte @NotNull [] SERVER_KEY_HMAC_MESSAGE
    • Constructor Detail

      • ScramFunctions

        private ScramFunctions()
    • Method Detail

      • 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
        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 @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 java.lang.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 java.lang.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 java.lang.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,
                                                    java.lang.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 java.lang.String nonce​(int nonceSize,
                                             java.security.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:
        java.lang.IllegalArgumentException - if the nonceSize is not positive, or if random is null
      • salt

        public static byte @NotNull [] salt​(int saltSize,
                                            @NotNull
                                            @NotNull java.security.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:
        java.lang.IllegalArgumentException - if the saltSize is not positive, or if random is null
      • authMessage

        public static java.lang.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