基础加密调用：接口签名、参数与完整流程

前面我们聊了SDK初始化，但说实话，初始化只是第一步。真正的硬仗在调用加密接口的时候。今天这一章，我们就要把“一次完整加密”给拆开揉碎了。我会从接口签名讲起，然后把各个参数的含义掰扯清楚，最后带你走一遍完整的加密流程。嗯，这段路我走过不少坑，你跟着走能少踩很多。

加密接口签名：背后藏着什么逻辑

先看一个典型的加密接口签名。我用的是C风格示例，但思想在其他语言里一模一样。

int dlp_encrypt(
    DLP_HANDLE      handle,         // SDK句柄
    DLP_ALG_ID      alg_id,         // 算法标识
    DLP_KEY_ID      key_id,         // 密钥索引
    const uint8_t*  iv,             // 初始化向量
    size_t          iv_len,         // IV长度
    const uint8_t*  plaintext,      // 明文
    size_t          plaintext_len,  // 明文长度
    uint8_t*        ciphertext,     // 密文输出缓冲区
    size_t*         ciphertext_len  // 输入时缓冲区大小，输出时实际密文长度
);

你想想看，为什么签名里要分开传指针和长度？我刚开始做的时候也觉得冗余。后来才明白，这是为了兼容不同平台的内存模型。特别是当你需要在Windows和嵌入式Linux之间做数据交换时，这种设计很重要。

参数说明：每个字段都有脾气

参数分三组：句柄与算法、密钥与IV、数据缓冲区。咱们一个一个说。

参数	类型	说明	备注
handle	输入	SDK句柄	必须由 dlp_init 返回，不要传 NULL
alg_id	输入	算法标识	例如 DLP_AES_256_GCM、DLP_SM4_CBC
key_id	输入	密钥索引	由密钥管理系统分配，0表示默认密钥
iv	输入	初始化向量	长度取决于算法，AES-GCM固定12字节，SM4-CBC是16字节
iv_len	输入	IV长度	建议用 sizeof 时确认好字节数
plaintext	输入	明文数据	字节数组
plaintext_len	输入	明文长度	单位字节，不要传长度0
ciphertext	输出	密文输出缓冲区	必须预分配，大小 >= plaintext_len + 算法开销
ciphertext_len	输入输出	缓冲区大小/实际密文长度	调用前赋值为缓冲区容量，调用后为实际密文长度

这里有个常见误区。我记得有次排查线上问题，发现加密后数据全是乱码。最后定位到原因：ciphertext_len 传进去的时候给了 NULL。SDK拿不到缓冲区长度，直接写内存越界了。这种行为是未定义的，运气好没事，运气不好直接崩。你想想看，这种问题多冤。

一次完整加密流程：从入口到出口

好，现在咱们把流程走一遍。过程就六步，但每一层都不能出错。

1. 初始化SDK：调用 dlp_init 拿到句柄。
2. 准备密钥上下文：根据 key_id 加载密钥。
3. 生成/获取IV：GCM模式下建议用随机数，CBC模式下必须用随机数。别偷懒。
4. 调用加密接口：把参数填满，调用 dlp_encrypt。
5. 检查返回码：成功返回 DLP_OK，失败返回错误码。
6. 提取密文：根据 ciphertext_len 的实际值，取出密文。

光说步骤不过瘾，直接上代码。

// 1. 初始化
DLP_HANDLE handle;
if (dlp_init(&handle) != DLP_OK) {
    // 处理初始化失败
    return -1;
}

// 2. 准备密钥上下文（假设密钥ID=100已经预置在硬件安全模块中）
DLP_KEY_CTX key_ctx;
dlp_key_load(handle, 100, &key_ctx);

// 3. 生成随机IV
uint8_t iv[12];  // AES-GCM固定12字节
dlp_random_bytes(handle, iv, sizeof(iv));

// 4. 准备明文
const uint8_t* plaintext = (uint8_t*)"Hello, DLP!";
size_t pt_len = strlen((char*)plaintext);

// 5. 预分配密文缓冲区（GCM模式下需要额外空间存储认证标签）
uint8_t ciphertext[1024];
size_t ct_len = sizeof(ciphertext);  // 传入缓冲区容量

// 6. 调用加密
int ret = dlp_encrypt(
    handle,
    DLP_AES_256_GCM,   // 算法
    100,                // 密钥ID
    iv, sizeof(iv),
    plaintext, pt_len,
    ciphertext, &ct_len  // 注意这里是 &ct_len
);

// 7. 检查返回码
if (ret != DLP_OK) {
    // 加密失败，根据错误码排查
    // 我曾经遇到返回 -1002，最后发现是密钥索引没生效
    dlp_cleanup(handle);
    return -1;
}

// 8. ct_len 现在变成了实际密文长度
printf("加密成功，密文长度：%zu 字节\n", ct_len);

核心调用链路一览

我知道光看文字容易乱，所以画了张流程图。它把这章的核心逻辑串起来了。

看着这个图，你脑子里应该形成一个思维模型：加密调用不是一次函数调用，而是一条链路。每个环节都有前置条件和后置检查。说白了，就是一次“输入-处理-输出”的闭环，中间插了密钥和IV这两个调节参数。

常见错误与排查思路

最后，我把自己踩过的坑整理成一条清单，你遇到问题可以直接对着查。

• 返回码 -1001：密钥索引无效。检查 key_id 是否已经预置到硬件安全模块，或者密钥服务器是否在线。
• 返回码 -1002：IV长度不对。GCM用12字节，CBC用16字节。我曾遇到开发同学把IV传了8字节，结果SDK直接拒绝。
• 返回码 -1003：缓冲区溢出。ciphertext_len 输入值太小。请确保密文缓冲区 >= 明文长度 + 算法开销（一般加16字节认证标签）。
• 返回码 -2000：句柄失效。确认 dlp_init 没有被重复调用覆盖句柄值。
• 返回码 -3000：算法不支持。检查 alg_id 是否在当前SDK版本中可用。

好，到这一章为止，你手里应该有一套可以跑起来的加密调用代码了。接下来深入加密签名校验和性能优化，你会更轻松地理解。