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

配置 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。

KeyStore 与 TrustStore 在单向和双向 TLS 中的关系

三种常见存储形式的边界如下:

格式 适合场景 注意点
JKS 兼容较老的 Java 工具链 Java 生态专用,跨工具交换不如 PKCS12
PKCS12 Java、OpenSSL 间交换私钥与证书链 适合作为统一容器,并显式配置 type=PKCS12
PEM 私钥、证书、CA 分文件管理 是否可直接加载取决于目标 ZooKeeper 版本与加载器

生产环境应固定存储类型,不要只靠 .jks、.p12 或 .pem 扩展名推断格式。

创建可验证的两个库

下面的主示例可独立运行,要求系统中已有 OpenSSL 与 JDK keytool。它先创建演示 CA 和服务端证书,再把私钥与证书链封装进服务端 KeyStore,并把 CA 导入客户端 TrustStore。

bash
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"

预期输出(签发工具可能额外打印版本相关提示,末尾关键行应为)

text
Alias name: server
Entry type: PrivateKeyEntry
Alias name: demo-ca
Entry type: trustedCertEntry

如果服务端条目显示为 trustedCertEntry,说明库里没有与证书匹配的私钥,不能用于服务端身份认证;客户端 TrustStore 则应该是受信任证书条目。

在 ZooKeeper 中引用密码文件

以下是单向 TLS 的 zoo.cfg 片段示例,不是独立命令。<PATH> 请替换为实际绝对路径;配置生效后,服务端会在安全端口加载 PKCS12 KeyStore。

text
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 命令:

text
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 验证。

bash
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

预期输出

text
extracted-server.crt: OK

若这里失败,先修复证书链或 TrustStore,再去排查 ZooKeeper 端口和网络。TLS 配置最稳妥的检查顺序是:私钥存在、叶子证书与私钥匹配、证书链完整、TrustStore 信任签发 CA,最后才进入应用层握手。

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

目录与阅读设置

阅读设置

17

记录一个想法

配置 KeyStore 与 TrustStore

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

登录哪都通