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

让 Java 客户端通过 TLS 连接

让 Java 客户端通过 TLS 连接

这一节把已经开放安全端口的 ZooKeeper 接到 Java 客户端:切换为 Netty 连接实现,开启 secure 模式并加载信任库,再通过一次读写和 JVM TLS 握手日志确认业务请求确实走加密通道。

学习目标

  • 为 Java 客户端启用 ClientCnxnSocketNetty 与 zookeeper.client.secure
  • 正确加载服务端 CA 信任库并连接 secureClientPort
  • 用业务请求和 TLS 握手日志同时验证加密链路

明确安全端口与客户端模式

ZooKeeper 的 secureClientPort 专门接收 TLS 客户端连接,而 Java 客户端要使用安全端口,必须改用 org.apache.zookeeper.ClientCnxnSocketNetty 并开启 zookeeper.client.secure=true。普通 NIO 客户端直接连安全端口并不会自动升级为 TLS。([Apache ZooKeeper][1])

片段示例:如果本节只验证服务端证书和链路加密,服务器端可显式关闭客户端证书要求;证书路径、数据目录和其他集群参数仍按现有部署保留。

properties
secureClientPort=<PORT>
serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory
ssl.keyStore.location=<PATH>/server-keystore.p12
ssl.keyStore.password=<PASSWORD>
ssl.keyStore.type=PKCS12
ssl.clientAuth=none

ssl.clientAuth=none 只适用于单向 TLS。若服务器已经要求 mTLS,则不要为了让客户端“连得上”而关闭它,而应同时给客户端配置自己的 keyStore。当前 ZooKeeper 的 ssl.clientAuth 支持 none、want、need,默认值为 need。([Apache ZooKeeper][1])

Java 客户端 TLS 握手与业务请求链路

配置并运行 Java 客户端

可运行 Java 主程序如下。前提是项目已经引入与目标集群兼容的 ZooKeeper Java 客户端依赖;连接地址必须填写安全端口,而不是原来的明文 clientPort。

java
import java.nio.charset.StandardCharsets;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import org.apache.zookeeper.CreateMode;
import org.apache.zookeeper.Watcher;
import org.apache.zookeeper.ZooDefs;
import org.apache.zookeeper.ZooKeeper;

public class TlsZooKeeperClient {
    public static void main(String[] args) throws Exception {
        String connectString =
                System.getenv().getOrDefault("ZK_CONNECT", "zk1.example.com:2281");
        CountDownLatch connected = new CountDownLatch(1);

        ZooKeeper zk = new ZooKeeper(connectString, 10_000, event -> {
            if (event.getState() == Watcher.Event.KeeperState.SyncConnected) {
                connected.countDown();
            }
        });

        if (!connected.await(10, TimeUnit.SECONDS)) {
            zk.close();
            throw new IllegalStateException("ZooKeeper TLS connection timed out");
        }

        String path = "/tls-check";
        byte[] expected = "encrypted".getBytes(StandardCharsets.UTF_8);
        if (zk.exists(path, false) == null) {
            zk.create(
                    path,
                    expected,
                    ZooDefs.Ids.OPEN_ACL_UNSAFE,
                    CreateMode.PERSISTENT);
        } else {
            zk.setData(path, expected, -1);
        }

        byte[] data = zk.getData(path, false, null);
        System.out.println("state=" + zk.getState());
        System.out.println("data=" + new String(data, StandardCharsets.UTF_8));
        zk.close();
    }
}

示例故意使用开放 ACL,只隔离验证传输层;权限控制应在后续安全策略中单独收紧。启动时用系统属性切换 Netty、安全模式和信任库,并打开 JDK 的握手调试信息,确认 TLS 在 ZooKeeper 会话建立前已经完成。

bash
ZK_CONNECT=<HOST>:<PORT> java \
  -Djavax.net.debug=ssl:handshake \
  -Dzookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty \
  -Dzookeeper.client.secure=true \
  -Dzookeeper.ssl.trustStore.location=<PATH>/client-truststore.p12 \
  -Dzookeeper.ssl.trustStore.password=<PASSWORD> \
  -Dzookeeper.ssl.trustStore.type=PKCS12 \
  -cp "<PATH>/classes:<PATH>/lib/*" \
  TlsZooKeeperClient

预期输出

text
<TLS_HANDSHAKE_DETAILS>
state=CONNECTED
data=encrypted

<TLS_HANDSHAKE_DETAILS> 代表随 JDK 版本变化的握手调试行;应能看到 ClientHello、ServerHello、证书校验和协商出的 TLS 协议相关信息。<HOST>、<PORT>、<PATH> 与证书密码按实际环境替换。

同时验证“连通”和“加密”

程序打印 CONNECTED 只能证明 ZooKeeper 会话建立成功;真正确认加密还要看到 TLS 握手先于 ZooKeeper 业务请求完成。若关闭 zookeeper.client.secure 后同一地址无法正常建立 ZooKeeper 会话,而启用 secure 后可以读写 /tls-check,说明客户端确实在使用安全端口。

ZooKeeper 默认启用服务端主机名校验。连接串里的主机名必须出现在服务端证书可接受的名称范围中;生产环境不要通过关闭 zookeeper.ssl.hostnameVerification 来掩盖证书 SAN 配置错误。([Apache ZooKeeper][1])

失败时按握手层定位

出现 Connection refused 时先检查 <HOST>:<PORT> 是否真的是 secureClientPort 以及服务端是否监听;出现 SSLHandshakeException 或 PKIX 路径错误时检查客户端 trustStore 是否信任签发服务端证书的 CA;出现主机名校验失败时检查连接串主机名与服务端证书 SAN。

最重要的边界是把“ZooKeeper 会话失败”和“TLS 握手失败”分开处理:前者进入 ZooKeeper 协议层后再排查超时、ACL 等问题,后者应先修正端口、证书链、信任库或主机名,业务代码本身通常不是根因。

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

目录与阅读设置

阅读设置

17

记录一个想法

让 Java 客户端通过 TLS 连接

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

登录哪都通