跳到主要内容
Tomcat

Tomcat 配置 SSL 证书完整教程:PFX/PKCS12 与 JKS 实战(含排错与验证)

问题背景与根因:Tomcat 启用 SSL 后为什么仍握手失败

Tomcat 配置 SSL 证书的本质,是把 Connector 从 HTTP 端点切换为 TLS 端点。实际故障很少是“证书没上传”,而是格式、密码、别名、证书链、SNI、端口和协议不匹配。旧教程常用 keystoreFile/keystorePass,Tomcat 8.5/9/10 更推荐 SSLHostConfig 与 Certificate;PKCS12(PFX)已成为 Java 默认 keystore 类型,JKS 仍常见于历史系统。公共可信 TLS 证书有效期自 2020-09-01 起最长 398 天,Let’s Encrypt 为 90 天,过期或链不完整会触发浏览器 NET::ERR_CERT_DATE_INVALID、curl (60) unable to get local issuer certificate。常见根因包括:PFX 密码错误或私钥密码与 keystore 密码不同;JKS 只导入叶证书,缺少中间 CA;Connector 仍写 protocol=’HTTP/1.1′ 或端口未监听;证书 SAN 不含访问域名;Tomcat 运行用户无读权限。先执行 java -version 和 catalina.sh version 确认版本,再按 PFX 或 JKS 路线操作。

准备工作:CSR、证书链与有效期核对

生成 CSR 时 SAN 必须覆盖 example.com 和 www.example.com。可执行:

openssl req -new -newkey rsa:2048 -nodes -keyout example.com.key -out example.com.csr -subj '/CN=example.com' -addext 'subjectAltName=DNS:example.com,DNS:www.example.com'

校验 CSR:

openssl req -in example.com.csr -noout -text | grep -A2 'Subject Alternative Name'

收到证书后确认 fullchain.pem 包含叶证书和中间 CA,根 CA 不必放服务器。检查有效期与 SAN:

openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName

注意公共 TLS 证书最长 398 天,Let’s Encrypt 为 90 天,需用 cron 或 certbot renew 自动续期。PFX 打包命令:

openssl pkcs12 -export -in fullchain.pem -inkey example.com.key -out example.com.pfx -name tomcat -passout pass:changeit

查看 PFX 内容:

openssl pkcs12 -in example.com.pfx -info -noout -passin pass:changeit

若报 Mac verify error: invalid password,说明密码错。权限设置为 chown tomcat:tomcat /opt/ssl/example.com.pfx && chmod 640 /opt/ssl/example.com.pfx,并备份 server.xml。

完整实操步骤一:PFX/PKCS12 直接配置(推荐)

PFX 路线转换最少。把 example.com.pfx 放到 /opt/ssl,先确认别名和链长度:

keytool -list -v -keystore /opt/ssl/example.com.pfx -storetype PKCS12 -storepass changeit | grep -E 'Alias name|Entry type|Certificate chain length'

编辑 $CATALINA_BASE/conf/server.xml,在 Service 内加入 Connector。Tomcat 9/10 推荐写法:

<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='changeit'
                 certificateKeystoreType='PKCS12'
                 certificateKeyAlias='tomcat' />
  </SSLHostConfig>
</Connector>

若私钥密码与 keystore 密码不同,增加 certificateKeyPassword='私钥密码'。不要同时保留旧 keystoreFile 属性。重启并看日志:

systemctl restart tomcat
tail -n 80 /opt/tomcat/logs/catalina.out

看到 Starting ProtocolHandler ['https-jsse-nio-8443'] 表示监听成功。检查端口和握手:

ss -lntp | grep 8443
openssl s_client -connect 127.0.0.1:8443 -servername example.com -showcerts </dev/null

若报 Keystore was tampered with, or password was incorrect,优先查密码和 storetype。PFX 推荐原因:PKCS12 是标准格式,Java 9+ 默认,跨平台,Tomcat 可直接读取。

完整实操步骤二:JKS 方式转换与证书链导入

JKS 适合旧 Tomcat 或统一 JKS 运维。不要手工只导入叶证书。用 keytool 从 PFX 转 JKS,保留私钥和链:

keytool -importkeystore -srckeystore /opt/ssl/example.com.pfx -srcstoretype PKCS12 -srcstorepass changeit -destkeystore /opt/ssl/example.com.jks -deststoretype JKS -deststorepass changeit -destkeypass changeit -alias tomcat

检查链长度:

keytool -list -v -keystore /opt/ssl/example.com.jks -storepass changeit | grep -E 'Alias name|Entry type|Certificate chain length|Valid from'

若只有 PEM,先按上一节打包 PFX 再转 JKS。若链缺失,可用 keytool -importcert -alias intermediate -file intermediate.crt -keystore /opt/ssl/example.com.jks -storepass changeit -noprompt 导入中间 CA;但导入到独立别名只增加可信证书,不会自动补到私钥条目链。正确做法是确保 fullchain.pem 含中间 CA 后重新 pkcs12 -export 再转 JKS。Tomcat 配置:

<Certificate certificateKeystoreFile='/opt/ssl/example.com.jks'
             certificateKeystorePassword='changeit'
             certificateKeystoreType='JKS'
             certificateKeyAlias='tomcat' />

若 key 密码不同,加 certificateKeyPassword。重启后验证。JKS 是 Java 私有格式,keytool 可管理;PKCS12 更通用。不要用 keytool -genkeypair 生成生产证书。

配置示例:server.xml 完整 HTTPS Connector 与 HTTP 跳转

下面片段同时保留 8080 并设置 redirectPort,应用层可用 security-constraint 跳转 HTTPS:

<Connector port='8080' protocol='HTTP/1.1' connectionTimeout='20000' 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'>
    <Certificate certificateKeystoreFile='/opt/ssl/example.com.pfx'
                 certificateKeystorePassword='changeit'
                 certificateKeystoreType='PKCS12'
                 certificateKeyAlias='tomcat' />
  </SSLHostConfig>
</Connector>

说明:protocols 不要写 SSLv3;TLSv1.0/1.1 已淘汰。若需 HSTS,可在 web.xml 增加 header 或由反向代理设置。修改后先做 XML 校验:

xmllint --noout /opt/tomcat/conf/server.xml
systemctl restart tomcat
journalctl -u tomcat -n 100 --no-pager

不要继续使用已废弃的 keystoreFile/keystorePass 混搭 SSLHostConfig,否则容易出现配置被忽略。HTTP 自动跳转 HTTPS 建议在应用 web.xml 配置 security-constraint,或在 Nginx 层 301。生产环境还应限制 8443 安全组,只开放必要来源。

JKS 与 PFX/PKCS12 对比表

项目 PFX/PKCS12 JKS
标准与跨平台 PKCS#12 标准,OpenSSL/Java/Windows 通用 Java 私有格式,跨平台性较弱
Java 默认 Java 9+ 默认 keystore 类型 历史默认,旧系统常见
Tomcat 类型 certificateKeystoreType=’PKCS12′ certificateKeystoreType=’JKS’
密码管理 keystore 密码与 key 密码可不同 keystore 密码与 key 密码可不同
证书链 导出时包含 fullchain 即可 转换时保留链,避免只导叶证书
常用命令 openssl pkcs12 -info keytool -list -v
推荐场景 新部署、跨平台迁移、Tomcat 9/10 旧 Tomcat、既有 JKS 运维体系

选择原则:新项目优先 PFX/PKCS12,减少转换步骤;存量系统若已统一 JKS,可继续使用,但必须用 keytool -list -v 确认 Certificate chain length 大于 1。迁移时先备份原 keystore,再改 server.xml,回滚成本最低。无论哪种格式,Tomcat 运行用户都必须有读权限。

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

1. java.io.IOException: Keystore was tampered with, or password was incorrect:storepass 错或 storetype 错。用 keytool -list -storetype PKCS12 -keystore example.com.pfx -storepass changeit 验证。2. java.security.UnrecoverableKeyException: Cannot recover key:私钥密码不同,增加 certificateKeyPassword。3. alias not found: tomcat:别名不存在,执行 keytool -list -v 查 Alias name。4. PKIX path building failed / curl: (60) unable to get local issuer certificate:链缺中间 CA,用 fullchain.pem 重新打包。5. SSL_ERROR_NO_CYPHER_OVERLAP 或 ERR_SSL_VERSION_OR_CIPHER_MISMATCH:协议不匹配,检查 protocols='TLSv1.2,TLSv1.3',并用 openssl s_client -tls1_2 测试。6. java.net.BindException: Address already in use:端口占用,执行 ss -lntp | grep 8443。7. No subject alternative names present:证书 SAN 不含域名,需重签。8. Permission denied:Tomcat 用户无读权限,执行 chmod 640 并检查 SELinux。

效果验证:命令行、浏览器与证书链检查

先看端口:ss -lntp | grep 8443。再验证证书链和主机名:

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

用 curl 验证 HTTP 状态和证书:

curl -vI https://example.com:8443 --resolve example.com:8443:127.0.0.1

检查 TLS 版本:

openssl s_client -connect example.com:8443 -servername example.com -tls1_2 </dev/null
openssl s_client -connect example.com:8443 -servername example.com -tls1_3 </dev/null

浏览器打开 https://example.com:8443,F12 的 Security 面板应显示证书有效、链完整、SAN 匹配。日志中搜索 https-jsse-nio-8443 和 SEVERE。生产环境再用 nmap --script ssl-enum-ciphers -p 8443 example.com 检查弱套件。若 curl 成功但浏览器失败,优先检查 SNI、系统时间、证书链和中间 CA。

常见问题

新部署优先 PFX/PKCS12,Tomcat 9/10 直接写 certificateKeystoreType=’PKCS12’,跨平台且转换少;旧系统统一 JKS 也可用,关键是证书链完整、别名和密码正确。

certificateKeystorePassword 填 PFX 容器密码,certificateKeyPassword 填私钥密码;先用 openssl pkcs12 -info 验证,若报 Cannot recover key 就是私钥密码未配置。

让 fullchain.pem 同时包含叶证书和中间 CA,根 CA 不必放服务器;重新执行 openssl pkcs12 -export 或 keytool -importkeystore 转换,不要只导入叶证书。

执行 ss -lntp | grep 8443 查占用进程,停止冲突服务或修改 Connector port;同时检查 firewall-cmd 和云安全组是否放行新端口。

用 certbot renew –deploy-hook 重启 Tomcat,并确认续期后 fullchain.pem 已更新;公共可信 TLS 证书最长 398 天,LE 为 90 天,必须自动化续期。

内容审核

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