iOS ATS 与 SSL 证书部署实战:TLS 1.2/1.3 配置、证书链修复与真实报错排查
ATS 为什么会拦截你的 App:背景与根因
App Transport Security(ATS)是 iOS 9 引入、默认开启的网络层强制策略。2017 年 1 月 1 日起,App Store 审核要求新提交的应用默认满足 ATS;虽然仍可通过 Info.plist 的 NSAllowsArbitraryLoads 申请例外,但必须在审核说明中给出理由,且苹果对例外审查越来越严。ATS 的默认要求可以归纳为 5 条硬指标:
- 协议版本:TLS 1.2 及以上(iOS 13 起完整支持 TLS 1.3);TLS 1.0/1.1 已被 RFC 8996 正式弃用,ATS 直接拒绝。
- 密码套件:必须支持前向保密,即 ECDHE 密钥交换,且仅接受 AES-128-GCM、AES-256-GCM、ChaCha20-Poly1305 这类 AEAD 套件;CBC 套件在 ATS 默认策略下不被接受。
- 签名算法:SHA-256 及以上,SHA-1 签名的证书一律失败。
- 密钥强度:RSA 不少于 2048 位,ECC 不少于 256 位(P-256)。
- 证书本身:域名(含 SAN)必须匹配、在有效期内、被 iOS 系统根证书库信任,并且证书链完整;2020 年 9 月 1 日之后签发的证书有效期不得超过 398 天。
线上最常见的根因有四类:一是只部署了服务器证书(leaf),没有附带中间证书,浏览器能靠 AIA 自动补链,iOS 不会,握手直接失败;二是服务器仍开放 TLS 1.0/1.1,或只配置了 RSA 密钥交换套件,没有 ECDHE;三是使用 SHA-1 签名的老证书或 RSA 1024 位密钥;四是自签名证书或私有 CA 未加入设备信任。另有一个容易被忽略的坑:2021 年 9 月 30 日 DST Root CA X3 过期,导致 iOS 9 及更早设备对 Let’s Encrypt 证书报错,需要改用 ISRG Root X1 交叉签名链,或直接放弃对旧系统的支持。
第一步:诊断现有 HTTPS 是否满足 ATS
改造之前必须先摸清现状。以下命令在 Linux/macOS 上可直接执行,按顺序跑一遍就能定位问题出在协议、套件还是证书链。
# 1) 抓取服务器实际下发的完整证书链(重点看返回了几个证书)
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| openssl x509 -noout -subject -issuer -dates -ext subjectAltName
# 2) 单独验证 TLS 1.2 是否可用(ATS 的最低门槛)
openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null 2>/dev/null | grep -E 'Protocol|Cipher'
# 3) 探测是否还开着 TLS 1.0/1.1,出现 handshake failure 反而是好事
openssl s_client -connect example.com:443 -servername example.com -tls1_1 </dev/null
# 4) 枚举全部协议与密码套件
nmap --script ssl-enum-ciphers -p 443 example.com
命令 1 的输出里,如果 -showcerts 只打印出一个 BEGIN CERTIFICATE,基本可以判定缺中间证书。命令 3 若返回 1408xxxxx:error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure,说明服务端已关闭旧协议,符合预期;若握手成功并显示 Protocol : TLSv1.1,就必须在服务端关掉。
在 macOS 上还可以直接用苹果官方的 ATS 诊断工具,它会针对不同 TLS 版本、不同套件组合逐项测试并给出 PASS/FAIL:
nscurl --ats-diagnostics --verbose https://example.com
最后检查签名算法与密钥长度:openssl s_client -connect example.com:443 </dev/null 2>/dev/null | openssl x509 -noout -text | grep -E 'Signature Algorithm|Public-Key'。出现 sha1WithRSAEncryption 或 Public-Key: (1024 bit),证书必须立即更换,任何配置都无法让 ATS 接受。
第二步:生成 CSR 并申请符合 ATS 的证书
确认需要换证后,先在服务器上生成密钥与 CSR。推荐 2048 位 RSA(兼容性最好)或 P-256 ECC(体积小、握手快,iOS 9+ 完全支持)。注意 SAN 字段:iOS 只认 SAN,不再认 CN,所有会被 App 访问的域名(含 api 子域)都要写进去。
openssl req -new -newkey rsa:2048 -sha256 -nodes
-keyout example.com.key -out example.com.csr
-subj '/C=CN/ST=Zhejiang/L=Hangzhou/O=Example Tech Ltd/CN=example.com'
-addext 'subjectAltName=DNS:example.com,DNS:www.example.com,DNS:api.example.com'
# 核对 CSR 中的 SAN 是否完整
openssl req -in example.com.csr -noout -text | grep -A1 'Subject Alternative Name'
# 生成 ECC 私钥与 CSR(可选方案)
openssl ecparam -genkey -name prime256v1 -out example.com.ec.key
openssl req -new -sha256 -key example.com.ec.key -out example.com.ec.csr
-subj '/CN=example.com' -addext 'subjectAltName=DNS:example.com,DNS:www.example.com'
-addext 需要 OpenSSL 1.1.1 及以上;若系统版本较低,改用配置文件方式,在 [req] 段加 req_extensions = v3_req,并在 [v3_req] 中写 subjectAltName = @alt_names。
如果使用 Let’s Encrypt,可直接签发,注意其证书有效期固定为 90 天,需配置自动续期,且续期后必须 reload 服务:
certbot certonly --webroot -w /var/www/html
-d example.com -d www.example.com -d api.example.com
--key-type ecdsa --elliptic-curve secp256r1
# 验证续期流程是否可用
certbot renew --dry-run
拿到证书后必须做链拼接。CA 通常会提供 example.com.crt(服务器证书)、intermediate_ca.crt(中间证书)、root_ca.crt(根证书,不要拼进链里)。拼接顺序是 leaf 在前、中间证书在后:
cat example.com.crt intermediate_ca.crt > fullchain.pem
openssl verify -CAfile root_ca.crt -untrusted intermediate_ca.crt example.com.crt
输出 example.com.crt: OK 才算链正确。若报 error 20 at 0 depth lookup: unable to get local issuer certificate,说明中间证书选错或缺失。
第三步:Nginx / Apache 的 TLS 1.2+ 配置示例
证书就绪后,服务端配置必须同时满足“协议版本 + 前向保密套件 + 完整链”三件事。下面是经过 ATS 验证的 Nginx 片段(1.19+,支持 TLS 1.3):
server {
listen 443 ssl http2;
server_name example.com www.example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 必须是拼接后的链
ssl_certificate_key /etc/nginx/ssl/example.com.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:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305';
ssl_prefer_server_ciphers off;
ssl_conf_command Ciphersuites 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256';
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/fullchain.pem;
add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always;
}
要点:TLS 1.3 的套件不能用 ssl_ciphers 配置,必须用 ssl_conf_command Ciphersuites(需 Nginx 1.19.4+ 与 OpenSSL 1.1.1+);ssl_prefer_server_ciphers 建议设为 off,把选择权交给客户端,iOS 会优先选 ChaCha20-Poly1305,弱网下表现更好。
Apache 2.4 的等价配置:
<VirtualHost *:443>
ServerName example.com
SSLEngine on
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305
SSLHonorCipherOrder off
SSLOpenSSLConfCmd Curves X25519:secp256r1
SSLCertificateFile /etc/httpd/ssl/fullchain.pem
SSLCertificateKeyFile /etc/httpd/ssl/example.com.key
Header always set Strict-Transport-Security 'max-age=31536000'
</VirtualHost>
Apache 2.4.8 之后不再需要单独的 SSLCertificateChainFile,中间证书直接拼进 SSLCertificateFile 即可。改完务必 nginx -t && nginx -s reload 或 apachectl configtest && systemctl reload httpd,并在 reload 前确认新证书路径已生效,避免重启后仍加载旧文件。
证书链与算法选择:ATS 合规对照表
很多“配置看起来没问题但 App 仍连不上”的情况,都是某一项指标差一点。下表把 ATS 的硬性要求和常见不合格表现、检测手段对应起来,可直接当验收清单用。
| 检查项 | ATS 要求 | 常见不合格表现 | 检测方式 |
|---|---|---|---|
| TLS 协议 | TLS 1.2 / 1.3 | 仍开放 TLS 1.0、1.1 | openssl s_client -tls1_1 |
| 密钥交换 | 必须 ECDHE | 只有 RSA 密钥交换套件 | nmap --script ssl-enum-ciphers |
| 对称套件 | AEAD(GCM / ChaCha20) | 仅 CBC(AES128-SHA) | 同上,看套件列表 |
| 签名算法 | SHA-256 及以上 | SHA-1 签名 | openssl x509 -text |
| 密钥长度 | RSA ≥ 2048 / ECC ≥ 256 | RSA 1024、弱曲线 | Public-Key: (1024 bit) |
| 证书链 | leaf + 中间证书完整 | 只下发 leaf | s_client -showcerts |
| 有效期 | ≤ 398 天(2020-09-01 后签发) | 多年期老证书 | openssl x509 -dates |
| 域名 | SAN 覆盖全部域名 | CN 有、SAN 缺 | -ext subjectAltName |
算法选择上的取舍:RSA 2048 兼容性最广,从 iOS 9 到老旧 Android 4.x 都认;ECC P-256 握手更快、证书更小,iOS 9+ 与 Android 5+ 支持良好,但如果 App 还需覆盖极老设备,建议 ECC + RSA 双证书(Nginx 用两个 ssl_certificate 指令分别指向 ECDSA 与 RSA 链)。至于 DV/OV/EV,ATS 本身不区分,只要求被系统信任;但企业级 App 若涉及支付,OV 证书在合规审计中更易通过。另外注意:2020 年 9 月 1 日后签发的证书一旦超过 398 天,苹果设备会直接判定不受信任,这已不是“建议”而是硬限制,多年期证书必须改为一年期并配合自动化续期。
常见错误排查:从 -1022 到证书链不完整
下面这些报错是 iOS 端与服务端最常撞见的,按现象对照处理即可。
1)NSURLErrorDomain Code=-1022:The resource could not be loaded because the App Transport Security policy requires the use of a secure connection. 说明 App 在访问明文 HTTP 地址。解决方式是服务端启用 HTTPS 并做 301 跳转,或在 Info.plist 中为该域名配置例外(需审核说明理由)。
2)NSURLErrorDomain Code=-1200:An SSL error has occurred and a secure connection to the server cannot be made. 这是握手失败,90% 以上是协议或套件不达标,或证书链不完整。先跑 openssl s_client -connect example.com:443 -servername example.com -showcerts,只看到一个证书就是链缺失。
3)NSURLErrorDomain Code=-1202:The certificate for this server is invalid. 证书过期、域名不匹配、自签名或不被系统信任。用 openssl x509 -noout -dates -ext subjectAltName 逐项核对。
4)服务端日志 SSL_CTX_use_PrivateKey_file ... key values mismatch:证书与私钥不配对。用下面两条命令比对公钥指纹:
openssl x509 -noout -pubkey -in fullchain.pem | openssl sha256
openssl pkey -pubout -in example.com.key | openssl sha256
5)unable to get local issuer certificate / error:num=20:中间证书缺失或顺序错误。重新执行 cat leaf.crt intermediate.crt > fullchain.pem,顺序不能颠倒。
6)CFNetwork SSLHandshake failed (-9824):多为服务端要求客户端证书,或套件协商不出共同项。检查是否误开了 ssl_verify_client on。
另外,如果只在旧设备上失败,检查是否用了 Let’s Encrypt 旧链(DST Root CA X3 已于 2021-09-30 过期)。用 openssl s_client -showcerts 看链顶端是否为 ISRG Root X1;不是则更新 certbot 与链文件。
效果验证:四道检查全部通过再发版
配置完成后不要直接提审,按以下四层验证,全部通过才算收工。
第一层,协议与套件。确认 TLS 1.2/1.3 可用、1.0/1.1 不可用:
echo | openssl s_client -connect example.com:443 -servername example.com -tls1_3 2>/dev/null | grep -E 'Protocol|Cipher'
openssl s_client -connect example.com:443 -servername example.com -tls1_1 </dev/null # 应报 handshake failure
curl -I --tlsv1.2 --tls-max 1.2 https://example.com # 应返回 200/301
curl -I --tlsv1.1 https://example.com # 应失败
第二层,证书链完整性。用 openssl s_client -showcerts 确认输出 2 个及以上证书;再用第三方视角验证,curl -vI https://example.com 2>&1 | grep -i 'SSL certificate verify',出现 SSL certificate verify ok 才算通过。
第三层,苹果官方诊断。在 macOS 上执行 nscurl --ats-diagnostics --verbose https://example.com,重点看输出末尾的 Result : PASS。若为 FAIL,日志会明确指出是 TLS 版本、套件还是证书问题。
第四层,真机回归。用 iPhone 分别在不同网络(Wi-Fi 与蜂窝)下调用接口,观察控制台是否还有 -1200;同时用 Charles/Proxyman 抓包确认实际协商的协议为 TLS 1.3、套件为 TLS_AES_128_GCM_SHA256 或 ECDHE-RSA-AES128-GCM-SHA256。
最后加一道运维保险:给证书到期设置监控(如 openssl x509 -checkend 2592000 -noout -in fullchain.pem,剩余不足 30 天返回非零),并为 90 天有效期的 Let’s Encrypt 证书配置 certbot renew --deploy-hook 'systemctl reload nginx',避免证书过期导致线上 App 集体断连。
常见问题
浏览器会通过 AIA 自动补全中间证书,iOS 不会。用 openssl s_client -showcerts 检查,若只返回一个证书,说明服务端未下发中间证书。把 leaf 与 intermediate 按顺序拼成 fullchain.pem 后重载服务即可解决。
不强制。ATS 的最低要求是 TLS 1.2,并需支持 ECDHE 前向保密套件与 AEAD 加密。TLS 1.3 握手更快、更安全,建议开启,但只配 TLS 1.2 也能通过 ATS 与 App Store 审核。
可以。苹果要求 2020 年 9 月 1 日后签发的证书有效期不超过 398 天,90 天远低于上限。关键是配置自动续期,并用 deploy-hook 在续期后重载 Nginx/Apache,否则 90 天到期会造成 App 连接失败。
技术上可以,但属于审核例外,必须在提交说明中给出充分理由,苹果可能拒绝。正确做法是服务端升级到 TLS 1.2+ 并部署完整证书链;确需兼容个别老域名,用 NSExceptionDomains 做定向例外,不要全局关闭。
说明证书与私钥不配对,常见于多域名环境拿错了 key。用 openssl x509 -noout -pubkey -in fullchain.pem 与 openssl pkey -pubout -in example.com.key 分别计算 sha256,两者一致才可配对,否则重新签发或找回对应私钥。