CFCA SSL 证书部署到 Tomcat 实战:PKCS12 配置、证书链修复与 8 类报错排查
一、问题背景与根因:Tomcat 部署 CFCA 证书为什么反复踩坑
CFCA(中国金融认证中心)签发的 SSL 证书覆盖 RSA/ECC 国际算法与 SM2 国密算法双体系,常见于银行、政务、国企项目。但证书装进 Tomcat 后,最典型的故障是「浏览器能打开、Java 客户端和小程序握手失败」,或者 Tomcat 启动日志直接抛 keystore 异常。归纳下来有 5 类根因。
根因 1:只部署了叶子证书。CFCA 交付包里 server.crt 是服务器证书,intermediate.crt 是中间 CA。Tomcat 只会把 keystore 里已有的证书链原样下发,缺中间证书时 Chrome 会尝试通过 AIA 扩展自动补链而显示正常,但 Java、curl、微信小程序不会去抓 AIA,直接报 PKIX path building failed。
根因 2:文件格式不对。Tomcat 的 <Certificate> 只认 keystore(PKCS12/JKS),不能直接读 fullchain.pem + privkey.key,PEM 必须先转换。
根因 3:PFX 的 PBE 算法与 JDK 不匹配。OpenSSL 3.x 默认用 AES-256-CBC + SHA256 加密 PKCS12,JDK 8u301 之前的版本读不了,启动时报 keystore 密码错误。
根因 4:配置属性过期。Tomcat 8.5 起 Connector 上的 keystoreFile/keystorePass 已弃用,改为 SSLHostConfig + Certificate;沿用旧写法在 Tomcat 9/10 上会出现「证书配了但 8443 不监听」。
根因 5:有效期规则已变。按 CA/Browser Forum 要求,2020-09-01 起所有公开信任证书单张有效期上限 398 天(Let’s Encrypt 仍为 90 天),CFCA 国际算法证书同样受此限制。这意味着一年至少续期一次,而 Tomcat 不会自动重载 keystore,续期后必须重启进程。
另外要澄清一个过时说法:CFCA 证书「支持国密 SM2」不等于「Tomcat 能跑 SM2」。Apache Tomcat 官方版本与 SunJSSE 均不支持 SM2/SM3/SM4 密码套件,国密必须通过国密网关或改造版 TLS 栈落地,详见第七节。
二、部署前的文件准备:校验、拼链与生成 PKCS12
CFCA 交付压缩包通常包含:server.crt(服务器证书)、intermediate.crt(中间 CA)、root.crt(根 CA)、server.key(私钥)。先做三件事。
(1)确认证书主体、有效期、SAN 与私钥是否匹配:
# 查看主体、签发者、有效期、SAN
openssl x509 -in server.crt -noout -subject -issuer -dates -ext subjectAltName
# RSA 证书比对模数(两条命令输出必须一致)
openssl x509 -in server.crt -noout -modulus | openssl md5
openssl rsa -in server.key -noout -modulus | openssl md5
# ECC 证书没有 modulus,改比公钥指纹
openssl x509 -in server.crt -noout -pubkey | openssl md5
openssl pkey -in server.key -pubout | openssl md5
(2)拼装完整证书链,顺序为叶子 → 中间 → 根(根可选但建议带上):
cat server.crt intermediate.crt > fullchain.pem
grep -c "BEGIN CERTIFICATE" fullchain.pem # 期望输出 2 或 3
(3)生成 Tomcat 可直接使用的 PKCS12:
openssl pkcs12 -export
-in fullchain.pem
-inkey server.key
-name cfca-tomcat
-out /opt/ssl/example.com.pfx
-keypbe AES-256-CBC -certpbe AES-256-CBC -macalg SHA256
-passout pass:'Str0ng@Passw0rd'
-keypbe/-certpbe/-macalg 三个参数是关键:JDK 8u301+ 与 JDK 11+ 支持 AES-256-CBC;若目标 JDK 更老(8u301 以前),改用 -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -macalg SHA1,否则启动时报 keystore password was incorrect。
(4)验证产物并收紧权限:
openssl pkcs12 -in /opt/ssl/example.com.pfx -nokeys -noout -passin pass:'Str0ng@Passw0rd'
keytool -list -v -keystore /opt/ssl/example.com.pfx -storetype PKCS12 -storepass 'Str0ng@Passw0rd'
chown tomcat:tomcat /opt/ssl/example.com.pfx && chmod 600 /opt/ssl/example.com.pfx
keytool 输出中应满足:Alias name 为 cfca-tomcat、Entry type 为 PrivateKeyEntry、Certificate chain length 为 2 或 3。链长度只有 1 说明打包时漏了中间证书,回到第(2)步重做。
三、Tomcat 8.5/9/10 标准配置:SSLHostConfig + PKCS12
编辑 $CATALINA_BASE/conf/server.xml,把原有 8443 Connector 整段替换(旧的注释掉):
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="200" SSLEnabled="true" scheme="https" secure="true">
<SSLHostConfig protocols="TLSv1.2,TLSv1.3"
honorCipherOrder="true"
ciphers="TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256">
<Certificate certificateKeystoreFile="/opt/ssl/example.com.pfx"
certificateKeystorePassword="Str0ng@Passw0rd"
certificateKeystoreType="PKCS12"
certificateKeyAlias="cfca-tomcat" />
</SSLHostConfig>
</Connector>
配置要点:
protocols只写TLSv1.2,TLSv1.3,显式禁用 TLS1.0/1.1,满足等保 2.0 三级与 PCI DSS 要求;TLS 1.3 需要 JDK 8u261+ 或 JDK 11+,低版本 JDK 即使配了也会被忽略。certificateKeyAlias在 PFX 只有一个私钥条目时可省略;有多个条目时必须指定,否则 Tomcat 取第一个 key entry,可能取错证书。- 直接用 443 端口时把 port 改为 443(Linux 下需 root 或
setcap 'cap_net_bind_service=+ep' $JAVA_HOME/bin/java)。 - 多域名/SNI:一个 Connector 下挂多个
<SSLHostConfig hostName="a.example.com">,并用defaultSSLHostConfigName指定默认站点。 - Tomcat 10.1 起 Servlet API 包名变为 jakarta.*,但 server.xml 中 SSL 相关属性与 9.0 完全一致,无需改动证书配置。
改完执行重启并观察日志:
$CATALINA_HOME/bin/shutdown.sh
$CATALINA_HOME/bin/startup.sh
tail -f $CATALINA_HOME/logs/catalina.out | grep -i -E "ssl|https|connector"
日志出现 Starting ProtocolHandler ["https-jsse-nio-8443"] 才算监听成功;若出现 Failed to initialize end point associated with ProtocolHandler,基本是密码或别名错,直接跳到第六节。
四、老版本 Tomcat(7/8.0)用 keytool 转 JKS
Tomcat 7 与 8.0 只支持 Connector 上的 keystoreFile 属性,需要先把 PKCS12 转成 JKS:
keytool -importkeystore
-srckeystore /opt/ssl/example.com.pfx -srcstoretype PKCS12 -srcstorepass 'Str0ng@Passw0rd'
-destkeystore /opt/ssl/example.com.jks -deststoretype JKS
-deststorepass 'Jks@Passw0rd' -destkeypass 'Jks@Passw0rd'
-alias cfca-tomcat
三个易错点:
1)必须显式写 -deststoretype JKS。Java 9 起 keytool 默认生成 PKCS12,不加这个参数得到的仍是 pfx,老 Tomcat 读不进去。
2)JKS 格式要求 storepass 与 keypass 一致,不一致会报 keytool error: java.lang.IllegalArgumentException: password can't be different。
3)转换后核对条目:keytool -list -keystore /opt/ssl/example.com.jks -storepass 'Jks@Passw0rd',应显示 PrivateKeyEntry 且链长度 ≥2。
Tomcat 7 的 server.xml 写法:
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
keystoreFile="/opt/ssl/example.com.jks"
keystorePass="Jks@Passw0rd"
keystoreType="JKS"
clientAuth="false"
sslEnabledProtocols="TLSv1.2"
ciphers="TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"/>
Tomcat 8.0 可用 sslProtocol="TLSv1.2"。需要注意:Tomcat 7 已于 2021-03-31 结束支持、8.0 于 2018 年结束支持,两者都不支持 TLS 1.3,存在合规风险。建议至少升级到 8.5.x / 9.0.x 最新分支,升级时只需把旧 Connector 换成第三节的 SSLHostConfig 写法,证书文件本身不用动,JKS 也能继续被 8.5/9.0 读取。
五、格式与版本对比:选哪种组合最省事
先看证书载体格式的对比,这决定了你要不要做转换:
| 格式 | Tomcat 原生支持 | 含私钥 | 含中间证书 | 跨平台性 | 推荐场景 |
|---|---|---|---|---|---|
| PKCS12 (.pfx/.p12) | 8.5+ 直接支持,7/8.0 需转换 | 是 | 导出时决定 | 好(Java/OpenSSL/Windows 通用) | 首选,新部署一律用这个 |
| JKS (.jks) | 全版本支持 | 是 | 是 | 差(Java 私有格式) | 仅 Tomcat 7/8.0 遗留系统 |
| PEM (fullchain + key) | 不支持 | 分开存放 | 是 | 最好(Nginx/Apache) | Nginx 前端卸载 TLS,Tomcat 走内网 HTTP |
| DER (.cer/.crt) | 不能单独使用 | 否 | 否 | 一般 | 仅用于导入 cacerts 信任库 |
再看 Tomcat 版本与配置方式、协议能力的对应关系:
| Tomcat 版本 | Connector 配置方式 | TLS 1.3 | JDK 要求 | 维护状态 |
|---|---|---|---|---|
| 7.0.x | keystoreFile/keystorePass | 否 | JDK 7/8 | 已停止支持 |
| 8.0.x | keystoreFile/keystorePass | 否 | JDK 7/8 | 已停止支持 |
| 8.5.x | SSLHostConfig + Certificate(旧属性弃用) | 是(JDK 8u261+) | JDK 7+ | 维护中 |
| 9.0.x | SSLHostConfig + Certificate | 是 | JDK 8+ | 维护中 |
| 10.1.x / 11.x | SSLHostConfig + Certificate(jakarta 命名空间) | 是 | JDK 11/17+ | 维护中 |
算法与有效期补充:CFCA 国际算法证书单张最长 398 天(CA/B Forum 规则,Let’s Encrypt 为 90 天),到期必须续签换证;国密 SM2 证书有效期同理,且浏览器侧需国密浏览器才能识别。密钥强度建议 RSA ≥2048 位、ECC 用 P-256。
选型结论:Tomcat 8.5+ 一律用 PKCS12 + SSLHostConfig;若前端已有 Nginx/SLB 做 TLS 卸载,证书装前端、Tomcat 只跑 HTTP,能省掉每次续期重启 Tomcat 的运维成本,但内网链路要单独做访问控制。
六、常见错误排查:8 个真实报错与修复
报错 1:java.io.IOException: Keystore was tampered with, or password was incorrect
原因:密码含 & 等特殊字符被 XML 解析截断,或 PFX 用了 JDK 不支持的 PBE 算法。修复:server.xml 中把 & 写成 &;或按第二节用 AES-256-CBC 重新导出。
报错 2:java.lang.IllegalArgumentException: Alias name [cfca-tomcat] does not identify a key entry
原因:certificateKeyAlias 指向了证书条目而非私钥条目。修复:keytool -list -keystore x.pfx -storetype PKCS12 -storepass xxx 找到 PrivateKeyEntry 对应的 alias,改过来或删除该属性。
报错 3:javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
原因:服务端未下发中间证书,客户端无法构建信任链。修复:确认 PKCS12 中链长度 ≥2,重做第二节的拼链与导出。
报错 4:curl: (60) SSL certificate problem: unable to get local issuer certificate
原因同上,可用 curl --cacert /path/cfca-root.crt -vI https://www.example.com 验证根证书是否正确。
报错 5:java.security.cert.CertificateException: No subject alternative names present
原因:证书 SAN 不含客户端访问的域名或 IP。修复:重新签发,把域名和 IP 一并写入 SAN,不要依赖 CN 字段。
报错 6:浏览器 ERR_SSL_VERSION_OR_CIPHER_MISMATCH / ERR_SSL_PROTOCOL_ERROR
原因:protocols 与客户端能力不匹配,例如只开 TLSv1.3 而客户端只支持 1.2。修复:protocols="TLSv1.2,TLSv1.3",并检查 ciphers 中是否保留了客户端可用的套件。
报错 7:keytool error: java.io.IOException: keystore password was incorrect
原因:JDK 18+ 对 PKCS12 密码校验更严格,或老 JDK 读不了 AES-256-CBC。修复:用与目标 JDK 匹配的 PBE 参数重新导出,并在目标机器上用同版本 keytool 复验。
报错 8:续期后浏览器仍显示旧证书
原因:Tomcat 不会热加载 keystore,且配置可能仍指向旧文件。修复:bin/shutdown.sh && bin/startup.sh;用 readlink -f 确认软链接指向新文件;再执行 openssl s_client -connect 127.0.0.1:8443 -servername www.example.com | openssl x509 -noout -dates 复核 notAfter。
排查顺序建议:先用 keytool 看 keystore 里的链 → 再用 openssl s_client 看服务端实际下发 → 最后在客户端侧复现。三段定位可以覆盖 90% 的握手问题。
七、国密 SM2 双算法的正确落地方式
很多项目在选型时看到「CFCA 支持 SM2 双算法」,就直接把 SM2 证书往 Tomcat 里塞,结果启动即失败。原因很明确:Apache Tomcat 官方发行版与 JDK 自带的 SunJSSE 都不实现 SM2/SM3/SM4 TLS 密码套件(如 ECDHE-SM2-SM4-CBC-SM3),certificateKeystoreType 无论填 PKCS12 还是 JKS 都解决不了协议栈缺失的问题。
可行的落地方式有两种:
方案 A(推荐):国密网关 + 后端 Tomcat。在 Tomcat 前面部署支持国密的 TLS 网关,如基于铜锁(Tongsuo)编译的 Nginx、CFCA 国密网关、或硬件密码机的 SSL 卸载模块。网关侧配置双证书(SM2 签名证书 + SM2 加密证书),按 ClientHello 的密码套件分流:国际算法走 RSA/ECC 证书,国密算法走 SM2 双证书,后端统一转发到 Tomcat 的 HTTP 端口。这样 Tomcat 完全不用改,证书续期也只动网关。
# 用铜锁版 openssl 验证国密握手(系统自带 openssl 通常不支持)
/usr/local/tongsuo/bin/openssl s_client -connect www.example.com:443
-servername www.example.com -tls1_2 -cipher ECDHE-SM2-SM4-CBC-SM3 -showcerts
方案 B:改造 JSSE。引入 BouncyCastle 的 SM 算法提供者并替换 Tomcat 的 SSLImplementation,工作量集中在自定义 Provider、证书解析与 CipherSuite 注册,升级 Tomcat 或 JDK 时极易回退失效,除非有强定制需求,一般不建议。
还有两点必须说清:一是双算法不要求同端口同进程,国际算法用 443、国密用网关的另一入口是最稳妥的工程做法;二是如果项目只要求国际算法合规(等保、PCI DSS),完全不需要引入国密改造,按第三、四节部署 RSA/ECC 证书即可,强行上 SM2 反而增加故障面。
八、效果验证:openssl、curl、Java 三路确认
配置完成后不要只看浏览器绿锁,按下面四步做完整验证。
(1)服务端链路验证:
openssl s_client -connect 127.0.0.1:8443 -servername www.example.com
-showcerts -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null
关注三点:输出包含 Verify return code: 0 (ok);subject= 是 www.example.com;-showcerts 打印的证书段数为 2~3。若返回 21 (unable to verify the first certificate),说明缺中间证书。
(2)协议与套件枚举:
nmap --script ssl-enum-ciphers -p 8443 127.0.0.1
openssl s_client -connect 127.0.0.1:8443 -tls1_1 </dev/null | head -3 # 应握手失败
确认列表中不含 TLSv1.0/1.1、RC4、3DES。
(3)HTTP 层验证:
curl -vI https://www.example.com --resolve www.example.com:443:127.0.0.1
期望看到 SSL certificate verify ok. 与 HTTP/1.1 200。
(4)Java 客户端验证(最接近小程序/APP 的真实场景):
java -Djavax.net.debug=ssl:handshake -cp app.jar com.example.HttpsTest
日志中应出现 ServerHello, TLSv1.3 或 TLSv1.2、Found trusted certificate,且没有 PKIX path building failed。
(5)到期时间纳入监控:
echo | openssl s_client -connect www.example.com:443 -servername www.example.com 2>/dev/null
| openssl x509 -noout -subject -issuer -dates
把 notAfter 提前 30~45 天写入告警(Prometheus blackbox_exporter 可用 probe_ssl_earliest_cert_expiry 指标)。398 天有效期的证书建议提前 45 天发起续签,续期后按第六节报错 8 的流程重启并复验,形成闭环。
常见问题
不能。Tomcat 的 Certificate 节点只接受 keystore 文件,必须先用 openssl pkcs12 -export 把 fullchain.pem 与 server.key 打包成 PKCS12(.pfx),或用 keytool 转成 JKS,再在 server.xml 中通过 certificateKeystoreFile 指向该文件。
不建议。可把密码写入 conf/catalina.properties 或通过 JVM 参数 -Dssl.keystore.pass 传入,server.xml 中用 ${ssl.keystore.pass} 引用,再把配置文件权限设为 600 且仅 tomcat 用户可读,避免配置随代码库泄露。
必须。Tomcat 的 SSLHostConfig 不会热加载 keystore,即使新文件已覆盖旧文件,进程内仍是旧证书。执行 shutdown.sh 再 startup.sh,并用 openssl s_client 复核 notAfter 是否更新。
正常。按 CA/Browser Forum 规则,2020-09-01 起公开信任证书单张有效期上限为 398 天,签发时刻起算扣掉签发耗时,实际剩余 396~397 天。续期需重新签发,不能延长原证书。
不能。Apache Tomcat 与 SunJSSE 均不支持 SM2/SM3/SM4 TLS 套件,装进去会握手失败。正确做法是在前端部署铜锁版 Nginx 或国密网关做双证书卸载,后端 Tomcat 继续用 HTTP 或国际算法证书。