Introduction
Cryptographic key management remains a critical aspect of secure software development in Java. With the release of Java 25, the platform introduces a dedicated Key Derivation Function (KDF) API, building on its initial preview in JDK 24 under JEP 478. This API offers a clean, extensible model for deriving cryptographic keys from initial key material using well-established algorithms. In this guide, we explore the motivation behind the KDF API, its architecture, core components, and derivation methods.
Why KDFs Matter
A Key Derivation Function (KDF) takes initial key material (IKM) and produces one or more cryptographically strong keys. IKM can be a shared secret from a network handshake, a user password, or entropy from a key agreement protocol. KDFs are essential in several scenarios:
- TLS and protocol handshakes: After Diffie-Hellman or ECDH exchanges, the raw shared secret should not be used directly. A KDF transforms it into session keys with appropriate length and entropy.
- Password-based encryption: Raw passwords are weak keys. Algorithms like PBKDF2 stretch and salt passwords to create secure cryptographic material.
- Key diversification: A master key can be expanded into multiple purpose-specific sub-keys without compromising the original.
Before Java 25, developers had no unified API for these use cases. They relied on low-level MAC-based constructions, vendor-specific provider APIs, or third-party libraries like Bouncy Castle. The new KDF API solves this by providing a standard, JCA-integrated interface that is algorithm-agnostic and provider-extensible.
Architecture of the New KDF API
The KDF API resides in the javax.crypto package and follows the familiar factory-method pattern used by other Java cryptographic APIs:
KDF kdf = KDF.getInstance("HKDF-SHA256");The factory pattern uses the getInstance() method to create objects without specifying the concrete class. Here, the method accepts an algorithm name and optionally a Provider. This consistency with the broader JCA architecture allows alternative implementations to be plugged in without changing application code.
Once obtained, a KDF instance can derive either a typed SecretKey or raw byte material:
SecretKey key = kdf.deriveKey("AES", paramSpec);
byte[] rawKeyMaterial = kdf.deriveData(paramSpec);Derivation Methods
The KDF class exposes two primary derivation methods, each suited to different needs:
deriveKey(String alg, AlgorithmParameterSpec params)
This method derives a SecretKey for the specified target algorithm. The provider uses the params to determine the required key length and other parameters. The result is a key object that can be used directly with cryptographic operations such as encryption or signing.
deriveData(AlgorithmParameterSpec params)
In contrast, deriveData returns raw key material as a byte array. This is useful when the derived key needs to be processed further or when compatibility with non-JCA APIs is required. Both methods accept an AlgorithmParameterSpec that specifies the derivation parameters, such as salt, info, and output length.
For a deeper understanding of the parameters, refer to the Motivation section for typical use cases. The KDF API also integrates with existing JCA providers and supports algorithms like HKDF, PBKDF2, and more, ensuring flexibility across applications.
Conclusion
Java 25's KDF API marks a significant step forward in standardizing key derivation within the Java platform. By adhering to JCA patterns, it replaces ad-hoc solutions with a unified, provider-extensible interface. Developers can now derive secure keys for TLS, password storage, and key diversification without relying on external libraries. As adoption grows, expect more providers to implement the KDF API, further enriching the ecosystem.