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 强制跳转。
- SSL证书申请 · SSL证书购买 · SSL证书安装配置
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
- SSL/HTTPS 证书配置 · 证书安装 · 证书申请
@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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。