📚 课程目录第3章 OpenSSL命令行工具总览

3. OpenSSL命令行工具总览

OpenSSL 的命令行工具 openssl 是企业密码工程中最常被直接调用的入口。它既是一个多合一工具集，也是一个可被脚本编排的“密码计算器”。理解它的命令结构，比记住零散命令更重要——因为几乎所有子命令都遵循同一套语法骨架，掌握骨架后，新子命令可以靠帮助系统自行推导。

一、命令结构：三段式语法骨架

openssl 的通用调用形式可以抽象为三段：

openssl <子命令> [子命令选项] [输入/输出参数]

第一段是程序名，第二段是子命令（command），决定这次要做什么，例如 genpkey、req、x509、dgst、enc、s_client。第三段是该子命令自己的选项与参数。关键点在于：选项的归属是子命令，而不是 openssl 本身。因此 openssl -in file 是无效的，必须写成 openssl x509 -in file。很多初学者报错“unknown option”，根源就是把选项放错了层级。

此外，OpenSSL 3.x 引入了提供者（provider）与算法获取机制，部分子命令支持 -provider、-propquery 等全局性选项，但它们仍写在子命令之后。工程中若使用国密或第三方引擎，通常通过配置文件或 -provider 指定，而不是改变命令骨架。

二、帮助系统：不背命令也能查

OpenSSL 的帮助系统分三层，工程中应养成“先查再写”的习惯：

openssl help：列出所有可用子命令，并给出常用选项提示。当你不确定某个功能对应哪个子命令时，先看这里。
openssl list -commands：以纯列表形式输出全部子命令，适合脚本中做能力探测。
openssl <子命令> -help：查看该子命令的完整选项说明。例如 openssl req -help 会列出 -new、-key、-subj、-addext 等选项及其含义。

在 OpenSSL 3.x 中，还可以用 openssl list -providers 查看当前加载的提供者，用 openssl list -digest-algorithms、openssl list -cipher-algorithms 查看可用算法。这在排查“为什么某个算法不可用”时非常直接：如果算法不在列表里，说明当前提供者未加载或该算法被禁用。

帮助输出中的选项顺序不代表必须按此顺序书写，但 -help 通常应放在子命令之后、其他参数之前，避免被误解析为输入文件名。

三、工程脚本中的调用方式

在 Shell 脚本或 CI 流水线中调用 openssl，核心原则是：显式指定输入输出、避免交互、检查退出码。以下是一段生成私钥与自签名证书的示例脚本片段，参数均为教学示例值：

#!/usr/bin/env bash
set -euo pipefail

DAYS=365
SUBJ="/C=CN/O=Example Corp/CN=api.example.com"

# 1. 生成 2048 位 RSA 私钥（PKCS#8 格式）
openssl genpkey -algorithm RSA \
  -pkeyopt rsa_keygen_bits:2048 \
  -out server.key

# 2. 生成证书签名请求（CSR），非交互
openssl req -new -key server.key \
  -subj "$SUBJ" \
  -addext "subjectAltName=DNS:api.example.com,DNS:www.example.com" \
  -out server.csr

# 3. 自签名生成证书
openssl x509 -req -in server.csr \
  -signkey server.key \
  -days "$DAYS" \
  -copy_extensions copy \
  -out server.crt

# 4. 校验证书与私钥是否匹配
openssl x509 -noout -modulus -in server.crt | openssl dgst -sha256
openssl rsa  -noout -modulus -in server.key | openssl dgst -sha256

这段脚本体现了几个工程要点。第一，set -euo pipefail 让任何一步失败立即终止，避免用错误证书继续部署。第二，-subj 和 -addext 把交互式输入变成命令行参数，使脚本可在无人值守环境运行。第三，最后两行通过比较证书与私钥的模数摘要是否一致，判断二者是否配对——这是证书部署前最值得做的一次自检。

另一个常见场景是校验证书链。可以用 openssl verify -CAfile ca.crt -untrusted intermediate.crt server.crt，退出码为 0 表示验证通过，非 0 表示失败。脚本中应直接判断退出码，而不是去解析输出文本，因为输出格式可能随版本变化。

不要把私钥口令写在命令行参数里（如 -passin pass:123456），它会出现在进程列表和历史记录中。应使用 -passin file:、-passin env: 或交互式输入，并限制文件权限为 600。

四、参数与退出码的判读

工程脚本中，openssl 的返回值是最可靠的判断依据：成功返回 0，失败返回非 0。常见失败原因包括：文件不存在、格式不匹配（如把 DER 当 PEM 读）、口令错误、算法不可用、证书验证失败。排查时先用 -help 确认选项拼写，再用 openssl asn1parse 或 openssl x509 -text 查看对象实际结构，往往比反复试参数更快定位问题。