iOS ATS 与 SSL 证书部署实战:nscurl 诊断、TLS 1.2 合规与 398 天有效期
很多团队把 App 的 HTTPS 问题归咎于“证书没买对”,但真正拦住请求的往往不是证书本身,而是 iOS 的 App Transport Security(ATS)策略。本文从根因讲起,给出可直接执行的诊断命令、证书签发流程、服务端与 Info.plist 配置示例,以及真实报错对照表。
一、问题背景与根因:为什么装了证书仍然被 ATS 拦截
ATS 是苹果在 iOS 9 引入、并从 2017 年 1 月 1 日起在 App Store 审核中强制要求默认开启的网络传输安全策略。它的本质是客户端侧的强制校验:只要 App 通过 URL Loading System(NSURLSession、NSURLConnection 及基于其上的第三方库)发起请求,系统就会在握手阶段检查协议版本、密码套件、证书签名算法、密钥长度、有效期和证书链完整性,任何一项不达标直接中断连接。
常见的三个错误码必须区分清楚,否则会排查方向跑偏:
- NSURLErrorDomain Code=-1022:请求 URL 使用了
http://,或被 ATS 策略拒绝(The resource could not be loaded because the App Transport Security policy requires the use of a secure connection)。 - NSURLErrorDomain Code=-1200:TLS 握手失败,通常是服务端不支持 TLS 1.2 或没有双方都支持的 ECDHE 套件(An SSL error has occurred and a secure connection to the server cannot be made)。
- NSURLErrorDomain Code=-1202:证书本身不被信任——缺中间证书、域名不在 SAN 中、有效期超限、根证书不在 iOS 信任库。
根因可以分三层:协议层(仍开着 TLS 1.0/1.1、只提供 RSA 密钥交换套件)、证书层(自签名、只部署 leaf 证书、CN-only 无 SAN、有效期超过 398 天)、配置层(Info.plist 例外域名写错、CDN 回源降级到 HTTP)。另外要注意两个常见误解:一是 ATS 只作用于 URL Loading System,裸 socket 和部分 WKWebView 网页内容不受约束,但 App 内的 API 请求几乎都走 NSURLSession;二是 ATS 不区分 DV、OV、EV 证书,只校验技术属性,所以免费 DV 证书同样可以满足要求。
二、ATS 的硬性门槛:证书与 TLS 参数清单
下面这张表是 iOS 端校验的实际条件,逐项核对即可定位问题,不需要猜测:
| 检查项 | ATS 要求 | 检测方式 | 不满足时的表现 |
|---|---|---|---|
| TLS 版本 | ≥ TLS 1.2(TLS 1.3 更佳,但非强制) | openssl s_client -tls1_2 |
-1200 握手失败 |
| 密码套件 | 必须支持前向保密(ECDHE 或 TLS 1.3 的 TLS_AES_*) | nmap --script ssl-enum-ciphers |
-1200,openssl 报 handshake failure |
| 签名算法 | SHA-256 及以上,SHA-1 已被拒绝 | openssl x509 -text 看 Signature Algorithm |
-1202 证书不受信 |
| 密钥长度 | RSA ≥ 2048 位,ECC ≥ 256 位 | openssl x509 -noout -text | grep Public-Key |
-1200 / -1202 |
| 有效期 | ≤ 398 天(2020-09-01 之后签发的证书) | openssl x509 -noout -dates |
-1202 |
| 域名匹配 | 必须有 SAN 扩展且包含请求域名,通配符只匹配一级 | openssl x509 -noout -ext subjectAltName |
-1202 |
| 证书链 | 必须下发中间证书,根证书需在 iOS 信任库 | openssl s_client -showcerts 看链长度 |
-1202,verify error num=20 |
三个高频踩坑点值得单独强调。第一,398 天规则是硬上限,苹果自 2020 年 9 月 1 日起拒绝有效期更长的 TLS 服务端证书,续签时必须核对 notAfter - notBefore。第二,Let’s Encrypt 默认有效期 90 天(2025 年起还提供 6 天有效期的短周期证书选项),必须配置自动续期,否则每季度固定故障一次。第三,现代 iOS 只认 SAN,不认 CN,即使 Common Name 完全正确,缺少 subjectAltName 一样报 -1202。
三、实操第一步:用 nscurl 与 openssl 诊断服务端
macOS 自带的 nscurl 是最贴近 ATS 真实行为的工具,它会按不同 TLS 版本与密码套件组合逐项尝试,输出 PASS/FAIL:
# 逐项诊断,输出每条组合的结果
nscurl --ats-diagnostics --verbose https://api.example.com
# 只验证 ATS 默认策略能否通过
nscurl --ats-diagnostics --ats-tls-version TLSv1.2 https://api.example.com
如果所有条目都是 PASS,说明服务端在协议层已经合规,问题多半在 App 侧配置或域名不匹配。接着用 openssl 做协议层精查:
openssl s_client -connect api.example.com:443
-servername api.example.com -tls1_2 -showcerts < /dev/null
重点看三行输出:Protocol : TLSv1.2、Cipher : ECDHE-RSA-AES256-GCM-SHA384、Verify return code: 0 (ok)。若出现 verify error:num=20:unable to get local issuer certificate,说明服务端只发了 leaf 证书、没发中间证书,这是 iOS 报 -1202 最常见的原因。若出现 no protocols available 或 sslv3 alert handshake failure,说明服务端不支持 TLS 1.2 或没有共同套件。
# 枚举服务端实际开启的协议与套件
nmap --script ssl-enum-ciphers -p 443 api.example.com
# 用 testssl.sh 做完整评级(含 398 天有效期、链完整性检查)
testssl.sh --severity HIGH https://api.example.com
# 模拟客户端仅用 TLS 1.2 请求
curl -vI --tlsv1.2 --tls-max 1.2 https://api.example.com
诊断顺序建议固定为:nscurl 定性 → openssl 看协议与链 → nmap/testssl 看套件与合规项 → curl 复现。这样能在十分钟内把问题锁定在“协议层、证书层、配置层”中的某一层,避免反复重签证书。
四、实操第二步:签发并部署符合 ATS 的证书
先生成带 SAN 的 CSR,注意 -sha256 与 -addext 必须显式指定,否则部分 CA 会按老模板签发无 SAN 证书:
openssl req -new -newkey rsa:2048 -sha256 -nodes
-keyout api.key -out api.csr
-subj '/C=CN/ST=Shanghai/L=Shanghai/O=Example Ltd/CN=api.example.com'
-addext 'subjectAltName=DNS:api.example.com,DNS:www.example.com'
# 核对 CSR 中的 SAN 是否正确
openssl req -in api.csr -noout -text | grep -A2 'Subject Alternative Name'
如果使用 Let’s Encrypt,一条命令即可完成签发与部署,并挂上 reload 钩子:
certbot --nginx -d api.example.com -d www.example.com
--deploy-hook 'systemctl reload nginx'
# 确认自动续期任务存在(有效期仅 90 天,必须自动化)
systemctl list-timers | grep certbot
certbot renew --dry-run
部署环节有一个决定性细节:必须部署 fullchain(leaf + 中间证书),而不是单独的 cert。很多证书包解压后 cert.pem 只有服务器证书,直接配上就会在 iOS 上报 -1202,而在桌面浏览器上却正常(因为浏览器会自行补链)。部署后立即核对有效期与 SAN:
openssl x509 -in fullchain.pem -noout -dates -subject -issuer
openssl x509 -in fullchain.pem -noout -ext subjectAltName
# 计算剩余天数,确认不超过 398 天上限
openssl x509 -in fullchain.pem -noout -enddate
五、配置示例:nginx、Apache 与 Info.plist
nginx 侧的关键是关掉老旧协议、只保留 ECDHE 套件、并把证书链配全:
server {
listen 443 ssl;
http2 on; # nginx 1.25.1+;旧版写 listen 443 ssl http2;
server_name api.example.com;
ssl_certificate /etc/ssl/fullchain.pem; # 必须含中间证书
ssl_certificate_key /etc/ssl/api.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off; # TLS 1.3 由客户端决定顺序
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/ssl/chain.pem;
add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always;
}
Apache 对应配置:
SSLProtocol -all +TLSv1.2 +TLSv1.3
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
SSLHonorCipherOrder off
SSLCertificateFile /etc/ssl/fullchain.pem
SSLCertificateKeyFile /etc/ssl/api.key
如果确有历史域名无法升级(例如合作方只支持 TLS 1.0),只能在 Info.plist 中做最小化例外,禁止全局放开:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>legacy.example.com</key>
<dict>
<key>NSExceptionMinimumTLSVersion</key>
<string>TLSv1.0</string>
<key>NSIncludesSubdomains</key>
<true/>
<key>NSExceptionRequiresForwardSecrecy</key>
<false/>
</dict>
</dict>
</dict>
注意 NSExceptionDomains 的键必须是域名,不支持 IP 地址;写 IP 不会报错,但也不会生效。若只做本地调试,用 NSAllowsLocalNetworking 而不是 NSAllowsArbitraryLoads,后者在审核时需要逐条说明理由。
六、方案对比:证书类型与 ATS 例外策略
先看证书选型,结论是 ATS 只看技术属性,不看证书等级:
| 类型 | 有效期 | ATS 是否满足 | 适用场景 | 主要成本 |
|---|---|---|---|---|
| Let’s Encrypt DV | 90 天(可选 6 天) | 满足(需自动化续期) | API、内部服务、绝大多数 App 后端 | 必须配 cron/timer |
| 商业 DV | ≤ 398 天 | 满足 | 不想维护续期脚本的团队 | 年费 |
| OV / EV | ≤ 398 天 | 满足 | 对外官网、支付类业务 | 需组织验证,签发慢 |
| 自签名 | 自定义 | 不满足 | 仅本地联调 | 需在 App 内做证书固定 |
再看 ATS 例外策略的取舍:
| 策略 | 作用范围 | 审核影响 | 推荐度 |
|---|---|---|---|
| 默认(不写任何键) | 全局强制 ATS | 无 | 首选 |
| NSExceptionDomains | 仅指定域名 | 需简要说明 | 临时过渡可用 |
| NSAllowsLocalNetworking | 仅本地/内网地址 | 基本无影响 | 调试期推荐 |
| NSAllowsArbitraryLoads | 全局放开 | 需逐条举证,易被追问 | 不推荐 |
实践建议:优先把服务端升级到 TLS 1.2 + ECDHE,把例外配置彻底删掉。例外配置的维护成本远高于一次升级——它会掩盖问题,导致新接入的域名在真机上偶发失败而难以复现。
七、常见错误排查:真实报错与修复动作
下面这些报错在工单里出现频率最高,按表对照即可:
| 报错信息 | 根因 | 修复动作 |
|---|---|---|
-1022 The resource could not be loaded because the App Transport Security policy requires the use of a secure connection |
URL 写成 http://,或域名命中例外规则 | 改为 https://,检查 Info.plist 是否有冲突键 |
-1200 An SSL error has occurred + openssl 报 sslv3 alert handshake failure |
服务端未开 TLS 1.2 或无共同 ECDHE 套件 | 调整 ssl_protocols / ssl_ciphers 后重载 |
-1202 + verify error:num=20:unable to get local issuer certificate |
只部署了 leaf 证书,缺中间证书 | 改为 fullchain.pem,用 -showcerts 确认链长度 ≥ 2 |
-1202,证书 CN 正确但校验失败 |
缺 SAN 或 SAN 不含该子域名 | 重新签发带 SAN 的证书,通配符只覆盖一级 |
-1202,浏览器访问正常 |
证书有效期超过 398 天,或使用了 SHA-1 签名 | 核对 openssl x509 -noout -dates 后重签 |
| 老设备(iOS 9/10)报证书不受信,新设备正常 | Let’s Encrypt 旧链 DST Root CA X3 过期导致的信任链问题 | 改用 ISRG Root X1 签发链,或升级最低支持版本 |
还有两个容易被忽略的坑。一是 NSIncludesSubdomains 未设为 true,导致 api.example.com 的例外对 v2.api.example.com 无效。二是 CDN 回源降级:边缘节点支持 TLS 1.3,但回源到源站时用了 HTTP,客户端握手成功却拿到错误内容,此时 nscurl 全 PASS,必须抓包或查 CDN 的回源协议配置。
八、效果验证:上线前的检查清单
改完后不要只看浏览器绿锁,按下面顺序逐项验证,全部通过再提审:
# 1. ATS 全组合诊断,应全部 PASS
nscurl --ats-diagnostics --verbose https://api.example.com
# 2. 协议与套件
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 < /dev/null | grep -E 'Protocol|Cipher|Verify'
# 3. 证书链完整性(应看到至少 2 段 BEGIN CERTIFICATE)
openssl s_client -connect api.example.com:443 -showcerts < /dev/null | grep -c 'BEGIN CERTIFICATE'
# 4. 有效期与 SAN
openssl x509 -in fullchain.pem -noout -dates -ext subjectAltName
# 5. 整体评级
testssl.sh --severity HIGH https://api.example.com
工程侧还要做三件事:其一,在真机上分别用当前最新 iOS 与最低支持版本各跑一遍主流程,模拟器不复现 ATS 差异;其二,提交前在 Xcode 中搜索 NSAllowsArbitraryLoads,确认没有遗留的全局放开配置;其三,把证书到期监控接入告警(例如用 openssl s_client 定时检查剩余天数,低于 21 天报警),尤其是 90 天有效期的证书,自动续期失败往往在半夜发生。最后建议在 CI 中加入一条 nscurl 冒烟测试,让协议配置回退在合并前就暴露出来。
常见问题
已经买了 SSL 证书,iOS 为什么还报 -1022?
-1022 是 ATS 策略拒绝,与证书无关。最常见原因是请求 URL 仍是 http://,或代码里存在硬编码的明文地址、第三方 SDK 内部使用了 HTTP。先全局搜索 http://,再用 nscurl --ats-diagnostics 确认域名本身能否通过 ATS。
ATS 要求必须支持 TLS 1.3 吗?
不要求。ATS 的底线是 TLS 1.2 加前向保密套件,TLS 1.3 只是更优选择(握手更快、套件更安全)。但要注意 TLS 1.2 必须提供 ECDHE 套件,只开 RSA 密钥交换的套件(如 AES128-SHA)依然会被判定不满足前向保密而失败。
证书有效期到底是多少天?
苹果要求 2020 年 9 月 1 日之后签发的 TLS 服务端证书有效期不超过 398 天,超限会被判定为不受信任。Let’s Encrypt 默认签发 90 天证书,2025 年起还提供 6 天有效期的短周期选项,两者都符合要求,但必须配置自动续期(certbot renew --dry-run 验证)。
能不能用 IP 地址访问并满足 ATS?
不能。ATS 的例外配置 NSExceptionDomains 只接受域名,写 IP 不生效;同时证书必须包含与请求主机名匹配的 SAN,而主流 CA 不再为公网 IP 签发证书。请改用域名加 DNS 解析。
免费证书和付费证书在 ATS 上有区别吗?
没有区别。ATS 只校验技术属性:TLS 版本、前向保密套件、签名算法、密钥长度、有效期、SAN 与证书链。免费 DV 证书只要满足这些条件就能通过。付费证书的差异体现在组织验证、保险赔付、技术支持与更长的可选有效期上。
保留 NSAllowsArbitraryLoads 会被拒审吗?
存在风险。苹果要求开发者在审核备注中逐条说明为什么必须放开 ATS,且不能仅以“历史遗留”为由。建议只对确需兼容的单一域名使用 NSExceptionDomains,并在服务端升级完成后立即删除例外配置。