Android: Trust anchor for certification path not found
一、错误在说什么:Trust anchor 就是“信任锚”
这个异常在 OkHttp、Retrofit、HttpURLConnection、WebView 里都会出现,完整堆栈通常长这样:
javax.net.ssl.SSLHandshakeException: java.security.cert.CertPathValidatorException: Trust anchor for certification path not found.
at com.android.org.conscrypt.OpenSSLSocketImpl.startHandshake(OpenSSLSocketImpl.java:448)
at okhttp3.internal.connection.RealConnection.connectTls(RealConnection.java:318)
at okhttp3.internal.connection.RealConnection.establishProtocol(RealConnection.java:284)
...
Caused by: java.security.cert.CertPathValidatorException: Trust anchor for certification path not found.
at com.android.org.conscrypt.TrustManagerImpl.verifyChain(TrustManagerImpl.java:683)
at com.android.org.conscrypt.TrustManagerImpl.checkTrustedRecursive(TrustManagerImpl.java:557)
Android 的 TrustManager 拿到服务端下发的证书链后,会从叶子证书(服务器证书)逐级向上找签发者,直到找到一张“自己签发自己”的根证书——这张根证书必须存在于设备的信任库中(系统 CA store,或 App 通过 network_security_config 声明的 trust-anchors)。找不到,就抛出这个异常。
关键认知:它不代表证书一定无效,只代表“我验证不到你”。常见触发原因有四类:
- 自签证书:根就是服务器证书本身,设备里当然没有。
- 私有 CA 签发:企业内网 CA,未预置到设备信任库。
- 证书链不完整:服务端只下发了叶子证书,没带中间证书。这是公网服务最常见的原因。
- 信任策略不匹配:证书本身没问题,但 Android 7.0+ 默认不再信任用户手动安装的 CA。
二、Android 信任模型的三次关键变更
同一个 APK 在老机型上正常、在新机型上崩,几乎都是下面这张表造成的:
| Android 版本 | API | 默认信任的 CA | 关键变更 |
|---|---|---|---|
| 5.0 – 6.0 | 21 – 23 | 系统 CA + 用户安装的 CA | 用户手动装证书即生效 |
| 7.0 – 8.1 | 24 – 27 | 仅系统 CA | 信任用户 CA 必须由 App 通过 network-security-config 显式声明 |
| 9 | 28 | 仅系统 CA | 明文 HTTP 默认禁止,cleartextTrafficPermitted 默认 false |
| 10 – 13 | 29 – 33 | 仅系统 CA | 无重大变更 |
| 14 及以上 | 34+ | 仅系统 CA | targetSdk ≥ 34 的 release 构建无法再启用用户 CA,只有 debuggable 构建可用 |
设备上的两套信任库可以直接用 adb 观察,这是判断“用户 CA 到底有没有生效”最快的方法:
# 系统 CA(预置在只读分区,普通 App 无法修改)
adb shell ls /system/etc/security/cacerts | head -n 20
# 用户安装的 CA(Android 7+ 默认不被 App 信任)
adb shell ls /data/misc/user/0/cacerts-added
如果目标证书出现在 cacerts-added 里但 App 依然报错,那问题就 100% 是信任策略,而不是证书本身。
三、5 分钟定位:先分清是服务端问题还是客户端配置问题
不要凭感觉改代码。按下面四步走,通常 5 分钟内能锁定方向。
1. 看服务端到底下发了几张证书
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null
| grep -E '^( *[0-9]+ s:| *i:)'
输出里只有一条 s:,说明服务端只发了叶子证书,中间证书缺失——这就是根因。正常情况下应该看到 s:(叶子)→ i:(中间)→ s:(中间)→ i:(根)的交替链条。
2. 用 openssl 完整校验一次证书链
openssl s_client -connect api.example.com:443 -servername api.example.com
-CAfile /etc/ssl/certs/ca-certificates.crt -verify_return_error </dev/null 2>&1
| grep -E 'Verify return code|verify error'
看到 Verify return code: 0 (ok) 才说明链是完整的。unable to get local issuer certificate 表示缺中间证书,certificate has expired 表示过期。
3. 抓 Android 侧的真实堆栈
adb logcat -c
adb logcat -v time | grep -iE 'SSLHandshake|CertPathValidator|Trust anchor|CertificateExpired|SSLPeerUnverified'
一定要看 Caused by 那几行,最外层的 IOException 通常只是包装。
4. 顺手排除时间与主机名问题
# 证书有效期
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null
| openssl x509 -noout -subject -issuer -dates
# 设备时间是否离谱(时间错乱同样会报 Trust anchor)
adb shell date
四、方案一(首选):服务端补全证书链,使用公共 CA
绝大多数线上事故属于这一类:证书是正规 CA 签的,但运维把 cert.pem 而不是 fullchain.pem 配进了 Nginx。浏览器能容忍缺失的中间证书(会通过 AIA 自动补全),Android 的 Conscrypt 通常不会,于是直接失败。
Nginx 正确配置
server {
listen 443 ssl;
server_name api.example.com;
# 必须是 fullchain(叶子 + 中间证书),不能是 cert.pem
ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_session_cache shared:SSL:10m;
}
Apache 正确配置
SSLCertificateFile /etc/letsencrypt/live/api.example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/api.example.com/privkey.pem
# 老版本 Apache(2.4.8 之前)需要单独指定链文件
# SSLCertificateChainFile /etc/letsencrypt/live/api.example.com/chain.pem
用 certbot 自动生成完整链
certbot certonly --webroot -w /var/www/html -d api.example.com
ls -l /etc/letsencrypt/live/api.example.com/
# fullchain.pem 才是你要配置的那个文件
nginx -t && systemctl reload nginx
改完后重跑第三节的 openssl s_client ... -verify_return_error,确认返回码为 0,再在报错的机型上重试。若仍失败,检查设备系统 CA 库是否过旧(Android 4.x 常见),此时需要选择带交叉签名的证书或升级目标机型。
五、方案二:内网私有 CA —— 用 network_security_config 精确信任
内网服务不可能去申请公网 CA,正确做法是把根证书(不是服务器证书)打包进 APK,并且只对指定域名生效。
步骤 1:拿到并核对根证书
# 从服务端导出完整链
openssl s_client -connect internal.corp.example.com:443 -servername internal.corp.example.com -showcerts </dev/null 2>/dev/null
| awk '/BEGIN CERTIFICATE/,/END CERTIFICATE/' > /tmp/chain.pem
# 核对根证书信息,确认 subject 与 issuer 相同(自签)
openssl x509 -in corp-root-ca.pem -noout -subject -issuer -dates -fingerprint -sha256
注意:必须内置根证书。内置中间证书虽然也能跑通,但中间证书有效期通常只有 1–3 年,到期后老版本 App 会集体报同样的错。
步骤 2:放入 res/raw
app/src/main/res/raw/corp_root_ca.pem
文件名只能包含小写字母、数字和下划线(corp_root_ca.pem 合法,CorpRoot-CA.pem 会编译失败)。PEM 和 DER 格式都支持。
步骤 3:编写 network_security_config.xml
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
<!-- 默认策略:只信任系统 CA -->
<base-config cleartextTrafficPermitted="false">
<trust-anchors>
<certificates src="system" />
</trust-anchors>
</base-config>
<!-- 只对内网域名放开私有根证书 -->
<domain-config>
<domain includeSubdomains="true">internal.corp.example.com</domain>
<domain includeSubdomains="true">api.corp.example.com</domain>
<trust-anchors>
<certificates src="@raw/corp_root_ca" />
<certificates src="system" />
</trust-anchors>
</domain-config>
<!-- 仅当 android:debuggable=true 时生效,用于本地抓包调试 -->
<debug-overrides>
<trust-anchors>
<certificates src="user" />
<certificates src="@raw/corp_root_ca" />
</trust-anchors>
</debug-overrides>
</network-security-config>
几个容易踩的坑:<domain> 里不能写协议、端口和路径,只能写主机名或 IP 字面量;不写 <domain-config> 而只写 <base-config>,等于对所有域名放开私有 CA,安全边界会消失;<debug-overrides> 只在 debuggable 构建里生效,release 包不会用它。
步骤 4:在 Manifest 中引用
<application
android:networkSecurityConfig="@xml/network_security_config"
android:usesCleartextTraffic="false"
... >
步骤 5:验证是否真的生效
adb logcat -c
adb shell am force-stop com.example.app
adb shell monkey -p com.example.app -c android.intent.category.LAUNCHER 1
adb logcat -v time | grep -iE 'SSLHandshake|Trust anchor|Certificate'
如果换成私有根证书后仍报 Trust anchor for certification path not found,先确认 res/raw 里那张确实是签发链顶端的根证书(用 openssl verify -CAfile corp_root_ca.pem server.pem 验证),再确认域名拼写与 includeSubdomains 是否符合预期。
六、方案对比:选哪一条路
| 方案 | 适用场景 | 客户端改动 | 服务端改动 | 可维护性 | 安全等级 |
|---|---|---|---|---|---|
| 补全中间证书(已有公共 CA) | 公网服务,链不完整 | 无 | 改用 fullchain.pem | 高 | 高 |
| 改用公共 CA(Let’s Encrypt / DigiCert 等) | 公网服务,当前是自签或私有 CA | 无 | 换证书 + 自动续期 | 高 | 高 |
| network_security_config 内置私有根证书 | 内网 / 私有 CA,无法上公网 | 加 raw 证书 + xml + Manifest | 无 | 中(换 CA 需发版) | 高 |
| MDM / 系统分区预置 CA | 企业统一管控的设备 | 无 | 无 | 高 | 中高(依赖设备管控) |
| 用户手动安装 CA(设置 → 安全 → 安装证书) | 仅开发调试 | 无 | 无 | 低 | 低(API 24+ 默认不生效) |
| trustAllCerts / 重写 TrustManager 全部放行 | 禁止使用 | — | — | — | 极低(等同关闭 HTTPS) |
七、故障排查:真实报错对照表
| 报错原文 | 根因 | 处理方式 |
|---|---|---|
javax.net.ssl.SSLHandshakeException: java.security.cert.CertPathValidatorException: Trust anchor for certification path not found. |
服务端证书链无法回溯到设备信任的根证书 | 用第三节的 openssl 命令判断是缺中间证书还是根证书不受信 |
Caused by: java.security.cert.CertPathValidatorException: Trust anchor for certification path not found.(被包在 OkHttp 的 java.io.IOException 里) |
同上,外层异常只是包装 | 看 Caused by 链的最底层,不要被 IOException 误导 |
java.security.cert.CertPathValidatorException: Certificate expired at Wed Jan 01 00:00:00 UTC 2025 |
证书过期,或设备系统时间错乱 | openssl x509 -noout -dates 核对有效期;adb shell date 核对设备时间 |
javax.net.ssl.SSLPeerUnverifiedException: Hostname api.example.com not verified: |
证书 SAN 里没有该主机名 | 重新签发包含该域名(或 IP,需 iPAddress 类型)的证书 |
| 仅 Android 7.0+ 失败,5.x / 6.0 正常 | 用户手动安装的 CA 在 API 24+ 默认不受信 | 改用公共 CA,或用 network_security_config 内置根证书 |
java.net.UnknownServiceException: CLEARTEXT communication to api.example.com not permitted by network security policy |
请求走了 http://,Android 9+ 默认禁止明文 | 改成 https;确需明文时仅在 <domain-config cleartextTrafficPermitted="true"> 内放开 |
javax.net.ssl.SSLHandshakeException: Chain validation failed |
链中某张证书无效(签名算法过弱、缺少中间证书、顺序错误) | 逐张导出检查,确保下发顺序为 叶子 → 中间 → 根 |
SSLHandshakeException: Connection closed by peer |
TLS 版本或加密套件不兼容 | 服务端启用 TLSv1.2 / TLSv1.3,移除已被淘汰的套件 |
sun.security.validator.ValidatorException: PKIX path building failed |
这是 JVM 侧报错,不是 Android | 把根证书导入 JVM 信任库:keytool -importcert -cacerts -file root.pem -alias corp |
WebView 里 net::ERR_CERT_AUTHORITY_INVALID |
WebView 复用同一套信任策略 | 修复证书链;不要在 onReceivedSslError 里调用 handler.proceed() |
八、安全红线:为什么绝不能 trustAllCerts
网上大量“解决方案”是重写 X509TrustManager 把所有证书放行,或者设置 HostnameVerifier 恒返回 true。这等于把 HTTPS 降级成 HTTP:任何中间人(公共 Wi-Fi、恶意代理、被劫持的 DNS)都能解密和篡改你的流量,账号密码、Token 全部裸奔。上架应用商店时这也是明确的违规项。
确实需要防中间人时,正确做法是证书固定(Certificate Pinning),而不是放弃校验:
val pinner = CertificatePinner.Builder()
.add("api.example.com", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")
.build()
val client = OkHttpClient.Builder()
.certificatePinner(pinner)
.build()
生成 pin 值(取公钥的 SHA-256,注意轮换证书时要同时保留新旧两个 pin):
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null
| openssl x509 -pubkey -noout
| openssl pkey -pubin -outform der
| openssl dgst -sha256 -binary
| openssl enc -base64
九、FAQ
Q1:我已经在手机“设置 → 安全 → 安装证书”里装了 CA,为什么 App 还是报错?
因为 Android 7.0(API 24)起,App 默认只信任系统 CA。用户安装的 CA 只有在你用 network_security_config 显式声明 <certificates src="user" /> 时才对 App 生效;而 Android 14(targetSdk ≥ 34)的 release 构建即使声明了也不会生效,只有 debuggable 构建可以。
Q2:为什么浏览器和 Postman 能访问,App 就不行?
浏览器有自己的信任策略,且会通过 AIA 自动抓取缺失的中间证书;Postman 允许关闭 SSL 校验。Android App 走的是系统信任库 + App 自身的 network security config,链路更严格,所以“浏览器能开”不能作为证书正常的证据。
Q3:一定要把根证书打包进 APK 吗?
只有私有 CA 才需要。如果服务在公网,最正确的做法是换成公共 CA 签发的证书,客户端零改动、可自动续期。内置根证书意味着每次 CA 轮换都要发新版本,老版本 App 会在某个时间点集体失效。
Q4:证书链不完整,为什么有的客户端能通、有的不能?
缺中间证书时,部分客户端(如桌面浏览器)会依据证书里的 AIA 扩展去下载中间证书补全,而 Android 的 Conscrypt 一般不做这个兜底,直接判定链不完整。这就是“浏览器正常、App 报 Trust anchor”的典型场景。
Q5:服务端用 IP 地址访问,证书该怎么签?
证书的 SAN 必须包含该 IP,且类型为 iPAddress(用 openssl x509 -noout -text | grep -A1 'Subject Alternative Name' 确认)。network_security_config 的 <domain> 支持直接写 IP 字面量。
Q6:为什么只有部分机型失败?
常见原因有三个:系统 CA 库版本不同(老系统缺新根证书,或缺少交叉签名);厂商定制 ROM 修改了信任策略;部分机型系统时间偏差过大导致证书被判为未生效或已过期。
Q7:调试阶段想抓 HTTPS 包,怎么配置最方便?
用 <debug-overrides> 配合 <certificates src="user" />,它只在 android:debuggable="true" 时生效,不会污染 release 包。或者把抓包工具的 CA 放进 res/raw 并在 debug-overrides 中引用。
Q8:换掉私有 CA 之后老用户怎么办?
建议在 trust-anchors 里同时保留新旧两张根证书,并在新版本 App 中逐步切换域名;等老版本装机量降到可接受水平后再移除旧证书。不要指望服务端“同时支持两套证书链”,TLS 握手只能下发一条链。
Q9:如何一次性确认修复真的生效了?
三步:服务端 openssl s_client ... -verify_return_error 返回 Verify return code: 0 (ok);真机 adb logcat 不再出现 Trust anchor for certification path not found;接口返回 200 且业务数据正常。三者缺一不可。