证书链不完整 best practices:用 openssl verify 与 AIA 审计构建 6 步链完整性基线(2025)
证书链不完整的核心修复原则是:服务器按「叶子证书 → 全部中间证书」顺序发送,绝不包含根证书,并用 openssl verify -untrusted 在 CI 和线上同时校验;错误码 20 表示缺中间证书,21 表示链顺序或签名不匹配。 采集线上真实链用 openssl s_client -connect example.com:443 -servername example.com -showcerts(OpenSSL 3.0.13),正常返回 2–3 张证书,总字节建议控制在 4 KB 以内,超过 4 张需评估握手分片风险。 OpenSSL、curl、Python requests 以及 Java 默认(com.sun.security.enableAIAcaIssuers=false)都不会主动抓取 AIA 扩展里的 caIssuers 地址,而 Windows CryptoAPI 会抓取,因此「Windows 浏览器正常、Linux curl 报 (60)」几乎就是缺中间证书的指纹。 Nginx 1.24+ 的写法是 ssl_certificate fullchain.pem、ssl_certificate_key privkey.pem、ssl_trusted_certificate chain.pem,再开 ssl_stapling on 与 ssl_stapling_verify on,避免客户端为补链多走一次网络往返。 巡检基线建议:每日对每个入口执行 openssl s_client -verify_return_error -verify_hostname,验证失败或 notAfter 剩余不足 21 天即告警,阈值可用 blackbox_exporter 0.25 的 probe_ssl_earliest_cert_expiry 指标实现。
浏览器能打开、App 却握手失败?证书链不完整的 5 类根本原因
问:为什么 Chrome、curl 都能正常打开,Java 服务调用同一域名却抛握手失败?因为浏览器和 JVM 对「证书链不完整」的容忍度完全不同:Chrome 会主动抓取 AIA 扩展里指向的中间证书,而 Java 的 PKIX 实现默认不会这么做。据 RFC 5280 第 4.2.2.1 节,Authority Information Access(AIA)扩展中的 caIssuers 只是「可选提示」,不是协议强制,所以是否抓取完全由客户端实现决定。这就是同一张证书在不同客户端上表现分裂的技术根源。
根因一:只部署了叶子证书。绝大多数线上事故并非「链拼错」,而是根本没拼:运维把 domain.crt 直接写进 Nginx 的 ssl_certificate,服务器只发送 1 张证书。一张 RSA 2048 叶子证书约 1.2–1.5 KB,缺失中间证书时客户端要么直接失败,要么触发一次 AIA 抓取,跨境场景会额外增加约 80–200 ms 握手延迟。
根因二:拼接顺序错误。fullchain 必须是叶子在前、中间证书在后。OpenSSL 3.x 构建信任链时会尝试重排,但 Java 8 的 PKIX 实现和部分 Android 版本严格按文件顺序构建,乱序会直接抛 PKIX path building failed。用下面这条命令可以打印服务器实际发送的顺序:
# 抓取服务端实际发送的证书链并逐张打印 Subject/Issuer(叶子应排第一)
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null
| openssl crl2pkcs7 -nocrl -certfile /dev/stdin
| openssl pkcs7 -print_certs -noout
# 校验链是否闭合:chain.pem 为中间证书,缺链时典型输出
# error 20 at 0 depth lookup: unable to get local issuer certificate
openssl verify -untrusted chain.pem -CAfile /etc/ssl/certs/ca-certificates.crt fullchain.pem
根因三:根证书更替与交叉签名消失。据 Let’s Encrypt 官方公告,DST Root CA X3 已于 2021-09-30 到期,ISRG Root X1 的交叉签名于 2024-06-06 停止提供,默认链从 3 张降为 2 张。系统根证书库只含 DST Root CA X3 的 Android 7.1 及更早设备因此失败,而这类终端在存量 App 装机中仍占一定比例。
根因四:客户端 AIA 行为不一致。不同实现是否默认抓取 caIssuers,差异很大:
| 客户端 | 默认抓取 AIA caIssuers | 缺中间证书时的典型报错 |
|---|---|---|
| Chrome / Safari / Edge | 是(带缓存与超时) | 首次可用但变慢,内网或离线环境失败 |
| OpenSSL 3.x s_client / verify | 否 | error 20 at 0 depth lookup |
| curl(OpenSSL 后端) | 否 | curl: (60) SSL certificate problem: unable to get local issuer certificate |
| Java 8/11/17 PKIX | 否,com.sun.security.enableAIAcaIssuers 默认 false |
SunCertPathBuilderException: unable to find valid certification path to requested target |
临时打开 Java 的 AIA 抓取(会带来一次额外网络往返,不建议作为长期方案):
# JDK 8u231+/11/17 均支持,默认值为 false
java -Dcom.sun.security.enableAIAcaIssuers=true -jar app.jar
根因五:多入口与私有 CA 副本漂移。CDN 边缘、K8s Ingress 的 tls.crt、F5/HAProxy 的证书包、老 .NET 服务各持一份副本,只更新其中一个入口,就表现为「部分地区或部分客户端失败」。私有 CA 与 mTLS 场景同理:内部 CA 只签叶子证书、客户端 truststore 只导入根证书,中间证书无人分发,PKIX 构建直接失败——Istio 1.20+ 的 Citadel 与 PostgreSQL 15 的 sslrootcert/sslcert 都是高发区。唯一可靠的核对方式是对每个入口 IP 逐一探测:
# 对每个入口 IP 单独指定 SNI,确认返回的链长度与内容一致
for ip in 203.0.113.10 203.0.113.11; do
echo "== $ip =="
openssl s_client -connect $ip:443 -servername api.example.com -showcerts /dev/null
| grep -c "BEGIN CERTIFICATE" # 期望值 >= 2
done
这五类根因对应五种不同的修复动作:补发中间证书、调整拼接顺序、补齐旧根兼容链、显式声明 AIA 或禁用其依赖、统一多入口副本。后续的 6 步链完整性基线正是按此顺序用 openssl verify 与 AIA 审计逐项闭环。
补全证书链的 6 步实操:从采集线上链到分发到每个入口
为什么浏览器打开正常,curl 和 Java 客户端却报 unable to get local issuer certificate?因为浏览器会靠 AIA(Authority Information Access)扩展自动补拉中间证书,而大多数命令行工具、移动端 SDK 和老版本 Java 不会。据 RFC 5280 第 4.2.2.1 节,AIA 只是”辅助获取”手段,服务端仍必须下发完整链。下面 6 步把这件事从人工排查变成可复用基线。
第 1 步:采集线上真实链。不要只测 443,也别省 -servername——SNI 缺省时 Nginx/Apache 返回的是默认虚拟主机证书,结论会完全错位。443、8443、CDN 回源端口要分别采样:
# 逐个 host:port 探测,统计实际下发的证书张数(期望 ≥2)
for hp in "www.example.com:443" "api.example.com:8443" "origin.example.com:8080"; do
h=${hp%:*}; p=${hp#*:}
n=$(openssl s_client -connect "$hp" -servername "$h" -showcerts /dev/null
| grep -c 'BEGIN CERTIFICATE')
echo "$hp -> $n 张"
done
第 2 步:判定是缺链还是链错。把叶子证书单独存为 leaf.pem、其余存入 chain.pem,然后按 OpenSSL verify(1) 手册的语义读错误码:
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted chain.pem leaf.pem
# 典型输出:error 20 at 0 depth lookup: unable to get local issuer certificate
| 错误码 | X509_V_ERR 常量 | 真实含义 | 处理方向 |
|---|---|---|---|
| 20 | UNABLE_TO_GET_ISSUER_CERT_LOCALLY | 本地找不到中间证书 | 补中间证书 |
| 21 | UNABLE_TO_VERIFY_LEAF_SIGNATURE | 中间证书与叶子不匹配或顺序颠倒 | 重新配对、调整顺序 |
| 10 | CERT_HAS_EXPIRED | 链中任一张过期 | 整链轮换 |
| 2 / 27 | UNABLE_TO_GET_ISSUER_CERT / CERT_UNTRUSTED | 根不在信任库或跨根签发 | 换链或更新 CA 库 |
第 3 步:取回正确中间证书。优先用 CA 官方仓库:Let’s Encrypt 文档给出的 chains 目录同时提供 R3/E1 等中间证书与交叉签名版本,DigiCert、Sectigo 也有 intermediate 下载页。不要凭文件名猜,用 AKI/SKI 逐字节比对:
openssl x509 -in leaf.pem -noout -text | grep -A1 'Authority Key Identifier'
# Authority Key Identifier: keyid:6F:8A:...:C1 ← 候选中间证书的 SKI 必须等于这个值
for f in intermediate*.pem; do
echo "$f => $(openssl x509 -in "$f" -noout -ext subjectKeyIdentifier | tail -1)"
done
第 4 步:拼接并静态校验。顺序是叶子在前、中间在后,绝不能把根证书 cat 进去——多余的自签根会让部分 Android 与 Java 客户端直接判链失败,还会白白增加握手字节。
cat leaf.crt intermediate.crt > fullchain.pem
grep -c 'BEGIN CERTIFICATE' fullchain.pem # 期望 2 或 3
openssl verify -CAfile root.pem -untrusted fullchain.pem leaf.crt # 期望输出 leaf.crt: OK
第 5 步:分发到全部入口。漏掉任何一个入口(灰度集群、旧 LB、备用域名)等于没修。改前把上一版目录整份备份并写好回滚脚本:
nginx -t && systemctl reload nginx # 平滑重载,不断连接
apachectl -configtest && apachectl -k graceful # Apache 2.4 的优雅重启
kubectl create secret tls example-tls --cert=fullchain.pem --key=privkey.pem
--dry-run=client -o yaml | kubectl apply -f - # K8s 用证书包,不是单证书
# 云负载均衡(ALB/SLB/CLB)上传的是"证书+中间证书"的 PEM 包,控制台单证书入口会再次造成缺链
第 6 步:把校验前置到流水线。人眼复核迟早会漏,让 CI 阻断比让用户报错便宜得多。线上用 blackbox_exporter 0.25 每 60s 探一次,配合 Prometheus 规则同时盯到期与探活抖动:
- name: chain-verify
run: openssl verify -untrusted fullchain.pem leaf.crt # 非 OK 即 fail,阻断发布
- alert: TLSChainExpiring
expr: probe_ssl_earliest_cert_expiry - time() < 21 * 86400
- alert: TLSProbeFlapping
expr: changes(probe_success[30m]) > 2 # 链问题时通时不通的典型信号
把以上 6 步写成脚本后,证书链不完整 best practices 的落地成本就只剩一次 CI 集成;后续再叠加 OCSP stapling、HSTS 与 CT 监控,整条 TLS 配置基线才真正闭环。这些正是 证书链不完整 best practices 中容易被跳过、却最容易在移动端复现的部分。
命令与配置片段:OpenSSL 3.0.13、Nginx 1.24、HAProxy 2.8、Java 17 各自怎么写
先回答一个高频问题:判断服务端是否真的下发了中间证书,最可靠的第一现场是 openssl s_client 的 Verify return code,而不是浏览器地址栏的绿锁。据 OpenSSL 3.0 的 s_client(1) 手册,-verify_return_error 会让验证失败直接终止握手,-verify_hostname 则把主机名校验并入同一条链验证路径——这比事后看日志更接近真实客户端行为。
# OpenSSL 3.0.13:一次采集整条链 + 校验证书链 + 校验主机名(</dev/null 防止阻塞)
openssl s_client -connect example.com:443 -servername example.com
-showcerts -verify_return_error -verify_hostname example.com
-CAfile /etc/ssl/certs/ca-certificates.crt </dev/null
# 期望输出:Verify return code: 0 (ok) → 链完整且主机名匹配
# 常见失败:Verify return code: 20 (unable to get local issuer certificate) → 缺中间证书
# 常见失败:Verify return code: 21 (unable to verify the first certificate) → 链拼接/顺序错误
# 只想看摘要时加 -brief,输出 Protocol/TLSv1.3、Ciphersuite 与 Verification 行
openssl s_client -connect example.com:443 -servername example.com -brief </dev/null
注意 -servername 不能省:SNI 未命中会拿到默认站点证书,验证结果就失去意义。返回 20 和 21 的区别值得记住——前者是“信任锚找不到签发者”(典型缺中间证书),后者是“叶子证书的签发者就在链里但验不过”(典型顺序错或混入了不相关证书)。这正是证书链不完整 best practices 里最先要固化的一步:先判定失败类型,再决定改服务端还是改客户端信任库。
| 组件(版本) | 证书文件形态 | 关键参数/属性 | 一次性验证命令 |
|---|---|---|---|
| OpenSSL 3.0.13 | 任意 PEM 链 | -verify_return_error、-CAfile |
openssl verify -CAfile ca.crt -untrusted chain.pem leaf.pem |
| Nginx 1.24/1.26 | fullchain 与 chain 分文件 | ssl_certificate / ssl_trusted_certificate |
nginx -t + 上面的 s_client |
| HAProxy 2.8 | 叶子+中间+私钥合并单一 PEM | crt(叶子必须在前) |
haproxy -c -f /etc/haproxy/haproxy.cfg |
| Java 17 | JKS/PKCS12 信任库 | -Dcom.sun.security.enableAIAcaIssuers |
keytool -list -keystore cacerts |
Nginx 1.24/1.26 怎么写?核心是三个文件职责分离:ssl_certificate 必须是 fullchain(叶子+中间),ssl_trusted_certificate 只放中间与根、不含叶子,它专供 OCSP stapling 验证使用,两个参数指向同一文件在多数场景下会触发 stapling 校验失败。
# /etc/nginx/conf.d/example.com.conf (Nginx 1.24 / 1.26 通用)
server {
listen 443 ssl;
http2 on; # 1.25.1+ 的写法;1.24 用 listen 443 ssl http2;
server_name example.com;
ssl_certificate /etc/nginx/ssl/example.com/fullchain.pem; # 叶子+中间
ssl_certificate_key /etc/nginx/ssl/example.com/privkey.pem;
ssl_trusted_certificate /etc/nginx/ssl/example.com/chain.pem; # 仅中间/根,供 stapling 验证
ssl_stapling on; # 默认 off
ssl_stapling_verify on; # 默认 off,开启后必须配 trusted_certificate
resolver 1.1.1.1 8.8.8.8 valid=300s; # stapling 取 OCSP 响应用,不配则静默不生效
resolver_timeout 5s;
}
HAProxy 2.8 为什么只有一个 crt?据 HAProxy 2.8 配置手册,crt 指向的 PEM 里证书按“叶子 → 中间 → …”顺序排列,私钥位置不限但惯例放末尾;顺序错会直接导致客户端报 21。合并后用 -c 做语法与文件可读性校验,再用 s_client 做链路校验。
# 合并:叶子在前,中间证书按签发顺序跟随,私钥放最后
cat leaf.crt intermediate.crt privkey.pem > /etc/haproxy/certs/example.pem
chmod 600 /etc/haproxy/certs/example.pem
# haproxy.cfg 片段
# bind :443 ssl crt /etc/haproxy/certs/example.pem alpn h2,http/1.1
# 改完先校验配置语法,再 reload
haproxy -c -f /etc/haproxy/haproxy.cfg
Java 17 客户端侧:如果调用方是 JVM,缺链表现为 PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException。两条路——把根证书导入信任库,或让 JVM 通过 AIA 扩展自行抓取签发者(RFC 5280 定义的 caIssuers 访问方法)。
# 1) 导入私有根到 JDK 默认信任库(默认口令 changeit)
keytool -importcert -alias internal-root -file root.crt
-keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit -noprompt
# 2) 允许 JVM 走 AIA 抓取中间证书(默认 false;生产不推荐长期依赖)
java -Dcom.sun.security.enableAIAcaIssuers=true -jar app.jar
AIA 抓取依赖服务端可达外网且证书里确实写了 caIssuers 地址,延迟不可控、还可能被防火墙拦。因此证书链不完整 best practices 的共识是:由服务端下发完整链,而不是让每个客户端各自补齐。
curl 8.5 / Python 3.11 / Node 18+ 怎么快速验?适合塞进 CI 或巡检脚本:
# curl 8.5:%{ssl_verify_result} 为 0 才算通过(非 0 即 OpenSSL 错误码)
curl -sS -o /dev/null -w '%{ssl_verify_result} %{time_appconnect}n' https://example.com
# Python 3.11 + requests:显式指定信任包,避免用到系统里过期的 CA
python3 -c "import requests;print(requests.get('https://example.com',verify='/etc/ssl/certs/ca-certificates.crt').status_code)"
# Node.js 18+:为私有根追加信任,不覆盖内置根
NODE_EXTRA_CA_CERTS=/etc/ssl/certs/internal-root.crt node app.js
cert-manager 1.14 的 Secret 会不会踩坑?不会,只要你没手动改它。据 cert-manager 文档,tls.crt 已包含叶子与中间证书组成的完整链,tls.key 是私钥,ca.crt 只是签发者证书、不要用它覆盖 tls.crt。Ingress 侧只引用 secretName 即可,ingress-nginx 1.9+ 会自动拼装;自建 Ingress Controller 需确认其证书参数(如 ssl-certificate)指向的是 fullchain 而非单独的叶子文件,否则又回到“缺中间证书”的老问题。
方案选型:链放在源站、CDN 还是负载均衡器?三张对比表
“证书链到底配在哪一层?”这是证书链不完整 best practices 里最先要定的事。链放错层不会立刻报错,而是在某些客户端、某些回源路径上偶发失败。先看四类常见交付位置的差异。
表 1 链交付位置对比
| 交付位置 | 生效范围 | 更新窗口 | 常见坑 | 验证方式 |
|---|---|---|---|---|
| 源站 Nginx fullchain | 全站源站 | reload 后秒级 | 多节点漏更一台 | openssl s_client 逐 IP 探测 |
| CDN 边缘证书 | 全球边缘节点 | 分钟级 | 回源链路仍需单独配链 | 各地 dig 后 s_client |
| 云负载均衡 | 单区域 | 1–5 分钟 | 上传证书包时必须含中间证书 | 云厂商 API 查询证书详情 |
| K8s Ingress | 单集群 | 秒级 | Secret 里只放了叶子 | 解 base64 后核对张数 |
源站方案最容易“漏更”,必须按 IP 而不是按域名验证,因为 DNS 往往只指向其中一台:
# 逐节点核对下发链张数,期望 >= 2(叶子 + 至少一张中间证书)
for ip in 10.0.1.11 10.0.1.12 10.0.1.13; do
echo "== $ip =="
openssl s_client -connect "$ip":443 -servername www.example.com -showcerts /dev/null
| grep -c "BEGIN CERTIFICATE"
done
# -servername 不可省,否则 SNI 站点会拿到默认虚拟主机的证书,结论失真
# K8s 场景:Secret 里证书张数核对
kubectl get secret tls-wildcard -n prod -o jsonpath='{.data.tls.crt}'
| base64 -d | grep -c 'BEGIN CERTIFICATE' # 结果为 1 即缺中间证书
表 2 验证工具对比(以 OpenSSL 3.0.13、curl 8.5、testssl.sh 3.2 为例)
| 工具与版本 | 能否发现缺中间证书 | 退出码语义 | 主要盲区 |
|---|---|---|---|
openssl s_client 3.0.13 |
能,返回 verify code 20/21 | 0 通过;需加 -verify_return_error 才以非 0 退出 |
不抓 AIA,不测应用层 |
openssl verify 3.0.13 |
能,精确到错误码 | 0 通过,非 0 失败 | 需手工准备 -untrusted 文件 |
curl 8.5 |
能,报 (60) SSL certificate problem |
0 通过、60 证书错误 | 只反映本地信任库 |
testssl.sh 3.2 |
能,输出 Chain of trust 段 | --severity 分级 |
扫描耗时较长 |
| Java SSLPoke | 能,抛 PKIX path building failed |
异常即失败 | 需 JDK 环境 |
把服务端实际下发的链抓下来交给 openssl verify,是唯一能精确到错误码的做法:
openssl s_client -connect www.example.com:443 -servername www.example.com -showcerts /dev/null
| awk '/BEGIN CERTIFICATE/,/END CERTIFICATE/' > served.pem
csplit -z -f part- served.pem '/BEGIN CERTIFICATE/' '{*}' >/dev/null # part-00 为叶子
openssl verify -untrusted part-01.pem part-00.pem
# 缺中间证书:error 20 at 0 depth lookup: unable to get local issuer certificate
# 自签/私有 CA:error 18 self-signed certificate
表 3 链长度权衡
| 链构成 | 证书消息字节约值 | 兼容性 | 建议 |
|---|---|---|---|
| 仅叶子 | 1.3 KB | 依赖客户端 AIA 抓取,Java 与 curl 常失败 | 禁止上线 |
| 叶子 + 1 张中间 | 2.6–3.0 KB | 覆盖绝大多数现代客户端 | 推荐默认 |
| 叶子 + 2 张中间(含交叉签名) | 4.0–4.5 KB | 兼容 Android 7.1 及更早 | 存量老终端占比 > 1% 时启用 |
| 叶子 + 中间 + 根 | 5.5 KB 以上 | 无收益 | 不要这么做 |
结论一:老终端决定链长。只要业务仍有 Android 7.x 或 Java 8 早期版本客户端,就应保留带交叉签名的 3 张链,代价是握手体积增加约 1.5 KB。据 RFC 8446 §4.4.2 的 Certificate 消息结构,TLS 1.3 下这段数据位于 ServerHello 之后的首个加密扩展中,超过 MTU 即触发分片,弱网下 RTT 感知明显。
结论二:CDN 与源站必须成对评估。边缘证书完整不代表回源 TLS 完整。回源若用自签或私有 CA,源站仍需向 CDN 提供完整链,否则会出现“用户侧正常、回源 502”的隐蔽故障,这类问题在证书链不完整 best practices 的排查清单里出现频率最高。
结论三:OCSP stapling 不能替代完整链。stapling 只解决吊销状态查询,客户端仍要自行构建信任链;且当 ssl_trusted_certificate 指向错误文件时,Nginx 会静默降级为不 stapling,仅在 debug 日志留痕(Nginx 1.25.x 中 ssl_stapling 默认 off):
ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/fullchain.pem; # 必须是完整链,指向 leaf 会静默失效
resolver 223.5.5.5 valid=300s; # stapling 取 OCSP 响应依赖 resolver
# 验证:应输出 OCSP Response Status: successful
openssl s_client -connect www.example.com:443 -servername www.example.com -status /dev/null | grep -A1 "OCSP Response Status"
这 6 条报错分散在 curl、OpenSSL、Java、Android、Nginx 里,但都在回答同一个问题:叶子 → 中间 → 根这条路径,断在哪一环。判断只需两个维度——客户端能不能拿到完整链、本地信任库是否含对应根。把这两点分开,定位时间通常能压到 1 分钟内,这也是证书链不完整 best practices 里最省事的一条基线。
报错一:curl: (60) SSL certificate problem: unable to get local issuer certificate
先用服务端”应该发”的完整链作为信任锚做对照实验:
# 把服务端配置的 fullchain.pem 下载到本地当信任锚
curl -v --cacert ./fullchain.pem https://example.com
# 返回 200 → 服务端漏发中间证书(链不全)
# 仍报 (60) → 本地信任库缺根证书,与服务端无关
注意:curl 8.x 在 OpenSSL 后端下不会主动抓取 AIA 补链(据 curl 文档,AIA 抓取只在部分 TLS 后端实现),所以这条报错在 OpenSSL 版本上几乎等价于”服务端链不全”。
报错二:verify error:num=20 与 num=21
num=20:unable to get local issuer certificate 是缺中间证书;num=21:unable to verify the first certificate 是中间证书在位却签不上叶子(版本错或拼接顺序错)。用 subject/issuer 交叉核对,一分钟内出结论:
- HTTPS证书申请 · SSL证书安装部署 · 证书续费
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
- SSL/HTTPS 证书配置 · 证书安装 · 证书申请
openssl s_client -connect example.com:443 -servername example.com -showcerts &1
| grep -E 'verify error|Verify return code'
openssl x509 -in leaf.pem -noout -subject -issuer # issuer 应等于中间证书的 subject
openssl x509 -in inter.pem -noout -subject -issuer
报错三:Java PKIX path building failed ... unable to find valid certification path
打开握手日志看链长,这是最直接的判据:
java -Djavax.net.debug=ssl:handshake -jar app.jar 2>&1 | grep -i 'Certificate chain length'
# 输出 1 → 服务端只发了叶子证书(链不全)
# 输出 2 仍失败 → JVM cacerts 缺根,用 keytool 确认
keytool -list -cacerts -storepass changeit -alias isrgrootx1
报错四:Android Trust anchor for certification path not found
高发于 Android 7.1 及更早系统,它们的系统信任库没有 ISRG Root X1。历史上靠交叉签名链兜底,但据 Let’s Encrypt 公告,DST Root CA X3 交叉证书已于 2024-09-30 到期,这条路已封闭,现实方案只剩 App 内打包信任锚:
<!-- res/xml/network_security_config.xml -->
<network-security-config>
<domain-config>
<domain includeSubdomains="true">example.com</domain>
<trust-anchors><certificates src="@raw/isrg_root_x1"/></trust-anchors>
</domain-config>
</network-security-config>
报错五:Nginx error:0A00018E:SSL routines::ca md too weak
OpenSSL 3.0 引入安全级别机制,Debian/Ubuntu 22.04 起在 /etc/ssl/openssl.cnf 中默认 CipherString = DEFAULT@SECLEVEL=2(约 112 位强度),SHA-1 签名的老中间证书会被直接拒绝:
openssl x509 -in inter.pem -noout -text | grep -A1 'Signature Algorithm'
# sha1WithRSAEncryption → 命中该错误
grep -n SECLEVEL /etc/ssl/openssl.cnf # 确认当前安全级别
正确处理是向 CA 索取 SHA-256 中间证书,而不是把 SECLEVEL 降到 1 去掩盖问题。
报错六:verify error:num=10:certificate has expired,过期的是中间证书
叶子可能还剩数月有效期,链却已不可用。无需重签叶子,只替换中间证书并重新拼接 fullchain:
openssl s_client -connect example.com:443 -showcerts /dev/null
| openssl crl2pkcs7 -nocrl -certfile /dev/stdin | openssl pkcs7 -print_certs -noout
openssl x509 -in inter.pem -noout -subject -dates # 逐个核对 notAfter
| 报错文本 | 断点位置 | 首条定位命令 | 修复动作 |
|---|---|---|---|
| curl (60) unable to get local issuer | 服务端未发中间证书 | curl --cacert fullchain.pem |
fullchain 补全中间证书 |
| num=20 | 缺中间证书 | s_client -showcerts |
同上 |
| num=21 | 中间证书签不上叶子 | x509 -subject -issuer |
换正确版本/顺序 |
| PKIX path building failed | 服务端链长=1 或 JVM 缺根 | -Djavax.net.debug |
补链或导入 cacerts |
| Trust anchor not found | 旧 Android 无 ISRG X1 | 系统版本核对 | App 内打包信任锚 |
| ca md too weak (0A00018E) | 中间证书 SHA-1 签名 | x509 -text | grep Signature |
向 CA 换 SHA-256 链 |
| num=10 expired | 中间证书过期 | pkcs7 -print_certs |
仅替换中间证书 |
把这 6 条对照表纳入发布前检查,配合 openssl verify -CAfile root.pem -untrusted inter.pem leaf.pem 与 AIA 字段审计,就构成了一套可复现的证书链不完整 best practices 基线:先证明”服务端发了什么”,再证明”客户端信什么”,两件事永远分开验证。
配置改完不等于生效——中间证书漏配、顺序颠倒、CDN 回源覆盖,都会让”看起来正常”的站点在特定客户端上失败。下面 6 个动作都能在 CI 或运维终端里复现,前 4 个判断”链是否完整”,后 2 个防止”今天完整、下个月静默退化”。据 OpenSSL verify(1) 手册,-verify_return_error 的作用是把验证失败从”打印一行错误但继续握手”变成”直接以非零状态退出”,这是脚本化的前提。
动作一:本机严格验证,退出码 0 才算过。
# -verify_return_error:验证失败即中断握手并返回非零码
# -verify_hostname:同时校验 SAN 是否匹配,避免只验链不验名
openssl s_client -connect example.com:443 -servername example.com
-verify_return_error -verify_hostname example.com
-CAfile /etc/ssl/certs/ca-certificates.crt </dev/null
echo $? # 期望 0;非 0 表示链不完整或主机名不符
# 失败时典型输出:Verify return code: 21 (unable to verify the first certificate)
# 或:Verify return code: 20 (unable to get local issuer certificate)
动作二:应用层验证,一次拿到结果码、HTTP 状态与握手耗时。curl 的 ssl_verify_result 直接复用 OpenSSL 的 X509_V_ERR 编号,非 0 时查表定位即可,不必猜。
curl -sS -o /dev/null
-w '%{ssl_verify_result} %{http_code} %{time_appconnect}n'
https://example.com
# 期望:0 200 0.0xx
# 若返回 60 且 stderr 报 "SSL certificate problem: unable to get local issuer certificate"
# 就是服务端少发了中间证书,而不是本地 CA 库的问题
动作三:第三方扫描复核,换一套解析实现交叉验证。testssl.sh 3.2 与 sslyze 6.1 会独立解析并打印链长度,能暴露自建脚本里的逻辑盲区。
./testssl.sh --quiet --color 0 --protocols --server-defaults example.com
| grep -E 'Chain of trust|Certificate expiration|Cert #'
sslyze --certinfo example.com 2>/dev/null | grep -iE 'chain|received'
动作四:客户端矩阵抽测,别只点开 Chrome。Chrome 会读系统信任库并主动抓取 AIA(RFC 5280 §4.2.2.1 定义的 Authority Information Access 扩展),常把缺失的中间证书”自动补齐”,于是本机永远复现不出用户故障。
| 客户端 | 信任库来源 | 是否自动抓 AIA 补链 | 链不完整时的典型报错 |
|---|---|---|---|
| Java 17(SSLPoke) | $JAVA_HOME/lib/security/cacerts |
默认否 | PKIX path building failed: unable to find valid certification path |
| Python 3.11 + certifi 2024.2 | certifi 内置 CA bundle | 否 | SSLCertVerificationError: unable to get local issuer certificate |
| Node.js 20 | 内置 Mozilla CA 列表 | 否 | UNABLE_TO_VERIFY_LEAF_SIGNATURE |
| Android 7.0 模拟器 | 系统 CA + 用户 CA | 部分场景会 | Trust anchor for certification path not found |
| iOS 15 真机 | 系统信任库 | 是 | 常表现为”没有报错”,最易漏检 |
动作五:核对链长度与握手体积。叶证书 + 中间证书通常是 2 张,含根为 3 张;超过 4 KB 的证书消息会显著拉低弱网首包成功率,这正是证书链不完整 best practices 里”少而全”的由来——只补必要中间证书,不塞根证书。
# 期望输出 2 或 3
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| grep -c 'BEGIN CERTIFICATE'
# 粗估证书消息体积(字节数 / 1024)
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | wc -c
动作六:接入监控与指纹审计,让退化可被发现。blackbox_exporter 0.25 的 probe_ssl_earliest_cert_expiry 给出链上最早到期时间,与 probe_success、probe_tls_version_info 组合成三条告警:
# 14 天内到期 / 握手失败 / 协议降级到 TLS 1.0
probe_ssl_earliest_cert_expiry - time() < 86400 * 14
probe_success == 0
probe_tls_version_info{version="TLS 1.0"} == 1
# 指纹审计:确认线上跑的就是预期那张证书,而非回源旧证书
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null
| openssl x509 -noout -fingerprint -sha256 -subject -dates
# 与 crt.sh 上该域名最新证书的 SHA-256 指纹逐位比对
六个动作里,动作一、二适合放进每次发布后的冒烟测试,动作六常驻监控;动作四按季度抽测即可。据 Let’s Encrypt 文档,其签发的中间证书(如 ISRG Root X1 交叉链)会随信任库演进而变化,因此指纹与链长度都应作为基线值固化进仓库,而不是靠记忆判断”应该没问题”。
把链完整性做成基线:5 条可落地的治理规则
规则一:证书来源唯一,所有入口只读一个目录。手工上传与 ACME 自动签发并存,是“证书链不完整”复现率最高的根因:控制台里传的是 fullchain,脚本里贴的是 leaf,谁覆盖了谁无从查证。做法是把 certbot 2.9 或 acme.sh 3.0 的输出收敛到 /etc/ssl/fullchain.d/<domain>/,固定四个文件(fullchain.pem / chain.pem / leaf.pem / privkey.pem),Nginx、HAProxy、Java keystore 只允许引用此目录。certbot 2.9 起可用 --deploy-hook 在每次续期后原子落盘:
# certbot 2.9+(Let's Encrypt 文档推荐 --deploy-hook 而非 --post-hook:只在成功续期时触发)
certbot certonly --nginx -d example.com
--deploy-hook 'D=/etc/ssl/fullchain.d/example.com; install -d -m 0755 "$D" &&
cp "$RENEWED_LINEAGE/fullchain.pem" "$D/fullchain.pem" &&
cp "$RENEWED_LINEAGE/chain.pem" "$D/chain.pem" &&
cp "$RENEWED_LINEAGE/cert.pem" "$D/leaf.pem" &&
cp "$RENEWED_LINEAGE/privkey.pem" "$D/privkey.pem" &&
chmod 0600 "$D/privkey.pem"'
# acme.sh 3.0 等价写法
acme.sh --install-cert -d example.com
--fullchain-file /etc/ssl/fullchain.d/example.com/fullchain.pem
--key-file /etc/ssl/fullchain.d/example.com/privkey.pem
--reloadcmd "systemctl reload nginx"
据 Let’s Encrypt 文档,fullchain.pem 的定义就是 cert.pem 与 chain.pem 的拼接,因此“张数”天然是叶子 + 中间证书,不应包含根。
规则二:张数与命名必须可被审计。把张数写进部署清单,CI 里断言 2 ≤ 张数 ≤ 3 且不含自签根;OpenSSL 1.1.1 及以上提供 storeutl,可一次列出 fullchain.pem 内全部证书,便于 code review 时肉眼核对中间证书是否正确:
F=/etc/ssl/fullchain.d/example.com/fullchain.pem
openssl storeutl -noout -certs "$F" # 逐张列出证书(OpenSSL 1.1.1+)
openssl crl2pkcs7 -nocrl -certfile "$F" | openssl pkcs7 -print_certs -noout # 列出 subject/issuer
n=$(grep -c 'BEGIN CERTIFICATE' "$F")
[ "$n" -ge 2 ] && [ "$n" -le 3 ] || { echo "链张数=$n 越界(期望 2~3)"; exit 1; }
# 自签根检测:最后一张的 subject 与 issuer 相同即判失败
[ "$(openssl crl2pkcs7 -nocrl -certfile "$F" | openssl pkcs7 -print_certs -noout | tail -2 | sed 's/^(subject|issuer)=//' | uniq | wc -l)" -ne 1 ] || { echo "链尾为自签根"; exit 1; }
规则三:变更窗口与灰度。先在 1 台低流量节点替换目录内容,观察 5 分钟,必须同时通过 OpenSSL 与 Java 两条链路——JSSE 有自己的信任库与链构建逻辑,curl 通过而 Java 报 unable to find valid certification path to requested target 是典型的不完整链症状:
curl -svI https://example.com 2>&1 | grep -E 'SSL certificate verify|subject:|issuer:'
keytool -printcert -sslserver example.com:443 | head -20 # JDK 11+,验证 JSSE 链路
openssl x509 -noout -fingerprint -sha256 -in /etc/ssl/fullchain.d/example.com/leaf.pem # 指纹写入变更单
变更单必须记录:时间、操作人、SHA-256 指纹、张数。否则“谁在什么时候换了链”永远查不出来。
规则四:回滚成本要低于修复成本。部署前用 cp -a 把当前目录快照到 .prev/,回滚脚本只做“拷回 + reload”。实测中链错误导致的 MTTR 取决于能否 30 秒内回滚,而不是重新签发有多快:
# 部署前
cp -a /etc/ssl/fullchain.d/example.com /etc/ssl/fullchain.d/example.com.prev
# 回滚(目标:< 30s)
rsync -a --delete /etc/ssl/fullchain.d/example.com.prev/ /etc/ssl/fullchain.d/example.com/
&& systemctl reload nginx && echo "rolled back $(date -Is)"
规则五:月度全量扫描,输出 CSV。对全部域名与入口跑一遍脚本化扫描,字段固定为域名、IP、张数、最早到期日、verify 结果,纳入月度运维报告。这比事后排障省人力,也能提前发现 CA 静默更换中间证书(如 Let’s Encrypt 调整签发中间证书)导致的链路漂移:
#!/usr/bin/env bash
# scan.sh 用法: ./scan.sh domains.txt > chain-audit-$(date +%F).csv
printf 'domain,ip,count,not_after,verifyn'
while read -r d; do
ip=$(dig +short "$d" | head -1)
openssl s_client -connect "$d:443" -servername "$d" -showcerts </dev/null 2>/dev/null > /tmp/c.pem
n=$(grep -c 'BEGIN CERTIFICATE' /tmp/c.pem)
end=$(openssl x509 -in /tmp/c.pem -noout -enddate | cut -d= -f2)
awk '/BEGIN CERT/{i++} i==1' /tmp/c.pem > /tmp/leaf.pem
awk '/BEGIN CERT/{i++} i>1' /tmp/c.pem > /tmp/chain.pem
v=$(openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt
-untrusted /tmp/chain.pem /tmp/leaf.pem >/dev/null 2>&1 && echo OK || echo FAIL)
printf '%s,%s,%s,%s,%sn' "$d" "$ip" "$n" "$end" "$v"
done < "$1"
两种主流签发方式的取舍,直接决定这五条规则能否落地:
| 证书来源 | 链张数可控 | 审计痕迹 | 回滚成本 | 建议 |
|---|---|---|---|---|
| 控制台手工上传 | 否(易只传 leaf) | 无 | 高,需找回原始文件 | 禁止与 ACME 并存 |
| certbot 2.9 + –deploy-hook | 是 | /var/log/letsencrypt | 低,目录快照即回滚 | 推荐(root 场景) |
| acme.sh 3.0 –install-cert | 是 | ~/.acme.sh/acme.sh.log | 低 | 推荐(非 root / 多 CA 场景) |
把“证书链不完整 best practices”从经验变成基线,关键不在工具选型,而在于每条规则都有可执行的断言:来源唯一靠目录约束,张数靠 CI 退出码,回滚靠 cp -a 与 systemctl reload,漂移靠月度 CSV 对比。这些检查项同时也覆盖了 OCSP Stapling 失效、SNI 错配、根证书过期等相邻问题,可作为后续 TLS 配置基线的第一层。
根证书更替时间线:为什么 2024 年之后链问题明显变多
问:为什么 2024 年之后,unable to get local issuer certificate 和 unable to verify the first certificate 这类报错明显变多?
答:不是你的配置退化了,而是信任锚和中间证书在这四年里被上游换了三轮。证书链是一条「谁签发谁」的关系,任何一环被替换,下游的缓存、证书钉扎(pinning)和白名单都会瞬间失效——这也是证书链不完整 best practices 在 2024 年后从「建议」变成「基线」的直接原因。
| 时间 | 事件 | 对证书链的实际影响 |
|---|---|---|
| 2021-09-30 | DST Root CA X3 到期 | 据 Let’s Encrypt 公告,未更新系统根证书的 Android 7.1 及更早设备无法验证新证书,这是「老安卓用户突然打不开」的第一波集中反馈 |
| 2024-03 | Let’s Encrypt 启用 R10/R11 中间证书 | 签发者统一为 ISRG Root X1;旧环境缓存的 R3 链与新链混用,出现「一部分节点还是 3 张链、一部分已是 2 张链」的不一致状态 |
| 2024-06-06 | ISRG Root X1 交叉签名停止提供 | 默认链长度由 3 张降为 2 张,依赖交叉签名兼容老终端的方案失效,需显式决定是否自行拼接交叉证书 |
| 2023–2024 | Sectigo、DigiCert 多次更新 intermediate | 中间证书有效期通常 5–10 年,但替换时不主动通知;订阅 CA 的 status 页面或公告邮件是唯一低成本手段 |
| 2025 起 | 短期证书路线图 | 签发频率提升意味着链文件变更次数增加,手工维护必然出错,自动化与巡检基线不再是可选项 |
六个节点里最容易被忽略的是 2024-06-06:交叉签名停止提供后,3 张链与 2 张链适用场景不同,不能互相替代。自查只需一条命令(OpenSSL 1.1.1 与 3.x 通用):
# -showcerts 打印服务器实际发送的整条链
# -servername 必须显式写,否则拿到的是默认虚拟主机的证书
openssl s_client -showcerts -connect example.com:443
-servername example.com /dev/null | grep -E 'i:|s:'
2024-06 之后的默认新链输出形如:
0 s:CN = example.com
i:C = US, O = Let's Encrypt, CN = R11
1 s:C = US, O = Let's Encrypt, CN = R11
i:C = US, O = Internet Security Research Group, CN = ISRG Root X1
若第 1 张中间证书的 i: 显示 O = Digital Signature Trust, CN = DST Root CA X3,说明服务器仍在发旧的交叉签名兼容链——链尾出现自签的 ISRG Root X1 才是新链。本地闭环验证用 openssl verify,注意 -untrusted 传中间证书、-CAfile 传信任锚(Debian/Ubuntu 默认 /etc/ssl/certs/ca-certificates.crt):
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt
-untrusted chain.pem cert.pem
# 输出 cert.pem: OK 才算闭环
# error 20 = unable to get local issuer certificate(缺中间证书)
# error 2 = unable to get issuer certificate(缺根)
| 维度 | 3 张兼容链 | 2 张新链(2024-06 后默认) |
|---|---|---|
| 链路构成 | leaf → R3 → ISRG Root X1(交叉签名,由 DST Root CA X3 签发) | leaf → R10/R11 → ISRG Root X1 |
| Android 7.1 及更早 | 可验证 | 握手失败 |
| 现代浏览器 | 正常 | 正常 |
| 获取方式 | 交叉签名停止后需自行拼接,Let’s Encrypt 不再默认下发 | ACME 客户端默认返回 |
商业 CA 同理:Sectigo、DigiCert 的 intermediate 在 2023–2024 年间多次静默替换,替换动作不会打电话通知,只会体现在 CA status 页面与公告邮件里。叠加短期证书趋势后,链文件每年变更次数从「一次」变成「多次」,这正是需要把 openssl verify 与 AIA 审计固化成 6 步链完整性基线的现实背景。
不要。根证书通常已在客户端信任库里,服务器多发一张只会增加约 1.3 KB 握手体积,没有兼容性收益;RFC 5246/8446 的证书消息也不要求包含根。只有在私有 CA 且明确知道客户端信任库为空时才考虑单独分发根证书文件,而不是塞进 fullchain。
桌面 Chrome、Edge 往往不会提示,因为 Windows CryptoAPI 会通过 AIA 扩展去抓取中间证书,用户看到的是正常的小锁。真正暴露问题的是 curl、Java、Python、Node 以及不抓 AIA 的移动端,因此「浏览器正常」不能作为链完整的证据,必须用 openssl s_client -verify_return_error 判定。
CDN 托管只覆盖边缘到用户这一段,更新窗口以分钟计、无需 reload,但回源链路仍需源站自己提供完整链;自建 fullchain 覆盖源站全链路,更新是秒级 reload,风险在于多节点漏更。常见做法是两者都做:边缘用 CDN 证书,回源用私有 CA 或公网证书并同样拼 fullchain。
先跑 openssl s_client -connect 域名:443 -servername 域名 -showcerts /dev/null | grep -c 'BEGIN CERTIFICATE',若返回 1 就是服务端只发了叶子证书;再对比 curl -v –cacert ./fullchain.pem 是否成功,成功即确认缺中间证书。修复方式是把中间证书拼进 fullchain 并 reload,而不是去改客户端的 CA 包。
通常不需要。叶子证书的有效期与中间证书相互独立,只要 CA 仍用同一签发体系,替换中间证书、重新拼接 fullchain 并 reload 即可恢复。只有当 CA 同时更换了签发根或要求重签时,才需要重新走 CSR 流程;操作前用 openssl x509 -noout -dates 分别确认两张证书的 notAfter。
对每个入口 IP 单独执行 openssl s_client -connect IP:443 -servername 域名 -showcerts,统计证书张数并用 -fingerprint -sha256 比对指纹,全部一致才算完成。规模较大时用 blackbox_exporter 的 probe_ssl_earliest_cert_expiry 加指纹标签做集中比对,比人工逐台登录可靠。
有。Let's Encrypt 当前默认链为叶子加 1 张中间证书(ISRG Root X1 签发),共 2 张;部分商业 CA 因交叉签名或双链策略会提供 3 张链,兼容更老的终端但体积更大。选型时应按实际客户端分布决定,而不是简单认为张数越多越好。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。