【密码学实战】openHiTLS keymgmt命令行：密钥管理工具

概述

hitls keymgmt是 openHiTLS提供的密钥管理命令行工具，为商用密码算法（SM2/SM4/SM3）环境设计，用于密钥的创建、导出、接收、同步与安全存储。该工具深度贴合国密标准体系，严格遵循《GM/T 0024-2014 信息安全技术公钥密码基础设施密钥管理规范》等相关标准，支持在 TLCP（Transport Layer Cryptography Protocol，国密 TLS 协议）场景下，对本地或远程密钥进行全生命周期管理，适用于安全通信、密钥分发、设备配对、云端密钥同步等典型国密应用场景。

与 openHiTLS genpkey、genrsa等命令不同，hitls keymgmt 更强调密钥的同步性、安全封装与 UUID 标识体系 ，其核心设计理念是"密钥即资源，以 UUID 唯一标识，支持跨节点安全同步"。相较于传统工具，它具备更强的国密算法适配性、更完善的密钥生命周期管控能力，以及与 openHiTLS 协议栈的无缝集成特性。

命令语法

hitls keymgmt <command> [options] [--help]

其中 <command> 可为以下子命令之一：

create：创建新密钥（支持 SM2/SM4/HMAC-SM3 等算法）
receive：接收并存储远程同步的密钥
list：列出本地已存储密钥及关键属性
export：导出密钥为标准或同步格式（用于调试、迁移或跨设备传输）
delete：删除本地指定 UUID 的密钥（新增子命令）
info：查询指定 UUID 密钥的详细信息（新增子命令）

子命令详解

1. `create` ------ 创建密钥

用于在本地生成新的 SM2 非对称密钥对、SM4 对称密钥或 HMAC-SM3 密钥，并以指定 UUID 关联存储。生成过程中会对密钥进行安全加固，确保符合国密算法密钥生成规范。

基本用法

hitls keymgmt create -a <alg> -u <uuid> [options]

必选参数

选项	说明
`-a, --alg <alg>`	指定算法类型，支持：• `sm2`：SM2 非对称密钥对（256 位，符合 GM/T 0003-2012）• `sm4-cbc` / `sm4-ctr` / `sm4-gcm`：SM4 对称密钥（128 位，对应不同模式）• `hmac-sm3`：SM3-HMAC 密钥（推荐长度 ≥ 32 字节）
`-u, --uuid <uuid>`	为密钥分配唯一标识符（UUID），用于后续引用或同步。格式为字符串，支持字母、数字、下划线，长度建议 8-64 字符，如 `sm2_server_cert_001`、`sm4_session_20251007`。

可选参数

选项	说明
`-i, --iter <num>`	PBKDF2 迭代次数（仅对加密存储有效）。默认为 20000 次，必须 ≥ `APP_KEYMGMT_PBKDF2_IT_CNT_MIN`（当前定义为 10000），数值越大密钥加密强度越高，但生成时间更长。
`-s, --salt-len <len>`	盐值长度（字节）。默认为 16 字节，必须 ≥ `APP_KEYMGMT_PBKDF2_SALT_LEN_MIN`（当前定义为 8 字节），建议使用 16-32 字节以增强抗彩虹表攻击能力。
`-p, --passphrase <file>`	指定口令文件路径（用于加密密钥文件）。文件内容为单行字符串，建议长度 ≥ 16 字符并包含大小写字母、数字及特殊符号。v1.3.0 及以上版本已正式启用该功能。
`-o, --output <dir>`	指定密钥存储目录（默认路径为 `~/.hitls/keys/`）。需确保目录权限为 0700（仅当前用户可读写），否则工具会自动调整权限或报错。

示例

cpp 复制代码

# 创建 SM2 密钥对（用于服务器证书），UUID 为 sm2_server_2025 
hitls keymgmt create -a sm2 -u sm2_server_2025 -o /var/hitls/keys 
# 创建 SM4-GCM 对称密钥（会话密钥），指定迭代次数、盐长和口令文件 
hitls keymgmt create -a sm4-gcm -u sm4_session_001 -i 30000 -s 24 -p /etc/hitls/passwd.txt 
# 创建 HMAC-SM3 密钥（用于消息认证） 
hitls keymgmt create -a hmac-sm3 -u hmac_sm3_key_01

成功后，工具会输出生成结果（如 "Key created successfully. UUID: sm2_server_2025"），并将密钥以加密格式存储（默认采用 AES-256-GCM 加密 PKCS#12 容器）。密钥文件命名格式为 <uuid>.key，如 sm2_server_2025.key。

2. `receive` ------ 接收同步密钥

用于接收来自远程节点的密钥同步数据（通常通过 TLCP 协议或安全文件传输），并验证数据完整性后安全写入本地密钥库。支持对同步数据进行版本校验、算法一致性检查和权限控制。

基本用法

hitls keymgmt receive -d <sync_data_file> [options]

必选参数

选项	说明
`-d, --data <file>`	指向包含 `HITLS_SyncKeyInfo` 结构的二进制文件。该文件由对端通过 `hitls keymgmt export` 或 openHiTLS 协议栈自动导出生成，文件权限建议设置为 0600。

可选参数

选项	说明
`-f, --force`	强制覆盖已存在的同 UUID 密钥（默认行为为拒绝覆盖并提示用户，避免误操作导致密钥丢失）。
`-v, --verify`	启用严格验证模式，包括：同步数据版本号校验（需匹配本地工具版本）、算法 ID 合法性校验、密钥长度合规性校验等，校验失败则拒绝导入。
`-k, --checksum <file>`	指定校验和文件路径，用于验证同步数据文件的完整性（文件内容为 SM3 哈希值，格式为 `<hash> <filename>`）。

同步数据格式说明

HITLS_SyncKeyInfo 是 HITLS 定义的密钥同步标准结构，采用大端字节序，确保跨平台兼容，具体结构如下：

cpp 复制代码

typedef struct
 { uint32_t version; 
// 版本号（APP_KEYMGMT_SYNC_DATA_VERSION） uint32_t alg_id;
 // 算法标识（如 CRYPT_PKEY_SM2、CRYPT_CIPHER_SM4_GCM） 
uint8_t uuid_len; // UUID 长度（字节） char uuid[64]; 
// 密钥 UUID uint32_t key_len; 
// 密钥体长度（字节） uint8_t key_body[]; 
// 序列化密钥体 uint32_t checksum_len; 
// 校验和长度（字节，固定为 32，SM3 哈希） uint8_t checksum[32]; 
// 密钥体 + UUID 的 SM3 校验和 
} HITLS_SyncKeyInfo;

其中密钥体序列化规则：

SM2 ：[pubLen(4B)][publicKey][prvLen(4B)][privateKey]（公钥/私钥均为 raw 格式）
SM4/HMAC-SM3：直接为密钥原始字节流

示例

cpp 复制代码

# 接收同步密钥并启用严格验证 
hitls keymgmt receive -d /tmp/sync_key.bin -v 
# 强制覆盖已存在的密钥，并验证同步文件完整性 
hitls keymgmt receive -d /tmp/sync_key_v2.bin -f -k /tmp/sync_key.sm3

3. `list` ------ 列出本地密钥

用于查询本地密钥库中已存储的所有密钥，输出 UUID、算法类型、创建时间、密钥状态等关键信息，便于用户快速了解密钥库存情况。

基本用法

hitls keymgmt list [options]

可选参数

选项	说明
`-a, --alg <alg>`	按算法类型过滤结果，如仅列出 SM2 密钥：`hitls keymgmt list -a sm2`。
`-l, --long`	输出详细信息，包括密钥存储路径、加密状态、最后访问时间等。
`-o, --output <file>`	将结果导出为 CSV 文件，便于后续分析或存档：`hitls keymgmt list -o key_list.csv`。

示例

# 列出所有本地密钥 hitls keymgmt list # 列出 SM4 类型密钥的详细信息 hitls keymgmt list -a sm4 -l # 导出所有密钥列表到 CSV 文件 hitls keymgmt list -o /tmp/hitls_key_inventory.csv

普通模式输出示例：

UUID Alg Created Time Status sm2_server_2025 sm2 2025-10-01 09:30:00 Valid sm4_session_001 sm4-gcm 2025-10-07 14:15:22 Valid hmac_sm3_key_01 hmac-sm3 2025-10-05 11:20:33 Valid

4. `export` ------ 导出密钥

用于将本地存储的密钥导出为标准格式（如 PEM、DER）或 HITLS 同步格式（HITLS_SyncKeyInfo），支持对导出密钥进行加密保护，适用于密钥迁移、调试或跨节点同步场景。

基本用法

hitls keymgmt export -u <uuid> -t <type> -o <file> [options]

必选参数

选项	说明
`-u, --uuid <uuid>`	指定待导出密钥的 UUID。
`-t, --type <type>`	导出格式类型：• `sync`：HITLS 同步格式（二进制，用于 `receive` 子命令）• `pem`：PEM 格式（文本，SM2 私钥为 PKCS#8 格式，公钥为 SubjectPublicKeyInfo 格式）• `der`：DER 格式（二进制，与 PEM 对应）
`-o, --output <file>`	导出文件路径。

可选参数

选项	说明
`-p, --passphrase <file>`	指定口令文件，用于加密导出的 PEM/DER 格式密钥（SM2 私钥导出时必填，否则工具会提示输入口令）。
`-pub`	仅导出 SM2 公钥（默认导出完整密钥对或对称密钥）。

示例

cpp 复制代码

#导出 SM2 密钥为同步格式（用于传输给其他节点） 
hitls keymgmt export -u sm2_server_2025 -t sync -o /tmp/sync_sm2_key.bin 
# 导出 SM2 公钥为 PEM 格式 hitls keymgmt export -u sm2_server_2025 -t pem -o sm2_server_pub.pem -pub 
# 导出 SM4 密钥为加密 PEM 格式 
hitls keymgmt export -u sm4_session_001 -t pem -o sm4_session.pem -p /etc/hitls/passwd.txt

5. `delete` ------ 删除密钥

用于删除本地密钥库中指定 UUID 的密钥，支持"软删除"（仅标记删除状态）和"硬删除"（彻底删除文件）两种模式，防止误删除导致的数据丢失。

基本用法

hitls keymgmt delete -u <uuid> [options]

必选参数

选项	说明
`-u, --uuid <uuid>`	指定待删除密钥的 UUID。

可选参数

选项	说明
`-f, --force`	执行硬删除，彻底删除密钥文件（默认行为为软删除，密钥文件仍存在但标记为"Deleted"状态，可通过工具恢复）。
`-c, --confirm`	删除前需要用户手动确认（防止脚本误操作）。

示例

# 软删除指定 UUID 的密钥 hitls keymgmt delete -u sm4_session_001 # 硬删除密钥并要求确认 hitls keymgmt delete -u hmac_sm3_key_01 -f -c

6. `info` ------ 查询密钥详情

用于查看指定 UUID 密钥的详细属性信息，包括算法参数、存储信息、安全状态等，帮助用户深入了解密钥的具体配置。

基本用法

hitls keymgmt info -u <uuid>

必选参数

选项	说明
`-u, --uuid <uuid>`	指定待查询密钥的 UUID。

示例

hitls keymgmt info -u sm2_server_2025

输出示例：

Key Info: UUID: sm2_server_2025 Algorithm: sm2 (CRYPT_PKEY_SM2) Key Type: Asymmetric Key Pair Public Key: 047a12... (512 bits) Private Key: Encrypted (AES-256-GCM) Storage Path: /var/hitls/keys/sm2_server_2025.key Created Time: 2025-10-01 09:30:00 Last Access: 2025-10-07 10:15:44 Status: Valid Encryption: Enabled (PBKDF2 iter: 20000, salt len: 16B) Version: 1.2.0

安全特性说明

内存安全擦除 所有临时密钥缓冲区（如私钥、对称密钥、口令）在使用后均通过 BSL_SAL_CleanseData() 函数进行多轮覆写（默认采用 0x00、0xFF、随机数三轮覆写），防止密钥信息通过内存dump泄露。
参数合法性校验 严格校验输入参数：UUID 不可为空且符合命名规范；算法 ID 必须为预定义国密算法；PBKDF2 迭代次数与盐长不低于安全下限；密钥长度符合国密标准（如 SM4 固定 128 位）。
算法一致性检查 在 receive 操作时，自动校验同步数据中的算法与本地策略（可通过配置文件 /etc/hitls/keymgmt.conf 设置）是否一致，若本地禁用某算法则拒绝导入。
密钥存储加密 本地密钥默认采用 AES-256-GCM 加密存储，加密密钥由用户口令通过 PBKDF2 算法派生（结合随机盐值），确保即使密钥文件被窃取也无法直接获取原始密钥。
访问权限控制 密钥文件默认权限为 0600（仅当前用户可读写），密钥库目录权限为 0700（仅当前用户可进入），工具启动时会自动检查并修复权限，防止未授权用户访问。
操作日志审计 所有密钥操作（创建、导出、删除等）均记录详细日志，包括操作时间、操作类型、UUID、操作用户、客户端IP等信息，日志路径默认为 /var/log/hitls/keymgmt.log，支持集成到第三方审计系统。
错误码体系 所有失败操作返回标准化错误码，便于问题定位，常见错误码及说明如下：错误码说明解决方案HITLS_APP_OPT_VALUE_INVALID参数值无效（如迭代次数小于最小值）检查参数值是否符合要求，参考子命令参数说明HITLS_APP_KEY_EXIST指定 UUID 密钥已存在更换 UUID 或使用 -f 选项强制覆盖HITLS_APP_KEY_NOT_FOUND未找到指定 UUID 密钥使用 list 子命令确认 UUID 是否正确HITLS_APP_CHECKSUM_MISMATCH同步数据校验和不匹配重新获取同步文件，检查文件完整性

典型应用场景

场景 1：TLCP 服务端双证书部署

国密 TLCP 协议要求服务端采用双证书模式（加密证书 + 签名证书），可通过以下步骤准备密钥：

cpp 复制代码

# 生成 SM2 加密密钥对 
hitls keymgmt create -a sm2 -u tlcp_enc_key -i 25000 -s 20 -o /etc/hitls/keys 
# 生成 SM2 签名密钥对 
hitls keymgmt create -a sm2 -u tlcp_sign_key -i 25000 -s 20 -o /etc/hitls/keys 
# 查看生成的密钥 
hitls keymgmt list -a sm2

随后在 openHiTLS 服务端配置文件中指定：

[tls] protocol = tlcp

enc_key_uuid = tlcp_enc_key

sign_key_uuid = tlcp_sign_key

cert_path = /etc/hitls/certs/server_cert.pem

场景 2：设备间安全会话密钥同步

在物联网设备集群、分布式系统等场景中，设备间需建立安全通信通道，临时会话密钥的同步是核心环节。通过 hitls keymgmt 可实现密钥的安全生成、传输与导入，确保数据传输机密性，具体步骤如下：

设备A生成会话密钥：创建SM4-GCM对称密钥（会话密钥建议设置短期有效期，如24小时，降低泄露风险），并导出为HITLS同步格式及生成SM3校验和（用于完整性验证）。

cpp 复制代码

# 设备A：生成SM4-GCM会话密钥（指定迭代次数和盐长） 
hitls keymgmt create -a sm4-gcm -u iot_session_20251007 -i 20000 -s 16 
# 设备A：导出密钥为同步格式（供其他设备接收） 
hitls keymgmt export -u iot_session_20251007 -t sync -o /tmp/iot_session.bin 
# 设备A：生成同步文件的SM3校验和 
hitls hash -a sm3 /tmp/iot_session.bin > /tmp/iot_session.sm3

安全传输密钥文件 ：通过TLCP协议（国密TLS）或加密文件传输工具（如SFTP结合SM2非对称加密）将 /tmp/iot_session.bin 和 /tmp/iot_session.sm3 传输至设备B。严禁通过HTTP、FTP等未加密协议传输密钥文件，避免传输过程中被窃取。
设备B接收并验证密钥：先通过校验和验证同步文件完整性，再启用严格模式导入密钥至本地密钥库，确保密钥未被篡改且算法符合本地策略。

cpp 复制代码

# 设备B：验证同步文件完整性（匹配SM3校验和）
hitls hash -a sm3 -c /tmp/iot_session.sm3 /tmp/iot_session.bin 
# 设备B：接收并存储会话密钥（启用版本、算法一致性校验） 
hitls keymgmt receive -d /tmp/iot_session.bin -v

确认密钥可用性 ：设备B查询密钥详情，核对UUID、算法类型、状态等信息，确保导入成功。 # 设备B：查看会话密钥详细信息 ``hitls keymgmt info -u iot_session_20251007成功输出示例： Key Info: ``UUID: iot_session_20251007 ``Algorithm: sm4-gcm (CRYPT_CIPHER_SM4_GCM) ``Key Type: Symmetric Key ``Key Length: 128 bits ``Storage Path: /home/user/.hitls/keys/iot_session_20251007.key ``Created Time: 2025-10-07 15:30:00 ``Last Access: 2025-10-07 15:35:22 ``Status: Valid ``Encryption: Enabled (PBKDF2 iter: 20000, salt len: 16B)
会话结束后清理密钥：通信完成后，双方设备执行硬删除操作移除临时会话密钥，避免密钥长期留存带来的安全隐患。

cpp 复制代码

# 设备A/B：硬删除临时会话密钥（需手动确认） 
hitls keymgmt delete -u iot_session_20251007 -f -c

关键安全要点：会话密钥采用SM4-GCM模式，同时提供机密性和完整性保护；传输过程结合校验和与加密通道，双重保障密钥安全；短期有效期+主动删除机制，降低密钥泄露后的影响范围。

免费下载openHiTLS

1、下载相关代码

openHiTLS下载地址：https://gitcode.com/openhitls

libboundscheck下载地址：https://gitee.com/openeuler/libboundscheck.git 说明：需要将libboundscheck下载至openHiTLS/platform/Secure_C目录

2、构建安装，在openHiTLS根路径下执行以下命令：
cpp 复制代码
mkdir build
cd build
cmake ..
make && make install

【密码学实战】openHiTLS keymgmt命令行：密钥管理工具

概述

命令语法

子命令详解

1. create ------ 创建密钥

基本用法

必选参数

可选参数

示例

2. receive ------ 接收同步密钥

基本用法

必选参数

可选参数

同步数据格式说明

示例

3. list ------ 列出本地密钥

基本用法

可选参数

示例

4. export ------ 导出密钥

基本用法

必选参数

可选参数

示例

5. delete ------ 删除密钥

基本用法

必选参数

可选参数

示例

6. info ------ 查询密钥详情

基本用法

必选参数

示例

安全特性说明

典型应用场景

场景 1：TLCP 服务端双证书部署

场景 2：设备间安全会话密钥同步

免费下载openHiTLS

1. `create` ------ 创建密钥

2. `receive` ------ 接收同步密钥

3. `list` ------ 列出本地密钥

4. `export` ------ 导出密钥

5. `delete` ------ 删除密钥

6. `info` ------ 查询密钥详情