GM/T 0018-2023 密码设备应用接口规范：国密密码设备互操作的统一语言

概述

GM/T 0018-2023《密码设备应用接口规范》是国密密码产品互联互通的基础性标准。它规定了公钥密码基础设施应用技术体系下，服务端密码设备的统一接口规范，涵盖算法标识、数据结构和接口函数三个核心要素。

该标准首次发布于2012年（GM/T 0018-2012），在2023年进行了全面修订。2023版在保留原有接口框架的基础上，大幅扩充了算法标识体系（新增SM9、ZUC、国密TLS密码套件等标识），重构了数据结构定义，并增强了与GB/T 33560-2026《网络安全技术 密码应用标识》的衔接。

标准定位与体系关系

GM/T 0018-2023 在国密标准体系中处于"承上启下"的位置——向上对接应用层密码服务接口（GM/T 0019），向下对接密码设备硬件接口（PKCS#11、CNG等）：

应用层          密码服务层          接口规范层          设备层
┌──────────┐   ┌──────────┐    ┌──────────┐    ┌──────────┐
│ GM/T 0019│   │ 应用API  │    │ GM/T 0018│    │ PKCS#11  │
│(密码服务  │──▶│(Java/C/  │───▶│(服务端   │───▶│(硬件密码  │
│ 接口规范) │   │ Python) │    │ 设备接口) │    │ 模块)    │
└──────────┘   └──────────┘    └──────────┘    └──────────┘

与相关标准的关系：

接口体系架构

1. 算法标识体系

GM/T 0018-2023 定义了完整的算法标识体系，每种密码算法都有一个唯一的标识符（algorithm identifier）。2023版相较2012版新增了数十种算法标识：

#### SM2算法标识

2. 数据结构定义

GM/T 0018-2023 定义了密码设备交互所需的所有数据结构，主要包括：

#### 密钥数据结构

密钥句柄结构：
┌─────────────────────────┐
│ 密钥类型 (UINT32)       │  ← SM2/SM3/SM4/SM9/ZUC
│ 密钥用途 (UINT32)       │  ← 签名/验签/加密/解密/密钥交换
│ 密钥长度 (UINT32)       │  ← 以比特为单位
│ 密钥数据 (BYTE[])       │  ← 密钥材料（加密存储）
│ 密钥标签 (CHAR[64])     │  ← 人类可读的密钥标识
└─────────────────────────┘

#### 会话数据结构

会话句柄结构：
┌─────────────────────────┐
│ 会话ID (UINT32)         │
│ 设备ID (UINT32)         │  ← 关联的密码设备
│ 加密算法 (UINT32)       │  ← 会话使用的加密算法
│ 签名算法 (UINT32)       │  ← 会话使用的签名算法
│ 随机数种子 (BYTE[32])   │  ← 会话随机数初始化
└─────────────────────────┘

#### 证书数据结构

证书数据结构：
┌─────────────────────────┐
│ 证书版本 (UINT32)       │
│ 序列号 (BYTE[20])       │
│ 签发算法 (UINT32)       │
│ 颁发者 (CHAR[128])      │
│ 有效期开始 (TIME)       │
│ 有效期结束 (TIME)       │
│ 主体 (CHAR[128])        │
│ 主体公钥 (PUBLIC_KEY)   │
│ 签名值 (SIGNATURE)      │
│ 证书数据 (BYTE[])       │  ← DER编码的完整证书
└─────────────────────────┘

3. 接口函数体系

GM/T 0018-2023 定义了约120个标准接口函数，按功能分为以下几大类：

#### 设备管理接口

2023版修订要点

1. 算法标识体系全面扩充

2023版新增了SM9标识密码、ZUC序列密码、国密TLS密码套件等算法的标识定义，使接口规范能够覆盖当前国密体系中的所有主流算法。

2. 与GB/T 33560-2026密码应用标识对齐

2023版将算法标识符与GB/T 33560-2026《网络安全技术 密码应用标识》中定义的OID和标识符进行了映射对齐，确保密码设备接口层与应用标识层的一致性。

3. 接口函数签名规范化

2023版将所有接口函数的参数类型统一为C语言标准类型（UINT32、BYTE、CHAR等），消除了2012版中部分函数使用自定义类型导致的编译器兼容性问题。

4. 新增错误码体系

2023版定义了完整的错误码体系，涵盖设备错误、密钥错误、签名错误、加密错误、权限错误等5大类共50余个具体错误码：

5. 增强异步操作支持

2023版新增了一组异步接口函数，支持密码设备的非阻塞操作：

与PKCS#11的对比分析

GM/T 0018-2023 的设计受到了PKCS#11（Cryptoki）标准的深刻影响，两者在接口设计理念上有诸多相似之处，但也存在关键差异：

互操作方案

在实际工程中，常常需要在GM/T 0018和PKCS#11之间进行互操作。常见的方案包括：

• 适配器模式：编写GM/T 0018到PKCS#11的适配层，将GM/T 0018的接口调用转换为PKCS#11 API调用
• 统一抽象层：在上层定义统一的密码服务接口（如GM/T 0019），底层同时支持GM/T 0018和PKCS#11
• 中间件方案：使用密码中间件（如国密密码服务网关）统一屏蔽底层接口差异

与GB/T 33560-2026密码应用标识的衔接

GB/T 33560-2026《网络安全技术 密码应用标识》规定了密码应用中各类密码服务类标识和安全管理类标识的唯一编码方式。GM/T 0018-2023 的算法标识体系与GB/T 33560-2026的标识编码存在以下对应关系：

实际集成要点

1. 密码设备发现与选择

在实际应用中，首先需要发现可用的密码设备：

// 【伪代码】示意性代码，非标准C实现。UINT32/HANDLE/DEVICE_INFO等为概念类型，
// 实际GM/T 0018接口头文件中定义的具体类型请参考标准附录。
// 获取可用密码设备数量
UINT32 device_count = GM_GetDeviceCount();

// 遍历设备并选择
for (UINT32 i = 0; i < device_count; i++) {
    DEVICE_INFO info;
    GM_GetDeviceInfo(i, &info);
    // 检查设备是否支持所需算法
    if (info.supported_algorithms & ALG_SM2) {
        // 打开选定的设备
        HANDLE h_device = GM_OpenDevice(i);
        break;
    }
}

2. 算法标识的动态映射

由于GM/T 0018-2023定义了较多的算法标识，实际应用中建议建立算法标识与OID/名称的双向映射表：

# 【伪代码】示意性映射表，实际实现需根据GM/T 0018-2023标准附录中的完整标识符列表填充
# 算法标识映射表示例
ALG_MAP = {
    0x0001: {"name": "SM2-SIGN", "oid": "1.2.156.10197.1.501"},
    0x0004: {"name": "SM2-ENCRYPT", "oid": "1.2.156.10197.1.503"},
    0x0101: {"name": "SM3", "oid": "1.2.156.10197.1.504"},
    0x0201: {"name": "SM4", "oid": "1.2.156.10197.1.502"},
    0x0301: {"name": "SM9-SIGN", "oid": "1.2.156.10197.1.601"},
}

3. 错误处理的健壮性

GM/T 0018-2023 的接口函数均返回错误码，实际应用中必须进行完整的错误处理：

// 【伪代码】示意性错误处理代码
HANDLE h_device = GM_OpenDevice(0);
if (h_device == INVALID_HANDLE) {
    UINT32 err = GM_GetLastError();
    switch (err) {
        case GM_E_DEVICE:
            // 设备未连接，尝试重新枚举
            break;
        case GM_E_PERMISSION:
            // 权限不足，提示用户输入PIN
            break;
        default:
            // 未知错误，记录日志
            break;
    }
}

参考来源

• GM/T 0018-2023《密码设备应用接口规范》，国家密码管理局
• GM/T 0019-2023《通用密码服务接口规范》，国家密码管理局
• GM/T 0020-2023《证书应用综合服务接口规范》，国家密码管理局
• GB/T 33560-2026《网络安全技术 密码应用标识》，国家市场监督管理总局
• GM/T 0006-2023《密码应用标识规范》，国家密码管理局
• PKCS #11 v3.0 Cryptographic Token Interface Standard, RSA Laboratories
• 国家密码管理局公告（第54号），2026年1月7日发布GM/T 0031-2025等20项标准