GM/T 0016-2023 智能密码钥匙密码应用接口规范：国密 USBKey 客户端密码设备互操作的基石

概述

在国密密码应用体系中，智能密码钥匙（俗称 USBKey）是最常见的客户端密码设备形态。从个人网银 U 盾到企业数字证书载体，USBKey 承载着 SM2 签名、SM3 杂凑、SM4 加密等核心密码操作。

GM/T 0016-2023《智能密码钥匙密码应用接口规范》 是规范这一类设备接口的基础性标准。它首次发布于 2012 年（GM/T 0016-2012），在 2023 年进行了全面修订，新增了对 SM9、ZUC 等国密算法的支持，并与 GM/T 0006-2023《密码应用标识规范》保持标识体系一致。

重要说明：GM/T 0016 与 GM/T 0018 构成国密密码设备接口的双轨体系——GM/T 0016 面向客户端智能密码钥匙，GM/T 0018 面向服务端密码设备。两者接口架构相似但应用场景不同。

标准定位与体系关系

接口规范体系

┌─────────────────────────────────────────────────────┐
│                  应用层（Java/Python/C 调用）          │
├─────────────────────────────────────────────────────┤
│  GM/T 0016          │  GM/T 0018          │  GM/T 0019  │
│  智能密码钥匙接口    │  服务端密码设备接口  │  密码服务接口 │
│  (客户端 USBKey)    │  (服务器端密码机)    │  (统一服务层) │
├─────────────────────────────────────────────────────┤
│  GM/T 0017          │  数据结构定义        │
│  智能密码钥匙数据格式 │                     │           │
├─────────────────────────────────────────────────────┤
│  硬件驱动层（PC/SC、USB HID）                       │
└─────────────────────────────────────────────────────┘

与相关标准的关系

接口函数体系

GM/T 0016-2023 定义了三层接口函数体系，覆盖身份认证、密钥管理、密码操作三大场景。

1. 身份认证接口

智能密码钥匙通常存储用户私钥，使用前需进行身份认证（PIN 码验证）。

合规要点：PIN 码长度不得少于 6 位，错误尝试次数超过限定值后应自动锁定设备（通常 3-6 次，具体以产品规格为准）。

2. 密钥管理接口

// 密钥生成
int GM_T_GenerateKeyPair(
    unsigned char *pubKey,      // 输出：公钥
    unsigned long *pubKeyLen,   // 输出：公钥长度
    unsigned char *privateKey,  // 输出：私钥（若支持导出）
    unsigned long *privKeyLen,  // 输出：私钥长度
    int algorithmId             // 算法标识（如 SM2_SIGN=0x0001）
);

// 密钥导入
int GM_T_ImportKey(
    unsigned char *privateKey,
    unsigned long privateKeyLen,
    unsigned char *publicKey,
    unsigned long publicKeyLen,
    int algorithmId
);

// 密钥删除
int GM_T_DeleteKey(
    unsigned char *publicKey,
    unsigned long publicKeyLen
);

注意：根据 GM/T 0028 安全等级要求，部分安全等级的 USBKey 不支持私钥导出，此时 privateKey 参数应返回错误码。

3. 密码操作接口

#### 3.1 SM2 签名接口

int GM_T_Sign(
    unsigned char *signature,      // 输出：签名值
    unsigned long *signatureLen,   // 输出：签名长度
    unsigned char *data,           // 输入：待签名数据
    unsigned long dataLen,         // 输入：数据长度
    unsigned char *publicKey,      // 输入：签名者公钥
    unsigned long publicKeyLen     // 输入：公钥长度
);

国密 SM2 签名流程：

• 计算 ZA = SM3(ENTL ∥ ID ∥ a ∥ b ∥ xG ∥ yG ∥ xA ∥ yA)
• 计算 e = SM3(ZA ∥ m)
• 生成随机数 k，计算 (x₁, y₁) = [k]G
• 计算 s = ((1 + dₐ)⁻¹ × (k - e × dₐ)) mod n

标准引用：GM/T 0003.2-2012《SM2 密码算法使用规范》第 5.2 节定义签名算法细节。

int GM_T_VerifySignature(
    unsigned char *signature,
    unsigned long signatureLen,
    unsigned char *data,
    unsigned long dataLen,
    unsigned char *publicKey,
    unsigned long publicKeyLen
);

#### 3.3 SM3 杂凑接口

int GM_T_Digest(
    unsigned char *digest,       // 输出：256 位摘要
    unsigned long digestLen,     // 输出：摘要长度（应为 32）
    unsigned char *data,
    unsigned long dataLen
);

#### 3.4 SM4 加密/解密接口

int GM_T_Encrypt(
    unsigned char *ciphertext,
    unsigned long *ciphertextLen,
    unsigned char *plaintext,
    unsigned long plaintextLen,
    unsigned char *key,
    unsigned long keyLen,
    int mode,              // 工作模式（CBC/ECB/CTR）
    unsigned char *iv,     // 初始化向量（CBC 模式需要）
    unsigned long ivLen
);

int GM_T_Decrypt(
    unsigned char *plaintext,
    unsigned long *plaintextLen,
    unsigned char *ciphertext,
    unsigned long ciphertextLen,
    unsigned char *key,
    unsigned long keyLen,
    int mode,
    unsigned char *iv,
    unsigned long ivLen
);

数据结构定义

GM/T 0017-2023 定义了接口中使用的核心数据结构。

1. 算法标识（Algorithm ID）

说明：以下算法标识表参考 GM/T 0018-2023《密码设备应用接口规范》的标识体系。GM/T 0016-2023 与 GM/T 0018-2023 在算法标识上保持一致，两者共同构成国密密码设备接口的统一标识体系。

2. SM2 密钥对结构

typedef struct {
    unsigned char publicKey[64];   //  uncompressed point (x||y), 各 32 字节
    unsigned char privateKey[32];  //  私钥 d, 32 字节（若支持导出）
} GM_T_SM2_KeyPair;

3. SM2 签名结构

typedef struct {
    unsigned char r[32];
    unsigned char s[32];
} GM_T_SM2_Signature;

编码说明：GM/T 0010-2023 定义了 SM2 签名的 DER 编码格式，实际传输中应使用 r || s 拼接格式或 DER 编码格式。

与 GM/T 0018 的对比

国密合规应用要点

1. 密评检查项

在等保 2.0 和密评工作中，GM/T 0016 相关检查点包括：

2. 常见实现问题

问题一：SM2 签名 ZA 计算缺失

部分厂商实现跳过 ZA 计算直接使用原始数据签名，导致与非国密 SM2 实现不兼容。

排查方法：使用 gmssl 工具验证签名兼容性

BASH

复制

> # 生成测试密钥对
> openssl sm2 -genkey -out user.key
> # 使用标准库验证
> sm2sign -in test.txt -key user.key
>

根据 GM/T 0027-2014《智能密码钥匙技术规范》及行业实践，Level 3 及以上 USBKey 通常应具备：

• PIN 码长度 ≥ 6 位
• 错误尝试次数限制 ≤ 6 次
• 锁定后需 PUKE（个人解锁密钥）解锁

注意：具体参数以产品实际实现为准，不同厂商可能在安全等级评定中有差异化要求。

旧版 GM/T 0016-2012 与新版 2023 版本的算法标识存在差异，迁移时需注意：

• 2012 版仅支持 SM2/SM3/SM4
• 2023 版新增 SM9、ZUC 标识

3. 与其他标准的衔接

GM/T 0016（接口规范）
    ↓
GM/T 0006-2023（密码应用标识）
    ↓
X.509 证书（算法 OID 映射）

在构建国密 PKI 系统时，应确保：

• USBKey 中存储的证书算法 OID 与 GM/T 0006 定义一致
• 签名算法标识使用 sm2sign_with_sm3 OID（1.2.156.10197.1.501）
• 密钥交换使用 sm2keyexchange OID（1.2.156.10197.1.503）

工程实践建议

1. 接口选型

2. 开发注意事项

# Python 调用 GM/T 0016 接口的典型模式（伪代码）
import usbkey

# 1. 枚举设备
devices = usbkey.enumerate()
key = devices[0]

# 2. 登录（验证 PIN）
key.login(pin="123456")

# 3. SM2 签名
signature = key.sign(
    data=b"message to sign",
    algorithm=usbkey.ALG_SM2_SIGN
)

# 4. 注销
key.logout()

注意：实际开发中建议使用成熟的国密密码库（如 gmssl、Tongsuo）封装底层调用，避免直接操作 USBKey 驱动。

3. 测试验证清单

总结

GM/T 0016-2023 是国密 USBKey 密码应用的基础接口标准，与 GM/T 0018 共同构成国密密码设备的接口体系。理解该标准有助于：

• 正确选型：根据应用场景选择 GM/T 0016（客户端）还是 GM/T 0018（服务端）
• 合规实施：满足密评对密码设备接口的规范要求
• 互操作保障：确保不同厂商 USBKey 之间的兼容性

参考链接：

• GM/T 0016-2023 智能密码钥匙密码应用接口规范
• GM/T 0018-2023 密码设备应用接口规范
• GM/T 0017-2023 智能密码钥匙密码应用接口数据格式规范
• GM/T 0006-2023 密码应用标识规范
• GM/T 0027-2014 智能密码钥匙技术规范

• GM/T 0018-2023 密码设备应用接口规范 — 服务端密码设备接口
• GM/T 0019-2023 通用密码服务接口规范 — 上层密码服务抽象
• GM/T 0015-2023 数字证书格式 — 证书数据结构