跳到主要内容
Tomcat

Tomcat 配置 SSL 证书完整教程:PFX/PKCS12 与 JKS 实操、排错与验证

1. 问题背景与根因:为什么 Tomcat 的 8443 仍然握手失败

Tomcat 配置 SSL 后打不开 8443,常见根因并不是证书本身,而是密钥库类型、密码、证书链、SAN 与 Connector 写法不匹配。Tomcat 8.5 以后推荐使用 SSLHostConfig,旧的 keystoreFile/keystorePass 写法已废弃;若仍混用,重启后可能直接忽略证书。另一个高频问题是有效期:公共信任 TLS 证书最长 398 天,Let’s Encrypt 为 90 天,证书过期后浏览器报 NET::ERR_CERT_DATE_INVALID。还有 PFX 的 store password 与 key password 不一致、JKS 只导入叶子证书缺少中间证书、证书 SAN 不含访问域名、Java 版本过低导致 TLS 1.3 握手失败等。排查顺序应是:先看 catalina.out 的 Keystore/SSL 异常,再用 openssl 验证证书链与 SAN,最后检查 server.xml 的 Connector 与端口。不要一上来重签证书。

快速定位命令:grep -i -E 'ssl|keystore|certificate|handshake' /var/log/tomcat/catalina.out | tail -n 50。若日志出现 Keystore was tampered with,先查密码;出现 No subject alternative names present,先查 SAN;出现 PKIX path building failed,先查中间证书。

2. 准备工作:确认证书格式、SAN、有效期与文件权限

准备四个对象:PFX/PKCS12 文件、导出密码、fullchain.pem、privkey.pem。先检查证书主题、SAN 和有效期,避免把旧证书或错误域名配进 Tomcat。

openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
openssl pkcs12 -in example.com.pfx -info -noout -passin pass:'PFX密码'
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout

输出中必须包含实际访问域名,例如 DNS:example.com、DNS:www.example.com;有效期应覆盖当前日期。公共信任证书最长 398 天,Let’s Encrypt 为 90 天,临近到期先续期再排错。创建目录并授权给 Tomcat 运行用户,避免 No such file 或权限拒绝:

sudo install -d -m 750 -o tomcat -g tomcat /opt/ssl
sudo install -m 640 -o tomcat -g tomcat example.com.pfx /opt/ssl/example.com.pfx
sudo -u tomcat test -r /opt/ssl/example.com.pfx && echo readable
java -version

Tomcat 9 通常运行在 Java 8 及以上,Tomcat 10.1/11 要求 Java 11 及以上;TLS 1.3 与 JDK 版本相关,旧 JDK 只支持 TLS 1.2。确认 server.xml 路径,常见为 /opt/tomcat/conf/server.xml 或 /etc/tomcat/server.xml。

3. 方式一:PFX/PKCS12 配置 Tomcat(推荐)

PFX 本质是 PKCS12,Tomcat 8.5 以上可直接读取,不需要先转 JKS。编辑 server.xml,在 Service 内增加或替换 8443 Connector。注意使用 SSLHostConfig,证书密码放在 Certificate 上,store 密码与 key 密码不同时补 certificateKeyPassword。

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

如果 PFX 导出时私钥密码与库密码不同,增加 certificateKeyPassword='私钥密码';如果文件有多个别名,增加 certificateKeyAlias='别名'。保存后重启并观察日志:

sudo systemctl restart tomcat
sudo tail -n 100 /var/log/tomcat/catalina.out
ss -lntp | grep 8443

看到 Tomcat started 且 8443 处于 LISTEN 才算启动成功。若日志提示 Keystore was tampered with,优先核对 certificateKeystorePassword;若提示 No such file,检查 Tomcat 用户对 /opt/ssl 的读权限。PFX 方案少一次格式转换,证书链通常随 PKCS12 一起导入,是当前更省事的做法。

4. 方式二:JKS 配置 Tomcat 与 keytool 导入证书链

JKS 适合旧系统或企业统一密钥库。最稳妥的做法不是手工逐个导入中间证书,而是先确保 PKCS12 内含完整链,再整体转换为 JKS。转换与检查命令如下:

keytool -importkeystore -srckeystore /opt/ssl/example.com.pfx -srcstoretype PKCS12 -srcstorepass 'PFX密码' -destkeystore /opt/ssl/example.com.jks -deststoretype JKS -deststorepass 'JKS密码' -destkeypass 'JKS密码' -noprompt
keytool -list -v -keystore /opt/ssl/example.com.jks -storepass 'JKS密码' | grep -E 'Alias name|Certificate chain length|Valid from'

若 PFX 缺少中间证书,先用私钥和 fullchain 重新导出 PKCS12,再转 JKS:

openssl pkcs12 -export -out /opt/ssl/full.pfx -inkey privkey.pem -in fullchain.pem -passout pass:'新PFX密码'
keytool -importkeystore -srckeystore /opt/ssl/full.pfx -srcstoretype PKCS12 -srcstorepass '新PFX密码' -destkeystore /opt/ssl/example.com.jks -deststoretype JKS -deststorepass 'JKS密码' -destkeypass 'JKS密码' -noprompt

server.xml 中把类型改为 JKS:

<Certificate certificateKeystoreFile='/opt/ssl/example.com.jks'
             certificateKeystorePassword='JKS密码'
             certificateKeystoreType='JKS' />

注意:只把 intermediate.crt 用 keytool -importcert 导入为独立别名,通常不会自动附加到私钥条目,服务端仍可能只发送叶子证书。判断标准是 keytool -list -v 中私钥条目的 Certificate chain length 至少为 2,包含叶子证书和中间证书。改完重启 Tomcat,再用 openssl 验证链。

5. 配置示例:HTTP 跳转 HTTPS 与 TLS 加固

完整配置通常保留 8080 作为 HTTP,并让 8443 处理 HTTPS。8080 Connector 设置 redirectPort=’8443’,应用再用 security-constraint 或反向代理统一跳转。下面示例同时限制协议为 TLS 1.2/1.3,并给出 TLS 1.2 的 ECDHE 套件;TLS 1.3 套件由 JDK 管理,不要硬套旧名称。

<Connector port='8080' protocol='org.apache.coyote.http11.Http11NioProtocol'
            maxThreads='200' redirectPort='8443' />
<Connector port='8443' protocol='org.apache.coyote.http11.Http11NioProtocol'
            maxThreads='150' SSLEnabled='true' scheme='https' secure='true'>
  <SSLHostConfig protocols='TLSv1.2,TLSv1.3'
                 ciphers='TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256'>
    <Certificate certificateKeystoreFile='/opt/ssl/example.com.pfx'
                 certificateKeystorePassword='PFX密码'
                 certificateKeystoreType='PKCS12' />
  </SSLHostConfig>
</Connector>

若使用 JKS,只改 certificateKeystoreFile 和 certificateKeystoreType 即可。不要把 protocols 写成 SSLv3 或只写 TLSv1;现代浏览器会直接报 ERR_SSL_VERSION_OR_CIPHER_MISMATCH。修改后执行 sudo systemctl restart tomcat,再用 ss -lntp | grep -E '8080|8443' 确认端口。生产环境建议在 Tomcat 前放 Nginx/HAProxy 卸载 TLS,Tomcat 只监听 127.0.0.1:8080;若 Tomcat 直接对外,务必限制 8443 安全组并关闭 8080 公网访问。

6. JKS 与 PFX/PKCS12 对比:怎么选

两者都能让 Tomcat 提供 HTTPS,差别主要在格式、链处理和运维习惯。PFX 是 PKCS12 容器,通常包含私钥、叶子证书和中间证书;JKS 是 Java 传统密钥库,需要 keytool 管理。选择时不要只看扩展名,要看 certificateKeystoreType 与实际内容是否一致。

维度 PFX/PKCS12 JKS
格式本质 PKCS12 容器,跨平台通用 Java KeyStore,Java 生态传统格式
Tomcat 类型 certificateKeystoreType=’PKCS12′ certificateKeystoreType=’JKS’
证书链 通常随导出文件携带完整链 需确保私钥条目 chain length 完整
密码 库密码与私钥密码可不同 storepass 与 keypass 需分别核对
转换 可直接使用,推荐优先 用 keytool -importkeystore 转换
适用场景 新部署、证书平台直接下载 PFX 旧系统、统一 JKS 密钥库、合规要求

结论:Tomcat 8.5 及以上优先 PFX/PKCS12,少一次转换就少一次链丢失风险;必须用 JKS 时,用包含 fullchain 的 PKCS12 整体转换,并用 keytool -list -v 验证私钥条目链长度。无论选哪种,证书最长有效期 398 天、Let’s Encrypt 90 天的续期节奏都不会变,续期后要更新密钥库并重启 Tomcat。

7. 常见错误排查:真实报错与处理

报错 1:java.io.IOException: Keystore was tampered with, or password was incorrect。原因是 certificateKeystorePassword 与密钥库实际密码不一致,或 JKS 的 keypass 与 storepass 不同。处理:用 keytool -list -keystore 文件 -storepass 密码 验证;PFX 私钥密码不同时补 certificateKeyPassword。

报错 2:java.security.cert.CertificateException: No subject alternative names present。证书没有 SAN 或 SAN 不含访问域名,现代浏览器不再接受 CN 匹配。处理:重新签发含 DNS:example.com、DNS:www.example.com 的证书,不要改 hosts 掩盖。

报错 3:SSLHandshakeException: PKIX path building failed。服务端链缺中间证书,或客户端 truststore 不信任该 CA。处理:把 fullchain 放入密钥库,确保 chain length 大于等于 2;用 openssl s_client 看 Verify return code 是否为 0。

报错 4:ERR_SSL_VERSION_OR_CIPHER_MISMATCH。协议或套件不匹配,常见于只开 TLSv1.3 却用旧客户端,或 ciphers 写了无效名称。处理:protocols 保留 TLSv1.2,TLSv1.3,删除不支持的套件,重启后复测。

报错 5:java.net.BindException: Address already in use 或 8443 不监听。端口被占用或 Connector 未加载。处理:ss -lntp | grep 8443 查占用,检查 server.xml 是否改在正确 Service,查看 catalina.out 启动行。

8. 效果验证:openssl、curl、keytool 与浏览器四层确认

配置完成后不要只看端口通不通,要验证证书链、主机名、协议和有效期。第一层用 openssl 看握手与链:

openssl s_client -connect 127.0.0.1:8443 -servername example.com -showcerts </dev/null 2>/dev/null
openssl s_client -connect 127.0.0.1:8443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

输出中 Verify return code 应为 0 (ok);若为 21 (unable to verify the first certificate),说明中间证书缺失;若为 62,通常是主机名不匹配。第二层用 curl 验证 HTTP 状态与证书:

curl -Iv https://example.com:8443 --resolve example.com:8443:127.0.0.1
curl -I http://example.com:8080 --resolve example.com:8080:127.0.0.1

第三层用 keytool 检查密钥库链长度:keytool -list -v -keystore /opt/ssl/example.com.jks -storepass 'JKS密码' | grep -E 'Alias name|Certificate chain length|Valid from'。第四层用浏览器访问 https://example.com:8443,确认锁标志、证书颁发者和有效期;公网服务再用 SSL Labs 或 testssl.sh 检查 TLS 1.2/1.3、HSTS 与链。最后确认续期任务:公共证书最长 398 天,Let’s Encrypt 90 天,到期前自动替换并重启 Tomcat。

常见问题

优先用 PFX/PKCS12。Tomcat 8.5 及以上在 SSLHostConfig 中设置 certificateKeystoreType=’PKCS12′ 即可;JKS 适合旧系统或统一密钥库。转换后必须用 keytool -list -v 检查私钥条目的 Certificate chain length,至少包含叶子证书和中间证书。


公共信任 TLS 证书最长有效期为 398 天,Let’s Encrypt 免费证书为 90 天。到期前应自动续期,并在续期后重启或热加载 Tomcat;仅替换文件不重启,旧证书仍会被 JVM 缓存。


先查 SAN 与链。用 openssl x509 -in fullchain.pem -noout -text 查看 Subject Alternative Name 是否含访问域名;再用 openssl s_client 看 Verify return code。若为 21 或 20,通常是中间证书缺失,需把 fullchain 放入密钥库。


修改 server.xml 后必须重启 Tomcat,检查是否改在正确的 Connector 与 SSLHostConfig 上;查看 catalina.out 是否有 Keystore was tampered with 或 No such file。若用 systemd,确认服务名与配置路径一致。


不能只把中间证书作为 trustedCertEntry 导入。应使用包含私钥和完整 fullchain 的 PEM 重新导出 PKCS12,再用 keytool -importkeystore 转 JKS,确保私钥条目的 chain length 大于等于 2。


Tomcat 9/10/11 在支持 TLS 1.3 的 JDK 上可用。SSLHostConfig 设置 protocols=’TLSv1.2,TLSv1.3′ 可兼容新旧客户端;若只留 TLSv1.3,旧浏览器和 Java 8 客户端可能握手失败。

内容审核

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