Java 25 KDF 怎么派生 AES 密钥：HKDF 参数、长度与验收

服务端手里已经有了一段预先协商好的共享密钥，接下来要分别派生出AES加密密钥、签名校验上下文还有会话标识。之前项目里大家常自己手写HMAC拼接实现，参数顺序和输出长度只要两端约定得不一样，就会出现两边代码都跑成功、但最后算出来的密钥完全对不上的坑。Java 25正式上线密钥派生函数API之后，HKDF完全可以走标准的 javax.crypto.KDF 接口把这件事做对。

影响面：手写 HKDF 最容易错在哪里

HKDF不是一次简单的哈希调用，分extract和expand两个独立阶段。extract先把输入密钥材料和盐值处理成伪随机密钥，expand再结合场景上下文派生出指定长度的输出。漏掉salt、把info随便设成空数组，或者两端约定的输出长度不一样，最后出来的密钥肯定对不上。

Java 25的API直接把这些输入拆成了可读性很强的参数构造链。开发者可以直接把“这把密钥用在什么业务场景”写进info参数里，不用把用途逻辑藏在一堆很难排查的字节拼接代码里。

时间线：JEP 510 在 Java 25 变成正式 API

密钥派生函数API最早在JDK 24里以预览形态发布，JEP 510在JDK 25中正式转正。核心入口是 KDF.getInstance，运行结果既可以通过 deriveKey 拿到 SecretKey 对象，也可以通过 deriveData 直接拿到原始字节数组。

这套API的设计目标是统一支持HKDF、Argon2等各类密钥派生算法，也给KEM、TLS 1.3混合密钥交换、HPKE这类标准协议提供统一的派生接口。它不是用来做密码哈希存储的API，现有的PBKDF1、PBKDF2实现仍然保留在 SecretKeyFactory 里。

触发条件：先把 HKDF 的四个输入对齐

• IKM：两端已经协商好的输入密钥材料，必须是高熵的秘密值，不能直接把普通用户的明文密码当成HKDF的输入。
• salt：extract阶段的盐值，协议层面要明确约定是固定值、随机生成，还是跟着会话一起传输。
• info：expand阶段的用途上下文，例如 order-service/aes-v1，用来避免同一组IKM派生出用途混淆的不同密钥。
• 长度：AES-128对应16字节，AES-256对应32字节，长度必须作为协议的组成部分提前固定下来。

只要两端的算法名、salt、info或者输出长度任意一项不一样，派生出来的结果肯定对不上。先别急着写代码改逻辑，把这些值统一整理进协议说明或者测试用例里再动手。

根因：extract 与 expand 不能混成一层

下面的示例是用固定测试输入派生32字节AES密钥。这里用固定输入只是为了方便测试复现，生产环境要使用安全的密钥来源，通过安全配置或者密钥管理系统注入参数。

import java.nio.charset.StandardCharsets;
import java.security.GeneralSecurityException;
import javax.crypto.KDF;
import javax.crypto.SecretKey;
import javax.crypto.spec.HKDFParameterSpec;

public final class HkdfAesKey {
    public static SecretKey derive(byte[] ikm, byte[] salt)
            throws GeneralSecurityException {
        KDF hkdf = KDF.getInstance("HKDF-SHA256");
        HKDFParameterSpec spec = HKDFParameterSpec.ofExtract()
                .addIKM(ikm)
                .addSalt(salt)
                .thenExpand(
                        "order-service/aes-v1".getBytes(StandardCharsets.UTF_8),
                        32);
        return hkdf.deriveKey("AES", spec);
    }
}

ofExtract() 代表参数链从extract阶段开始配置；addIKM 和 addSalt 把提取阶段的输入补全；thenExpand 把用途上下文和输出长度传给expand阶段。最后指定的算法名 AES 决定了返回的 SecretKey 具体类型。

修复动作：用长度、算法和重算结果做验收

先验收输出长度

byte[] ikm = "test-input-key-material".getBytes(StandardCharsets.UTF_8);
byte[] salt = "session-salt-2026".getBytes(StandardCharsets.UTF_8);
SecretKey key = HkdfAesKey.derive(ikm, salt);

if (!"AES".equals(key.getAlgorithm())) {
    throw new IllegalStateException("unexpected key algorithm");
}
if (key.getEncoded() == null || key.getEncoded().length != 32) {
    throw new IllegalStateException("AES-256 output must be 32 bytes");
}

不要只打印密钥的明文内容来判断派生是否成功，单元测试里只要校验算法名和输出字节长度就够了，生产环境的日志里绝对不能输出原始密钥。

再验收用途隔离

把info参数改成 order-service/sign-v1，哪怕IKM、salt和输出长度全都不变，派生出来的结果也应该不一样。加这个断言就能提前发现“业务用途没进派生上下文”的隐性缺陷。

HKDFParameterSpec otherUse = HKDFParameterSpec.ofExtract()
        .addIKM(ikm)
        .addSalt(salt)
        .thenExpand("order-service/sign-v1".getBytes(StandardCharsets.UTF_8), 32);
byte[] otherKey = KDF.getInstance("HKDF-SHA256")
        .deriveData(otherUse);
if (java.util.Arrays.equals(key.getEncoded(), otherKey)) {
    throw new AssertionError("different info must separate derived keys");
}

如果要做多端互通，建议把info做成带版本号的常量，每个版本都提前准备好跨语言的测试向量。只在Java端跑单元测试，根本发现不了另一端把info的编码从UTF-8改成了其他编码的问题。

防复发：把 KDF 与密码存储方案分开

HKDF适合从已经存在的高熵密钥材料里，派生多把用途不同的子密钥。用户密码的哈希存储还是要走面向密码的专用方案，按对应算法的参数策略配置，不能看到它能派生密钥就直接当成密码哈希的替代方案。

上线之前可以做四项校验：两端约定的算法名是不是完全一致；salt的传递规则和生命周期有没有写清楚；info有没有包含业务用途和版本号；输出长度和对应的AES变体是不是匹配。如果项目目前还兼容Java 21，旧版本代码不要直接引用Java 25新增的 KDF 类，可以暂时保留原有经过验证的实现，或者用其他成熟的第三方密码库，做多版本构建的时候再单独切换适配逻辑。

常见问题

Java 25 的 KDF API 需要打开预览开关吗？

不需要。JEP 510 在 Java 25 已经正式交付，直接用正式版JDK 25编译就能正常使用。

HKDF 的 salt 可以一直传空数组吗？

是否允许要结合业务协议和安全目标决定，不能用统一答案直接替代方案设计。如果对应规范明确要求提供salt，就按规范传入，保证两端参数完全一致。

info 和 salt 都是公开数据吗？

通常它们不需要承担IKM的秘密性，但仍然要纳入协议的完整性保护范围。公开不代表可以随意改动，任意一项变了，派生出来的密钥结果就会完全不同。

KDF 能直接替代 PBKDF2 吗？

不能简单直接替换。官方文档明确把 PBKDF1、PBKDF2 留在 SecretKeyFactory API 中，密码存储场景要按对应算法的参数要求和威胁模型做专门设计。

最后确认

Java 25 的 KDF API 解决的是“用标准入口统一规范密钥派生逻辑”的问题，不会自动帮你决定所有协议参数。把IKM、salt、info、输出长度和用途版本都提前固定好，再用算法名、长度和跨语言测试向量做全链路验收，HKDF的实现才真正具备可维护的工程边界。