跳到主要内容
Tomcat

TrustAsia(亚洲诚信)SSL 证书 Tomcat 部署实战:PFX/JKS 配置、排错与验证

一、问题背景与根因:Tomcat 证书部署为什么总卡在“链”和“库”上

TrustAsia(亚洲诚信)的证书由 DigiCert 授权根签发,信任链与国际品牌一致,中文控制台、本地审核、人民币计价对国内企业采购比较友好。但把证书装到 Tomcat 上,失败点几乎从来不在“证书本身”,而在 Java 的密钥库(keystore)机制。Tomcat 通过 JSSE 完成 TLS 终结,证书必须被打包进 Java 能读的 PKCS12 或 JKS 文件,并且库里必须同时包含叶子证书与中间 CA,缺一环就会出现“浏览器正常、程序报错”的经典现象。

第一个根因是证书链不完整。Chrome、Edge、Safari 内置 AIA 自动补链能力,所以你用浏览器打开是绿锁;而 curl、Java HttpClient、微信小程序、Android 老版本、Python requests 不会去下载中间证书,直接报 unable to get local issuer certificate 或 PKIX path building failed。原文提到的“误用叶子证书而非 fullchain”正是这一类。

第二个根因是密钥库类型与密码模型不匹配。PKCS12 允许“库密码”和“私钥密码”不同,而老式 JKS 默认两者一致。很多人把 PFX 的导出密码填进 certificateKeystorePassword,却漏了 certificateKeyPassword,启动日志就抛 UnrecoverableKeyException: Cannot recover key。JDK 9 之后 keytool 默认生成 PKCS12 而不是 JKS,如果你按老教程写了 keystoreType="JKS" 却没有加 -deststoretype JKS,就会得到一个“后缀是 .jks、内容却是 PKCS12”的文件。

第三个根因是版本与有效期规则。TLS 1.3 需要 JDK 11 及以上,JDK 8 无论 Tomcat 多新都协商不出 TLS 1.3;公网 SSL 证书单张最长有效期自 2020-09-01 起为 398 天,CA/B Forum 已通过分阶段缩短方案(2026-03-15 起 200 天、2027-03-15 起 100 天),Let’s Encrypt 则固定 90 天。“装一次用三年”的做法彻底失效,续期后如何让 Tomcat 正确加载新文件,本身就是部署流程的一部分。

二、证书文件准备:从 TrustAsia 下发的压缩包到可用的 PFX/JKS

TrustAsia 交付的压缩包通常包含:example.com.crt(服务器/叶子证书)、example.com_ca.crt 或 ca-bundle.crt(中间 CA 链)、example.com.key(私钥,仅在你自行生成 CSR 时才有),以及可选的 example.com.pfx。先在服务器上解包并核对关键信息:

mkdir -p /opt/ssl/example.com && cd /opt/ssl/example.com
unzip -o example.com_ssl.zip
# 1) 看主体、签发者、有效期
openssl x509 -in example.com.crt -noout -subject -issuer -dates
# 2) 校验证书与中间链是否匹配
openssl verify -CAfile ca-bundle.crt example.com.crt
# 期望输出:example.com.crt: OK
# 3) 检查 PFX 里有几张证书(至少 2 张:叶子 + 中间 CA)
openssl pkcs12 -in example.com.pfx -nokeys -passin pass:导出密码 2>/dev/null | grep -c "BEGIN CERTIFICATE"

如果 CA 只给了 PEM 格式(.crt + .key),用 openssl 自己合成 PKCS12,注意 -certfile 放中间 CA,不要放根证书(根证书在客户端信任库中,重复放入反而可能引起链顺序错误):

openssl pkcs12 -export 
  -inkey example.com.key 
  -in example.com.crt 
  -certfile ca-bundle.crt 
  -name tomcat 
  -out example.com.pfx 
  -passout pass:'YourStrongPass'

需要 JKS 兼容老系统时,用 keytool 转换。注意 JDK 9+ 必须显式指定 -deststoretype JKS,并让别名与后续配置一致:

keytool -importkeystore 
  -srckeystore example.com.pfx -srcstoretype PKCS12 -srcstorepass 'YourStrongPass' 
  -destkeystore example.com.jks -deststoretype JKS 
  -deststorepass 'ChangeIt' -destkeypass 'ChangeIt' -alias tomcat
keytool -list -v -keystore example.com.jks -storepass 'ChangeIt' | grep -E "Alias name|Certificate chain length"

最后收紧权限,keystore 里就是私钥,任何能读文件的人都可能解密流量:chown tomcat:tomcat example.com.pfx && chmod 600 example.com.pfx。certificateKeyAlias 要记住,后面配置会用到;如果 PFX 只有一个条目,Tomcat 会自动选取,但显式指定更稳妥,也方便日后多域名多证书共存。

三、配置示例:Tomcat 8.5/9/10 的 SSLHostConfig 写法

Tomcat 8.5 起用 SSLHostConfig 替代了旧的 keystoreFile 属性组。以下是可直接粘贴进 conf/server.xml 的片段(Tomcat 9.0.x 实测通过):

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="200" SSLEnabled="true"
           scheme="https" secure="true" connectionTimeout="20000">
  <SSLHostConfig hostName="example.com"
                 protocols="TLSv1.2,TLSv1.3"
                 honorCipherOrder="true"
                 ciphers="TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384">
    <Certificate certificateKeystoreFile="/opt/ssl/example.com/example.com.pfx"
                 certificateKeystorePassword="YourStrongPass"
                 certificateKeystoreType="PKCS12"
                 certificateKeyAlias="tomcat" />
  </SSLHostConfig>
  <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
</Connector>

三个容易踩的细节:其一,ciphers 默认走 JSSE 命名(TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256),不是 OpenSSL 命名;只有设置 sslImplementationName="org.apache.tomcat.util.net.openssl.OpenSSLImplementation" 时才用 ECDHE-RSA-AES128-GCM-SHA256 这种写法,写错命名的结果是套件被全部过滤、握手直接失败。其二,protocols 不要写 TLSv1,TLSv1.1,主流浏览器与支付、小程序网关已拒绝。其三,certificateKeyPassword 仅当私钥密码与库密码不同时才需要。

老版本(Tomcat 7 / 8.0)写法不同,没有 SSLHostConfig:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true" scheme="https" secure="true"
           keystoreFile="/opt/ssl/example.com/example.com.jks"
           keystorePass="ChangeIt" keystoreType="JKS" keyAlias="tomcat"
           sslEnabledProtocols="TLSv1.2" />

再补一段 80 端口强制跳转(放在 8080 Connector 之后、</Host> 之前):

<security-constraint>
  <web-resource-collection>
    <web-resource-name>HTTPSOnly</web-resource-name>
    <url-pattern>/*</url-pattern>
  </web-resource-collection>
  <user-data-constraint><transport-guarantee>CONFIDENTIAL</transport-guarantee></user-data-constraint>
</security-constraint>

注意 Tomcat 10 起应用包名迁移到 jakarta.*,但 Connector 的 protocol 取值不变,仍是 org.apache.coyote.http11.Http11NioProtocol。

四、完整实操步骤:从 CSR 到服务生效的可复制流程

以下流程按“重新签发 + 部署”完整走一遍,命令可直接执行(域名与路径按需替换)。

Step 1 生成私钥与 CSR,私钥务必在服务器上生成、不要外传:

openssl req -new -newkey rsa:2048 -sha256 -nodes 
  -keyout /opt/ssl/example.com/example.com.key 
  -out /opt/ssl/example.com/example.com.csr 
  -subj "/C=CN/ST=Shanghai/L=Shanghai/O=Example Co.,Ltd/CN=example.com"
openssl req -in example.com.csr -noout -text | grep -A1 "Subject Alternative Name"

Step 2 上传证书并校验:按第二节的 openssl verify 与证书数量检查执行,确认 PFX 内证书条数 ≥ 2。

Step 3 备份配置:cp $CATALINA_HOME/conf/server.xml $CATALINA_HOME/conf/server.xml.bak.$(date +%F),出问题可 30 秒回滚。

Step 4 修改 server.xml:套用第三节模板,注意路径、密码、别名三处必须与 keystore 实际内容一致。

Step 5 配置语法自检,不真正对外服务,可提前发现 XML 写错、文件不存在、别名错误:

$CATALINA_HOME/bin/catalina.sh configtest

Step 6 重启服务,Tomcat 没有“重载证书”命令,改 Connector 必须重启进程:

systemctl restart tomcat && systemctl status tomcat --no-pager
ss -lntp | grep 8443
tail -n 50 $CATALINA_HOME/logs/catalina.out | grep -iE "startup|exception|ssl"

Step 7 放行端口:云主机安全组放行 8443/TCP,本机 firewalld 执行 firewall-cmd --permanent --add-port=8443/tcp && firewall-cmd --reload。若前面有 Nginx/SLB 做七层转发,Tomcat 只需监听内网,证书应装在入口层而非后端。

Step 8 续期演练:新证书到位后保持文件名不变直接替换,再重启;建议把“替换 + 重启 + openssl 验证”写成一个脚本,避免 398 天到期时手忙脚乱。整个流程控制在 10 分钟内,才能支撑每年至少一次的续期节奏。

五、对比表格:PFX/JKS 选型、Tomcat 版本差异与有效期规则

选型先看密钥库格式。下表是生产环境最常纠结的三个维度:

对比项 PKCS12(.pfx/.p12) JKS(.jks)
标准属性 RFC 7292 国际标准 Oracle 私有格式
Tomcat 8.5+ 支持 原生推荐,直接读取 支持,需 keystoreType=”JKS”
JDK 9+ keytool 默认 是 否,需 -deststoretype JKS
库密码/私钥密码 可不同,需 certificateKeyPassword 默认一致,可用 -destkeypass 分离
跨平台复用 openssl、Nginx、Java 通用 仅 Java 生态
建议 首选 仅老系统兼容

Tomcat 版本决定配置写法与协议能力:

Tomcat 版本 证书配置写法 TLS 1.3 状态
7.0.x keystoreFile / keystorePass 不支持 已 EOL
8.0.x keystoreFile / keystorePass 不支持 已 EOL
8.5.x SSLHostConfig + Certificate 需 JDK 11+ 维护中
9.0.x SSLHostConfig + Certificate 需 JDK 11+ 当前主流
10.1.x SSLHostConfig + Certificate 需 JDK 11+ Jakarta EE 9+

有效期规则直接决定运维节奏,务必按最新规则排期:

规则生效时间 单张公网 SSL 证书最长有效期
2020-09-01 起 398 天
2026-03-15 起 200 天
2027-03-15 起 100 天
Let’s Encrypt 90 天(固定)

结论很明确:新项目一律用 PKCS12,避免 keytool 转换引入的密码与别名歧义;只有必须对接只认 JKS 的老中间件时再转换。398 天有效期意味着同一张证书每年至少续期一次,而 2026 年后周期缩短到 200 天、2027 年后 100 天,续期窗口会更密集,建议在监控里配置到期前 30 天告警,而不是靠日历提醒。

六、常见错误排查:真实报错与定位命令

下面这些报错在 Tomcat 部署 TrustAsia 证书时出现频率最高,按日志原文对照处理即可。

1. java.io.IOException: Keystore was tampered with, or password was incorrect
库密码错误。用 openssl pkcs12 -in example.com.pfx -info -noout -passin pass:xxx 先验证密码本身是否正确,再检查 server.xml 里是否有空格或特殊字符未转义(& 需写成 &amp;)。

2. java.security.UnrecoverableKeyException: Cannot recover key
私钥密码与库密码不一致。PKCS12 场景下补上 certificateKeyPassword;JKS 场景下确认 -destkeypass 与 keystorePass 是否相同。

3. java.lang.IllegalArgumentException: Alias name [tomcat] does not exist
别名写错。执行 keytool -list -keystore example.com.pfx -storetype PKCS12 -storepass xxx 查看真实别名,或直接删掉 certificateKeyAlias 让 Tomcat 取默认条目。

4. PKIX path building failed / curl: (60) SSL certificate problem: unable to get local issuer certificate
证书链不完整,典型是只导入了叶子证书。用 openssl pkcs12 -in x.pfx -nokeys -passin pass:xxx | grep -c "BEGIN CERTIFICATE" 数条数,应 ≥ 2;重新打包时加 -certfile ca-bundle.crt。

5. 浏览器 ERR_SSL_VERSION_OR_CIPHER_MISMATCH / Firefox SSL_ERROR_NO_CYPHER_OVERLAP
两种可能:JDK 版本过低(TLS 1.3 需 JDK 11+,JDK 8 不支持);或 ciphers 用了 OpenSSL 命名却被 JSSE 解析,导致套件被全部过滤。用 java -version 与 nmap --script ssl-enum-ciphers -p 8443 example.com 交叉确认。

6. curl: (7) Failed to connect to example.com port 8443
服务未起或端口未放行。ss -lntp | grep 8443 看监听,再查安全组与 firewalld。

7. 续期后浏览器仍显示旧证书
Tomcat 只在启动时读取 keystore,换文件必须重启;并确认 certificateKeystoreFile 指向的正是被替换的文件,很多事故是配置指向 old.pfx 而运维换的是新目录。

8. 证书与私钥不匹配
比对模数:openssl x509 -noout -modulus -in example.com.crt | openssl md5 与 openssl rsa -noout -modulus -in example.com.key | openssl md5,两个 MD5 必须一致;ECDSA 证书无 modulus,改用 -pubkey 比对公钥。

七、效果验证:openssl、curl、SSLLabs 与自动化巡检

部署完成不能只看浏览器绿锁,要按“链、有效期、协议、客户端兼容性”四层验证。第一条命令确认链完整与到期时间:

openssl s_client -connect example.com:8443 -servername example.com -showcerts </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates
# 校验返回码必须是 0
openssl s_client -connect example.com:8443 -servername example.com -verify_return_error </dev/null 
  | grep "Verify return code"

再用 curl 模拟真实客户端,注意要指定 CA 链才能验证完整路径:

curl -vI https://example.com:8443 --cacert ca-bundle.crt
curl -I --http2 https://example.com:8443 --cacert ca-bundle.crt   # 验证 HTTP/2 是否生效

Java 应用侧自测,打开握手日志可以看到实际协商的协议与套件:

java -Djavax.net.debug=ssl:handshake -cp . SSLPing example.com 8443
# 日志中确认 "Protocol: TLSv1.3" 与 "Cipher Suite: TLS_AES_128_GCM_SHA256"

把剩余天数巡检做成 cron 任务,比人工记忆可靠得多:

#!/bin/bash
END=$(echo | openssl s_client -connect example.com:8443 -servername example.com 2>/dev/null 
      | openssl x509 -noout -enddate | cut -d= -f2)
DAYS=$(( ( $(date -d "$END" +%s) - $(date +%s) ) / 86400 ))
echo "证书剩余 ${DAYS} 天"
[ "$DAYS" -lt 30 ] && echo "ALERT: 需续期" && exit 2

最后用 SSL Labs(https://www.ssllabs.com/ssltest/)跑一次公开评分,目标 A 及以上:若提示“Chain issues: Incomplete”,回到第二节补链;若提示 TLS 1.0/1.1 可协商,检查 protocols 是否漏配。验证通过后再把配置同步到测试环境与灾备节点,形成闭环。

常见问题

Tomcat 8.5 及以上优先用 PKCS12/PFX,Tomcat 原生支持,JDK 9+ 的 keytool 默认格式也是 PKCS12,还能在 Nginx、openssl 之间复用;只有对接只认 JKS 的老系统或 Tomcat 7/8.0 时才转 JKS,转换时必须显式加 -deststoretype JKS,否则会得到后缀为 .jks 实为 PKCS12 的文件,导致 keystoreType 校验失败。

这是证书链不完整,PFX 里只有叶子证书、缺中间 CA。浏览器有 AIA 自动补链所以看不出问题,curl 和 Java 不会自动下载中间证书。用 openssl pkcs12 -in x.pfx -nokeys 数一下证书条数,应不少于 2 条;重新打包时用 -certfile ca-bundle.crt 把中间链带进去,根证书不要放。

Tomcat 只在 Connector 初始化时读取 keystore,替换文件不会自动生效,必须重启进程(systemctl restart tomcat)。另外确认 server.xml 里的 certificateKeystoreFile 指向的就是被替换的那个文件,很多事故是配置仍指向 old.pfx,而运维换的是新目录下的文件。

分别计算模数 MD5 比对:openssl x509 -noout -modulus -in example.com.crt | openssl md5 与 openssl rsa -noout -modulus -in example.com.key | openssl md5,两个值一致才匹配。ECDSA 证书没有 modulus,改用 openssl x509 -pubkey 与 openssl pkey -pubout 比对公钥。

可以,但取决于 JDK:需要 JDK 11 及以上,JDK 8 不支持 TLS 1.3。Tomcat 9/10 在 protocols 中写 TLSv1.2,TLSv1.3 即可,开启后用 openssl s_client -tls1_3 验证。注意不要为了评分关掉 TLS 1.2,部分老客户端只支持 1.2。

意味着同一张证书每年至少续期一次,且 CA/B Forum 已确定 2026-03-15 起缩至 200 天、2027-03-15 起缩至 100 天。建议到期前 30 天启动续期,把“替换文件 + 重启 Tomcat + openssl 验证”固化成脚本,并加上剩余天数监控告警。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。