跳到主要内容

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 且业务数据正常。三者缺一不可。