跳到主要内容

NET::ERR_SSL_PINNED_KEY_NOT_IN_CERT_CHAIN 全解析:证书锁定失败的根因、修复步骤与验证脚本

一、问题背景:这个报错到底在说什么

NET::ERR_SSL_PINNED_KEY_NOT_IN_CERT_CHAIN 是 Chromium 网络栈的错误码,内部值 net::ERR_SSL_PINNED_KEY_NOT_IN_CERT_CHAIN = -150。它的语义非常明确:TLS 握手本身是成功的,服务器证书的域名、有效期、签发链全部通过常规校验,但客户端在“证书锁定(Certificate Pinning)”这一步失败——服务器实际下发的证书链里,没有任何一个公钥(SPKI)的 SHA-256 哈希命中客户端预置的 pin 列表。

这决定了排查方向:它不是证书过期(ERR_CERT_DATE_INVALID),不是域名不匹配(ERR_CERT_COMMON_NAME_INVALID),也不是中间证书缺失(ERR_CERT_AUTHORITY_INVALID)。最典型的特征是“命令行正常、特定客户端报错”:用 curl、openssl、Postman 请求一切正常,因为它们在设计上不做 pinning;只有带锁定逻辑的客户端才会触发。

触发者通常只有三类:一是 App 内置 pinning(OkHttp CertificatePinner、Android network_security_config、iOS TrustKit、Flutter 的 pinning 插件);二是浏览器/系统内置的静态 pin(Chrome 对 Google 自有域名内置,企业可通过策略或 MDM 下发);三是企业 TLS 检查代理用自签 CA 重签了证书,导致整条链的 SPKI 全部改变。

还要先破除一个常见误区:HPKP(HTTP Public Key Pinning)响应头在 Chrome 72(2019 年 1 月)和 Firefox 72 中已被彻底移除,现代浏览器不会再因为响应头里的 Public-Key-Pins 报这个错。但服务器上遗留的响应头仍是重要线索,它说明历史上做过 HPKP,通常也意味着 App 侧同时存在 pinning 逻辑,二者要一起处理。

二、根因剖析:三条互相独立的锁定路径

路径一:应用内 pinning(占比最高)。开发者在 App 里硬编码了证书或公钥的 SHA-256 pin。运维在服务端换了证书——比如从 DigiCert 换到 Let’s Encrypt,或者同一 CA 但重新签发了密钥对——新证书的 SPKI 哈希变了,旧版本 App 的 pin 列表对不上,立刻抛错。由于主流 CA 的证书最长有效期已被限制在 398 天,Let’s Encrypt 更是只有 90 天,换证频率比过去高得多,这类故障因此显著增加。

路径二:浏览器/系统内置静态 pin。Chrome 对 Google 自有域名(如 google.com、gstatic)内置了 pin 列表,这些站点一旦更换密钥而 Chrome 版本过旧,同样会报 -150。企业环境里,管理员可能通过组策略或 MDM 向 Chrome、Edge 下发证书锁定配置,普通用户无从感知,需要到 chrome://policy 查看。

路径三:企业 TLS 检查代理(中间人解密)。防火墙或 SASE 网关(Palo Alto、Fortinet、Zscaler、深信服 AC 等)对 HTTPS 做解密再重签,客户端看到的是代理自签 CA 签发的证书,SPKI 与真实站点完全不同,任何 pin 都会失败。这类故障的识别特征是证书 issuer 变成厂商名称。

关键区分点:路径一、二失败在客户端代码/策略层,服务端做什么都无用;路径三失败在网络中间设备,需要在代理上放行。三者排查手段不同,必须先定位,再动手。

三、实操步骤(一):定位锁定来源并计算 SPKI

第一步先确认服务端有没有遗留的 pinning 响应头,并拿到真实证书链的公钥哈希,用来和客户端 pin 列表比对。

# 1) 检查遗留的 HPKP / Expect-CT 响应头
curl -sSI https://api.example.com | grep -iE 'public-key-pins|expect-ct' 
  || echo 'no pinning header'

# 2) 计算叶子证书的 SPKI pin(与 App 里的 sha256/xxx= 直接可比)
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null 
  | openssl x509 -pubkey -noout 
  | openssl pkey -pubin -outform der 
  | openssl dgst -sha256 -binary 
  | openssl enc -base64

如果客户端 pin 的是中间证书或根证书,需要把整条链拆开逐个算:

i=0
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null 
| awk '/BEGIN CERTIFICATE/{i++} i>0{print > ("chain" i ".pem")}'
for f in chain*.pem; do
  printf '%s sha256/%sn' "$f" "$(openssl x509 -in "$f" -pubkey -noout 
    | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64)"
done

第三步判断客户端类型。Android 用 adb logcat -s CertificatePinner:* OkHttp:* 抓日志;iOS 用 Console.app 过滤 TrustKit 或 NSURLErrorDomain;Chrome 打开 chrome://net-export/ 导出 netlog,搜索 PINNED_KEY 与 -150,同时在 chrome://policy 搜索锁定相关策略。最后用 openssl s_client -connect host:443 -servername host | openssl x509 -noout -issuer -subject 看 issuer,若是 Fortinet、Zscaler 之类,直接判定为代理中间人。

四、实操步骤(二):清理 HPKP、放行代理与正确的换证顺序

若确认存在遗留响应头,先在入口层彻底移除。Nginx 自身无法直接删除上游下发的头,需要 headers-more 模块;Apache 用 Header unset。

# Nginx:先全局搜索残留配置
# grep -rn 'Public-Key-Pins' /etc/nginx/

# 若来自上游应用,隐藏它
proxy_hide_header Public-Key-Pins;

# 若由 headers-more 模块管理
more_clear_headers 'Public-Key-Pins' 'Public-Key-Pins-Report-Only' 'Expect-CT';
# Apache httpd
Header always unset Public-Key-Pins
Header always unset Public-Key-Pins-Report-Only
Header always unset Expect-CT

注意:移除响应头只能阻止新的 pin 被缓存,对已经缓存 pin 的老客户端无效——它们要等到 max-age 过期才释放。好在现代浏览器已不执行 HPKP,实际影响面仅限 ≤71 的老版本。

企业代理场景,把业务域名加入 SSL 解密白名单:Palo Alto 在 Decryption Policy 中对该目标设为 No Decrypt;FortiGate 在 SSL Inspection 里配置 exempt 列表;Zscaler 在 SSL Inspection Policy 中按 URL 分类绕过;深信服 AC 在 SSL 内容识别 里排除该域名。

最关键的运维纪律是换证顺序,绝不能反过来:① 先把新公钥的 pin 加进客户端并发布新版本;② 监控旧版本 App 的流量占比降到 5% 以下;③ 才在服务端切换证书。服务端先换、客户端后跟,必然导致存量用户全线报错。

五、配置示例:Android、OkHttp、iOS 的正确 Pinning 写法

核心原则只有两条:至少配两个 pin(当前 + 备用),以及尽量 pin 中间 CA 而非叶子证书。叶子证书 90~398 天就换一次,中间 CA 通常能用 5~10 年。

<!-- Android res/xml/network_security_config.xml -->
<network-security-config>
  <domain-config>
    <domain includeSubdomains='true'>api.example.com</domain>
    <pin-set expiration='2027-06-30'>
      <!-- 当前中间 CA 的 SPKI -->
      <pin digest='SHA-256'>AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</pin>
      <!-- 备用 CA 或备用密钥 -->
      <pin digest='SHA-256'>BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=</pin>
    </pin-set>
  </domain-config>
</network-security-config>

expiration 属性是安全阀:到期后系统自动停止 pinning,避免因忘记续期把 App 锁死。

// OkHttp
CertificatePinner pinner = new CertificatePinner.Builder()
    .add("api.example.com", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")
    .add("api.example.com", "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=")
    .build();
OkHttpClient client = new OkHttpClient.Builder().certificatePinner(pinner).build();
<!-- iOS TrustKit Info.plist -->
<key>TSKConfiguration</key>
<dict>
  <key>TSKPinnedDomains</key>
  <dict>
    <key>api.example.com</key>
    <dict>
      <key>TSKEnforcePinning</key><true/>
      <key>TSKIncludeSubdomains</key><true/>
      <key>TSKPublicKeyHashes</key>
      <array>
        <string>AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</string>
        <string>BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=</string>
      </array>
    </dict>
  </dict>
</dict>

上线前务必把 TSKEnforcePinning 设为 false 跑一段“仅上报”模式,观察线上是否有 pin 不匹配的流量,确认无异常后再改为强制。

六、方案对比:五种防护机制怎么选

机制 部署位置 生效范围 换证风险 现状
HPKP 服务端响应头 Chrome ≤71 / Firefox ≤71 极高,易自锁 已废弃,Chrome 72 / Firefox 72 移除
应用内 Pinning 客户端代码 仅自家 App 高,需发版同步 推荐,但必须配双 pin + expiration
Certificate Transparency CA 日志 + SCT 全平台浏览器 低 Chrome 强制要求 SCT
CAA 记录 DNS 所有公共 CA 无 推荐作为基础防线
mTLS 双向证书 自控客户端 中 内网与 API 场景推荐

结论很清晰:HPKP 不要再用,它在设计上就存在“配置错误即永久锁死”的缺陷,浏览器厂商因此集体移除。真正需要防 CA 误签时,优先用 CAA + CT 监控做“发现层”,用应用内 Pinning 做“强制层”。如果只做 App 与后端 API 之间的通信,mTLS 往往比 pinning 更省心——客户端证书可以随包分发、可吊销、可轮换,不必担心服务端换证导致的连锁故障。

如果业务必须保留 pinning,请把 pin 对象从叶子证书改为中间 CA,并保留至少一个来自不同 CA 的备用 pin。这样即便某家 CA 出问题需要整体迁移,客户端也不会瞬间失联。

七、常见错误排查:真实报错与处理

1)Android + OkHttp:

javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure!
  Peer certificate chain:
    sha256/AAAA...=: CN=*.example.com, O=Example Inc
    sha256/CCCC...=: CN=R3, O=Let's Encrypt
  Pinned certificates for api.example.com:
    sha256/BBBB...=

处理:把日志里的 sha256/AAAA...= 与代码中的 pin 对比,确认是换证导致。短期救火只能发新版 App 或引导用户升级;长期按第五节改造为双 pin。

2)Android network_security_config:报 java.security.cert.CertificateException: Pin verification failed 或 Chain validation failed。检查 pin-set 的 expiration 是否已过期、digest 是否写成 SHA-256(大小写敏感)。

3)iOS TrustKit:Console 输出 Domain api.example.com failed pinning validation,伴随 NSURLErrorDomain Code=-1200。多为后台换了证书但 App 未更新,或 TSKPublicKeyHashes 填成了证书 DER 哈希而非 SPKI 哈希。

4)浏览器报错但 curl 正常:说明服务端没问题,问题在客户端 pin 或企业策略。用 chrome://net-export/ 抓日志,搜索 PINNED_KEY 即可定位是哪条 pin 未命中。

5)证书 issuer 异常:openssl s_client ... | openssl x509 -noout -issuer 输出 O=Fortinet、O=Zscaler、O=Sangfor 时,100% 是 TLS 检查代理,去代理侧加白名单,不要动服务端证书。

6)易混淆项:如果报的是 ERR_CERT_AUTHORITY_INVALID,那是证书链不受信(漏配中间证书、自签根未安装),与本错误无关,别把中间证书删了去“修”pinning 问题。

八、效果验证:脚本化巡检与灰度换证

修复后必须验证两件事:服务端不再下发 pinning 头,且线上证书的 SPKI 始终在客户端 pin 列表内。把下面的脚本挂到 cron 或 CI 里,证书到期前 30 天自动告警。

#!/usr/bin/env bash
set -euo pipefail
DOMAIN='api.example.com'
PIN_FILE='pins.txt'   # 每行一个 sha256/xxx=

ACTUAL=$(openssl s_client -connect "$DOMAIN:443" -servername "$DOMAIN" -showcerts </dev/null 2>/dev/null 
  | openssl x509 -pubkey -noout 
  | openssl pkey -pubin -outform der 
  | openssl dgst -sha256 -binary | openssl enc -base64)

if grep -qx "sha256/$ACTUAL" "$PIN_FILE"; then
  echo "OK: sha256/$ACTUAL matched"
else
  echo "FAIL: sha256/$ACTUAL not in $PIN_FILE"; exit 1
fi

# 顺带校验有效期,398 天上限下必须提前预警
openssl s_client -connect "$DOMAIN:443" -servername "$DOMAIN" </dev/null 2>/dev/null 
  | openssl x509 -noout -enddate

客户端侧验证:Android 安装旧版本 APK 与新证书组合测试,adb logcat | grep -i pin 应无输出;iOS 用 TestFlight 灰度包验证;浏览器侧访问 chrome://net-export/ 确认错误码 -150 不再出现。最后做灰度换证:先在预发环境用新证书跑一周,观察 App 崩溃率与网络错误率,再切生产。

别忘了把 pin 计算纳入证书申请流程——CSR 生成时就同步算出新公钥的 SPKI,写入客户端配置仓库,避免“证书已换、pin 未更新”的经典事故。

常见问题

浏览器不执行你 App 里的 pin 列表。App 内置了 SPKI 锁定,服务端换证后新公钥不在列表中就会报错。用 openssl 算出当前证书的 sha256 SPKI 哈希,与 App 代码里的 pin 值比对,不一致即可确认。


HPKP 已被 Chrome 72 和 Firefox 72 移除,现代浏览器不再执行该响应头。若仍报错,来源必然是 App 内置 pin、系统或企业策略、或 TLS 检查代理。删头只对 ≤71 的老客户端有意义。[/sg_faq_question]

不一定。正确做法是 pin 中间 CA 或备用密钥,并在客户端预置两个 pin。这样只要新证书仍由同一 CA 签发,pin 依然匹配,无需发版。只有 pin 叶子证书时才必须同步发版。[/sg_faq_question]

可以,但只能 pin ISRG Root X1 或中间证书的公钥,不能 pin 叶子证书——它 90 天就变一次。同时要设置 pin-set expiration,并准备一个来自其他 CA 的备用 pin 以防整体迁移。[/sg_faq_question]

执行 openssl s_client -connect host:443 -servername host 后接 openssl x509 -noout -issuer。若 issuer 显示 Fortinet、Zscaler、Sangfor 等厂商名称,说明被中间人重签,把域名加入代理的 SSL 解密白名单即可。[/sg_faq_question]

后者是证书链本身不受信任,比如漏配中间证书、自签根未安装;前者是证书链可信但公钥没命中 pin。排查方向完全不同,删中间证书或换自签证书会引发后者,不要混淆。