openssl s_client verify error:num=20 完全排查手册:证书链、信任库与中间证书
用 openssl s_client 手工验证证书链时,verify error:num=20:unable to get local issuer certificate 是最常见的一条报错。它不表示证书过期、域名不匹配或密钥有问题,只表示一件事:验证方在构建证书链时,找不到签发当前这张证书的上游证书。责任可能完全在服务端(少发中间证书),也可能完全在客户端(没指定信任库、信任库缺根、目录没 hash)。本文按「先定位、再分场景修、最后脚本化验收」的顺序给出可直接复制的命令。
一、报错到底在说什么:num=20 的含义
典型输出如下(注意 depth=0 处报错,说明断点就在叶子证书这一环):
$ openssl s_client -connect www.example.com:443 -servername www.example.com </dev/null
CONNECTED(00000003)
depth=0 CN = www.example.com
verify error:num=20:unable to get local issuer certificate
verify return:1
---
Certificate chain
0 s:CN = www.example.com
i:C = US, O = Let's Encrypt, CN = R3
---
...
Verify return code: 20 (unable to get local issuer certificate)
OpenSSL 的验证逻辑是:拿叶子证书的 issuer 字段,去两个地方找对应的证书——
- 服务器在握手中实际发送的证书列表(
-showcerts能看到); - 本机信任库(
-CAfile/-CApath/-CAstore或编译期默认路径)。
两边都找不到,就报 num=20。所以定位的第一步永远是:把「服务器发了几张」和「本机信任了什么」分开看,不要一上来就改配置。
一个高频困惑:浏览器能正常打开,为什么 openssl 报 20? 因为主流浏览器实现了 AIA(Authority Information Access)扩展的自动补链——证书里写着一个 CA Issuers 的 HTTP URL,浏览器会自己去下载缺失的中间证书。openssl s_client 默认不做 AIA 抓取,服务器少发一张,它就一定报错。所以 num=20 往往正是「服务端配置不完整」的暴露,而不是误报。
二、一分钟定位:服务器到底发了几张证书
用 -showcerts 打印服务器实际下发的完整列表,并直接计数:
$ openssl s_client -connect www.example.com:443 -servername www.example.com -showcerts </dev/null 2>/dev/null
| grep -c 'BEGIN CERTIFICATE'
结果判读:
- 只有 1 张 → 服务器只发了叶子证书,链不完整,问题在服务端(见第三节)。
- 2~3 张 → 服务器已带中间证书,问题在本机信任库或证书顺序(见第四、五节)。
- 0 张 → 连接根本没建立成功,先解决 SNI、端口、协议版本问题。
把服务器发来的链落盘并拆开逐张查看,是最有效的下一步:
$ openssl s_client -connect www.example.com:443 -servername www.example.com -showcerts </dev/null 2>/dev/null
| awk '/BEGIN CERTIFICATE/,/END CERTIFICATE/' > chain.pem
$ awk 'BEGIN{n=0} /BEGIN CERTIFICATE/{n++} n>0{print > ("cert-" n ".pem")}' chain.pem
$ for f in cert-*.pem; do
echo "== $f"
openssl x509 -in "$f" -noout -subject -issuer -dates
done
输出里应该呈现一条清晰的「自下而上」关系:cert-1 的 issuer 等于 cert-2 的 subject,cert-2 的 issuer 等于 cert-3 的 subject。只要有一环对不上,就是断链点。
三、场景 A:服务器证书链不完整——修服务端
确认只发了 1 张证书后,标准做法是把「叶子证书 + 中间证书」拼成一个 fullchain 文件,配置到服务端。顺序必须是叶子在前、中间在后;根证书通常不要下发(多数客户端自带,多发只会增加握手字节,个别老旧客户端反而会因链中出现自签根而报 num=19)。
# 手工拼接(Let's Encrypt 等 CA 一般直接提供 fullchain.pem,优先用它)
$ cat server.crt intermediate.crt > fullchain.pem
# 检查拼接后的顺序与内容
$ openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
各服务端的配置位置对照:
| 服务端 | 配置项 | 放什么 |
|---|---|---|
| Nginx | ssl_certificate |
fullchain.pem(叶子 + 中间,叶子在前) |
| Apache 2.4.8+ | SSLCertificateFile |
fullchain.pem(旧版的 SSLCertificateChainFile 已废弃) |
| Apache < 2.4.8 | SSLCertificateFile + SSLCertificateChainFile |
叶子证书 / 中间证书分开放 |
| HAProxy | bind :443 ssl crt ... |
单个 PEM,内含私钥 + 叶子 + 中间 |
| Tomcat / Java | keystore | 用 keytool -importcert 导入完整链 |
| 云负载均衡 / CDN | 证书上传框 | 通常分「证书」与「证书链」两栏,都要填 |
改完后重载并立即回验:
$ nginx -t && nginx -s reload
$ openssl s_client -connect www.example.com:443 -servername www.example.com -showcerts </dev/null 2>/dev/null
| grep -c 'BEGIN CERTIFICATE'
四、场景 B:本地信任库未指定——修客户端
服务器发了 2~3 张仍然报 num=20,说明断点不在服务端,而在于本机没有把对应的根(或交叉签名的上游)纳入信任。手工验证时显式指定信任库即可:
# 单文件 CA bundle(Debian/Ubuntu、Alpine 常见)
$ openssl s_client -connect www.example.com:443 -servername www.example.com
-CAfile /etc/ssl/certs/ca-certificates.crt
# 已 hash 的目录(RHEL/CentOS 常见)
$ openssl s_client -connect www.example.com:443 -servername www.example.com
-CApath /etc/pki/tls/certs
# OpenSSL 3.x 的通用存储接口
$ openssl s_client -connect www.example.com:443 -servername www.example.com
-CAstore /etc/ssl/certs/ca-certificates.crt
常用信任库路径速查:
- Debian / Ubuntu:
/etc/ssl/certs/ca-certificates.crt,目录/etc/ssl/certs - RHEL / CentOS / Rocky:
/etc/pki/tls/certs/ca-bundle.crt,目录/etc/pki/tls/certs - Alpine:
/etc/ssl/certs/ca-certificates.crt(需装ca-certificates包) - macOS(系统 LibreSSL):
/etc/ssl/cert.pem;自编译 OpenSSL 需手工导出 keychain
三种信任库参数的差异与注意事项:
| 选项 | 适用场景 | 示例 | 坑 |
|---|---|---|---|
-CAfile |
单个 PEM 打包文件,最通用 | -CAfile /etc/ssl/certs/ca-certificates.crt |
可重复指定多次,会累加 |
-CApath |
目录形式,按 subject hash 索引 | -CApath /etc/ssl/certs |
目录必须已 hash,否则静默无效,照样报 20 |
-CAstore |
OpenSSL 3.0+ 的 URI 式存储 | -CAstore file:///etc/ssl/certs/ca-certificates.crt |
1.1.1 及更早版本无此选项 |
-no-CAfile -no-CApath -no-CAstore |
关闭默认信任库,复现「只看服务器发了什么」 | openssl s_client -connect h:443 -no-CAfile -no-CApath -no-CAstore |
用于区分服务端 / 客户端责任,不作为生产配置 |
-partial_chain |
直接把某张中间证书当作信任锚 | -CAfile inter.crt -partial_chain |
仅测试用,绕过根验证有安全含义 |
-trusted_first |
优先使用可信链,处理交叉签名 | 1.1.0 起为默认行为 | 老版本需显式加 |
如果 -CApath 加了没反应,先确认目录是否 hash 过:
$ openssl rehash /etc/ssl/certs # OpenSSL 1.1.0+
$ c_rehash /etc/ssl/certs # 老版本 / 发行版脚本
$ ls /etc/ssl/certs | grep -c '.0$' # 有大量 xxxxxxxx.0 才算 hash 过
另外两个环境变量会覆盖默认行为,排查时值得一并检查:SSL_CERT_FILE 和 SSL_CERT_DIR。
五、场景 C:证书顺序错误、交叉签名与 AIA 补链
服务器确实发了多张证书,但顺序颠倒(中间在前、叶子在后)。OpenSSL 自身的验证器容错较好,常能自己重排;但 Java 客户端、Windows Schannel、部分负载均衡会严格按顺序构建链,同样表现为 num=20 或握手失败。所以顺序问题必须修,不能赌客户端。
# 检查顺序:cert-1 的 issuer 必须等于 cert-2 的 subject
$ for f in cert-*.pem; do
printf '%st' "$f"
openssl x509 -in "$f" -noout -subject -issuer | tr 'n' ' '
echo
done
交叉签名是另一个隐蔽原因:中间证书被「旧根」签发,而本机信任库里只有「新根」(或反之)。此时链在逻辑上是通的,但验证器找不到匹配的上游,仍报 num=20 或 num=2。判断方法:
# 看中间证书到底由谁签发
$ openssl x509 -in cert-2.pem -noout -issuer
# 在信任库里搜同名根
$ openssl crl2pkcs7 -nocrl -certfile /etc/ssl/certs/ca-certificates.crt
| openssl pkcs7 -print_certs -noout | grep -i 'CN = ISRG Root'
# 单独验证一条链,看断在哪
$ openssl verify -show_chain -CAfile /etc/ssl/certs/ca-certificates.crt
-untrusted cert-2.pem cert-1.pem
如果证书里带 AIA 扩展,可以顺着 URL 手工补齐缺失的中间证书:
$ openssl x509 -in cert-1.pem -noout -text | grep -A3 'Authority Information Access'
但请注意:这是排查手段,不是修复方案。生产环境的正确做法仍然是让服务端把完整链发出来。
六、验收标准:Verify return code: 0 (ok)
只有出现下面这一行才算真正通过,其余任何非 0 的返回码都视为失败:
Verify return code: 0 (ok)
推荐使用下面这条「严格模式」命令,它会让任何验证错误直接变成非零退出码,便于脚本化与 CI 使用:
$ openssl s_client -connect www.example.com:443
-servername www.example.com
-verify_return_error -verify 5
-verify_hostname www.example.com
-CAfile /etc/ssl/certs/ca-certificates.crt
-showcerts </dev/null
参数含义:-verify_return_error 让验证失败中断连接;-verify 5 设置最大链深度;-verify_hostname 一并校验 SAN 是否匹配(OpenSSL 1.1.0+)。
可复用的验收脚本:
#!/usr/bin/env bash
set -u
HOST=${1:?usage: $0 host [port]}
PORT=${2:-443}
CA=${CA_BUNDLE:-/etc/ssl/certs/ca-certificates.crt}
out=$(openssl s_client -connect "$HOST:$PORT" -servername "$HOST"
-verify_return_error -verify 5 -verify_hostname "$HOST"
-CAfile "$CA" -showcerts </dev/null 2>&1)
rc=$?
echo "$out" | grep 'Verify return code'
echo "sent certs: $(echo "$out" | grep -c 'BEGIN CERTIFICATE')"
if [ $rc -eq 0 ]; then echo "PASS $HOST:$PORT"; else echo "FAIL $HOST:$PORT (rc=$rc)"; exit 1; fi
七、错误码对照与常见报错处理
证书验证错误码来自 OpenSSL 的 X509_V_ERR_* 枚举,掌握下面这些基本可以覆盖 95% 的现场问题:
| 错误码 | 原始信息 | 含义 | 处理方向 |
|---|---|---|---|
| 20 | unable to get local issuer certificate |
找不到签发者,链断或信任库缺根 | 服务端补中间证书;客户端指定 -CAfile/-CApath |
| 21 | unable to verify the first certificate |
服务器只发了叶子,本地也没有对应中间证书 | 与 20 同源,优先查服务端 fullchain |
| 2 | unable to get issuer certificate |
链中间某一环缺失,常见于 -CAfile 给错文件 |
用 openssl verify -show_chain 定位断点 |
| 18 | self-signed certificate |
叶子证书自签,且未被信任 | 把自签证书本身加入 -CAfile |
| 19 | self-signed certificate in certificate chain |
链里带了自签根,但该根不在信任库 | 服务端去掉根证书;或客户端信任该根 |
| 27 | certificate not trusted |
证书在库中但被标记为 distrust(如被移除的旧根) | 换用新的签发链 / 更新 CA 包 |
| 10 | certificate has expired |
链中某张证书过期 | 续签,注意中间证书也会过期 |
| 9 | certificate is not yet valid |
系统时间或时区错误 | 校时(NTP)后重试 |
| 62 | hostname mismatch |
证书 SAN 与访问域名不符 | 检查 SNI 是否正确,多域名是否配错证书 |
| 66 | EE certificate key too weak |
密钥强度低于安全级别要求 | 换 2048 位以上 RSA / 256 位 EC,或调整 @SECLEVEL |
几个高频排错动作:
# 1) 只信任服务器发来的链,判断是「服务端少发」还是「客户端不信任」
$ openssl s_client -connect www.example.com:443 -no-CAfile -no-CApath -no-CAstore </dev/null
# 2) 用服务器下发的链去验证叶子,看断在哪一环
$ openssl verify -show_chain -CAfile /etc/ssl/certs/ca-certificates.crt
-untrusted cert-2.pem cert-1.pem
# 3) 排除 SNI 干扰(虚拟主机配错证书的经典表现)
$ openssl s_client -connect 1.2.3.4:443 -servername www.example.com </dev/null
# 4) 排除 TLS 版本干扰,确认是否只是协议协商问题
$ openssl s_client -connect www.example.com:443 -servername www.example.com -tls1_2 </dev/null
八、FAQ
Q1:浏览器能正常访问,openssl 却报 num=20,是不是 openssl 有问题?
不是。浏览器会通过证书里的 AIA 扩展自动下载缺失的中间证书,openssl s_client 默认不抓取。报错恰恰说明服务器没有下发完整链,属于服务端配置缺陷——浏览器「帮它兜住了」,但 Java、部分 IoT 设备、老版本 Android 等不会兜,迟早出问题。
Q2:已经看到服务器发了 2 张证书,为什么还是 20?
两种可能:一是这 2 张里缺的是「中间证书的签发者」(比如中间证书本身是交叉签名的,需要第 3 张);二是本机信任库缺失或未指定。用 -no-CAfile -no-CApath -no-CAstore 对照一次即可区分:如果关掉信任库后报错相同、开启后变 0,就是客户端问题。
Q3:根证书要不要一起发给客户端?
通常不要。客户端本来就该自带根证书,多下发的根只会增加握手体积;个别严格实现还会因为链中出现自签根而报 num=19。正确的链是「叶子 + 全部中间证书」,止于中间证书。
Q4:加了 -CApath /etc/ssl/certs 完全没效果,也不报错?
-CApath 要求目录里的证书按 subject hash 命名(形如 abcd1234.0)。如果只是把 PEM 文件丢进目录,OpenSSL 会静默跳过,表现就是「加了参数照样报 20」。执行 openssl rehash /etc/ssl/certs 或 c_rehash 后重试。
Q5:num=20 和 num=21 有什么区别?
21(unable to verify the first certificate)表示连叶子证书的直接签发者都找不到,通常是服务器只发了 1 张、且本地也没有对应中间证书;20 表示在链的某一层找不到签发者,断点可能更深。实际排查中两者处理路径几乎一致:先数服务器发了几张,再查信任库。
Q6:内网自签证书怎么让 openssl 验证通过?
把自签根(或自签叶子)本身作为信任锚显式传入:
$ openssl s_client -connect intranet.local:443 -CAfile /etc/pki/internal-ca.crt </dev/null
如果只想信任某张中间证书而不追溯根,可用 -CAfile inter.crt -partial_chain,但要注意这等于放弃了根级别的信任保证,仅建议测试环境使用。
Q7:离线 / 容器环境里没有 ca-certificates 怎么办?
精简镜像(alpine、distroless、scratch)经常根本没装 CA 包,此时任何公网证书都会报 20。安装 ca-certificates,或把宿主机的 bundle 挂载进去并用 -CAfile 指定,也可以设置环境变量 SSL_CERT_FILE 让所有 OpenSSL 程序生效。
Q8:证书链顺序真的重要吗?OpenSSL 不是会自己重排?
OpenSSL 的验证器容错较好,多数情况能自己找到正确路径;但 Java 的 X509TrustManager、Windows Schannel、部分硬件负载均衡会严格按下发顺序建链,顺序错就直接失败。既然修复成本只是 cat 时换个顺序,就没有理由不修。
Q9:怎么把这条检查塞进监控或 CI?
用第六节的严格模式命令,配合 -verify_return_error 让失败返回非零退出码;再叠加到期时间检查,形成完整的证书健康监控:
$ openssl s_client -connect www.example.com:443 -servername www.example.com </dev/null 2>/dev/null
| openssl x509 -noout -enddate