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

openHiTLS密码开源社区2025-10-09 12:18

概述

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

安全特性说明

  1. 内存安全擦除 所有临时密钥缓冲区（如私钥、对称密钥、口令）在使用后均通过 BSL_SAL_CleanseData() 函数进行多轮覆写（默认采用 0x00、0xFF、随机数三轮覆写），防止密钥信息通过内存dump泄露。

  2. 参数合法性校验 严格校验输入参数：UUID 不可为空且符合命名规范；算法 ID 必须为预定义国密算法；PBKDF2 迭代次数与盐长不低于安全下限；密钥长度符合国密标准（如 SM4 固定 128 位）。

  3. 算法一致性检查 在 receive 操作时，自动校验同步数据中的算法与本地策略（可通过配置文件 /etc/hitls/keymgmt.conf 设置）是否一致，若本地禁用某算法则拒绝导入。

  4. 密钥存储加密 本地密钥默认采用 AES-256-GCM 加密存储，加密密钥由用户口令通过 PBKDF2 算法派生（结合随机盐值），确保即使密钥文件被窃取也无法直接获取原始密钥。

  5. 访问权限控制 密钥文件默认权限为 0600（仅当前用户可读写），密钥库目录权限为 0700（仅当前用户可进入），工具启动时会自动检查并修复权限，防止未授权用户访问。

  6. 操作日志审计 所有密钥操作（创建、导出、删除等）均记录详细日志，包括操作时间、操作类型、UUID、操作用户、客户端IP等信息，日志路径默认为 /var/log/hitls/keymgmt.log，支持集成到第三方审计系统。

  7. 错误码体系 所有失败操作返回标准化错误码，便于问题定位，常见错误码及说明如下： 错误码说明解决方案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、下载相关代码

2、构建安装，在openHiTLS根路径下执行以下命令：

cpp 复制代码 
mkdir build
cd build
cmake ..
make && make install
相关推荐
openHiTLS密码开源社区14 小时前
【密码学实战】openHiTLS kdf命令行：密钥派生工具
暴力破解·sm3·密钥派生·kdf·商用密码·密码算法·彩虹表
openHiTLS密码开源社区1 天前
【密码学实战】openHiTLS genrsa命令行：RSA私钥生成专属工具
aes·rsa·sm2·私钥·sm4·密钥轮换
openHiTLS密码开源社区4 天前
【密码学实战】openHiTLS enc命令行：数据加解密
aes·sm4·数据加解密·大文件加密·网络流加密
qqxhb25 天前
系统架构设计师备考第20天——信息加解密技术&密钥管理技术
系统架构·des·aes·加解密·rsa·密钥管理·kdc
mashanshui1 个月前
Https之(四)国密GMTLS
https·gmssl·tlcp·gmtls·国密https
openHiTLS密码开源社区2 个月前
【密码学实战】国密TLCP协议简介及代码实现示例
密码学·国密·sm2·sm3·sm4·openhitls·tlcp
WAZYY06192 个月前
处理jdk21版本及No such algorithm: SM4/ECB/PKCS5Padding jar包冲突问题
java·jar·jdk21·sm4
gavin carter4 个月前
iOS-SM3加密算法N种集成
ios·sm3
胡耀超5 个月前
对称加密算法（AES、ChaCha20和SM4）Python实现——密码学基础(Python出现No module named “Crypto” 解决方案)
开发语言·python·密码学·数据安全·aes·sm4·chacha
热门推荐
01两千字总结：Codex 国内如何安装和使用的教程，以及如何设置中文回答02GitHub 镜像站点03UV安装并设置国内源04KGG转MP3工具|非KGM文件|解密音频05DeepSeek-VL 解析：混合视觉-语言模型如何超越传统计算机视觉方法06Linux下V2Ray安装配置指南07jdk21下载、安装（Windows、Linux、macOS）08一文了解国产算子编程语言 TileLang，TileLang 对国产开源生态的影响与启示09Claude Code & 智谱GLM-4.5 环境配置指南 (Windows/macOS/Ubuntu)1046个Nano-banana 精选提示词，持续更新中