iOS/macOS 报错“证书无效”全解:NSURLSession、ATS 与 TLS 配置实战
问题背景与根因
在 iOS/macOS 上,NSURLSession 默认走 ATS(App Transport Security)与系统信任库。报错通常长这样:NSURLErrorDomain Code=-1202,附带 The certificate for this server is invalid. You might be connecting to a server that is pretending to be ...。这不是“网络不通”,而是 TLS 握手后的证书校验失败。ATS 默认要求:TLS 1.2 及以上、签名算法 SHA-256 或更强、RSA 至少 2048 位或 ECC 256 位、支持前向保密套件、证书含 SAN、EKU 含 serverAuth、有效期不超过 398 天(2020-09-01 后签发的公开证书)。Let’s Encrypt 证书有效期 90 天,需自动续期。此外,iOS 13/macOS 10.15 起对服务器证书有效期执行 398 天上限,超期证书即使未到期也会被判定不合规。常见根因:证书过期;只部署了叶子证书,缺中间证书;仍用 SHA-1 或 TLS 1.0/1.1;CN 写对但没有 SAN;自签名未受信任;主机名不匹配;旧设备不信任新根。Safari 可能因缓存或用户手动继续而放行,但 NSURLSession 不允许用户绕过,所以 App 内必现。
三步定位:证书、链、ATS
先在同机用三条命令定位,不要直接改代码。第一条看证书链与有效期:
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null | openssl x509 -noout -subject -issuer -dates -ext subjectAltName
输出重点看 notAfter 是否已过、subjectAltName 是否包含域名。第二条看签名算法与密钥长度:
openssl s_client -connect example.com:443 -servername example.com /dev/null | openssl x509 -noout -text | grep -E 'Signature Algorithm|Public-Key|DNS:'
若出现 sha1WithRSAEncryption 或 Public-Key: (1024 bit),ATS 直接判失败。第三条验证链是否完整:
openssl s_client -connect example.com:443 -servername example.com -CAfile /etc/ssl/certs/ca-certificates.crt /dev/null | grep 'Verify return code'
返回 0 (ok) 才算链完整;返回 20 (unable to get local issuer certificate) 说明服务器没发中间证书。随后用 Apple 自带工具逐项测 ATS:
nscurl --ats-diagnostics https://example.com --verbose
它会分别测试默认 ATS、TLS 1.2、前向保密、SHA-256 等组合,哪一项 FAIL 就对应修哪项。最后用 curl -vI https://example.com 交叉确认,排除代理与本地 DNS 干扰。
服务端 Nginx 配置示例
服务端先保证协议与套件满足 ATS。Nginx 最小可用配置如下,注意 ssl_certificate 必须指向 fullchain,而不是单张叶子证书:
server {
listen 443 ssl http2;
server_name example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/chain.pem;
add_header Strict-Transport-Security 'max-age=31536000' always;
}
修改后先 nginx -t,再 systemctl reload nginx。若仍支持旧 Android 或 IoT,不要为了兼容回退 TLS 1.0/1.1;正确做法是让旧客户端升级,或为旧域名单独保留入口。Apache 对应指令为 SSLProtocol TLSv1.2 TLSv1.3 与 SSLCipherSuite,证书链同样用 SSLCertificateChainFile 或合并 fullchain。配置完成后必须用第 2 节命令复测,不能只看浏览器绿锁。
证书链与 398 天有效期修正
证书链顺序必须是“叶子证书 → 中间证书 → 根证书(可选)”。很多 -1202 不是证书买错,而是只上传了 cert.pem。检查 fullchain 内容:
openssl crl2pkcs7 -nocrl -certfile /etc/nginx/ssl/fullchain.pem | openssl pkcs7 -print_certs -noout
应看到至少两张证书,且第一张的 Subject 是域名,第二张的 Issuer 指向公共根。用以下命令验证:
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted /etc/nginx/ssl/chain.pem /etc/nginx/ssl/cert.pem
返回 OK 才合格;返回 error 20 at 0 depth lookup: unable to get local issuer certificate 就是缺中间证书。有效期方面,Apple 要求 2020-09-01 之后签发的 TLS 服务器证书有效期不超过 398 天;Let’s Encrypt 为 90 天,必须用 certbot renew --dry-run 验证自动续期。若旧设备不信任 Let’s Encrypt 新根,可在签发时指定链:
certbot renew --preferred-chain 'ISRG Root X1'
同时确认 SAN 与 EKU:openssl x509 -in cert.pem -noout -ext subjectAltName -ext extendedKeyUsage,输出应含 DNS:example.com 与 TLS Web Server Authentication。缺 SAN 的 CN-only 证书在 iOS 13+ 直接失败。
ATS 要求与旧配置对比表
把 ATS 校验项与常见旧配置对照,排查时逐行打勾:
| 校验项 | iOS/macOS ATS 要求 | 常见旧配置 | 修复动作 |
|---|---|---|---|
| TLS 版本 | TLS 1.2 / 1.3 | TLS 1.0、1.1、SSLv3 | Nginx 设置 ssl_protocols TLSv1.2 TLSv1.3; |
| 签名算法 | SHA-256 及以上 | SHA-1 | 重新签发 SHA-256 证书 |
| 密钥长度 | RSA ≥2048,ECC ≥256 | RSA 1024 | 换 2048/4096 位或 ECC P-256 |
| 主机名 | 必须含 SAN | 仅 CN | 重签含 subjectAltName |
| 证书链 | 完整到受信任根 | 只发叶子证书 | 部署 fullchain.pem |
| 有效期 | ≤398 天(公开证书) | 多年期证书 | 缩短周期并自动续期 |
| 套件 | 支持前向保密 | RSA key exchange | 启用 ECDHE 套件 |
再记一张报错映射表:-1202 证书不受信任,优先查链、有效期、SAN;-1200 安全连接失败,查 TLS 版本与套件;底层 SecureTransport 的 -9814 表示证书过期,-9813 表示找不到根/中间证书。若服务端仍开启 TLS 1.1,即使浏览器显示锁,nscurl 也会在 ATS Default Connection 一项 FAIL。把这两张表放在排障文档里,能避免“证书没问题”的口头争论。
Info.plist 豁免配置(慎用)
只有第三方服务短期无法修复时才考虑 ATS 豁免,且要按域名最小化。示例:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>legacy.example.com</key>
<dict>
<key>NSIncludesSubdomains</key>
<true/>
<key>NSExceptionMinimumTLSVersion</key>
<string>TLSv1.2</string>
<key>NSExceptionRequiresForwardSecrecy</key>
<false/>
<key>NSExceptionAllowsInsecureHTTPLoads</key>
<false/>
</dict>
</dict>
</dict>
注意:NSAllowsArbitraryLoads 只放宽 HTTP 明文与部分 ATS 算法限制,不能绕过证书信任失败。证书过期、自签名、链不完整仍会报 -1202。自签名场景应让用户安装并信任根证书(设置 → 通用 → 关于本机 → 证书信任设置),或使用 MDM 下发;企业内网可接受,公开 App 不建议。若必须在代码层处理,只能实现 URLSessionDelegate 的 urlSession(_:didReceive:completionHandler:) 做证书锁定,且要内置证书或公钥哈希,绝不能无条件 .useCredential。App Store 审核会要求说明豁免理由,能修服务端就不要写 Info.plist。
常见错误排查与真实报错
真实报错与处理动作要一一对应,下面这些在 Xcode 控制台和 Console.app 中很常见:
NSURLErrorDomain Code=-1202
The certificate for this server is invalid. You might be connecting to a server that is pretending to be example.com
处理:先跑 openssl s_client -showcerts,90% 是缺中间证书或证书过期。若 notAfter 已过,续期后重启服务;若链只有一张,补 fullchain。
NSURLErrorDomain Code=-1200
An SSL error has occurred and a secure connection to the server cannot be made.
处理:抓包看 ClientHello 与 ServerHello,确认是否只支持 TLS 1.0/1.1,或服务端套件全是 RSA key exchange。用 nmap --script ssl-enum-ciphers -p 443 example.com 列出套件。
curl: (60) SSL certificate problem: unable to get local issuer certificate
处理:与 -1202 同源,服务器未发送中间证书。执行 openssl verify -untrusted chain.pem cert.pem 会得到 error 20。
CFNetwork SSLHandshake failed (-9814)
处理:SecureTransport 明确报证书过期,检查系统时间与证书 notBefore/notAfter;若设备时间正确,立即续期。若 Xcode 只显示 The operation couldn’t be completed,展开 NSError.userInfo 的 NSUnderlyingError 才能看到 -9814。还有一种“假正常”:Safari 能打开是因为它允许用户点击继续,而 NSURLSession 没有该交互。不要用浏览器结果证明 App 可用,必须以 nscurl 的 PASS 为准。
效果验证与发布检查
修复后按“命令行 → 系统工具 → 真机”三层验证。第一层:
curl -sS -o /dev/null -w '%{http_code} %{ssl_verify_result}n' https://example.com
期望输出 200 0,ssl_verify_result 为 0 表示链验证通过。第二层:
nscurl --ats-diagnostics https://example.com
期望每一组都是 Result : PASS,尤其是 ATS Default Connection 与 TLS 1.2。若某项 FAIL,按第 5 节表格回查。第三层:
echo | openssl s_client -servername example.com -connect example.com:443 2>/dev/null | openssl x509 -noout -enddate -issuer
确认 notAfter 在 398 天窗口内、Issuer 是受信任 CA。真机验证时,用 Xcode 分别跑 iOS 15/16/17 与 macOS 13+,打开 URLSession.shared.dataTask 请求并打印 error;成功时 error == nil。再在弱网与代理环境下复测,避免 CDN 节点证书不一致。发布前建议把域名加入监控,证书到期前 30 天告警;最后把 nscurl 输出存档到发布检查单,后续换证书可直接对比。
常见问题
Safari 允许用户查看证书并手动继续,NSURLSession 默认执行 ATS 严格校验,不允许交互式绕过;同时 App 可能未命中系统缓存的中间证书,所以同一设备上结果不同。
能解决“证书太贵”但不能自动解决链问题。Let’s Encrypt 有效期 90 天,必须部署 fullchain 并自动续期;旧 iOS 还需注意根证书兼容,可用 –preferred-chain 指定 ISRG Root X1。
不能。该键只放宽 HTTP 明文和部分 ATS 算法限制,证书过期、自签名、链不完整仍由系统信任库校验,依然报 -1202。
从 notBefore 到 notAfter 的总天数不能超过 398 天,适用于 2020-09-01 后签发的公开信任 TLS 服务器证书;Let’s Encrypt 为 90 天,需用 certbot renew –dry-run 验证续期。
执行 openssl s_client -connect 域名:443 -servername 域名 -showcerts,若只返回一张证书,或 openssl verify 报 error 20 unable to get local issuer certificate,就是缺中间证书,部署 fullchain 即可。