密码学与证书 / 知识点
OpenSSL 证书操作手册
手册条目
在文本 PEM 与二进制 DER 格式之间转换证书和密钥。
转换 PEM 和 DER
用于在可读的 PEM 文本与二进制 DER 之间转换 X.509 证书和私钥。证书转换只改变编码;私钥经 pkey 转换时封装形式可能变化,但密钥参数不变。先确认对象类型,再选择 x509 或 pkey 子命令。
基本语法
证书使用 openssl x509,私钥使用 openssl pkey。-inform 指定输入编码,-outform 指定输出编码;PEM 是带头尾标记的 Base64 文本,DER 是二进制数据。
# 语法模板:将占位符替换为实际文件和 PEM 或 DER
openssl x509 -in <CERT_INPUT> -inform PEM|DER -out <CERT_OUTPUT> -outform PEM|DER
openssl pkey -in <KEY_INPUT> -inform PEM|DER -out <KEY_OUTPUT> -outform PEM|DER以上是语法模板,不能原样执行;<CERT_INPUT>、<KEY_INPUT> 等需替换为实际路径。
高频用法
将 PEM 证书转成 DER,再转回 PEM 并读取关键字段:
# 转换后立即回读,避免只检查文件是否生成
openssl x509 -in server.crt -outform DER -out server.der
openssl x509 -inform DER -in server.der -outform PEM -out server.roundtrip.crt
openssl x509 -in server.roundtrip.crt -noout -subject -issuer -dates预期输出:
subject=CN = api.example.com
issuer=CN = Example Intermediate CA
notBefore=<TIME>
notAfter=<TIME>实际名称和时间取决于证书;能正常打印字段且命令退出码为 0,说明转换后的证书可被解析。
转换私钥前先限制新文件权限,并用 -check 验证结果:
# 防止新生成的私钥被同组用户或其他用户读取
umask 077
openssl pkey -in server.key -outform DER -out server-key.der
openssl pkey -inform DER -in server-key.der -out server-key.roundtrip.pem
openssl pkey -in server-key.roundtrip.pem -check -noout预期输出:
Key is valid部分算法或版本的成功提示可能略有不同;退出码为 0 才表示校验成功。
风险与边界
-inform 和 -outform 只控制编码,不能把 PKCS#12、PKCS#7 或 CSR 当作普通证书处理。对象类型选错时通常出现 unable to load、Could not read 或 ASN.1 错误。先检查 PEM 头尾、执行 file,再用对应子命令试读,不要仅凭扩展名判断。
加密私钥转换时,如果输出命令未指定加密算法,结果可能成为未加密私钥,泄露后可直接被使用。安全替代方案是保留严格权限,并在输出 PEM 时增加 -aes-256-cbc;需要加密 PKCS#8 DER 时使用 openssl pkcs8 -topk8 并设置口令。
排障清单
遇到 Expecting: TRUSTED CERTIFICATE,通常是把 DER 当作 PEM 读取,补上 -inform DER。出现 bad decrypt 时,先确认输入私钥口令。转换成功但应用仍拒绝文件时,核对目标要求的是证书 DER、PKCS#8 私钥,还是包含证书链的 PKCS#12,三者不能互换。
OpenSSL 1.1.1 与 3.x 均支持上述核心命令;若旧设备只接受传统 RSA 私钥格式,应先确认兼容要求,再考虑使用 openssl rsa,不要默认降级。
将证书、私钥和证书链打包为 PFX 或 P12 文件。
导出 PKCS#12 文件
用于把叶子证书、对应私钥和中间证书链打包成 .p12 或 .pfx,供 Windows、IIS、Java、中间件或证书导入工具使用。导出前先确认私钥与叶子证书匹配,并检查中间证书链。
前置验证
分别提取证书和私钥的公钥并计算摘要;两行摘要必须完全一致:
# 摘要只比较公钥,不会输出私钥内容
openssl x509 -in server.crt -noout -pubkey \
| openssl pkey -pubin -outform DER \
| openssl dgst -sha256
openssl pkey -in server.key -pubout -outform DER \
| openssl dgst -sha256预期输出:
SHA2-256(stdin)= <HASH>
SHA2-256(stdin)= <HASH><HASH> 必须相同;不一致说明证书与私钥不是一对,继续打包只会得到无法正常使用的文件。
导出命令
-in 放叶子证书,-inkey 放对应私钥,-certfile 放中间证书链,-name 设置导入工具中显示的友好名称。命令会交互式要求设置导出口令:
# intermediate-chain.pem 通常只放中间 CA,不必包含公共根证书
openssl pkcs12 -export \
-out server-bundle.p12 \
-inkey server.key \
-in server.crt \
-certfile intermediate-chain.pem \
-name "api.example.com"预期输出:
Enter Export Password:
Verifying - Enter Export Password:两次输入一致且命令退出码为 0 时生成 server-bundle.p12。命令通常不会再打印成功消息。
验证内容
不导出私钥明文,只检查容器的 MAC、证书包和加密私钥包:
# 该命令会要求输入刚设置的导出口令
openssl pkcs12 -in server-bundle.p12 -info -noout预期输出:
Enter Import Password:
MAC: sha256, Iteration <COUNT>
Certificate bag
Shrouded Keybag: <ALGORITHM>算法名称和迭代次数会随 OpenSSL 版本及参数变化;出现 Mac verify error: invalid password? 表示口令错误或文件损坏。
常用参数
-certfile 可包含多个中间证书,建议按“签发叶子证书的中间 CA → 更上级中间 CA”排列。自动化场景可用 -passout file:<PATH> 从权限为 600 的文件读取口令;避免使用 -passout pass:<PASSWORD>,否则口令可能进入命令历史、审计日志或进程参数。
OpenSSL 3.x 的默认算法可能被旧系统拒绝。只有在明确出现兼容性错误且无法升级目标系统时,才临时增加 -legacy;它可能启用较旧算法,降低容器保护强度。更安全的替代方案是升级导入端,或按其文档显式选择双方支持的现代 PBE 和 MAC 算法。
排障清单
出现 No certificate matches private key 时,重新执行公钥摘要比对。导入后缺少链证书时,检查 intermediate-chain.pem 是否遗漏中间 CA、误放叶子证书或顺序错误。出现 unsupported、RC2 等错误时,先确认是读取旧 P12 还是导出给旧客户端,再决定是否在受控环境使用 -legacy。
生成后立即执行 chmod 600 server-bundle.p12,并通过受控渠道传输;P12 同时包含私钥,泄露后的影响等同于私钥泄露。
从 PFX 或 P12 文件中提取证书、私钥和 CA 证书链。
解包 PKCS12 文件
用于把 .pfx 或 .p12 中的叶子证书、私钥和 CA 证书链分别导出。默认先保留加密私钥,确认权限和用途后再决定是否生成未加密版本。
命令定位
openssl pkcs12 负责读取 PKCS#12 容器;-clcerts 选择终端实体证书,-cacerts 选择 CA 证书,-nokeys 与 -nocerts 分别排除私钥或证书。先查看容器是否可读以及包含哪些对象:
openssl pkcs12 -in app.p12 -info -noout预期输出:
Enter Import Password:
MAC: sha256, Iteration <COUNT>
PKCS7 Encrypted data
Certificate bag
Shrouded Keybag实际算法、迭代次数和对象数量可能不同;出现 Mac verify error 通常表示口令错误或文件损坏。
提取证书、私钥和 CA 链
下面的示例会多次询问导入口令,并为导出的私钥设置新的 PEM 口令:
set -euo pipefail
P12_FILE="app.p12"
openssl pkcs12 -in "$P12_FILE" -clcerts -nokeys -out server.crt
openssl pkcs12 -in "$P12_FILE" -nocerts -out server.key.encrypted
openssl pkcs12 -in "$P12_FILE" -cacerts -nokeys -out ca-chain.crt
chmod 600 server.key.encrypted
for f in server.crt server.key.encrypted ca-chain.crt; do
test -s "$f" && printf '%s OK\n' "$f"
done预期输出:
Enter Import Password:
Enter Import Password:
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
Enter Import Password:
server.crt OK
server.key.encrypted OK
ca-chain.crt OKserver.crt 可能包含 Bag Attributes,不影响 OpenSSL 和多数服务读取;ca-chain.crt 为空时,容器可能没有附带中间证书。
按需生成未加密私钥
只有目标服务无法交互输入口令时才执行。生成后立即限制权限,并避免把文件提交到代码仓库或普通备份目录:
openssl pkey -in server.key.encrypted -out server.key
chmod 600 server.key
test -s server.key && echo "server.key OK"预期输出:
Enter pass phrase for server.key.encrypted:
server.key OKOpenSSL 3.x 也可在导出时使用 -noenc;较老版本常见 -nodes。两者都会直接产生未加密私钥,风险高于先导出加密私钥再转换。
验证证书与私钥匹配
比较两者公钥的 SHA-256 摘要;结果一致才可配对部署:
cert_hash=$(openssl x509 -in server.crt -pubkey -noout \
| openssl pkey -pubin -outform DER \
| openssl sha256)
key_hash=$(openssl pkey -in server.key.encrypted -pubout -outform DER \
| openssl sha256)
printf 'cert=%s\nkey=%s\n' "$cert_hash" "$key_hash"
test "$cert_hash" = "$key_hash" && echo "MATCH"预期输出:
Enter pass phrase for server.key.encrypted:
cert=SHA2-256(stdin)= <HASH>
key=SHA2-256(stdin)= <HASH>
MATCH<HASH> 为动态值;若没有 MATCH,不要部署,应重新确认 P12 内是否包含多组证书和私钥。
风险与排障
不要使用 -passin pass:明文口令,它可能进入 Shell 历史或进程列表;优先交互输入,自动化场景使用权限为 600 的口令文件。出现 unsupported、legacy cipher 或 RC2 错误时,可临时增加 -legacy 读取旧 P12,但应立即重新打包为现代算法,而不是长期依赖兼容模式。
按正确顺序组合服务器证书和中间证书,生成完整链文件。
合并证书链文件
用于生成服务器可直接加载的完整链文件。顺序必须是“叶子证书 → 签发它的中间证书 → 更上级中间证书”;通常不要把根证书放进线上 fullchain。
合并顺序
先确认每个文件都是 PEM 证书,再按签发关系从叶子向根方向追加。以下示例包含一个服务器证书和两个中间证书:
set -euo pipefail
leaf="server.crt"
chain=(intermediate-1.crt intermediate-2.crt)
out="fullchain.crt"
: > "$out"
for f in "$leaf" "${chain[@]}"; do
openssl x509 -in "$f" -noout
cat "$f" >> "$out"
printf '\n' >> "$out"
done
count=$(grep -c '^-----BEGIN CERTIFICATE-----$' "$out")
printf 'certificate_count=%s\n' "$count"预期输出:
certificate_count=3若任一文件不是有效 PEM,脚本会在合并前失败;证书数量应等于叶子证书加实际中间证书数量。
检查链条方向
查看每张证书的 subject 和 issuer。前一张的 issuer 应与后一张的 subject 对应:
openssl crl2pkcs7 -nocrl -certfile fullchain.crt \
| openssl pkcs7 -print_certs -noout预期输出:
subject=<LEAF_SUBJECT>
issuer=<INTERMEDIATE_1_SUBJECT>
subject=<INTERMEDIATE_1_SUBJECT>
issuer=<INTERMEDIATE_2_SUBJECT>
subject=<INTERMEDIATE_2_SUBJECT>
issuer=<ROOT_SUBJECT>名称格式会随 OpenSSL 版本和证书内容变化;重点读取相邻证书的签发关系,而不是逐字比较显示格式。
验证完整链
根证书只用于本地信任验证,不需要追加到部署文件。将中间证书单独组成 -untrusted 链后验证叶子证书:
cat intermediate-1.crt intermediate-2.crt > intermediates.crt
openssl verify -CAfile root-ca.crt \
-untrusted intermediates.crt \
server.crt预期输出:
server.crt: OK若出现 unable to get local issuer certificate,优先检查是否缺少中间证书或顺序错误;出现 certificate has expired 时应更换对应证书,重新拼接不能修复过期问题。
风险与边界
把中间证书放错顺序、遗漏中间证书或混入另一条交叉签名链,可能导致部分客户端握手失败,而浏览器因缓存证书仍表现正常。安全替代方案是使用 CA 明确提供的链包,并通过 openssl verify 在干净环境验证。
不要把私钥追加到通用 fullchain.crt。Nginx 等服务通常要求证书链和私钥分开配置;只有明确要求单一 PEM 的组件才可另建专用文件,并将权限限制为 600。根证书通常由客户端信任库提供,附加到线上链只会增加体积,且不能让未受信任根自动变可信。
兼容性
OpenSSL 1.1.1 与 3.x 均支持上述 x509、pkcs7 和 verify 用法。Nginx 的证书文件按叶子到中间证书顺序加载;其他服务器若要求单独的 chain 文件,应从 fullchain.crt 中去掉第一张叶子证书后再配置。
将包含多个证书的 PEM 文件拆分为独立证书并识别其角色。
拆分 PEM 证书链
当 chain.pem 同时包含服务器证书和多个 CA 证书时,先按证书边界拆成独立文件,再根据 Basic Constraints、Subject 和 Issuer 判断角色。拆分只改变文件组织,不代表证书链已经通过信任验证。
命令定位
PEM 证书块由 -----BEGIN CERTIFICATE----- 和 -----END CERTIFICATE----- 包围。awk 负责按块写文件,openssl x509 负责读取证书元数据;不要仅凭原文件中的排列顺序认定叶子证书、中间 CA 或根 CA。
高频用法
下面的脚本在临时目录中生成 cert-01.pem、cert-02.pem 等文件,避免覆盖当前目录里的同名文件,并为每张证书给出初步角色。
out_dir=$(mktemp -d)
awk -v out="$out_dir" '
/-----BEGIN CERTIFICATE-----/ {
n++
file=sprintf("%s/cert-%02d.pem", out, n)
in_cert=1
}
in_cert { print > file }
/-----END CERTIFICATE-----/ {
close(file)
in_cert=0
}
' chain.pem
set -- "$out_dir"/cert-*.pem
[ -e "$1" ] || { echo "no certificate blocks found" >&2; exit 1; }
for f in "$@"; do
subject=$(openssl x509 -in "$f" -noout -subject -nameopt RFC2253 | sed 's/^subject=//')
issuer=$(openssl x509 -in "$f" -noout -issuer -nameopt RFC2253 | sed 's/^issuer=//')
if openssl x509 -in "$f" -noout -ext basicConstraints | grep -q 'CA:TRUE'; then
[ "$subject" = "$issuer" ] && role="root CA candidate" || role="intermediate CA"
else
role="leaf/end-entity"
fi
printf '%s\n role=%s\n subject=%s\n issuer=%s\n' "$f" "$role" "$subject" "$issuer"
done预期输出
<PATH>/cert-01.pem
role=leaf/end-entity
subject=CN=www.example.com
issuer=CN=Example Intermediate CA
<PATH>/cert-02.pem
role=intermediate CA
subject=CN=Example Intermediate CA
issuer=CN=Example Root CA
<PATH>/cert-03.pem
role=root CA candidate
subject=CN=Example Root CA
issuer=CN=Example Root CA<PATH> 是 mktemp 创建的动态目录,实际 Subject、Issuer 和证书数量会不同。叶子证书通常为 CA:FALSE 或没有 Basic Constraints;中间 CA 为 CA:TRUE 且 Subject 与 Issuer 不同;Subject 等于 Issuer 只能说明“自签名候选”,不能单独证明签名有效。
将文件按角色重命名后,用可信根证书验证完整链。根证书经常不会包含在服务器发送的链中,此时应从可信来源单独取得 root.pem。
openssl verify -CAfile root.pem -untrusted intermediate.pem leaf.pem预期输出
leaf.pem: OK风险与边界
若原 PEM 同时含私钥,脚本会忽略私钥块,但原文件仍属于敏感材料;应保持最小权限并避免复制到公共目录。若证书块缺少结束标记,可能生成不完整文件,后续会出现 unable to load certificate 或解析错误。
不要把 Subject 与 Issuer 相等直接当作可信根,也不要把“拆分成功”当作“链验证成功”。安全做法是保留可信根、把中间证书通过 -untrusted 提供,并以 openssl verify 的结果为准。
排障清单
出现 no certificate blocks found 时,先确认输入是否为 DER、PKCS#7,或使用了 BEGIN TRUSTED CERTIFICATE 头;这些格式不能直接套用本脚本。出现 unable to get local issuer certificate 时,通常是缺少中间证书、根证书不匹配,或叶子与中间证书并非同一条签发链。
兼容性
脚本适用于 Linux、macOS、WSL 和常见 POSIX Shell。OpenSSL 1.1.1 与 3.x 均可使用核心命令;若旧版本不支持 openssl x509 -ext basicConstraints,改用 openssl x509 -text -noout 查看 Basic Constraints。
为未加密私钥添加口令保护并选择合适的加密算法。
加密私钥
当 server.key 是无口令 PEM 私钥时,优先生成新的加密副本并验证后再替换,而不是直接覆盖原文件。通用选择是 PKCS#8、PBES2、PBKDF2 与 AES-256-CBC,可同时支持 RSA、EC 等常见私钥类型。
前置检查
先确认私钥本身可解析,并检查调用它的服务是否支持启动时读取口令。无人值守服务若没有密钥代理、秘密挂载或交互式解锁能力,加密后可能在重启时无法启动。
openssl pkey -in server.key -noout -check预期输出
Key is valid如果输入已经加密,命令会先提示输入原口令;若输出 Could not read key,应先确认文件格式、口令和权限,不要继续覆盖。
高频用法
下面使用临时文件生成加密 PKCS#8 私钥,显式选择 AES-256-CBC,并把 PBKDF2 迭代次数设为 200000。验证成功后再移动到目标文件,命令中断时 trap 会清理未完成文件。
umask 077
tmp=$(mktemp ./server.encrypted.key.XXXXXX)
trap 'rm -f "$tmp"' EXIT
openssl pkcs8 -topk8 \
-in server.key \
-out "$tmp" \
-v2 aes-256-cbc \
-iter 200000
openssl pkey -in "$tmp" -noout -check
mv "$tmp" server.encrypted.key
trap - EXIT
head -n 1 server.encrypted.key预期输出
Enter Encryption Password:
Verifying - Enter Encryption Password:
Enter pass phrase for ./server.encrypted.key.<ID>:
Key is valid
-----BEGIN ENCRYPTED PRIVATE KEY-----<ID> 是 mktemp 生成的动态后缀,提示词在不同 OpenSSL 版本中可能略有差异。最终首行应为 BEGIN ENCRYPTED PRIVATE KEY,文件权限应保持为仅属主可读写。
加密前后公钥摘要必须一致;摘要不同表示使用了错误的源文件或替换了另一把私钥。
old_fp=$(openssl pkey -in server.key -pubout -outform DER | openssl sha256 | awk '{print $NF}')
new_fp=$(openssl pkey -in server.encrypted.key -pubout -outform DER | openssl sha256 | awk '{print $NF}')
printf 'old=%s\nnew=%s\n' "$old_fp" "$new_fp"预期输出
Enter pass phrase for server.encrypted.key:
old=<HEX>
new=<HEX>两行 <HEX> 必须完全相同。实际摘要值取决于私钥;验证完成前不要删除或覆盖原始文件。
常用参数
-topk8 输出 PKCS#8;-v2 aes-256-cbc 使用 PBES2 与 AES-256-CBC;-iter 设置口令派生迭代次数,数值越高越抗暴力破解,但服务解锁越慢。-passin 与 -passout 可指定口令来源,自动化场景优先使用权限为 600 的临时秘密文件或秘密管理器挂载。
-traditional 会输出旧式算法专用 PEM,仅在遗留程序无法读取 PKCS#8 时使用。不要为新系统选择 DES、3DES 或 -noiter;这些选项会降低安全性或只为兼容旧软件服务。
风险与边界
服务不支持口令解锁时,加密私钥会导致重启失败和业务中断;安全替代方案是先在预发布环境验证加载方式,或使用密钥代理、HSM、TPM、systemd credential、容器 Secret 等受控解锁机制。若必须无人值守使用明文私钥,至少限制为专用账户和 600 权限,并缩小主机访问面。
口令丢失会使私钥不可恢复,应先把口令托管到秘密管理系统并执行一次恢复测试。不要使用 -passout pass:明文,口令可能进入 Shell 历史或进程参数;环境变量也可能被诊断工具、崩溃转储或子进程读取。
加密不会消除已经泄露的明文副本,SSD、快照和写时复制文件系统上也不能保证安全擦除。若私钥曾暴露,应生成新私钥、重新签发证书并撤销旧证书,而不是只给旧文件加口令。
兼容性
openssl pkcs8 和 openssl pkey 适用于 OpenSSL 1.1.1 与 3.x。部分旧中间件、脚本或硬件设备不能读取 PBES2 加密的 PKCS#8,迁移前必须实际加载验证;兼容性要求不明确时,保留 PKCS#8 作为主格式,不要默认降级。
为需要无人值守启动的服务生成无口令私钥并控制文件风险。
移除私钥口令
用于把受口令保护的 PEM 私钥转换为无口令私钥,供 systemd、Nginx、Java 网关等无人值守进程启动。转换只移除文件层的加密保护,不会重新生成密钥对;OpenSSL 官方示例使用 openssl pkey -in key.pem -out keyout.pem。:contentReference[oaicite:0]{index=0}
基本语法
openssl pkey -in <ENCRYPTED_KEY.pem> -out <UNENCRYPTED_KEY.pem>-in 读取原私钥;输入已加密且未提供 -passin 时会安全地交互提示口令。-out 必须使用不同文件名,默认写出 PEM;未指定输出加密算法时,生成的私钥不再受口令保护。
安全转换与验证
先限制新建文件权限并保留原文件,再输出到临时文件。不要直接覆盖生产路径,验证通过后再由部署工具原子替换。
umask 077
cp -p server.key server.key.encrypted.bak
# 读取时输入原口令;输出文件不再加密
openssl pkey -in server.key -out server.key.unencrypted
chmod 600 server.key.unencrypted
# 检查私钥内部结构和公私钥组件是否一致
openssl pkey -in server.key.unencrypted -check -noout预期输出
Enter pass phrase for server.key:
Key is valid口令提示文字可能随版本和输入格式变化;关键结果是命令退出码为 0,且检查输出为 Key is valid。随后让目标服务引用临时文件执行配置检查或预启动验证,确认成功后再替换正式私钥。
常用参数
-passin fd:<N>:从已打开的文件描述符读取输入口令,适合与密钥管理器或受控脚本集成,避免把明文口令写进命令行。-passin file:<PATH>:从文件读取口令;该文件必须仅授权给运行账户,并在使用后安全删除。-traditional:写出旧式算法专用格式,仅在旧软件无法读取默认 PKCS#8 格式时使用。-check -noout:不打印私钥内容,只检查密钥一致性。
不要使用 -passin pass:<PASSWORD> 处理生产口令。触发条件是把口令直接放入命令参数;后果是口令可能进入 shell 历史、进程列表或审计日志;安全替代是交互输入、受控文件描述符或密钥管理器注入。
风险与边界
无口令私钥一旦被复制,攻击者无需额外凭据即可使用它。触发条件是文件权限过宽、备份外泄、镜像打包或日志误收集;后果可能是服务身份冒用和新连接被解密或劫持;安全替代是优先使用 HSM、TPM、KMS、systemd credentials 或受权限控制的临时密钥挂载。
不要把 -out 指向原输入文件。触发条件是边读边覆盖同一路径;后果可能是文件被截断且无法恢复;安全替代是写入同目录临时文件,完成 -check 和服务配置验证后再原子替换,并保留加密备份直至变更确认。
排障清单
- 出现
Could not read key:确认文件路径、PEM 头尾、读取权限和私钥格式。 - 出现
bad decrypt或口令反复失败:确认输入的是私钥口令,而不是 PKCS#12 导出口令或证书库口令。 - 服务仍提示输入口令:检查服务实际加载的路径、软链接目标、容器挂载和重载是否生效。
- 服务报密钥与证书不匹配:分别导出证书和私钥的公钥摘要进行比对,不要继续上线。
现代版本优先使用通用的 openssl pkey;仅在遗留 RSA 工具链中使用 openssl rsa -in server.key -out server.key.unencrypted。
检查远程服务的握手过程、协议版本、密码套件和证书链。
测试 TLS 握手
使用 openssl s_client 从当前主机直接连接远端服务,确认 TCP 可达、SNI、协商协议、密码套件、证书链和本地信任校验。它是诊断客户端,不等同于业务程序的 DNS、代理、信任库和客户端证书配置。:contentReference[oaicite:1]{index=1}

基本语法
openssl s_client \
-connect <HOST>:<PORT> \
-servername <DNS_NAME> \
-verify_return_error \
-verify_hostname <DNS_NAME> \
-brief </dev/null-connect 决定实际网络目标,-servername 写入 ClientHello 的 SNI,二者在负载均衡、CDN 或同 IP 多证书场景中可能不同。</dev/null 在握手输出后关闭标准输入,避免命令停留在交互状态。
查看协商结果
下面示例连接 example.com:443,要求证书链校验和主机名校验成功,并只显示关键协商参数。
openssl s_client \
-connect example.com:443 \
-servername example.com \
-verify_return_error \
-verify_hostname example.com \
-brief </dev/null预期输出
CONNECTION ESTABLISHED
Protocol version: TLSv1.3
Ciphersuite: <CIPHER>
Peer certificate: <SUBJECT>
Verification: OK
Server Temp Key: <KEY-EXCHANGE>
DONE<CIPHER>、<SUBJECT> 和 <KEY-EXCHANGE> 会随服务配置变化。读取时先看 Verification: OK,再确认 Protocol version 和 Ciphersuite 是否符合预期;命令退出码为 0 才表示本次严格验证通过。
查看服务端发送的证书链
-showcerts 按服务端发送顺序打印证书列表,但该列表本身不是已经验证完成的信任链。:contentReference[oaicite:2]{index=2}
openssl s_client \
-connect example.com:443 \
-servername example.com \
-showcerts </dev/null预期输出
CONNECTED(<ID>)
Certificate chain
0 s:<LEAF_SUBJECT>
i:<INTERMEDIATE_ISSUER>
-----BEGIN CERTIFICATE-----
<CERTIFICATE_DATA>
-----END CERTIFICATE-----
...
Verify return code: 0 (ok)重点检查编号 0 是否为站点证书、后续是否包含所需中间证书,以及末尾 Verify return code。根证书通常不应由服务端发送;0 (ok) 只代表当前主机所用信任库完成了验证。
协议与 STARTTLS 测试
强制协议版本可定位“服务不支持”还是“自动协商失败”。将 -tls1_3 改为 -tls1_2 即可分别测试;SMTP、IMAP、PostgreSQL 等明文升级协议必须使用 -starttls <PROTOCOL>,不能直接把端口当作原生 TLS。
openssl s_client \
-connect example.com:443 \
-servername example.com \
-tls1_3 \
-brief </dev/null预期输出
CONNECTION ESTABLISHED
Protocol version: TLSv1.3
Ciphersuite: <TLS13_CIPHER>
Verification: OK
DONE若服务不支持指定版本,通常会出现 handshake failure、protocol version 或连接被关闭。不要据单次公网测试断言全局故障,应从与业务程序相同的网络、DNS 和代理路径复测。
高频参数
| 参数 | 用途 |
|---|---|
-brief |
只显示协议、套件、证书主体和验证结果等摘要 |
-showcerts |
打印服务端实际发送的证书列表 |
-verify_return_error |
遇到证书验证错误立即失败,而不是继续握手 |
-verify_hostname <NAME> |
按目标 DNS 名校验证书 SAN/CN |
-tls1_2、-tls1_3 |
固定协议版本,定位兼容性问题 |
-starttls smtp |
先执行应用协议升级,再开始 TLS 握手 |
-cert、-key |
测试需要客户端证书的双向 TLS |
排障清单
wrong version number:常见于连接了明文 HTTP 端口、代理端口或遗漏-starttls;先确认监听协议和端口。no peer certificate available:服务端在发证书前关闭连接;检查 SNI、负载均衡健康状态、访问控制和协议版本。unable to get local issuer certificate:服务端缺少中间证书或本机信任库不完整;补齐服务端链,或用正确 CA 文件复测。hostname mismatch:连接地址、-servername、-verify_hostname与证书 SAN 不一致;按业务实际域名测试,不要用关闭校验代替修复。no shared cipher或handshake failure:客户端和服务端在协议、密码套件、签名算法或密钥组上没有交集;分别固定 TLS 1.2/1.3 并检查服务端策略。
s_client 成功只证明当前测试主机的这条路径可用。业务仍失败时,对齐应用使用的 DNS 结果、出口代理、CA 信任库、TLS 库版本、客户端证书和 ALPN;涉及 mTLS 时,私钥文件必须按最小权限保护。
定位缺少中间证书、链顺序错误或根证书误下发等问题。
排查证书链不完整
用于定位服务端漏发中间证书、证书顺序错误或把根证书错误地放入下发链的问题。最终应确认服务端按“站点证书 → 最近的中间证书 → 更上级中间证书”发送,根证书留在客户端信任库中。
命令定位
先从客户端实际抓取 TLS 握手中的证书链。-servername 用于发送 SNI,未指定时可能拿到负载均衡器的默认证书;-showcerts 展示服务端实际发送的全部证书,而不是 OpenSSL 自动补全后的链。
openssl s_client \
-connect example.com:443 \
-servername example.com \
-showcerts </dev/null预期输出
Certificate chain
0 s:CN = example.com
i:CN = <INTERMEDIATE_CA>
1 s:CN = <INTERMEDIATE_CA>
i:CN = <ROOT_CA>
Verify return code: 0 (ok)CA 名称和字段顺序会随站点变化。编号 0 应为站点证书,后续编号依次为中间证书;Verify return code: 0 (ok) 表示当前客户端能够构建可信链。若出现 20 (unable to get local issuer certificate) 或 21 (unable to verify the first certificate),通常需要继续检查中间证书或客户端信任库。
输出字段说明
subject 表示当前证书属于谁,issuer 表示由谁签发。链中上一张证书的 issuer 应与下一张证书的 subject 对应;仅比较 CN 不够严谨,排障时以完整名称和证书指纹为准。
服务端通常不应发送根证书。根证书是客户端预置信任锚,附加到链尾不会让不信任该根的客户端自动信任,只会增加握手数据。若输出只有编号 0,而其签发者不是客户端直接信任的根,通常就是缺少中间证书。
高频用法
把站点证书、中间证书和根证书分别保存后,用明确的信任锚在本地复现验证。-untrusted 提供服务端应发送的中间证书,-CAfile 只放受信任根证书。
openssl verify \
-show_chain \
-CAfile root-ca.pem \
-untrusted intermediates.pem \
leaf.pem缺少中间证书时的预期输出
CN = api.example.com
error 20 at 0 depth lookup: unable to get local issuer certificate
error leaf.pem: verification failed补齐正确中间证书后的预期输出
leaf.pem: OK
Chain:
depth=0: CN = api.example.com
depth=1: CN = <INTERMEDIATE_CA>
depth=2: CN = <ROOT_CA>重建服务端链文件时,先放站点证书,再按离站点最近到最远的顺序追加中间证书。下面示例只有一张中间证书;存在多级中间证书时继续向后追加,但不要追加根证书。
cat leaf.pem intermediate.pem > fullchain.pem
openssl crl2pkcs7 -nocrl -certfile fullchain.pem |
openssl pkcs7 -print_certs -noout预期输出
subject=CN = api.example.com
issuer=CN = Example Intermediate CA
subject=CN = Example Intermediate CA
issuer=CN = Example Root CA读取时确认第一张是站点证书,第二张的 subject 与第一张的 issuer 对应。修改 Nginx、Apache、HAProxy、Ingress 或云负载均衡器配置后,必须重新加载服务并再次运行 s_client,不能只检查本地文件。
风险与边界
当私有 CA 的根证书未安装在客户端时,即使服务端中间链完整,仍会得到验证失败。安全做法是用 -CAfile 指定正确根证书复测,或在受控环境安装企业根证书;不要关闭证书验证来掩盖问题。
当多个后端节点、多个监听器或 CDN 边缘节点使用不同证书配置时,单次检查可能只命中正常节点。应按目标 IP 分别连接并保持相同 SNI,确认每个节点发送的链一致。错误顺序可能被部分客户端自动修复,却会在旧版 Java、嵌入式设备或严格验证器中失败。
排障清单
- 用
s_client -showcerts获取线上真实下发链,不以服务器磁盘文件代替。 - 确认编号
0是站点证书,后续证书按签发关系连续排列。 - 用正确根证书和中间证书执行
openssl verify -show_chain。 - 重新生成仅含站点证书和中间证书的
fullchain.pem,不要附加私钥或根证书。 - 重载服务后再次从客户端验证;返回码仍非
0时,再检查客户端信任库、SNI、DNS 和多节点配置。
处理无法读取证书、错误 PEM 标记、换行损坏和格式不匹配问题。
排查证书格式错误
用于处理 openssl x509 无法读取证书、PEM 起止标记错误、文件被截断、BOM 或换行污染,以及把 DER、CSR、私钥、PKCS#7、PKCS#12 误当作普通证书的问题。最终应确定真实容器类型,并转换成可被目标程序读取的 PEM 或 DER。
快速判定
文件扩展名不能决定编码格式,.cer、.crt 和 .pem 都可能保存 PEM 或 DER。下面脚本先按 PEM 解析,再按 DER 解析;成功时会输出检测到的格式和证书主题。
CERT="cert.bin"
if openssl x509 -in "$CERT" -noout >/dev/null 2>&1; then
echo "format=PEM"
openssl x509 -in "$CERT" -noout -subject
elif openssl x509 -inform DER -in "$CERT" -noout >/dev/null 2>&1; then
echo "format=DER"
openssl x509 -inform DER -in "$CERT" -noout -subject
else
echo "format=unknown-or-damaged"
fiPEM 证书的预期输出
format=PEM
subject=CN = api.example.comDER 证书会输出 format=DER。若得到 format=unknown-or-damaged,文件可能不是 X.509 证书,也可能已截断或混入非法字符,应先核对来源和文件大小,不要直接修改正文。
PEM 标记与换行
标准 PEM 证书必须使用完全匹配的起止行,正文为 Base64 数据。先检查标记位置,避免把 BEGIN CERTIFICATE REQUEST、BEGIN PRIVATE KEY 或其他对象误改成证书标记。
grep -nE -- '-----BEGIN |-----END ' cert.pem预期输出
1:-----BEGIN CERTIFICATE-----
28:-----END CERTIFICATE-----普通 CRLF 换行通常不会导致 OpenSSL 失败,常见破坏源是 UTF-8 BOM、复制时插入的非 ASCII 字符、起止标记被改写或 Base64 正文被截断。下面命令保留原文件,只移除开头 BOM 并统一换行,再让 OpenSSL 重写为规范 PEM;若正文已损坏,验证步骤仍会失败,不会生成可用证书。
python3 - <<'PY'
from pathlib import Path
src = Path("cert.pem")
dst = Path("cert.normalized.pem")
raw = src.read_bytes()
if raw.startswith(b"\xef\xbb\xbf"):
raw = raw[3:]
text = raw.decode("ascii").replace("\r\n", "\n").replace("\r", "\n")
dst.write_bytes(text.encode("ascii"))
PY
openssl x509 \
-in cert.normalized.pem \
-out cert.canonical.pem
openssl x509 \
-in cert.canonical.pem \
-noout \
-subject \
-issuer预期输出
subject=CN = api.example.com
issuer=CN = Example Intermediate CA如果 Python 报 UnicodeDecodeError,说明文件仍含非 ASCII 字节;应回到原始签发系统重新导出,或逐字确认污染位置,而不是用 tr -cd 等命令无差别删除字符。
高频转换
确认输入确实是 X.509 证书后,再进行 PEM 与 DER 转换。重命名扩展名不会改变编码,必须使用 -inform 或 -outform。
openssl x509 \
-inform DER \
-in cert.der \
-out cert.pem
openssl x509 \
-in cert.pem \
-noout \
-subject \
-issuer预期输出
subject=CN = api.example.com
issuer=CN = Example Intermediate CA反向转换为 DER 并立即验证:
openssl x509 \
-in cert.pem \
-outform DER \
-out cert.der
openssl x509 \
-inform DER \
-in cert.der \
-noout \
-serial预期输出
serial=<SERIAL_HEX><SERIAL_HEX> 为证书真实序列号,实际值不同。转换只改变编码容器,不会改变主题、签发者、序列号、有效期或公钥。
错误对照
Could not read certificate、Unable to load certificate 或 no start line 常见于输入不是 PEM、起始标记错误、文件带 BOM,或实际对象是 CSR、私钥等。bad base64 decode 多表示正文含非法字符或被截断;wrong tag、nested asn1 error 常见于把其他 DER 对象当作 X.509 证书解析。
对象类型不匹配时应改用对应子命令:CSR 使用 openssl req -in request.csr -noout -subject,私钥使用 openssl pkey -in private.key -noout -check,PKCS#7 使用 openssl pkcs7 -in chain.p7b -print_certs -noout,PKCS#12 使用 openssl pkcs12 -in bundle.p12 -info -noout。不能通过替换 PEM 标签把这些对象“变成”证书,因为内部 ASN.1 结构不同。
风险与边界
不要直接覆盖原文件。触发条件是尝试修复 BOM、换行或标签时;一旦误删 Base64 字符,证书将永久损坏且难以追踪。安全做法是始终写入新文件,并用 openssl x509 -noout -subject -issuer -serial 验证后再替换生产配置。
openssl x509 对包含多张证书的 PEM 文件通常只处理第一张,不能据此判断整个证书包都有效。证书链文件应逐张检查,或用 openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout 列出全部证书。
OpenSSL 1.1.1 与 3.x 的错误文字可能不同,但 x509 -inform DER、x509 -outform DER 和上述验证方式保持一致。若格式正确仍无法被应用读取,再检查应用是否要求单证书、完整链、特定文件权限或独立私钥路径。
定位服务启动时证书与私钥不匹配或密钥类型不兼容的问题。
排查私钥不匹配
用于处理服务启动时报 key values mismatch、private key does not match the certificate,或证书能读取但私钥加载失败。先确认两个文件都能解析,再比较它们导出的公钥;公钥摘要一致才表示证书与私钥成对。
快速判定
下面的方法同时适用于 RSA、EC、Ed25519 等 openssl pkey 可读取的密钥类型,比仅比较 RSA modulus 更通用。脚本会在解析失败时立即退出;私钥加密时由 OpenSSL 交互式询问口令。
set -euo pipefail
cert="server.crt"
key="server.key"
cert_hash="$(
openssl x509 -in "$cert" -noout -pubkey |
openssl pkey -pubin -outform DER 2>/dev/null |
openssl dgst -sha256 -r |
awk '{print $1}'
)"
key_hash="$(
openssl pkey -in "$key" -pubout -outform DER 2>/dev/null |
openssl dgst -sha256 -r |
awk '{print $1}'
)"
printf 'certificate: %s\nprivate-key: %s\n' "$cert_hash" "$key_hash"
if [ "$cert_hash" = "$key_hash" ]; then
echo "result: MATCH"
else
echo "result: MISMATCH"
exit 1
fi预期输出(摘要实际值会不同):
certificate: <SHA256_HEX>
private-key: <SHA256_HEX>
result: MATCH两行摘要不同即为文件配错,不能通过改权限、重启服务或重新排列证书链解决。应找到对应私钥,或用正确私钥重新签发证书。
分别检查文件
先排除文件格式、口令和内容损坏。命令只验证可解析性与私钥内部一致性,不会证明两者匹配。
cert="server.crt"
key="server.key"
openssl x509 -in "$cert" -noout >/dev/null &&
openssl pkey -in "$key" -check -noout >/dev/null &&
echo "certificate-and-key-parse-ok"预期输出:
certificate-and-key-parse-ok若证书报 Unable to load certificate,检查 PEM/DER 格式、文件内容和路径。若私钥报 Could not read key、bad decrypt 或口令提示后失败,检查密钥格式、口令来源以及服务是否支持非交互式解密。
定位服务实际加载的文件
摘要匹配但服务仍报错时,重点检查“命令验证的文件”和“服务实际读取的文件”是否相同。确认生效配置、软链接目标、容器挂载、Kubernetes Secret 版本及证书部署目录,不要只看编辑过的配置文件。
readlink -f server.crt
readlink -f server.key
stat -c '%n inode=%i size=%s mode=%a owner=%U:%G' server.crt server.key预期输出(路径、inode 和权限会不同):
<PATH>/server.crt inode=<ID> size=<BYTES> mode=644 owner=<USER>:<GROUP>
<PATH>/server.key inode=<ID> size=<BYTES> mode=600 owner=<USER>:<GROUP>读取方法:软链接应指向本次发布文件;私钥通常只授予服务账户或专用组读取。若部署后 inode 未变化,可能仍挂载旧 Secret、旧卷或旧发布目录。
风险与边界
不要为排障执行 chmod 777、把私钥复制到公共目录,或在终端、工单和 CI 日志中输出私钥正文。触发条件是服务账户无权读取或口令无法注入;后果是私钥泄露或扩大主机横向风险。安全替代方案是修正属主、最小化组权限、使用受控 Secret 挂载,并在服务账户身份下验证读取权限。
证书链顺序错误通常会导致链验证失败,但不会改变叶子证书与私钥的公钥匹配结果。若摘要已一致仍提示算法不兼容,应检查服务版本、加密提供程序、FIPS 模式以及是否支持 RSA-PSS、Ed25519 或所用 EC 曲线。
排障清单
- 用
openssl x509和openssl pkey -check确认两个文件都能解析。 - 比较 DER 公钥的 SHA-256 摘要,确认结果为
MATCH。 - 核对服务生效配置、软链接、容器卷和 Secret,而非只核对源文件。
- 检查加密私钥的口令注入方式及服务启动环境。
- 匹配仍失败时,查看算法、FIPS/provider 限制和服务端具体错误日志。
检查协议版本、密码套件、SNI 和安全级别导致的握手失败。
排查 TLS 协议失败
用于定位连接被协议版本、密码套件、SNI 或安全级别拒绝的问题。先用带 SNI 的基线连接确认错误,再一次只改变一个条件;不要同时放宽协议、密码套件和安全级别,否则无法判断真正原因。

基线连接
使用域名同时作为连接目标和 SNI。-brief 保留关键协商结果,-verify_return_error 让证书验证错误直接导致失败,-verify_hostname 校验目标域名,</dev/null 防止命令等待标准输入。
host="example.com"
port="443"
openssl s_client \
-connect "${host}:${port}" \
-servername "$host" \
-brief \
-verify_return_error \
-verify_hostname "$host" \
</dev/null预期输出(协议、套件和证书内容会随站点变化):
CONNECTION ESTABLISHED
Protocol version: TLSv1.<N>
Ciphersuite: <CIPHER_SUITE>
Verification: OK若立即出现 wrong version number,优先确认端口是否实际提供明文 HTTP、SMTP 等协议,以及中间代理是否要求 STARTTLS;这类错误不等同于“服务器只支持旧 TLS”。
隔离协议版本
分别强制 TLS 1.3 和 TLS 1.2,判断双方是否存在共同协议。不要用已废弃协议作为长期修复方案。
host="example.com"
port="443"
for protocol in tls1_3 tls1_2; do
echo "== ${protocol} =="
openssl s_client \
-connect "${host}:${port}" \
-servername "$host" \
"-${protocol}" \
-brief \
</dev/null 2>&1 |
grep -E 'CONNECTION ESTABLISHED|Protocol version:|Ciphersuite:|alert protocol version|handshake failure|error:'
done预期输出示例之一:
== tls1_3 ==
CONNECTION ESTABLISHED
Protocol version: TLSv1.3
Ciphersuite: <TLS13_CIPHER_SUITE>
== tls1_2 ==
<ERROR_LINE>读取方法:某一版本成功、另一版本收到 alert protocol version,说明版本边界不重合或服务端禁用了该版本;两者都失败时继续检查 SNI、套件、证书算法和安全策略。
区分 TLS 1.2 与 TLS 1.3 套件
-cipher 控制 TLS 1.2 及更早版本;-ciphersuites 控制 TLS 1.3。两个选项不可互相替代。
host="example.com"
port="443"
openssl s_client \
-connect "${host}:${port}" \
-servername "$host" \
-tls1_2 \
-cipher 'ECDHE+AESGCM' \
-brief \
</dev/null
openssl s_client \
-connect "${host}:${port}" \
-servername "$host" \
-tls1_3 \
-ciphersuites 'TLS_AES_128_GCM_SHA256' \
-brief \
</dev/null预期输出(两次命令都成功时):
Protocol version: TLSv1.2
Ciphersuite: <TLS12_CIPHER_SUITE>
Protocol version: TLSv1.3
Ciphersuite: TLS_AES_128_GCM_SHA256若出现 no shared cipher 或通用 handshake failure,还需检查证书签名算法、密钥类型、支持组和服务端策略,不能只依据错误文字认定为套件问题。
检查 SNI
同一 IP 承载多个站点时,遗漏或错误的 -servername 可能命中默认证书、错误虚拟主机,甚至被服务器拒绝。连接 IP 时仍应把真实域名放入 SNI。
ip="<SERVER_IP>"
host="api.example.com"
port="443"
openssl s_client \
-connect "${ip}:${port}" \
-servername "$host" \
-brief \
</dev/null预期结果:
CONNECTION ESTABLISHED
Protocol version: TLSv1.<N>
Ciphersuite: <CIPHER_SUITE><SERVER_IP> 必须替换为实际地址。若带正确 SNI 成功、不带 SNI 失败或返回其他证书,根因在虚拟主机/SNI 路由,而不是客户端密码套件。
安全级别诊断
仅在复现隔离环境中临时降低 TLS 1.2 安全级别。若默认配置失败而 @SECLEVEL=1 成功,常见原因是弱 DH 参数、过短密钥或弱签名;长期修复应升级服务端参数和证书。
host="example.com"
port="443"
openssl s_client \
-connect "${host}:${port}" \
-servername "$host" \
-tls1_2 \
-cipher 'DEFAULT:@SECLEVEL=1' \
-brief \
</dev/null预期输出(诊断连接成功时):
CONNECTION ESTABLISHED
Protocol version: TLSv1.2
Ciphersuite: <CIPHER_SUITE>触发条件是默认安全策略拒绝对端参数;可能后果是放宽后接受弱算法,增加降级、破解或合规风险。安全替代方案是更新证书密钥与签名算法、使用足够强的 DH/EC 参数并升级旧服务,禁止把降低安全级别写入全局生产配置。
排障清单
- 确认端口确实是直接 TLS,STARTTLS 服务使用对应
-starttls参数。 - 基线命令始终携带正确
-servername。 - 分别强制 TLS 1.3 和 TLS 1.2,记录哪一步首次成功。
- TLS 1.2 使用
-cipher,TLS 1.3 使用-ciphersuites。 - 仅把降低安全级别作为临时诊断,并根据错误升级服务端参数。
certificate verify failed表示协商可能已完成,应转向证书链、信任根、主机名和时间检查;若-tls1_3或-brief不存在,先用openssl version -a确认版本并移除不支持的选项。
通过 OCSP 地址查询证书是否已被证书颁发机构吊销。
检查证书吊销状态
用于确认一张终端证书在签发机构的 OCSP 响应中是 good、revoked 还是 unknown。查询必须同时准备终端证书和直接签发它的中间 CA 证书;只有终端证书时,OCSP 请求无法正确构造或验证。
前置文件与命令定位
准备 server.pem、issuer.pem 和用于验证 OCSP 响应签名的 ca-chain.pem。先读取证书中的签发者、序列号和 OCSP 地址,确认地址不为空。
openssl x509 -in server.pem -noout -issuer -serial -ocsp_uri预期输出
issuer=<ISSUER_DN>
serial=<ID>
<OCSP_URL>最后一行是查询地址;实际签发者、序列号和 URL 会随证书变化。没有最后一行通常表示证书未声明 OCSP 服务,应改查 CA 发布的 CRL 或官方吊销查询渠道。
发起并验证 OCSP 查询
下面的命令先从证书提取 URL,再查询状态。-no_nonce 可兼容不接受 nonce 的常见公共响应器;-CAfile 用于验证响应签名,不能省略后再把结果当作可信状态。
OCSP_URL=$(openssl x509 -in server.pem -noout -ocsp_uri)
test -n "$OCSP_URL" || {
echo "证书未声明 OCSP 地址" >&2
exit 2
}
openssl ocsp \
-issuer issuer.pem \
-cert server.pem \
-url "$OCSP_URL" \
-CAfile ca-chain.pem \
-no_nonce \
-validity_period 300 \
-status_age 86400预期输出
Response verify OK
server.pem: <STATUS>
This Update: <TIME>
Next Update: <TIME>Response verify OK 表示响应签名验证通过,<STATUS> 会是 good、revoked 或 unknown。<TIME> 为响应器返回的实际时间;This Update 过旧或 Next Update 已经过期时,不应继续使用该结果。
状态判读
good 只表示响应器当前没有记录该序列号已吊销,不代表域名、有效期、用途或证书链都正确。revoked 表示已吊销,输出通常还包含吊销时间和原因,应立即停止部署并更换证书。unknown 表示响应器无法确认该证书,不能按未吊销处理。
不要只检查进程退出码。openssl ocsp 的命令执行成功不等于证书状态为 good;自动化脚本应同时匹配签名验证结果和证书状态行,并把无响应、验证失败、unknown 都归为不可判定。
风险与边界
当响应器超时、DNS 失败或被防火墙阻断时,查询结果是“无法判定”,不是“未吊销”。高可用业务可采用短时软失败并告警,强合规业务应按策略硬失败;安全替代方案是使用近期缓存且仍在有效窗口内的已验证 OCSP 响应,或检查可信 CRL。
出现 Response Verify Failure 时,先确认 issuer.pem 是否为直接签发者、ca-chain.pem 是否包含完整可信链以及系统时间是否正确。不要用 -noverify 绕过验证,否则攻击者可伪造状态响应。生产 TLS 服务还应同时检查 OCSP Stapling,因为客户端实际看到的可能是服务器缓存的装订响应。
兼容性
命令适用于常见 OpenSSL 1.1.1 与 3.x 环境。不同 CA 的响应字段和是否提供 Next Update 可能不同;先用 openssl ocsp -help 核对本机选项。若企业代理要求额外 HTTP 头,应按本机版本支持的 -header 语法配置,避免直接照搬其他版本示例。
批量检查本地证书文件或多个服务端点的剩余有效期。
批量扫描证书过期
用于把本地证书目录或多个 TLS 服务端点统一标记为 OK、WARN、EXPIRED 或错误状态。核心判断使用 openssl x509 -checkend,不依赖不同系统的 date 参数,适合放入巡检脚本和告警任务。
判定规则
openssl x509 -checkend <秒数> 在证书至少还能有效指定秒数时返回 0,否则返回非 0。扫描时先用 30 天阈值判断 OK,再用 0 秒区分“即将过期”和“已经过期”;不要把一次非 0 直接当成已过期。
扫描本地证书目录
脚本同时尝试 PEM 和 DER 解析,默认扫描 ./certs,可通过第一个参数指定目录,通过 WARN_DAYS 调整告警天数。这里没有启用 set -e,因为 -checkend 的非 0 本身就是业务判断结果。
#!/usr/bin/env bash
set -uo pipefail
CERT_DIR="${1:-./certs}"
WARN_DAYS="${WARN_DAYS:-30}"
[[ "$WARN_DAYS" =~ ^[0-9]+$ ]] || {
echo "WARN_DAYS 必须是非负整数" >&2
exit 2
}
WARN_SECONDS=$((WARN_DAYS * 86400))
x509() {
local file=$1
shift
openssl x509 -in "$file" -noout "$@" 2>/dev/null ||
openssl x509 -inform DER -in "$file" -noout "$@" 2>/dev/null
}
find "$CERT_DIR" -type f \
\( -name '*.pem' -o -name '*.crt' -o -name '*.cer' \) -print0 |
while IFS= read -r -d '' cert; do
end_date=$(x509 "$cert" -enddate) || {
printf 'INVALID\t%s\n' "$cert"
continue
}
end_date=${end_date#notAfter=}
if x509 "$cert" -checkend "$WARN_SECONDS" >/dev/null; then
state=OK
elif x509 "$cert" -checkend 0 >/dev/null; then
state=WARN
else
state=EXPIRED
fi
printf '%s\t%s\t%s\n' "$state" "$end_date" "$cert"
done预期输出
OK <TIME> ./certs/api.pem
WARN <TIME> ./certs/edge.crt
EXPIRED <TIME> ./certs/old.cer
INVALID ./certs/not-a-cert.pem<TIME> 是证书的实际 notAfter 时间,通常以 GMT 显示。WARN 表示证书当前仍有效,但剩余时间不超过阈值。
扫描多个 TLS 端点
在 endpoints.txt 中每行写一个 DNS名称:端口,例如:
example.com:443
www.example.com:443脚本显式传入 -servername,避免共享 IP 的站点返回默认证书;timeout 防止单个异常端点拖住整批任务。第一个参数可指定其他端点文件。
#!/usr/bin/env bash
set -uo pipefail
ENDPOINT_FILE="${1:-endpoints.txt}"
WARN_DAYS="${WARN_DAYS:-30}"
[[ -r "$ENDPOINT_FILE" ]] || {
echo "无法读取端点文件: $ENDPOINT_FILE" >&2
exit 2
}
[[ "$WARN_DAYS" =~ ^[0-9]+$ ]] || {
echo "WARN_DAYS 必须是非负整数" >&2
exit 2
}
WARN_SECONDS=$((WARN_DAYS * 86400))
while IFS= read -r endpoint; do
[[ -z "$endpoint" || "$endpoint" == \#* ]] && continue
host=${endpoint%:*}
cert=$(
timeout 8s openssl s_client \
-connect "$endpoint" \
-servername "$host" \
-showcerts </dev/null 2>/dev/null |
openssl x509 -outform PEM 2>/dev/null
) || {
printf 'ERROR\t%s\tTLS connection or certificate parsing failed\n' "$endpoint"
continue
}
end_date=$(printf '%s\n' "$cert" | openssl x509 -noout -enddate)
end_date=${end_date#notAfter=}
if printf '%s\n' "$cert" | openssl x509 -noout -checkend "$WARN_SECONDS" >/dev/null; then
state=OK
elif printf '%s\n' "$cert" | openssl x509 -noout -checkend 0 >/dev/null; then
state=WARN
else
state=EXPIRED
fi
printf '%s\t%s\t%s\n' "$state" "$end_date" "$endpoint"
done < "$ENDPOINT_FILE"预期输出
<STATE> <TIME> example.com:443
<STATE> <TIME> www.example.com:443<STATE> 会是 OK、WARN 或 EXPIRED,实际状态和 <TIME> 会随远端证书更新而变化。ERROR 表示网络、TLS 握手或证书解析失败,必须单独告警,不能按过期状态或正常状态合并处理。
输出与排障
OK 表示有效期超过阈值;WARN 表示仍有效但进入续期窗口;EXPIRED 表示当前已过期;INVALID 表示本地文件不是可解析证书;ERROR 表示远端扫描未取得可用证书。自动化任务应至少对后三种状态返回失败,并把 WARN 发送到续期流程。
远端结果异常时,先手工运行 openssl s_client -connect <HOST>:<PORT> -servername <HOST> -showcerts,检查 DNS、端口、SNI、代理和握手错误。本地文件异常时,用 file <PATH> 和 openssl x509 -in <PATH> -noout -text 确认格式与权限。
风险与兼容性
远端脚本只读取握手返回的第一张证书,即叶子证书;中间 CA 过期也可能导致故障,严格巡检应拆分 -showcerts 输出并逐张检查。负载均衡、CDN 或多地域 DNS 可能返回不同证书,安全替代方案是从每个实际入口、地域和 SNI 分别扫描,而不是只查一个域名一次。
GNU coreutils 环境通常提供 timeout;macOS 默认没有,可安装 GNU coreutils 后把它改为 gtimeout。脚本要求 Bash,且端点格式为域名加端口,不直接支持裸 IPv6 字面量。
设置安全的文件权限、存储位置和备份方式,降低私钥泄露风险。
保护证书私钥文件
用于把私钥放到只有目标服务可读的位置,并建立可验证、可恢复的加密备份。核心原则是:先限制目录,再限制文件;运行副本只给读取权限,备份副本必须加密,且不得与口令放在同一位置。
命令定位
umask 077 防止新文件在创建瞬间带有组或其他用户权限;install 可一次完成复制、属主和权限设置;stat 用于核对最终权限。不要只执行 chmod,父目录可遍历性、属主、ACL 和安全模块策略同样会影响实际访问。
安全落盘
推荐让私钥保持 root 所有,由专用服务组只读。目录使用 0750,私钥使用 0640;如果服务由 root 读取后再降权,私钥可进一步收紧为 0600 root:root。专用组中只能包含确实需要读取私钥的进程账号。
set -euo pipefail
KEY_SRC=./server.key
KEY_DIR=/etc/myapp/tls
KEY_DST="$KEY_DIR/server.key"
SERVICE_GROUP=myapp
test -f "$KEY_SRC"
getent group "$SERVICE_GROUP" >/dev/null
# 目录由 root 控制,服务组只能进入和读取。
sudo install -d -m 0750 -o root -g "$SERVICE_GROUP" "$KEY_DIR"
sudo install -m 0640 -o root -g "$SERVICE_GROUP" "$KEY_SRC" "$KEY_DST"
sudo stat -c 'mode=%a owner=%U group=%G path=%n' "$KEY_DIR" "$KEY_DST"预期输出:
mode=750 owner=root group=myapp path=/etc/myapp/tls
mode=640 owner=root group=myapp path=/etc/myapp/tls/server.key实际组名和路径可能不同。生成新私钥时应先设置 umask 077,避免文件在后续 chmod 前短暂暴露:
umask 077
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 \
-out server.key 2>/dev/null
stat -c 'mode=%a path=%n' server.key预期输出:
mode=600 path=server.key加密备份
运行中的未加密私钥不应直接复制到共享盘、对象存储或同步目录。先转换为带口令的 PKCS#8 备份,再保存到受控、离线或不可变介质;口令应进入独立的密码管理系统,而不是写入脚本、环境文件或同一备份目录。
set -euo pipefail
KEY=/etc/myapp/tls/server.key
BACKUP_DIR=/var/backups/myapp
BACKUP="$BACKUP_DIR/server.key.pk8"
sudo install -d -m 0700 -o root -g root "$BACKUP_DIR"
# 命令会交互式要求设置备份口令,不把口令写入命令行历史。
sudo openssl pkcs8 -topk8 -v2 aes-256-cbc -iter 200000 \
-in "$KEY" -out "$BACKUP"
sudo chmod 0600 "$BACKUP"
# 仅解密到 /dev/null,验证口令和备份文件是否可用。
sudo openssl pkcs8 -in "$BACKUP" -out /dev/null
printf 'backup verified: %s\n' "$BACKUP"预期输出:
Enter Encryption Password:
Verifying - Enter Encryption Password:
Enter Password:
backup verified: /var/backups/myapp/server.key.pk8不同 OpenSSL 版本的提示文字可能略有差异;最终命令退出码为 0 且出现 backup verified 才表示验证通过。备份后应记录恢复责任人、介质位置和轮换日期,并定期做一次不落盘或在临时隔离环境中的恢复测试。
风险与边界
- 触发条件:将私钥设置为
0644、0666、0777,或把它放进所有用户可读的目录。可能后果:同机低权限账号、被入侵进程或备份代理直接读取私钥。安全替代:使用0600,或仅对专用服务组使用0640。 - 触发条件:私钥归服务账号所有,且服务账号拥有写权限。可能后果:服务进程被攻陷后可替换私钥,导致后续重启加载攻击者控制的密钥。安全替代:保持
root所有,只给服务组读取权限。 - 触发条件:给运行私钥加口令,但没有可靠的解锁机制。可能后果:无人值守重启时服务停在口令提示。安全替代:使用受控的密钥管理或凭据注入;无法部署时,保留
0600 root:root的未加密运行副本,并重点保护主机。 - 触发条件:加密备份与口令存放在同一主机、同一共享目录或同一工单附件中。可能后果:一次泄露同时获得密文和口令。安全替代:分离存储、限制下载权限,并保留至少一份离线或不可变备份。
- 触发条件:只检查文件权限,忽略父目录、ACL、SELinux 或 AppArmor。可能后果:服务仍然无法读取,或额外主体通过 ACL 获得权限。安全替代:同时检查目录链、ACL 和安全上下文。
排障清单
先确认服务账号“可读但不可写”,再检查目录链和附加权限。下面的结果适用于 0640 root:myapp 且服务账号属于 myapp 组的情况。
KEY=/etc/myapp/tls/server.key
SERVICE_USER=myapp
sudo -u "$SERVICE_USER" test -r "$KEY" \
&& echo readable || echo denied
sudo -u "$SERVICE_USER" test -w "$KEY" \
&& echo writable || echo read-only预期输出:
readable
read-only若结果为 denied,用 namei -l /etc/myapp/tls/server.key 逐级检查父目录是否允许服务账号遍历;用 getfacl -p /etc/myapp/tls/server.key 查看是否存在额外 ACL;启用 SELinux 时再检查 ls -Z 和审计日志。若结果为 writable,立即移除组写权限并确认文件属主仍为 root。
兼容性
示例使用 GNU/Linux 的 stat -c、getent 和 sudo -u。macOS 可用 stat -f '%Lp %Su %Sg %N' 查看权限;Windows 应使用 NTFS ACL,而不是依赖 chmod。OpenSSL 1.1.1 与 3.x 均可处理加密 PKCS#8,但算法策略、默认提示和受限加密套件可能不同。
速查:目录优先使用 0750 root:<服务组>,私钥使用 0640 root:<服务组>;只有 root 需要读取时改为 0700 目录和 0600 root:root 私钥。