* {@code KDF} objects are instantiated with the {@code getInstance} family of * methods. *
* The class has two derive methods, {@code deriveKey} and {@code deriveData}. * The {@code deriveKey} method accepts an algorithm name and returns a * {@code SecretKey} object with the specified algorithm. The {@code deriveData} * method returns a byte array of raw data. *
* API Usage Example:
* {@snippet lang = java:
* KDF kdfHkdf = KDF.getInstance("HKDF-SHA256");
*
* AlgorithmParameterSpec derivationSpec =
* HKDFParameterSpec.ofExtract()
* .addIKM(ikm)
* .addSalt(salt).thenExpand(info, 32);
*
* SecretKey sKey = kdfHkdf.deriveKey("AES", derivationSpec);
*}
*
*
* If the {@code getProviderName} or {@code getParameters} method is called
* before the {@code deriveKey} or {@code deriveData} methods, the first
* provider supporting the {@code KDF} algorithm and optional
* {@code KDFParameters} is chosen. This provider may not support the key
* material that is subsequently passed to the {@code deriveKey} or
* {@code deriveData} methods. Therefore, it is recommended not to call the
* {@code getProviderName} or {@code getParameters} methods until after a key
* derivation operation. Once a provider is selected, it cannot be changed.
*
* @see KDFParameters
* @see SecretKey
* @since 25
*/
public final class KDF {
private static final Debug pdebug = Debug.getInstance("provider",
"Provider");
private static final boolean skipDebug = Debug.isOn("engine=")
&& !Debug.isOn("kdf");
private record Delegate(KDFSpi spi, Provider provider) {}
//guarded by 'lock'
private Delegate theOne;
//guarded by 'lock'
private final Delegate candidate;
// The name of the KDF algorithm.
private final String algorithm;
// Additional KDF configuration parameters
private final KDFParameters kdfParameters;
// remaining services to try in provider selection
// null once provider is selected
private final Iterator
* The returned parameters may be the same that were used to initialize
* this {@code 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 {@code KDF} object, the generated parameters are returned;
* otherwise {@code null} is returned.
*
* @return the parameters used with this {@code KDF} object, or
* {@code null}
*
* @see Delayed Provider
* Selection
*/
public KDFParameters getParameters() {
useFirstSpi();
return theOne.spi().engineGetParameters();
}
/**
* Returns a {@code KDF} object that implements the specified algorithm.
*
* @implNote The JDK Reference Implementation additionally uses the
* {@code jdk.security.provider.preferred}
* {@link Security#getProperty(String) Security} property to
* determine the preferred provider order for the specified
* algorithm. This may be different than the order of providers
* returned by
* {@link Security#getProviders() Security.getProviders()}.
*
* @param algorithm
* the key derivation algorithm to use. See the {@code KDF} section
* in the
* Java Security Standard Algorithm Names Specification for
* information about standard KDF algorithm names.
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @return a {@code KDF} object
*
* @throws NoSuchAlgorithmException
* if no {@code Provider} supports a {@code KDF} implementation for
* the specified algorithm
* @throws NullPointerException
* if {@code algorithm} is {@code null}
* @see Delayed Provider
* Selection
*/
public static KDF getInstance(String algorithm)
throws NoSuchAlgorithmException {
Objects.requireNonNull(algorithm, "algorithm must not be null");
try {
return getInstance(algorithm, (KDFParameters) null);
} catch (InvalidAlgorithmParameterException e) {
throw new NoSuchAlgorithmException(
"No implementation found using null KDFParameters", e);
}
}
/**
* Returns a {@code KDF} object that implements the specified algorithm from
* the specified security provider. The specified provider must be
* registered in the security provider list.
*
* @param algorithm
* the key derivation algorithm to use. See the {@code KDF} section
* in the
* Java Security Standard Algorithm Names Specification for
* information about standard KDF algorithm names.
* @param provider
* the provider to use for this key derivation
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @return a {@code KDF} object
*
* @throws NoSuchAlgorithmException
* if the specified provider does not support the specified
* {@code KDF} algorithm
* @throws NoSuchProviderException
* if the specified provider is not registered in the security
* provider list
* @throws NullPointerException
* if {@code algorithm} or {@code provider} is {@code null}
*/
public static KDF getInstance(String algorithm, String provider)
throws NoSuchAlgorithmException, NoSuchProviderException {
Objects.requireNonNull(algorithm, "algorithm must not be null");
Objects.requireNonNull(provider, "provider must not be null");
try {
return getInstance(algorithm, null, provider);
} catch (InvalidAlgorithmParameterException e) {
throw new NoSuchAlgorithmException(
"No implementation found using null KDFParameters", e);
}
}
/**
* Returns a {@code KDF} object that implements the specified algorithm from
* the specified security provider.
*
* @param algorithm
* the key derivation algorithm to use. See the {@code KDF} section
* in the
* Java Security Standard Algorithm Names Specification for
* information about standard KDF algorithm names.
* @param provider
* the provider to use for this key derivation
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @return a {@code KDF} object
*
* @throws NoSuchAlgorithmException
* if the specified provider does not support the specified
* {@code KDF} algorithm
* @throws NullPointerException
* if {@code algorithm} or {@code provider} is {@code null}
*/
public static KDF getInstance(String algorithm, Provider provider)
throws NoSuchAlgorithmException {
Objects.requireNonNull(algorithm, "algorithm must not be null");
Objects.requireNonNull(provider, "provider must not be null");
try {
return getInstance(algorithm, null, provider);
} catch (InvalidAlgorithmParameterException e) {
throw new NoSuchAlgorithmException(
"No implementation found using null KDFParameters", e);
}
}
/**
* Returns a {@code KDF} object that implements the specified algorithm and
* is initialized with the specified parameters.
*
* @implNote The JDK Reference Implementation additionally uses the
* {@code jdk.security.provider.preferred}
* {@link Security#getProperty(String) Security} property to
* determine the preferred provider order for the specified
* algorithm. This may be different than the order of providers
* returned by
* {@link Security#getProviders() Security.getProviders()}.
*
* @param algorithm
* the key derivation algorithm to use. See the {@code KDF} section
* in the
* Java Security Standard Algorithm Names Specification for
* information about standard KDF algorithm names.
* @param kdfParameters
* the {@code KDFParameters} used to configure the derivation
* algorithm or {@code null} if no parameters are provided
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @return a {@code KDF} object
*
* @throws NoSuchAlgorithmException
* if no {@code Provider} supports a {@code KDF} implementation for
* the specified algorithm
* @throws InvalidAlgorithmParameterException
* if at least one {@code Provider} supports a {@code KDF}
* implementation for the specified algorithm but none of them
* support the specified parameters
* @throws NullPointerException
* if {@code algorithm} is {@code null}
* @see Delayed Provider
* Selection
*/
public static KDF getInstance(String algorithm,
KDFParameters kdfParameters)
throws NoSuchAlgorithmException, InvalidAlgorithmParameterException {
Objects.requireNonNull(algorithm, "algorithm must not be null");
// make sure there is at least one service from a signed provider
Iterator
* If the spi has already been set, it will just return the result.
*/
private Object chooseProvider(String algorithm,
AlgorithmParameterSpec derivationSpec)
throws InvalidAlgorithmParameterException,
NoSuchAlgorithmException {
boolean isDeriveData = (algorithm == null);
synchronized (lock) {
if (checkSpiNonNull(theOne)) {
return (isDeriveData) ?
theOne.spi().engineDeriveData(derivationSpec) :
theOne.spi().engineDeriveKey(algorithm, derivationSpec);
}
Exception lastException = null;
if (!checkSpiNonNull(candidate)) {
throw new AssertionError("Unexpected Error: candidate is null!");
}
Delegate currOne = candidate;
try {
while (true) {
try {
Object result = (isDeriveData) ?
currOne.spi().engineDeriveData(derivationSpec) :
currOne.spi().engineDeriveKey(algorithm,
derivationSpec);
// found a working KDFSpi
this.theOne = currOne;
if (!skipDebug && pdebug != null) {
pdebug.println("The provider "
+ currOne.provider().getName()
+ " is selected");
}
return result;
} catch (Exception e) {
if (!skipDebug && pdebug != null) {
pdebug.println("A " + this.getAlgorithm()
+ " derivation cannot be performed "
+ "using the supplied derivation "
+ "inputs, using "
+ currOne.provider().getName()
+ ". Another Provider will be "
+ "attempted.");
e.printStackTrace(pdebug.getPrintStream());
}
if (lastException == null) {
lastException = e;
}
// try next one if available
assert serviceIterator != null : "serviceIterator was null";
currOne = getNext(serviceIterator, kdfParameters);
}
}
} catch (InvalidAlgorithmParameterException e) {
throw e; // getNext reached end and have seen IAPE
} catch (NoSuchAlgorithmException e) {
if (!skipDebug && pdebug != null) {
pdebug.println(
"All available Providers have been examined "
+ "without a match for performing the "
+ this.getAlgorithm()
+ " derivation using the supplied derivation "
+ "inputs. Therefore, the caught "
+ "NoSuchAlgorithmException will be logged, and "
+ "an InvalidAlgorithmParameterException will "
+ "then be thrown with the last known Exception.");
e.printStackTrace(pdebug.getPrintStream());
}
// getNext reached end without finding an implementation
throw new InvalidAlgorithmParameterException(
"No provider supports this input", lastException);
}
}
}
private static Delegate getNext(Iterator