Class KDF
KDF is a preview API of the Java platform.
 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 thegetInstance
 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:
- 
Method SummaryModifier and TypeMethodDescriptionbyte[]deriveData(AlgorithmParameterSpec derivationSpec) Derives a key, returns raw data as a byte array.deriveKey(String alg, AlgorithmParameterSpec derivationSpec) Derives a key, returned as aSecretKeyobject.Returns the algorithm name of thisKDFobject.getInstance(String algorithm) Returns aKDFobject that implements the specified algorithm.getInstance(String algorithm, String provider) Returns aKDFobject that implements the specified algorithm from the specified security provider.getInstance(String algorithm, Provider provider) Returns aKDFobject that implements the specified algorithm from the specified security provider.getInstance(String algorithm, KDFParametersPREVIEW kdfParameters) Returns aKDFobject that implements the specified algorithm and is initialized with the specified parameters.getInstance(String algorithm, KDFParametersPREVIEW kdfParameters, String provider) Returns aKDFobject that implements the specified algorithm from the specified provider and is initialized with the specified parameters.getInstance(String algorithm, KDFParametersPREVIEW kdfParameters, Provider provider) Returns aKDFobject that implements the specified algorithm from the specified provider and is initialized with the specified parameters.Returns theKDFParametersused with thisKDFobject.Returns the name of the provider.
- 
Method Details- 
getAlgorithmReturns the algorithm name of thisKDFobject.- Returns:
- the algorithm name of this KDFobject
 
- 
getProviderNameReturns the name of the provider.- Returns:
- the name of the provider
- See Also:
 
- 
getParametersReturns theKDFParametersused with thisKDFobject.The returned parameters may be the same that were used to initialize this KDFobject, 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 theKDFobject, the generated parameters are returned; otherwisenullis returned.- Returns:
- the parameters used with this KDFobject, ornull
- See Also:
 
- 
getInstanceReturns aKDFobject that implements the specified algorithm.- Implementation Note:
- The JDK Reference Implementation additionally uses the
         jdk.security.provider.preferredSecurityproperty to determine the preferred provider order for the specified algorithm. This may be different than the order of providers returned bySecurity.getProviders().
- Parameters:
- algorithm- the key derivation algorithm to use. See the- KDFsection in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.
- Returns:
- a KDFobject
- Throws:
- NoSuchAlgorithmException- if no- Providersupports a- KDFimplementation for the specified algorithm
- NullPointerException- if- algorithmis- null
- See Also:
 
- 
getInstancepublic static KDFPREVIEW getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException Returns aKDFobject 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- KDFsection 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 KDFobject
- Throws:
- NoSuchAlgorithmException- if the specified provider does not support the specified- KDFalgorithm
- NoSuchProviderException- if the specified provider is not registered in the security provider list
- NullPointerException- if- algorithmor- provideris- null
 
- 
getInstancepublic static KDFPREVIEW getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException Returns aKDFobject that implements the specified algorithm from the specified security provider.- Parameters:
- algorithm- the key derivation algorithm to use. See the- KDFsection 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 KDFobject
- Throws:
- NoSuchAlgorithmException- if the specified provider does not support the specified- KDFalgorithm
- NullPointerException- if- algorithmor- provideris- null
 
- 
getInstancepublic static KDFPREVIEW getInstance(String algorithm, KDFParametersPREVIEW kdfParameters) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException Returns aKDFobject that implements the specified algorithm and is initialized with the specified parameters.- Implementation Note:
- The JDK Reference Implementation additionally uses the
         jdk.security.provider.preferredSecurityproperty to determine the preferred provider order for the specified algorithm. This may be different than the order of providers returned bySecurity.getProviders().
- Parameters:
- algorithm- the key derivation algorithm to use. See the- KDFsection in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.
- kdfParameters- the- KDFParametersused to configure the derivation algorithm or- nullif no parameters are provided
- Returns:
- a KDFobject
- Throws:
- NoSuchAlgorithmException- if no- Providersupports a- KDFimplementation for the specified algorithm
- InvalidAlgorithmParameterException- if at least one- Providersupports a- KDFimplementation for the specified algorithm but none of them support the specified parameters
- NullPointerException- if- algorithmis- null
- See Also:
 
- 
getInstancepublic static KDFPREVIEW getInstance(String algorithm, KDFParametersPREVIEW kdfParameters, String provider) throws NoSuchAlgorithmException, NoSuchProviderException, InvalidAlgorithmParameterException Returns aKDFobject 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- KDFsection in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.
- kdfParameters- the- KDFParametersused to configure the derivation algorithm or- nullif no parameters are provided
- provider- the provider to use for this key derivation
- Returns:
- a KDFobject
- Throws:
- NoSuchAlgorithmException- if the specified provider does not support the specified- KDFalgorithm
- NoSuchProviderException- if the specified provider is not registered in the security provider list
- InvalidAlgorithmParameterException- if the specified provider supports the specified- KDFalgorithm but does not support the specified parameters
- NullPointerException- if- algorithmor- provideris- null
 
- 
getInstancepublic static KDFPREVIEW getInstance(String algorithm, KDFParametersPREVIEW kdfParameters, Provider provider) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException Returns aKDFobject 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- KDFsection in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.
- kdfParameters- the- KDFParametersused to configure the derivation algorithm or- nullif no parameters are provided
- provider- the provider to use for this key derivation
- Returns:
- a KDFobject
- Throws:
- NoSuchAlgorithmException- if the specified provider does not support the specified- KDFalgorithm
- InvalidAlgorithmParameterException- if the specified provider supports the specified- KDFalgorithm but does not support the specified parameters
- NullPointerException- if- algorithmor- provideris- null
 
- 
deriveKeypublic SecretKey deriveKey(String alg, AlgorithmParameterSpec derivationSpec) throws InvalidAlgorithmParameterException, NoSuchAlgorithmException Derives a key, returned as aSecretKeyobject.- Parameters:
- alg- the algorithm of the resultant- SecretKeyobject
- derivationSpec- the object describing the inputs to the derivation function
- Returns:
- the derived key
- Throws:
- InvalidAlgorithmParameterException- if the information contained within the- derivationSpecis invalid or if the combination of- algand the- derivationSpecresults in something invalid
- NoSuchAlgorithmException- if- algis empty or invalid
- NullPointerException- if- algor- derivationSpecis null
- See Also:
 
- 
deriveDatapublic 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- derivationSpecis invalid
- UnsupportedOperationException- if the derived keying material is not extractable
- NullPointerException- if- derivationSpecis null
- See Also:
 
 
- 
KDFwhen preview features are enabled.