服务注册与分布式协调 / 系统课时

排查 TLS 握手与主机名失败

排查 TLS 握手与主机名失败

ZooKeeper TLS 失败不要从“换密码、重启服务”开始试错。有效的排查顺序是先证明证书链可信,再检查有效期与 SAN,随后确认是否要求客户端证书,最后才比较 TLS 协议和密码套件。这样可以把相似的握手报错快速归到唯一层级。

学习目标

  • 用 OpenSSL 和 keytool 验证证书链、有效期、SAN 与信任关系
  • 区分证书不受信任、主机名不匹配和客户端证书缺失三类常见故障
  • 在证书无误后继续定位协议版本与密码套件不兼容

先固定失败发生在哪一层

客户端看到 SSLHandshakeException 只能说明握手没有完成,不能直接说明是“证书坏了”。先保留客户端异常和服务端同一时刻日志,再按从静态证书到动态握手的顺序检查。

TLS 握手失败分层排查流程

排查时先使用与应用相同的目标主机名和端口。如果应用连接 zk1.example.com,就不要改成 IP 地址测试,否则 SAN 校验路径已经发生变化。

验证证书链、有效期与 SAN

下面的命令直接对 ZooKeeper 的 TLS 端口发起握手,并要求 OpenSSL 同时验证 CA 链和主机名。把变量替换为真实环境值;<PORT> 表示实际安全客户端端口。

bash
HOST=zk1.example.com
PORT='<PORT>'
CAFILE=/etc/zookeeper/pki/ca.pem

openssl s_client \
  -connect "${HOST}:${PORT}" \
  -servername "${HOST}" \
  -CAfile "${CAFILE}" \
  -verify_hostname "${HOST}" \
  -verify_return_error </dev/null

预期输出

text
Verification: OK
Verify return code: 0 (ok)

OpenSSL 版本不同,周边输出会有差异,但成功判据应包含证书验证成功与返回码 0。若出现 unable to get local issuer certificate、self-signed certificate in certificate chain 一类结果,应先修复信任链,而不是关闭主机名校验。

再读取服务端证书的有效期、主题和 SAN。这里假设证书文件已导出为 PEM;如果证书只在 JKS 或 PKCS12 中,可先用 keytool -list -v 查看同样的信息。

bash
openssl x509 \
  -in /etc/zookeeper/pki/server.pem \
  -noout -subject -issuer -dates -ext subjectAltName

预期输出

text
subject=<SERVER_SUBJECT>
issuer=<CA_SUBJECT>
notBefore=<TIME>
notAfter=<TIME>
X509v3 Subject Alternative Name:
    DNS:zk1.example.com

连接名必须出现在 SAN 中。现代 TLS 校验不应依赖 CN 兜底;如果应用使用 zk1.example.com,证书只有 DNS:zk1 或某个 IP SAN,都不能视为匹配。有效期检查还要同时确认 ZooKeeper 主机和客户端主机时间没有明显漂移。

区分信任失败和主机名失败

两类问题的修复方向完全不同。证书不受信任说明客户端不能把服务端证书链到自己的受信 CA;主机名失败则说明链可能完全可信,但证书身份与连接目标不一致。

若应用使用 JKS 或 PKCS12 信任库,可用 keytool 确认受信 CA 是否真的存在,而不是只检查文件路径。

bash
TRUSTSTORE=/etc/zookeeper/pki/client-truststore.p12
STOREPASS='<PASSWORD>'

keytool -list -v \
  -keystore "${TRUSTSTORE}" \
  -storepass "${STOREPASS}" \
  -alias zk-ca

预期输出

text
Alias name: zk-ca
Entry type: trustedCertEntry
Owner: <CA_SUBJECT>
Issuer: <CA_SUBJECT>

若别名不存在、证书指纹与签发服务端证书的 CA 不一致,应该修复 truststore 内容。若 truststore 正确但 -verify_hostname 失败,则应重新签发包含正确 DNS/IP SAN 的服务端证书,或让客户端改用证书已覆盖的规范主机名。

检查客户端证书是否缺失

当服务端配置为双向 TLS 时,服务端不仅出示自己的证书,还会要求客户端证明身份。此时“CA 已受信”仍不足以完成握手。

使用同一个目标再带上客户端证书和私钥测试:

bash
HOST=zk1.example.com
PORT='<PORT>'
CAFILE=/etc/zookeeper/pki/ca.pem
CLIENT_CERT=/etc/zookeeper/pki/client.pem
CLIENT_KEY=/etc/zookeeper/pki/client-key.pem

openssl s_client \
  -connect "${HOST}:${PORT}" \
  -servername "${HOST}" \
  -CAfile "${CAFILE}" \
  -cert "${CLIENT_CERT}" \
  -key "${CLIENT_KEY}" \
  -verify_hostname "${HOST}" \
  -verify_return_error </dev/null

预期输出

text
Verification: OK
Verify return code: 0 (ok)

如果“不带客户端证书失败、带证书成功”,根因已经缩小到客户端认证。接下来应检查应用是否加载了正确 keystore、私钥口令是否正确,以及客户端证书是否由服务端 truststore 信任的 CA 签发。错误文案可能因 JDK 与 TLS 版本而不同,不要只靠某一条固定报错字符串判断。

最后比较协议与密码套件

证书链、时间、SAN 和双向认证都通过后,才有必要检查协议与密码套件。最直接的方法是强制一个协议版本重复握手,以确认双方是否存在交集。

bash
HOST=zk1.example.com
PORT='<PORT>'
CAFILE=/etc/zookeeper/pki/ca.pem

openssl s_client \
  -connect "${HOST}:${PORT}" \
  -servername "${HOST}" \
  -CAfile "${CAFILE}" \
  -tls1_2 </dev/null

预期输出

text
Protocol  : TLSv1.2
Verify return code: 0 (ok)

如果默认握手失败而强制 TLS 1.2 成功,应继续对照 ZooKeeper 进程使用的 JDK、安全策略和客户端运行时,确认双方启用的协议与密码套件集合。若连 TCP 都无法建立,则问题已经不属于 TLS,应先检查监听端口、防火墙和目标地址。

最终验收不是“日志不再报错”,而是客户端用生产连接名完成证书链、主机名和双向认证校验后成功建立会话。按这个顺序保留每一步证据,才能避免用降低安全性的配置掩盖真正根因。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查 TLS 握手与主机名失败

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通