KDFSpi (Java SE 26 & JDK 26)
Description: declaration: module: java.base, package: javax.crypto, class: KDFSpi
Keywords: javax.crypto.KDFSpi class

# Class KDFSpi

java.lang.Object
javax.crypto.KDFSpi

public abstract class KDFSpi extends Object
This class defines the Service Provider Interface (SPI) for the Key Derivation Function (`KDF`) class.

All the abstract methods in this class must be implemented by each cryptographic service provider who wishes to supply the implementation of a particular key derivation function algorithm.

Implementations must provide a public constructor which accepts a `KDFParameters` object if they depend on the default implementation of `Provider.Service.newInstance` to construct `KDFSpi` instances. The constructor must call `super(params)` passing the parameters supplied. The constructor must also throw an `InvalidAlgorithmParameterException` if the supplied parameters are inappropriate. If a `KDF` object is instantiated with one of the `getInstance` methods that contains a `KDFParameters` parameter, the user-provided `KDFParameters` object will be passed to the constructor of the `KDFSpi` implementation. Otherwise, if it is instantiated with one of the `getInstance` methods without a `KDFParameters` parameter, a `null` value will be passed to the constructor.

Implementations which do not support `KDFParameters` must require `null` to be passed, otherwise an `InvalidAlgorithmParameterException` will be thrown. On the other hand, implementations which require `KDFParameters` should throw an `InvalidAlgorithmParameterException` upon receiving a `null` value if default parameters cannot be generated or upon receiving `KDFParameters` which are not supported by the implementation.

To aid the caller, implementations may return parameters with additional default values or supply random values as used by the underlying `KDF` algorithm. See `engineGetParameters()` for more details.

Since:
  25
See Also:
  - `KDF`
  - `KDFParameters`
  - `KDF.getParameters()`
  - `SecretKey`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `KDFSpi(KDFParameters kdfParameters)`
  The sole constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected abstract byte[]`
  `engineDeriveData(AlgorithmParameterSpec derivationSpec)`
  Derives a key, returns raw data as a byte array.
  `protected abstract SecretKey`
  `engineDeriveKey(String alg, AlgorithmParameterSpec derivationSpec)`
  Derives a key, returned as a `SecretKey` object.
  `protected abstract KDFParameters`
  `engineGetParameters()`
  Returns the `KDFParameters` used with this `KDF` object.

  ### 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.

- ## Constructor Details

  - ### KDFSpi

    protected KDFSpi(KDFParameters kdfParameters) throws InvalidAlgorithmParameterException
    The sole constructor.

    A `KDFParameters` object may be specified for KDF algorithms that support initialization parameters.

    Parameters:
      `kdfParameters` - the initialization parameters for the `KDF` algorithm (may be `null`)
    Throws:
      `InvalidAlgorithmParameterException` - if the initialization parameters are inappropriate for this `KDFSpi`
    See Also:
      - `KDF.getParameters()`

- ## Method Details

  - ### engineGetParameters

    protected abstract KDFParameters engineGetParameters()
    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`

  - ### engineDeriveKey

    protected abstract SecretKey engineDeriveKey(String alg, AlgorithmParameterSpec derivationSpec) throws InvalidAlgorithmParameterException, NoSuchAlgorithmException
    Derives a key, returned as a `SecretKey` object.
    Implementation Note:
      If the resultant key is extractable, then its `getEncoded` value should have the same content as the result of `deriveData`.
    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` - derivation parameters
    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

  - ### engineDeriveData

    protected abstract byte[] engineDeriveData(AlgorithmParameterSpec derivationSpec) throws InvalidAlgorithmParameterException
    Derives a key, returns raw data as a byte array.
    Parameters:
      `derivationSpec` - derivation parameters
    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