跳到主要内容
安装配置教程

Undertow SSL证书安装:WildFly与Spring Boot配置、报错排查与验证

undertow ssl证书安装 — Undertow SSL证书安装:WildFly与Spring Boot配置、报错排查与验证
核心结论

Undertow SSL 证书安装的核心是把含完整证书链和私钥的 PKCS12/JKS 密钥库挂到 HTTPS 监听器:WildFly 30 在 standalone.xml 配 https-listener 与 Elytron key-store,Spring Boot 3.2 配 server.ssl.key-store 指向 keystore.p12,HTTPS 端口常显式设为 8443。 把 fullchain.pem 与 privkey.pem 合成密钥库:openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out keystore.p12 -name undertow -CAfile chain.pem -caname root -passout pass:ChangeMe_2024。 WildFly 25+ 优先使用 Elytron server-ssl-context,旧版 WildFly 10-24 可用 security-realm;协议建议 protocols=TLSv1.3,TLSv1.2,enable-http2=true。 验证命令:openssl s_client -connect example.com:8443 -servername example.com -showcerts -tls1_3,看到 Verify return code: 0 (ok) 与 Protocol : TLSv1.3 才算链路和协议都正确。 常见根因是证书链缺中间证书、keystore 密码与 key-password 不一致、PEM 未转换、客户端与服务器无共同套件;先看日志 UT000065、Cannot recover key、PKIX path building failed。

Undertow 安装 SSL 证书为什么总失败?先看根本原因

问题一:把 fullchain.pem 直接丢给 Undertow 为什么必然失败?因为 Undertow 2.3.x(WildFly 30/31 与 Spring Boot 3.2.x 的内嵌版本)底层走的是 Java KeyStore API,从不解析 PEM。WildFly 通过 Elytron 的 key-store 或旧的 security-realm 加载 JKS/PKCS12;Spring Boot 通过 server.ssl.key-store 加载 KeyStore。所以 undertow ssl证书安装的第一步永远是格式转换,而不是改配置:

# 将 Let's Encrypt 产物合并成 PKCS12(Undertow 只认 KeyStore)
openssl pkcs12 -export 
  -in fullchain.pem       # 必须含叶证书+中间证书,只给 cert.pem 会导致链不完整
  -inkey privkey.pem 
  -name undertow          # alias,需与 WildFly 的 alias / Spring Boot 的 key-alias 一致
  -out keystore.p12 
  -passout pass:changeit   # storepass;PKCS12 中 keypass 默认与之相同

# 校验:应打印出两段 subject/issuer(叶证书 + 中间证书)
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
keytool -list -v -keystore keystore.p12 -storepass changeit | grep -E "Alias|Entry type"

问题二:为什么浏览器正常、Java 客户端却报错?据 Let’s Encrypt 文档,fullchain.pem 才是”叶证书 + 中间证书”的完整链,cert.pem 只有叶证书。只导入后者时,Java 17 客户端抛 PKIX path building failed: unable to find valid certification path,curl 抛 curl: (60) unable to get local issuer certificate——这不是 Undertow 的问题,而是信任链断了。

问题三:密码和别名对不上会怎样?PKCS12 里 storepass 与 keypass 通常相同,若 WildFly 的 keystore-password 与 key-password 写成不同值,启动即抛 java.security.UnrecoverableKeyException: Cannot recover key;alias 拼错则提示 No key found for alias。问题四:监听器没开 SSL。WildFly 的 https-listener 必须挂 ssl-context(Elytron)或 security-realm;Spring Boot 需同时设置 server.ssl.enabled=true 与 server.port=8443,漏掉前者 8443 端口根本不会监听:

server:
  port: 8443                # 不写则仍是 8080,浏览器访问 8443 直接拒绝连接
  ssl:
    enabled: true           # 默认 false,漏写会退回明文 HTTP
    key-store: classpath:keystore.p12
    key-store-type: PKCS12  # 默认 JKS,写错报 "not a valid keystore"
    key-store-password: changeit
    key-alias: undertow

问题五:为什么握手直接失败?据 RFC 8446,TLS 1.3 只保留 AEAD 套件(AES-GCM/ChaCha20-Poly1305)。若服务器 protocols 只写 TLSv1.3 而客户端仅支持 TLS 1.2,Firefox 报 SSL_ERROR_NO_CYPHER_OVERLAP,OpenSSL 报 no cipher suites in common。问题六:版本写法不能照抄。WildFly 30 使用 Elytron 与 Undertow 2.3.x,旧版 WildFly 10–24 的 security-realm 片段粘进新 standalone.xml 会直接启动失败,这也是 undertow ssl证书安装最常见的”配置对但起不来”:

运行环境 Undertow 版本 证书加载方式 典型坑
WildFly 30 / 31 2.3.x Elytron key-store + ssl-context 沿用旧 security-realm 写法
WildFly 10–24 2.2.x 及以下 security-realm / keystore 无 ssl-context 属性
Spring Boot 3.2.x 2.3.x server.ssl.key-store 漏写 server.ssl.enabled

所以排查顺序应是:先用 keytool -list 确认 alias 与条目类型是 PrivateKeyEntry,再用 openssl s_client -connect host:8443 -showcerts 看返回几段证书,最后才回到配置文件——顺序反过来,你会反复在 XML 和 YAML 里找根本不存在的问题。

安装前要准备哪些文件?证书链、私钥、域名和端口怎么核对

在把证书交给 Undertow 之前,先问三个问题:私钥和证书是不是一对?SAN 里有没有你真正访问的域名?8443 端口通不通?这三项任一不成立,后面配 WildFly 的 https-listener 或 Spring Boot 的 server.ssl.* 都会白忙一场——而且报错信息通常很有迷惑性(例如握手失败只显示 SSL_ERROR_NO_CYPHER_OVERLAP)。

先确认文件角色。Let’s Encrypt 通过 certbot 签发的证书默认落在 /etc/letsencrypt/live/example.com/,目录里是符号链接(据 Let’s Encrypt 官方文档,live/ 下永远是”最新一份”,archive/ 下才是历史版本,因此不要让 keystore 直接引用 archive/ 里的带序号文件):

# certbot 默认目录结构(Ubuntu 22.04 / certbot 2.x 实测)
ls -l /etc/letsencrypt/live/example.com/
# cert.pem      -> ../../archive/example.com/cert1.pem        仅叶证书
# chain.pem     -> ../../archive/example.com/chain1.pem       中间证书
# fullchain.pem -> ../../archive/example.com/fullchain1.pem   叶+中间,服务端用这个
# privkey.pem   -> ../../archive/example.com/privkey1.pem     私钥,权限应为 600
stat -c '%a %U:%G' /etc/letsencrypt/live/example.com/privkey.pem
# 期望 600 root:root;若 WildFly 以非 root 运行,需改为 640 并加入对应组
文件 内容 在 Undertow 中的正确用法
server.crt / cert.pem 仅叶证书 不可单独导入,缺中间证书会触发 PKIX path building failed
chain.pem 中间证书(可能多张) 与叶证书拼接后再转 PKCS12
fullchain.pem 叶证书 + 中间证书 转 keystore 的首选输入
privkey.pem 私钥(PKCS#8 或 PKCS#1) 与 fullchain 一起 openssl pkcs12 -export

核对匹配关系。RSA 证书比模数,ECDSA 证书(Let’s Encrypt 自 2025 年起默认签发 ECDSA P-256)没有 modulus 字段,必须比公钥——这是很多人第一次用 -modulus 报 unable to load 的原因:

# RSA:两行 md5 必须完全一致
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa  -noout -modulus -in privkey.pem   | openssl md5

# ECDSA:改用公钥比对(OpenSSL 1.1.1+ 支持 pkey 命令)
openssl x509 -in fullchain.pem -noout -pubkey | openssl md5
openssl pkey -in privkey.pem -pubout          | openssl md5

核对 SAN 与有效期。现代浏览器只认 SAN,不再看 CN(RFC 6125 第 6.4.4 节明确规定 CN 回退已被弃用),所以 subject=CN = example.com 漂亮并不代表可用:

openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
# subject=CN = example.com
# issuer=C = US; O = Let's Encrypt; CN = R11
# notBefore=Mar  1 00:00:00 2025 GMT
# notAfter=May 30 00:00:00 2025 GMT     ← 剩余需 > 30 天,否则先在维护窗口续期
# X509v3 Subject Alternative Name:
#     DNS:example.com, DNS:www.example.com   ← 必须含你实际访问的主机名

验证证书链。把根证书单独存为 root.pem,用 -untrusted 喂中间证书;返回 OK 才说明链完整。若报 error 20: unable to get local issuer certificate,就是缺中间证书——正确做法是补 chain.pem 后重新生成 keystore,而不是只把叶证书导进去然后在 WildFly 里靠 truststore 硬撑。

openssl verify -CAfile root.pem -untrusted chain.pem server.crt
# server.crt: OK

端口与防火墙。WildFly 的 standalone.xml 里预定义 https socket-binding 端口为 8443(据 WildFly 官方文档,Undertow 的 https-listener 通过 socket-binding="https" 引用它);Spring Boot 内嵌 Undertow 不会自动开 8443,必须显式写 server.port=8443,否则你会对着 8080 排查半天。

ss -lntp | grep 8443                     # 确认进程确实监听,而不是只写了配置
firewall-cmd --list-ports                # 输出需含 8443/tcp
firewall-cmd --permanent --add-port=8443/tcp && firewall-cmd --reload

证书类型与续期节奏。这直接决定你把 reload 安排在什么时候:

类型 有效期 参考价格 对 Undertow 运维的影响
Let’s Encrypt 90 天 0 元 需 certbot renew --deploy-hook 自动重建 keystore 并 reload
商业 DV 1 年 0–300 元 手动替换,一年一次易遗忘
商业 OV 1 年 500–2000 元 需企业实名核验,签发 1–3 个工作日,必须留提前量

注意趋势:据 CA/Browser Forum 通过的 SC-081 提案,公网 TLS 证书最长有效期将在 2026–2029 年间由 398 天逐步压缩到 47 天,自动化续期从”可选”变成”必须”。因此本节核对完文件后,建议顺手写好 deploy-hook:

# /etc/letsencrypt/renewal-hooks/deploy/reload-undertow.sh
#!/bin/sh
# certbot 续期成功后自动执行:重建 PKCS12 并重载 WildFly(以 systemd 为例)
openssl pkcs12 -export 
  -in  /etc/letsencrypt/live/example.com/fullchain.pem 
  -inkey /etc/letsencrypt/live/example.com/privkey.pem 
  -name undertow -out /etc/pki/undertow/keystore.p12 
  -passout pass:changeit
chown wildfly:wildfly /etc/pki/undertow/keystore.p12
chmod 640 /etc/pki/undertow/keystore.p12
systemctl reload wildfly    # 若未配置 reload 语义,改用 restart
# 授权:chmod 755 /etc/letsencrypt/renewal-hooks/deploy/reload-undertow.sh

Undertow 证书怎么导入?PKCS12 与 JKS 的具体命令

先说结论:Undertow 自身不解析 PEM 文件,它通过 Java 的 KeyStore 读取私钥和证书链,因此无论跑在 WildFly 还是 Spring Boot 上,undertow ssl证书安装的第一步都是把 Let’s Encrypt 签发的 fullchain.pem + privkey.pem 打包成 PKCS12 或 JKS。一条 OpenSSL 命令即可完成,剩下的工作只是确认别名、校验条目类型、放对路径。

PKCS12 打包:一条命令搞定,-name 就是后续的 alias

# 在证书目录执行;fullchain.pem = 站点证书 + 中间证书(Let's Encrypt 默认如此)
openssl pkcs12 -export 
  -in fullchain.pem 
  -inkey privkey.pem 
  -out keystore.p12 
  -name undertow 
  -CAfile chain.pem 
  -caname root 
  -passout pass:ChangeMe_2024

# 关键行说明:
# -name undertow   → friendlyName,即 WildFly 的 key-alias / Spring Boot 的 server.ssl.key-alias
# -CAfile chain.pem → 仅在 fullchain.pem 未含中间证书(只给了 cert.pem)时才需要补齐链
# -caname root      → 给附加 CA 条目起的别名,可省略
# -passout          → storepass 与 keypass 在 PKCS12 中相同(RFC 7292 的 MAC 校验要求)

据 Let’s Encrypt 文档,fullchain.pem 已包含叶证书与中间证书,此时 -CAfile 可省;只提供 cert.pem 却忘了补链,运行期就会撞上 PKIX path building failed: unable to find valid certification path——这是链不完整最典型的报错。

校验内容:确认 PrivateKeyEntry 与链长度

keytool -list -v -keystore keystore.p12 -storetype PKCS12 -storepass ChangeMe_2024

# 期望输出片段(JDK 17):
# Keystore type: PKCS12
# Alias name: undertow
# Entry type: PrivateKeyEntry          ← 必须是 PrivateKeyEntry,trustedCertEntry 说明私钥没打进去
# Certificate chain length: 3          ← 2~3 为正常(叶 + 中间,或叶 + 中间 + 根)
# Certificate[1]: Owner: CN=example.com  SHA256: 5A:1F:...

注意 -storetype 必须显式写:据 Oracle keytool 文档,JDK 9 起默认 keystore 类型已从 JKS 改为 PKCS12,但在 JDK 8 上默认仍是 JKS,省略 -storetype 会得到 keytool error: java.io.IOException: Invalid keystore format。

转 JKS 兼容旧版 WildFly / 老中间件

keytool -importkeystore 
  -srckeystore keystore.p12 -srcstoretype PKCS12 -srcstorepass ChangeMe_2024 
  -destkeystore keystore.jks -deststoretype JKS -deststorepass ChangeMe_2024 
  -destkeypass ChangeMe_2024 -alias undertow
# -destkeypass 必须显式给出且等于 storepass,
# 否则 JKS 的 key 密码与 store 密码不一致,运行期抛
# java.security.UnrecoverableKeyException: Cannot recover key

选型时可直接参考下表(PKCS12 为 OpenSSL 与 Java 通用格式,JKS 仅为 Java 私有格式):

维度 PKCS12 (.p12/.pfx) JKS (.jks)
规范来源 RFC 7292(IETF 标准) Sun 私有格式,无 RFC
keytool 默认类型 JDK 9+ 默认 JDK 8 及更早默认
key 密码与 store 密码 通常必须相同 允许不同(-destkeypass)
跨语言可读 OpenSSL / curl / Nginx / Go 均可读 仅 Java 生态
WildFly key-store type 默认值 需显式写 type="PKCS12" 默认值即 JKS,可省略

ECDSA 证书的兼容性坑:若证书是 ECDSA P-256,OpenSSL 3.x 仍可用上面的 pkcs12 -export;JDK 17 自带 SunEC provider 无问题,但 JDK 8u301 之前的版本对 secp256r1 之外曲线支持不全,导入后可能报 java.security.KeyStoreException: Key protection algorithm not found,稳妥做法是改用 RSA 2048 证书或升级 JDK。

路径与权限:WildFly 放在 $JBOSS_HOME/standalone/configuration/keystore.p12,并执行 chown jboss:jboss keystore.p12 && chmod 640 keystore.p12(640 让同组可读、其他用户不可读);Spring Boot 放 src/main/resources/keystore.p12,或外置 file:/etc/ssl/keystore.p12 避免把密钥打进 jar。密码绝不进 Git:Spring Boot 用 --server.ssl.key-store-password=${SSL_KEYSTORE_PASSWORD} 注入,WildFly 用 Elytron 的 credential-store 或环境变量替代明文——这两处的具体写法属于下一节 undertow ssl证书安装的配置环节。

WildFly / JBoss EAP 下 Undertow HTTPS 监听器怎么配?Elytron 与旧版 security-realm 示例

问:WildFly 30 里照着老教程改了 security-realm,HTTPS 还是连不上,为什么?

答:WildFly 25 起(含 WildFly 30、JBoss EAP 8)的默认配置里 legacy security 子系统已被移除,Undertow 的 https-listener 不再接受 security-realm 属性,只认 ssl-context。据 WildFly 官方《How to Configure Server Security》指南,Elytron 是当前唯一受支持的 SSL 提供者;而 WildFly 10–24 / EAP 7.x 仍可继续用 security-realm。两者的差异决定了迁移成本:

维度 Elytron(WildFly 25+/EAP 8) legacy security-realm(WildFly 10–24)
监听器属性 ssl-context="undertowSSC" security-realm="ApplicationRealm"
密钥库定义位置 elytron 子系统 key-store security-realm/server-identities/ssl/keystore
密码管理 credential-reference,可对接 credential-store 做加密存储 属性内明文 keystore-password
协议/套件控制 protocols、cipher-suite-filter 精确到监听器 只能改 JVM 或 security-properties,粒度粗
TLS 1.3 原生支持,与 RFC 8446 一致 依赖 JDK,易被全局属性拖回 1.2

问:WildFly 30 的 Elytron 方式,完整命令怎么走?

答:把 PKCS12 文件放到 $JBOSS_HOME/standalone/configuration/keystore.p12,然后用 jboss-cli 一次性建好 key-store → key-manager → server-ssl-context → https-listener 这条链。注意 cipher-suite-filter 的分隔符可用逗号、冒号或空格(Elytron 的 CipherSuiteSelector.fromString 三者均接受),但不要同时开 TLSv1.0/1.1。

# 适用:WildFly 25+/30、JBoss EAP 8;管理端口默认 9990
$JBOSS_HOME/bin/jboss-cli.sh --connect

# 1) key-store:type 默认 JKS,这里显式指定 PKCS12
/subsystem=elytron/key-store=undertowKS:add(path=keystore.p12, 
  relative-to=jboss.server.config.dir, type=PKCS12, 
  credential-reference={clear-text=ChangeMe_2024})

# 2) key-manager 引用上面的 key-store
/subsystem=elytron/key-manager=undertowKM:add(key-store=undertowKS, 
  credential-reference={clear-text=ChangeMe_2024})

# 3) server-ssl-context:只放行 1.2/1.3,套件按服务端顺序协商
/subsystem=elytron/server-ssl-context=undertowSSC:add(key-manager=undertowKM, 
  protocols=["TLSv1.3","TLSv1.2"], 
  cipher-suite-filter="TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", 
  use-cipher-suites-order=true)

# 4) https-listener 引用;socket-binding https 默认 port=8443
/subsystem=undertow/server=default-server/https-listener=https:add( 
  socket-binding=https, ssl-context=undertowSSC, enable-http2=true)
# 若资源已存在会报 WFLYCTL0212: Duplicate resource,改用:
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=undertowSSC)

reload   # 必须重载,SSL 上下文才会真正绑定到监听器

等价的 XML 片段(standalone.xml 中 elytron 子系统,注意用 relative-to="jboss.server.config.dir" 避免绝对路径迁移问题):

<key-store name="undertowKS">
  <credential-reference clear-text="ChangeMe_2024"/>
  <implementation type="PKCS12"/>
  <file path="keystore.p12" relative-to="jboss.server.config.dir"/>
</key-store>
<key-manager name="undertowKM" key-store="undertowKS">
  <credential-reference clear-text="ChangeMe_2024"/>
</key-manager>
<server-ssl-context name="undertowSSC" protocols="TLSv1.3,TLSv1.2"
  cipher-suite-filter="TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
  use-cipher-suites-order="true" key-manager="undertowKM"/>

问:还在 WildFly 10–24 上,security-realm 怎么写?

<security-realm name="ApplicationRealm">
  <server-identities>
    <ssl>
      <!-- JKS 密钥库;别名 undertow 必须存在,否则启动即 SSL 初始化失败 -->
      <keystore path="keystore.jks" relative-to="jboss.server.config.dir"
                keystore-password="ChangeMe_2024" alias="undertow" key-password="ChangeMe_2024"/>
    </ssl>
  </server-identities>
</security-realm>
<!-- undertow 子系统中: -->
<https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>

问:怎么确认配好了,出问题怎么回滚?

# 期望输出 outcome=success,且能看到 "ssl-context" => "undertowSSC"
/subsystem=undertow/server=default-server/https-listener=https:read-resource

# 从外部验证协议与套件,-alpn h2 用于确认 HTTP/2 协商成功
openssl s_client -connect 127.0.0.1:8443 -tls1_3 -alpn h2 </dev/null | openssl x509 -noout -subject -dates

常见真实报错:密码错误时日志为 ELY01006: MissingKeyStoreCredentialException 或 WFLYELY00023: Could not load key store;ssl-context 名字写错则 CLI 直接报 WFLYCTL0369: required capabilities are not available。注意 UT005023 属于请求处理阶段异常,与 SSL 初始化无关,不要误判。若 reload 后出现其他 SSL 初始化失败(例如证书链不完整导致浏览器报 NET::ERR_CERT_AUTHORITY_INVALID),立即执行 reload --admin-only 或回退到上一个 standalone.xml 快照。Mozilla 的 SSL Configuration Generator 建议的服务端套件顺序与上面 use-cipher-suites-order="true" 的做法一致,可用于交叉核对套件白名单。

Spring Boot 内嵌 Undertow 怎么配 SSL?application.yml 参数与版本对应

Spring Boot 内嵌 Undertow 怎么配 SSL?先确认版本,再谈参数

Spring Boot 3.2.x 默认内嵌的是 Tomcat,要换 Undertow 必须先排除再引入;Spring Boot 2.7.x 属性名与 3.2.x 基本一致,但 Jakarta/javax 命名空间不同,迁移时容易踩坑。据 Spring Boot 官方 Application Properties 文档,server.ssl.* 是容器无关的通用前缀,Undertow 同样生效。

Spring Boot 内嵌 Undertow Servlet 命名空间 JDK 基线 TLS 1.3 默认可用
3.2.x 2.3.x jakarta.*(Servlet 6.0) 17 是(JDK 17 内置)
2.7.x 2.2.x javax.*(Servlet 4.0) 8 JDK 11+ 或 8u261+ 才可用
<!-- pom.xml:Spring Boot 3.2.x,排除 Tomcat 并引入 Undertow 2.3.x -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
  <exclusions>
    <exclusion>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-tomcat</artifactId>  <!-- 不排除则两个容器都在 classpath -->
    </exclusion>
  </exclusions>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-undertow</artifactId>      <!-- 版本由 parent 管理,3.2.x → 2.3.x -->
</dependency>

application.yml 里到底写哪些参数?下面这份是可直接运行的完整示例,注释里标了默认值:

server:
  port: 8443                              # 默认 8080;改成 8443 后 8080 将不再监听
  ssl:
    enabled: true                         # 默认 false
    key-store: file:/etc/ssl/keystore.p12 # 也可 classpath:keystore.p12;外置路径便于轮换
    key-store-type: PKCS12                # Boot 2.x 起默认 PKCS12;JKS 必须显式声明
    key-store-password: ${SSL_KEYSTORE_PASSWORD}   # 用环境变量注入,不要写死在仓库
    key-alias: undertow                   # PKCS12 只有一个条目时可省略
    enabled-protocols: TLSv1.3,TLSv1.2    # 不要留空,否则按 JVM 默认走
    ciphers: TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

前两个套件是 RFC 8446 定义的 TLS 1.3 套件,第三个是 TLS 1.2 的 ECDHE 套件——三者必须混写,否则禁用了 TLS 1.2 的客户端会握手失败。套件名单建议对照 Mozilla SSL Configuration Generator 的 Intermediate 档位。

# 生成 PKCS12 密钥库(OpenSSL 3.x;-name 与 key-alias 对应)
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem 
  -name undertow -out /etc/ssl/keystore.p12 -passout env:SSL_KEYSTORE_PASSWORD

# 启动时注入密码,命令行参数优先级高于 application.yml
SSL_KEYSTORE_PASSWORD='ChangeMe_2024' java -jar app.jar

只想改 server.port=8443,原来的 8080 还监听吗?不监听。若需保留 HTTP 并跳转,可加一个 UndertowBuilderCustomizer,再配合 Spring Security 的 requiresChannel();也可以直接配置 HTTPS 后由 Security 强制跳转。

@Bean
UndertowBuilderCustomizer httpConnector() {
    // 保留 8080,交给 Security 的 requiresChannel().anyRequest().requiresSecure() 跳转
    return builder -> builder.addHttpListener(8080, "0.0.0.0");
}

手写 Undertow.builder() 时能直接传 PEM 路径吗?不能。addHttpsListener(port, host, sslContext) 的第三个参数是 javax.net.ssl.SSLContext(Undertow 2.3 仍为 javax),必须先用 KeyManagerFactory 加载密钥库再初始化:

KeyStore ks = KeyStore.getInstance("PKCS12");
try (InputStream in = Files.newInputStream(Path.of("/etc/ssl/keystore.p12"))) {
    ks.load(in, password.toCharArray());          // 密码错误会抛 IOException: keystore password was incorrect
}
KeyManagerFactory kmf = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
kmf.init(ks, password.toCharArray());
SSLContext sslContext = SSLContext.getInstance("TLS");
sslContext.init(kmf.getKeyManagers(), null, null);
Undertow.builder().addHttpsListener(8443, "0.0.0.0", sslContext).build();

最常见的两个启动报错:java.io.IOException: Alias name [undertow] does not identify a key entry(key-alias 与密钥库条目名不符,用 keytool -list -keystore keystore.p12 -storetype PKCS12 核对),以及 java.io.IOException: keystore password was incorrect(环境变量未注入或含尾随空格)。

PKCS12、JKS、PEM 怎么选?Undertow 证书格式与协议参数对比表

先把结论说在前面:Undertow 本身不解析证书文件格式,它只接受一个 java.security.KeyStore 实例(或由你代码构建的 SSLContext)。所以“选格式”本质是“选 KeyStore 类型”。据 JDK 官方 keytool 文档,自 JDK 9 起 java.security 中的 keystore.type 默认值已从 JKS 改为 PKCS12,JDK 17 上执行 keytool -genkeypair 不写 -storetype 生成的就是 PKCS12 文件——这是“首选 PKCS12”最硬的依据。

格式 Undertow 配置方式 推荐场景 关键命令/参数
PKCS12(.p12/.pfx) key-store type=PKCS12 Spring Boot 3.2、WildFly Elytron 首选 openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out keystore.p12 -name undertow
JKS key-store type=JKS 旧 JBoss EAP 6/7、WildFly 10 及历史脚本兼容 keytool -importkeystore -srckeystore keystore.p12 -destkeystore keystore.jks -deststoretype JKS
PEM(fullchain.pem + privkey.pem) 不能直接配,需转 PKCS12/JKS 或写代码构建 SSLContext Nginx/Apache 迁移过来、Let’s Encrypt 原始产物 openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out keystore.p12

为什么 PEM 不能直接喂给 Undertow?因为 Undertow 的 XnioSsl/HTTPS listener 只认 KeyStore 与 KeyManager,PEM 的解析能力在 JDK 里并不存在(JDK 直到 18 才有实验性的 KeyStore.getInstance("PEM"),且默认未启用)。所以 PEM 必须走一次转换。OpenSSL 3.0 的 pkcs12 -export 默认使用 AES-256-CBC + PBKDF2,JDK 17 读没问题,但若目标端还是 JDK 8 老版本,需加兼容参数:

# Let's Encrypt 证书转 PKCS12(OpenSSL 3.x)
# -name 指定别名,Spring Boot 的 key-alias / Elytron 取私钥都依赖它,务必固定
# -certfile 把中间证书显式并入,避免链不全导致浏览器报 "证书链不完整"
openssl pkcs12 -export 
  -in fullchain.pem 
  -inkey privkey.pem 
  -certfile chain.pem 
  -out keystore.p12 
  -name undertow 
  -passout pass:Changeit123

# 仅当目标 JVM 为 JDK 8 旧版本时追加(OpenSSL 3.x 才支持 -legacy)
# openssl pkcs12 -export -legacy -in fullchain.pem -inkey privkey.pem -out keystore.p12 -name undertow

# 转 JKS(仅为兼容老 WildFly/JBoss);keytool 会打印"JKS 是专有格式"的迁移提示
keytool -importkeystore 
  -srckeystore keystore.p12 -srcstoretype PKCS12 -srcstorepass Changeit123 
  -destkeystore keystore.jks -deststoretype JKS -deststorepass Changeit123 
  -destkeypass Changeit123

# 验证:输出应显示 "Keystore type: PKCS12" 且 "Your keystore contains 1 entry"
keytool -list -v -keystore keystore.p12 -storetype PKCS12 -storepass Changeit123

密码参数是最容易踩坑的地方。PKCS12 规范上只有一个完整性/加密密码,storepass 与 keypass 通常必须相同;JKS 允许两者不同。这直接导致配置差异:WildFly Elytron 的 key-store 用 credential-reference,而 key-manager 取私钥时若密码不一致会失败;Spring Boot 则只暴露一个 server.ssl.key-store-password,没有独立的 key password 属性。典型报错就是密码不匹配:

java.security.UnrecoverableKeyException: Get Key failed: Given final block not properly padded.
Such issues can arise if a bad key is used during decryption.

协议参数方面,面向公网建议显式锁定 TLSv1.3 + TLSv1.2,禁用 TLSv1.0/1.1 与 3DES。据 WildFly 文档,Elytron 的 server-ssl-context 不写 protocols 时沿用 JVM 默认(JDK 11+ 为 TLSv1.3、TLSv1.2);Spring Boot 的 server.ssl.enabled-protocols 同理。

参数 Spring Boot 3.2 WildFly Elytron 默认值 / 建议值
协议版本 server.ssl.enabled-protocols protocols 默认 JVM 值;公网写 TLSv1.3,TLSv1.2
密码套件 server.ssl.ciphers cipher-suite-filter 默认按 provider 顺序;需保留 ECDHE_RSA_AES128_GCM_SHA256 供老 Java 8 客户端
KeyStore 类型 server.ssl.key-store-type key-store 的 type PKCS12
# Spring Boot 3.2(Undertow 作为容器)application.yml
server:
  ssl:
    enabled: true
    key-store: classpath:keystore.p12
    key-store-type: PKCS12            # 默认即 PKCS12,显式写出便于审阅
    key-store-password: ${SSL_PASS}   # 只有这一个密码属性
    key-alias: undertow
    enabled-protocols: TLSv1.3,TLSv1.2

# WildFly 30+ jboss-cli.sh:PKCS12 证书接入 Elytron 并挂到 https-listener
/subsystem=elytron/key-store=undertowKS:add(path=/etc/ssl/keystore.p12, type=PKCS12, credential-reference={clear-text=Changeit123}, required=true)
/subsystem=elytron/key-manager=undertowKM:add(key-store=undertowKS, algorithm=PKIX)
/subsystem=elytron/server-ssl-context=undertowSSC:add(key-manager=undertowKM, protocols=["TLSv1.3","TLSv1.2"])
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=undertowSSC)

一句话选型:新项目一律 PKCS12;只在对接旧 JBoss EAP / WildFly 10 或遗留运维脚本时保留 JKS;手上只有 PEM 时先 openssl pkcs12 -export,不要试图让 Undertow 直接读 PEM——这正是 undertow ssl证书安装 阶段最高频的失败原因。完成格式与协议选型后,下一步才是 listener 端口、证书链校验与 openssl s_client 验证。

Undertow SSL 证书安装常见报错怎么排查?真实错误信息与处理

Undertow 的 SSL 报错几乎都落在三类根因上:密钥库格式或密码不对、证书链不全、协议与密码套件不匹配。先按下表定位,再执行对应的完整命令序列。表中命令均以 server.p12 作为示例,实际使用时替换文件名即可。

报错关键片段 根因 首条定位命令
java.io.IOException: Invalid keystore format PEM 直接改名 .p12,或把 JKS 当 PKCS12 读 keytool -list -storetype PKCS12
UnrecoverableKeyException: Cannot recover key key-password 与 keystore-password 不一致,或 alias 写错 keytool -list -v 查 alias
Keystore was tampered with, or password was incorrect storepass 错误(含 Secret 里的换行符) tr -d 'rn' 后比对
SSLHandshakeException: PKIX path building failed 服务端未下发中间证书 openssl s_client -showcerts
UT000065: SSL must be specified when using HTTPS listener https-listener 未引用 ssl-context 检查 standalone.xml
SSL_ERROR_NO_CYPHER_OVERLAP / no cipher suites in common protocols 与 cipher-suite-filter 无交集 分别用 -tls1_2 / -tls1_3 测试

1. Invalid keystore format:文件内容和扩展名不一致。PKCS12 是二进制 ASN.1 结构,-----BEGIN CERTIFICATE----- 开头的文本文件无论怎么改名都读不进去。用 keytool 验证真实格式,再按 OpenSSL 文档的 pkcs12 -export 重新打包(-name 就是后续要填的 alias):

# 验证真实格式:PKCS12/JKS 会列出条目,PEM 会直接抛 Invalid keystore format
keytool -list -v -storetype PKCS12 -keystore server.p12 -storepass changeit

# 由 PEM 证书链 + 私钥重新导出,-name 即 alias,后续配置要一致
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem 
  -name undertow -out server.p12 -passout pass:changeit

2. Cannot recover key:密码体系没对齐。JKS 支持 storepass 与 keypass 不同;PKCS12 在 JDK 8u60 之后基本要求二者相同,keytool 会直接拒绝不同的 keypass。WildFly(Elytron 体系,21+ 使用 server-ssl-context)中 key-password 缺省时回退到 keystore-password,但 alias 必须与文件内条目名逐字一致:

<!-- standalone.xml:显式写出 key-password 与 alias,避免回退歧义 -->
<keystore path="server.p12" relative-to="jboss.server.config.dir" type="PKCS12"
          alias="undertow" keystore-password="${env.KEYSTORE_PASS}"
          key-password="${env.KEYSTORE_PASS}"/>

3. Keystore was tampered with:密码里混入了不可见字符。最常见于 Kubernetes Secret 或 CI 变量末尾的换行。Spring Boot 侧对应 server.ssl.key-store-password(默认无值,必须显式设置):

# 打印字节,确认结尾没有 r n 或空格
tr -d 'rn' < keystore.pass | od -c | tail -2

4. PKIX path building failed:客户端只拿到叶子证书。服务端 keystore 必须导入 fullchain(叶子 + 中间证书),只导叶子会导致部分客户端链验证失败——这与 Let’s Encrypt 文档中”必须提供完整链”的要求一致。用下面的命令数证书条数,正常应为 2 条以上:

openssl s_client -connect example.com:8443 -servername example.com -showcerts </dev/null 2>/dev/null 
  | grep -E '^ *[0-9]+ s:|i:'

5. UT000065:HTTPS 监听器没有绑定 SSL 上下文。WildFly 中 https-listener 必须引用 ssl-context,改完执行 :reload;Spring Boot 则确认 server.ssl.enabled=true(默认 false,仅当检测到 key-store 时才隐式开启,显式声明更可靠)。

<https-listener name="https" socket-binding="https" ssl-context="sslCtx" enable-http2="true"/>

6. no cipher suites in common:协议版本被裁掉了。Elytron 的 cipher-suite-filter 默认值为 DEFAULT,protocols 默认 TLSv1.3,TLSv1.2。若手工只填了 TLS 1.2 套件名却仍开放 TLS 1.3,或反之,就会出现无交集。分别探测两个版本再调整:

openssl s_client -connect example.com:8443 -tls1_2 </dev/null 2>/dev/null | grep -E 'Protocol|Cipher'
openssl s_client -connect example.com:8443 -tls1_3 </dev/null 2>/dev/null | grep -E 'Protocol|Cipher'

# Elytron 侧显式声明,TLS 1.3 套件名不带 ECDHE- 前缀(见 RFC 8446)
<server-ssl-context name="sslCtx" protocols="TLSv1.2,TLSv1.3"
    cipher-suite-filter="TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:ECDHE-RSA-AES128-GCM-SHA256"/>

怎么验证 Undertow SSL 证书安装生效?openssl、curl、keytool 与日志四步法

装完证书后,第一个该看的命令是什么?不要急着用浏览器访问,先确认 8443 端口确实已被 JVM 接管。如果 listener 根本没起来,后面所有握手测试都只是在测试“没有服务”的端口。

ss -lntp | grep 8443
# 期望:LISTEN 0 4096 *:8443 *:* users:(("java",pid=12345,fd=88))
# 进程名不是 java → 端口被 nginx/haproxy 占用,请求没到 Undertow
# 完全无输出     → https-listener 未启用,undertow ssl证书安装 实际没落地

8443 只是约定值:WildFly 默认的 https-listener 就监听 8443,而 Spring Boot 的 server.port 默认是 8080,必须显式配置 server.port=8443 并补全 server.ssl.*,否则 curl 打到的是明文端口。

WildFly 里怎么确认 ssl-context 真的绑上了?用 CLI 读运行时模型,比翻 standalone.xml 可靠:

/opt/wildfly/bin/jboss-cli.sh --connect --commands=
'/subsystem=undertow/server=default-server/https-listener=https:read-resource(recursive=true)'
# 关键字段:
#   "ssl-context"     => "applicationSSC"      ← WildFly 23+ / Elytron 写法
#   "security-realm"  => "ApplicationRealm"    ← WildFly 22 及更早的 legacy 写法
# 两者同时为空 → listener 未绑定密钥库,握手必然失败

WildFly 23 起默认由 Elytron 接管安全域,security-realm 属性仍可用但已 deprecated。同时配了 Elytron 的 server-ssl-context 又保留旧的 security-realm,是 undertow ssl证书安装后“证书导入成功却不生效”的头号原因。

证书链怎么验证?重点看两处:Verify return code 和链上证书张数。

openssl s_client -connect example.com:8443 -servername example.com -showcerts </dev/null
# 关注:
#   Verify return code: 0 (ok)
#   Certificate chain 段应出现 2~3 张证书(leaf + 中间 CA;根 CA 一般不下发)

openssl s_client -connect example.com:8443 -servername example.com -showcerts </dev/null 2>/dev/null 
  | grep -c 'BEGIN CERTIFICATE'
# 返回 1 → 只下发了 leaf,缺中间证书:浏览器靠 AIA 补链能过,
#          Java 客户端却会抛 PKIX path building failed

-servername 不能省。未发送 SNI 时 Undertow 可能回落到默认证书,测到的是另一张;多域名共用同一 listener 时尤其容易误判。

协议版本与密码套件怎么测?正向测 TLS 1.3 与 1.2 都要通,反向测 1.0/1.1 必须被拒:

openssl s_client -connect example.com:8443 -servername example.com -tls1_3 </dev/null 2>/dev/null 
  | grep -E 'Protocol|Cipher'
# 期望:Protocol : TLSv1.3 / Cipher : TLS_AES_256_GCM_SHA384

openssl s_client -connect example.com:8443 -servername example.com -tls1_2 </dev/null 2>/dev/null 
  | grep -E 'Protocol|Cipher'
# 期望:Protocol : TLSv1.2 / Cipher : ECDHE-RSA-AES256-GCM-SHA384

# 反向验证旧协议(OpenSSL 3.x 默认 SECLEVEL=2,需降级才发得出握手)
openssl s_client -connect example.com:8443 -servername example.com -tls1 -cipher 'DEFAULT@SECLEVEL=0' </dev/null
# 期望:alert protocol version / no protocols available,而非握手成功

JDK 11 起 jdk.tls.disabledAlgorithms 默认已包含 TLSv1、TLSv1.1,因此 WildFly 的 https-listener 若未显式设置 enabled-protocols,实际生效的是 JSSE 默认值而非 XML 里的历史残留值——这也是升级 JDK 后老客户端突然连不上的常见诱因。

HTTP 层怎么确认双协议兼容?

curl -I --http2 https://example.com:8443
# 期望首行:HTTP/2 200 或 HTTP/2 302

curl -sS -o /dev/null -w '%{http_version} %{http_code}n' 
  --tlsv1.2 --tls-max 1.2 https://example.com:8443
# 期望输出:1.2 200 —— TLS1.2 客户端仍可访问,双协议兼容成立

返回 HTTP/1.1 200 并不代表证书有问题,而是 ALPN 未协商成功:Undertow 的 HTTP/2 仅在 TLS 上通过 ALPN 提供,需要 JDK 9+(JDK 8 要额外挂 alpn-boot)。curl 退出码也有诊断价值:60 是证书校验失败,35 是握手失败。

怎么核对证书细节与有效期?

echo | openssl s_client -connect example.com:8443 -servername example.com 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName
# subject=CN = example.com
# issuer=C = US, O = Let's Encrypt, CN = R3
# notBefore=Feb  1 00:00:00 2025 GMT
# notAfter=May  2 00:00:00 2025 GMT
# X509v3 Subject Alternative Name:
#     DNS:example.com, DNS:www.example.com

据 Let’s Encrypt 文档,其证书有效期固定 90 天,若 notAfter 与当前时间之差明显偏离 90 天,说明加载的是旧文件或替换后未 reload。SAN 必须覆盖实际访问域名——CN 自 2017 年起已不被主流客户端用于域名匹配(参见 RFC 6125 与 CA/Browser Forum 基线要求)。

日志里该 grep 什么?

grep -E 'UT000065|Cannot recover key|PKIX|SSLHandshakeException' 
  /opt/wildfly/standalone/log/server.log
# UT000065 / Cannot recover key → keystore 密码或 key 密码不一致
# PKIX path building failed     → 缺中间证书,或对端 truststore 未导入
# SSLHandshakeException         → 协议/套件不匹配、SNI 缺失、证书过期

# Spring Boot 启动日志应出现(类名 o.s.b.w.e.undertow.UndertowWebServer):
# Undertow started on port(s) 8443 (https)
curl -sSf https://example.com:8443/actuator/health
# {"status":"UP"}   ← 非 0 退出码即探活失败
工具 验证层次 通过判据 失败时的典型指向
ss -lntp TCP 监听 java 进程 LISTEN 8443 listener 未启用、端口被前置代理占用
WildFly CLI 配置绑定 ssl-context 非空 Elytron 与 legacy security-realm 混用
openssl s_client 握手 / 证书链 Verify return code: 0,链上 2~3 张 缺中间证书、SAN 不匹配、协议被禁
curl 应用层可达性 HTTP/2 200,TLS1.2 也返回 200 ALPN 未生效、健康检查路径错误

不能按 Nginx 的方式直接填 PEM 路径。Undertow 需要 KeyStore 或 SSLContext,标准做法是先用 openssl pkcs12 -export 把 fullchain.pem 与 privkey.pem 合成 keystore.p12,再在 WildFly 或 Spring Boot 中引用。

WildFly 25+ 推荐 Elytron 的 ssl-context,先定义 key-store、key-manager、server-ssl-context,再让 https-listener 引用 ssl-context。security-realm 主要留给旧版 WildFly 10-24 或历史配置迁移。

主要差在版本:Spring Boot 3.2.x 内嵌 Undertow 2.3.x 并要求 JDK 17,TLS 1.3 支持更完整;Boot 2.7.x 常见 Undertow 2.2.x。配置属性名基本一致,仍是 server.ssl.key-store、key-store-type、key-store-password、key-alias。

先确认 alias 是否存在:keytool -list -v -keystore keystore.p12 -storetype PKCS12。再统一 storepass 与 keypass,WildFly 里同时检查 keystore-password、key-password、alias,Spring Boot 里检查 server.ssl.key-store-password 与 key-alias。

Nginx 直接读 ssl_certificate fullchain.pem 与 ssl_certificate_key privkey.pem;Undertow 读 PKCS12/JKS 密钥库或程序化 SSLContext。两者都要求服务端发送完整证书链,只是文件格式和配置入口不同。

替换 keystore.p12 后,WildFly 可用 jboss-cli.sh –connect 执行 reload;Spring Boot 通常需要滚动重启,因为 server.ssl.* 在启动时加载。续期前 30 天检查 notAfter,并保留旧 keystore 以便快速回滚。

用 openssl s_client -connect example.com:8443 -servername example.com -showcerts


本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

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