跳到主要内容
基础知识

SSL Pinning 证书锁定实战:Android 与 iOS 公钥锁定配置、报错排查与轮换验证

ssl pinning 证书锁定 — SSL Pinning 证书锁定实战:Android 与 iOS 公钥锁定配置、报错排查与轮换验证
核心结论

SSL Pinning 证书锁定是在客户端把服务端证书公钥(SPKI)的 SHA-256 哈希写死,只信任指定公钥;生产配置至少放 2 个 pin(当前+备份),否则证书轮换时会出现全量 SSLPeerUnverifiedException。 Android 7.0(API 24)起可用 network_security_config.xml 的 ,OkHttp 4.12.0 用 CertificatePinner.Builder().add("api.example.com", "sha256/...");iOS 需 URLSessionDelegate 或 TrustKit 3.0.0。 计算 pin 的命令:openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64,OpenSSL 3.0.13 实测可用。 HPKP 虽由 RFC 7469 定义,但 Chrome 72(2019-01)已移除,Web 端不要再用;移动端 pin 中间 CA 公钥可把轮换成本从 90 天一次降到 1-3 年一次。 验证时先做正向握手,再故意改错一个 pin 字符触发 javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure,确认失败路径可观测后再灰度 5% 用户 24 小时。

为什么 SSL Pinning 证书锁定会在证书轮换时集中爆发?

为什么服务端只是换了一张证书,App 就大面积连不上?

因为 SSL Pinning 证书锁定把客户端的信任范围从”任意公共 CA”收窄成了”指定公钥的 SHA-256 哈希”。信任判断从”验证 CA 签名链”变成”比对硬编码哈希”之后,证书生命周期就被绑死在 App 发版周期上:服务端换证书那一刻,旧版本客户端手里那把唯一的尺子就失效了。这跟证书类型无关——DV、OV、EV 都可能被 pin,真正的变量只有三个:公钥是否变化、中间 CA 是否更换、backup pin 是否真实可用。

为什么用 Let’s Encrypt 的项目风险最高?

据 Let’s Encrypt 官方文档,其证书有效期 90 天,到期前 30 天即可续期。若 pin 的是叶子证书公钥,一年至少触发 4 次轮换;而移动端应用商店审核通常 1–3 天,撞上春节、圣诞的审核冻结窗口,发版根本追不上。HPKP 当年就是被这个矛盾拖垮的:RFC 7469 定义了 max-age 与 backup pin,但配置失误会造成整站自锁、且易被滥用,Chrome 72(2019 年 1 月)正式移除支持。Web 端现在更推荐 CAA 记录加 Certificate Transparency 日志监控,移动端则只能靠 pin 集合设计自救。

该 pin 哪一层?先看这张表

Pin 对象 轮换频率 典型失效场景 结论
叶子证书 SPKI 90 天(Let’s Encrypt) 每次自动续期都换公钥 年发版 4 次以上,必须配可用的 backup pin
中间 CA SPKI 数年 服务端换 CA(如 DigiCert → Let’s Encrypt) 业界主流,建议同时 pin 两家 CA
根 CA SPKI 10 年以上 根过期或交叉签名链变化 防护面过宽,几乎等于不 pin
完整证书(含有效期) 90 天 必然失效 不推荐,等于定时炸弹

发版前怎么验证 pin 集合没有踩空?

# 用途:轮换前核对线上证书的 SPKI SHA-256 是否命中客户端内置 pin
# 适用:OpenSSL 1.1.1 / 3.x(openssl pkey 子命令自 1.0.0 起提供)
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null 
  | openssl x509 -noout -pubkey 
  | openssl pkey -pubin -outform der 
  | openssl dgst -sha256 -binary 
  | openssl base64
# 输出形如 R8b0mZ0k...= ,与 OkHttp CertificatePinner("sha256/R8b0mZ0k...=") 逐字节比对

# 看整条链(叶子 + 中间 CA),确认 backup pin 是否覆盖了新的中间 CA
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null 
  | openssl crl2pkcs7 -nocrl -certfile /dev/stdin 
  | openssl pkcs7 -print_certs -noout

客户端侧同样有默认值陷阱:OkHttp 的 CertificatePinner 默认不启用任何 pin,必须显式 add();TrustKit iOS 的 TSKEnforcePinning 默认是 YES,pin 集合全部失配时直接阻断请求,TSKIncludeSubdomains 默认 NO,TSKPublicKeyAlgorithms 默认 [TSKAlgorithmRsa2048]——如果你的新链是 ECDSA,这个默认值会让校验直接落空。

报错长什么样,为什么服务端日志是干净的?

Android 端典型堆栈是 javax.net.ssl.SSLPeerUnverifiedException: public key pinning failure;iOS 端 TrustKit 记录 pin validation failed for <hostname>,请求以 NSURLErrorDomain Code=-999 或 -1202 失败。关键点在于:这些错误发生在 TLS 握手完成之后的客户端校验阶段,所以 Nginx 的 access_log 里只看到一条没写完的请求,甚至什么都没有。典型事故链路因此是——服务端更换中间 CA → 客户端 backup pin 未覆盖新链 → Android 端错误率从 0.2% 飙到 37% → 运维盯 access_log 却一片正常。

排查必须两头对齐:客户端拉 pin 失败日志与内置哈希列表,服务端用上面的 openssl s_client 确认链上每个证书的 SPKI。根本原因从来不是 TLS 协议失败,而是 CertificatePinner 或 TrustKit 在校验阶段主动抛错。

证书锁定的三种对象:叶子证书、公钥与 CA 公钥怎么选?

很多团队第一次做 ssl pinning 证书锁定,都是把服务器证书的 DER 拿去做 SHA-256,然后写进配置。上线三个月后 Let’s Encrypt 自动续期,App 全线报 SSLPeerUnverifiedException。问题不在实现,而在锁错了对象。据 Let’s Encrypt 文档,其证书有效期已缩短至 90 天(2025 年起还在推进更短周期),每次续期叶子证书的序列号、公钥、签名全部变化——整证书锁定在这个节奏下等于给自己设定时故障。

Android NSC 和 OkHttp 到底锁的是什么?两者锁的都是 SPKI(Subject Public Key Info)的 SHA-256,而不是整证书哈希,这与 RFC 7469 定义的 HTTP Public Key Pinning 一致。也就是说 XML 里那个 <pin digest="SHA-256"> 的 base64 值,是对公钥 DER 做哈希后再 base64,不是对证书做哈希。这一点搞错,pin 永远对不上。

锁定对象 pin 值来源 轮换频率 安全强度 移动端适用性
整证书(DER 哈希) 证书文件本身 90 天(Let’s Encrypt) 高 不可行,除非自建 CA 且长周期
叶子公钥 SPKI 叶子证书公钥 每次签发新密钥 最高 需 --reuse-key + 高频发版
中间 CA 公钥 R10/R11/E5/E6 等 1–3 年 中高 推荐主 pin
根 CA 公钥 ISRG Root X1/X2 X1 至 2035-06-04 最低 仅作备份 pin

怎么把这三个 pin 值算出来?用 OpenSSL 1.1.1 或 3.x,对着线上真实链路取:

# 1) 抓取完整证书链(-showcerts 会输出服务器发送的所有证书)
openssl s_client -connect api.example.com:443 -servername api.example.com 
  -showcerts /dev/null > chain.pem

# 2) 叶子证书公钥 SPKI 的 SHA-256(base64),即 OkHttp/NSC 用的 pin
openssl x509 -in chain.pem -pubkey -noout 
  | openssl pkey -pubin -outform der 
  | openssl dgst -sha256 -binary | openssl enc -base64

# 3) 第一张中间 CA 的公钥 pin(awk 取第 2 个 BEGIN CERTIFICATE 块)
awk '/BEGIN CERTIFICATE/{n++} n==2' chain.pem 
  | openssl x509 -pubkey -noout 
  | openssl pkey -pubin -outform der 
  | openssl dgst -sha256 -binary | openssl enc -base64

# 4) 确认中间证书主体,避免锁错(应为 R10/R11 或 E5/E6)
awk '/BEGIN CERTIFICATE/{n++} n==2' chain.pem | openssl x509 -noout -subject -enddate

坚持 pin 叶子公钥怎么办?必须让私钥不随续期变化。Certbot 从 1.3.0 起提供 --reuse-key,默认关闭,需要显式写进续期配置:

# /etc/letsencrypt/renewal/api.example.com.conf 中追加(certbot >= 1.3.0)
# 复用现有私钥,保证叶子公钥 pin 在续期后依然有效
renew_before_expiry = 30 days
reuse_key = True

即便如此,密钥一旦泄露或需要算法升级(如 RSA→ECDSA),pin 仍然要变,而 iOS/Android 的发版审核周期是硬约束——这正是多数团队放弃叶子 pin 的原因。

折中方案怎么配?业界常见做法是 3 个 pin:当前中间 CA + 备用中间 CA + 根 CA。Android 从 API 24 起支持 <pin-set>,expiration 属性是必填的,缺失会导致网络配置解析失败(XmlPullParserException),App 启动即崩溃;建议不超过 4 个 pin,避免配置膨胀:

<!-- res/xml/network_security_config.xml,API 24+ -->
<network-security-config>
  <domain-config>
    <domain includeSubdomains="false">api.example.com</domain>
    <pin-set expiration="2026-06-30">
      <!-- 当前中间 CA:Let's Encrypt R11 的 SPKI SHA-256 -->
      <pin digest="SHA-256">AAAA...当前中间CA...=</pin>
      <!-- 备用中间 CA:R10,主中间证书退役时自动生效 -->
      <pin digest="SHA-256">BBBB...备用中间CA...=</pin>
      <!-- 备份根:ISRG Root X1(2035-06-04 到期),只做兜底 -->
      <pin digest="SHA-256">CCCC...ISRG Root X1...=</pin>
    </pin-set>
  </domain-config>
</network-security-config>

注意:只锁根 CA 安全性最低,因为任何一张由该根签发的证书都能通过校验,等于把锁定退化成普通 CA 信任;据 OWASP MASVS-NETWORK-2 要求,证书锁定应覆盖所有远程通信并明确轮换策略——没有备用 pin 和到期时间的证书锁定,等同于给 App 埋定时故障。pin 校验失败时 OkHttp 抛出的典型堆栈是 javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure!,后面紧跟 Peer certificate chain: 与 Pinned certificates for api.example.com: 两段,排查时逐条比对链上每张证书的 SPKI 哈希即可定位是锁错层级还是漏配备用 pin。

SSL Pinning 证书锁定完整实操步骤(7 步)

为什么同样的 pin 配置,有人在灰度 5% 时炸出大量 NSURLErrorDomain Code=-1202,有人却能平稳切到 100%?差别几乎都在这 7 步的执行顺序上。下面每一步都给出可直接复制的命令与配置。

第 1 步:盘点域名与证书链。先确认服务端到底下发几张证书、签发者是谁。据 OpenSSL 文档,-servername 用于发送 SNI,缺少它可能拿到默认站点证书而非目标域名证书。

# OpenSSL 1.1.1+ / 3.x(macOS 自带 LibreSSL 参数不全,建议 brew install openssl@3)
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null 
  | openssl crl2pkcs7 -nocrl -certfile /dev/stdin 
  | openssl pkcs7 -print_certs -noout
# 输出示例(叶子 → 中间 → 根,逐条记录 Subject 与 notAfter)
# subject=CN = api.example.com ; issuer=CN = R3 (Let's Encrypt)
# subject=CN = R3              ; issuer=CN = ISRG Root X1
# subject=CN = ISRG Root X1    ; issuer=CN = ISRG Root X1

第 2 步:计算 SPKI SHA-256。注意锁的是 SubjectPublicKeyInfo 而非整张证书,所以证书续期只要密钥不变,pin 就不失效——这是 Let’s Encrypt 短期证书(90 天)场景下必须锁公钥的原因。

# 拆出每张证书后逐个算公钥哈希,结果固定 44 字符 base64(含 1 个 '=')
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null 
  | awk '/BEGIN CERTIFICATE/{n++} n>0{print > ("c" n ".pem")}'
for f in c1.pem c2.pem c3.pem; do
  printf '%s: ' "$f"
  openssl x509 -in "$f" -pubkey -noout 
    | openssl pkey -pubin -outform DER 
    | openssl dgst -sha256 -binary | openssl enc -base64
done
# 变更单务必附 openssl version -a 输出,不同实现曾出现过换行/编码差异

第 3 步:确定 pin 集合。至少 2 个、建议 3 个,且必须包含一枚”当前用不到但真实存在”的备用中间 CA 公钥;禁止填入来源不明的哈希。RFC 7469 的 HPKP 已被浏览器弃用,但 App 内 pinning 与它无关,仍需自建这套登记表:

pin(SHA-256) 来源证书 notAfter 负责人
47DEQpj8…hSuFU= 叶子/中间 CN=R3(当前) 2026-03-15 @ops-a
YLh1dUR9…uihg= 备用中间 CN=E6 2027-01-20 @ops-a
C5+lpZ7t…Fr8M= 根 ISRG Root X1 2035-06-04 @sec-b

第 4 步:Android NSC 配置。据 Android 开发者文档,networkSecurityConfig 自 Android 7.0(API 24)生效,expiration 到期后系统会自动忽略该 pin-set,所以它必须早于证书到期日、又不能早于你的轮换窗口。

<!-- res/xml/network_security_config.xml -->
<network-security-config>
  <domain-config>
    <domain includeSubdomains="false">api.example.com</domain>
    <pin-set expiration="2026-06-30">
      <pin digest="SHA-256">47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=</pin>
      <pin digest="SHA-256">YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg=</pin>
    </pin-set>
  </domain-config>
</network-security-config>

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

第 5 步:代码层双保险。NSC 在低版本系统与某些调试构建下不生效,用 OkHttp 4.12.0 的 CertificatePinner 补齐;两处 pin 集合必须逐字一致,否则会出现”一处更新、一处遗漏”的诡异失败。

val pinner = CertificatePinner.Builder()
    .add("api.example.com", "sha256/47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=")
    .add("api.example.com", "sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg=")
    .build()
val client = OkHttpClient.Builder().certificatePinner(pinner).build()

第 6 步:iOS 配置。TrustKit 3.0.0 在 Info.plist 中读取 kTSKPublicKeyHashes(对应键名 TSKPublicKeyHashes),灰度期把 kTSKEnforcePinning 设为 NO,只通过 TSKPinningValidationFailed 通知上报,不阻断请求;同时准备 URLSession 的 serverTrust 校验作为不引入三方库的替代方案。

<key>TSKConfiguration</key><dict>
  <key>TSKPinnedDomains</key><dict><key>api.example.com</key><dict>
    <key>TSKPublicKeyHashes</key>
    <array>
      <string>47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=</string>
      <string>YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg=</string>
    </array>
    <key>TSKEnforcePinning</key><false/>  <!-- 灰度期只上报 -->
  </dict></dict>
</dict>

第 7 步:灰度发布。先放量 5%,盯两类错误率:Android 侧 javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure!(OkHttp 会在异常里直接打印服务端链与已配置 pin 的对比),iOS 侧 NSURLErrorDomain Code=-1202。24 小时内低于 0.5% 再升到 50%、100%;同时保留远程配置回滚开关(关闭 enforce / 下发降级 pin 列表),避免只能靠发版救火。

Android 证书锁定配置示例:NSC 与 OkHttp 4.12.0 双保险

为什么 Android 端建议用“NSC + OkHttp”双保险,而不是二选一?因为两条链路覆盖的版本区间不同:系统级 Network Security Configuration(NSC)从 Android 7.0(API 24)才开始生效,minSdk 若低于 24,老设备上 android:networkSecurityConfig 属性会被静默忽略——应用照常联网,但完全没有锁定。OkHttp 的 CertificatePinner 走应用层,从 OkHttp 4.12.0(最低 Android 5.0 / API 21)起可用,正好补上这个缺口。据 Android 官方 NSC 文档,<pin-set> 中的 <pin> 内容必须是公钥 SPKI 的 SHA-256 摘要再做 Base64,不能带 sha256/ 前缀;而 OkHttp 的 CertificatePinner 恰恰要求 sha256/ 前缀——这是最常见的踩坑点。

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <!-- 生产配置:禁止明文;对 api.example.com 强制公钥锁定 -->
    <domain-config cleartextTrafficPermitted="false">
        <domain includeSubdomains="true">api.example.com</domain>
        <!-- expiration 到期后该 pin-set 被系统忽略(软失败,回退系统 CA) -->
        <pin-set expiration="2026-06-30">
            <!-- 当前叶子/中间 CA 公钥的 SPKI SHA-256,标准 Base64,带 = 填充 -->
            <pin digest="SHA-256">AAAA...=</pin>
            <!-- 备用 pin:轮换或 CA 换签时的救命稻草,必须存在 -->
            <pin digest="SHA-256">BBBB...=</pin>
        </pin-set>
    </domain-config>
</network-security-config>

在 AndroidManifest.xml 的 <application> 上挂载:android:networkSecurityConfig="@xml/network_security_config"。pin 值可用 OpenSSL 直接从线上证书算出来(据 OpenSSL 文档,x509 -pubkey 输出的是 SubjectPublicKeyInfo):

# 取出 api.example.com 的 SPKI → SHA-256 → Base64
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
# 输出示例:5r4B...9k= (NSC 直接用;OkHttp 需写成 sha256/5r4B...9k=)
维度 NSC(network_security_config.xml) OkHttp 4.12.0 CertificatePinner
生效版本 Android 7.0(API 24)及以上 API 21+(OkHttp 4.x 最低要求)
pin 写法 纯 Base64,无 sha256/ 必须 sha256/ 前缀
子域匹配 includeSubdomains="true" *.example.com,仅匹配一级子域
格式写错的后果 配置解析抛 XmlPullParserException: ... Invalid pin digest.,通常启动即崩 运行时抛 SSLPeerUnverifiedException: Certificate pinning failure!
到期行为 expiration 到期后忽略该 pin-set,软失败 无到期概念,需自行删改代码
// app/build.gradle.kts: implementation("com.squareup.okhttp3:okhttp:4.12.0")
val pinner = CertificatePinner.Builder()
    .add(
        "api.example.com",
        "sha256/AAAA...=",   // 与 NSC 中同一个 SPKI 摘要,但必须加 sha256/ 前缀
        "sha256/BBBB...="    // 备用 pin,缺了它轮换时就是全线断网
    )
    .build()

val client = OkHttpClient.Builder()
    .certificatePinner(pinner)
    .build()

expiration 到期会发生什么?按 AOSP 的实现,到期后系统忽略该 <pin-set> 并回退到系统 CA 校验——这是软失败,不会报错,也就意味着锁定被悄悄解除。该行为在 Android 8.0(API 26)及以上更明确,低版本不要依赖它。所以到期前 30 天必须有告警,最省事的做法是在 CI 里卡住:

# CI 校验:剩余不足 30 天直接让流水线失败
EXP=$(grep -oP 'pin-set expiration="K[0-9-]+' app/src/main/res/xml/network_security_config.xml)
[ "$(date -d "$EXP" +%s)" -gt "$(date -d '+30 days' +%s)" ] 
  || { echo "pin-set 将在 30 天内过期: $EXP"; exit 1; }

怎么确认锁定真的生效?先装 Debug 包,观察正常握手:

adb logcat -s OkHttp:D | grep -iE 'CertificatePinner|SSLPeerUnverified'
# 正常情况:无任何 pin 相关输出
# 反向验证:临时把 pin 改成错误值,应看到
# javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure!
#   Peer certificate chain: [...]  Pinned certificates for api.example.com: sha256/...

负向验证不可省略:只有亲眼看到一次失败,才能证明告警链路和 pin 配置都活着。最后是红线——<debug-overrides> 只在 android:debuggable="true" 的测试包上生效,release 包的 base-config 里绝不能出现 <certificates src="user"/>,也不要为了“方便抓包”在 release 变体开 debuggable,那等于把 ssl pinning 证书锁定的意义整体交出去。

iOS 证书锁定配置示例:TrustKit 3.0.0 与原生 URLSession

TrustKit 3.0.0 的 Info.plist 该怎么写?TrustKit 走的是”配置即代码”路线:在 Info.plist 里声明 TSKConfiguration 字典,打开 swizzling 后它会在 NSURLSession 和 NSURLConnection 的认证回调中注入 pin 校验。据 TrustKit 官方 README,kTSKSwizzleNetworkDelegates 默认为 NO,不打开等于配置不生效——这是接入时最容易踩的坑。

<key>TSKConfiguration</key>
<dict>
  <key>kTSKSwizzleNetworkDelegates</key>
  <true/>                                    <!-- 默认 NO,必须显式开启 -->
  <key>kTSKReportUris</key>
  <array>
    <string>https://report.example.com/pin</string>  <!-- 不配则用 TrustKit 默认上报端点 -->
  </array>
  <key>kTSKPinnedDomains</key>
  <dict>
    <key>api.example.com</key>
    <dict>
      <key>kTSKIncludeSubdomains</key> <true/>
      <key>kTSKEnforcePinning</key>    <false/>  <!-- 灰度期:只上报不阻断 -->
      <key>kTSKExpirationDate</key>    <string>2026-06-30</string>
      <key>kTSKPublicKeyHashes</key>
      <array>
        <string>AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</string> <!-- 当前叶子证书 SPKI,固定 44 字符 -->
        <string>BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=</string> <!-- 备用链/交叉签名 -->
        <string>CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=</string> <!-- 下一张待轮换证书,提前埋点 -->
      </array>
    </dict>
  </dict>
</dict>

不用 TrustKit,原生 URLSession 怎么算 SPKI 哈希?iOS 15 及以上仍以 URLSessionDelegate 为主,关键是别对 SecKeyCopyExternalRepresentation 的原始字节直接做 SHA-256——它返回的是 PKCS#1(RSA)或 X9.63(EC)裸公钥,缺少 SubjectPublicKeyInfo 头,算出来的值与 OpenSSL 的 -pubkey 输出永远对不上。必须先拼接 SPKI DER 头。

import CryptoKit

func urlSession(_ s: URLSession, didReceive challenge: URLAuthenticationChallenge,
                completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
    guard challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust,
          let trust = challenge.protectionSpace.serverTrust else {
        return completionHandler(.performDefaultHandling, nil)
    }
    var err: CFError?
    guard SecTrustEvaluateWithError(trust, &err) else {        // 先做系统链验证
        return completionHandler(.cancelAuthenticationChallenge, nil)
    }
    guard let chain = SecTrustCopyCertificateChain(trust) as? [SecCertificate],  // iOS 15+;14 用 SecTrustGetCertificateAtIndex
          let leaf = chain.first,
          let hash = Self.spkiSHA256Base64(leaf),
          Self.pinnedHashes.contains(hash) else {
        return completionHandler(.cancelAuthenticationChallenge, nil)   // 触发 -1202
    }
    completionHandler(.useCredential, URLCredential(trust: trust))
}

static func spkiSHA256Base64(_ cert: SecCertificate) -> String? {
    guard let key = SecCertificateCopyKey(cert),
          let raw = SecKeyCopyExternalRepresentation(key, nil) as Data? else { return nil }
    let size = SecKeyGetBlockSize(key)
    let header: [UInt8]
    switch (SecKeyCopyAttributes(key) as? [CFString: Any])?[kSecAttrKeyType] as? String {
    case kSecAttrKeyTypeRSA as String where size == 256:          // RSA-2048
        header = [0x30,0x82,0x01,0x22,0x30,0x0d,0x06,0x09,0x2a,0x86,0x48,0x86,0xf7,0x0d,
                  0x01,0x01,0x01,0x05,0x00,0x03,0x82,0x01,0x0f,0x00]
    case kSecAttrKeyTypeECSECPrimeRandom as String where size == 32:  // P-256
        header = [0x30,0x59,0x30,0x13,0x06,0x07,0x2a,0x86,0x48,0xce,0x3d,0x02,0x01,
                  0x06,0x08,0x2a,0x86,0x48,0xce,0x3d,0x03,0x01,0x07,0x03,0x42,0x00]
    default: return nil
    }
    return Data(SHA256.hash(data: Data(header) + raw)).base64EncodedString()
}

报错 NSURLErrorDomain Code=-1202 怎么定位?该错误文本为 “The certificate for this server is invalid.”,在 pin 场景下几乎只有三种成因:哈希不匹配、base64 串里混入换行/空格(长度不再是 44)、设备时间偏差超过 5 分钟导致链验证先失败。用 Console.app 过滤 TrustKit,出现 Pin verification failed for domain api.example.com 时先数哈希长度。可用 OpenSSL 独立复算对照:

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
# 输出 44 字符 base64,与 kTSKPublicKeyHashes 逐字节比对(注意 = 补位)
维度 TrustKit 3.0.0 原生 URLSession
接入方式 Info.plist + swizzling,零业务代码 手写 delegate,需接管所有 Session
灰度与上报 kTSKEnforcePinning=NO 只上报;kTSKReportUris 直连服务端 需自行埋点上报
公钥哈希计算 库内完成 SPKI 封装 需手动拼 DER 头(见上例)
多域名/子域 kTSKPinnedDomains + kTSKIncludeSubdomains 按 host 自行分支
可控性 依赖第三方,swizzling 与部分网络库冲突 完全可控,便于加 kTSKExpirationDate 类兜底

据 TrustKit 文档建议,kTSKEnforcePinning=NO 应先观察 1–2 个版本:灰度期把 pin 失败事件按域名聚合,确认失败率低于 0.1% 且无系统性偏差后再切 YES。调试阶段可在 Xcode 15 的 Scheme → Run → Arguments 中加入 -com.apple.network 1 打开 CFNetwork 日志;生产环境把 -1202 与 TrustKit 失败事件接入 Sentry 或 Firebase Crashlytics 并单独设告警,避免与普通网络超时混在一起被淹没。

证书锁定方案对比:NSC、OkHttp、TrustKit、HPKP 怎么选?

“NSC、OkHttp、TrustKit、HPKP,到底该用哪个?”先看结论:移动端没有“唯一正确答案”,只有“覆盖范围 × 轮换成本”的权衡。下表把五条主流路径放在一起对比,其中版本号与生效条件可直接作为验收依据。

方案 版本/生效条件 配置位置 pin 对象 备份 pin 过期控制 适用场景
Android NSC Android 7.0(API 24)+ network_security_config.xml SPKI SHA-256 支持多 pin pin-set expiration Android 原生网络栈
OkHttp CertificatePinner OkHttp 4.12.0 Kotlin/Java 代码 SPKI SHA-256 支持多 pin 无内置过期,需代码控制 Android/Java 服务端客户端
TrustKit Android 1.1.0 / iOS 3.0.0 Info.plist 或代码 SPKI SHA-256 支持多 pin 配置版本控制 iOS 快速接入
iOS 原生 URLSession iOS 12+ URLSessionDelegate SPKI SHA-256 自行实现 自行实现 需要精细控制
HPKP RFC 7469,Chrome 72 已移除 HTTP 响应头 SPKI SHA-256 支持 max-age 不建议新项目

pin 叶子证书、中间 CA 还是根 CA?安全性排序是:叶子公钥锁定 > 中间 CA 公钥锁定 > 根 CA 公钥锁定;运维成本排序正好相反。原因是根 CA 一旦被 pin,任何共用该根的其他站点被误签发都会放大风险面,而叶子证书每 90 天(Let’s Encrypt 默认有效期)就换一次。据 Let’s Encrypt 文档,其证书有效期为 90 天且支持 ACME 自动续期,因此金融类 App 若坚持 pin 叶子,就必须接受“每 90 天发一次版”的节奏;一般业务建议以中间 CA 为主 pin、根 CA 作备份 pin。

Android 端最稳的做法是 NSC + OkHttp 双保险:NSC 覆盖 WebView 与系统网络栈,OkHttp 覆盖应用层请求。两处 pin 值必须来自同一次 openssl 计算,否则会出现“一个通道通、另一个通道报错”的割裂现象。

# 计算目标域名的 SPKI SHA-256 pin(OpenSSL 1.1.1 / 3.x 通用)
# 若为 OpenSSL 1.0.2,把 pkey 换成 rsa
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
# 输出示例:aBcD...9xY=  → 即为 sha256/ 前缀后的字符串
<!-- res/xml/network_security_config.xml:expiration 到期后 pin 校验自动失效,避免过期锁死 -->
<network-security-config>
  <domain-config>
    <domain includeSubdomains="true">api.example.com</domain>
    <pin-set expiration="2026-06-30">
      <pin digest="SHA-256">aBcD...9xY=</pin>      <!-- 主 pin:中间 CA -->
      <pin digest="SHA-256">QwEr...7zX=</pin>      <!-- 备份 pin:根 CA -->
    </pin-set>
  </domain-config>
</network-security-config>
// OkHttp 4.12.0:无内置过期机制,需随发版更新 pin 列表
val pinner = CertificatePinner.Builder()
    .add("api.example.com", "sha256/aBcD...9xY=")   // 主 pin
    .add("api.example.com", "sha256/QwEr...7zX=")   // 备份 pin,缺一不可
    .build()

Web 端还要不要上 HPKP?不要。据 RFC 7469 与 Chrome 官方公告,HPKP 已在 Chrome 72 中移除,误配置会导致站点长期无法访问。需要监控证书误签发时,改用 CAA 记录(RFC 8659)限制可签发 CA,并用 CT 日志告警替代。iOS 侧若项目已引入 TrustKit,直接升到 3.0.0 可省掉自研 URLSessionDelegate 的校验代码,报错信息会以 kTSKAlgorithmPinValidationFailed 形式出现在日志中;Android 侧 pin 不匹配则抛 javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure,两者都值得写进排查手册。

成本怎么估?证书本身:Let’s Encrypt 0 元/年;商业 DV 约 50–500 元/年;OV 约 1000–3000 元/年;EV 约 3000–10000 元/年。ssl pinning 证书锁定不改变证书价格,真正增加的是发版与监控人力成本,这也是“pin 中间 CA”通常更划算的原因。

上线前最后一道关:把轮换演练纳入验收——每季度在预发环境替换一次证书,用上面的 openssl 命令核对新证书 pin 是否命中备份 pin,再跑一遍真机请求。没有演练过的 ssl pinning 证书锁定配置,不能视为可上线。

证书锁定常见报错与排查:从 SSLPeerUnverifiedException 到 -1202

为什么浏览器打开正常,App 却直接抛异常?因为浏览器只验证「证书链能否追到受信根」,而 ssl pinning 证书锁定比对的是链上某张证书公钥的 SPKI SHA-256 指纹——这是两条独立的判定路径。据 OkHttp 官方文档,CertificatePinner 默认对整条链逐张比对,任一配置的 pin 命中即通过;一条都不命中才抛异常。搞清这一点,绝大多数报错都能在 5 分钟内定位。

Q:OkHttp 报 javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure! Peer certificate chain: [api.example.com, R10, ISRG Root X1] 怎么办?

这是「pin 不在当前链上」,不是证书无效。注意异常里打印的链是 服务端下发的原始链,你配的 pin 必须与其中某一张的公钥指纹逐字符一致。用 OpenSSL 重新算:

# 1) 抓取完整链(-servername 传 SNI,否则可能拿到默认站点证书)
openssl s_client -connect api.example.com:443 -servername api.example.com 
  -showcerts </dev/null 2>/dev/null 
  | awk '/BEGIN CERTIFICATE/,/END CERTIFICATE/' > chain.pem

# 2) 拆成单张证书(cert1.pem = 叶证书,依次向上)
awk 'BEGIN{n=0} /BEGIN CERT/{n++} {print > "cert" n ".pem"}' chain.pem

# 3) 逐张输出 SPKI SHA-256 base64 —— 直接粘进 CertificatePinner
#    OkHttp 要求格式为 "sha256/<base64>",末尾的 = 不能删
for f in cert*.pem; do
  echo "$f: sha256/$(openssl x509 -in "$f" -pubkey -noout 
    | openssl pkey -pubin -outform der 
    | openssl dgst -sha256 -binary | openssl enc -base64)"
done

Q:Android 报 CertPathValidatorException: Trust anchor for certification path not found,是 pin 配错了吗?不是。这属于信任链问题,与 pin 无关:系统找不到可信锚点。两个高频原因——服务端漏发中间证书(只发叶证书),以及 Android 7.0(API 24)以下根本不读取 Network Security Config,<pin-set> 与 <debug-overrides> 全部静默失效。后者是灰度期最容易踩的坑,务必确认 minSdkVersion。

Q:iOS 报 NSURLErrorDomain Code=-1202 "The certificate for this server is invalid."?按此顺序查:① kTSKPublicKeyHashes 数组里是否有拼写错、少一个 =、或从终端复制时带入了换行;② 服务端是否缺中间证书;③ 设备时间偏差是否超过 5 分钟(Apple 在 NSURLError.h 中对 -1202 的定义即证书校验失败,时间偏差会直接触发)。

Q:TrustKit 输出 TrustKit: Pin verification failed for domain api.example.com?先确认 kTSKPublicKeyHashes 同时包含当前公钥与备份公钥(TrustKit 文档要求至少 1 个,工程实践建议 2 个)。灰度期把 kTSKEnforcePinning 设为 NO,只上报不拦截,观察 pinVerificationFailed 回调统计后再切 YES。

报错原文 触发层 首要排查动作
Certificate pinning failure! 应用层 pin 比对 openssl 重算链上每张 SPKI base64
Trust anchor for certification path not found 系统信任链 补全中间证书 / 确认 API ≥ 24
Code=-1202 iOS 证书校验 pin 字符串完整性 + 设备时间
Pin verification failed (TrustKit) TrustKit 策略 备份 pin 是否存在、enforce 开关

Q:开了 Charles / Fiddler 的 SSL Proxying 还是 pin 失败?正常现象——pin 校验发生在代理替换证书之后,代理注入的自签证书公钥与你的 pin 必然不匹配。Debug 包可临时在 NSC 中加 <debug-overrides>(仅在 android:debuggable="true" 时生效,Release 自动忽略),但绝不能把关闭 pin 的代码路径发到生产。据 RFC 7469 的设计初衷,锁定的价值正来自「CA 被攻破或误签发时仍能拦截」。

Q:服务端自己就有问题怎么发现?执行 openssl s_client -connect api.example.com:443 -servername api.example.com,若输出 Verify return code: 20 (unable to get local issuer certificate),说明链不完整,客户端必然失败——先补中间证书,再谈 pin 排查,顺序反了会白查半天。

如何验证 SSL Pinning 证书锁定已生效?

验证 SSL Pinning 证书锁定是否真的生效,不能只看“App 还能正常请求”这一件事——那可能只是 pin 配置被静默忽略。可靠的验证需要三路并行:正向确认证书链可验证、哈希逐字符比对、负向注入确认失败路径存在,最后用日志和监控把结论固化下来。

第一步:正向验证。先用 OpenSSL 确认服务端返回的正是你要锁定的那张证书:

# -servername 必须显式指定,否则不发 SNI,CDN 可能返回默认站点证书,算出错误 pin
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null 
  | grep -E "Verify return code|subject="
# 期望输出(据 OpenSSL 1.1.1+ / 3.x 行为):
# subject=CN = api.example.com
# Verify return code: 0 (ok)

注意:Verify return code: 0 (ok) 只证明系统信任库能验证这条链,并不证明 pin 生效——这正是最常见的误判来源。真正的 pin 生效判据在客户端:抓包(Charles / mitmproxy)应看到 TLS 握手完成且业务请求返回 200;若你在设备上装了用户 CA 并开启代理,请求应该直接失败,因为代理证书的 SPKI 不在 pin 集合里。这个“失败”本身就是正向证据。

第二步:SPKI 哈希比对。SSL Pinning 锁的是 SubjectPublicKeyInfo 的 SHA-256,不是整张证书的指纹(后者换证就失效,前者只要密钥不变就持续有效,据 RFC 7469 与 OkHttp 文档):

# 计算当前线上证书公钥的 SHA-256,输出为 44 字符 base64(32 字节 + 1 个 '=' 填充)
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
# 示例:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=

把输出与 Android res/xml/network_security_config.xml 里的 <pin digest="SHA-256">、iOS TrustKit 的 kTSKPublicKeyHashes 数组逐字符比对。要锁定中间 CA 时,改用 openssl s_client -showcerts 取出链上每一张证书分别计算。

验证方向 Android 观测点 iOS 观测点 通过判据
正向链验证 openssl s_client + 抓包 同左(macOS 自带 LibreSSL 亦可) Verify return code: 0 (ok),业务请求 200
哈希比对 network_security_config.xml kTSKPublicKeyHashes 44 字符 base64 完全一致
负向注入 SSLPeerUnverifiedException NSURLErrorDomain Code=-1202 Debug 包必失败,改回后必成功
日志与监控 adb logcat -s OkHttp:D TrustKit:D Console.app 过滤 TrustKit pin 失败率 < 0.5%(灰度 24h)

第三步:负向验证,这是唯一能证明“校验路径真实生效”的手段。把某个 pin 的最后一个字符故意改错,安装 Debug 包:

# OkHttp 4.x 默认不启用 pinning,必须显式 CertificatePinner.Builder().add(...);未配置即不锁定
adb install -r app-debug.apk
adb logcat -s OkHttp:D TrustKit:D | grep -iE "CertificatePinner|pin"
# 期望:javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure!
#       Peer certificate chain: ...
# iOS 侧 TrustKit 默认 kTSKEnforcePinning = YES,失败日志形如:
# NSURLErrorDomain Code=-1202 "The certificate for this server is invalid."

改回正确哈希、重新安装并确认请求成功,才算闭环。据 Android 官方文档,<pin-set expiration> 到期后 pin 校验会被静默跳过(软失败),这是生产事故的高发点,因此必须给 pin-set 过期时间和证书到期日各设 30 天前的提醒。

第四步:轮换演练与监控闭环。在预发环境把服务端证书切换到由备用中间 CA 签发的证书,验证 backup pin 生效,记录从切换完成到全部客户端恢复的时间,建议每季度演练一次。接入 Sentry / Bugly 后,为 SSLPeerUnverifiedException 与 NSURLErrorDomain Code=-1202 建独立告警项,灰度期 pin 失败率阈值设为 0.5% 并持续观察 24 小时——超过阈值说明有存量客户端未升级到含新 pin 的版本,应立即回滚而不是硬扛。

普通 HTTPS 证书是服务端向 CA 申请的身份凭证,客户端默认信任系统根证书库;SSL Pinning 证书锁定是客户端额外把指定公钥哈希写死,只信任该公钥。前者解决加密与身份认证,后者解决 CA 被滥用或中间人代理问题。据 RFC 5280,证书链验证仍要执行,pinning 是叠加校验。

移动端优先 pin 中间 CA 公钥并配置备份 pin,因为 Let's Encrypt 90 天续期会更换叶子密钥,pin 叶子会导致每 90 天发版。若安全要求高,可 pin 叶子公钥并配合密钥复用与自动化发版,但要接受应用商店审核 1-3 天的窗口风险。

Android 8.0(API 26)起,pin-set 的 expiration 到期后系统会忽略该 pin-set,回退到系统 CA 验证,属于软失败,不会直接断网,但等于关闭了证书锁定。必须在到期前 30 天更新配置,并给 expiration 日期设置告警。

可能是。先检查 kTSKPublicKeyHashes 是否包含当前链上公钥的 base64,确认没有换行和空格;再检查设备时间偏差是否超过 5 分钟;最后用 openssl s_client 确认服务端是否漏发中间证书。若使用 TrustKit,在 Console.app 中搜索 Pin verification failed 可进一步定位。

不是。HPKP 是 HTTP 响应头 Public-Key-Pins,由 RFC 7469 定义,在浏览器端生效,Chrome 72(2019 年 1 月)已移除支持。SSL Pinning 是客户端 App 或网络库内置的校验。Web 端现在更推荐 CAA 记录限制 CA,并用 Certificate Transparency 日志做误签发监控。

证书锁定校验的是服务端公钥哈希,Charles 作为中间人替换了证书链,公钥不匹配就会抛 SSLPeerUnverifiedException 或 -1202。Debug 包可临时把 Charles CA 加入 debug-overrides 或关闭 pin,Release 包必须保留锁定;不要把关闭 pin 的代码发到生产。

至少 2 个,推荐 3 个:当前中间 CA 公钥、备用中间 CA 公钥、根 CA 公钥;Android NSC 建议不超过 4 个。每个 pin 都要记录来源证书、到期时间和负责人,备份 pin 必须来自真实可用的证书链,不能填入未知哈希。


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

内容审核

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