【密码学实战】openHiTLS client命令行：国密TLCP/DTLCP客户端工具

命令概述

`hitls client` 是 openHiTLS 工具集中的核心客户端组件，专注于建立与远程服务器的 TLS/DTLS 安全连接。其核心优势在于同时支持国际标准 TLS/DTLS 协议（如 TLS 1.0/1.1/1.2/1.3、DTLS 1.2/1.3）与符合中国密码管理局（GM/T）规范的 TLCP/DTLCP 国密协议（TLCP 1.0/1.1、DTLCP 1.0/1.1），为开发者和运维人员提供了一站式的安全通信测试、协议兼容性验证及合规性检查能力。广泛应用于金融、政务、能源等对数据安全和合规性有严格要求的领域，是构建符合国密标准的安全通信系统不可或缺的测试工具。

基本语法

hitls client [选项] [参数]

语法遵循 Unix 命令行工具设计规范，选项与参数需严格区分：选项以 `--` 开头（部分工具支持短选项 `-`，但 hitls client 统一使用长选项），用于配置连接行为；参数为选项的补充值（如主机名、文件路径等），需紧跟对应选项。

连接选项

必需参数

• `--host <hostname|ip>` **功能**：指定目标服务器的主机名或 IP 地址 **说明**：支持 IPv4（如 192.168.1.100）和 IPv6（如 2001:db8::1）地址格式，若输入主机名需确保本地 DNS 可解析或通过 hosts 文件配置映射 **示例**：`--host example.com` 或 `--host 2001:db8::1`

• `--port <port>` **功能**：指定目标服务器的端口号 **默认值**：4433（openHiTLS 工具集默认测试端口，非标准端口需显式指定） **说明**：需确保端口为服务器监听的 TLS/DTLS 服务端口，常见标准端口为 443（TLS）、4433（测试用） **示例**：`--port 8443`

协议选择

• `--tlcp` **功能**：使用 TLCP 国密协议进行连接 **说明**：启用后自动切换为 TLCP 协议栈，优先使用国密算法套件（如 SM2/SM3/SM4），需服务器端同样支持 TLCP 协议 **适用场景**：国密合规场景下的安全连接测试

• `--dtlcp` **功能**：使用 DTLCP 协议进行连接（基于 UDP 的 TLCP） **说明**：基于 UDP 传输层的国密协议，适用于对实时性要求高但可容忍少量丢包的场景（如语音通话、物联网设备通信） **注意**：需与服务器的 UDP 端口通信，确保防火墙开放对应 UDP 端口

• `--cipher <cipher_suites>` **功能**：指定优先使用的密码套件列表 **说明**：多个套件之间用冒号（:）分隔，工具将按顺序尝试与服务器协商；若未指定，将根据协议版本自动选择默认套件 **国密示例**：`--cipher "ECDHE-SM2-SM4-CBC-SM3:TLCP_ECC_SM4_CBC_SM3"` **国际示例**：`--cipher "AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256"`

证书和验证选项

证书验证配置

• `--CAfile <file>` **功能**：指定受信任的 CA 证书文件 **格式**：支持 PEM（文本格式，以 `-----BEGIN CERTIFICATE-----` 开头/结尾）和 DER（二进制格式） **说明**：用于验证服务器证书的合法性，若服务器证书由第三方 CA 签发，需指定该 CA 的根证书 **示例**：`--CAfile /path/to/root_ca.pem`

• `--chainCAfile <file>` **功能**：指定证书链验证所需的中间 CA 文件 **说明**：当服务器返回的证书链不完整（如仅包含服务器证书和中间 CA，缺少根 CA）时，通过此选项补充中间 CA，构建完整的验证链，避免因链断裂导致验证失败 **使用场景**：服务器证书由多级 CA 签发的场景

• `--noverify` **功能**：跳过服务器证书验证 **使用场景**：本地测试环境、自签名证书调试或快速排除证书问题的临时场景 **安全警告**：生产环境严禁使用，可能导致连接到伪造服务器，引发中间人攻击或数据泄露

证书格式指定

• `--certform <PEM|DER>` **功能**：指定证书文件的格式 **默认值**：PEM **说明**：若证书文件为二进制 DER 格式，需显式指定此选项，否则工具将无法解析证书 **示例**：`--certform DER`

• `--keyform <PEM|DER>` **功能**：指定私钥文件的格式 **默认值**：PEM **说明**：与证书格式对应，私钥文件需与证书格式保持一致，否则会出现密钥加载失败

TLCP 专用选项

TLCP 协议采用独特的双证书体系，将加密与签名功能分离：加密证书用于密钥交换过程中对会话密钥的加密传输，签名证书用于客户端身份认证（若服务器启用双向认证），两者需分别配置对应的证书和私钥。

加密证书配置

• `--tlcp_enc_cert <file>` **功能**：指定 TLCP 加密证书文件 **说明**：证书中包含客户端的加密公钥，服务器将使用此公钥加密会话密钥，确保密钥传输安全 **要求**：需为符合 GM/T 0024 规范的国密证书

• `--tlcp_enc_key <file>` **功能**：指定 TLCP 加密私钥文件 **说明**：与加密证书配对的私钥，用于解密服务器发送的加密会话密钥 **安全建议**：私钥文件需设置严格权限（如 Linux 下权限 0600，仅所有者可读写），避免泄露

签名证书配置

• `--tlcp_sign_cert <file>` **功能**：指定 TLCP 签名证书文件 **说明**：用于客户端向服务器证明身份，服务器通过验证此证书的签名有效性确认客户端合法性 **场景**：服务器启用双向认证（客户端认证）时必须配置

• `--tlcp_sign_key <file>` **功能**：指定 TLCP 签名私钥文件 **说明**：与签名证书配对，用于生成客户端身份认证的数字签名，私钥安全性直接影响身份认证有效性

输出和控制选项

输出模式

• `--quiet` **功能**：启用静默模式，减少输出信息 **说明**：仅输出关键错误信息和最终执行状态码，屏蔽握手过程详情、交互提示等内容 **使用场景**：自动化脚本、批量测试或无需人工干预的场景，便于程序解析执行结果

• `--state` **功能**：显示详细的握手状态信息 **输出内容**：包括协议版本、协商的密码套件、服务器证书主题/ issuer /有效期、会话 ID、扩展字段（如 ALPN、SNI）、密钥交换算法等 **价值**：故障排查的核心选项，可直观定位协议不兼容、证书问题等

• `--prexit` **功能**：在完成握手后立即退出，不进行数据交换 **说明**：仅验证握手过程的正确性，不建立后续的数据传输通道 **使用场景**：快速验证服务器的协议支持、端口开放及基础证书配置，节省测试时间

国密模式特殊选项

当 openHiTLS 编译时启用 `HITLS_APP_SM_MODE` 宏定义，`hitls client` 将支持国密模式下的特殊配置选项，进一步适配国密合规场景的需求。

• `--sm` **功能**：启用国密模式特殊处理 **说明**：启用后自动适配国密协议的特殊行为，如默认优先使用 SM2/SM3/SM4 算法套件、禁用非国密扩展字段等 **适用场景**：需严格遵循国密规范的合规性测试

• `--uuid <uuid>` **功能**：在国密模式下指定客户端唯一标识符 **格式**：需符合标准 UUID 4 格式（如 550e8400-e29b-41d4-a716-446655440000） **说明**：部分国密服务器要求客户端提供 UUID 用于会话跟踪或设备标识，未指定可能导致握手失败

• `--workpath <path>` **功能**：指定国密算法相关工作目录 **说明**：用于存放国密运算过程中的临时文件（如密钥缓存、随机数种子），需确保目录具备读写权限 **建议**：使用独立目录（如 /var/lib/hitls/sm_workdir），避免与其他文件冲突

使用示例

基础连接测试

# 连接国际标准 TLS 服务器（默认 TLS 协议，端口 4433）
hitls client --host example.com --port 443# 连接国密 TLCP 服务器（显式启用 TLCP 协议）
hitls client --host sm2.server.com --port 443 --tlcp

说明：第一个示例适用于验证遵循国际 TLS 标准的服务器（如互联网常见的 HTTPS 服务器）；第二个示例针对支持国密 TLCP 协议的服务器，需确保服务器端已配置国密证书和协议支持。

完整的 TLCP 连接示例（双向认证）

hitls client \--host tlcp.example.com \--port 8443 \--tlcp \--tlcp_enc_cert /path/to/client_enc.crt \--tlcp_enc_key /path/to/client_enc.key \--tlcp_sign_cert /path/to/client_sign.crt \--tlcp_sign_key /path/to/client_sign.key \--CAfile /path/to/root_ca.crt \--state

说明：此示例为 TLCP 双向认证场景的完整配置，包含双证书（加密+签名）、CA 根证书验证及详细状态输出，适用于生产环境前的合规性与兼容性测试。`--state` 选项可输出握手过程的关键参数，便于确认协议和套件协商结果。

快速验证服务器配置

# 仅验证握手过程，不进行数据交换
hitls client --host test.server.com --port 443 --prexit --state

说明：通过 `--prexit` 选项在握手成功后立即退出，可快速判断服务器的地址、端口、协议及证书是否基本正常，避免等待数据交换过程，提升测试效率。

调试和故障排查

# 指定国密套件并输出详细状态，定位握手失败问题
hitls client \--host problem.server.com \--port 4433 \--tlcp \--cipher "TLCP_ECC_SM4_CBC_SM3" \--state \--CAfile /path/to/trusted_ca.pem

说明：当连接出现“握手失败”时，通过 `--cipher` 锁定特定套件，结合 `--state` 输出的详细日志，可快速判断是否为套件不兼容、CA 证书不匹配等问题。

国密模式使用

hitls client \--host sm.server.com \--port 443 \--tlcp \--sm \--uuid "550e8400-e29b-41d4-a716-446655440000" \--workpath /var/lib/hitls/sm_workdir

说明：启用国密模式（`--sm`）并指定 UUID 和工作目录，适用于需严格遵循国密规范的特殊场景（如政务内网系统），确保客户端行为符合国密协议要求。

交互模式

当不使用 `--prexit` 选项时，`hitls client` 会在握手成功后自动进入交互模式，支持用户与服务器进行实时数据交换。

交互模式流程

1. 连接建立：控制台输出连接成功及握手完成信息

2. 数据发送：用户通过标准输入（键盘）输入文本，按 Enter 发送

3. 实时响应：服务器返回的响应数据将实时打印在控制台

4. 退出方式：使用 Ctrl+C 发送中断信号终止连接，或在部分环境中使用 Ctrl+D 发送 EOF 信号退出

交互模式示例

$ hitls client --host echo.server.com --port 4433
Connected to echo.server.com:4433
Starting TLS handshake...
TLS handshake completed successfully (Protocol: TLSv1.3, Cipher: AES256-GCM-SHA384)
Interactive mode - type messages (Ctrl+C to exit):
Hello Server!
Response: Hello Client!
How are you?
Response: I'm fine, thank you!

说明：此示例连接到回声服务器（Echo Server），用户发送的消息将被服务器原封不动返回，适用于验证数据传输过程中的加密有效性和通信双向性。

返回值说明

`hitls client` 命令执行完成后会返回状态码，可通过 shell 的 `$?` 变量查看（如 Linux 下执行 `echo $?`），状态码含义如下：

• `0`：成功完成所有操作（如握手成功、数据交换完成）

• `非0`：执行过程中出现错误，常见错误码示例： `1`：网络连接失败（如服务器不可达、端口未开放）

• `2`：证书验证失败（如 CA 证书不匹配、证书过期）

• `3`：握手协议不兼容（如协议版本/密码套件不支持）

• `4`：参数配置错误（如文件路径不存在、格式非法）

故障排查技巧

常见问题处理

1. 连接失败检查网络连通性：使用 `ping 服务器地址` 测试网络可达性

2. 验证端口开放：使用 `telnet 服务器地址 端口` 或 `nc -zv 服务器地址 端口` 确认端口是否监听

3. 排查防火墙：确认客户端与服务器之间的防火墙（本地、网络、服务器端）未拦截对应端口

4. 证书验证失败检查 CA 证书：使用 `openssl x509 -in /path/to/ca.crt -text` 查看 CA 证书详情，确认其为服务器证书的签发机构

5. 验证证书链：通过 `openssl s_client -connect 服务器:端口` 查看服务器返回的证书链，确认无中间 CA 缺失

6. 检查证书有效期：查看证书的 `Not Before` 和 `Not After` 字段，确认证书在有效期内

7. 握手失败协议兼容性：确认客户端指定的协议（如 --tlcp）与服务器支持的协议一致

8. 套件兼容性：使用 `openssl s_client -connect 服务器:端口 -cipher ALL` 查看服务器支持的套件，确保客户端指定的套件在列表中

9. 证书匹配：验证客户端证书（如 TLCP 双证书）与服务器要求的证书类型一致

调试建议

• 优先使用 `--state` 选项：获取握手过程的详细日志，是定位问题的首要步骤

• 临时使用 `--noverify`：在测试环境中排除证书问题，确认是否为证书导致的连接失败

• 启用编译级调试：若需更底层的日志，可在编译 openHiTLS 时添加 `-DDEBUG` 选项，生成带详细调试信息的工具

• 对比测试：使用国际标准工具（如 openssl s_client）与 hitls client 对比测试，判断问题是否为工具或服务器端配置导致

注意事项

• 安全警告：生产环境中严禁使用 `--noverify` 选项，跳过证书验证会直接暴露在中间人攻击风险下

• 性能考虑：国密算法（如 SM2）的计算复杂度略高于部分国际算法，高并发场景下需进行性能测试，可通过启用会话复用（如 TLS 会话票证）优化性能

• 兼容性：需确保客户端与服务器的协议版本、密码套件、证书格式兼容，建议在上线前进行全场景兼容性测试

• 证书管理：加密/签名私钥需妥善保管，建议使用密钥管理工具（如 KMIP 服务器）存储；证书需定期检查有效期，设置过期前提醒（如提前 30 天）

• 权限控制：证书和私钥文件需设置最小权限，避免其他用户读取；工作目录（如 --workpath 指定）同样需限制访问权限

`hitls client` 作为 openHiTLS 生态的核心测试工具，不仅满足国际标准安全测试需求，更深度适配中国国密规范，为构建合规、安全的通信系统提供了标准化的测试手段。

 免费下载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