nginx ssl_ciphers 配置指南:从默认值、TLS 1.2/1.3 套件到验证排错
nginx ssl_ciphers 只控制 TLS 1.2 及以下密码套件,TLS 1.3 需用 ssl_conf_command Ciphersuites(nginx 1.19.4+);公网站点推荐 ssl_protocols TLSv1.2 TLSv1.3 加 ECDHE+AEAD 套件。 nginx 1.23.0 的 ssl_ciphers 默认值为 HIGH:!aNULL:!MD5,ssl_protocols 默认值已改为 TLSv1.2 TLSv1.3;不显式配置时仍可能协商出 AES-CBC 与 RSA 密钥交换套件。 验证命令:openssl ciphers -v 'ECDHE-RSA-AES128-GCM-SHA256:...' 预检套件名,再用 openssl s_client -connect 域名:443 -servername 域名 -tls1_2 查看 Cipher 是否为预期值。 常见报错 nginx: [emerg] SSL_CTX_set_cipher_list(...) failed 多因套件名拼写错误或发行版 @SECLEVEL=2 过滤;unknown directive ssl_conf_command 表示 nginx 低于 1.19.4。 选型上 Mozilla 中间配置兼容 TLS 1.2 旧客户端,现代配置仅保留 AEAD 且扫描结果更干净;内网旧设备需保留 CBC 时,应放在独立 server 块并用防火墙限制来源。
nginx ssl_ciphers 配置为什么不生效:问题背景与根本原因
为什么改了 nginx ssl_ciphers,openssl s_client 却还是看到 TLS_AES_256_GCM_SHA384?因为这条指令根本管不到 TLS 1.3。nginx 把 ssl_ciphers 交给 OpenSSL 的 SSL_CTX_set_cipher_list(),它只作用于 TLS 1.2 及以下;TLS 1.3 的五个套件(TLS_AES_128_GCM_SHA256、TLS_AES_256_GCM_SHA384、TLS_CHACHA20_POLY1305_SHA256 等)由 SSL_CTX_set_ciphersuites() 管理,在 nginx 里要通过 1.19.4 起才提供的 ssl_conf_command Ciphersuites ... 设置。把 TLS 1.3 套件名写进 ssl_ciphers 既不会报错也不会生效——这正是”配置写了没反应”的头号原因。
| 指令 | 控制层级 | nginx 默认值 | 备注 |
|---|---|---|---|
ssl_ciphers |
TLS 1.2 及以下 | HIGH:!aNULL:!MD5 |
映射到 SSL_CTX_set_cipher_list |
ssl_conf_command Ciphersuites |
TLS 1.3 | 未设置,用 OpenSSL 默认 | nginx ≥ 1.19.4 |
ssl_prefer_server_ciphers |
服务端顺序优先 | off |
不开则 ssl_ciphers 的排列顺序无意义 |
ssl_protocols |
协议版本 | 1.23.0 起 TLSv1.2 TLSv1.3 |
旧版本还含 TLSv1/1.1 |
默认串为什么让扫描器报出 CBC 套件?HIGH:!aNULL:!MD5 并不等于”现代套件”,它仍包含 AES-CBC 与 RSA 密钥交换组合,扫描器常报 TLS_RSA_WITH_AES_128_CBC_SHA。想彻底剔除无前向保密的套件,光写 !aNULL 不够,必须写 !kRSA,或用 openssl ciphers -v 的 Kx= 列逐条核对:
# 看每条套件的 Kx(密钥交换)与 Enc(对称算法)
openssl ciphers -v 'ECDHE-RSA-AES128-GCM-SHA256:AES128-GCM-SHA256' | awk '{print $1, $3}'
# ECDHE-RSA-AES128-GCM-SHA256 - Kx=ECDH ← 有前向保密
# AES128-GCM-SHA256 - Kx=RSA ← 无前向保密,!aNULL 不会过滤它
# 排查实际生效值:必须看 -T 展开后的全量配置,而不是主文件
nginx -T 2>/dev/null | grep -n -A2 'ssl_ciphers'
发行版的 OpenSSL 安全等级会二次过滤。Debian 10、Ubuntu 20.04 在 /etc/ssl/openssl.cnf 写入 CipherString = DEFAULT@SECLEVEL=2,SECLEVEL=2 要求 ≥112 位安全强度,会静默丢弃 3DES、RC4 和部分 SHA1 套件。当 ssl_ciphers 里的套件被全部过滤,nginx 启动会直接失败并打印 SSL_CTX_set_cipher_list("...") failed (SSL: ...:no cipher match)。对比验证方法:
openssl ciphers -v 'DES-CBC3-SHA' # SECLEVEL=2 下输出为空
openssl ciphers -v 'DES-CBC3-SHA@SECLEVEL=1' # 降低等级后才可见
配置层级覆盖与 SNI 是另外两个高频陷阱。ssl_ciphers 可写在 http 与 server 块,后者覆盖前者;若 include 的 vhost 在 http 之后再次赋值,nginx -T 会看到多个值,握手只采用命中 server 块的那一个。多域名共用 443 时,扫描器若用 IP 或不匹配的 SNI 连接,会命中 default_server,看到的是另一个 server 块的配置。因此验证必须带 -servername,并给 default_server 也显式配置 ssl_ciphers,否则会回退到 nginx 默认的 HIGH:!aNULL:!MD5(据 nginx 官方 ngx_http_ssl_module 文档)。
# 带 SNI 验证 TLS 1.2 实际协商结果(ssl_ciphers 的唯一作用域)
openssl s_client -connect example.com:443 -servername example.com -tls1_2 /dev/null | grep 'Cipher is'
# 套件全被过滤时会看到:sslv3 alert handshake failure
nginx ssl_ciphers 配置完整实操步骤(6 步)
下面这 6 步是一套可以直接在生成环境执行的操作流程,命令基于 nginx 1.24.x + OpenSSL 3.0.x 验证(Ubuntu 22.04 / Rocky 9 均适用)。每一步都给出可回滚的检查点,避免“改完 reload 才发现配置写错”的情况。
步骤 1:记录基线,先备份再动手。套件名是否被支持,完全取决于 nginx 编译时链接的 OpenSSL 版本,所以第一步是把这两个版本记录下来。据 OpenSSL 官方文档,TLS 1.3 的密码套件只能通过 OpenSSL 的 Ciphersuites 接口控制,因此 nginx 侧必须知道底层的 OpenSSL 版本:
# 查看 nginx 版本与编译时链接的 OpenSSL 版本
nginx -V 2>&1 | tr ' ' 'n' | grep -E 'nginx/|openssl'
# 示例输出:
# nginx/1.24.0
# --with-openssl=/usr/lib/ssl 或 built with OpenSSL 3.0.11
# 查看运行环境中的 OpenSSL 版本(应为同一主版本)
openssl version -a
# 备份配置,文件名带日期,便于按时间点回滚
cd /etc/nginx
cp nginx.conf nginx.conf.bak.20250101
cp -a conf.d conf.d.bak.20250101
步骤 2:确定协议范围。公网站点统一设为 ssl_protocols TLSv1.2 TLSv1.3;。如果仍需兼容 Windows 7 上的 IE11 或 JDK 8 早期版本,保留 TLSv1.2 就够了,不要再打开 TLSv1.1。据 RFC 8996(2021 年 3 月),TLS 1.0 和 TLS 1.1 已被正式弃用,主流浏览器与 CDN 均已停止协商。另一个细节:ssl_protocols 只在 http 块写一次,server 块不要重复写。nginx 的配置继承规则是“子块覆盖父块”,一旦某个 server 块里写了半套指令,排查时极易误判最终生效值。
步骤 3:写入 TLS 1.2 套件。在 http 块中集中设置,顺序即服务端优先级(配合 ssl_prefer_server_ciphers on 生效):
http {
# TLS 1.2 套件:仅保留 AEAD(GCM / ChaCha20)与前向保密(ECDHE)
# ECDSA 与 RSA 各列一套,便于后续部署双证书
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 on; # 默认 off,开启后按上面顺序优先
ssl_protocols TLSv1.2 TLSv1.3; # 默认值仅 TLSv1.2 TLSv1.3(1.23.4+)
}
如果当前只部署了 RSA 单证书,列表里的 ECDSA 套件不会被实际协商,保留它们没有副作用;等后续加上 ECDSA 证书(Let’s Encrypt 与大多数公有 CA 默认签发 ECDSA 链),这四类套件即可立即生效,无需再改配置。注意 ssl_prefer_server_ciphers 的默认值是 off,在 TLS 1.3 下该指令不产生影响,因为 TLS 1.3 的套件选择由客户端主导。
步骤 4:单独控制 TLS 1.3 套件。ssl_ciphers 对 TLS 1.3 完全无效,必须用 ssl_conf_command 透传给 OpenSSL。该指令要求 nginx 1.19.4 及以上、且编译时链接的 OpenSSL 为 1.1.1 及以上:
http {
# 仅在 nginx >= 1.19.4 且 OpenSSL >= 1.1.1 时可用
ssl_conf_command Ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;
}
版本不够时只能升级 nginx,靠改 ssl_ciphers 是绕不过去的。执行 nginx -V 可以确认编译参数中是否出现 built with OpenSSL 1.1.1w 之类的字样。
步骤 5:检查覆盖关系与语法。先确认最终生效的指令只有一份,再做语法测试:
# 展开完整配置,定位所有 SSL 相关指令及其行号
nginx -T | grep -n -E 'ssl_(ciphers|protocols|conf_command|prefer_server_ciphers)'
# 语法检查,预期输出:
# nginx: configuration file /etc/nginx/nginx.conf test is successful
nginx -t
若出现 nginx: [emerg] unknown directive "ssl_conf_command",说明 nginx 版本低于 1.19.4,此时不要 reload,直接回滚配置或升级 nginx 后再操作。
步骤 6:平滑重载与回滚预案。
# 平滑重载:旧 worker 处理完存量连接后退出,443 监听不中断
systemctl reload nginx
ss -ltnp | grep ':443' # 确认监听仍在,pid 已更新
# 回滚命令(随时可用)
cd /etc/nginx && cp nginx.conf.bak.20250101 nginx.conf
&& nginx -t && systemctl reload nginx
变更窗口建议放在业务低峰,观察 10 分钟内的 5xx 比例与 error.log 中的 SSL_do_handshake() failed 记录,再关闭变更单。下表是本节涉及的四个关键指令的版本与默认值对照,方便你在多台机器上核对:
| 指令 | 作用域 | 默认值 | 版本要求 / 说明 |
|---|---|---|---|
ssl_protocols |
http / server | TLSv1.2 TLSv1.3 | nginx 1.23.4 起默认不再含 TLSv1/1.1 |
ssl_ciphers |
http / server | HIGH:!aNULL:!MD5 | 仅对 TLS 1.2 及以下生效 |
ssl_prefer_server_ciphers |
http / server | off | 对 TLS 1.3 无效 |
ssl_conf_command |
http / server | 无 | nginx ≥ 1.19.4 且 OpenSSL ≥ 1.1.1 |
nginx ssl_ciphers 配置示例:可复制的 nginx.conf 片段与 openssl 命令
把配置直接写进 nginx.conf 之前,先确认版本底线:ssl_conf_command 需要 nginx 1.19.4+ 且链接 OpenSSL 1.1.1+(TLS 1.3 套件由 OpenSSL 管理,不走 ssl_ciphers)。执行 nginx -V 2>&1 | tr ' ' 'n' | grep -E 'nginx/|openssl' 可一次看到两项版本号。下面片段只保留 ECDHE 密钥交换 + AEAD 加密,剔除全部 AES-CBC 与 RSA 密钥交换套件:
# nginx.conf —— 适用 nginx 1.19.4+ / OpenSSL 1.1.1+
http {
# TLS 1.3 套件必须用 ssl_conf_command 下发,ssl_ciphers 对它无效
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 on; # 默认 off,TLS 1.2 下让服务端顺序优先
ssl_conf_command Ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;
ssl_session_cache shared:SSL:10m; # 默认 none,10m 约可存 4 万会话
ssl_session_timeout 1d;
ssl_session_tickets off; # 默认 on;关闭以支持前向保密
}
server {
listen 443 ssl;
ssl_certificate /etc/nginx/ssl/fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
ssl_ecdh_curve X25519:secp256r1:secp384r1; # 默认 auto(1.11.0+)
}
关键配套:上面的 ECDHE-ECDSA-* 套件只有在服务器持有 ECDSA 证书时才会被选中。nginx 1.11.0+ 允许在同一 server 块写两组 ssl_certificate/ssl_certificate_key(ECC 在前、RSA 在后),nginx 会按客户端能力自动选择,双证书才让这段 nginx ssl_ciphers 配置里的 ECDSA 分支真正生效。
写进配置前先用 openssl ciphers 预检套件名是否合法(据 OpenSSL 官方文档,套件名大小写敏感、冒号分隔):
openssl ciphers -v 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256'
# 预期输出含:TLSv1.2 Kx=ECDH Au=ECDSA Enc=AESGCM(128)
# TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(128)
# 若输出为空:拼写错误,或被 OpenSSL 3.x 默认 SECLEVEL=2 过滤
openssl ciphers -v 'ECDHE-RSA-AES128-GCM-SHA256:@SECLEVEL=1' # 加安全等级对比
上线后用 s_client 分别验证两个协议版本。TLS 1.3 必须用 -ciphersuites,用 -cipher 会报 no ciphers available 或静默回退到 TLS 1.2:
# TLS 1.2:指定单一套件,验证证书与协商
openssl s_client -connect example.com:443 -servername example.com -tls1_2
-cipher 'ECDHE-RSA-AES128-GCM-SHA256' /dev/null | grep -E 'Protocol|Cipher'
# 预期:Protocol: TLSv1.2 / Cipher: ECDHE-RSA-AES128-GCM-SHA256
# TLS 1.3:只能用 -ciphersuites
openssl s_client -connect example.com:443 -servername example.com -tls1_3
-ciphersuites TLS_AES_128_GCM_SHA256 /dev/null | grep -E 'Protocol|Cipher'
| 验证手段 | 适用协议 | 参数写法 | 典型失败信息 |
|---|---|---|---|
openssl ciphers -v |
仅 TLS 1.2 及以下 | 套件名 + :@SECLEVEL=n |
输出为空(拼写/安全等级) |
s_client -cipher |
TLS 1.2 | -tls1_2 -cipher '...' |
handshake failure |
s_client -ciphersuites |
TLS 1.3 | -tls1_3 -ciphersuites '...' |
no ciphers available |
| nginx 访问日志 | 两者 | $ssl_protocol $ssl_cipher |
日志出现 AES-CBC 即配置未生效 |
最省力的持续验证是让 nginx 自己记录协商结果($ssl_cipher 自 1.7.4+ 可用,$ssl_curves 需 1.11.4+):
log_format tls '$remote_addr $ssl_protocol $ssl_cipher $ssl_curves $ssl_server_name';
access_log /var/log/nginx/tls.log tls;
# 上线一周后按套件聚合,确认无 AES-CBC 流量
awk '{print $3}' /var/log/nginx/tls.log | sort | uniq -c | sort -rn
若聚合结果里仍出现 ECDHE-RSA-AES128-SHA 一类 CBC 套件,通常是某个 server 块遗漏了 http 级继承,或 ssl_prefer_server_ciphers 被下游覆盖——用 nginx -T | grep -n ssl_ciphers 可列出全部生效位置。
nginx ssl_ciphers 方案对比与选型表:默认值、Mozilla 中间、现代与严格套件
实际选型时,不要只记一条字符串,而要把“兼容性下限”和“加密强度上限”分开决策。下面这张表把四类常见方案放在一起对比,其中字符串均摘自 Mozilla SSL Configuration Generator(server-side TLS 版本 5.7)与 nginx 官方文档,可直接粘贴进 ssl_ciphers。
| 方案 | ssl_ciphers 关键内容 | 兼容性 | 适用场景 |
|---|---|---|---|
| nginx 默认值 | HIGH:!aNULL:!MD5;包含 ECDHE/RSA 密钥交换、AES-GCM/AES-CBC、CHACHA20 |
很广,含 Windows XP SP3 之后的旧客户端 | 仅作兜底;公网生产不建议依赖默认值 |
| Mozilla 中间(Intermediate) | ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384 |
覆盖 Firefox 27、Chrome 31、IE 11(Win7)、Java 8u261 | 通用公网站点,TLS 1.2 + 1.3 并存 |
| Mozilla 现代(Modern) | 仅 ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384,去掉 DHE 与 CBC |
不支持 IE11、Android 4.4、Java 8 早期版本 | 新浏览器为主的站点、内部管理后台 |
| 严格套件 | 仅 ECDHE-ECDSA/RSA 的 AES-GCM/CHACHA20,并强制 TLS 1.3 | 需 ECDSA + RSA 双证书,客户端须支持 TLS 1.3 | 高安全 API、支付回调、后台管理 |
为什么 ssl_prefer_server_ciphers on 有时“看起来没用”? 该指令默认 off(nginx 1.11.0 起默认关闭),只在 TLS 1.2 及以下生效:开启后服务端按 ssl_ciphers 中的书写顺序挑选套件,适合统一服务端策略;关闭时由客户端偏好决定。TLS 1.3 下这条指令完全无效,套件由 ssl_conf_command Ciphersuites ... 传入 OpenSSL 的 TLS 1.3 列表,再与客户端求交集。据 OpenSSL 文档,TLS 1.3 的 ciphersuites 与 TLS 1.2 的 cipher list 是两套独立 API,把 TLS 1.3 套件名写进 ssl_ciphers 不会报错但也不会生效。
# nginx.conf —— 中间配置 + 显式区分 TLS 1.2 / 1.3(nginx 1.19.4+ 支持 ssl_conf_command)
ssl_protocols TLSv1.2 TLSv1.3; # 默认值仅 TLSv1.2 TLSv1.3(1.23.4+)
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers on; # 默认 off;仅对 TLS 1.2 生效
ssl_conf_command Ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256; # 需 OpenSSL 1.1.1+
性能与安全如何权衡? AES-GCM 在支持 AES-NI 的 x86 上吞吐明显更高;CHACHA20-POLY1305 在无 AES-NI 的 ARM 与老设备上更快。可以把 ECDHE-ECDSA-CHACHA20-POLY1305 写在 RSA 套件之前,但顺序最终仍受客户端偏好影响,除非开启 ssl_prefer_server_ciphers on。注意 nginx 的 ssl_ciphers 是 server 级指令,http 块的设置在任一 server 块被覆盖后即失效,迁移时不能照抄 Apache 的 SSLProtocol 写法(Apache 用 SSLCipherSuite,作用域在 VirtualHost);Caddy 默认自动管理 TLS,不暴露等价配置项,需在 tls 指令里自定义。
怎么定? 公网 Web 首选中间配置加 TLS 1.3;API 网关可用现代配置;若仍有 Windows 7 + IE11 流量,先用日志统计再收紧:awk '{print $NF}' access.log | sort | uniq -c | sort -rn | head(需在 log_format 中追加 $http_user_agent)。内网旧设备单独用 listen 8443 ssl 的 server 块保留 CBC 套件,并用防火墙限制来源,不要在 443 上放开。据 Mozilla 生成器说明,现代配置只保留 AEAD,能显著减少扫描器报告的弱套件数量。
这类报错有个共同点:nginx 在解析配置阶段就把 ssl_ciphers 字符串原样交给 OpenSSL 的 SSL_CTX_set_cipher_list(),只要其中没有任何一项能匹配,就直接 [emerg] 拒绝加载——不存在”忽略无效项继续跑”的降级行为。所以排查方向永远是两端:字符串本身是否拼对,以及本地 OpenSSL 是否具备该套件。
| 报错原文(节选) | 根因 | 修复动作 |
|---|---|---|
SSL_CTX_set_cipher_list("...") failed (SSL: error:0A0000B1:SSL routines::no cipher match) |
套件名拼错(如把 AES128 写成 AES25)、OpenSSL 版本不支持、或被 @SECLEVEL=2 过滤 |
用 openssl ciphers -v 逐项验证,删除输出为空/报错的项 |
unknown directive "ssl_conf_command" |
nginx 版本低于 1.19.4 | 升级到 1.24.x / 1.26.x;否则 TLS 1.3 套件无法控制 |
SSL_CTX_set_ciphersuites() failed 或 invalid value "TLS_AES_128_GCM_SHA256:..." |
把 TLS 1.3 套件写进了 ssl_ciphers,或 OpenSSL < 1.1.1 |
移入 ssl_conf_command Ciphersuites;openssl version 确认 ≥ 1.1.1 |
alert handshake failure / no protocols available |
双方协议版本或证书密钥类型无交集(ECDSA 证书 + 只支持 RSA 的客户端) | 分别用 -tls1_2 与 -tls1_3 测试,核对证书类型 |
扫描器仍报 TLS_RSA_WITH_AES_256_GCM_SHA384 |
串里含静态 RSA 套件(AES256-GCM-SHA384 无 ECDHE- 前缀),或沿用了 HIGH 这类宏 |
加 !kRSA 或只保留 ECDHE- 前缀项 |
| 配置改了但浏览器仍协商旧套件 | 其他 server 块或 default_server 覆盖;CDN 在边缘终止 TLS |
-servername 指定域名复测;在 default_server 同步配置 |
先验证字符串再动 nginx,顺序不要反。据 OpenSSL 文档,openssl ciphers 使用的正是同一套密码列表解析逻辑,因此它能把 nginx 即将遇到的失败提前暴露出来:
# 1) 逐项验证:把准备写进 ssl_ciphers 的串原样贴入,输出行数=可用套件数
openssl ciphers -v 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305' | wc -l
# 若整串无匹配,会直接报 error:...:no cipher match 并返回非 0
# 2) 确认 nginx 版本与"实际编译链接"的 OpenSSL(不是系统 openssl 命令的版本)
nginx -v
nginx -V 2>&1 | tr ' ' 'n' | grep -E 'openssl|with-http_ssl_module'
# 3) 查看 include 合并后的最终生效值,排除被覆盖
nginx -T 2>/dev/null | grep -nE 'ssl_ciphers|ssl_protocols|ssl_conf_command|server_name'
# 4) 分协议版本握手,定位是"协议无交集"还是"套件无交集"
openssl s_client -connect example.com:443 -servername example.com -tls1_2 &1 | grep -E 'Protocol|Cipher|alert'
openssl s_client -connect example.com:443 -servername example.com -tls1_3 &1 | grep -E 'Protocol|Cipher|alert'
关于 TLS 1.3 那一条,根因是命名规则不同:RFC 8446 把密钥交换与套件解耦,所以 TLS_AES_128_GCM_SHA256 这类名字不带 ECDHE- 前缀,写进 ssl_ciphers 必然不被识别。正确写法需要 nginx ≥ 1.19.4 且 OpenSSL ≥ 1.1.1:
# 适用:nginx 1.19.4+(稳定版 1.24.x / 1.26.x),编译 OpenSSL 1.1.1+ 或 3.x
ssl_protocols TLSv1.2 TLSv1.3;
# 仅作用于 TLS 1.2 及以下;!kRSA 排除静态 RSA 密钥交换
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:!kRSA;
# TLS 1.3 专用,顺序即优先级;缺省时 OpenSSL 用自己的三项默认套件
ssl_conf_command Ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;
ssl_prefer_server_ciphers on; # 默认 off;仅对 TLS 1.2 有意义,TLS 1.3 忽略此项
被 @SECLEVEL=2 静默过滤是最容易被忽略的一条。Debian 12、Ubuntu 22.04 起,系统 /etc/ssl/openssl.cnf 默认带 CipherString = DEFAULT@SECLEVEL=2,它会丢弃安全强度不足 112 位的算法(如 3DES、1024 位 RSA);此时你显式写下的 DES-CBC3-SHA 会变成”空项”,最终表现仍是 no cipher match。可临时验证:openssl ciphers -v 'DES-CBC3-SHA' 与 openssl ciphers -v 'DES-CBC3-SHA:@SECLEVEL=0' 输出对比。
最后解释”改完没生效”的两个高频假象。其一,nginx -s reload 在新配置解析失败时保留旧 worker 继续服务,报错只出现在终端或 error.log 里,业务侧看起来一切正常但套件未变——务必先 nginx -t 再 reload,并以 nginx -T 的输出去比对,而不是盯源文件。其二,若站点挂在 CDN 或云负载均衡后,TLS 在边缘节点终止,源站 ssl_ciphers 对终端用户完全无影响,需要在 CDN 控制台同步套件策略。据 Mozilla Server Side TLS 指南的推荐做法,优先使用其配置生成器产出的 intermediate 串,可避免手写时遗漏 ECDSA/RSA 双证书分支。
如何验证 nginx ssl_ciphers 配置已生效:s_client、nmap、sslyze 与日志
改完 nginx ssl_ciphers 后,怎么确认线上真的生效了?别只看配置文件——nginx 的 ssl_ciphers 可以在 http、server、location 多层级被覆盖,还能被 include 进来的 conf.d 文件二次覆盖。唯一可信的验证顺序是:单点握手 → 负向排除 → 全量枚举 → 真实流量日志。
第一步:用 s_client 看单次握手的实际结果。必须带 -servername(SNI),否则虚拟主机场景下拿到的是默认 server 的策略,结论完全失真;</dev/null 让握手后立即退出,避免交互挂起。
# 验证 TLS 1.2 实际协商的套件与密钥交换算法
openssl s_client -connect example.com:443 -servername example.com -tls1_2
/dev/null | grep -E 'Protocol|Cipher|Server Temp Key'
# 典型输出(OpenSSL 1.1.1 / 3.x)
# Protocol : TLSv1.2
# Cipher : ECDHE-RSA-AES256-GCM-SHA384
# Server Temp Key: X25519, 253 bits
# 验证 TLS 1.3(预期三者之一)
openssl s_client -connect example.com:443 -servername example.com -tls1_3
/dev/null | grep -E 'Protocol|Cipher'
出现 Server Temp Key: X25519 说明 ECDHE 密钥交换生效;若这一行缺失、只有 Cipher : AES256-GCM-SHA384 这类不带 ECDHE 前缀的套件,意味着退化到了 static RSA 密钥交换(无前向保密)。TLS 1.3 的预期套件按 RFC 8446 §9.1 只有五个 AEAD 套件,实际常见的是 TLS_AES_256_GCM_SHA384、TLS_AES_128_GCM_SHA256、TLS_CHACHA20_POLY1305_SHA256。注意:nginx 的 ssl_ciphers 对 TLS 1.3 无效,据 nginx 官方 ngx_http_ssl_module 文档,TLS 1.3 套件由 OpenSSL 默认集决定,要改必须用 ssl_conf_command Ciphersuites ...(nginx ≥ 1.19.4)。
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
- HTTPS证书申请 · SSL证书安装部署 · 证书续费
- SSL证书申请 · SSL证书购买 · SSL证书安装配置
第二步:负向验证,确认”删掉的真的协商不上”。
# 应失败:若 ssl_ciphers 已移除 CBC/RSA 套件
openssl s_client -connect example.com:443 -servername example.com -tls1_2
-cipher 'AES128-SHA' &1 | grep -E 'alert|Cipher is'
# 真实报错样例:
# 40A7...:error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure
# 应成功:确认保留的 GCM 套件仍可协商(兼容 Java 8 等旧客户端)
openssl s_client -connect example.com:443 -servername example.com -tls1_2
-cipher 'ECDHE-RSA-AES128-GCM-SHA256' /dev/null | grep 'Cipher is'
负向测试专门抓一类问题:指令写了但被上层 ssl_ciphers 覆盖,看起来删了、实际仍能协商。这一步失败才叫生效。
第三步:用扫描器枚举全部套件并留档。建议变更前后各跑一次、保存输出做 diff,作为 nginx ssl_ciphers 配置变更的验收证据。
| 工具 | 最小命令 | 关键输出 | 适用场景 |
|---|---|---|---|
| openssl s_client | -connect host:443 -servername host -tls1_2 |
单个 Cipher、Server Temp Key | 单点确认、负向排除 |
| nmap | nmap --script ssl-enum-ciphers -p 443 example.com |
TLSv1.2/TLSv1.3 套件清单 + strength A–F 评级 | 快速全量枚举 |
| sslyze | sslyze --regular example.com |
Accepted cipher suites、证书链、OCSP | CI 自动化回归 |
| testssl.sh | testssl.sh --fast https://example.com |
弱套件告警、协议支持矩阵 | 合规审计 |
第四步:日志验证——按真实流量确认。这是最直接的方式。在 server 块加一条独立日志($ssl_protocol、$ssl_cipher 自 nginx 0.7.65 起可用):
log_format tls '$remote_addr $ssl_protocol $ssl_cipher $time_iso8601';
access_log /var/log/nginx/tls.log tls;
# 运行 24 小时后统计协议与套件组合
awk '{print $2, $3}' /var/log/nginx/tls.log | sort | uniq -c | sort -nr | head
# 18342 TLSv1.3 TLS_AES_256_GCM_SHA384
# 2107 TLSv1.2 ECDHE-RSA-AES128-GCM-SHA256
# 3 TLSv1.2 AES128-SHA <-- 非预期,说明仍有覆盖源
一旦出现 TLSv1.2 AES128-SHA 这类非预期组合,用 nginx -T | grep -n ssl_ciphers 打印合并后的完整配置,定位是哪个 include 文件或哪个层级的 server 覆盖了策略。
第五步:外部评级与同面配置回归。用 Qualys SSL Labs 或 testssl.sh 对比评级,注意扫描器有缓存,变更后等 5–10 分钟再扫。同一轮变更里容易一起回归的还有 HSTS 与 OCSP stapling:add_header Strict-Transport-Security "max-age=31536000" always; 与 ssl_stapling on; ssl_stapling_verify on;(后者依赖 ssl_trusted_certificate),可用 openssl s_client -connect example.com:443 -servername example.com -status /dev/null | grep 'OCSP Response Status' 确认返回 successful (0x0)。
最后:别忘了旧客户端。curl --tlsv1.2 --tls-max 1.2 -sI https://example.com 与 curl --tlsv1.3 -sI https://example.com(curl ≥ 7.54 支持 --tls-max)分别验证。Java 8 不支持 X25519,只能走 P-256 的 ECDHE 套件,所以 ECDHE-RSA-AES128-GCM-SHA256 通常要保留;把变更前后的握手错误率记下来,避免只验证了新浏览器。
nginx ssl_ciphers 配置的版本差异与长期维护:nginx 1.19.4/1.23.0 与 OpenSSL 1.1.1/3.0
很多人第一次遇到“同一份 nginx ssl_ciphers 配置,在测试机和线上机扫描结果不一样”,根因往往不在字符串本身,而在 nginx 与 OpenSSL 的版本组合。下面按问题逐条拆。
为什么升级 nginx 小版本就能多出一条指令?据 nginx 官方 CHANGES 记录,ssl_conf_command 在 1.19.4(2020-12)引入,用于把 SSL_CONF_cmd 参数透传给 OpenSSL,这是唯一能控制 TLS 1.3 套件(如 TLS_AES_128_GCM_SHA256)的 nginx 原生命令。1.23.0(2022-06)又把 ssl_protocols 的默认值从 TLSv1 TLSv1.1 TLSv1.2 改为 TLSv1.2 TLSv1.3。低于 1.19.4 的版本,TLS 1.3 套件只能听 OpenSSL 的默认值,ssl_ciphers 对它完全无效。
| 发行版 | nginx | OpenSSL | ssl_conf_command | 备注 |
|---|---|---|---|---|
| Ubuntu 22.04 | 1.18.0 | 3.0.2 | 不支持 | 需 nginx.org PPA 升到 1.24.x |
| Debian 12 | 1.22.1 | 3.0.11 | 支持 | 默认可用 |
| RHEL 9 | 1.20.x | 3.0.x | 支持 | openssl.cnf 常设 SECLEVEL=2 |
| Ubuntu 20.04 | 1.18.0 | 1.1.1f | 不支持 | TLS 1.3 可用但不可控 |
怎么确认 nginx 真正链接的是哪个 OpenSSL?--with-openssl= 只是编译期路径,运行时版本要看 nginx -V 输出里的 built with OpenSSL 与 (running with ...):
# 查看编译参数与运行时 OpenSSL;running with 与 built with 不一致时要重点排查
nginx -V 2>&1 | tr ' ' 'n' | grep -E 'nginx version|built with OpenSSL|--with-openssl'
# 输出示例:
# nginx version: nginx/1.24.0
# built with OpenSSL 3.0.11 19 Sep 2023 (running with OpenSSL 3.0.13 30 Jan 2024)
# --with-openssl=/build/openssl-3.0.11
为什么改了 ssl_ciphers 却没生效?发行版的 /etc/ssl/openssl.cnf 里常见 CipherString = DEFAULT@SECLEVEL=2,它会在 OpenSSL 层再做一次过滤,把 3DES、RSA<2048、SHA1 签名等直接砍掉。对比测试时用 OPENSSL_CONF=/dev/null 屏蔽发行版配置,就能判断差异是 nginx 还是 OpenSSL 造成的:
# 带发行版配置
openssl ciphers -v 'ECDHE+AESGCM:ECDHE+CHACHA20' | head -3
# 屏蔽 /etc/ssl/openssl.cnf,排除 SECLEVEL 干扰
OPENSSL_CONF=/dev/null openssl ciphers -v 'ECDHE+AESGCM:ECDHE+CHACHA20' | head -3
# 注意:openssl.cnf 在 nginx 进程启动时读取,改完必须 restart,reload 无效
CI 里怎么防止配置漂移?把 nginx 实际生效的字符串抓出来交给 OpenSSL 解析,语法错误或套件被裁掉会立刻暴露:
set -e
nginx -t # 语法与证书路径校验
C=$(nginx -T 2>/dev/null | awk '/^[[:space:]]*ssl_ciphers/ {print $2}' | tr -d ';' | head -1)
echo "ssl_ciphers=$C"
openssl ciphers -v "$C" | awk '{print $1}' | sort > /tmp/actual.txt
diff -u ciphers-allowlist.txt /tmp/actual.txt # 白名单比对,不一致即失败
变更单该记什么?至少包含:nginx 版本、OpenSSL 版本、旧字符串、新字符串、nginx -t 与 openssl s_client -connect host:443 -tls1_3 </dev/null 的输出、回滚窗口(建议 ≥7 天)。多 CDN 场景下源站与边缘节点要分别验证,只改 nginx 而边缘仍放行旧套件,等于没改。
证书换了,套件会跟着变吗?会。只有 ECDSA 证书才能协商 ECDHE-ECDSA-* 套件,RSA 证书只能走 ECDHE-RSA-*;续期后务必用 openssl s_client 复查实际协商的 Cipher。OCSP stapling 与 HSTS 属于同一 TLS 加固面,按 Mozilla SSL Configuration Generator 生成片段后仍要按本站客户端分布裁剪,并在调整 nginx ssl_ciphers 配置后一并回归,避免只改一项造成配置漂移。
把 nginx ssl_ciphers 配置放进整体 TLS 加固:证书链、OCSP 与 HSTS 的联动
问:证书链不完整,为什么会被误判成 nginx ssl_ciphers 配置错误?
因为握手失败时客户端只报“SSL handshake failed”,而排查者往往先怀疑套件不匹配。实际上据 Let’s Encrypt 文档,fullchain.pem 必须同时包含叶子证书与中间证书,只部署叶子证书时桌面浏览器会靠 AIA 自动补链掩盖问题,而 Android 旧版、Java 8 客户端、部分 curl 版本会直接失败。所以调完 nginx ssl_ciphers 后必须单独验证证书链:
# 1) 查看服务器实际下发的证书数量,正常为 2 张(叶子 + 中间证书)
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| grep -E "^ *[0-9]+ s:"
# 2) 校验链是否可信;返回码非 0 即为链不完整
openssl s_client -connect example.com:443 -servername example.com -verify_return_error </dev/null 2>&1
| grep "Verify return code"
# 只部署叶子证书时的典型报错:
# verify error:num=21:unable to verify the first certificate
# Verify return code: 21 (unable to verify the first certificate)
问:OCSP stapling 怎么配,怎么确认真的生效?
OCSP stapling 把吊销状态查询结果缓存在服务端,随握手一起下发,省掉客户端对 CA 的额外请求。它和套件选择无关,但同属握手路径优化,应与 nginx ssl_ciphers 配置放在同一次变更里验证。注意 ssl_stapling、ssl_stapling_verify 默认都是 off,且必须提供 ssl_trusted_certificate(只放中间证书与根,不要放叶子证书)。
server {
listen 443 ssl;
http2 on; # nginx 1.25.1+ 写法,替代 listen ... http2
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 叶子 + 中间证书
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
ssl_stapling on; # 默认 off
ssl_stapling_verify on; # 默认 off
ssl_trusted_certificate /etc/nginx/ssl/chain.pem; # 仅中间证书/根
resolver 223.5.5.5 119.29.29.29 valid=300s; # 必须显式配,否则不解析 OCSP 响应地址
resolver_timeout 5s;
}
openssl s_client -connect example.com:443 -servername example.com -status </dev/null 2>/dev/null
| grep -A1 "OCSP Response Status"
# 成功:OCSP Response Status: successful (0x0)
# 失败:OCSP Response Status: no response sent
# 若 error.log 出现:ssl_stapling" ignored, issuer certificate not found for certificate
# 说明 ssl_trusted_certificate 指向的文件里缺少签发该叶子的中间证书
问:HSTS 能一次开到 max-age=31536000 吗?
不建议。HSTS 一旦下发,浏览器在有效期内拒绝走 HTTP,回滚成本极高,因此要灰度:先 max-age=300 验证全站(含 API、图床、CDN 回源)HTTPS 无误,再升到 31536000,最后才加 includeSubDomains。一个高频坑是 add_header 的继承规则——只要子级 location 里出现任何 add_header,父级全部 add_header 都会失效,所以务必带 always 并逐路径用 curl -sI https://example.com | grep -i strict-transport 抽查。
add_header Strict-Transport-Security "max-age=300" always; # 灰度起点,观察 1-2 天
# 稳定后: "max-age=31536000; includeSubDomains"(确认所有子域都支持 HTTPS 再加)
问:会话复用参数怎么调?
TLS 1.2 的完整握手需要 2-RTT,会话复用能把它降到 1-RTT。nginx 文档给出的换算关系是 1MB 共享缓存约存 4000 个会话,shared:SSL:10m 约 4 万个,需按峰值并发估算。TLS 1.3 的票据由 OpenSSL 管理,ssl_session_tickets off 会提升前向保密,但代价是握手次数增加,属于安全与性能的显式取舍。
ssl_session_cache shared:SSL:10m; # 默认 none
ssl_session_timeout 1d; # 默认 5m
ssl_session_tickets off; # 默认 on
# 验证复用是否生效:第二次连接应出现 "Reused"
openssl s_client -connect example.com:443 -servername example.com -reconnect </dev/null 2>/dev/null
| grep -E "New|Reused"
问:HTTP/2 与套件选择有什么联动?
据 RFC 9113 §9.2.2(取代 RFC 7540 的同等条款),HTTP/2 要求 TLS 1.2 及以上、禁止重协商,并列出了一组禁止使用的套件(主要是 TLS_RSA_WITH_AES_*_CBC_* 等非前向保密套件)。所以在 nginx ssl_ciphers 配置中去掉 CBC 与 RSA 密钥交换套件,本身就让 HTTP/2 部署更安全。另外从 nginx 1.25.1 起 listen 443 ssl http2; 已废弃,nginx -t 会告警:the “listen … http2” directive is deprecated, use the “http2” directive instead,应改为 listen 443 ssl; 加独立 http2 on;。
| 加固项 | 关键指令与默认值 | 建议值 | 验证方式 |
|---|---|---|---|
| 证书链 | ssl_certificate(无默认,必填) |
fullchain.pem |
openssl s_client -showcerts 看到 2 张证书 |
| OCSP stapling | ssl_stapling off / ssl_stapling_verify off |
均 on + ssl_trusted_certificate |
openssl s_client -status 返回 successful (0x0) |
| HSTS | 无内置指令,需 add_header |
max-age=300 起步 → 31536000 |
curl -sI 查响应头 |
| 会话复用 | ssl_session_cache none、ssl_session_timeout 5m、ssl_session_tickets on |
shared:SSL:10m / 1d / off |
openssl s_client -reconnect 出现 Reused |
| HTTP/2 | listen 443 ssl(1.25.1 前用 http2 参数) |
listen 443 ssl; + http2 on; |
nginx -t 无告警;curl -I --http2 |
顺序建议:先修证书链,再开 OCSP stapling,最后收紧密码套件并同时上调 HSTS——证书链有问题时,收紧套件会放大失败面,把两类故障混在一起,反而更难定位到底是链的问题还是 nginx ssl_ciphers 配置的问题。
因为 ssl_ciphers 只控制 TLS 1.2 及以下,TLS 1.3 套件由 OpenSSL 的 Ciphersuites 控制。需要在 nginx 1.19.4+ 中使用 ssl_conf_command Ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;,然后用 openssl s_client -tls1_3 -ciphersuites 验证。
公网站点可先用 Mozilla 中间配置:ECDHE-ECDSA/RSA 的 AES-GCM 与 CHACHA20,加 DHE-RSA 兼容旧客户端;再配合 TLS 1.3 的三个标准套件。若站点已无 Windows 7/IE11 流量,可收紧到仅 ECDHE+AEAD,减少扫描器报告的 CBC 与 RSA 密钥交换套件。
先执行 openssl ciphers -v '你的 ssl_ciphers 字符串',输出为空的项就是问题套件,常见是拼写错误或被 @SECLEVEL=2 过滤。删掉空项后 nginx -t 再 reload;若必须保留旧套件,可临时加 @SECLEVEL=1,但不建议在主站长期使用。
两者都使用 OpenSSL 套件命名,但作用域不同:nginx 的 ssl_ciphers 可写在 http/server 块,Apache 写在 VirtualHost 的 SSLCipherSuite。nginx 的 TLS 1.3 套件还需要 ssl_conf_command Ciphersuites,不能直接复制 Apache 配置;迁移时应分别验证 nginx -T 与 openssl s_client 输出。
该指令只影响 TLS 1.2 及以下,让服务端按 ssl_ciphers 顺序优先选择套件,默认是 off;TLS 1.3 下无效。若服务端把 AES-GCM 排在 CHACHA20 前,无 AES-NI 的旧设备可能性能较差;可根据客户端分布调整顺序,但不要指望它改变 TLS 1.3 套件。
用 openssl s_client -connect 源站 IP:443 -servername 域名 直连源站,查看 Cipher 是否为弱套件;若源站已移除而外部扫描仍有,检查 CDN/负载均衡的 TLS 配置。再用 nginx 日志中的 $ssl_cipher 统计源站实际协商结果,避免把边缘节点问题误判为 nginx ssl_ciphers 配置问题。
nginx 1.23.0 起 ssl_protocols 默认值变为 TLSv1.2 TLSv1.3,ssl_ciphers 默认值仍为 HIGH:!aNULL:!MD5;建议显式写死 ssl_ciphers 与 ssl_protocols,不依赖默认值。升级后用 nginx -T 检查最终配置,并用 openssl s_client 分别测试 TLS 1.2 与 TLS 1.3 的协商结果。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。