【密码学实战】openHiTLS server命令行：搭建国密标准安全通信服务器

名称

hitls server 是openHiTLS密码库生态中用于构建国密标准安全通信服务的核心命令行工具。

概述

hitls server [选项]

通过指定不同选项组合，可快速搭建支持国密TLCP/DTLCP协议的安全服务器，满足从开发测试到生产部署的各类加密通信需求。

描述

hitls server 命令基于openHiTLS密码库开发，实现了功能完备的TLS/DTLS服务器，其核心优势在于对国密TLCP（GB/T 38636-2020）协议的原生支持，同时兼容密码库的高性能加密算法实现。该服务器可完成从连接监听、安全握手到加密数据传输的全流程处理，是构建符合国内安全标准通信系统的关键组件。

服务器支持两种运行模式，覆盖不同网络场景需求：

• TLCP：基于TCP协议的国密TLS通信模式，提供可靠的面向连接加密服务，适用于对数据传输可靠性要求高的场景，如金融交易、政务数据交换等。

• DTLCP：基于UDP协议的国密DTLS通信模式，采用 datagram 传输方式，具有低延迟特性，适用于实时性要求高但可容忍少量丢包的场景，如物联网设备通信、视频会议等。

程序默认以前台交互式运行，实时输出连接状态与日志信息；支持通过信号控制（如SIGINT）实现优雅退出。内部采用多上下文并发机制，每个客户端连接独立分配加密上下文，确保连接间的安全隔离与并发处理能力。

选项说明

监听选项

这些选项控制服务器的网络监听行为，包括监听地址、端口等核心网络参数配置。

• --accept *host:port* 精确指定服务器的监听端点，格式为"主机地址:端口号"。其中： host：支持IPv4地址（如192.168.1.100）、IPv6地址（如[::1]）或主机名（如localhost）；若省略host部分（格式为:port），则默认监听所有网络接口（IPv4的0.0.0.0和IPv6的::）。

• port：取值范围为1-65535，其中1-1024为特权端口，需root/管理员权限才能绑定。

--accept 192.168.1.100:4433    # 仅监听192.168.1.100网卡的4433端口
--accept [::1]:8443            # 监听IPv6本地回环地址的8443端口
--accept :8443                 # 监听所有接口的8443端口

--port *port* 简化的端口指定选项，默认值为4433。当与--accept同时使用时，--accept中的端口配置将覆盖此选项，优先级更高。适用于仅需修改端口而保持默认监听地址的场景。

协议选项

用于指定服务器采用的安全协议版本及密码套件，直接影响通信的安全性与兼容性。

• --tlcp 启用国密TLCP协议（基于TCP），遵循GB/T 38636-2020《信息安全技术 传输层密码协议》标准，是国内合规场景下的首选协议模式。启用此选项后，需配合双证书配置（见证书选项）才能完成握手。

• --dtlcp 启用国密DTLCP协议（基于UDP），基于TLCP协议的 datagram 扩展，支持数据包重传、序列号校验等机制，在保证安全性的同时降低传输延迟。适用于带宽受限或实时性要求高的物联网、工业控制等场景。

• --cipher *cipherlist* 指定服务器支持的密码套件列表，多个套件以英文逗号分隔，服务器将按列表顺序优先选择协商套件。国密常用密码套件包括： ECC_SM4_SM3：基于ECC密钥交换、SM4加密、SM3哈希的套件

• ECDHE_SM4_SM3：基于ECDHE临时密钥交换、SM4加密、SM3哈希的套件（前向安全）

• RSA_SM4_SM3：基于RSA密钥交换、SM4加密、SM3哈希的套件

--cipher "ECDHE_SM4_SM3,ECC_SM4_SM3" # 优先使用前向安全套件

证书和密钥选项

配置服务器身份认证所需的证书与私钥，是建立TLS连接的核心安全凭证。国密TLCP协议强制要求双证书体系，需分别配置加密证书和签名证书。

• --CAfile *file* 指定包含受信任CA证书的文件路径，用于验证客户端证书（当服务器启用客户端认证时）。文件需包含PEM/DER格式的CA证书链，确保客户端证书可追溯至信任根。

• --chainCAfile *file* 指定服务器证书链文件，包含从服务器证书到根CA的中间CA证书。配置此选项可帮助客户端快速完成证书信任链验证，避免因缺少中间证书导致的握手失败。

TLCP双证书选项

国密TLCP协议采用"加密证书+签名证书"双证书体系，二者功能分离：加密证书用于密钥交换过程中的会话密钥加密，签名证书用于服务器身份认证与握手消息签名。

• --tlcp_enc_cert *file*：指定服务器加密证书文件路径，证书主题通常包含"加密"用途标识。

• --tlcp_enc_key *file*：指定加密证书对应的私钥文件，私钥需妥善保管，建议权限设置为600（仅所有者可读可写）。

• --tlcp_sign_cert *file*：指定服务器签名证书文件路径，证书主题通常包含"签名"用途标识。

• --tlcp_sign_key *file*：指定签名证书对应的私钥文件，与加密私钥分开存储，增强密钥管理安全性。

格式选项

指定证书和私钥文件的存储格式，确保服务器能正确解析凭证文件。

• --certform PEM|DER 指定证书文件格式，默认值为PEM。两种格式区别： PEM：文本格式，以"-----BEGIN CERTIFICATE-----"和"-----END CERTIFICATE-----"为标识，便于文本编辑和传输。

• DER：二进制格式，文件体积小，适合嵌入式设备等资源受限场景。

--keyform PEM|DER 指定私钥文件格式，默认值为PEM。私钥文件若为DER格式，需确保不包含密码保护（部分场景下密码保护的DER私钥解析可能失败）。

服务选项

控制服务器运行时的行为模式，包括连接处理策略、日志输出级别等。

• --accept_once 单连接模式：服务器接受第一个客户端连接，完成握手与数据传输后立即退出。适用于测试场景，如验证证书配置、握手流程或单条数据传输的正确性。

• --quiet 安静模式：仅输出错误信息和关键事件日志（如监听失败、握手错误），关闭常规状态日志（如连接建立、数据传输量）。适用于生产环境，减少日志输出对系统性能的影响。

• --state 详细状态模式：输出TLS握手的每个阶段日志，包括客户端hello、服务器hello、证书交换、密钥协商等步骤的具体参数。用于调试握手失败问题，如密码套件不匹配、证书验证失败等。

帮助选项

• --help：显示所有选项的简洁说明、默认值及使用示例，输出后立即退出程序。

国密SM模式选项

当openHiTLS编译时启用国密SM模式（编译选项：--enable-sm-mode），将解锁以下增强安全选项，提供更符合国密标准的深度定制功能。

• --sm_mode 启用国密SM特殊模式，开启增强安全特性，包括：SM2密钥交换的参数强化、SM4加密的分组模式校验、SM3哈希的抗碰撞性增强等。此模式下仅支持国密算法套件，禁用非国密算法。

• --work_path *path* 指定SM模式的工作目录，目录内需包含以下配置文件： sm_config.conf：SM模式核心配置文件，包含密钥派生参数、安全策略开关等。

• sm_param.bin：预生成的SM2椭圆曲线参数文件，加速密钥交换过程。

环境

服务器运行依赖以下系统环境配置，确保服务稳定可靠：

• 文件描述符限制：系统需配置足够的文件描述符上限，以支持并发连接。生产环境建议设置为65535以上，临时修改命令：ulimit -n 65535；永久修改需编辑/etc/security/limits.conf文件。

• 文件权限：证书和私钥文件需确保服务器进程有读取权限，私钥文件建议设置为600，证书文件设置为644。避免使用777等宽松权限，防止凭证泄露。

• 端口权限：绑定1024以下特权端口需root/管理员权限，非特权用户可使用setcap命令赋予程序绑定特权端口的能力：setcap 'cap_net_bind_service=+ep' /path/to/hitls。

• 网络环境：确保服务器所在网络的防火墙、安全组规则允许监听端口的传入连接（TCP/UDP根据协议模式配置），避免因网络策略导致连接被阻断。

诊断

服务器通过标准输出（stdout）和标准错误（stderr）输出状态与错误信息，不同日志级别对应不同问题类型：

• 启动日志：成功启动时输出"Listening on [host:port] with [protocol]"，表示监听已就绪。

• 连接日志：新连接建立时输出"New connection from [client_ip:port]"，握手成功后输出"Handshake completed: cipher=[cipher_suite], protocol=[TLCP/DTLCP]"

• 错误日志：错误信息以"ERROR: "开头，包含错误码和描述，常见错误及排查方向如下：

常见错误码说明

• HITLS_APP_SUCCESS (0)：操作成功，无错误。

• HITLS_APP_ERR_HANDSHAKE：握手失败，排查方向：证书格式/权限错误、密码套件不匹配、客户端证书未信任。

• HITLS_APP_ERR_LISTEN：监听失败，排查方向：端口已被占用、无绑定权限、地址格式错误。

• HITLS_APP_INVALID_ARG：参数无效，排查方向：选项拼写错误、必填参数缺失（如双证书未完整配置）、参数值超出范围。

• HITLS_APP_ERR_CERT：证书错误，排查方向：证书过期、主题与域名不匹配、证书链不完整。

• HITLS_APP_ERR_KEY：私钥错误，排查方向：私钥与证书不匹配、私钥密码错误、私钥格式不支持。

示例

基本TLCP服务器（开发测试）

启动监听所有接口4433端口的TLCP服务器，配置完整双证书和CA信任链，适用于开发环境测试： 

hitls server --tlcp \--tlcp_enc_cert ./certs/enc_cert.pem \--tlcp_enc_key ./keys/enc_key.pem \--tlcp_sign_cert ./certs/sign_cert.pem \--tlcp_sign_key ./keys/sign_key.pem \--CAfile ./certs/ca_cert.pem \--state  # 启用详细状态日志便于调试

生产级TLCP服务器（指定网卡+安静模式）

监听特定网卡（192.168.1.100）的8443端口，启用安静模式减少日志开销，适用于生产环境：

hitls server --tlcp --accept 192.168.1.100:8443 --quiet \--tlcp_enc_cert /etc/openhitls/certs/enc_cert.pem \--tlcp_enc_key /etc/openhitls/keys/enc_key.pem \--tlcp_sign_cert /etc/openhitls/certs/sign_cert.pem \--tlcp_sign_key /etc/openhitls/keys/sign_key.pem \--chainCAfile /etc/openhitls/certs/chain_ca.pem

单连接测试模式

接受单个客户端连接并完成一次数据传输后退出，用于验证证书配置和握手流程：

hitls server --tlcp --accept_once \--tlcp_enc_cert enc_cert.pem \--tlcp_enc_key enc_key.pem \--tlcp_sign_cert sign_cert.pem \--tlcp_sign_key sign_key.pem

DTLCP物联网服务器

启动基于UDP的DTLCP服务器，监听4434端口，适用于物联网设备低延迟通信：

hitls server --dtlcp --port 4434 \--tlcp_enc_cert iot_enc_cert.pem \--tlcp_enc_key iot_enc_key.pem \--tlcp_sign_cert iot_sign_cert.pem \--tlcp_sign_key iot_sign_key.pem \--cipher "ECDHE_SM4_SM3"  # 优先前向安全套件

注意

1. 证书要求：TLCP协议强制要求配置双证书（加密+签名），仅配置单证书会直接导致握手失败。证书需由合规国密CA签发，确保主题字段、用途标识符合TLCP标准。

2. 文件格式一致性：确保证书/私钥文件格式与--certform/--keyform选项一致，混合格式（如PEM证书+DER私钥）会导致解析错误。

3. 私钥安全：私钥文件应存储在安全目录（如/etc/openhitls/keys），权限设置为600，避免被其他用户读取。生产环境建议使用硬件安全模块（HSM）存储私钥。

4. 防火墙配置：根据协议模式开放对应端口的TCP/UDP流量，例如TLCP开放TCP 4433，DTLCP开放UDP 4434。云服务器需同步配置安全组规则。

5. 性能优化：生产环境中建议：①启用--quiet减少日志IO；②调大系统文件描述符限制；③使用多核CPU部署，利用openHiTLS的多线程并发能力。

6. 信号处理：服务器响应SIGINT（Ctrl+C）和SIGTERM信号，收到信号后会停止接受新连接，等待现有连接处理完成后优雅退出，避免数据丢失。

7. 版本兼容性：不同openHiTLS版本的选项可能存在差异，使用前建议通过hitls server --help确认当前版本支持的选项。

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