跳到主要内容
安装配置教程

安卓 https 证书不受信任怎么解决?从证书链、targetSdkVersion 到 network_security_config 的完整排查

安卓 https 证书不受信任 — 安卓 https 证书不受信任怎么解决?从证书链、targetSdkVersion 到 network_security_config 的完整排查
核心结论

安卓 https 证书不受信任,第一嫌疑是证书链不完整或 CA 不在客户端信任库,而不是证书本身买错;先跑 openssl s_client -connect 域名:443 -servername 域名 -showcerts,数清楚服务器实际下发了 1 张还是 2 张证书。 Android 7.0(API 24)起,targetSdkVersion ≥ 24 的应用默认只信任 /system/etc/security/cacerts,用户手动安装的 CA 必须通过 network_security_config.xml 的 显式放行才生效。 Android 7.1.1(API 25)以下的系统根库不含 ISRG Root X1,Let's Encrypt 已于 2024-06-06 停止提供 X1→DST Root CA X3 交叉证书,老设备访问 LE 证书站点会稳定失败,需换 CA 或在 App 内嵌 Conscrypt 2.5.x。 服务端只发 leaf 证书是最高频的配置错误,Nginx 应使用 cat cert.pem chain.pem > fullchain.pem 生成的完整链,根证书不要下发,握手包会白多 1-2 KB。 验证是否修好只需一条命令:openssl s_client -connect api.example.com:443 -servername api.example.com -CAfile /etc/ssl/certs/ca-certificates.crt,末尾必须是 Verify return code: 0 (ok)。

安卓提示“证书不受信任”到底是哪一环出了问题?

“证书不受信任”不是单一错误,而是一条校验链上任意一环断开的结果:应用信任锚 → 服务器下发的证书链 → 证书属性 → 设备时钟与中间代理。排查的第一步不是抓包,而是先确认提示来自哪个校验主体。

提示形态 校验主体 典型日志 / 错误码 优先排查
Chrome 显示“您的连接不是私密连接” Chromium 自带根库 + 系统根库 NET::ERR_CERT_AUTHORITY_INVALID、ERR_CERT_DATE_INVALID 证书链、SAN、有效期
App 内弹窗或请求失败 OkHttp / HttpURLConnection(Conscrypt) SSLHandshakeException、CertPathValidatorException targetSdkVersion、network_security_config

第一环:targetSdkVersion ≥ 24,用户安装的 CA 一律不生效。据 Android 官方 Network security configuration 文档,从 Android 7.0(API 24,2016 年 8 月)起,应用默认只信任 /system/etc/security/cacerts 中的系统 CA;用户手动装到 /data/misc/user/0/cacerts-added 的证书,对 targetSdkVersion ≥ 24 的应用不生效——这正是“装完用户证书还是不受信任”的第一大原因。先确认目标的 targetSdkVersion:

# 方式一:已安装到设备上的包(无需源码)
adb shell dumpsys package com.example.app | grep -i targetSdkVersion

# 方式二:直接读 APK 清单
aapt2 dump badging app-release.apk | grep -i sdkVersion
# 输出示例:targetSdkVersion:'33'

# 放行用户 CA 或调试期抓包证书,需在 res/xml/network_security_config.xml 中声明
# 并在 AndroidManifest.xml 的 <application android:networkSecurityConfig="@xml/network_security_config"> 引用
# 注意:debug-overrides 仅对 debuggable=true 的包生效,release 包无效

第二环:证书链下发不完整。服务器只发 leaf、不带中间证书时,TrustManager 无法把链构建到根,抛出 java.security.cert.CertPathValidatorException: Trust anchor for certification path not found(RFC 5280 第 6 节的路径构建要求服务器提供完整中间链)。数一下实际下发张数:

# 公网站点通常应为 2 张:leaf + 中间证书;不应包含根证书
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null 
  | grep -c "BEGIN CERTIFICATE"

# 若输出 1,说明只发了 leaf:Nginx 应配置 fullchain.pem(leaf 在前、中间证书在后)
# ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
# ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

第三环:系统根库太老。Android 7.1.1(API 25)以下的根库中没有 ISRG Root X1。据 Let’s Encrypt 公告,DST Root CA X3 交叉签名于 2021-09-30 停止,2024-06-06 又停止提供 X1→DST 的交叉证书,因此这批老设备访问 LE 证书站点会直接握手失败。可用 openssl s_client -connect … -CAfile /system/etc/security/cacerts/… 对照验证。

第四、五环:证书属性与环境。用 openssl x509 -in cert.pem -noout -text 逐项核对:SAN 是否含实际访问域名(www 前缀、IP 直连、内网域名最易漏)、notAfter 是否已过、RSA 是否 ≥ 2048 位、签名是否仍为 SHA-1(Android 7.0+ 直接拒绝)、是否缺少 extendedKeyUsage=serverAuth。环境侧则检查手机系统时间是否被刷机或手动改到有效期之外,以及 MDM 或 Charles / Fiddler / HttpCanary 的 TLS 拦截根证书是否被 App 信任。

排查步骤:从服务器到手机的 6 步定位法

安卓 https 证书不受信任的报错几乎总能在这两个位置找到根因:服务器下发的证书链不完整,或 App 的信任配置(targetSdkVersion 与 network_security_config)与证书不匹配。下面 6 步按”服务端 → 传输层 → 手机端 → App 配置”的顺序逐层收敛,每一步都有明确的通过判据,避免在错误的方向上反复改代码。

  1. 第 1 步:拉取服务器实际下发的证书链。不要看证书文件本身,要看握手时真正吐出来的链——很多事故是 Nginx 的 ssl_certificate 只配了 leaf,漏了中间证书。

    # -servername 必须写,否则 SNI 站点会返回默认证书,排查结果失真
    openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null 
      | openssl crl2pkcs7 -nocrl -certfile /dev/stdin 
      | openssl pkcs7 -print_certs -noout
    # 通过判据:输出应有 2 组 subject=/issuer=
    # 且第 2 张证书的 subject 必须等于第 1 张证书的 issuer
    # 只输出 1 组 = 中间证书未下发,Android 上必现 Trust anchor 错误
    

    据 OpenSSL 文档,s_client -showcerts 打印的是服务端在握手时发送的全部证书;Android 从 7.0(API 24)起不再像早期版本那样依赖 AIA 自动补齐中间证书,所以链缺失在浏览器能过、在 App 里过不了是常见现象。

  2. 第 2 步:在本地独立验证链。把第 1 步输出的第一张存为 cert.pem,其余存为 chain.pem,用系统根库做一次离线校验(OpenSSL 3.0.x 与 1.1.1 语法一致):

    openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted chain.pem cert.pem
    # 通过:cert.pem: OK
    # 失败典型:error 20 at 0 depth lookup: unable to get local issuer certificate  → 缺中间证书
    #           error 10 at 0 depth lookup: certificate has expired              → 证书过期
    
  3. 第 3 步:检查 SAN、有效期与签名算法。Android 自 API 24 起完全忽略 CN 字段,只认 subjectAltName,这是”域名明明一样却不信任”的高频原因。

    openssl x509 -in cert.pem -noout -dates -subject -ext subjectAltName
    # 确认:SAN 覆盖 api.example.com(含通配符 *.example.com 的匹配范围)
    #       Not After 在有效期内,且链上每张证书都未过期
    #       Signature Algorithm 为 sha256WithRSAEncryption 或 ecdsa-with-SHA256
    
  4. 第 4 步:交叉验证协议版本与密钥强度。老旧的 TLS 1.0/1.1、SHA-1 签名或 1024 位 RSA 在 Android 8.0+ 上会被直接拒绝:

    testssl.sh --severity MEDIUM --protocols https://api.example.com
    # 或直接调 SSL Labs API(all=done 拿完整结果)
    curl -s "https://api.ssllabs.com/api/v3/analyze?host=api.example.com&all=done" | jq '.endpoints[].details.protocols'
    

    据 Qualys SSL Labs 的评级规则,使用 SHA-1 签名的证书无法获得 A 级评分,而 Android 的默认 NetworkSecurityPolicy 对这类链同样会抛校验异常。

  5. 第 5 步:在真机上复现并抓完整异常链。只看到最外层消息不足以定位,务必逐层打印 getCause():

    # 清空日志后只过滤 TLS 相关关键字
    adb logcat -c && adb logcat | grep -iE "SSLHandshakeException|CertPathValidator|Trust anchor"
    
    // App 内逐层打印 cause,最内层才是真实原因
    try {
        // 你的 HTTPS 请求
    } catch (SSLHandshakeException e) {
        for (Throwable c = e; c != null; c = c.getCause()) {
            Log.e("TLS", c.getClass().getSimpleName() + ": " + c.getMessage(), c);
        }
    }
    

    最常见的真实报错是 javax.net.ssl.SSLHandshakeException: java.security.cert.CertPathValidatorException: Trust anchor for certification path not found.——它意味着链走到了尽头也没碰到一个被信任的根,90% 对应第 1、2 步的失败。

  6. 第 6 步:核对 App 侧配置是否”故意”缩小了信任范围。先确认编译目标,再看网络安全配置文件:

    # build-tools 34.0.0 的 aapt 即可读取
    aapt dump badging app.apk | grep -i sdkVersion
    # 解包二进制 XML(apk 内的 xml 是编译过的,需 apktool 解码)
    apktool d app.apk -o apk_out
    grep -n "networkSecurityConfig" apk_out/AndroidManifest.xml
    cat apk_out/res/xml/network_security_config.xml   # 检查 trust-anchors 是否只声明了 system
    
    targetSdkVersion / 系统版本 默认信任用户安装的 CA 默认允许明文 HTTP
    ≤ 23(Android 6.0 及以下) 是 是
    24–27(Android 7.0–8.1) 否,需在 network_security_config 中显式声明 <certificates src="user"> 是
    ≥ 28(Android 9.0+) 否,同上 否,cleartextTrafficPermitted 默认 false

    如果 App 的自定义 TrustManager 或 network_security_config.xml 只信任 system 锚点,而你又在测试环境里抓包或使用自签证书,那么安卓 https 证书不受信任就不是服务器的问题,而是配置把用户 CA 排除在外了。

服务端怎么配:Nginx / Apache / Tomcat 下发完整证书链的正确写法

在客户端排查之前,先确认服务端下发的证书链是否完整——这是「安卓 https 证书不受信任」最常见的根因之一。Android 7.0(API 24)起不再信任用户安装的 CA,但系统根库仍然是完整的;真正让握手失败的是服务端只发了 leaf 证书、没发中间证书,浏览器靠 AIA(Authority Information Access)自动补链能成功,而 Android 的 Conscrypt 栈默认不做 AIA 拉取,直接报 java.security.cert.CertPathValidatorException: Trust anchor for certification path not found。

Nginx 怎么写才对?

据 Nginx 官方文档 ngx_http_ssl_module,ssl_certificate 指向的文件必须是「leaf 在前、中间证书在后」的 PEM 拼接文件,顺序不能颠倒,否则部分客户端会挑错链。拼接方式:

# 顺序:站点证书(leaf) → 中间证书(chain),切勿把根证书拼进来
cat cert.pem chain.pem > /etc/nginx/ssl/fullchain.pem

# nginx.conf(Nginx 1.25.x stable / 1.26.x 均适用)
server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/nginx/ssl/fullchain.pem;   # leaf + intermediate
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;     # 私钥,权限 600

    # 协议:Android 5.0+ 支持 TLS1.2;4.4 及以下只到 TLS1.0
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_session_cache   shared:SSL:10m;                 # 默认 none
    ssl_session_timeout 1d;                             # 默认 5m

    # OCSP Stapling:Android 对 OCSP 硬失败容忍度低,建议开启
    ssl_stapling        on;                             # 默认 off
    ssl_stapling_verify on;                             # 默认 off
    ssl_trusted_certificate /etc/nginx/ssl/chain.pem;   # 只放中间证书
    resolver            223.5.5.5 valid=300s;
}

把根证书也拼进去是常见误操作:握手包会多出 1–2 KB,且部分老客户端会因为出现自签根而判定链异常。验证命令:

openssl s_client -connect example.com:443 -servername example.com -status </dev/null 
  | openssl x509 -noout -subject -issuer
# 期望输出包含 OCSP Response Status: successful

Nginx 双证书(RSA + ECDSA)值得配吗?

值得。Nginx 1.11.0+ 允许 ssl_certificate 写两次,按客户端能力自动选择。ECDSA P-256 覆盖 Android 7.0+,RSA 2048 兜底 Android 5.x/6.x 与老旧 IoT 设备,实测握手成功率提升明显,且 ECDSA 握手字节数更少、移动网络下更快。

ssl_certificate     /etc/nginx/ssl/ecdsa-fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/ecdsa-privkey.pem;
ssl_certificate     /etc/nginx/ssl/rsa-fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/rsa-privkey.pem;

Apache 与 Tomcat 的写法差异

Apache httpd 2.4.8+ 把 leaf 与中间证书合并写入 SSLCertificateFile;SSLCertificateChainFile 自 2.4.8 起已废弃(仍可用但不推荐)。SSLCACertificateFile 只在做客户端证书 mTLS 时才需要,配错会导致「链不完整」的假象。

# httpd.conf / ssl.conf(Apache 2.4.8+)
SSLCertificateFile    /etc/httpd/ssl/fullchain.pem   # leaf + intermediate 合并
SSLCertificateKeyFile /etc/httpd/ssl/privkey.pem
# SSLCertificateChainFile 已废弃,勿再配置

Tomcat 的问题在于 JKS 无法保存完整链。用 OpenSSL 3.x 生成 PKCS12:

openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem 
  -out keystore.p12 -name tomcat -CAfile chain.pem -caname root

# server.xml(Tomcat 9.0.x / 10.1.x)
<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true" scheme="https" secure="true">
  <SSLHostConfig>
    <Certificate certificateKeystoreFile="conf/keystore.p12"
                 certificateKeystoreType="PKCS12"
                 certificateKeystorePassword="***" />
  </SSLHostConfig>
</Connector>
服务端 链文件写法 关键指令 / 属性 易错点
Nginx 1.25/1.26 fullchain.pem(leaf→中间) ssl_certificate 拼入根证书;顺序颠倒
Apache 2.4.8+ 合并进 SSLCertificateFile SSLCertificateChainFile 已废弃 误配 SSLCACertificateFile
Tomcat 9/10.1 PKCS12(含 -CAfile) keystoreType="PKCS12" 用 JKS 丢失中间证书

配完用 Qualys SSL Labs 或 openssl s_client -showcerts 复核「证书链中是否包含 2 张以上证书」,再回到 Android 端复测。

App 侧怎么放行:network_security_config.xml 与 targetSdkVersion 的关系

很多人改完证书链、确认服务端已经下发完整中间证书之后,App 依然报 Trust anchor for certification path not found,问题往往出在 App 自己的信任配置上。Android 7.0(API 24)是一个分水岭:据 Android 官方文档 Network security configuration,当 targetSdkVersion ≥ 24 时,应用的默认信任锚(trust anchors)只包含 system,用户手动安装到”用户证书区”的 CA 不再被 App 信任——这正是抓包工具装完证书后依然抓不到 HTTPS 的根本原因,也是”安卓 https 证书不受信任”最高频的成因之一。

要放行自建 CA,必须显式声明配置文件:

<!-- res/xml/network_security_config.xml -->
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <!-- 基线配置:默认仍只信任系统 CA,与 API 24+ 默认行为保持一致 -->
    <base-config cleartextTrafficPermitted="false">
        <trust-anchors>
            <certificates src="system"/>
        </trust-anchors>
    </base-config>

    <!-- 仅 android:debuggable="true" 的包生效,release 包自动忽略 -->
    <debug-overrides>
        <trust-anchors>
            <certificates src="user"/>   <!-- Charles / mitmproxy 装的用户证书 -->
            <certificates src="system"/>
        </trust-anchors>
    </debug-overrides>

    <!-- 精确到域名:只对 api.example.com 及其子域放行自建 CA -->
    <domain-config cleartextTrafficPermitted="false">
        <domain includeSubdomains="true">api.example.com</domain>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>  <!-- res/raw/my_ca.pem,DER 格式会解析失败 -->
            <certificates src="system"/>
        </trust-anchors>
    </domain-config>
</network-security-config>

<!-- AndroidManifest.xml 中引用 -->
<application
    android:networkSecurityConfig="@xml/network_security_config"
    android:debuggable="${debuggable}" />   <!-- AGP 按 buildType 自动注入 -->
信任锚写法 生效范围 targetSdkVersion≥24 默认值 适用场景
src="system" 全局 唯一默认项 线上环境
src="user" 全局 不包含 仅调试抓包
src="@raw/xxx" 指定 domain 无 企业内网自建 CA(PEM)
<debug-overrides> 仅 debuggable 包 — release 自动失效,避免把调试信任带上线

另一个常被误判为证书问题的报错来自明文流量。据 Android 文档,targetSdkVersion ≥ 28(Android 9)起 cleartextTrafficPermitted 默认为 false,此时 HTTP 请求直接抛:

java.net.UnknownServiceException: CLEARTEXT communication to api.example.com not permitted by network security policy

看到 not permitted by network security policy 就别再去查证书了,那是域名没走 TLS。

还有两个版本陷阱:其一,Android 11(API 30)起应用进程无法读取 /system/etc/security/cacerts,HttpCanary 一类”安装系统证书”方案在未 root 的 Android 11+ 上失效,只能改用 VPN 模式或 root 后 remount。其二,OkHttp 4.12.0 默认走平台 TrustManager,若自行构造 SSLSocketFactory,X509TrustManager.checkServerTrusted 必须是真实校验,写成 {} 空实现会被 Google Play 与国内主流应用市场扫描并拒审,同时也会让”安卓 https 证书不受信任”变成静默失效——请求成功但毫无安全保障。

方案选型:公有 CA、私有 CA、自签名与抓包证书怎么选

“安卓 https 证书不受信任”这个问题,有相当一部分根本不是代码问题,而是一开始就选错了证书方案。例如,把自签名证书部署到公网,或给正式版 App 安装了 Charles 的代理证书,之后无论怎么修改 network_security_config,都只会让问题更隐蔽。据 Android 官方 Network security configuration 文档,从 Android 7.0(API 24)起,App 默认只信任系统 CA,用户手动安装的证书对 App 无效,这正是多数“装了证书还是报错”的根因。典型报错为:

java.security.cert.CertPathValidatorException:
    Trust anchor for certification path not found.

先按使用场景选型,再进入排查流程:

方案 代表产品 2024–2025 报价 有效期 Android 兼容起点 关键限制
免费 DV Let’s Encrypt、ZeroSSL 0 元 90 天 7.1.1+ 内置 ISRG Root X1 必须自动续期,否则到期即报不受信任
商业 DV DigiCert、GeoTrust 约 800–2000 元/年 ≤398 天 Android 4.x(DigiCert Global Root CA 自 2.3 预置) 需域名验证
OV / EV DigiCert、Sectigo 约 1000–8000 元/年 ≤398 天 同上 需企业实名;浏览器 UI 差异已不明显
私有 CA step-ca、Easy-RSA 0 元 + 运维成本 自定义,建议 ≤1 年 需 MDM 下发或 App 内置根证书 Android 7+ 用户证书不被 App 信任
自签名 openssl req -x509 0 元 自定义 仅限内网测试 必须配 network_security_config
抓包代理证书 Charles、Fiddler、mitmproxy 随工具授权 随工具 仅调试包 禁止进入 release 构建

选型建议一:面向公众的 App 后端一律用公有 CA。不要指望用户手动安装证书。如果预算敏感,就用 Let’s Encrypt 加自动续期,关键是续期任务必须配置 deploy-hook,否则 nginx 会一直加载旧证书:

# certbot 2.x(推荐 snap 安装:sudo snap install --classic certbot)
# --deploy-hook 仅在证书真正续期后触发,避免每次空跑都 reload
0 3 * * * /usr/bin/certbot renew -q --deploy-hook "systemctl reload nginx"

# 上线前务必演练,确认续期链路可用
sudo certbot renew --dry-run

选型建议二:必须兼容 Android 5.x/6.x 时,优先选根证书预置早的 CA(DigiCert Global Root CA 自 Android 2.3 起内置),或做 RSA 2048 + ECDSA P-256 双证书部署,nginx 1.11.0+ 支持在同一 server 块并列两组证书:

server {
    listen 443 ssl;
    server_name api.example.com;

    # ECDSA P-256:现代客户端优先命中
    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
    # RSA 2048:兜底 Android 5.x/6.x 及老客户端
    ssl_certificate     /etc/letsencrypt/live/api.example.com-rsa/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com-rsa/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;   # nginx 默认值随版本变化,显式声明更稳
}

选型建议三:内网服务与 IoT 设备用私有 CA。根证书通过 MDM 或设备所有者模式下发;Device Owner 模式下可静默安装系统级 CA,绕过“用户证书不被信任”的限制:

# 将设备置为 Device Owner(需恢复出厂设置后、无其他账号时执行)
adb shell dpm set-device-owner com.example.dpc/.AdminReceiver
# 成功输出:Success: Device owner set to package ComponentInfo{com.example.dpc/...}

# 根证书须按 subject_hash_old 命名后放入系统信任库(需 root/remount,或由 DPC 代劳)
HASH=$(openssl x509 -inform PEM -subject_hash_old -in root-ca.crt | head -1)
adb push root-ca.crt /system/etc/security/cacerts/${HASH}.0

成本核算:Let’s Encrypt 单域名 0 元但 90 天续期一次(据 Let’s Encrypt 官方文档,有效期固定 90 天);商业 DV 3 年期约 1500–3000 元,折合每年 500–1000 元,换来的是老设备兼容性与免运维。按 CA/Browser Forum 基线要求,公有证书最长有效期已压到 398 天,任何“买一张管三年”的预期都不成立。量级上,这笔钱通常远低于一次线上“安卓 https 证书不受信任”事故的损失。

常见报错原文对照:这 6 条日志分别该怎么处理

这 6 条报错看似都属于”安卓 https 证书不受信任”,但根因分散在证书链、信任库、域名、设备时间、明文策略和根证书兼容性六个层面。先看总览,再逐条给出第一条要执行的命令——顺序错了会白折腾半天。

日志关键片段 真正的根因 第一动作
Trust anchor for certification path not found 链不完整,或 CA 不在信任库 openssl s_client -showcerts 数证书张数
已装用户证书,仍报 Trust anchor targetSdkVersion ≥ 24,未声明信任 user 证书 改 network_security_config.xml
SSLPeerUnverifiedException: Hostname not verified 证书 SAN 不含该域名 核对 subjectAltName
CertificateExpiredException 设备时间错误或证书真过期 adb shell date
UnknownServiceException: CLEARTEXT … not permitted Android 9+ 默认禁明文,与证书无关 查 cleartextTrafficPermitted
PKIX path building failed Android 5.x/6.x 缺 ISRG Root X1 换老根 CA 或独立兼容域名

① 链不完整 vs App 不信任,一步分清。只发 1 张证书就是链问题(服务器漏配中间证书),发了 3 张以上仍报错,说明 CA 不在系统信任库(私有 CA 或用户证书):

# 统计服务器实际下发的证书数量,正常应为 2~3 张(叶子+中间+可选根)
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null 
  | grep -c "BEGIN CERTIFICATE"
# 输出 1 → 补配中间证书;输出 3 仍报错 → 走 ② 的信任配置

② 用户证书装了却无效。Android 7.0(API 24)起,App 默认只信任系统 CA,据 Android 官方文档,targetSdkVersion ≥ 24 时必须显式声明。仅装证书不改配置一定失败:

<!-- res/xml/network_security_config.xml -->
<network-security-config>
  <base-config cleartextTrafficPermitted="false">
    <trust-anchors>
      <certificates src="system"/>   <!-- 系统 CA,默认即此项 -->
      <certificates src="user"/>     <!-- 仅调试包保留,release 必须删掉 -->
    </trust-anchors>
  </base-config>
</network-security-config>
<!-- AndroidManifest.xml: <application android:networkSecurityConfig="@xml/network_security_config"> -->

③ 域名不匹配。Android 自 API 17 起只认 SAN,忽略 CN。用一条命令同时看 SAN 与有效期:

openssl s_client -connect api.example.com:443 -servername api.example.com /dev/null 
  | openssl x509 -noout -subject -ext subjectAltName -dates

④ 证书过期。先排除设备时钟漂移(模拟器、老平板常见):adb shell date 若明显偏移,执行 adb shell settings put global auto_time 1 恢复自动对时,再复测;若 -dates 显示 notAfter 已过,则确属证书过期,需续签。

⑤ 明文流量被拦截。这条根本不是证书问题。Android 9(API 28)起 cleartextTrafficPermitted 默认 false。正确做法是全站 HTTPS;仅内网调试时按域名放开:

<domain-config cleartextTrafficPermitted="true">
  <domain includeSubdomains="true">10.0.0.8</domain>  <!-- 只放行内网 IP -->
</domain-config>

⑥ 老设备 PKIX path building failed。Android 5.x/6.x 的信任库早于 ISRG Root X1 交叉签名,访问 Let’s Encrypt 证书的站点必然失败(据 Let’s Encrypt 文档,2024 年后默认链不再提供交叉签名)。方案二选一:给 minSdkVersion ≤ 23 的构建换用 DigiCert/Sectigo 等老根 CA,或为老客户端单独保留一个兼容域名。

效果验证:怎么确认配置真的生效了

配置改完之后,最容易犯的错误是「改了但没生效」——例如中间证书只装到了其中一台后端、network_security_config 里的 domain 写成了通配符之外的子域、或者 App 仍在使用旧的 OkHttp 缓存连接。下面这套验证顺序从服务端到客户端逐层排除,每步都有明确的通过标准。

第一步:服务端证书链自检。据 OpenSSL 官方文档,s_client 的 -CAfile 用于指定信任库,-servername 触发 SNI(缺失会拿到默认站点的证书,是常见误判来源):

# OpenSSL 1.1.1 / 3.x 通用;-servername 不可省略,否则多域名服务器可能返回错误证书
openssl s_client -connect api.example.com:443 
  -servername api.example.com 
  -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null

# 只看结论,便于脚本判断
openssl s_client -connect api.example.com:443 -servername api.example.com 
  -CAfile /etc/ssl/certs/ca-certificates.crt /dev/null 
  | grep -E "Verify return code|notAfter"
# 期望输出:Verify return code: 0 (ok)

判定标准有两条:末尾必须是 Verify return code: 0 (ok),且 Certificate chain 段应恰好 2 项(叶子证书 + 1 张中间证书)。出现 verify error:num=21:unable to verify the first certificate 就是漏发中间证书;出现 3 项以上通常是把根证书也打包进去了,Android 4.x 之后虽能容忍,但会增加握手字节数并可能触发顺序错误(num=20:unable to get local issuer certificate 常由顺序颠倒引起)。

第二步:外部评分与批量巡检。把域名丢给 Qualys SSL Labs(https://www.ssllabs.com/ssltest/analyze.html?d=api.example.com),目标是 A 及以上,且 Chain issues 一栏必须为 None——据 SSL Labs 评分文档,链不完整会直接把等级压到 B 甚至 F。适合 CI 冒烟与巡检的工具对比如下:

工具/方式 典型命令 耗时 适用场景 局限
openssl s_client s_client -connect ... -CAfile ... <1s 发布流水线快速门禁 只验证链,不评估协议/套件
curl -vI curl -vI https://api.example.com 2>&1 | grep "SSL certificate verify" <1s CI 冒烟,验证系统信任库 输出格式随版本变化
testssl.sh 3.2+ testssl.sh --quiet --color 0 https://api.example.com | grep -E "Trust|Chain|expire" 30–90s 定时巡检脚本、合规报告 需 bash 4+、依赖 openssl 二进制
SSL Labs API analyze.html?d=... 1–3min 上线前人工复核、对外证明 有速率限制,不适合每次提交

curl 的通过标准是出现 SSL certificate verify ok.;若看到 SSL certificate problem: unable to get local issuer certificate,说明服务端链问题依旧存在,此时不要用 curl -k 掩盖,那只是跳过了验证。

第三步:真机矩阵。Android 7.0(API 24)起系统不再信任用户安装的 CA,Android 9(API 28)起默认禁止明文 HTTP,这两个版本的行为差异最容易在灰度时暴露。至少覆盖 5.1(22)、7.0(24)、9(28)、11(30)、14(34) 各一台,先用系统浏览器打通再跑 App:

# 用系统浏览器验证"设备信任库 + 服务端链"这一层,绕开 App 自身配置
adb shell am start -a android.intent.action.VIEW -d https://api.example.com

# 确认设备上安装的 CA 数量与 targetSdkVersion,排查"用户证书不被信任"类问题
adb shell settings get secure user_setup_complete
adb shell dumpsys package com.example.app | grep -E "targetSdk|versionName"

第四步:App 内自检与线上埋点。在自定义 X509TrustManager 的 checkServerTrusted 里打印链长,能直接确认中间证书是否真的到达客户端——这是区分「服务端没发」与「客户端没认」的唯一手段:

@Override
public void checkServerTrusted(X509Certificate[] chain, String authType) throws CertificateException {
    // 期望 chain.length == 2;若为 1 说明服务端未下发中间证书
    Log.d("TLS", "chain.length=" + chain.length);
    for (X509Certificate c : chain) {
        Log.d("TLS", "subject=" + c.getSubjectDN() + ", notAfter=" + c.getNotAfter());
    }
    // 必须保留默认校验逻辑,禁止空实现(等价于信任所有证书)
    defaultTrustManager.checkServerTrusted(chain, authType);
}

线上按 Build.VERSION.SDK_INT 与机型分桶统计 SSLHandshakeException(典型信息 Trust anchor for certification path not found)的发生率,比总量更能定位长尾问题。

第五步:续期回归。Let’s Encrypt 证书有效期为 90 天,据其官方文档建议在到期前 30 天续期。把「续期」与「reload」拆成两步,并在 reload 后自动重跑第一步的命令,比对 notAfter 是否已更新——只 reload 未成功加载新证书时,服务端仍会返回旧证书,而浏览器和 App 都不会报错,直到过期当天集体失败。建议在续期后 24 小时内复查一次,并把 openssl s_client 的返回码写进告警规则。

老安卓与 Let's Encrypt:ISRG Root X1 的兼容时间线

为什么 2016 年的老手机,到 2025 年还在报”证书不受信任”?因为报错的往往不是你的证书,而是设备的系统根库里压根没有 ISRG Root X1 这张根。ISRG Root X1 于 2015-06-04 生成,直到 Android 7.1.1(API 25,2016 年 12 月)才被内置进系统根库;Android 7.0 及以下出厂即缺失,这是硬性事实,不是配置问题。

据 Let’s Encrypt 官方文档,交叉签名曾长期是老设备唯一的救命绳:X1 由 DST Root CA X3 交叉签名,而 DST Root CA X3 在 Android 2.3 时代就已内置。这根绳子断过两次:

  • 2021-09-30:DST Root CA X3 根证书到期,部分客户端(尤其未做链校验回退的实现)开始直接报错。
  • 2024-06-06:Let’s Encrypt 停止签发 X1 → DST Root CA X3 交叉证书,最后一张交叉证书于 2024-09-30 到期。此后纯 LE 证书在 Android 7.0 及以下无解,只能靠改域名、改信任锚或换 TLS 栈。

影响面别只看统计数字。Google 公布的 Android 版本分布中 7.1 以下占比已低于 3%,但国内定制 ROM、车机、POS 机、老平板仍大量停留在 5.x/6.0,B 端项目上线前必须实测终端版本,而不是查行业报告。

怎么确认一台设备到底有没有这张根?别猜,直接查系统根库文件(需 root 或可读权限):

# 1) 先算出 ISRG Root X1 在 Android 根库中的文件名(subject hash)
HASH=$(openssl x509 -in isrg-root-x1.pem -subject_hash_old -noout)
echo $HASH

# 2) 到设备上确认该文件是否存在;不存在即系统不信任该根
adb shell ls -l /system/etc/security/cacerts/$HASH.0

# 3) 顺带看服务端是否下发了完整证书链(缺中间证书同样报不受信任)
openssl s_client -connect legacy.example.com:443 -servername legacy.example.com -showcerts /dev/null 
  | openssl crl2pkcs7 -nocrl -certfile /dev/stdin | openssl pkcs7 -print_certs -noout

兼容做法 A:为老客户端保留独立域名,按 SNI 分流。让 legacy.example.com 单独部署 DigiCert、GlobalSign 这类根证书在 Android 2.3 时代就已内置的 CA,主站继续用 LE,服务端按 server_name 下发不同证书链:

# /etc/nginx/conf.d/legacy.example.com.conf
# 适用 nginx 1.11.0+(SNI 分流);ssl_protocols 默认值自 1.23.4 起为 "TLSv1.2 TLSv1.3"
server {
    listen              443 ssl;
    server_name         legacy.example.com;                      # 老终端专用域名
    ssl_certificate     /etc/nginx/certs/legacy_fullchain.pem;   # 必须含老 CA 的完整中间链
    ssl_certificate_key /etc/nginx/certs/legacy.key;
    ssl_protocols       TLSv1.2;                                 # Android 5.0+ 默认支持
    ssl_ciphers         ECDHE-RSA-AES128-GCM-SHA256:AES128-SHA;  # 末尾算法为无 ECDHE 的老终端兜底
    location / { proxy_pass http://127.0.0.1:8080; }
}

兼容做法 B:自建私有 CA,用 network_security_config 指定信任锚。这里有个容易被忽略的版本窗口:<certificates src="@raw/..."/> 自 Android 7.0(API 24)才支持,而 7.0 恰好”有 NSC、没有 X1″,是这个方案的最佳区间;6.0 及以下该配置完全不生效,只能走做法 C。

<!-- app/src/main/res/xml/network_security_config.xml -->
<!-- 适用 Android 7.0+;src 仅接受 system / user / @raw/xxx 三种取值 -->
<network-security-config>
    <domain-config cleartextTrafficPermitted="false">
        <domain includeSubdomains="true">legacy.example.com</domain>
        <trust-anchors>
            <certificates src="@raw/legacy_ca"/>   <!-- 私有 CA(PEM/DER 放 res/raw) -->
            <certificates src="system"/>            <!-- 与系统根取并集 -->
        </trust-anchors>
    </domain-config>
</network-security-config>

<!-- AndroidManifest.xml 中挂载 -->
<application android:networkSecurityConfig="@xml/network_security_config" ... >

兼容做法 C:客户端集成 Conscrypt,自带信任锚接管校验。老设备脱离系统根库限制的常用方案,适合内网与专有设备:

// app/build.gradle
dependencies {
    implementation 'org.conscrypt:conscrypt-android:2.5.2'   // 要求 minSdkVersion 21+
}

// Application.onCreate() 中执行,必须早于任何 OkHttp / HttpURLConnection 初始化
Security.insertProviderAt(Conscrypt.newProvider(), 1);      // 用 Conscrypt 接管 JSSE 默认实现

// 把 ISRG Root X1 打进 App:res/raw/isrg_root_x1.pem
KeyStore ks = KeyStore.getInstance("PKCS12");
ks.load(null, null);
CertificateFactory cf = CertificateFactory.getInstance("X.509");
try (InputStream in = getResources().openRawResource(R.raw.isrg_root_x1)) {
    ks.setCertificateEntry("isrg-root-x1", cf.generateCertificate(in));
}
TrustManagerFactory tmf = TrustManagerFactory.getInstance("X.509", Conscrypt.newProvider());
tmf.init(ks);   // 信任锚只来自 App 内置根库,绕开 /system/etc/security/cacerts

三种路线怎么选,取决于你的终端版本分布和改动权限:

方案 适用 Android 版本 信任锚来源 改动位置 主要风险
A 独立域名 + 老 CA 2.3+ 全覆盖 系统根库(老牌公共 CA) DNS + 服务端证书 双份证书续期运维;老域名长期存在
B 私有 CA + NSC 7.0+(API 24) res/raw 内置 CA 客户端配置 + 服务端 7.0 以下不生效;CA 私钥泄露即全盘失守
C Conscrypt + 内置根 4.x+(minSdk 21 起) App 自带 KeyStore 客户端代码 增加约 1.5 MB 包体;须接管全部网络栈

补充一个常被踩的坑:Android 4.4 及以下默认不协商 TLS 1.2,方案 A 里若为兼容而打开 TLSv1,据 Mozilla Server Side TLS 指南属于已废弃协议,仅建议在隔离内网使用;公网场景优先把老终端迁到做法 C,而不是降级协议。

Android 7.0(API 24)起,targetSdkVersion ≥ 24 的应用默认只信任系统 CA,用户安装的证书需要在 network_security_config.xml 中用 显式放行。另外要确认安装的是带 Basic Constraints CA:TRUE 的 CA 证书,而不是服务器 leaf 证书。

根因是 Android 7.1.1 以下的系统根库没有 ISRG Root X1,且 Let's Encrypt 自 2024-06-06 起不再提供 X1→DST Root CA X3 交叉证书。可给老设备单独域名部署 DigiCert 等老根 CA 证书,或在 App 内集成 Conscrypt 2.5.x 使用其自带信任库。

公网 CA 基本不签发 IP SAN,部分商业 CA 支持内网 IP 但需付费且审核周期长。可行做法是用私有 CA 在 SAN 中写入 subjectAltName=IP:10.0.0.5 后签发,或改用域名加内网 DNS 解析,让客户端走域名访问。

调试包用 放行 user 证书即可,release 包自动忽略。若确实需要在灰度包抓包,需在 domain-config 中把 src="user" 限定到测试域名,且 Android 11(API 30)以上未 root 的设备无法把证书写入系统库,需改用 VPN 模式抓包。

面向公众的 App 后端用公有 DV 证书(Let's Encrypt 0 元,商业 DV 约 500-2000 元/年);内网服务与 IoT 设备用私有 CA 加 MDM 下发根证书;自签名只用于本地开发联调,不要上生产环境,否则每次系统升级都可能引发新的信任问题。

不一定。实际案例中约一半是链不完整,另一半是 CA 不在客户端信任库,包括用户证书未放行、私有 CA 未内置、老系统缺根证书。先跑 openssl s_client -showcerts 数清下发张数,再判断是补链还是改信任配置。

Android 14(API 34)起根证书可通过 Google Play 系统组件 com.google.android.truststore 独立更新,不再强依赖 OTA 升级。升级 targetSdkVersion 到 34 后建议回归一遍 network_security_config 的生效情况,尤其是依赖 debug-overrides 的测试流程。


本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。