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 里是否有空格或特殊字符未转义(& 需写成 &)。
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 验证”固化成脚本,并加上剩余天数监控告警。