跳到主要内容

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