跳到主要内容
Tomcat

Sectigo SSL 证书 Tomcat 部署实战:PKCS12 配置、证书链修复与真实报错排查

问题背景:Sectigo 证书在 Tomcat 上“装好了却不生效”的根因

在 Tomcat 上部署 Sectigo(原 Comodo CA)SSL 证书时,最典型的现象是:用 Chrome/Edge 访问 https://example.com:8443 小锁正常,但同一个域名用 curl、Java 客户端、微信小程序或 Android 原生 App 请求时直接握手失败。这类“浏览器正常、程序报错”的问题,九成不是证书本身有毛病,而是证书链、文件格式、Tomcat 配置三者之一出了偏差。

根因可归为四类:

  • 证书链不完整。只把叶子证书 example.com.crt 导进 keystore,没有导入 Sectigo 中间证书(常见为 Sectigo Public Server Authentication CA DV R36、USERTrust RSA Certification Authority)。桌面浏览器会走 AIA(Authority Information Access)自动补链,而 Java 的 PKIX 校验、curl、部分移动端 SDK 不会,于是抛出 unable to find valid certification path to requested target。
  • keystore 类型与密码不匹配。Tomcat 8.5 之后推荐 PKCS12,但大量旧教程仍让读者配 certificateKeystoreType="JKS",或者 PFX 导出密码含 $、& 等特殊字符导致解析失败。
  • Tomcat 版本属性错配。Tomcat 7 及更早版本把 keystoreFile/keystorePass/keystoreType 直接写在 <Connector> 上;Tomcat 8.5+ 改为 <SSLHostConfig> 下的 <Certificate certificateKeystoreFile=...>。两套写法混用不会报错,只会被静默忽略,表现为“配置改了但证书没变”。
  • 有效期认知过时。自 2020-09-01 起,公有 CA 签发的 SSL/TLS 证书最长有效期被限制为 398 天;CA/Browser Forum 已通过 SC-081,2026-03-15 起降为 200 天、2027-03-15 起降为 100 天。Let’s Encrypt 仍为 90 天并已提供 6 天短周期证书。因此“续期后不生效”多半不是配置写错,而是 Tomcat 进程仍加载着旧文件。

前置准备:Sectigo 交付文件清单与 PKCS12 格式转换

Sectigo 签发后下载的 ZIP 包通常包含:example.com.crt(服务器证书/叶子证书)、example.com.ca-bundle(中间证书,有时拆成 AAACertificateServices.crt + USERTrustRSACertificationAuthority.crt 两段)、以及可选的根证书。拼接顺序必须是“叶子在前、中间在后”,颠倒会导致服务器只发出中间证书,握手直接失败。

如果 CA 直接给了 .pfx,先确认它是否自带完整链:

openssl pkcs12 -in example.com.pfx -info -nokeys -passin pass:'YourPass'

输出中若只出现一个 subject=CN = example.com 条目,说明只有叶子证书,必须自行补链。拆分与重新打包命令如下:

# 1) 拆出私钥、叶子证书、中间链
openssl pkcs12 -in example.com.pfx -nocerts -nodes -passin pass:'YourPass' -out privkey.pem
openssl pkcs12 -in example.com.pfx -clcerts -nokeys -passin pass:'YourPass' -out cert.pem
openssl pkcs12 -in example.com.pfx -cacerts -nokeys -passin pass:'YourPass' -out chain.pem

# 2) 按叶子+中间的顺序拼接
cat cert.pem chain.pem > fullchain.pem

# 3) 重新导出带完整链的 PKCS12(Tomcat 8.5+ 首选)
openssl pkcs12 -export -name tomcat 
  -inkey privkey.pem -in fullchain.pem 
  -out /opt/ssl/example.com.p12 -passout pass:'YourPass'

三个坑要注意:-name tomcat 指定的别名要和 Tomcat 里 certificateKeyAlias 一致;密码不要用空字符串(Java 8 加载空密码 PKCS12 会抛 java.io.IOException: keystore password was incorrect);文件权限必须收紧,执行 chown tomcat:tomcat /opt/ssl/example.com.p12 && chmod 600 /opt/ssl/example.com.p12,否则 Tomcat 启动用户读不到,报 AccessDeniedException。

实操步骤一:用 keytool 生成 CSR 并向 JKS 导入证书链

若 Sectigo 要求 CSR 由你生成(OV/EV 证书必走此流程),或历史系统必须使用 JKS,按以下顺序执行。先建 keystore 并生成密钥对:

keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -sigalg SHA256withRSA 
  -keystore /opt/ssl/example.com.jks -storetype JKS -storepass 'ChangeIt123' 
  -validity 365 -dname 'CN=example.com, O=Example Inc, L=Shanghai, C=CN'

注意:-validity 只对自签名场景有效,CA 实际签发时长由 CA 决定且不得超过 398 天上限,写 365 只是避免 keytool 生成超长自签证书。随后导出 CSR 并提交给 Sectigo:

keytool -certreq -alias tomcat -keystore /opt/ssl/example.com.jks 
  -storepass 'ChangeIt123' -sigalg SHA256withRSA -file example.com.csr

拿到签发文件后,必须按“根 → 中间 → 叶子”的顺序导入,否则 keytool -importcert 会报 Failed to establish chain from reply:

keytool -importcert -trustcacerts -alias sectigo-root -file AAACertificateServices.crt 
  -keystore /opt/ssl/example.com.jks -storepass 'ChangeIt123' -noprompt
keytool -importcert -trustcacerts -alias sectigo-intermediate -file USERTrustRSACertificationAuthority.crt 
  -keystore /opt/ssl/example.com.jks -storepass 'ChangeIt123' -noprompt
keytool -importcert -alias tomcat -file example.com.crt 
  -keystore /opt/ssl/example.com.jks -storepass 'ChangeIt123'

若手上只有 PFX,用一条命令转成 JKS:keytool -importkeystore -srckeystore a.pfx -srcstoretype PKCS12 -srcstorepass 'YourPass' -destkeystore a.jks -deststoretype JKS -deststorepass 'ChangeIt123' -destkeypass 'ChangeIt123'。导入后用 keytool -list -v -keystore /opt/ssl/example.com.jks -storepass 'ChangeIt123' 检查:Certificate chain length 应 ≥ 2,且别名 tomcat 的条目类型必须是 PrivateKeyEntry;若显示 trustedCertEntry,说明叶子证书导入到了错误别名,Tomcat 启动会报找不到私钥。

实操步骤二:Tomcat 8.5/9/10.1 的 Connector 配置

编辑 $CATALINA_HOME/conf/server.xml,把默认被注释的 8443 Connector 替换为下面这段。Tomcat 8.5、9.0、10.0、10.1、11 的写法完全一致(10.x 起 Java 包名为 jakarta.*,但 SSL 配置项未变):

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="200" SSLEnabled="true" scheme="https" secure="true">
  <SSLHostConfig hostName="example.com"
                 protocols="TLSv1.2,TLSv1.3"
                 honorCipherOrder="true">
    <Certificate certificateKeystoreFile="/opt/ssl/example.com.p12"
                 certificateKeystorePassword="YourPass"
                 certificateKeystoreType="PKCS12"
                 certificateKeyAlias="tomcat" />
  </SSLHostConfig>
  <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
</Connector>

关键参数说明:protocols 显式写死 TLSv1.2/TLSv1.3,避免 Tomcat 8.5 早期版本默认仍带 TLSv1;honorCipherOrder="true" 让服务端决定密码套件顺序,配合 SSL Labs 评级;certificateKeyAlias 在 PKCS12 里只有一个私钥条目时可省略,但多证书 keystore 场景必须写,否则报 Alias name [null] does not identify a key entry。Http2Protocol 只有在 TLS + ALPN 生效时才会启用,测试需 curl --http2。

老版本 Tomcat 7 的写法完全不同,属性直接挂在 Connector 上,混用会导致新配置被忽略:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
           SSLEnabled="true" scheme="https" secure="true"
           keystoreFile="/opt/ssl/example.com.jks" keystorePass="ChangeIt123"
           keystoreType="JKS" clientAuth="false" sslProtocol="TLS" />

改完后必须重启进程:$CATALINA_HOME/bin/shutdown.sh && $CATALINA_HOME/bin/startup.sh。Tomcat 不会热加载 keystore 文件变化,即使 reloadable="true" 也不行,这是“续期后不生效”的第一大原因。

配置示例:HTTP 强制跳转 HTTPS、多域名 SAN 与安全响应头

生产环境需要三件事:8080 自动跳 8443、同一 keystore 承载多域名、以及 HSTS 等安全头。跳转在 server.xml 的 HTTP Connector 上声明 redirectPort,并在 conf/web.xml 末尾启用安全约束(Tomcat 自带注释模板):

<!-- server.xml -->
<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />

<!-- conf/web.xml -->
<security-constraint>
  <web-resource-collection>
    <web-resource-name>All Secure</web-resource-name>
    <url-pattern>/*</url-pattern>
  </web-resource-collection>
  <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
</security-constraint>

多域名场景:一张 Sectigo 多域名(UCC)或通配符证书覆盖全部 SAN 域名时,只需一个 SSLHostConfig;不同证书则在一个 Connector 下并列多个 SSLHostConfig,用 hostName 区分(依赖 SNI):

<SSLHostConfig hostName="example.com">
  <Certificate certificateKeystoreFile="/opt/ssl/san.p12"
               certificateKeystorePassword="YourPass"
               certificateKeystoreType="PKCS12" />
</SSLHostConfig>
<SSLHostConfig hostName="api.example.com">
  <Certificate certificateKeystoreFile="/opt/ssl/api.p12"
               certificateKeystorePassword="YourPass"
               certificateKeystoreType="PKCS12" />
</SSLHostConfig>

HSTS 用 Tomcat 内置过滤器,无需自己写 Filter:

<filter>
  <filter-name>httpHeaderSecurity</filter-name>
  <filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class>
  <init-param><param-name>hstsEnabled</param-name><param-value>true</param-value></init-param>
  <init-param><param-name>hstsMaxAgeSeconds</param-name><param-value>31536000</param-value></init-param>
  <init-param><param-name>antiClickJackingEnabled</param-name><param-value>true</param-value></init-param>
</filter>
<filter-mapping>
  <filter-name>httpHeaderSecurity</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

提醒:HSTS 一旦下发,浏览器会在 max-age 内强制走 HTTPS,先在测试域名用 300 秒验证再上生产。Sectigo 的 DV 分钟级签发、OV 1–3 个工作日、EV 3–5 个工作日,保障金最高约 50 万美元,通配符与多域名方案价格优势明显,多子域场景优先选 SAN 证书而非多个 SSLHostConfig,可省去 SNI 兼容排查成本。

对比表格:PKCS12 / JKS / PEM 与各 Tomcat 版本配置差异

选型前先看清三种格式的实际差异,尤其是 Java 9 之后 keytool 的默认行为变化:

维度 PKCS12 (.p12/.pfx) JKS (.jks) PEM (cert+key)
Tomcat 原生支持 8.5+ 直接支持 全版本支持 不支持,需转换
配置属性 certificateKeystoreType="PKCS12" "JKS"(必须显式) —
私钥密码 与 storepass 强制相同 可独立 destkeypass —
跨语言通用性 Java / OpenSSL / Nginx 通用 仅 Java 体系 通用
空密码支持 Java 8 不支持 支持但不安全 —
推荐度 ★★★★★ ★★☆(遗留系统) 仅用于中转转换

Tomcat 版本与配置位置的对应关系,配错就是“改了没反应”:

Tomcat 版本 配置位置 关键属性 备注
7.0 Connector 属性 keystoreFile / keystorePass / keystoreType 已 EOL,TLS 1.3 支持差
8.5 SSLHostConfig certificateKeystoreFile / Password / Type 2024-03-31 已 EOL
9.0 SSLHostConfig 同上 主流长期支持版本
10.1 / 11 SSLHostConfig 同上,包名 jakarta.* 需 Java 11+

特别提醒:从 Java 9 起 keytool 的默认 -storetype 已改为 PKCS12。若你执行 keytool -importkeystore -destkeystore a.jks 时没写 -deststoretype JKS,生成的文件其实是 PKCS12,却在 Tomcat 里配成 certificateKeystoreType="JKS",启动即报 Keystore was tampered with, or password was incorrect。用 file a.jks 或 head -c 4 a.jks | xxd 可快速判别:JKS 魔数为 FEEDFEED,PKCS12 以 30 82 开头。

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

下面这些报错几乎覆盖了 Sectigo 证书在 Tomcat 上 95% 的部署失败场景,按出现频率排序:

真实报错 根因 修复
java.io.IOException: Keystore was tampered with, or password was incorrect storepass 错误,或 storetype 与实际文件不符 keytool -list -keystore x.jks -storepass xxx 验证;用 file x.jks 确认格式
java.security.UnrecoverableKeyException: Cannot recover key JKS 中 keypass ≠ storepass,而 Tomcat 只填一个密码 转 PKCS12,或 keytool -keypasswd -alias tomcat -keystore a.jks 统一密码
PKIX path building failed: unable to find valid certification path to requested target 证书链不完整,只发了叶子证书 openssl s_client -showcerts 计数,正常应 ≥ 2 条
curl: (60) SSL certificate problem: unable to get local issuer certificate 同上,服务器未发中间证书 重新导出 fullchain 的 PKCS12 并重启
verify error:num=21:unable to verify the first certificate 链顺序颠倒或中间证书缺失 拼接顺序改为“叶子在前、中间在后”
ERR_SSL_VERSION_OR_CIPHER_MISMATCH protocols 只写了 TLSv1.3,客户端只支持 1.2 改为 protocols="TLSv1.2,TLSv1.3"
IllegalArgumentException: The configured certificateKeystoreFile [...] does not exist 相对路径按 CATALINA_BASE 解析,或权限不足 写绝对路径 + chown tomcat:tomcat + chmod 600
Alias name [tomcat] does not identify a key entry 别名指向 trustedCertEntry 而非私钥条目 重新按根→中间→叶子顺序导入到同一别名

排查顺序建议固定为:先 keytool -list -v 看链长与条目类型,再 openssl s_client 看服务端实际发出的证书数量,最后才怀疑客户端。另外,-Djavax.net.debug=ssl:handshake 会输出完整握手细节,注意它打印的是客户端信任库,不能替代服务端链检查。

效果验证:openssl、curl、Java 三路交叉确认

部署完成后不要只看浏览器小锁,按下面四步做交叉验证:

# 1) 检查服务端证书主题、签发者与到期时间
openssl s_client -connect 127.0.0.1:8443 -servername example.com -showcerts </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates

# 2) 数证书条数,2 或 3 为正常,1 表示链断了
openssl s_client -connect example.com:8443 -servername example.com </dev/null 2>/dev/null 
  | grep -c 'BEGIN CERTIFICATE'

# 3) 看校验结果,必须是 Verify return code: 0 (ok)
echo | openssl s_client -connect example.com:8443 -servername example.com -CAfile /etc/ssl/certs/ca-certificates.crt 2>&1 
  | grep 'Verify return code'

# 4) HTTP 层与协议协商
curl -vI --http2 https://example.com:8443
java -Djavax.net.debug=ssl:handshake -jar app.jar 2>&1 | grep -E 'Protocol|CipherSuite'

验证要点:第 1 步的 notAfter 必须是新证书的到期日,否则说明进程没重启;第 2 步若返回 1,直接回到“前置准备”重新拼 fullchain;第 4 步应看到 TLS_AES_256_GCM_SHA384 或 ECDHE-RSA-AES128-GCM-SHA256 这类 AEAD 套件,以及 ALPN, server accepted to use h2。最后再跑一次外部评级(docker run --rm -it ssllabs/ssllabs-scan ssllabs-scan --grade example.com),目标 A 级以上;若因 SHA-1 或 TLS 1.0/1.1 被降级,回到 protocols 与 ciphers 参数修正。

常见问题

几乎都是证书链不完整。用 openssl s_client -showcerts 数证书条数,正常应 ≥2;把 ca-bundle 与叶子证书合并成 fullchain.pem,重新导出 PKCS12 并重启 Tomcat 即可解决。


优先 PKCS12。8.5 起原生支持 certificateKeystoreType=”PKCS12″,格式是行业标准,可被 OpenSSL、Nginx 复用;JKS 仅在对接遗留系统或需独立 keypass 时使用,且必须显式 -storetype JKS 生成。


Tomcat 不热加载 keystore。先确认 server.xml 中 certificateKeystoreFile 指向新文件,再完整执行 shutdown.sh 后 startup.sh;用 openssl s_client -connect 127.0.0.1:8443 查看 notAfter 是否更新。systemd 托管时确认 ExecStop 真正杀掉了 JVM。


可以。证书绑定的是域名而非服务器,把同一个 PKCS12 分发到多台 Tomcat,配置相同的 certificateKeystoreFile 即可。注意文件权限 600、属主为运行 Tomcat 的用户,并做好私钥分发的审计与轮换记录。


适用。自 2020-09-01 起公有 CA 证书最长 398 天,2026-03-15 起缩短为 200 天、2027-03-15 起为 100 天;Let’s Encrypt 仍为 90 天。建议提前 30 天续期并纳入自动化到期巡检。


导入顺序错或缺少中间证书。必须先以 -trustcacerts 导入根证书和中间证书,最后把叶子证书导入到与生成 CSR 时完全相同的别名,别名不一致同样会触发该报错。

内容审核

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