跳到主要内容
Tomcat

CFCA SSL 证书 Tomcat 安装部署实战:PKCS12/JKS、国密 SM2 边界与链完整性排查

问题背景与根因:为什么 Tomcat 部署 CFCA 证书常出现“浏览器正常、接口报错”

CFCA(中国金融认证中心)SSL 证书支持国密 SM2 与国际 RSA/ECC 双算法,常见于银行、政务、国企及有国密改造需求的项目。把证书部署到 Tomcat 时,最常见的问题不是“证书没签下来”,而是只部署了叶子证书、PKCS12/JKS 密码不一致、私钥与证书不匹配、用 IP 访问导致 SAN 校验失败,或标准 JSSE 不支持 SM2。Tomcat 8.5+ 推荐使用 SSLHostConfig + PKCS12;老版本 Tomcat 才用 JKS keystore。

另一个容易忽略的根因是有效期。旧资料常写 2 年,实际公开信任 TLS 证书在 2020-09 至 2026-03 最长 398 天,自 2026-03-15 起 CA/B Forum SC-081 将上限缩短为 200 天,2027-03-15 起 100 天,2029-03-15 起 47 天;Let’s Encrypt 常见为 90 天。CFCA 金融/国密证书以合同和 CA 策略为准,部署前先看 notAfter,避免续期窗口判断错误。

建议排查顺序:先用 OpenSSL 校验证书链和私钥,再检查 Tomcat Connector 配置,最后用 openssl s_client、curl、Java 客户端和浏览器四层验证。这样能快速区分“服务端没发完整链”和“客户端信任库缺根”两类问题。

准备证书文件:PFX/PKCS12、JKS 与 fullchain 的取舍

CFCA 通常交付 .pfx/.p12、.cer/.crt、中间证书和密码。Tomcat 8.5+/9/10.1 优先用 PKCS12,因为一个文件同时包含私钥和证书链,配置项少。JKS 适合老 Tomcat 或既有运维体系。若还要给 Nginx、HAProxy、curl、Java 小程序做验证,建议额外导出 PEM 格式的叶子证书、中间链和私钥。

openssl pkcs12 -in example.com.pfx -info -noout
openssl pkcs12 -in example.com.pfx -clcerts -nokeys -out cert.pem
openssl pkcs12 -in example.com.pfx -cacerts -nokeys -out chain.pem
openssl pkcs12 -in example.com.pfx -nocerts -nodes -out key.pem
chmod 600 key.pem
cat cert.pem chain.pem > fullchain.pem

注意 fullchain 顺序必须是“叶子证书在前、中间证书在后”,不要只放中间证书。私钥导出后仅用于临时校验,生产环境应删除或放入权限 600 的目录。若 CFCA 单独给了根证书,保存为 root.pem,后续验证用 root.pem 做信任锚,chain.pem 做中间链。

完整实操:用 OpenSSL 校验证书链、私钥与有效期

先检查证书主题、SAN、签发者和有效期,再验证链和私钥匹配。RSA 证书比较模数;ECC 证书比较公钥 DER 的 MD5。不要只看浏览器绿锁,接口客户端往往更严格。

openssl x509 -in cert.pem -noout -subject -issuer -dates -serial -ext subjectAltName
openssl verify -CAfile root.pem -untrusted chain.pem cert.pem
openssl rsa -in key.pem -noout -modulus | openssl md5
openssl x509 -in cert.pem -noout -modulus | openssl md5

ECC 证书改用:

openssl pkey -in key.pem -pubout -outform DER | openssl md5
openssl x509 -in cert.pem -pubkey -noout | openssl pkey -pubin -outform DER | openssl md5

期望看到 cert.pem: OK,且两次 MD5 完全一致。若报 unable to get local issuer certificate,说明缺根或中间链;若两次 MD5 不同,说明私钥与证书不匹配,必须重新向 CFCA 获取正确文件。再用 openssl crl2pkcs7 -nocrl -certfile chain.pem | openssl pkcs7 -print_certs -noout 查看链中证书数量。

Tomcat 配置示例:8.5+/9/10.1 的 Connector 与 SSLHostConfig

编辑 $CATALINA_HOME/conf/server.xml,在 Service 内保留一个 8443 Connector。Tomcat 8.5+/9/10.1 使用 SSLHostConfig;协议建议启用 TLSv1.3 和 TLSv1.2。证书文件用绝对路径,密码不要放在全局可读文件里。

<Connector port='8443' protocol='org.apache.coyote.http11.Http11NioProtocol'
           maxThreads='200' SSLEnabled='true' scheme='https' secure='true'>
  <SSLHostConfig protocols='TLSv1.3,TLSv1.2'>
    <Certificate certificateKeystoreFile='/opt/ssl/example.com.pfx'
                 certificateKeystorePassword='CHANGE_ME'
                 certificateKeystoreType='PKCS12' />
  </SSLHostConfig>
</Connector>

部署命令示例:

sudo install -m 600 -o tomcat -g tomcat example.com.pfx /opt/ssl/example.com.pfx
sudo systemctl restart tomcat
sudo tail -n 100 /opt/tomcat/logs/catalina.out

如果 Tomcat 前面有 Nginx/负载均衡,还要同步更新前端证书,否则浏览器看到的仍是旧证书。修改 Connector 后必须重启 Tomcat;仅 reload 应用不会重新加载 Connector 证书。Tomcat 10.1 的 SSLHostConfig 写法相同,但应用需使用 Jakarta API。

老版本 Tomcat 与 JKS:keytool 导入、别名与密钥密码

Tomcat 7/8.0 或强制 JKS 的环境,用 keytool 把 PKCS12 导入 JKS。PKCS12 常见 storepass 与 keypass 相同;JKS 可以不同,但配置里的 keystorePass 必须对应 storepass,密钥密码不一致会报 Cannot recover key。

keytool -importkeystore -srckeystore example.com.pfx -srcstoretype PKCS12 
  -srcstorepass 'PFX密码' -destkeystore example.com.jks -deststoretype JKS 
  -deststorepass 'JKS密码' -destkeypass 'JKS密码' -noprompt
keytool -list -v -keystore example.com.jks -storepass 'JKS密码' | grep -E 'Alias|Entry type|Certificate chain length|Owner|Issuer'

老版本 Connector 示例:

<Connector port='8443' protocol='HTTP/1.1' SSLEnabled='true'
           keystoreFile='/opt/ssl/example.com.jks' keystorePass='JKS密码'
           keystoreType='JKS' />

确认 Certificate chain length 大于 1,说明 JKS 中包含中间链。若只有 1,需要把中间证书一并导入。JKS 文件权限设为 600,并确保 Tomcat 运行用户可读。

对比表格:PKCS12、JKS、PEM/fullchain 与 RSA/ECC/SM2 支持边界

格式/算法 Tomcat 配置 优点 注意
PKCS12/PFX certificateKeystoreType='PKCS12' Tomcat 8.5+ 推荐,单文件含私钥和链 密码错误会报 keystore password was incorrect
JKS certificateKeystoreType='JKS' 兼容老 Tomcat 和既有工具链 storepass 与 keypass 可能不同
PEM/fullchain 部分版本可用 certificateFile/certificateKeyFile 便于 Nginx、curl、Java 验证 链顺序必须叶子在前,私钥权限 600
RSA/ECC 标准 JSSE 支持 可直接用 PKCS12/JKS 部署 启用 TLSv1.3/TLSv1.2,禁用弱套件
SM2 标准 Tomcat 默认不支持 满足国密合规 需国密版 Tomcat、Tongsuo/GmSSL Provider 或国密网关,否则报 Unsupported curve: sm2p256v1

选型建议:新项目优先 PKCS12;老系统迁移用 JKS;需要给非 Java 客户端做链验证时额外导出 fullchain.pem。CFCA 双算法证书要确认 Tomcat/JDK 是否具备对应算法能力,不能把 SM2 证书直接塞进标准 JSSE 就期望握手成功。

常见错误排查:真实报错与修复

  • curl: (60) SSL certificate problem: unable to get local issuer certificate:服务端未发送中间链。修复:把 CFCA 中间证书导入 PKCS12/JKS,或让前端使用 fullchain。
  • java.security.cert.CertPathBuilderException: unable to find valid certification path to requested target:Java 信任库缺根/中间证书。修复:keytool -importcert -file chain.pem -alias cfca-ca -keystore truststore.jks,并让客户端加载该 truststore。
  • java.security.cert.CertificateException: No subject alternative names matching IP address 127.0.0.1 found:用 IP 访问但证书 SAN 只有域名。修复:使用域名访问并带 SNI。
  • java.io.IOException: keystore password was incorrect:Connector 密码与 PFX/JKS 不一致。修复:用 openssl pkcs12 -info -noout 或 keytool -list 复核密码。
  • java.security.UnrecoverableKeyException: Cannot recover key:JKS 的 keypass 与 storepass 不同。修复:重新导入时显式指定 -destkeypass。
  • SSLHandshakeException: No appropriate protocol 或 Unsupported curve: sm2p256v1:协议/算法不匹配,SM2 需国密能力。修复:调整 protocols/ciphers,或改用国密 Tomcat/网关。

排查时先执行 openssl s_client -connect 127.0.0.1:8443 -servername example.com -showcerts -CAfile root.pem -untrusted chain.pem -verify_return_error </dev/null。若出现 Verify return code: 21 (unable to verify the first certificate),基本可判定链不完整。

效果验证:openssl、curl、Java 与浏览器四层检查

第一层看端口和进程:ss -lntp | grep 8443。第二层看 TLS 握手和链:

openssl s_client -connect 127.0.0.1:8443 -servername example.com -showcerts 
  -CAfile /opt/ssl/root.pem -untrusted /opt/ssl/chain.pem -verify_return_error </dev/null

期望输出 Verify return code: 0 (ok)。第三层用 curl 验证 HTTP:curl -Iv --cacert /opt/ssl/root.pem https://example.com:8443/,期望 SSL certificate verify ok 和 HTTP 200。第四层用 Java:keytool -printcert -sslserver example.com:8443 查看服务端链;应用自测加 -Djavax.net.debug=ssl:handshake 观察握手。

续期后重点比对 serial 和 notAfter:openssl x509 -in cert.pem -noout -serial -dates,再对线上执行 openssl s_client -connect 127.0.0.1:8443 -servername example.com </dev/null | openssl x509 -noout -serial -dates。若线上仍是旧 serial,说明 Tomcat 未重启或前端未更新。浏览器最后检查 SAN、链完整性和 TLS 版本即可。

常见问题

Tomcat 8.5+/9/10.1 优先用 PKCS12/PFX,配置 certificateKeystoreType=’PKCS12′ 即可;只有老 Tomcat 或运维体系强制 JKS 时再用 keytool 导入。PFX 要注意导出密码与私钥密码一致,文件权限设为 600,避免把密码写进可公开读取的 server.xml。


这是证书链不完整或客户端信任库缺根。让 Tomcat 使用包含中间链的 PKCS12/JKS,并用 keytool -importcert 把 CFCA 根证书和中间证书导入客户端 truststore;再用 openssl s_client -showcerts 确认服务端发送了完整链。


不能。标准 Tomcat 的 JSSE 默认只支持 RSA/ECC,SM2 需要国密版 Tomcat、Tongsuo/GmSSL Provider 或国密网关卸载,否则握手会报 Unsupported curve: sm2p256v1。先确认 Tomcat 与 JDK 的国密能力再部署。


先确认 server.xml 指向新文件且密码正确,然后重启 Tomcat,而不是只 reload 应用;用 openssl s_client -connect 127.0.0.1:8443 -servername 域名 查看 serial 和 notAfter 是否变化。若前面有 Nginx/负载均衡,也要同步更新并重启。


旧资料写 2 年已过时。2020-09 至 2026-03 公开信任 TLS 证书最长 398 天;2026-03-15 起按 CA/B Forum SC-081 缩短为 200 天,2027-03-15 起 100 天,2029-03-15 起 47 天。Let’s Encrypt 常见为 90 天。CFCA 以证书 notAfter 为准。

内容审核

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