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 Summary
Modifier 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
-
getAlgorithm
Returns the algorithm name of thisKDFobject.- Returns:
- the algorithm name of this
KDFobject
-
getProviderName
Returns the name of the provider.- Returns:
- the name of the provider
- See Also:
-
getParameters
Returns 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:
-
getInstance
Returns 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 theKDFsection in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.- Returns:
- a
KDFobject - Throws:
NoSuchAlgorithmException- if noProvidersupports aKDFimplementation for the specified algorithmNullPointerException- ifalgorithmisnull- See Also:
-
getInstance
public 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 theKDFsection 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 specifiedKDFalgorithmNoSuchProviderException- if the specified provider is not registered in the security provider listNullPointerException- ifalgorithmorproviderisnull
-
getInstance
public 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 theKDFsection 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 specifiedKDFalgorithmNullPointerException- ifalgorithmorproviderisnull
-
getInstance
public 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 theKDFsection in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.kdfParameters- theKDFParametersused to configure the derivation algorithm ornullif no parameters are provided- Returns:
- a
KDFobject - Throws:
NoSuchAlgorithmException- if noProvidersupports aKDFimplementation for the specified algorithmInvalidAlgorithmParameterException- if at least oneProvidersupports aKDFimplementation for the specified algorithm but none of them support the specified parametersNullPointerException- ifalgorithmisnull- See Also:
-
getInstance
public 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 theKDFsection in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.kdfParameters- theKDFParametersused to configure the derivation algorithm ornullif no parameters are providedprovider- the provider to use for this key derivation- Returns:
- a
KDFobject - Throws:
NoSuchAlgorithmException- if the specified provider does not support the specifiedKDFalgorithmNoSuchProviderException- if the specified provider is not registered in the security provider listInvalidAlgorithmParameterException- if the specified provider supports the specifiedKDFalgorithm but does not support the specified parametersNullPointerException- ifalgorithmorproviderisnull
-
getInstance
public 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 theKDFsection in the Java Security Standard Algorithm Names Specification for information about standard KDF algorithm names.kdfParameters- theKDFParametersused to configure the derivation algorithm ornullif no parameters are providedprovider- the provider to use for this key derivation- Returns:
- a
KDFobject - Throws:
NoSuchAlgorithmException- if the specified provider does not support the specifiedKDFalgorithmInvalidAlgorithmParameterException- if the specified provider supports the specifiedKDFalgorithm but does not support the specified parametersNullPointerException- ifalgorithmorproviderisnull
-
deriveKey
public SecretKey deriveKey(String alg, AlgorithmParameterSpec derivationSpec) throws InvalidAlgorithmParameterException, NoSuchAlgorithmException Derives a key, returned as aSecretKeyobject.- Parameters:
alg- the algorithm of the resultantSecretKeyobjectderivationSpec- the object describing the inputs to the derivation function- Returns:
- the derived key
- Throws:
InvalidAlgorithmParameterException- if the information contained within thederivationSpecis invalid or if the combination ofalgand thederivationSpecresults in something invalidNoSuchAlgorithmException- ifalgis empty or invalidNullPointerException- ifalgorderivationSpecis null- See Also:
-
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 thederivationSpecis invalidUnsupportedOperationException- if the derived keying material is not extractableNullPointerException- ifderivationSpecis null- See Also:
-
KDFwhen preview features are enabled.