当前位置： 首页 > news >正文

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

news 2025/10/8 7:08:15

概述

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（仅当前用户可读写），否则工具会自动调整权限或报错。

示例

# 创建 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 定义的密钥同步标准结构，采用大端字节序，确保跨平台兼容，具体结构如下：

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：直接为密钥原始字节流

示例

# 接收同步密钥并启用严格验证 
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 公钥（默认导出完整密钥对或对称密钥）。

示例

#导出 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 协议要求服务端采用双证书模式（加密证书 + 签名证书），可通过以下步骤准备密钥：

# 生成 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校验和（用于完整性验证）。

# 设备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接收并验证密钥：先通过校验和验证同步文件完整性，再启用严格模式导入密钥至本地密钥库，确保密钥未被篡改且算法符合本地策略。

# 设备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)

  • 会话结束后清理密钥：通信完成后，双方设备执行硬删除操作移除临时会话密钥，避免密钥长期留存带来的安全隐患。

# 设备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根路径下执行以下命令：

mkdir build
cd build
cmake ..
make && make install
http://www.dtcms.com/a/453511.html

相关文章：

  • 网站上线倒计时html5模板企业培训机构有哪些
  • 中型规模生产架构部署详细步骤
  • 如何加强英文网站建设重庆网站建设的公司哪家好
  • 逆向分析文档：基于 app.endata.com.cn 票房数据接口的加密与解密流程
  • 为什么做腾讯网站如何压缩网站
  • 吴恩达机器学习课程（PyTorch适配）学习笔记：1.1 基础模型与数学原理
  • 【全志V821_FoxPi】6-1 MIPI协议与MIPI摄像头
  • 【防火墙源码】WordPress防火墙插件1.0测试版
  • 全国美容网站建设房源信息网
  • CentOS 7 环境下 MySQL 5.7 深度指南：从安装、配置到基础 SQL 操作
  • ⚡ arm 32位嵌入式 Linux 系统移植 NTP 服务
  • 抖音,小红书等自媒体平台多开账号如何操作不违规
  • [Java]PTA: jmu-Java-03面向对象基础-Object
  • 【大模型实战篇】基于xiaohongshu-mcp实现对话模式的小红书笔记操作
  • LangChain详解（一）
  • 门户网站建设需求wordpress云主机
  • 【OpenArm|Control】openarm机械臂ROS2仿真控制
  • 网站开发小组百度网页制作网站建设
  • 中小型项目组织架构和职能说明
  • wordpress发表文章更新失败网站标题优化工具
  • C++网络编程（五）socket编程---从socket()到connect()
  • 23-25年总结：23年因为大模型而转型科技，24年起发力具身，25年长沙具身开始一轮轮突飞猛进
  • AI智能体（Agent）大模型入门【7】--构建传统的RAG应用
  • 淮阴区建设局网站网站备案变更公司名称
  • Bittensor 中国巡回 Meetup｜上海站
  • S11e Network 商业模型：AI × Web3 × RWA 驱动的实体经济新范式
  • 人脸跟随 （ Channel 实现（缓存5条数据 + 2度过滤 + 平滑移动））
  • 线性表——数组描述
  • 帮客户做网站 没签合同咋办重视网站阵地建设
  • Raven2