4. ML-KEM密钥生成接口开发实战

在OpenSSL 3.x的架构中，ML-KEM（Module-Lattice-Based Key-Encapsulation Mechanism，即FIPS 203标准化的Kyber）被纳入统一的EVP_PKEY抽象层。这意味着开发者不需要直接调用底层PQC实现，而是复用与RSA、EC一致的密钥生命周期接口：通过算法名称获取EVP_PKEY_CTX，设置参数，调用EVP_PKEY_keygen生成密钥对，最后用EVP_PKEY句柄承载结果。本节围绕这条主线，把参数设置、上下文创建和错误处理三个关键环节落到可编译、可运行的代码上。

一、算法标识与上下文创建

ML-KEM在OpenSSL中以三种参数集形式暴露，算法名称分别为ML-KEM-512、ML-KEM-768和ML-KEM-1024，对应NIST安全类别1、3、5。名称中的数字决定模数环维度k（分别为2、3、4），直接影响公钥、私钥和密文长度。选择哪个参数集不是随意决定的：它与上层协议的安全目标绑定，例如TLS混合密钥交换中常用ML-KEM-768与X25519组合。

创建上下文的标准写法是先构造EVP_PKEY_CTX，再显式初始化。注意EVP_PKEY_CTX_new_from_name只完成算法查找，真正的算法初始化发生在EVP_PKEY_keygen_init中，二者必须成对出现，且都要检查返回值：

#include <openssl/evp.h>
#include <openssl/core_names.h>

EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "ML-KEM-768", NULL);
if (ctx == NULL) {
    /* 算法不可用：可能是OpenSSL版本过低或provider未加载 */
    ERR_print_errors_fp(stderr);
    return -1;
}
if (EVP_PKEY_keygen_init(ctx) <= 0) {
    ERR_print_errors_fp(stderr);
    EVP_PKEY_CTX_free(ctx);
    return -1;
}

这里有一个容易被忽略的前提：ML-KEM由default provider提供，需要OpenSSL 3.5及以上版本（早期版本以KYBER768等旧名称存在，且属于实验性接口）。如果EVP_PKEY_CTX_new_from_name返回NULL，第一反应应是确认版本与provider加载情况，而不是怀疑参数拼写。可以用openssl list -kem-algorithms快速核对当前环境支持的算法名。

二、密钥参数设置

ML-KEM密钥生成阶段可设置的参数并不多，但每一个都有实际意义。最常用的是通过OSSL_PKEY_PARAM_ML_KEM_IMPLICIT_REJECT控制隐式拒绝（implicit rejection）行为，该参数影响解封装失败时的派生密钥计算方式，默认开启，符合FIPS 203要求，一般不建议关闭。另一个值得关注的是确定性生成：通过OSSL_PKEY_PARAM_ML_KEM_SEED注入32字节种子（d‖z），可以让密钥生成过程可复现，这在测试向量验证和密钥派生审计中非常有用。

unsigned char seed[64];  /* d(32B) || z(32B)，示例中由安全随机源填充 */
if (RAND_bytes(seed, sizeof(seed)) != 1) { /* 处理随机源失败 */ }

OSSL_PARAM params[2];
params[0] = OSSL_PARAM_construct_octet_string(
               OSSL_PKEY_PARAM_ML_KEM_SEED, seed, sizeof(seed));
params[1] = OSSL_PARAM_construct_end();

if (EVP_PKEY_CTX_set_params(ctx, params) <= 0) {
    ERR_print_errors_fp(stderr);
    /* 清理并返回 */
}

需要强调：种子模式仅用于测试与可复现场景，生产环境应让库内部调用系统随机源，不要自行缓存或复用种子，否则会直接破坏密钥的唯一性。参数设置失败通常意味着当前provider不支持该参数，此时应回退到默认生成路径，而不是强行继续。

三、生成密钥对与结果判读

参数就绪后调用EVP_PKEY_keygen，输出一个EVP_PKEY *句柄。该句柄同时封装公钥与私钥，后续可用EVP_PKEY_get_octet_string_param按OSSL_PKEY_PARAM_PUB_KEY或OSSL_PKEY_PARAM_PRIV_KEY取出原始字节，也可直接交给EVP_PKEY_encapsulate/EVP_PKEY_decapsulate使用。

EVP_PKEY *pkey = NULL;
if (EVP_PKEY_keygen(ctx, &pkey) <= 0) {
    ERR_print_errors_fp(stderr);
    EVP_PKEY_CTX_free(ctx);
    return -1;
}

size_t publen = 0;
EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PUB_KEY,
                                NULL, 0, &publen);
printf("ML-KEM-768 公钥长度: %zu 字节\n", publen);  /* 预期 1184 */

EVP_PKEY_free(pkey);
EVP_PKEY_CTX_free(ctx);

长度是最直接的判读依据：ML-KEM-512/768/1024的公钥分别为800、1184、1568字节，私钥为1632、2400、3168字节，密文为768、1088、1568字节。若取出的长度与所选参数集不符，说明算法名与实际加载的实现不匹配，应优先排查provider配置。下图展示了从算法选择到密钥句柄产出的完整信号链，以及各环节的失败分支：

四、错误处理与资源释放

EVP接口的错误处理遵循统一约定：返回int的函数以<= 0表示失败，返回指针的函数以NULL表示失败。失败后应立即调用ERR_print_errors_fp或ERR_get_error取出错误栈，否则后续操作会覆盖错误信息。资源释放顺序与创建顺序相反：先EVP_PKEY_free，再EVP_PKEY_CTX_free。若在参数设置阶段失败，pkey尚未分配，只需释放ctx。

五、可复用的封装示例

把上述流程封装为一个返回EVP_PKEY *的函数，调用方只需关心参数集名称与可选的种子。下面给出一个结构完整的参考实现，包含参数校验、错误栈输出与清理标签：

EVP_PKEY *gen_mlkem_key(const char *alg, const unsigned char *seed64)
{
    EVP_PKEY_CTX *ctx = NULL;
    EVP_PKEY *pkey = NULL;

    ctx = EVP_PKEY_CTX_new_from_name(NULL, alg, NULL);
    if (!ctx || EVP_PKEY_keygen_init(ctx) <= 0)
        goto err;

    if (seed64) {
        OSSL_PARAM p[2];
        p[0] = OSSL_PARAM_construct_octet_string(
                   OSSL_PKEY_PARAM_ML_KEM_SEED, (void *)seed64, 64);
        p[1] = OSSL_PARAM_construct_end();
        if (EVP_PKEY_CTX_set_params(ctx, p) <= 0)
            goto err;
    }

    if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
        goto err;

    EVP_PKEY_CTX_free(ctx);
    return pkey;

err:
    ERR_print_errors_fp(stderr);
    EVP_PKEY_free(pkey);
    EVP_PKEY_CTX_free(ctx);
    return NULL;
}

验证封装是否正确的办法很直接：分别用三个参数集各生成一次，打印公钥长度并与上表比对；再用固定种子连续生成两次，比较两次公钥字节是否完全一致——一致说明种子路径生效，不一致则说明参数未被接受或实现忽略了种子。生产代码中还应把alg限定为白名单，避免调用方传入任意字符串导致算法查找失败。

至此，密钥生成环节的输入（参数集与可选种子）、处理（上下文初始化、参数设置、keygen）、可观察变化（返回码与错误栈）和结果判读（密钥长度、种子可复现性）已经形成闭环。生成的EVP_PKEY句柄可直接进入封装与解封装流程，这是后续接口开发的基础。