# 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