# 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 input keying material (IKM) and (optionally) other data.

`KDF` objects are instantiated with the `getInstance` family of methods.

The class has two derive methods, `deriveKey` and `deriveData`. The `deriveKey` method accepts an algorithm name and returns a `SecretKey` object with the specified algorithm. The `deriveData` method returns a byte array of raw data.

API Usage Example:

        KDF kdfHkdf = KDF.getInstance("HKDF-SHA256");

        AlgorithmParameterSpec derivationSpec =
                 HKDFParameterSpec.ofExtract()
                                  .addIKM(ikm)
                                  .addSalt(salt).thenExpand(info, 32);

        SecretKey sKey = kdfHkdf.deriveKey("AES", derivationSpec);

## Concurrent Access

Unless otherwise documented by an implementation, the methods defined in this class are not thread-safe. Multiple threads that need to access a single object concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating separate objects need not synchronize.

## Delayed Provider Selection

If a provider is not specified when calling one of the `getInstance` methods, the implementation delays the selection of the provider until the `deriveKey` or `deriveData` method is called. This is called delayed provider selection. The primary reason this is done is to ensure that the selected provider can handle the key material that is passed to those methods - for example, the key material may reside on a hardware device that only a specific `KDF` provider can utilize. The `getInstance` method returns a `KDF` object as long as there exists at least one registered security provider that implements the algorithm and supports the optional parameters. The delayed provider selection process traverses the list of registered security providers, starting with the most preferred `Provider`. The first provider that supports the specified algorithm, optional parameters, and key material is selected.

If the `getProviderName` or `getParameters` method is called before the `deriveKey` or `deriveData` methods, the first provider supporting the `KDF` algorithm and optional `KDFParameters` is chosen. This provider may not support the key material that is subsequently passed to the `deriveKey` or `deriveData` methods. Therefore, it is recommended not to call the `getProviderName` or `getParameters` methods until after a key derivation operation. Once a provider is selected, it cannot be changed.

Since:
  24
See Also:
  - `KDFParameters`PREVIEW
  - `SecretKey`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `byte[]`
  `deriveData(AlgorithmParameterSpec derivationSpec)`
  Derives a key, returns raw data as a byte array.
  `SecretKey`
  `deriveKey(String alg, AlgorithmParameterSpec derivationSpec)`
  Derives a key, returned as a `SecretKey` object.
  `String`
  `getAlgorithm()`
  Returns the algorithm name of this `KDF` object.
  `static KDFPREVIEW`
  `getInstance(String algorithm)`
  Returns a `KDF` object that implements the specified algorithm.
  `static KDFPREVIEW`
  `getInstance(String algorithm, String provider)`
  Returns a `KDF` object that implements the specified algorithm from the specified security provider.
  `static KDFPREVIEW`
  `getInstance(String algorithm, Provider provider)`
  Returns a `KDF` object that implements the specified algorithm from the specified security provider.
  `static KDFPREVIEW`
  `getInstance(String algorithm, KDFParametersPREVIEW kdfParameters)`
  Returns a `KDF` object that implements the specified algorithm and is initialized with the specified parameters.
  `static KDFPREVIEW`
  `getInstance(String algorithm, KDFParametersPREVIEW kdfParameters, String provider)`
  Returns a `KDF` object that implements the specified algorithm from the specified provider and is initialized with the specified parameters.
  `static KDFPREVIEW`
  `getInstance(String algorithm, KDFParametersPREVIEW kdfParameters, Provider provider)`
  Returns a `KDF` object that implements the specified algorithm from the specified provider and is initialized with the specified parameters.
  `KDFParametersPREVIEW`
  `getParameters()`
  Returns the `KDFParameters` used with this `KDF` object.
  `String`
  `getProviderName()`
  Returns the name of the provider.

  ### Methods declared in class java.lang.Object

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

- ## 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
    See Also:
      - Delayed Provider Selection

  - ### getParameters

    public KDFParametersPREVIEW getParameters()
    Returns the `KDFParameters` used with this `KDF` object.

    The returned parameters may be the same that were used to initialize this `KDF` object, or may contain additional default or random parameter values used by the underlying KDF algorithm. If the required parameters were not supplied and can be generated by the `KDF` object, the generated parameters are returned; otherwise `null` is returned.

    Returns:
      the parameters used with this `KDF` object, or `null`
    See Also:
      - Delayed Provider Selection

  - ### getInstance

    public static KDFPREVIEW getInstance(String algorithm) throws NoSuchAlgorithmException
    Returns a `KDF` object that implements the specified algorithm.
    Implementation Note:
      The JDK Reference Implementation additionally uses the `jdk.security.provider.preferred` `Security` property to determine the preferred provider order for the specified algorithm. This may be different than the order of providers returned by `Security.getProviders()`.
    Parameters:
      `algorithm` - the key derivation algorithm to use. See the `KDF` section in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.
    Returns:
      a `KDF` object
    Throws:
      `NoSuchAlgorithmException` - if no `Provider` supports a `KDF` implementation for the specified algorithm
      `NullPointerException` - if `algorithm` is `null`
    See Also:
      - Delayed Provider Selection

  - ### 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. The specified provider must be registered in the security provider list.
    Parameters:
      `algorithm` - the key derivation algorithm to use. See the `KDF` section in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.
      `provider` - the provider to use for this key derivation
    Returns:
      a `KDF` object
    Throws:
      `NoSuchAlgorithmException` - if the specified provider does not support the specified `KDF` algorithm
      `NoSuchProviderException` - if the specified provider is not registered in the security provider list
      `NullPointerException` - if `algorithm` or `provider` is `null`

  - ### getInstance

    public static KDFPREVIEW getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException
    Returns a `KDF` object that implements the specified algorithm from the specified security provider.
    Parameters:
      `algorithm` - the key derivation algorithm to use. See the `KDF` section in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.
      `provider` - the provider to use for this key derivation
    Returns:
      a `KDF` object
    Throws:
      `NoSuchAlgorithmException` - if the specified provider does not support the specified `KDF` algorithm
      `NullPointerException` - if `algorithm` or `provider` is `null`

  - ### getInstance

    public static KDFPREVIEW getInstance(String algorithm, KDFParametersPREVIEW kdfParameters) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
    Returns a `KDF` object that implements the specified algorithm and is initialized with the specified parameters.
    Implementation Note:
      The JDK Reference Implementation additionally uses the `jdk.security.provider.preferred` `Security` property to determine the preferred provider order for the specified algorithm. This may be different than the order of providers returned by `Security.getProviders()`.
    Parameters:
      `algorithm` - the key derivation algorithm to use. See the `KDF` section in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.
      `kdfParameters` - the `KDFParameters` used to configure the derivation algorithm or `null` if no parameters are provided
    Returns:
      a `KDF` object
    Throws:
      `NoSuchAlgorithmException` - if no `Provider` supports a `KDF` implementation for the specified algorithm
      `InvalidAlgorithmParameterException` - if at least one `Provider` supports a `KDF` implementation for the specified algorithm but none of them support the specified parameters
      `NullPointerException` - if `algorithm` is `null`
    See Also:
      - Delayed Provider Selection

  - ### getInstance

    public static KDFPREVIEW getInstance(String algorithm, KDFParametersPREVIEW kdfParameters, 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. The specified provider must be registered in the security provider list.
    Parameters:
      `algorithm` - the key derivation algorithm to use. See the `KDF` section in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.
      `kdfParameters` - the `KDFParameters` used to configure the derivation algorithm or `null` if no parameters are provided
      `provider` - the provider to use for this key derivation
    Returns:
      a `KDF` object
    Throws:
      `NoSuchAlgorithmException` - if the specified provider does not support the specified `KDF` algorithm
      `NoSuchProviderException` - if the specified provider is not registered in the security provider list
      `InvalidAlgorithmParameterException` - if the specified provider supports the specified `KDF` algorithm but does not support the specified parameters
      `NullPointerException` - if `algorithm` or `provider` is `null`

  - ### getInstance

    public static KDFPREVIEW getInstance(String algorithm, KDFParametersPREVIEW kdfParameters, 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. See the `KDF` section in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.
      `kdfParameters` - the `KDFParameters` used to configure the derivation algorithm or `null` if no parameters are provided
      `provider` - the provider to use for this key derivation
    Returns:
      a `KDF` object
    Throws:
      `NoSuchAlgorithmException` - if the specified provider does not support the specified `KDF` algorithm
      `InvalidAlgorithmParameterException` - if the specified provider supports the specified `KDF` algorithm but does not support the specified parameters
      `NullPointerException` - if `algorithm` or `provider` is `null`

  - ### deriveKey

    public SecretKey deriveKey(String alg, AlgorithmParameterSpec derivationSpec) throws InvalidAlgorithmParameterException, NoSuchAlgorithmException
    Derives a key, returned as a `SecretKey` object.
    Parameters:
      `alg` - the algorithm of the resultant `SecretKey` object
      `derivationSpec` - the object describing the inputs to the derivation function
    Returns:
      the derived key
    Throws:
      `InvalidAlgorithmParameterException` - if the information contained within the `derivationSpec` is invalid or if the combination of `alg` and the `derivationSpec` results in something invalid
      `NoSuchAlgorithmException` - if `alg` is empty or invalid
      `NullPointerException` - if `alg` or `derivationSpec` is null
    See Also:
      - Delayed Provider Selection

  - ### deriveData

    public byte[] deriveData(AlgorithmParameterSpec derivationSpec) throws InvalidAlgorithmParameterException
    Derives a key, returns raw data as a byte array.
    Parameters:
      `derivationSpec` - the object describing the inputs to the derivation function
    Returns:
      the derived key in its raw bytes
    Throws:
      `InvalidAlgorithmParameterException` - if the information contained within the `derivationSpec` is invalid
      `UnsupportedOperationException` - if the derived keying material is not extractable
      `NullPointerException` - if `derivationSpec` is null
    See Also:
      - Delayed Provider Selection