【密码学实战】openHiTLS req命令行：X.509证书签名请求管理

命令概述

openHiTLS `req` 命令是一款功能完备的X.509证书签名请求（CSR）全生命周期管理工具，专门用于PKI（公钥基础设施）体系中证书请求的生成、验证、解析与处理。该工具基于openHiTLS高性能密码库开发，不仅全面支持SM2/SM3等商用密码算法，还兼容RSA、ED25519等国际通用算法，具备安全的密钥生成与管理能力、灵活的请求配置方式以及完善的错误处理机制。相较于其他同类工具，其在商用密码算法的合规性和兼容性上表现突出，能满足国内企业及机构在密码应用方面的特殊需求，同时也兼顾国际场景下的算法支持，实现了跨环境的证书请求管理能力。

基本语法

hitls req [options]

语法说明：各选项可根据实际需求进行组合，不同选项之间通过空格分隔，部分选项需要搭配参数使用，参数紧跟在选项之后。命令执行时，系统会按照选项的优先级和依赖关系进行处理，例如密钥相关选项需在生成请求时提前指定，否则将使用默认参数生成临时密钥。

主要功能模式

1. 生成新证书请求（默认模式）

使用场景：为新的数字证书创建签名请求，适用于服务器证书、客户端证书、代码签名证书等各类X.509证书的申请场景，如网站HTTPS部署、VPN身份认证、文档加密等。

# 基本用法 - 自动生成密钥和CSR 
# 自动生成RSA 2048位密钥，生成的CSR输出至标准输出 
hitls req -new -subj "/C=CN/ST=Beijing/L=Beijing/O=MyOrg/CN=example.com" 
# 使用现有密钥生成CSR 
# 指定已存在的PEM格式私钥，生成针对server.domain.com的CSR 
hitls req -new -subj "/C=CN/ST=Shanghai/O=Company/CN=server.domain.com" \ -key existing_key.pem -keyform PEM 
# 使用配置文件生成复杂CSR # 通过配置文件定义扩展属性（如SAN），生成包含自定义信息的CSR 
hitls req -new -config request.conf -key private.key -out request.csr

说明：自动生成密钥时，默认会创建RSA算法的密钥对，密钥长度为2048位，若需指定其他算法和密钥长度，可结合相关配置文件进行设置；使用现有密钥时，需确保密钥格式与`-keyform`参数指定的一致，否则会导致密钥加载失败。

2. 验证证书请求

使用场景：验证现有CSR的完整性和签名有效性，确保CSR在传输过程中未被篡改，且签名信息符合算法要求，通常在提交CSR至CA（证书颁发机构）前进行验证。

# 验证CSR自签名 
# 检查CSR的签名是否有效，若验证通过无输出，失败则提示错误信息 
hitls req -verify -in request.csr 
# 验证并查看详细信息 # 验证签名的同时，以文本格式输出CSR的完整内容，便于人工核对 
hitls req -verify -in request.csr -text

说明：验证过程主要检查签名算法的正确性、签名值与CSR内容的匹配性，以及X.509结构的合规性；若CSR包含扩展属性（如SAN），验证时也会对扩展字段的格式进行检查。

3. 查看证书请求内容

使用场景：以可读格式显示CSR内容，用于核对证书主题信息、扩展属性、密钥算法、签名算法等关键信息，确保与预期一致。

# 显示CSR文本内容 
# 输出CSR的文本信息和编码内容（PEM/DER） 
hitls req -text -in request.csr 
# 显示内容但不输出编码文件 # 仅输出文本格式的CSR内容，不包含PEM/DER编码部分，便于快速查看
hitls req -text -noout -in request.csr

说明：文本格式输出包含版本号、序列号、主题信息、公钥信息、签名算法、扩展字段等内容，其中扩展字段（如subjectAltName）对于多域名证书申请至关重要，需重点核对。

详细选项说明

输入输出控制

选项	参数	说明	示例
-in	文件名	输入CSR文件（默认：标准输入）	-in server.csr
-inform	DER/PEM	输入格式（默认：PEM），PEM为文本编码，DER为二进制编码	-inform DER
-out	文件名	输出文件（默认：标准输出）	-out client.csr
-outform	DER/PEM	输出格式（默认：PEM），根据CA要求选择合适的格式	-outform PEM
-noout	-	不输出编码的请求，仅显示文本等其他信息	-text -noout
-text	-	以文本格式输出请求内容，包含所有X.509字段	-text -in request.csr

密钥管理选项

选项	参数	说明	示例
-key	文件名	签名私钥文件路径，用于对CSR进行签名	-key sm2_private.key
-keyform	DER/PEM	私钥输入格式，需与密钥文件实际格式一致	-keyform PEM
-passin	密码源	私钥密码来源，支持多种方式，避免明文密码暴露	-passin env:KEY_PASS
-passout	密码源	输出密码保护，若生成新密钥，用于设置密钥密码	-passout file:pass.txt

请求生成选项

选项	参数	说明	示例
-new	-	生成新的证书请求，为默认功能模式的触发选项	-new -subj "/C=CN/CN=test"
-subj	主题字符串	设置证书主题名称，遵循X.500可分辨名称格式	-subj "/C=CN/ST=Guangdong/O=TestOrg"
-mdalg	哈希算法	指定签名哈希算法，需与密钥算法兼容	-mdalg SM3
-config	文件名	请求模板配置文件，用于定义扩展属性等复杂信息	-config san.conf

验证选项

选项	参数	说明	示例
-verify	-	验证请求的自签名，检查签名有效性和内容完整性	-verify -in request.csr

主题名称格式

-subj 参数采用标准的X.500可分辨名称格式，各字段含义及规范如下：

/C=国家代码/ST=省份/L=城市/O=组织/OU=部门/CN=通用名称

• C（Country Name）：国家代码，采用两位字母的ISO 3166-1标准，例如CN代表中国，US代表美国，JP代表日本，不可省略。

• ST（State or Province Name）：省份或州名称，需使用全称，不可使用缩写，例如“Beijing”“Guangdong”，部分CA要求该字段不可为空。

• L（Locality Name）：城市或地区名称，同样需使用全称，例如“Shanghai”“Shenzhen”。

• O（Organization Name）：组织或企业名称，需与实际注册名称一致，对于企业证书申请，CA通常会要求提供组织证明文件。

• OU（Organizational Unit Name）：部门名称，用于区分组织内部的不同部门，例如“IT Department”“Finance Department”，可根据实际情况省略。

• CN（Common Name）：通用名称，通常为域名（服务器证书）或用户名（客户端证书），例如“example.com”“user@company.com”，是证书的核心标识字段。

示例：

-subj "/C=CN/ST=Guangdong/L=Shenzhen/O=Huawei/OU=Research/CN=hitls.example.com"

配置文件格式

openHiTLS支持通过配置文件定义复杂的证书请求属性，如扩展字段、密钥参数等，配置文件采用INI格式，主要包含[req]、[req_extensions]等 sections。以下为扩展后的配置文件示例及说明：

# request.conf 示例
[req]
default_bits = 2048                # 指定生成密钥的默认位数
default_md = SHA256                # 默认哈希算法
distinguished_name = req_distinguished_name  # 主题名称配置section
req_extensions = v3_req            # 启用v3扩展，指向[req_extensions] section
prompt = no                        # 不提示用户输入，直接使用配置中的主题信息

[req_distinguished_name]
C = CN                             # 国家代码
ST = Beijing                       # 省份
L = Beijing                        # 城市
O = MyCompany                      # 组织
OU = IT                            # 部门
CN = www.mycompany.com             # 通用名称

[req_extensions]
subjectAltName = @alt_names        # 主题备用名称，指向[alt_names] section
keyUsage = digitalSignature, keyEncipherment  # 密钥用途：数字签名、密钥加密
extendedKeyUsage = serverAuth, clientAuth  # 扩展密钥用途：服务器认证、客户端认证
basicConstraints = CA:FALSE        # 基本约束：不允许作为CA证书

[alt_names]
DNS.1 = www.mycompany.com          # 域名1
DNS.2 = mycompany.com              # 域名2
DNS.3 = *.mycompany.com            # 通配符域名
IP.1 = 192.168.1.100               # IP地址1
IP.2 = 10.0.0.5                    # IP地址2

配置项说明：prompt = no 表示不弹出交互提示，直接使用[req_distinguished_name]中的主题信息；keyUsage和extendedKeyUsage定义了证书的用途限制，CA会根据这些信息颁发符合用途的证书；basicConstraints = CA:FALSE 表明该证书为终端实体证书，不能用于签发其他证书。

密码参数格式

为保障私钥安全，openHiTLS req命令支持多种密码输入方式，避免在命令行中直接暴露明文密码，各方式的特点及适用场景如下：

# 环境变量
# 从环境变量PASSWORD_VAR中读取密码，适用于脚本自动化场景
-passin env:PASSWORD_VAR

# 文件读取
# 从password.txt文件中读取密码（文件需设置严格权限，仅所有者可读写）
-passin file:password.txt

# 标准输入
# 从标准输入读取密码，执行命令后会提示用户输入，适用于交互式操作
-passin stdin

# 直接输入（不推荐）
# 命令行中直接指定明文密码，存在安全风险（易被历史命令记录）
-passin pass:明文密码

安全提示：强烈建议避免使用pass:明文密码的方式，优先选择环境变量或文件读取方式，并确保密码文件的权限设置为600（仅所有者可读写），防止密码泄露。

算法支持

哈希算法

• 国际算法：SHA256、SHA384、SHA512 - SHA256：应用广泛的哈希算法，安全性较高，适用于大多数通用场景； - SHA384/SHA512：哈希值更长，安全性更高，适用于对安全要求极高的场景，如金融、政务等。

• 商密算法：SM3 - 符合GM/T 0004-2012标准，是国内密码应用的推荐算法，适用于需满足商密要求的场景，如国内政务系统、金融机构内部系统等。

• 特殊算法：ED25519（使用SHA512） - 基于椭圆曲线的签名算法，密钥长度短、签名速度快，适用于资源受限的设备或对性能要求较高的场景，如物联网设备、移动应用等。

非对称算法

• RSA（默认2048位）：国际通用的非对称算法，兼容性好，应用成熟，默认密钥长度为2048位，可通过配置文件指定为4096位以提升安全性。

• SM2（商用密码算法）：符合GM/T 0003-2012标准的椭圆曲线非对称算法，密钥长度短（256位）、安全性高。

• ED25519：基于Curve25519的椭圆曲线算法，具有密钥生成快、签名验证效率高的特点，且抗侧信道攻击能力强，适用于现代密码系统。

算法兼容性：不同的哈希算法与非对称算法需搭配使用，例如SM2密钥需使用SM3哈希算法进行签名，RSA密钥可搭配SHA256、SHA384等哈希算法，ED25519固定使用SHA512哈希算法。

使用示例详解

示例1：完整的企业证书请求

hitls req -new \
    -subj "/C=CN/ST=Beijing/L=Beijing/O=MyCorp/OU=IT Department/CN=secure.mycorp.com" \
    -keyform PEM \
    -key corporate_key.pem \
    -passin env:KEY_PASSWORD \
    -mdalg SHA256 \
    -config corp_req.conf \
    -out corporate_request.csr \
    -outform PEM

参数详解：

• -subj：指定企业证书的主题信息，包含国家、省份、城市、组织、部门和通用名称（企业域名）。

• -keyform PEM：指定私钥文件格式为PEM。

• -key corporate_key.pem：使用企业已有的私钥文件进行签名。

• -passin env:KEY_PASSWORD：从环境变量KEY_PASSWORD中获取私钥密码，避免在命令行中暴露明文密码。

• -mdalg SHA256：使用SHA256哈希算法进行签名。

• -config corp_req.conf：通过配置文件定义证书的扩展属性（如SAN、密钥用途等）。

• -out corporate_request.csr：将生成的CSR输出至指定文件。

• -outform PEM：指定CSR输出格式为PEM，便于提交给CA。

示例2：商密密码算法证书请求

hitls req -new \ -subj "/C=CN/ST=Guangdong/O=GMExample/CN=gm.example.com" \ -key sm2_key.pem \ -mdalg SM3 \ -out gm_request.csr

参数详解：

• -subj：指定商密证书的主题信息，包含国家、省份、组织和通用名称。

• -key sm2_key.pem：使用SM2算法的私钥文件，需确保该密钥为SM2格式。

• -mdalg SM3：搭配SM2密钥使用SM3哈希算法进行签名。

• -out gm_request.csr：将商密CSR输出至指定文件，该CSR可提交给支持商用密码算法的CA进行签发。

示例3：批量验证CSR文件

#!/bin/bash
# 批量验证当前目录下所有.csr文件
for csr_file in *.csr; do
    # 检查文件是否存在且为普通文件
    if [ -f "$csr_file" ]; then
        echo "====================================="
        echo "验证文件: $csr_file"
        # 验证CSR，不输出编码内容
        hitls req -verify -in "$csr_file" -noout
        # 根据命令执行结果判断验证是否通过
        if [ $? -eq 0 ]; then
            echo "✓ $csr_file 验证通过"
        else
            echo "✗ $csr_file 验证失败"
        fi
    fi
done
echo "====================================="
echo "批量验证完成"

脚本说明：该bash脚本会遍历当前目录下所有后缀为.csr的文件，逐一进行验证；使用-noout选项避免输出CSR编码内容，仅显示验证结果；通过$?获取上一条命令的执行状态码（0为成功，非0为失败），并输出对应的验证结果标识，便于快速筛选无效CSR。

错误处理与调试

常见错误代码

错误码	说明	解决方法
HITLS_APP_OPT_UNKOWN	未知选项	检查命令语法，确保所有选项拼写正确；使用hitls req -help查看支持的选项列表。
HITLS_APP_PASSWD_FAIL	密码处理失败	检查密码源格式是否正确（如环境变量是否存在、文件路径是否正确）；确保密码文件权限设置合理；若为交互式输入，核对密码是否正确。
HITLS_APP_LOAD_KEY_FAIL	密钥加载失败	验证密钥文件是否存在且可读取；检查密钥格式与-keyform参数是否一致；若密钥有密码，确保密码正确；验证密钥文件是否损坏（可通过其他工具尝试读取）。
HITLS_APP_X509_FAIL	X.509操作失败	检查输入CSR文件是否完整、格式是否正确；若为生成CSR，核对主题信息格式、配置文件语法是否合规；确保使用的算法组合兼容。
HITLS_APP_FILE_OPEN_FAIL	文件打开失败	检查输入/输出文件路径是否正确；确保当前用户对文件所在目录有读写权限；若文件已被其他进程占用，关闭占用进程后重试。

调试技巧

# 启用详细输出
# 生成CSR时同时输出文本格式内容，便于查看生成过程中的信息
hitls req -new -subj "/C=CN/CN=test" -text -out request.csr

# 检查中间结果
# 仅查看CSR的文本内容，不输出编码部分，快速核对关键信息
hitls req -text -noout -in request.csr

# 查看命令帮助信息
# 获取所有选项的详细说明，解决选项使用疑问
hitls req -help

# 验证密钥文件格式
# 检查私钥文件的格式和基本信息，确保密钥可用
hitls rsa -in private.key -text -noout  # RSA密钥
hitls sm2 -in sm2_key.pem -text -noout  # SM2密钥

建议：若遇到复杂错误，可逐步简化命令，排除无关选项，定位问题根源；例如先使用最基本的命令生成CSR，再逐步添加配置文件、密码等选项，观察在哪一步出现错误。

与其他工具集成

openHiTLS req命令生成的CSR可以与其他PKI工具配合使用：

# 生成CSR
hitls req -new -subj "/C=CN/CN=server" -key server.key -out server.csr

# 使用其他工具处理（示例）
hitls x509 -req -in server.csr -CA ca.crt -CAkey ca.key -out server.crt

版本与兼容性

该命令基于openHiTLS密码库开发，支持：

• X.509 v3 证书请求格式

• PEM 和 DER 编码格式

• 商用密码算法标准（GM/T）

• 国际通用密码算法标准

通过合理使用openHiTLS req命令，用户可以高效、安全地管理数字证书请求，为构建可信的网络身份体系提供坚实基础。