跳到主要内容
HTTPS小程序证书

iOS ATS 与 SSL 证书部署实战:nscurl 诊断、TLS 1.2 合规与 398 天有效期

iOS ATS 与 SSL 证书部署实战:nscurl 诊断、TLS 1.2 合规与 398 天有效期 — 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,并在服务端升级完成后立即删除例外配置。

内容审核

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