# Class KDF

java.lang.Object
javax.crypto.KDF

public final class KDF extends Object
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:
  25
See Also:
  - `KDFParameters`
  - `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 KDF`
  `getInstance(String algorithm)`
  Returns a `KDF` object that implements the specified algorithm.
  `static KDF`
  `getInstance(String algorithm, String provider)`
  Returns a `KDF` object that implements the specified algorithm from the specified security provider.
  `static KDF`
  `getInstance(String algorithm, Provider provider)`
  Returns a `KDF` object that implements the specified algorithm from the specified security provider.
  `static KDF`
  `getInstance(String algorithm, KDFParameters kdfParameters)`
  Returns a `KDF` object that implements the specified algorithm and is initialized with the specified parameters.
  `static KDF`
  `getInstance(String algorithm, KDFParameters kdfParameters, String provider)`
  Returns a `KDF` object that implements the specified algorithm from the specified provider and is initialized with the specified parameters.
  `static KDF`
  `getInstance(String algorithm, KDFParameters kdfParameters, Provider provider)`
  Returns a `KDF` object that implements the specified algorithm from the specified provider and is initialized with the specified parameters.
  `KDFParameters`
  `getParameters()`
  Returns the `KDFParameters` used with this `KDF` object.
  `String`
  `getProviderName()`
  Returns the name of the provider.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## 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 KDFParameters 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 KDF 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`
    External Specifications
      - Java Security Standard Algorithm Names
    See Also:
      - Delayed Provider Selection

  - ### getInstance

    public static KDF 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`
    External Specifications
      - Java Security Standard Algorithm Names

  - ### getInstance

    public static KDF 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`
    External Specifications
      - Java Security Standard Algorithm Names

  - ### getInstance

    public static KDF getInstance(String algorithm, KDFParameters 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`
    External Specifications
      - Java Security Standard Algorithm Names
    See Also:
      - Delayed Provider Selection

  - ### getInstance

    public static KDF getInstance(String algorithm, KDFParameters 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`
    External Specifications
      - Java Security Standard Algorithm Names

  - ### getInstance

    public static KDF getInstance(String algorithm, KDFParameters 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`
    External Specifications
      - Java Security Standard Algorithm Names

  - ### 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. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names.
      `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
    External Specifications
      - Java Security Standard Algorithm Names
    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