服务注册与分布式协调 / 系统课时
配置 KeyStore 与 TrustStore
配置 KeyStore 与 TrustStore
本节把证书材料整理成 ZooKeeper 可加载的 KeyStore 与 TrustStore,并用密码文件避免把口令直接写进配置。完成后,你会得到服务端私钥库、客户端信任库,以及一套在启用 TLS 前检查条目类型和证书链的验证方法。
学习目标
- 区分 KeyStore、TrustStore 以及 JKS、PKCS12、PEM 的职责
- 用 PKCS12 组织服务端私钥和客户端受信任 CA
- 使用密码文件配置 ZooKeeper TLS,并在启动前验证库内容
先分清两个库装什么
KeyStore 保存“本端要证明自己是谁”的私钥和证书链;TrustStore 保存“本端愿意信任谁”的 CA 或证书。单向 TLS 中,ZooKeeper 服务端需要 KeyStore,客户端至少需要 TrustStore;启用双向 TLS 后,客户端也需要自己的 KeyStore,服务端则需要能信任客户端签发 CA 的 TrustStore。

三种常见存储形式的边界如下:
| 格式 | 适合场景 | 注意点 |
|---|---|---|
| JKS | 兼容较老的 Java 工具链 | Java 生态专用,跨工具交换不如 PKCS12 |
| PKCS12 | Java、OpenSSL 间交换私钥与证书链 | 适合作为统一容器,并显式配置 type=PKCS12 |
| PEM | 私钥、证书、CA 分文件管理 | 是否可直接加载取决于目标 ZooKeeper 版本与加载器 |
生产环境应固定存储类型,不要只靠 .jks、.p12 或 .pem 扩展名推断格式。
创建可验证的两个库
下面的主示例可独立运行,要求系统中已有 OpenSSL 与 JDK keytool。它先创建演示 CA 和服务端证书,再把私钥与证书链封装进服务端 KeyStore,并把 CA 导入客户端 TrustStore。
set -euo pipefail
rm -rf ./store-demo
mkdir ./store-demo
cd ./store-demo
openssl genrsa -out ca.key 2048
openssl req -x509 -new -key ca.key -sha256 -days 3650 \
-subj "/CN=Demo Root CA" \
-addext "basicConstraints=critical,CA:TRUE" \
-addext "keyUsage=critical,keyCertSign,cRLSign" \
-out ca.crt
openssl genrsa -out server.key 2048
openssl req -new -key server.key \
-subj "/CN=zk-1.example.test" \
-out server.csr
printf '%s\n' \
'basicConstraints=critical,CA:FALSE' \
'keyUsage=critical,digitalSignature,keyEncipherment' \
'extendedKeyUsage=serverAuth' \
'subjectAltName=DNS:zk-1.example.test' > server.ext
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
-CAcreateserial -days 365 -sha256 -extfile server.ext -out server.crt
printf '%s\n' 'changeit-server' > keystore.pass
printf '%s\n' 'changeit-trust' > truststore.pass
chmod 600 keystore.pass truststore.pass
openssl pkcs12 -export -name server \
-inkey server.key -in server.crt -certfile ca.crt \
-out server-keystore.p12 -passout file:keystore.pass
keytool -importcert -noprompt -alias demo-ca -file ca.crt \
-keystore client-truststore.p12 -storetype PKCS12 \
-storepass:file truststore.pass
keytool -list -v -alias server -keystore server-keystore.p12 \
-storetype PKCS12 -storepass:file keystore.pass \
| grep -E "Alias name|Entry type"
keytool -list -v -alias demo-ca -keystore client-truststore.p12 \
-storetype PKCS12 -storepass:file truststore.pass \
| grep -E "Alias name|Entry type"预期输出(签发工具可能额外打印版本相关提示,末尾关键行应为)
Alias name: server
Entry type: PrivateKeyEntry
Alias name: demo-ca
Entry type: trustedCertEntry如果服务端条目显示为 trustedCertEntry,说明库里没有与证书匹配的私钥,不能用于服务端身份认证;客户端 TrustStore 则应该是受信任证书条目。
在 ZooKeeper 中引用密码文件
以下是单向 TLS 的 zoo.cfg 片段示例,不是独立命令。<PATH> 请替换为实际绝对路径;配置生效后,服务端会在安全端口加载 PKCS12 KeyStore。
secureClientPort=2281
serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory
ssl.keyStore.location=<PATH>/server-keystore.p12
ssl.keyStore.type=PKCS12
ssl.keyStore.passwordPath=<PATH>/keystore.pass
ssl.clientAuth=NONE这里显式设置 ssl.clientAuth=NONE,表示先建立“服务端出示证书、客户端验证服务端”的单向 TLS。若安全目标是双向 TLS,不应停在这个设置:服务端还需要 TrustStore,并应要求客户端出示受信任 CA 签发的证书。
客户端同样需要切换到 Netty TLS 连接,并至少指定受信任 CA。以下为 JVM 系统属性的片段示例,不是独立 Shell 命令:
zookeeper.client.secure=true
zookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty
zookeeper.ssl.trustStore.location=<PATH>/client-truststore.p12
zookeeper.ssl.trustStore.type=PKCS12
zookeeper.ssl.trustStore.passwordPath=<PATH>/truststore.pass实际启动客户端时,把这些键转换为对应的 -Dkey=value 参数,或按所用框架的配置方式注入。双向 TLS 时再补充客户端 KeyStore,并让服务端 TrustStore 信任客户端证书的签发 CA。
验证证书链是否真的可用
最后不要只检查“文件存在”,还要确认 KeyStore 中导出的服务端证书能被客户端信任的 CA 验证。
cd ./store-demo
openssl pkcs12 -in server-keystore.p12 \
-clcerts -nokeys \
-passin file:keystore.pass \
-out extracted-server.crt
openssl verify -CAfile ca.crt extracted-server.crt预期输出
extracted-server.crt: OK若这里失败,先修复证书链或 TrustStore,再去排查 ZooKeeper 端口和网络。TLS 配置最稳妥的检查顺序是:私钥存在、叶子证书与私钥匹配、证书链完整、TrustStore 信任签发 CA,最后才进入应用层握手。