跳至主要內容

keytool Java keystore 与 truststore 工具手册

高谷深陵大约 10 分钟约 3046 字
keytool Java keystore truststore 与 alias 管理知识海报
keytool Java store、alias 与运行时参考图先锁定 java.home，再区分 truststore、keystore、trusted certificate 和 private key entry。高清原图

浏览器正常而 Java 报 PKIX，先找真实运行时

同一个 HTTPS 地址在浏览器里能打开，Java 却报 PKIX path building failed，通常不是服务突然换了证书，而是两类客户端读取了不同信任库。更麻烦的是，一台开发机上可能同时存在系统 JDK、IDE Runtime、Gradle daemon JDK、Maven Toolchain、容器 JDK 和 CI JDK。向错误的 cacerts 导入再多次，目标进程也不会改变。

keytool 随 JDK 提供，不需要单独下载。先从应用启动参数、容器镜像或构建任务确认目标 JVM 的 java.home，把该 JDK 的根目录设为 JAVA_HOME。例如真实 JDK 安装在 /opt/jdk-25 时执行 export JAVA_HOME=/opt/jdk-25，不要直接照抄这个示例路径。下面同时检查 PATH 与目标 JDK，后续实验均使用同一个 $JAVA_HOME/bin：

: "${JAVA_HOME:?set JAVA_HOME to the target JDK home}"
test -x "$JAVA_HOME/bin/java" && test -x "$JAVA_HOME/bin/keytool"
command -v java
"$JAVA_HOME/bin/java" -XshowSettings:properties -version 2>&1 | grep 'java.home'
"$JAVA_HOME/bin/keytool" -help

预期 java.home 位于选定 JDK，keytool -help 正常列出命令；PATH 中的 java 不同不影响后面显式路径的命令，但要查清目标应用实际启动的是哪一个。test 失败说明所选目录不是完整 JDK，先修正路径。Windows 可以用 where.exe java 与 where.exe keytool，再从应用启动日志、IDE 设置或容器进程确认 java.home。只看 JAVA_HOME 仍不够，因为已经运行的 daemon 可能在环境变量修改前启动。

store、alias 和条目类型是三件事

keystore 是保存密钥和证书条目的容器，truststore 是按用途对 store 的称呼：运行时把其中的可信证书当作信任锚。cacerts 是 JDK 自带的系统级 CA store，典型路径为 $JAVA_HOME/lib/security/cacerts。keytool -cacerts 等价于选择当前 JDK 的 cacerts，不能再同时指定另一条 -keystore 路径。

alias 是条目的稳定名称，不是证书 subject，也不是文件名。删除、替换、审计和回滚都应该围绕 alias 与指纹进行。先只查看当前 JDK 的条目；项目专用 store 在下一节创建后再检查：

"$JAVA_HOME/bin/keytool" -list -cacerts

当前 JDK 的默认 keystore type 是 PKCS12；历史项目仍可能显式使用 JKS。文件扩展名不可靠，.jks 可能实际是 PKCS12，.p12 也可能因为错误转换而缺少私钥。让 keytool -list -v 输出 store type 和条目类型，再决定迁移方式。

trustedCertEntry 只有证书，常用于 truststore。PrivateKeyEntry 同时持有私钥和证书链，用于服务端身份或 mTLS 客户端身份。把叶子证书导成 trusted entry 不会让 Java 服务获得对应私钥；把 CA 私钥塞进服务 keystore 更是完全错误的权限扩大。

导入 CA 前先从独立渠道核对指纹

为了让实验可回滚，优先创建项目专用 truststore，不要直接修改全局 cacerts。没有现成测试 CA 时，先按 OpenSSL 测试身份生成材料，进入该 tls-lab 目录；下列 certs/dev-root.pem 就是其公开根。检查已有组织 CA 时，将路径换为经过授权交付的根证书。先打印 SHA-256 指纹，与 CA 管理入口或另一条受控渠道核对：

mkdir -p .local
"$JAVA_HOME/bin/keytool" -printcert -file certs/dev-root.pem
openssl x509 -in certs/dev-root.pem -noout -fingerprint -sha256

本机实验根由前一篇刚刚生成，用两种工具核对同一证书指纹并确认路径；组织 CA 则必须拿交付渠道之外的批准指纹进行比对。指纹或来源不符时停在这里，不能继续导入。确认后才创建本篇专用 store；若它已存在，先检查归属，避免把实验根加进已有项目配置：

test ! -e .local/dev-truststore.p12 &&
"$JAVA_HOME/bin/keytool" -importcert \
  -keystore .local/dev-truststore.p12 \
  -storetype PKCS12 \
  -alias blog-stack-dev-root \
  -file certs/dev-root.pem

"$JAVA_HOME/bin/keytool" -list -v \
  -keystore .local/dev-truststore.p12 \
  -storetype PKCS12 \
  -alias blog-stack-dev-root

不要为未知根证书加 -noprompt。Oracle JDK 17 keytool 手册要求在导入 CA 前检查指纹；导入不受信的根意味着 Java 将信任它签发的所有服务身份。不同 JDK 的选项以目标版本手册和本机 -help 为准。自动化场景可以取消交互，但前提应是流水线已经从受控清单验证证书摘要，而不是为了让命令“跑过去”。

若必须修改当前 JDK 的全局库，使用同一个 JAVA_HOME 下的 keytool，并在变更前导出 alias、指纹和 store 摘要。全局 cacerts 影响这个 JDK 启动的所有应用，升级或替换 JDK 还可能丢失手工变更；它更适合由镜像、配置管理或发行商基线重建，而不是靠每台机器的命令历史维护。

把 truststore 接给真实 JVM

先按 OpenSSL 测试身份创建 tls-lab 与证书，并保持回环 s_server 运行；在同一目录导入前节的 certs/dev-root.pem。JDK 17 及以上可直接执行 Java 源文件，在此目录保存 HttpsCheck.java：

import java.net.URI;
import java.net.http.*;
import java.time.Duration;

class HttpsCheck {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(3)).build();
        var request = HttpRequest.newBuilder(URI.create("https://127.0.0.1:8443/"))
            .timeout(Duration.ofSeconds(5)).GET().build();
        var response = client.send(request, HttpResponse.BodyHandlers.discarding());
        System.out.println("status=" + response.statusCode());
        if (response.statusCode() != 200) throw new IllegalStateException("unexpected HTTP status");
    }
}

项目专用 store 只有被目标 JVM 读取才生效。先在 Bash 执行 read -r -s -p 'Truststore password: ' TRUSTSTORE_PASSWORD; printf '\n' 交互读入口令，再启动：

java \
  -Djavax.net.ssl.trustStore=.local/dev-truststore.p12 \
  -Djavax.net.ssl.trustStoreType=PKCS12 \
  -Djavax.net.ssl.trustStorePassword="$TRUSTSTORE_PASSWORD" \
  HttpsCheck.java

预期输出 status=200。-D 最终仍会把展开后的口令放进 JVM 参数，只适合无真实私钥的本地实验，不是生产秘密注入方案。生产应通过应用或受控启动器从只读 secret 文件加载 store；口令不应直接写进仓库脚本、进程编排文件或 CI 日志。即使 truststore 只含公开 CA，口令仍保护 store 完整性；服务 keystore 的口令还保护私钥。生产环境应从权限受控的 secret source 生成启动配置，并限制 store 文件的读取权限。

正向实验是让应用访问只被项目根信任的测试服务。反向实验不是删除服务器证书，而是执行 "$JAVA_HOME/bin/java" HttpsCheck.java 让同一应用切回默认 truststore；预期应恢复 PKIX 错误。如果仍成功，说明 CA 已进入全局 cacerts、系统 CA 被当前发行版采用，或者应用代码显式提供了另一套 TrustManager。

需要定位加载路径时，可以短时启用 JSSE 调试：

java \
  -Djavax.net.debug=ssl,handshake,trustmanager \
  -Djavax.net.ssl.trustStore=.local/dev-truststore.p12 \
  HttpsCheck.java

日志会暴露加载的 store、候选 issuer、握手主机和拒绝位置，也可能包含内部域名、证书主体和会话信息。只对受控请求短时开启，完成后删除或脱敏，不要长期把完整握手日志送入集中日志平台。

私钥身份通常先以 PKCS12 进入 Java

keytool 能生成密钥对、CSR 和自签证书，也能导入 CA 返回的证书链。继续使用前文 OpenSSL 测试身份生成的材料，在同一个 tls-lab 目录中把叶子私钥、叶子证书和直接签发它的实验根打包成 PKCS12。先确认文件存在且目标输出未占用；openssl pkcs12 -export 会交互要求设置导出口令：

test -r certs/dev.local.test-key.pem &&
test -r certs/dev.local.test.pem &&
test -r certs/dev-root.pem &&
test ! -e .local/server.p12 &&
openssl pkcs12 -export \
  -inkey certs/dev.local.test-key.pem \
  -in certs/dev.local.test.pem \
  -certfile certs/dev-root.pem \
  -name server-tls \
  -out .local/server.p12

"$JAVA_HOME/bin/keytool" -list -v \
  -storetype PKCS12 \
  -keystore .local/server.p12 \
  -alias server-tls

预期 alias 为 server-tls，条目显示 PrivateKeyEntry，证书链包含本实验叶子与直接签发它的根；若不是，先检查三个输入文件和导入输出，不要继续转换。组织签发的证书若有中间 CA，应把 -certfile 换成按顺序整理的链文件，并核对实际链长。trustedCertEntry 只证明证书存在，不证明私钥被带入。应用启动后还要从外部执行 TLS 握手，确认服务实际发送的叶子、完整中间链和 SAN；store 文件可读并不等于监听器采用了它。OpenSSL pkcs12 手册列出导出、链与私钥选项。

旧应用如果只接受 JKS，可以显式转换，并保持源文件只读：

test ! -e .local/server.jks &&
"$JAVA_HOME/bin/keytool" -importkeystore \
  -srckeystore .local/server.p12 \
  -srcstoretype PKCS12 \
  -srcalias server-tls \
  -destkeystore .local/server.jks \
  -deststoretype JKS \
  -destalias server-tls

"$JAVA_HOME/bin/keytool" -list -v \
  -keystore .local/server.jks \
  -storetype JKS \
  -alias server-tls

转换前后要核对 alias、条目类型、链长度和指纹。失败回滚应恢复旧文件路径和启动参数，不要把转换结果反向覆盖唯一的原始 store。旧 JKS 只是兼容约束，不是新项目继续选择它的理由。

多 JDK 环境要把证书状态当成可部署配置

IDE 能启动应用而 CI 失败，往往说明证书被手工导进了 IDE Runtime；本机 Maven 成功而 Gradle 失败，可能是 daemon 尚未重启或 toolchain 选择了另一 JDK；宿主机成功而容器失败，则是镜像里的 $JAVA_HOME/lib/security/cacerts 完全独立。

团队应让构建和运行入口同时输出 Java 供应商、版本、java.home、truststore 路径与批准的 CA 指纹。敏感口令无需输出，证书私钥也不能进入诊断包。容器镜像中的信任基线应由 Dockerfile 或镜像构建流程可重复生成；运行时临时导入只适合短时实验，因为下一次重建会丢失状态。

mkcert 可以在设置了 JAVA_HOME 时尝试安装本地根，但它无法替团队证明每个进程选择了哪一个 JDK。keytool 的价值正是在真实运行时边界内对 store、alias 和条目做可复核操作。

删除 alias 后必须看到失败恢复

项目专用 truststore 的退出动作是：先让所有服务切回批准的 store，再删除对应 alias，最后在确认文件没有其他共享条目后删除整个文件。下面的删除命令只针对前面实验创建的 alias，不得直接套到团队共享 store：

"$JAVA_HOME/bin/keytool" -delete \
  -keystore .local/dev-truststore.p12 \
  -storetype PKCS12 \
  -alias blog-stack-dev-root

"$JAVA_HOME/bin/keytool" -list \
  -keystore .local/dev-truststore.p12 \
  -storetype PKCS12 \
  -alias blog-stack-dev-root

第二条应以 alias 不存在失败。全局 cacerts 则使用同一个 JDK 执行 keytool -delete -cacerts -alias ...，并重启 IDE、daemon、容器和长驻服务。只删除 PEM 文件或修改 JAVA_HOME 不会自动撤销已经运行进程中的 TrustManager。

最终反证是新 JVM 对原测试服务恢复明确的信任失败，同时其他批准的公网和内部 CA 仍可用。若删除一个 alias 后大量无关服务一起失败，说明此前把共享根、叶子证书和应用身份混在了同一条目策略里；恢复原 store 后，应重新按 CA 归属和运行时半径设计，而不是继续向 cacerts 追加临时证书。

完成反证、停止测试服务和 Java 进程后，在 tls-lab 目录内先核对 .local/dev-truststore.p12 已无其他条目，再逐个确认并移除本篇创建的文件。rm -i 会逐文件询问；若任何文件实际被项目使用，回答 n 并先查清归属。OpenSSL 实验生成的 CA 私钥和其他材料仍按 OpenSSL 的退出步骤单独处理：

"$JAVA_HOME/bin/keytool" -list -keystore .local/dev-truststore.p12 -storetype PKCS12

仅当输出确认该实验 store 没有其他条目、文件也没有被服务继续引用时，执行下面的逐文件清理：

rm -i -- HttpsCheck.java .local/dev-truststore.p12 .local/server.p12 .local/server.jks

权威资料与规范地址

查阅内容官方地址
JDK 17 keytool 手册https://docs.oracle.com/en/java/javase/17/docs/specs/man/keytool.html
OpenSSL pkcs12 手册https://docs.openssl.org/3.5/man1/openssl-pkcs12/
跳到正文