Class KDF

java.lang.Object
javax.crypto.KDF

public final class KDF extends Object
KDF is a preview API of the Java platform.
Programs can only use KDF when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
This class provides the functionality of a Key Derivation Function (KDF), which is a cryptographic algorithm for deriving additional keys from a secret key and other data.

KDF objects are instantiated with the getInstance family of methods. KDF algorithm names follow a naming convention of AlgorithmWithPRF. For instance, a KDF implementation of HKDF using HMAC-SHA256 has an algorithm name of "HKDFWithHmacSHA256". In some cases the PRF portion of the algorithm field may be omitted if the KDF algorithm has a fixed or default PRF.

If a provider is not specified in the getInstance method when instantiating a KDF object, the provider is selected the first time the deriveKey or deriveData method is called and a provider is chosen that supports the parameters passed to the deriveKey or deriveData method, for example the initial key material. However, if getProviderName is called before calling the deriveKey or deriveData methods, the first provider supporting the KDF algorithm is chosen which may not be the desired one; therefore it is recommended not to call getProviderName until after a key derivation operation. Once a provider is selected, it cannot be changed.

The deriveKey and deriveData methods of KDF objects must be thread-safe. That is, multiple threads may concurrently invoke these methods on a single KDF object with no ill effects.

API Usage Example:

    KDF kdfHkdf = KDF.getInstance("HKDFWithHmacSHA256");

    KDFParameterSpec kdfParameterSpec =
             HKDFParameterSpec.ofExtract()
                              .addIKM(ikm)
                              .addSalt(salt).thenExpand(info, 42);

    kdfHkdf.deriveKey("AES", kdfParameterSpec);
Since:
23
See Also:
  • Method Details

    • getAlgorithm

      public String getAlgorithm()
      Returns the algorithm name of this KDF object.
      Returns:
      the algorithm name of this KDF object
    • getProviderName

      public String getProviderName()
      Returns the name of the provider.
      Returns:
      the name of the provider
    • getInstance

      public static KDFPREVIEW getInstance(String algorithm) throws NoSuchAlgorithmException
      Returns a KDF object that implements the specified algorithm.
      Parameters:
      algorithm - the key derivation algorithm to use
      Returns:
      a KDF object
      Throws:
      NoSuchAlgorithmException - if no Provider supports a KDF implementation for the specified algorithm
      NullPointerException - if algorithm is null
    • getInstance

      public static KDFPREVIEW getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException
      Returns a KDF object that implements the specified algorithm from the specified security provider.
      Parameters:
      algorithm - the key derivation algorithm to use
      provider - the provider to use for this key derivation; if null, this method is equivalent to getInstance(String)
      Returns:
      a KDF object
      Throws:
      NoSuchAlgorithmException - if a provider is specified and it does not support the specified KDF algorithm, or if provider is null and there is no provider that supports a KDF implementation of the specified algorithm
      NoSuchProviderException - if the specified provider is not registered in the security provider list
      NullPointerException - if the algorithm is null
    • getInstance

      public static KDFPREVIEW getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException
      Returns a {code KDF} object that implements the specified algorithm from the specified security provider.
      Parameters:
      algorithm - the key derivation algorithm to use
      provider - the provider to use for this key derivation; if null, this method is equivalent to getInstance(String)
      Returns:
      a KDF object
      Throws:
      NoSuchAlgorithmException - if a provider is specified and it does not support the specified KDF algorithm, or if provider is null and there is no provider that supports a KDF implementation of the specified algorithm
      NullPointerException - if the algorithm is null
    • getInstance

      public static KDFPREVIEW getInstance(String algorithm, AlgorithmParameterSpec algParameterSpec) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
      Returns a KDF object that implements the specified algorithm and is initialized with the specified parameters.
      Parameters:
      algorithm - the key derivation algorithm to use
      algParameterSpec - the AlgorithmParameterSpec used to configure this KDF's algorithm or null if no additional parameters are provided
      Returns:
      a KDF object
      Throws:
      NoSuchAlgorithmException - if no Provider supports a KDFSpi implementation for the specified algorithm
      InvalidAlgorithmParameterException - if the AlgorithmParameterSpec is an invalid value
      NullPointerException - if the algorithm is null
    • getInstance

      public static KDFPREVIEW getInstance(String algorithm, AlgorithmParameterSpec algParameterSpec, String provider) throws NoSuchAlgorithmException, NoSuchProviderException, InvalidAlgorithmParameterException
      Returns a KDF object that implements the specified algorithm from the specified provider and is initialized with the specified parameters.
      Parameters:
      algorithm - the key derivation algorithm to use
      algParameterSpec - the AlgorithmParameterSpec used to configure this KDF's algorithm or null if no additional parameters are provided
      provider - the provider to use for this key derivation; if null, this method is equivalent to getInstance(String, AlgorithmParameterSpec)
      Returns:
      a KDF object
      Throws:
      NoSuchAlgorithmException - if a provider is specified and it does not support the specified KDF algorithm, or if provider is null and there is no provider that supports a KDF implementation of the specified algorithm
      NoSuchProviderException - if the specified provider is not registered in the security provider list
      InvalidAlgorithmParameterException - if the AlgorithmParameterSpec is an invalid value
      NullPointerException - if the algorithm is null
    • getInstance

      public static KDFPREVIEW getInstance(String algorithm, AlgorithmParameterSpec algParameterSpec, Provider provider) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
      Returns a KDF object that implements the specified algorithm from the specified provider and is initialized with the specified parameters.
      Parameters:
      algorithm - the key derivation algorithm to use
      algParameterSpec - the AlgorithmParameterSpec used to configure this KDF's algorithm or null if no additional parameters are provided
      provider - the provider to use for this key derivation; if null, this method is equivalent to getInstance(String, AlgorithmParameterSpec)
      Returns:
      a KDF object
      Throws:
      NoSuchAlgorithmException - if a provider is specified and it does not support the specified KDF algorithm, or if provider is null and there is no provider that supports a KDF implementation of the specified algorithm
      InvalidAlgorithmParameterException - if the AlgorithmParameterSpec is an invalid value
      NullPointerException - if the algorithm is null
    • deriveKey

      public SecretKey deriveKey(String alg, KDFParameterSpecPREVIEW kdfParameterSpec) throws InvalidParameterSpecException
      Derives a key, returned as a SecretKey.

      The deriveKey method may be called multiple times at the same time on a particular KDF instance.

      Delayed provider selection is also supported such that the provider performing the derive is not selected until the method is called. Once a provider is selected, it cannot be changed.

      Parameters:
      alg - the algorithm of the resultant SecretKey object (may not be null)
      kdfParameterSpec - derivation parameters
      Returns:
      a SecretKey object corresponding to a key built from the KDF output and according to the derivation parameters
      Throws:
      InvalidParameterSpecException - if the information contained within the KDFParameterSpec is invalid or incorrect for the type of key to be derived
      NullPointerException - if alg or kdfParameterSpec is null
    • deriveData

      public byte[] deriveData(KDFParameterSpecPREVIEW kdfParameterSpec) throws InvalidParameterSpecException
      Obtains raw data from a key derivation function.

      The deriveData method may be called multiple times at the same time on a particular KDF instance.

      Delayed provider selection is also supported such that the provider performing the derive is not selected until the method is called. Once a provider is selected, it cannot be changed.

      Parameters:
      kdfParameterSpec - derivation parameters
      Returns:
      a byte array containing a key built from the KDF output and according to the derivation parameters
      Throws:
      InvalidParameterSpecException - if the information contained within the KDFParameterSpec is invalid or incorrect for the type of key to be derived
      UnsupportedOperationException - if the derived key material is not extractable
      NullPointerException - if kdfParameterSpec is null