跳到主要内容

NET::ERR_SSL_PINNED_KEY_NOT_IN_CERT_CHAIN 全解析:证书锁定失败的原因、修复与验证

问题背景:错误码与影响范围

NET::ERR_SSL_PINNED_KEY_NOT_IN_CERT_CHAIN 是 Chromium 网络栈的证书锁定校验错误:TLS 握手拿到的证书链可以受信任,但链中任一证书的 SPKI SHA-256 指纹都不在客户端锁定列表里。它不等同于证书过期、域名不匹配或根证书缺失。常见触发是服务器更换了叶子证书或中间证书,而客户端仍固定旧公钥;也可能是旧项目遗留 HPKP 响应头,或企业 TLS 检查代理重签证书。

需要先明确:主流浏览器已移除 HPKP 支持,Chrome 与 Firefox 不再执行 Public-Key-Pins;该错误更多出现在内嵌 Chromium/WebView、旧客户端或应用内 pinning。公共 TLS 证书最长有效期目前为 398 天,Let’s Encrypt 默认 90 天,轮换频率高,任何 pin 方案都必须有备份与灰度。典型遗留头为 Public-Key-Pins: pin-sha256=BASE64; max-age=5184000; includeSubDomains,清除时需下发 max-age=0 并移除响应头。

快速看响应头:

curl -sSI https://example.com | grep -i '^public-key-pins'

有输出说明服务端仍在下发 HPKP 头;无输出也不能排除 App 内 pinning。

根因拆解与现场定位

根因分三条链路。第一,HPKP 遗留:服务器曾下发 Public-Key-Pins,旧浏览器/WebView 缓存后,换证即报错;浏览器已不再支持,但旧客户端可能仍生效。第二,应用内 pinning:Android Network Security Config、OkHttp CertificatePinner、iOS ATS NSPinnedDomains 或自研 TrustManager 把公钥写死在包内,服务端换证后新 SPKI 不在列表。第三,企业 TLS 检查代理:代理用企业 CA 重签站点证书,客户端看到的 issuer 变为 Corp Proxy CA,pin 自然不匹配。

定位命令:

openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -subject -issuer -dates
openssl s_client -connect example.com:443 -servername example.com -showcerts < /dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -fingerprint -sha256
openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

第三条输出就是当前叶子证书 SPKI pin,与客户端配置逐字比对。若 issuer 不是预期 CA,先查代理;若证书链正常,再查 App 版本与 pin 列表。注意 pin 的是 SPKI 而非证书文件哈希,换证但复用密钥时 pin 可能不变,反之换密钥必变。

服务端处理:移除遗留 HPKP 并安全换证

服务端处理分两步:移除遗留 HPKP,再按 pin 策略换证。Nginx 若安装了 headers-more 模块,用 more_clear_headers Public-Key-Pins;;没有模块时不要用 add_header Public-Key-Pins '' 试图覆盖,应在 CDN/反代源头删除。Apache 用 Header always unset Public-Key-Pins。示例:

server {
  listen 443 ssl;
  server_name example.com;
  ssl_certificate /etc/ssl/example/fullchain.pem;
  ssl_certificate_key /etc/ssl/example/privkey.pem;
  add_header Strict-Transport-Security max-age=31536000 always;
  # 禁止再出现 Public-Key-Pins
}

Apache:

Header always unset Public-Key-Pins
Header always set Strict-Transport-Security max-age=31536000

换证前检查有效期与链:openssl x509 -in fullchain.pem -noout -dates -subject -issuer;openssl s_client -connect example.com:443 -servername example.com -verify_return_error < /dev/null。若使用 Let’s Encrypt,90 天自动续期会频繁更换叶子公钥;不要把叶子 pin 写死在服务端之外。需要换证时,先确认客户端已带新 pin 与备份 pin,再切换证书;否则只能回滚旧证书。公共证书最长 398 天,但 pin 的生命周期由客户端版本决定,往往更长。

应用内 pinning:更新流程与配置示例

应用内 pinning 的正确顺序是「先发客户端,再换服务端证书」。以 Android Network Security Config 为例:

<network-security-config>
  <domain-config cleartextTrafficPermitted='false'>
    <domain includeSubdomains='true'>api.example.com</domain>
    <pin-set expiration='2027-06-30'>
      <pin digest='SHA-256'>CURRENT_PIN_BASE64=</pin>
      <pin digest='SHA-256'>BACKUP_PIN_BASE64=</pin>
    </pin-set>
  </domain-config>
</network-security-config>

iOS 14+ 可在 Info.plist 的 NSAppTransportSecurity 下配置 NSPinnedDomains,用 NSPinnedLeafIdentities 或 NSPinnedCAIdentities 写入 SPKI-SHA256-BASE64,至少保留一个备份。OkHttp 用 CertificatePinner.Builder().add('api.example.com','sha256/CURRENT_PIN_BASE64=').add('api.example.com','sha256/BACKUP_PIN_BASE64=').build()。发布策略:新版本同时包含当前 pin 与下一把 pin,灰度到 95% 以上再换证;保留回滚证书与旧 pin 至少一个发布周期;按 App 版本统计 pin 失败率。禁止只改服务端证书而不发客户端,否则旧版本会持续报 NET::ERR_SSL_PINNED_KEY_NOT_IN_CERT_CHAIN 或 OkHttp 的 Certificate pinning failure。

计算 SPKI pin 与备份 pin

计算 pin 必须针对 SPKI,不是证书 DER 的 SHA-256。对本地 fullchain.pem 先拆分:

csplit -s -z -f cert- -b '%02d.pem' fullchain.pem '/BEGIN CERTIFICATE/' '{*}'
openssl x509 -in cert-01.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64
openssl x509 -in cert-02.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

cert-01 通常是叶子证书,cert-02 是中间证书。远程核对:

openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

备份 pin 可来自备用中间 CA,或离线生成的备用密钥:

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out backup.key
openssl pkey -in backup.key -pubout -outform der | openssl dgst -sha256 -binary | openssl enc -base64

把输出转成 sha256/BASE64= 填入客户端。注意 SHA-256 SPKI base64 通常 44 字符并以 = 结尾;少一位、换行、URL-safe 编码都会导致不匹配。

方案对比:HPKP、应用内 pinning 与代理白名单

方案 锁定对象 更新方式 适用场景 主要风险
HPKP 响应头 SPKI pin-sha256 max-age=0 清除 历史遗留 浏览器已移除,旧客户端缓存难清
应用内 pin 叶子证书 叶子 SPKI 发新版客户端 高安全 App 90/398 天轮换即失败
应用内 pin 中间 CA 中间证书 SPKI 发新版客户端 推荐默认 换 CA 时仍需备份 pin
企业代理白名单 站点域名 代理策略下发 内网 TLS 检查 绕过检查带来合规风险
CAA/CT 监控 签发策略与日志 DNS/监控配置 发现误签发 不能替代客户端 pin

结论:新项目不要使用 HPKP;应用内 pinning 优先 pin 中间 CA 并保留备份 pin;企业内网被代理拦截时,把站点加入代理白名单,或把企业根证书纳入信任链并同步更新 pin。CAA 与 CT 用于监控签发,不解决公钥锁定失败。

常见错误排查与真实报错

  • NET::ERR_SSL_PINNED_KEY_NOT_IN_CERT_CHAIN:pin 不匹配。查响应头、证书 issuer、App 版本;回滚证书或发新 pin。
  • javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure! Peer certificate chain::OkHttp 报错。打印 certificate.publicKey().encoded 的 SHA-256,核对 sha256/...=。
  • java.security.cert.CertPathValidatorException: Trust anchor for certification path not found:Android 不信任代理 CA 或链缺失。安装企业根证书到信任库,或代理白名单;不要用 pin 掩盖链问题。
  • curl: (60) SSL certificate problem: unable to get local issuer certificate:服务器未发中间证书。确保 fullchain.pem 包含中间证书。
  • NSURLErrorDomain Code=-1200:iOS ATS/证书信任失败。用 nscurl --ats-diagnostics 检查 NSPinnedDomains 与代理。
adb logcat | grep -i -E 'pin|SSLPeerUnverified|CertPathValidator'
nscurl --ats-diagnostics https://api.example.com
for ip in $(dig +short api.example.com); do echo $ip; openssl s_client -connect $ip:443 -servername api.example.com -showcerts < /dev/null 2>/dev/null | openssl x509 -noout -issuer -subject; done

若多个 A 记录返回不同证书,逐 IP 检查,排除 CDN 边缘节点混用旧证书。若仅部分 App 版本失败,基本是客户端 pin 列表未更新。

效果验证与回归

修复后按四步验证。第一,确认响应头已清除:curl -sSI https://example.com | grep -i '^public-key-pins' 应无输出。第二,确认证书链与有效期:

openssl s_client -connect example.com:443 -servername example.com -showcerts < /dev/null 2>/dev/null | openssl x509 -noout -dates -subject -issuer
openssl s_client -connect example.com:443 -servername example.com -verify_return_error < /dev/null

第三,重新计算 pin 并与客户端配置比对;Android 用 adb logcat 观察握手,iOS 用 nscurl --ats-diagnostics。第四,灰度发布新客户端,按版本统计 pin 失败率,保留旧证书回滚窗口。监控至少包含证书到期时间、issuer、SPKI 指纹和 App 版本维度。

常见问题

不一定。它表示证书链可信但 SPKI 指纹不在锁定列表,过期、域名不匹配通常报 ERR_CERT_DATE_INVALID 等。先查是否换证、是否走 TLS 检查代理,再比对客户端 pin。

不能作为新方案。Chrome、Firefox 已移除 HPKP 支持,继续下发 Public-Key-Pins 没有收益且可能影响旧客户端。应删除遗留响应头,改用应用内 pinning 或 CAA/CT 监控。

优先 pin 中间 CA 并保留备份 pin,因为叶子证书 90 天或 398 天就会轮换。若合规要求 pin 叶子,必须同时内置当前与下一把 pin,灰度发布后再换证。

立即回滚旧证书,或让 CDN 切回旧证书链,为发版争取时间;同时发布包含新 pin 与备份 pin 的客户端。应用内 pinning 无法只靠服务端配置解决。

如果 pin 了叶子公钥,会。ACME 续期通常生成新密钥,SPKI 改变即失败。应 pin 中间 CA,或把新 pin 提前写入客户端并自动化校验续期后的指纹。