苹果 ATS 要求怎么配?iOS HTTPS 的 TLS 1.2、前向保密与证书实操指南
苹果 ATS(App Transport Security)自 iOS 9 起默认要求:TLS 1.2 及以上、支持 ECDHE 前向保密的密码套件、SHA-256 及以上签名证书、RSA 2048 位或 ECC 256 位以上;不满足时 URLSession 请求会以 NSURLErrorDomain Code=-1022 失败。 最快自检:在 macOS 终端执行 nscurl --ats-diagnostics https://api.example.com,所有测试项显示 Result : PASS 才说明 ATS 模拟通过;再用 openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 看 Cipher 是否为 ECDHE-*-GCM-*。 Nginx 1.24 + OpenSSL 3.0 建议:ssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers 以 ECDHE-ECDSA-AES256-GCM-SHA384 和 ECDHE-RSA-AES256-GCM-SHA384 开头;ssl_prefer_server_ciphers off;ssl_stapling on。 例外配置只用于无法升级的第三方域名:NSExceptionDomains 内写 NSExceptionMinimumTLSVersion、NSExceptionRequiresForwardSecrecy=false;全局 NSAllowsArbitraryLoads=true 会触发 App Store 审核问询。 证书链必须带中间证书:openssl s_client -showcerts 应返回 2 到 3 张证书,openssl verify -CAfile fullchain.pem server.crt 返回 OK;缺中间证书常见报错为 Verify return code: 21 (unable to verify the first certificate)。
苹果 ATS 要求到底卡什么?为什么 HTTPS 配好了 App 还报 -1022
先说结论:ATS 不是”有没有 HTTPS”的开关,而是一组对 TLS 参数与证书链的硬性约束。据 Apple 开发者文档《Preventing Insecure Network Connections》,ATS 自 iOS 9 与 macOS 10.11 起默认启用;iOS 10 追加了 NSAllowsArbitraryLoadsInWebContent、NSAllowsLocalNetworking 两个更细的例外键;iOS 12.1.1 起,对 2018-10-15 之后签发的证书强制要求证书透明度(CT)日志中的 SCT,依据是 RFC 6962。凡是通过 URLSession、NSURLConnection 或 CFNetwork 发起的请求,都按这套策略校验。
四项硬门槛,任何一项不满足都会直接抛 -1022,而不是降级协商:
| 门槛 | ATS 要求 | 典型失败现象 |
|---|---|---|
| TLS 协议版本 | ≥ TLS 1.2;iOS 9/10 不协商 TLS 1.3,只认合规的 TLS 1.2 套件 | 源站仅开 TLS 1.0/1.1 → 握手即失败 |
| 密钥交换 | 必须支持 ECDHE(前向保密) | 只有 RSA 密钥交换 → 无可用套件 |
| 证书签名算法 | 链上签名 ≥ SHA-256(SHA-1 已被拒) | 中间证书仍是 SHA-1 → 链校验失败 |
| 密钥长度 | RSA ≥ 2048 位,ECC ≥ 256 位 | 1024 位 RSA → 拒绝 |
注意 ATS 不要求 EV/OV:DV 证书只要算法合规、链完整、SAN 匹配即可通过。下面这条命令可以在 Mac 上直接定位到具体失败项(nscurl 随 Xcode Command Line Tools 提供,macOS 10.11+ 可用):
# 逐项模拟 ATS 策略组合,定位到底是哪一项不达标
nscurl --ats-diagnostics --verbose https://api.example.com
# 只看默认策略这一项的结果,输出更短
nscurl --ats-diagnostics https://api.example.com | grep -A2 "Default ATS"
# 手工核对签名算法、公钥长度与 SAN(OpenSSL 1.1.1+)
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 /dev/null
| openssl x509 -noout -text
| grep -E "Signature Algorithm|Public-Key|DNS:"
# 确认是否真的支持 ECDHE(应能看到 ECDHE-RSA-AES128-GCM-SHA256 之类)
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 /dev/null
| grep -E "Cipher|Server Temp Key"
失败时的真实输出长这样,可以直接拿去比对:
Default ATS Dictionary... FAIL
Error : Error Domain=NSURLErrorDomain Code=-1022 "The resource could not be loaded
because the App Transport Security policy requires the use of a secure connection."
作用域常被误解:ATS 只管 App 内的 URLSession 等网络栈,不会自动约束 WKWebView 页面里的混合内容。H5 中写死的 http:// 资源必须单独改造,别指望加个域名例外就放行——App Store 审核也会核查 NSAllowsArbitraryLoads 与域名例外是否确有必要。
另一个高频误判:桌面 Chrome/Firefox 打得开,不代表 ATS 能过。浏览器可以协商 TLS 1.3、接受非 ECDHE 套件、容忍 SHA-1 中间证书,而 ATS 的判定更窄。按实际排查频率,根因排序是:① 源站仍开 TLS 1.0/1.1 或只提供 RSA 密钥交换;② 证书链缺中间证书、SAN 不匹配域名;③ CDN/负载均衡默认套件列表含非 ECDHE 项。Mozilla 的 Server Side TLS 指南给出的 “Intermediate” 配置可直接作为 ATS 兼容的起点。
所以看到 -1022,先跑 nscurl --ats-diagnostics 拿到失败的具体域名与失败项,再回头改源站或 CDN 的 TLS 配置,比在 Info.plist 里堆例外键有效得多。
第 1 步 盘点域名。先在工程根目录列出所有明文入口,别凭记忆列清单:
# 扫描 .m/.swift/.plist 中的 http:// 调用,输出文件名:行号便于逐个确认
grep -RIn --include='*.m' --include='*.swift' --include='*.plist' 'http://' .
# 顺带扫一遍 Info.plist 里已有的 ATS 例外,避免重复配置或漏删
grep -n -A5 'NSAppTransportSecurity' $(find . -name 'Info.plist')
把命中结果按 host 与端口归档,第三方域名单独标出,因为只有它们才值得开例外:
| host | 端口 | 归属 | 用途 | 例外负责人 / 到期日 |
|---|---|---|---|---|
| api.example.com | 443 | 自家 | 核心 API | 不需要例外 |
| img.example.com | 443 | 自家 CDN | 图片 | 不需要例外 |
| legacy.vendor-sdk.com | 80 | 第三方 SDK 回调 | 登录回跳 | 张工 / 2025-12-31 |
第 2 步 测协议与套件。据 Apple《Preventing Insecure Network Connections》文档,ATS 默认强制 TLS 1.2 及以上并要求前向保密,所以先用 OpenSSL(1.1.1 或 3.x 均可)验证服务端真的达标:
# 强制走 TLS 1.2,成功时应看到 Protocol : TLSv1.2 与 ECDHE 开头的套件
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null
# 预期:Cipher : ECDHE-RSA-AES256-GCM-SHA384(或 ECDHE-ECDSA-...)
# 再压到 TLS 1.1,必须失败,典型报错:
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_1 </dev/null
# 40A7B7C0FF7F0000:error:0A00042E:SSL routines::tlsv1 alert protocol version
第 3 步 测证书算法与链。ATS 要求签名算法不低于 SHA-256、RSA 至少 2048 位或 ECC 至少 256 位,且证书有效期自 2020-09-01 起不得超过 398 天(据 Apple 支持文档 HT210176):
# 导出叶子证书并检查签名算法、公钥长度、有效期
openssl s_client -connect api.example.com:443 -servername api.example.com /dev/null
| openssl x509 -noout -text | grep -E 'Signature Algorithm|Public-Key|Not After|ASN1 OID'
# RSA 期望:Signature Algorithm: sha256WithRSAEncryption / Public-Key: (2048 bit)
# ECC 期望:ASN1 OID: prime256v1(或 secp384r1)
# 确认服务端下发 leaf + intermediate,共 2~3 张,缺中间证书 iOS 会报 -1202
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null | grep -c 'BEGIN CERTIFICATE'
第 4 步 改服务端。协议与套件在服务端一次配好,客户端才不用打补丁。nginx 旧版本默认 ssl_protocols TLSv1 TLSv1.1 TLSv1.2,必须显式覆盖;Apache 2.4 默认 SSLProtocol all,同样要收紧:
# nginx.conf(server 或 http 块)
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-RSA-AES128-GCM-SHA256;
ssl_prefer_server_ciphers on; # 默认 off,前向保密场景建议打开
ssl_ecdh_curve X25519:prime256v1:secp384r1;
nginx -t && nginx -s reload
# httpd.conf / ssl.conf(Apache 2.4.7+ 才支持 TLSv1.2)
SSLProtocol -all +TLSv1.2 +TLSv1.3
SSLCipherSuite ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256
SSLHonorCipherOrder on
apachectl configtest && apachectl graceful
套件列表只保留 ECDHE 开头项即可天然排除 RC4、3DES、MD5;可对照 Mozilla SSL Configuration Generator 的「Intermediate」档核对。
第 5 步 配例外。只给确实升不动的第三方域名开小口,不要用 NSAllowsArbitraryLoads=true 全局放行——那会让苹果 ATS 要求形同虚设,且 App Store 审核会追问理由:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>legacy.vendor-sdk.com</key>
<dict>
<key>NSExceptionMinimumTLSVersion</key><string>TLSv1.1</string>
<key>NSExceptionRequiresForwardSecrecy</key><false/>
<!-- 负责人:张工;到期日:2025-12-31,到期必须复测 -->
</dict>
</dict>
</dict>
第 6 步 真机回归。模拟器不复现真实 ATS 行为,必须用 iOS 15/16/17 真机走 TestFlight 跑核心接口;在 Console.app 按进程名过滤 NSURLErrorDomain,出现 -1022(ATS 策略拦截)、-1200(TLS 握手失败,多为协议/套件不匹配)、-1202(证书不受信,多为缺中间证书或自签名)即说明前面某步没改到位。抓包代理只用于调试,Charles/Fiddler 的根证书绝不能进生产包的信任链,否则等于自建中间人入口。
Nginx 1.24、Apache 2.4 与 Info.plist 可直接抄的配置片段
问:Nginx 1.24 + OpenSSL 3.0 的 server 段到底怎么写?
据 Apple Developer 文档对 NSAppTransportSecurity 的说明,ATS 默认要求 TLS 1.2 及以上、且密码套件必须支持前向保密(ECDHE)。下面这段配置直接满足该条件,可整段抄用:
# /etc/nginx/conf.d/api.example.com.conf Nginx 1.24.x + OpenSSL 3.0.x
server {
listen 443 ssl;
# Nginx 1.25.1+ 改为独立指令 http2 on; 1.24 只能写成 listen 443 ssl http2;
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 站点证书在前,中间证书在后
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
ssl_trusted_certificate /etc/nginx/ssl/chain.pem; # 只给 OCSP stapling 校验用,不下发给客户端
ssl_protocols TLSv1.2 TLSv1.3; # 默认仅 TLSv1.2/1.3(1.23.4 起)
ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_prefer_server_ciphers off; # 默认 off,让客户端选,避免拖慢 TLS 1.3/HTTP2
ssl_session_cache shared:SSL:10m; # 默认 none
ssl_session_timeout 1d; # 默认 5m
ssl_session_tickets off; # 默认 on;关闭以换取严格前向保密
ssl_stapling on; # 默认 off
ssl_stapling_verify on;
resolver 223.5.5.5 8.8.8.8 valid=300s;
add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always;
}
server {
listen 80;
server_name api.example.com;
return 301 https://$host$request_uri; # HSTS 生效前的兜底跳转
}
关键点:ssl_ciphers 在 OpenSSL 3.0 下只作用于 TLS 1.2 及以下,TLS 1.3 的 5 个套件(TLS_AES_128_GCM_SHA256 等,见 RFC 8446)由 OpenSSL 自动管理,写进去也不生效。证书链顺序可用 openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 核对,顺序颠倒会让部分 Android/iOS 客户端报 unable to get local issuer certificate;私钥不匹配则 Nginx 启动直接失败:SSL_CTX_use_PrivateKey_file(...) failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)。
问:Apache 2.4.57 怎么写等价配置?
# /etc/apache2/sites-available/api.example.com.conf
<VirtualHost *:443>
SSLEngine on
SSLCertificateFile /etc/ssl/api/fullchain.pem # 含中间证书,顺序同上
SSLCertificateKeyFile /etc/ssl/api/privkey.pem
SSLProtocol -all +TLSv1.2 +TLSv1.3 # 默认 +TLSv1.2 +TLSv1.3,显式写便于审计
SSLCipherSuite ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
SSLHonorCipherOrder off
SSLUseStapling on # 需配套 SSLStaplingCache "shmcb:logs/stapling-cache(150000)"
SSLSessionTickets off # 默认 on
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
</VirtualHost>
# 改完先语法检查再热加载,configtest 失败时 reload 会静默保留旧配置
apachectl configtest && systemctl reload apache2
问:确实存在老接口,Info.plist 最小例外怎么写?
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>legacy.example.com</key> <!-- 只对这一个域放宽 -->
<dict>
<key>NSExceptionMinimumTLSVersion</key><string>TLSv1.1</string>
<key>NSExceptionRequiresForwardSecrecy</key><false/>
<key>NSIncludesSubdomains</key><true/>
</dict>
</dict>
</dict>
不要写 NSAllowsArbitraryLoads——App Store 审核会要求逐条说明理由,而域名级例外通常无需额外说明。
问:证书怎么申请,要买商业证书吗?
# certbot 2.x(Let's Encrypt),--deploy-hook 保证续期后自动重载
certbot certonly --webroot -w /var/www/html -d api.example.com
--deploy-hook 'systemctl reload nginx'
# 演练续期,不实际签发
certbot renew --dry-run
| 类型 | 价格区间 | ATS 是否满足 | 适用场景 |
|---|---|---|---|
| Let’s Encrypt DV(90 天自动续期) | 0 元 | 满足,只要 RSA≥2048 或 ECDSA P-256、SHA-256 签名 | 绝大多数 App 后端 |
| 商业 DV | 约 0–800 元/年 | 满足 | 需要商业支持 SLA |
| OV / EV | 约 1000–3000 元/年 | 不额外加分 | 金融、政企合规要求 |
据 Let’s Encrypt 文档,其证书有效期 90 天、支持 ACME v2 自动续期;苹果 ATS 只看密钥长度与签名算法,不要求 OV/EV,把钱花在自动化续期监控上更划算。首次上线 HSTS 建议先设 max-age=300 观察 1 天,确认无混合内容(HTTP 图片/字体)后再升到 31536000,否则回滚窗口长达一年——RFC 6797 规定浏览器在 max-age 内强制走 HTTPS。
源站升级、CDN 卸载、反向代理还是 ATS 例外?四种方案对比
“源站一时改不动,能不能只改 App 的 Info.plist 绕过苹果 ATS 要求?”可以,但你要接受审核问询的代价。Apple 在《Preventing Insecure Network Connections》中明确:ATS 默认强制 TLS 1.2、AES-GCM/CBC、SHA-2 签名,且要求前向保密(ECDHE 密钥交换)。例外键只是“申报豁免”,不是“让连接变安全”。下面把四种落地路径横向摆开,再给可直接复制的配置。
| 方案 | TLS 1.2/1.3 | 前向保密 | 证书与密钥 | 改动范围 | 审核风险 | 适用场景 |
|---|---|---|---|---|---|---|
| 源站 Nginx/Apache 升级 | 可控,建议 TLSv1.2+TLSv1.3 | 可配 ECDHE | RSA 2048/ECC 256,SHA-256 | 中,改配置+证书链 | 低 | 自有域名、可改服务端 |
| CDN 边缘 TLS(Cloudflare/阿里云/腾讯云) | 边缘默认支持 TLS1.2/1.3 | 边缘支持 ECDHE | 免费 DV 也可 | 低,改 DNS/CNAME | 低 | 多地域、源站老旧 |
| 自建 HAProxy/Nginx 反代 | 可控 | 可配 ECDHE | 同上 | 中高,多一层运维 | 低 | 多台旧服务统一收口 |
| Info.plist 域名例外 | 可降到 TLS1.1 | 可关闭 | 不受 ATS 硬门槛 | 低,改 App | 中高,需说明理由 | 第三方域名短期无法升级 |
方案一:源站直改(推荐首选)。Nginx 1.23 起的 ssl_protocols 默认值是 TLSv1 TLSv1.1 TLSv1.2,也就是说开箱配置仍带 TLS 1.0/1.1,必须显式收紧。改完用 openssl s_client 自检,这是最接近 iOS 行为的验证手段:
# 1) 确认协议版本、密钥交换类型(ECDHE 才算前向保密)、证书链是否完整
openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null 2>/dev/null
| grep -E "Protocol|Cipher|Verify return code"
# 期望输出:Protocol: TLSv1.2 / Cipher: ECDHE-RSA-AES128-GCM-SHA256 / Verify return code: 0 (ok)
# 若出现 "unable to get local issuer certificate",说明漏发中间证书,iOS 会直接失败
# 2) 确认已禁用 TLS 1.0/1.1(应当连接失败)
openssl s_client -connect example.com:443 -tls1_1 </dev/null 2>&1 | grep -i "handshake failure"
# /etc/nginx/conf.d/ats.conf —— 适用 nginx 1.19+,含注释
server {
listen 443 ssl http2;
server_name example.com;
ssl_protocols TLSv1.2 TLSv1.3; # 关键行:删掉 TLSv1/1.1,满足 ATS 与 PCI-DSS 要求
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:
ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305; # 全部 ECDHE,保证前向保密
ssl_prefer_server_ciphers off; # 默认 off;TLS1.3 下由客户端决定顺序
ssl_ecdh_curve X25519:prime256v1; # 默认 auto,显式指定避免弱曲线
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; # 必须用 fullchain,内含中间证书
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
}
方案二:CDN 边缘卸载。据 Cloudflare 文档,其 SSL/TLS 模式中的 Full (strict) 才会校验源站证书有效性;Flexible 意味着“用户到 CDN 加密、CDN 到源站明文 HTTP”,苹果 ATS 要求表面满足,攻击面其实一点没减。另外部分厂商默认放行 TLS 1.0/1.1 兼容老客户端,需在控制台最低 TLS 版本里手动设为 1.2。接入后同样跑一遍上面的 openssl s_client,把域名换成 CDN 加速域名即可。
方案三:自建反向代理收口。适合后端是多台只支持 TLS 1.0 的老服务。HAProxy 2.2+ 可用如下片段,注意 ssl-min-ver 是硬性下限:
# /etc/haproxy/haproxy.cfg
global
ssl-default-bind-ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384
ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets # 关键行:低于 1.2 直接拒绝握手
frontend https_in
bind *:443 ssl crt /etc/haproxy/certs/example.com.pem alpn h2,http/1.1
default_backend legacy_pool
backend legacy_pool
server old1 10.0.0.11:8080 check
方案四:Info.plist 域名例外。只对具体域名开口子,绝不用 NSAllowsArbitraryLoads 全局关闭——后者上架时几乎必被问询,且会连累所有 HTTP 请求:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>legacy.thirdparty.com</key>
<dict>
<key>NSExceptionMinimumTLSVersion</key><string>TLSv1.1</string> <!-- 仅此域名降级 -->
<key>NSExceptionRequiresForwardSecrecy</key><false/> <!-- 关闭前向保密硬门槛 -->
<key>NSIncludesSubdomains</key><true/>
</dict>
</dict>
</dict>
配置没生效时,Xcode 控制台会给出可检索的原文报错,例如 NSURLErrorDomain Code=-1022 "The resource could not be loaded because the App Transport Security policy requires the use of a secure connection.",或 CFNetwork SSLHandshake failed (-9824)(多为协议版本或套件不匹配)、kCFStreamErrorDomainSSL, -9813(证书链不可信)。看到 -1022 先查域名是否漏配例外,看到 -9813 先补中间证书。
成本与选型。源站升级约 0.5–2 人日;CDN 接入 1–4 小时,之后按 GB 计流量费;自建反代 1–3 人日;ATS 例外 10 分钟改完,但审核问询可能多耗 1–3 个工作日。自家域名优先源站升级或 CDN 卸载;只有第三方 SDK 域名推不动时才动 NSExceptionDomains。
证书怎么选?苹果 ATS 要求只看签名算法与密钥长度,不看 DV/OV/EV。Let’s Encrypt 自 2024 年 6 月起默认签发由 ISRG Root X1 交叉的 R10/R11(RSA)与 E5/E6(ECC)中间证书,RSA 2048 或 ECC P-256 配 SHA-256 均满足要求;ECC 证书在 iOS 9+ 可用,但若仍有大量老 Android 客户端需先评估兼容性。证书到期与链变更属于 TLS 生命周期管理的常规项,与 OCSP 装订、HSTS 预加载同属后续可展开的话题。
常见报错怎么查:-1022、-1200、-1202 与证书链错误
真机跑起来只看到 NSURLErrorDomain Code=-1022,日志里没有更多线索——这是 iOS 网络排查最常见的起点。苹果在开发者文档 Preventing Insecure Network Connections 中明确,ATS 拦截会以 NSURLErrorDomain 错误码抛出,错误码本身已经指明故障落在哪一层:先分层,再动手,比直接改 Info.plist 快得多。
| 错误码 | 系统描述片段 | 故障层 | 第一条验证命令 |
|---|---|---|---|
| -1022 | App Transport Security policy requires the use of a secure connection | ATS 策略层(未发起握手) | nscurl --ats-diagnostics |
| -1200 | An SSL error has occurred and a secure connection to the server cannot be made | TLS 握手层(协议/套件) | openssl s_client -tls1_2 |
| -1202 | The certificate for this server is invalid | 证书信任链层 | openssl s_client 看 Verify return code |
| curl 35 | error:0A000410:SSL routines::sslv3 alert handshake failure | 服务端协议/套件配置 | openssl ciphers -v 'ECDHE' |
-1022 是 ATS 自己拦的,握手根本没发生。先确认请求 URL 是不是 http://,再看 Info.plist 里 NSAppTransportSecurity 的例外是不是被误删或被另一个 plist 覆盖,最后跑一遍诊断:
# macOS 自带,逐项测试服务端是否满足苹果 ATS 要求
/usr/bin/nscurl --ats-diagnostics --verbose https://api.example.com
# 输出形如:
# Result : FAIL
# Test : TLSv1.2 with ECDHE
# 说明:服务端未提供前向保密套件,需在 Nginx 的 ssl_ciphers 中加入 ECDHE
-1200 是握手失败。据 RFC 5246,TLS 1.2 握手失败通常返回 handshake_failure 警报;如果服务端只开 TLS 1.0/1.1,或套件列表里 ECDHE 被删光,就会看到 sslv3 alert handshake failure——这个警报名是历史遗留,与 SSLv3 无关。用下面的命令复现:
# -servername 必带,否则 SNI 站点会返回错误证书
openssl s_client -connect api.example.com:443
-servername api.example.com -tls1_2 </dev/null
# 服务端配置参考(Mozilla SSL Configuration Generator 中间兼容档)
# nginx.conf
ssl_protocols TLSv1.2 TLSv1.3; # 苹果 ATS 要求最低 TLS 1.2,默认值随 nginx 版本不同
ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305';
ssl_prefer_server_ciphers on;
-1202 是证书不受信任。依次核对 SAN 是否包含域名(RFC 6125 已废弃 CN 匹配)、是否过期、设备系统时间是否正确。输出里的 Verify return code: 21 (unable to verify the first certificate) 几乎可以确定是服务端没下发中间证书,用 fullchain.pem 代替 cert.pem 即可。
nscurl 某项 FAIL 但浏览器正常?看 FAIL 行对应的测试名回查:TLSv1.2 with ECDHE 指向套件,Certificate transparency 指向 SCT(RFC 6962)缺失。另外,Charles/Fiddler 装到真机的根证书会把信任链改写成代理自签,调试结束务必在”设置 → 通用 → VPN 与设备管理”里移除。
第三方 SDK 还在打 HTTP?在 Xcode 里给 NSURLSession 的 dataTask(with:) 下断点,或设置环境变量 CFNETWORK_DIAGNOSTICS=3 打开 CFNetwork 详细日志,抓出 host 后先推动 SDK 升级;实在升不动才针对单个域名写 NSExceptionDomains 例外,并在 App Store 审核备注里说明理由,否则容易被判为规避苹果 ATS 要求。
怎么确认苹果 ATS 已通过?5 种验证方法与判定标准
能连上 HTTPS 不等于通过 ATS。ATS(App Transport Security)是一条由客户端(iOS/macOS 系统框架)强制的策略,服务器“看起来支持 TLS 1.2”和“满足 ATS 的全部硬性条件”是两件事。判定标准只有一条:用系统自带的 ATS 模拟器逐项跑出全部 PASS,其余四种方法都是补充证据。
方法一:nscurl –ats-diagnostics(唯一权威判定)。它由 macOS 自带(/usr/bin/nscurl),用系统网络栈按不同 ATS 配置组合去握手,据 Apple 官方文档《Preventing Insecure Network Connections》,这是验证 ATS 兼容性的官方手段:
# macOS 自带,无需安装;--verbose 可打印每项实际协商的 TLS 版本与密码套件
nscurl --ats-diagnostics --verbose https://api.example.com
# 输出形如:
# ATS[1] ...
# Result : PASS
# ATS[2] ...
# Result : FAIL
# 判定:所有 ATS[n] 均为 PASS 才算 ATS 模拟通过,出现任一 FAIL 即需整改
方法二:openssl s_client(定位具体缺哪一项)。nscurl 只给结论,openssl 给原因:
# 强制 TLS 1.2 握手,</dev/null 避免等待交互输入
openssl s_client -connect api.example.com:443
-servername api.example.com -tls1_2 </dev/null
# 判定三条:Protocol : TLSv1.2
# Cipher : ECDHE-RSA-AES256-GCM-SHA384(必须以 ECDHE- 开头 = 前向保密)
# Verify return code: 0 (ok)(证书链完整,非 20/21/62)
# 反证:TLS 1.1 应失败
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_1 </dev/null
# 期望报错:alert protocol version / no protocols available
方法三:testssl.sh(覆盖面最广)。3.2 版(2023 年发布)是单文件脚本,git clone 后 ./testssl.sh 直接跑,无需安装依赖,但要求 GNU OpenSSL 而非 macOS 自带的 LibreSSL,用 brew install openssl 后加 --openssl=/opt/homebrew/bin/openssl 指定:
./testssl.sh --protocols --fs --server-defaults https://api.example.com
# 判定:TLS 1.2 offered;Forward Secrecy offered;
# cipherlist 中无 RC4、无 3DES(EDE)、无 EXPORT
方法四:curl(验证应用层确实可用):
curl --tlsv1.2 --tls-max 1.2 -v https://api.example.com -o /dev/null -s -w "%{http_code}n"
# 期望:* SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384
# 200
curl --tlsv1.1 https://api.example.com
# 期望失败:curl: (4) OpenSSL was built without TLS 1.1 support 或握手失败
方法五:iOS 真机 + SSL Labs。用 Xcode 15 的 Devices 窗口抓 Console.app 日志,过滤 NSURLErrorDomain 与 ATS 关键字;再用 TestFlight 包跑登录、支付、图片加载三条链路——ATS 失败只在真实请求时暴露,且不同域名(尤其第三方 SDK 域名)要分别验证。SSL Labs 的 A/A+ 只作参考,它评的是服务器配置而非 ATS 策略,不能替代 nscurl。
| 方法 | 核心命令 | 通过判定 | 局限 |
|---|---|---|---|
| nscurl | --ats-diagnostics |
全部 Result : PASS | 仅 macOS 可用,结论粗 |
| openssl | s_client -tls1_2 |
TLSv1.2 + ECDHE- 开头 + Verify 0 | 需手工判读 |
| testssl.sh | --protocols --fs |
1.2 offered、FS offered、无 RC4/3DES | 需 GNU OpenSSL |
| curl | --tls-max 1.2 -v |
TLSv1.2 + HTTP 200 | 不模拟 ATS 策略 |
| 真机/SSL Labs | Console.app 过滤 NSURLErrorDomain | 三条链路无 ATS 报错 | 仅参考,非判定依据 |
注意:苹果 ATS 要求中,TLS 1.2 只是底线,真正卡人的是前向保密(ECDHE)与证书链完整性;若 Verify return code 为 21(unable to verify the first certificate),说明服务器漏发中间证书,nscurl 会直接 FAIL。
iOS 9 到 iOS 17 的 ATS 差异与 App Store 审核注意点
iOS 9 到 iOS 17,ATS 的规则到底改过几次?
改过,而且每次都会让旧项目出现线上问题。ATS(App Transport Security)从 iOS 9 起默认开启,默认要求 TLS 1.2 及以上、支持前向保密的密码套件(Apple 官方文档 Preventing Insecure Network Connections)。下表把版本差异与对应的 Info.plist 键整理成一张速查表:
| 版本 | 关键变化 | 相关键 | 实操影响 |
|---|---|---|---|
| iOS 9 | ATS 默认开启,最低 TLS 1.2 | NSAllowsArbitraryLoads |
全局放行能临时让 App 跑起来,但现在提交审核会被重点追问 |
| iOS 10 | 放行粒度拆分为 WebView 与本地网络 | NSAllowsArbitraryLoadsInWebContent、NSAllowsLocalNetworking |
前者只放开 WKWebView/UIWebView 加载的内容,不放开 URLSession;后者用于 .local、192.168.x.x、169.254.x.x |
| iOS 12.1.1 / macOS 10.14.1 | 对 2018-10-15 之后签发的证书强制要求 CT 日志(SCT,RFC 6962) | 无键可关 | 证书缺 SCT 会直接连接失败,报 NSURLErrorDomain -1200 |
| iOS 13–17 | 支持 TLS 1.3(RFC 8446),ATS 仍接受 TLS 1.2 | — | 为了追 TLS 1.3 而关掉 TLS 1.2,会让 iOS 9/10 设备直接断连 |
| macOS 10.11+ | 桌面端同样执行 ATS | 同上 | 可用 nscurl 预检,但最终以 iOS 真机为准 |
怎么验证证书有没有 SCT?据 Let’s Encrypt 文档,其证书自 2018 年起默认内嵌 SCT,但自建 CA 或部分商业 CA 不一定。命令行自查:
# 1) 检查服务器是否下发 SCT(iOS 12.1.1+ 对 2018-10-15 后签发的证书强制要求)
openssl s_client -connect api.example.com:443 -servername api.example.com -ct </dev/null 2>/dev/null
| grep -A3 "Signed Certificate Timestamp"
# 无任何输出 = 未下发 SCT;TLS 1.3 下部分 OpenSSL 版本不返回 SCT,可加 -tls1_2 复测
# 2) 用 CT 日志反查证书是否已公开记录
curl -s "https://crt.sh/?q=api.example.com&output=json" | head -c 400
本地想模拟一遍 ATS 判定怎么做?Xcode 自带 nscurl(随 Command Line Tools 安装,无独立版本号),可逐项探测 TLS 版本与前向保密:
# 输出每一项 ATS 要求(TLS 版本、FS、CT)的通过/失败明细
xcrun nscurl --ats-diagnostics --verbose https://api.example.com
注意:模拟器网络栈与真机存在差异,尤其 TLS 1.3 与会话恢复行为,最终结论必须用真机验证。
必须放开例外时,Info.plist 该怎么写才过审?能用 NSExceptionDomains 就别用全局开关,例外域名越少越好;一旦出现 NSAllowsArbitraryLoads=true,App Store 审核会要求你在审核备注里写明具体域名、原因与整改计划。苹果ats要求的底线是:默认连接必须满足 TLS 1.2 + 前向保密,例外只是逐域名的临时豁免。
<key>NSAppTransportSecurity</key>
<dict>
<!-- 避免 NSAllowsArbitraryLoads 全局放行 -->
<key>NSExceptionDomains</key>
<dict>
<key>legacy.example.com</key>
<dict>
<key>NSExceptionMinimumTLSVersion</key><string>TLSv1.2</string>
<key>NSIncludesSubdomains</key><true/>
<key>NSExceptionRequiresForwardSecrecy</key><true/>
</dict>
</dict>
</dict>
最后提醒:NSAllowsArbitraryLoadsInWebContent 常被误当成”全局放行替代品”,它只影响 WebView 内容加载,URLSession 直连仍受苹果ats要求约束——这也是很多 App 在 WebView 里能打开、原生接口却报 -1200 的真实原因。
上线后的长期维护:证书轮换、监控与第三方域名治理
Let’s Encrypt 证书只有 90 天,certbot 怎么续期才不会把线上搞挂?
据 Let’s Encrypt 官方文档,其证书有效期固定为 90 天,且官方建议在剩余 30 天时续期——这意味着每年至少 4 次自动续期动作,任何一次 reload 失败都会让旧证书继续服务直到过期。certbot 2.x 的正确做法是把校验和重载绑进 renew_hook,让“配置校验失败就不 reload”成为硬约束:
# /etc/letsencrypt/renewal/api.example.com.conf (certbot 2.x)
[renewalparams]
authenticator = nginx
installer = nginx
# 关键行:nginx -t 失败则整条命令非 0 退出,reload 不会执行,旧配置继续可用
renew_hook = nginx -t && systemctl reload nginx
# 每月演练一次(--dry-run 会真实执行 renew_hook,是唯一能验证 hook 的途径)
certbot renew --dry-run
# 确认 systemd 定时器存在(certbot 2.x 默认安装 certbot.timer,带随机延迟)
systemctl list-timers certbot.timer
注意 reload 而非 restart:Nginx 的 reload 是平滑的,restart 会瞬断连接,而 iOS 客户端对连接重置的容忍度很低。
怎么在证书到期前收到告警?
两条路线,前者适合已有 Prometheus 的团队,后者适合单机小站:
| 方案 | 命令/表达式 | 阈值 | 适用 |
|---|---|---|---|
| blackbox_exporter | probe_ssl_earliest_cert_expiry - time() < 21 * 86400 |
21 天 | 多域名、多机房 |
| cron + openssl | 见下方脚本 | 21 天 | 单机、无监控栈 |
# 每天 09:00 执行,输出 notAfter 并计算剩余天数
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null
| openssl x509 -noout -enddate
# 输出示例:notAfter=Mar 9 12:00:00 2026 GMT
OCSP stapling 明明开了却显示未启用,为什么?
最常见原因是 Nginx 缺少 resolver 或 ssl_trusted_certificate,此时 stapling 会静默失效(不报错、不写日志)。验证命令与最小配置:
openssl s_client -connect api.example.com:443 -servername api.example.com -status </dev/null 2>/dev/null
| grep -A1 "OCSP Response Status"
# 期望:OCSP Response Status: successful (0x0)
# 失败:OCSP response: no response sent
ssl_stapling on;
ssl_stapling_verify on;
# 必须包含签发本证书的中间 CA,直接用 Let's Encrypt 的 chain.pem 即可
ssl_trusted_certificate /etc/letsencrypt/live/api.example.com/chain.pem;
resolver 1.1.1.1 8.8.8.8 valid=300s; # 缺这行 stapling 一定不生效
resolver_timeout 5s;
如何防止有人把 TLS 1.0 加回配置?
苹果ats要求(App Transport Security)只接受 TLS 1.2 及以上并强制前向保密套件,一旦回落到 TLSv1/1.1 或 RC4、3DES,iOS 端会直接抛 NSURLErrorSecureConnectionFailed。用 Ansible 模板锁定协议与套件,并在代码评审里把 TLSv1、TLSv1.1、RC4、3DES 列为禁止字符串;每季度跑一次基线对比:
testssl.sh --quiet --severity HIGH --protocols --fs
https://api.example.com > baseline-$(date +%F).txt
App 里的第三方 SDK 请求了 http:// 域名怎么办?
这是苹果ats要求最容易被绕过的地方:主站配置再完美,某个广告或统计 SDK 走明文 HTTP,同样会被 ATS 拦截。治理办法是每季度扫描一次 App 与 SDK 的域名清单,建立台账(域名、负责人、当前 TLS 版本、到期日、替代计划),新增例外必须写明负责人与到期日,到期前 30 天复核。扫描时重点看 NSExceptionDomains 中是否残留 NSExceptionAllowsInsecureHTTPLoads。
最低 TLS 1.2。Apple 文档写的是 TLS 1.2 或更高,TLS 1.3 可用但不强制;iOS 9/10 设备只支持到 TLS 1.2,所以服务端要同时保留 TLSv1.2。
浏览器不执行 ATS 策略,且可能协商了 App 不接受的套件。先查 URL 是否 http://,再跑 nscurl –ats-diagnostics,重点看 ECDHE、SHA-256、RSA 2048 三项。
通常可以。Cloudflare 边缘默认提供 TLS 1.2/1.3 与 ECDHE 套件,Universal SSL 的 DV 证书只要 RSA 2048/SHA-256 就满足 ATS;但要把 SSL/TLS 模式设为 Full (strict),并确认回源不是 HTTP。
能编译运行,但上架包风险高。Apple 审核通常要求说明为什么必须全局放开;能用 NSExceptionDomains 按域名例外就不要全局放开,例外数量越少越好。
先跑 openssl s_client -connect host:443 -servername host -tls1_2,看是否握手失败;再查证书链是否完整、套件是否含 ECDHE、服务端是否只开 TLS1.0/1.1。若输出 Verify return code: 21,补中间证书。
不要求。ATS 只看 TLS 版本、前向保密、签名算法和密钥长度;Let's Encrypt 等 DV 证书只要 RSA 2048 位以上、SHA-256 签名、链完整即可。
检查代理工具安装的根证书、App 内 WKWebView 的混合内容、ATS 例外作用域、证书 SCT/CT 状态和系统时间;再用 Console.app 过滤 NSURLErrorDomain 看具体错误码。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。