hitls genrsa 是 openHiTLS 加密工具集的核心子命令，专门用于生成 RSA 非对称密钥对 （私钥为主，公钥内嵌于私钥文件）。所有功能围绕 "合规性" 与 "安全性" 设计，需通过 hitls 主程序调用，以下为精简实用的完整指南
一、工具核心概述
1. 定位与核心能力
**hitls genrsa**不是独立工具，而是 openHiTLS 工具集的 "密钥生成模块"，核心能力聚焦两点：
- 生成指定长度的 RSA 密钥对（仅支持 1024/2048/3072/4096 位）；
- 用对称算法 + 密码加密私钥（仅输出 PKCS8 加密 PEM 格式，不支持裸私钥）。
二、基本语法
1. 完整命令格式
cpp
hitls genrsa [选项] <RSA密钥长度> # 密钥长度必须在最后，选项顺序可调整2. 命令构成说明
| 组成部分 | 作用 | 示例值 |
|---|---|---|
hitls |
主程序入口（固定） | 无 |
genrsa |
子命令（固定） | 无 |
[选项] |
配置项（如输出路径） | --cipher sm4-cbc |
<密钥长度> |
必填尾部参数 | 2048/4096 |
3. 语法注意事项
- 选项区分大小写：仅支持小写（如
--help而非--Help），大写会报 "未知选项"； - 空格分隔：选项与值之间必须用空格（如
--cipher aes128-cbc不可写--cipher=aes128-cbc）； - 路径格式：Windows 下支持
./keys/priv.pem或.\keys\priv.pem，Linux 仅支持/分隔。
三、选项详细说明
hitls genrsa 仅支持 3 个核心选项，无隐藏功能，以下为完整说明：
| 选项名 | 数据类型 | 功能说明 | 是否必填 | 关键使用注意点 |
|---|---|---|---|---|
--help |
无参数 | 输出帮助信息（含支持的算法、密钥长度），执行后退出，不生成密钥。 | 否 | 首次使用建议先执行 hitls genrsa --help，确认本地工具参数与文档一致。 |
--cipher |
字符串（算法名） | 指定加密私钥的对称算法，需从预设列表选择）。 | 是 | 1. 国密场景选 sm4-cbc/sm4-xts；2. 跨平台场景选 aes256-cbc/aes128-cbc；3. 输入错误会自动打印支持列表。 |
--out |
字符串（文件路径） | 指定私钥输出路径，默认输出到终端（stdout）。 | 否 | 1. 路径长度≤4096 字符（超长报错）；2. 已存在文件会直接覆盖（需提前备份）；3. 父目录需有写入权限（否则报 "Failed to set outfile mode"）。 |
四、关键参数范围（必看）
1. 支持的对称加密算法（--cipher 可选值）
工具仅支持 15 种算法，分 AES 与 SM4 系列，按场景分类如下：
| 算法系列 | 支持的完整算法名 | 适用场景 |
|---|---|---|
| AES 系列 | aes128-cbc、aes192-cbc、aes256-cbc | 跨平台兼容（如 Linux/Windows 交互） |
| AES 系列 | aes128-cfb、aes192-cfb、aes256-cfb | 低延迟场景（如实时加密） |
| AES 系列 | aes128-ofb、aes192-ofb、aes256-ofb | 抗 IV 重用风险 |
| AES 系列 | aes128-xts、aes256-xts | 块设备存储（如 SSD 私钥文件） |
| SM4 系列 | sm4-cbc、sm4-cfb、sm4-ofb、sm4-xts | 国密合规场景（政务、金融） |
2. RSA 密钥长度选择指南（尾部参数）
密钥长度直接影响安全与性能，仅支持 4 个固定值，场景适配如下：
| 支持长度 | 安全级别 | 性能消耗（相对值） | 推荐场景 | 不推荐场景 |
|---|---|---|---|---|
| 1024 | 弱安全（仅测试用） | 1x（最快） | 功能验证、临时演示环境 | 生产环境、敏感数据加密 |
| 2048 | 中安全（NIST 推荐至 2030） | 3x（较慢） | 常规生产（Web 服务 HTTPS、API 签名） | 超高安全需求（如金融核心交易） |
| 3072 | 高安全（NIST 推荐至 2050） | 8x（慢） | 敏感场景（金融转账、政务数据） | 高并发场景（如秒杀活动） |
| 4096 | 极高安全（抗量子潜力） | 20x（最慢） | 核心密钥（CA 根证书、KMS 系统） | 资源受限设备（嵌入式终端） |
3. 密码隐性规则
工具通过 HITLS_APP_CheckPasswd 校验密码，不满足会报错退出，规则如下：
- 长度：≥8 位（最大 64 位）；
- 复杂度：至少含 2 种字符类型（如字母 + 数字、字母 + 特殊符号）；
- 输入方式：终端隐藏输入（不显示字符，避免偷窥）。
五、典型使用示例（可直接复制）
以下示例覆盖 "测试、生产、合规、管道传递" 四大核心场景，复制后可直接执行。
示例 1：测试场景（1024 位密钥，临时文件）
场景：验证工具可用性，生成临时测试私钥，用完可删除。
cpp
# 1. 创建临时目录（避免污染当前目录）
mkdir -p ./tmp_test && cd ./tmp_test
# 2. 生成 1024 位私钥，aes128-cbc 加密，输出到 test_rsa.pem
hitls genrsa --cipher aes128-cbc --out test_rsa.pem 1024
# 3. 输入密码（示例：Test@1234，按提示输入）
# 4. 验证生成结果（查看文件是否存在）
ls -l test_rsa.pem
# 5. 测试完成后清理（可选）
cd .. && rm -rf ./tmp_test示例 2：生产场景（2048 位密钥，安全存储）
场景：为 Web 服务生成 HTTPS 私钥，存储到专用目录并控制权限。
cpp
# 1. 创建密钥专用目录（权限 700，仅所有者可访问）
mkdir -p /etc/hitls/keys && chmod 700 /etc/hitls/keys
# 2. 生成 2048 位私钥，aes256-cbc 加密，输出到安全路径
hitls genrsa --cipher aes256-cbc --out /etc/hitls/keys/web_rsa.pem 2048
# 3. 输入高强度密码（示例：WebRsa@2024!，建议存密码管理器）
# 4. 设置私钥权限（600，仅所有者可读写）
chmod 600 /etc/hitls/keys/web_rsa.pem
# 5. 验证权限与格式
ls -l /etc/hitls/keys/web_rsa.pem # 应显示 -rw-------
file /etc/hitls/keys/web_rsa.pem # 应显示"PEM encrypted private key"示例 3：国密合规场景（3072 位密钥，SM4 加密）
场景：政务系统生成符合国密标准的私钥，用于电子公文加密。
cpp
# 1. 创建合规目录（如 /opt/gov_secure，需提前授权）
mkdir -p /opt/gov_secure && chmod 700 /opt/gov_secure
# 2. 生成 3072 位私钥，sm4-cbc 加密，输出到合规路径
hitls genrsa --cipher sm4-cbc --out /opt/gov_secure/rsa_gov.pem 3072
# 3. 输入密码（需符合政务规范，如长度≥12位：GovRsa@2024!#）
# 4. 验证算法合规性（后续可提取公钥用于公文加密）
hitls rsa -in /opt/gov_secure/rsa_gov.pem -pubout -out /opt/gov_secure/rsa_gov_pub.pem示例 4：管道传递（不落地存储私钥）
场景：生成私钥后直接提取公钥，避免私钥文件落地，提升安全性。
cpp
# 生成 2048 位私钥（输出到 stdout），管道传递给 hitls rsa 提取公钥
hitls genrsa --cipher aes128-cbc 2048 | hitls rsa -pubout --out rsa_pub.pem
# 输入私钥密码（用于解密私钥以提取公钥）
# 验证公钥（查看公钥格式）
cat rsa_pub.pem # 应显示"-----BEGIN PUBLIC KEY-----"六、常见错误与排查（快速解决）
- 命令路径错误：
genrsa: command not found
- 原因 ：未加
hitls前缀，或hitls未安装 / 未在 PATH 中。 - 解决 ：
- 确认命令格式：必须写
hitls genrsa，而非单独genrsa； - 检查
hitls安装：执行which hitls，无输出则重新安装 openHiTLS。
- 确认命令格式：必须写
2. 密钥长度错误：The RSA key length is error...
- 原因：尾部参数不在 1024/2048/3072/4096 范围内（如输入 1536）。
- 解决 ：
- 修正尾部参数为 4 个支持值之一；
- 执行
hitls genrsa --help确认支持的长度列表。
3. 文件 IO 错误：Failed to set outfile mode.
- 原因：路径不存在、无写入权限或磁盘空间不足。
- 解决 ：
- 检查路径是否存在：如
ls -d /opt/keys，不存在则执行mkdir -p /opt/keys； - 检查权限：如
ls -ld /opt/keys，确保当前用户有w权限（可临时加权限：chmod +w /opt/keys）； - 检查磁盘空间：执行
df -h，确保剩余空间≥10KB（私钥文件很小）。
- 检查路径是否存在：如
4. 加密模块错误：Encode failed.
- 原因：系统熵源不足（随机数生成失败）。
- 解决 ：
- 检查熵源：执行
cat /proc/sys/kernel/random/entropy_avail，值＜100 需补充； - 临时补充熵源：执行
cat /dev/urandom > /dev/random &（后台运行，不影响其他操作）； - 永久补充：安装
rng-tools（CentOS：yum install rng-tools；Ubuntu：apt install rng-tools），安装后启动服务：systemctl start rngd。
- 检查熵源：执行
5. 密码错误：password error
- 原因 ：密码长度＜8 位或复杂度不足（未通过
HITLS_APP_CheckPasswd校验）。 - 解决 ：
- 确保密码长度≥8 位；
- 增加复杂度：如
RsaPass@2024（字母 + 数字 + 特殊符号）； - 重新输入时避免空格或不可见字符。
七、安全最佳实践（精简版）
1. 私钥存储与备份
- 密码单独存：加密私钥的密码不要与私钥文件存在同一位置，建议用硬件密码管理器存储；
- 加密备份：私钥备份时需加密（如
zip -e rsa_backup.zip rsa.pem），备份至少 2 份，存不同物理位置； - 权限控制：私钥文件权限固定为 600（
chmod 600 rsa.pem），目录权限固定为 700（chmod 700 /etc/hitls/keys）。
2. 密钥生命周期管理
- 定期轮换：生产环境私钥每 1-2 年轮换一次（用
hitls genrsa生成新密钥，替换旧密钥后销毁旧密钥）； - 安全销毁：旧私钥用
shred -u rsa_old.pem彻底删除（多次覆盖内容，防止恢复），备份介质同步销毁。
3. 性能优化（针对 3072/4096 位密钥）
- 提前补熵：生成高长度密钥前，先执行
rngd -r /dev/urandom填充熵源，缩短生成时间； - 错峰执行：3072/4096 位密钥生成耗 CPU（持续 3-20 秒），建议在系统低负载时段（如凌晨）执行。
八、常用关联命令（后续操作）
生成私钥后，常用 openHiTLS 命令如下，可直接复制使用：
| 需求 | 关联命令 |
|---|---|
| 提取公钥 | hitls rsa -in /etc/hitls/keys/web_rsa.pem -pubout -out web_rsa_pub.pem |
| 用私钥签名文件 | hitls sign -in data.txt -out data.sig -key web_rsa.pem -alg sha256 |
| 用公钥验证签名 | hitls verify -in data.txt -sig data.sig -key web_rsa_pub.pem -alg sha256 |
免费下载openHiTLS
1、下载相关代码
- openHiTLS下载地址：https://gitcode.com/openhitls
- libboundscheck下载地址：https://gitee.com/openeuler/libboundscheck.git 说明：需要将libboundscheck下载至openHiTLS/platform/Secure_C目录
2、构建安装，在openHiTLS根路径下执行以下命令：
cppmkdir build cd build cmake .. make && make install