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

JBoss SSL 证书安装:CSR 生成、keystore 配置与 HTTPS 验证(EAP 7.4/WildFly 31)

jboss ssl证书安装 — JBoss SSL 证书安装:CSR 生成、keystore 配置与 HTTPS 验证(EAP 7.4/WildFly 31)
核心结论

1. JBoss SSL 证书安装的核心是:把服务器证书与中间 CA 导入 JBoss 实际读取的 JKS/PKCS12 keystore,并让 standalone.xml 中 security-realm 的 server-identities/ssl 或 Elytron 的 server-ssl-context 指向它,再由 undertow 的 https-listener 暴露 8443/443。2. EAP 7.4 / WildFly 31 可用 keytool -genkeypair -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -storetype PKCS12 生成密钥与 CSR,CSR 提交后按 CA 要求导入 root、intermediate 与服务器证书。3. 默认 HTTPS 端口是 8443(socket-binding https port=${jboss.https.port:8443});要直接监听 443,需改 socket-binding 并以 root/authbind 启动,或用 iptables 把 443 REDIRECT 到 8443。4. 验证用 openssl s_client -connect host:8443 -servername host -showcerts,配合 keytool -list -v 查看 Certificate chain length 是否为 3;DV 证书通常 10 分钟内签发,OV 约 1-3 个工作日,Let's Encrypt 有效期 90 天。

为什么 JBoss 配了证书还是 HTTPS 不生效?先看根本原因

这是<jboss ssl证书安装过程中最常见也最容易被误判的问题:证书文件明明已经放进 configuration/ 目录,浏览器访问 8443 却仍然报错。根本原因通常不是证书本身,而是 JBoss 的 HTTPS 由 undertow 子系统的 https-listener 提供,它不会因为目录里多了一个 .jks 文件就自动启用 TLS。据 Red Hat EAP 7.4 文档,https-listener 的默认 socket-binding=https、端口 8443,但必须显式绑定 ssl-context(Elytron)或 security-realm(legacy)才会真正生效。

根因一:https-listener 根本没启用,或只改了证书却没重启。用 CLI 先确认当前状态:

# 适用 EAP 7.4 / WildFly 31;输出中若无 ssl-context 或 security-realm,说明 TLS 未启用
/subsystem=undertow/server=default-server/https-listener=https:read-resource(include-runtime=true)
# 启用并绑定 Elytron ssl-context(EAP 7.4 默认启用 elytron 子系统)
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=sslctx)
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=socket-binding, value=https)
reload   # 仅改 XML 不 reload,配置不会热生效

根因二:keystore 四要素任一不匹配即握手失败。legacy 路径下 security-realm/server-identities/ssl 的 keystore-path、alias、keystore-password、key-password 必须与 keystore 实际内容完全一致,注意 key-password 默认继承 keystore-password,PKCS12 中两者不同会直接抛 UnrecoverableKeyException:

<security-realm name="ApplicationRealm">
  <server-identities>
    <ssl>
      <!-- relative-to 指向 $JBOSS_HOME/standalone/configuration,路径写错等于没配 -->
      <keystore path="keystore.jks" relative-to="jboss.server.config.dir"
                keystore-password="changeit" alias="server" key-password="changeit"/>
    </ssl>
  </server-identities>
</security-realm>

根因三:只导入了服务器证书、漏了中间 CA。客户端会抛 PKIX path building failed: unable to find valid certification path to requested target。据 Let’s Encrypt 文档,fullchain 必须包含服务器证书与中间证书,导入 keystore 时按“服务器证书 → 中间 CA → 根 CA”顺序。用 OpenSSL 验证链路:

# 适用 OpenSSL 1.1.1/3.x;Verify return code 必须为 0 (ok)
openssl s_client -connect app.example.com:8443 -servername app.example.com -showcerts /dev/null 
  | grep -E "Verify return code|depth="
# 检查 keystore 里是否带完整链及 SAN
keytool -list -v -keystore standalone/configuration/keystore.jks -alias server -storepass changeit 
  | grep -A2 -E "Certificate chain length|SubjectAlternativeName"

根因四:证书 SAN 不含实际访问域名。只写 CN=example.com 却访问 www.example.com,Java 客户端直接抛 CertificateException: No subject alternative names present。RFC 6125 已明确以 SAN 为准、CN 仅作兼容回退,现代浏览器不再回退。

根因五:照搬了 JBoss 6 的配置。版本路径不同,抄错位置等于白做:

版本 HTTPS 配置位置 关键属性 默认端口
JBoss 6 及更早 JBoss Web 的 server.xml connector SSLEnabled、keystoreFile 8443
EAP 7.x / WildFly 31 undertow 子系统 https-listener + Elytron/security-realm ssl-context、security-realm 8443

根因六:前面有 Nginx、Apache 或 F5 做 TLS 终止。此时浏览器看到的是前置设备的证书链,JBoss 只需 HTTP 回源(8080)。在这种架构下重复做 jboss ssl证书安装不会改变浏览器显示的证书——用 openssl s_client -connect 你的域名:443 看 subject= 字段就能立刻确认证书到底由谁提供。

JBoss SSL 证书安装的完整步骤(EAP 7.4 / WildFly 31 实操)

问:JBoss 上装 SSL 证书,第一步该确认什么?先别急着敲 keytool——版本决定你能不能继续用 security-realm,端口决定防火墙和 openssl s_client 连哪里。用 CLI 一次性把三件事查清:

# 1) 版本与产品名:EAP 返回 "JBoss EAP 7.4.x",社区版返回 "WildFly Full 31.0.0.Final"
$JBOSS_HOME/bin/jboss-cli.sh --connect --command=':version'
$JBOSS_HOME/bin/jboss-cli.sh --connect --command=':product-info'

# 2) HTTPS 监听端口,standalone 默认 8443
$JBOSS_HOME/bin/jboss-cli.sh --connect 
  --command='/socket-binding-group=standard-sockets/socket-binding=https:read-attribute(name=port)'
对比项 JBoss EAP 7.4 WildFly 31
配置文件 $JBOSS_HOME/standalone/configuration/standalone.xml 同一路径(domain 模式为 domain/configuration/domain.xml)
证书挂载方式 legacy security-realm(已弃用)或 Elytron 仅 Elytron server-ssl-context
默认 HTTPS 端口 8443 8443
keytool 默认 storetype 随 JDK 走:JDK 8 = JKS,JDK 11+ = PKCS12 JDK 17+,默认 PKCS12

WildFly 25 起移除了 legacy security 子系统,因此 WildFly 31 上写 <security-realm> 不会报错但也不生效——这是 jboss ssl证书安装 最常见的“配了却还是旧证书”的原因。据 WildFly 25 发布说明,Elytron 是唯一受支持的安全栈。

步骤 2:生成密钥库和 CSR(PKCS12 下 -keypass 必须与 -storepass 相同,否则 keytool 会打印 Warning: Different store and key passwords not supported for PKCS12 KeyStores 并忽略 keypass):

export JBOSS_HOME=/opt/jboss-eap-7.4
KS=$JBOSS_HOME/standalone/configuration/jboss.keystore

keytool -genkeypair -alias jboss -keyalg RSA -keysize 2048 -sigalg SHA256withRSA 
  -validity 365 -storetype PKCS12 -keystore $KS 
  -storepass 'ChangeIt123' -keypass 'ChangeIt123' 
  -dname 'CN=www.example.com, OU=Ops, O=Example, L=Shanghai, ST=Shanghai, C=CN' 
  -ext san=dns:www.example.com,dns:example.com,ip:203.0.113.10   # SAN 才是 CA 校验的主体

keytool -certreq -alias jboss -keystore $KS -storepass 'ChangeIt123' -file www.example.com.csr

步骤 3:提交 CSR,等多久?按 CA/B Forum 基线要求,域名验证走 DNS/TXT 或文件校验:DV 约 10 分钟,OV 需核验组织资质约 1–3 个工作日,EV 约 3–7 个工作日。你会拿到 server.crt(服务器证书)、intermediate.crt(中间 CA)、root.crt(根),以及 CA 打包好的 fullchain 文件。

步骤 4:按“根 → 中间 → 服务器”的顺序导入,最后一步的 alias 必须与生成密钥时的 jboss 完全一致,否则会报 keytool error: java.lang.Exception: Certificate reply does not match the certificate request:

keytool -importcert -alias root -file root.crt -keystore $KS -storepass 'ChangeIt123' -noprompt
keytool -importcert -alias intermediate -file intermediate.crt -keystore $KS -storepass 'ChangeIt123' -noprompt
keytool -importcert -alias jboss -file server.crt -keystore $KS -storepass 'ChangeIt123'

# 若 CA 直接给 PKCS#7 链,可一步替换服务器证书:-file fullchain.p7b
keytool -list -v -alias jboss -keystore $KS -storepass 'ChangeIt123' | grep -E 'Certificate chain length|Owner|Issuer'

步骤 5:配置监听器。EAP 7.4 可沿用 legacy 写法(keystore-password 与 key-password 必填,后者缺省时取前者):

<security-realm name="ApplicationRealm">
  <server-identities>
    <ssl>
      <keystore path="jboss.keystore" relative-to="jboss.server.config.dir"
                keystore-password="ChangeIt123" alias="jboss" key-password="ChangeIt123"/>
    </ssl>
  </server-identities>
</security-realm>

WildFly 31 / EAP 7.4 推荐用 Elytron,四条 CLI 命令即可,protocols 缺省为 TLSv1.3 与 TLSv1.2:

/subsystem=elytron/key-store=jbossKS:add(path=jboss.keystore, relative-to=jboss.server.config.dir, 
  type=PKCS12, credential-reference={clear-text=ChangeIt123})
/subsystem=elytron/key-manager=jbossKM:add(key-store=jbossKS, alias-filter=jboss, 
  credential-reference={clear-text=ChangeIt123})
/subsystem=elytron/server-ssl-context=jbossSSC:add(key-manager=jbossKM, protocols=["TLSv1.3","TLSv1.2"])
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=jbossSSC)

步骤 6:reload 并验证。日志里看到 WFLYSRV0025: JBoss EAP 7.4.x ... started in ...ms 才算生效;WFLYSRV0026 则表示仍在启动中:

$JBOSS_HOME/bin/jboss-cli.sh --connect --command=':reload'
openssl s_client -connect www.example.com:8443 -servername www.example.com 
  -showcerts -CAfile root.crt </dev/null | openssl x509 -noout -subject -issuer -dates
# 期望:Verify return code: 0 (ok),且 Issuer 为中间 CA 而非自签

若客户端只支持 TLS 1.0/1.1,会撞上 SSLHandshakeException: no cipher suites in common——按 PCI DSS 与 Mozilla 服务器端 TLS 指南,这两个版本本就不该再开。后续可延伸的话题包括 OCSP stapling、HSTS 头、客户端证书双向认证(mTLS),以及用 Let’s Encrypt 短期证书做自动轮换——keystore 里 alias 不变、只替换证书链,就能做到 reload 不中断连接。

关键配置与命令示例:keytool、standalone.xml 与 jboss-cli

证书已经导进 keystore,为什么浏览器打开还是提示“不安全”?最常见的两个原因:standalone.xml 里没有任何 listener 引用这个 keystore;或者引用的是旧版 security-realm,而 WildFly 31 早已移除该机制。JBoss SSL 证书安装的真正难点在于完成“keystore 到 listener”的连接,而不在于 keytool -importcert 本身。

EAP 7.4 的默认模板仍保留 legacy 结构,可直接在 security 子系统中添加:

<!-- standalone.xml / standalone-full.xml,EAP 7.4 默认含 ApplicationRealm -->
<security-realm name="ApplicationRealm">
  <server-identities>
    <ssl>
      <!-- relative-to 默认 jboss.server.config.dir,即 standalone/configuration/ -->
      <keystore path="jboss.keystore" relative-to="jboss.server.config.dir"
                keystore-password="ChangeIt123" alias="jboss" key-password="ChangeIt123"/>
    </ssl>
  </server-identities>
</security-realm>

<server name="default-server">
  <!-- enable-http2 默认 false,需显式打开 -->
  <https-listener name="https" socket-binding="https"
                  security-realm="ApplicationRealm" enable-http2="true"/>
</server>

注意:legacy security realm 自 WildFly 25(WFLY-15032)起被删除,WildFly 31 只认 Elytron。在运行实例上用 jboss-cli 分四步建立 key-store → key-manager → server-ssl-context → listener 的引用链:

# 连接管理端口(默认 9990),EAP 7.4 / WildFly 31 通用
$JBOSS_HOME/bin/jboss-cli.sh --connect --controller=localhost:9990

# 1) 注册 keystore,type 建议 PKCS12(keytool 自 JDK 9 起默认格式)
/subsystem=elytron/key-store=jbossKS:add(path=jboss.keystore,relative-to=jboss.server.config.dir,type=PKCS12,credential-reference={clear-text=ChangeIt123})

# 2) key-manager,algorithm 默认即 PKIX
/subsystem=elytron/key-manager=jbossKM:add(key-store=jbossKS,algorithm=PKIX,credential-reference={clear-text=ChangeIt123})

# 3) SSL 上下文,只放行 TLS 1.2/1.3(禁用 1.0/1.1)
/subsystem=elytron/server-ssl-context=jbossSSC:add(key-manager=jbossKM,protocols=["TLSv1.2","TLSv1.3"])

# 4) 切换 listener:两个属性互斥,先删 security-realm 再写 ssl-context
/subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context,value=jbossSSC)

# 5) 重载使配置落地
:reload

子系统版本别照抄:EAP 7.4 的 undertow 通常为 urn:jboss:domain:undertow:12.0,WildFly 31 为 undertow:14.0,以实际 standalone.xml 的 xmlns 为准,版本号不匹配会导致启动时 schema 校验失败。

维度 legacy security-realm Elytron(推荐)
配置位置 security 子系统 <security-realms> elytron 子系统三个资源
EAP 7.4 支持,模板自带 ApplicationRealm 支持,Red Hat 推荐
WildFly 31 已移除,不可用 唯一方式
协议/套件控制 <ssl protocol="TLSv1.2,TLSv1.3">,粒度粗 protocols + cipher-suite-filter,粒度细
热更新 改 XML 后 reload CLI :write-attribute + :reload

想直接跑在 443,把绑定改成 <socket-binding name="https" port="${jboss.https.port:8443}"/> 中的默认值 443,或用 -Djboss.https.port=443 覆盖。1024 以下端口需特权,非 root 有两条路:

# 方案一:内核层重定向,JBoss 仍监听 8443
sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 8443

# 方案二:authbind 授予绑定特权端口的能力(Debian/Ubuntu 需先 apt install authbind)
sudo authbind --deep $JBOSS_HOME/bin/standalone.sh

上线前务必确认链完整——缺中间 CA 时浏览器与 Java 客户端都会报 unable to get local issuer certificate:

keytool -list -v -alias jboss 
  -keystore $JBOSS_HOME/standalone/configuration/jboss.keystore 
  -storepass 'ChangeIt123' | grep -E 'Alias|Valid|Certificate chain length'
# 期望输出:Certificate chain length: 3(服务器证书 + 中间 CA + 根 CA)
# 若为 1,说明只导入了服务器证书,需 -importcert 补齐中间证书

协议与套件的取值可直接照搬 Mozilla SSL Configuration Generator 的 intermediate 档:仅 TLS 1.2/1.3,禁用 TLS 1.0/1.1(RFC 8996 已将其列为不应使用)。Elytron 下等价写法是给 server-ssl-context 追加 cipher-suite-filter="TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256:TLS_AES_128_GCM_SHA256",冒号分隔、区分大小写。改完用 openssl s_client -connect localhost:8443 -servername your.domain -tls1_2 复核握手,输出中 Protocol : TLSv1.2 与完整的 Certificate chain 即表示 JBoss SSL 证书安装链路已通。

JKS、PKCS12、PEM 与 keystore/truststore 怎么选?参数对比表

先给结论:在 JBoss EAP 7.4 与 WildFly 31 上,默认且最省事的选择是 PKCS12。原因是这两个版本开箱即用的 application.keystore 本身就是 PKCS12,Elytron 对它的支持也最完整;JKS 只在维护 JBoss AS 6/7 老环境时才有意义;PEM 则根本不会被 Java 的 KeyStore 直接读取,必须先转换。据 Oracle keytool 官方文档,自 JDK 9 起 -storetype 的默认值已由 JKS 改为 PKCS12,这正是很多老脚本不显式写 -storetype JKS 就会报 keytool error: java.io.IOException: Invalid keystore format 的原因。

对比项 JKS PKCS12 PEM
keytool 参数 -storetype JKS -storetype PKCS12 不直接支持,需 openssl pkcs12 -export 转换
密码 storepass 与 keypass 可不同 通常 keypass = storepass 仅由私钥密码保护
别名 alias 必须与 ssl 配置中的 alias 一致 必须与 ssl 配置中的 alias 一致 转换时用 -name 指定
EAP 7.4 / WildFly 31 默认 否 是(application.keystore,密码 password) 否
推荐场景 老 JBoss 6/AS 7 遗留系统 EAP 7.4、WildFly 31 生产首选 Nginx/Apache 前端,或作为转换中间格式

keystore 与 truststore 不要混用:keystore 存私钥、服务器证书与中间 CA 链,是”我证明我是谁”;truststore 只存受信任的根/中间 CA,用于 JBoss 作为客户端去访问 LDAP、HTTPS 后端时校验对端。把服务器私钥塞进 truststore 既无意义,也扩大泄露面。

EAP 7.4 的 standalone-full-ha.xml 默认 key-store 指向 application.keystore(PKCS12,明文口令 password,别名 localhost,自签名);WildFly 31 的 applicationKS 行为一致。二者都不能直接上线——浏览器会报 NET::ERR_CERT_AUTHORITY_INVALID。如果 CA 只给了 .crt 与 .ca-bundle,用下面这段完成转换与校验:

# 1) 合并服务器证书与中间链,顺序必须是「服务器证书在前、中间 CA 在后」
cat server.crt ca-bundle.crt > fullchain.crt

# 2) 合成 PKCS12;-name 即 PKCS12 内的 alias,须与 JBoss 里 alias 属性一致
#    据 OpenSSL 文档,PKCS12 格式定义见 RFC 7292
openssl pkcs12 -export 
  -in fullchain.crt 
  -inkey server.key 
  -name jboss 
  -out jboss.p12 
  -passout pass:ChangeIt123

# 3) 校验:-storetype 必须显式写,否则可能按 JKS 解析失败
keytool -list -v -keystore jboss.p12 -storetype PKCS12 -storepass ChangeIt123
# 输出应看到 Alias name: jboss、Certificate chain length: 3

# 4) 若手上是旧 JKS,可直接迁移(保留 alias 与私钥)
keytool -importkeystore -srckeystore old.jks -srcstoretype JKS 
  -srcstorepass oldpass -destkeystore jboss.p12 
  -deststoretype PKCS12 -deststorepass ChangeIt123

选型与成本参考:

  • 单机 JBoss:一个 PKCS12 keystore 搞定,别名与 Elytron key-store 的 alias 对齐即可。
  • 集群:每节点同一张证书、各自独立的 keystore 文件,便于单独轮换。
  • TLS 由 Nginx 终止:JBoss 只保留 HTTP connector,证书仅装在前端,JBoss 侧无需 keystore——这是最常见的性能与运维折中。
  • 价格/时间:Let’s Encrypt 免费、有效期 90 天(据 Let’s Encrypt 官方文档,可用 ACME 客户端自动续期);商业 DV 约 ¥0–300/年;OV 约 ¥800–3000/年(1–3 个工作日);EV 约 ¥3000–8000/年(3–7 个工作日)。JBoss EAP 订阅费与证书费用分开计算,别把两者混为一谈。

做一次 jboss ssl 证书安装 时,先确认 keytool -list 里能看到完整链,再动 Elytron 配置;证书链不全导致的手握失败,比密码错误更难排查。

常见报错与排查:从 PKIX path building failed 到 no cipher suites

本节用问答方式复盘六个最常被搜到的 JBoss SSL 报错。先说结论:这些异常里真正属于”证书装错了”的只有一半,另一半出在 truststore、alias 或端口上。定位的第一步永远是拿到真实的报错堆栈与握手细节,而不是重新生成证书。

Q1:客户端报 PKIX path building failed: unable to find valid certification path to requested target,服务端证书明明有效?

这几乎总是链不全或信任锚缺失。据 RFC 5280 第 6 节的路径构建规则,客户端必须能从服务器下发的证书一路走到本地 truststore 里的根。用 OpenSSL 数一下实际下发的张数:

# 正常应返回 ≥2(服务器证书 + 中间 CA),只返回 1 就是漏发了中间证书
openssl s_client -connect www.example.com:8443 -servername www.example.com -showcerts /dev/null 
  | grep -c "BEGIN CERTIFICATE"

# 用 openssl 校验链,确认顺序是 server → intermediate → (root 可选)
openssl s_client -connect www.example.com:8443 -showcerts /dev/null | openssl verify -CAfile root.crt

修复:把 fullchain.pem 按 server→intermediate 顺序导入 keystore(根证书不要放进去),或在 WildFly 31/EAP 7.4 的 elytron 中显式挂载信任链:/subsystem=elytron/key-store=serverKS:read-resource 确认 certificate 属性只含叶证书。

Q2:No subject alternative names present 或 No name matching www.example.com found?

据 RFC 6125,现代客户端只按 SAN 匹配主机名,CN 已被主流实现忽略。检查:

openssl x509 -noout -text -in server.crt | grep -A1 "Subject Alternative Name"
# 期望输出:DNS:www.example.com, DNS:example.com

缺哪个域名就重签,不能靠改 jboss.https.port 绕过去。

Q3:Keystore was tampered with, or password was incorrect?

key-store 资源的 password 必须与生成时的 -storepass 完全一致。PKCS12 在 JDK 9+ 默认要求 key-password 等于 storepass,否则即使 storepass 正确也会在取私钥时报同一异常。核对:

keytool -list -v -keystore server.keystore.p12 -storepass 'ChangeIt!' | grep -E "Alias name|Entry type|Valid from"

Q4:no cipher suites in common 或 Received fatal alert: protocol_version?

这是版本错配,不是证书问题。EAP 7.4 与 WildFly 31 的 https-listener 默认 enabled-protocols 为 TLSv1.2,TLSv1.3,老客户端只发 TLS 1.0 就会被拒。分别探测:

openssl s_client -connect 127.0.0.1:8443 -tls1_2 </dev/null   # 应握手成功
openssl s_client -connect 127.0.0.1:8443 -tls1_3 </dev/null   # 应握手成功
openssl s_client -connect 127.0.0.1:8443 -tls1_1 </dev/null   # 预期失败

按 Mozilla SSL Configuration Generator 的 “Intermediate” 配置,保留 TLS 1.2/1.3 即可,不要为兼容老设备回退到 TLS 1.0。

Q5:Alias name [jboss] does not exist 或 Unrecognized SSL message, plaintext connection??

前者是 alias 大小写/拼写与 keystore 内条目不一致;后者是把 HTTPS 请求打到了 8080 明文端口。两条命令一次查清:

keytool -list -keystore server.keystore.p12 -storepass 'ChangeIt!'   # 看真实 alias
ss -lntp | grep -E '8080|8443'                                        # 看谁在监听哪个端口

Q6:validity check failed?

证书过期或主机时钟漂移超过 5 分钟。对比时间:

date -u
openssl x509 -noout -dates -in server.crt   # notBefore / notAfter
timedatectl set-ntp true                    # 启用 chrony/NTP 后再重启 JBoss

把六类报错压成一张速查表:

报错关键字 根因 定位命令 修复方向
PKIX path building failed 链不全 / truststore 缺根 openssl s_client -showcerts 导入 fullchain,顺序 server→intermediate
No subject alternative names SAN 缺域名 openssl x509 -text 重签含 DNS 条目的证书
Keystore was tampered with storepass/keypass 不符 keytool -list -v 对齐 key-store 的 password
no cipher suites in common TLS 版本被禁用 openssl s_client -tls1_2 保持 TLS 1.2/1.3
Alias name does not exist alias 拼写不一致 keytool -list 修正 alias 属性
validity check failed 过期 / 时钟漂移 date -u + x509 -dates 续签并启用 NTP

排查顺序建议固定为:先用 openssl s_client 从外部确认链与协议版本,再看 JBoss server.log 中 org.wildfly.security 与 io.undertow 的堆栈,最后才动 keystore。多数”jboss ssl证书安装失败”的工单,在第 一步就能定位到是链、SAN 还是端口问题,与证书文件本身无关。

如何验证 JBoss SSL 证书安装已生效?

完成 jboss ssl证书安装 后不要只看启动成功,要拿到三层证据:keystore 内容、TLS 握手、应用层响应。WildFly 31 与 JBoss EAP 7.4 的 HTTPS 监听器默认端口是 8443,就绪标志是日志里的 WFLYSRV0025。

# 1) 端口与启动日志(WildFly 31 / EAP 7.4 通用)
ss -lntp | grep 8443
# 期望:LISTEN 0 128 *:8443 *:* users:(("java",pid=12345,fd=...))

grep -E 'WFLYSRV0025|WFLYSRV0010' "$JBOSS_HOME/standalone/log/server.log"
# WFLYSRV0025: WildFly Full 31.0.0.Final (WildFly Core 23.0.0.Final) started in 4521ms

# SSL 相关异常集中在 Undertow 的 UT005 系列
tail -f "$JBOSS_HOME/standalone/log/server.log" | grep -iE 'ssl|https|UT005'

握手用 OpenSSL 三连。据 OpenSSL 文档,-servername 用于在 ClientHello 中发送 SNI 扩展;同 IP 多域名时省略它会拿到默认证书,后续校验必然失败。

# 2) 证书链与校验结论;</dev/null 防止交互挂起
openssl s_client -connect www.example.com:8443 
  -servername www.example.com -showcerts </dev/null
# 期望:Verify return code: 0 (ok)

# 3) 解析叶子证书的 SAN、签发者与有效期
openssl s_client -connect www.example.com:8443 -servername www.example.com </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName
# subject=CN = www.example.com
# issuer=C = US, O = Let's Encrypt, CN = R3
# notAfter=Mar  1 12:00:00 2026 GMT
# X509v3 Subject Alternative Name:
#     DNS:www.example.com, DNS:example.com

非 0 返回值就是定位线索:20 (unable to get local issuer certificate) 通常是中间证书缺失,10 (certificate has expired) 是过期,62 (hostname mismatch) 是 SAN 不含实际访问域名。

# 4) 应用层验证;若前面有 Nginx/F5 做 443 映射,把端口换成 443
curl -vI https://www.example.com:8443 --tlsv1.2 2>&1 
  | grep -E 'SSL certificate verify|HTTP/|expire'
# *  SSL certificate verify ok.
# < HTTP/1.1 200 OK        (302 也表示应用已接管请求)

# 5) HSTS 是否按预期下发(Undertow 可用 header filter 注入 max-age=31536000; includeSubDomains)
curl -sI https://www.example.com:8443 | grep -i strict-transport-security
# 6) 回查 keystore:alias、有效期、链长度必须与 server-identity / ssl-context 一致
#    EAP 7.4 默认走 Elytron key-store(application.keystore,PKCS12),keytool 会自动识别类型
keytool -list -v -keystore "$JBOSS_HOME/standalone/configuration/keystore.jks" 
  -storepass changeit -alias jboss 
  | grep -E 'Alias name|Valid from|Certificate chain length'
# Alias name: jboss
# Valid from: ... until: ...
# Certificate chain length: 2   ← 值为 1 说明中间证书没导入

链长度为 1 时,Java 客户端会抛 javax.net.ssl.SSLHandshakeException: PKIX path building failed,而 curl 走系统信任库可能反而正常——这正是“浏览器能开、程序连不上”的常见成因。

# 7) 协议面:TLS 1.3 必须成功,TLS 1.1 必须失败
openssl s_client -connect www.example.com:8443 -servername www.example.com -tls1_3 </dev/null 
  | grep -E 'Protocol|Cipher'
# Protocol: TLSv1.3
openssl s_client -connect www.example.com:8443 -tls1_1 </dev/null
# 期望:alert protocol version 或 handshake failure

# 8) 套件枚举,内部环境用它兜底
nmap --script ssl-enum-ciphers -p 8443 www.example.com

WildFly 31 的 https-listener 中 enabled-protocols 默认为空,即沿用 JVM 默认(JDK 11 及以上为 TLSv1.2、TLSv1.3);要显式收紧需在管理 CLI 中设为 TLSv1.2,TLSv1.3 并 reload。

验证手段 命令要点 检查目标 失败时的典型信号
openssl s_client -servername + </dev/null 握手、SNI、链完整性 Verify return code: 20 / 21
openssl x509 管道解析叶子证书 SAN、有效期 hostname mismatch(62)
curl -vI --tlsv1.2 应用是否真正响应 curl: (60) SSL certificate problem
keytool -list -v 直读 keystore alias、链长度、指纹 Certificate chain length: 1
nmap ssl-enum-ciphers 端口扫描 协议与套件暴露面 出现 TLSv1.0/1.1、RC4、3DES

判断 jboss ssl证书安装 是否真正生效,还要看外部视角:浏览器 DevTools → Security 面板核对证书链与 SAN 是否与命令行一致;对外站点再跑一次 SSL Labs 评级(仅对 443 有效,内部 8443 无法评级)。内部环境至少用 openssl 与 nmap 双检——单看一个 curl 返回 200,既发现不了中间证书缺失,也发现不了弱套件仍在协商。

JBoss 6/7/8 与 WildFly 的差异:老 server.xml 怎么迁移

这是迁移时最常见的翻车点:把 JBoss 6 的 server.xml 整段拷进 EAP 7.4,重启后 8443 端口根本不监听。原因是 JBoss 7 之后已经没有 JBoss Web 的 server.xml 了——AS 5/6 用的是 Tomcat 派生的 jbossweb.sar,EAP 6/AS 7 改成 web 子系统,EAP 7+ 换成 undertow 子系统。做 JBoss SSL 证书安装前,先确认你的实例属于哪一代。

老配置长这样(AS 5/6,文件路径 $JBOSS_HOME/server/default/deploy/jbossweb.sar/server.xml):

<!-- JBoss AS 5/6:Tomcat 风格 Connector,密码明文写在同一文件里 -->
<Connector protocol="HTTP/1.1" port="8443"
           SSLEnabled="true" scheme="https" secure="true"
           clientAuth="false"
           keystoreFile="${jboss.server.home.dir}/conf/jboss.jks"
           keystorePass="changeit" />
版本 SSL 配置位置 关键元素 子系统命名空间
JBoss AS 5/6 jbossweb.sar/server.xml <Connector SSLEnabled="true" keystoreFile=… keystorePass=…> 无(Tomcat 式 XML)
AS 7 / EAP 6 standalone.xml 的 web 子系统 <connector name="https"><ssl key-alias certificate-key-file password/> urn:jboss:domain:web:1.x
EAP 7.4.x undertow 子系统 https-listener security-realm=… 或 ssl-context=… urn:jboss:domain:undertow:12.0
WildFly 31 同上,但推荐 Elytron ssl-context(server-ssl-context) urn:jboss:domain:undertow:14.0

注意 WildFly 25 起已移除 legacy security 子系统,但 core-service=management/security-realm 仍在,https-listener 的 security-realm 属性因此还能用;生产环境据 WildFly 官方文档建议改用 Elytron 的 server-ssl-context,以便集中管理协议版本、证书吊销与密钥轮换(TLS 1.3 定义见 RFC 8446)。

EAP 7.4 迁移的完整 CLI 序列(standalone 模式,先跑测试实例):

# 0) 回滚基线:备份 + 纳入 git
cp $JBOSS_HOME/standalone/configuration/standalone.xml{,.bak}

# 1) 连接管理 CLI(EAP 7.4 / WildFly 31 通用)
$JBOSS_HOME/bin/jboss-cli.sh --connect

# 2) 用 management security-realm 挂 keystore(等价于老 server.xml 的 keystoreFile/Pass)
/core-service=management/security-realm=UndertowRealm:add()
/core-service=management/security-realm=UndertowRealm/server-identity=ssl:add(
  keystore-path=jboss.jks, keystore-relative-to=jboss.server.config.dir,
  keystore-password=changeit, alias=jboss)
# alias 默认 jboss;keystore-relative-to 默认 jboss.server.config.dir

# 3) 建 https-listener(socket-binding 默认 https=8443)
/subsystem=undertow/server=default-server/https-listener=https:add(
  socket-binding=https, security-realm=UndertowRealm)

# 4) 生效
:reload

若走 Elytron(WildFly 31 首选),把第 2、3 步换成:

/subsystem=elytron/key-store=jbossKS:add(path=jboss.jks, relative-to=jboss.server.config.dir,
  type=JKS, credential-reference={clear-text=changeit})   # type 默认 JKS
/subsystem=elytron/key-manager=jbossKM:add(key-store=jbossKS, algorithm=PKIX)
/subsystem=elytron/server-ssl-context=jbossSSC:add(key-manager=jbossKM,
  protocols=["TLSv1.3","TLSv1.2"])   # 默认即 TLSv1.3,TLSv1.2,可显式写死
/subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=jbossSSC)
:reload

跨版本复制 standalone.xml 片段会直接失败:undertow:14.0 的命名空间在 EAP 7.4 未注册,启动阶段抛 XMLStreamException: ParseError;而 https-listener 引用了不存在的 realm 时,CLI 返回 "outcome" => "failed"、WFLYCTL0184: New missing/unsatisfied dependencies 并 rolled-back。所以顺序固定为:备份 → 导入 keystore → CLI 逐条写入 → :reload → 回滚用 standalone.xml.bak 或 git diff 还原。下一步的 keystore 生成与 CSR 提交流程,与本节的 JBoss SSL 证书安装路径是同一套 keytool 参数。

生产加固:TLS 协议、密码套件、OCSP 与证书续期

把证书装上只是起点,真正决定线上安全评级的是协议版本、套件白名单和续期链路是否闭环。下面这些配置在 JBoss EAP 7.4 与 WildFly 31 的 Elytron 子系统上通用,默认值以官方管理模型为准,改完记得执行 :reload 使 ssl-context 生效。

协议:只留 TLS 1.2 与 1.3。据 RFC 8446,TLS 1.3 精简了握手并移除了 RSA 密钥传输、CBC 等遗留算法;TLS 1.0/1.1 已被 RFC 8996 正式弃用。Elytron 的 server-ssl-context 未设置 protocols 时沿用 JVM 默认值(JDK 11+ 的 jdk.tls.disabledAlgorithms 已默认禁用 TLSv1/1.1),但显式声明更可控。legacy 的 jboss-web 连接器则用 <ssl protocol="TLSv1.2,TLSv1.3"/>。

# 适用:JBoss EAP 7.4 / WildFly 31,Elytron 子系统
# protocols 未设置时走 JVM 默认;显式锁定 1.2+1.3,取值区分大小写
/subsystem=elytron/server-ssl-context=httpsSSC:write-attribute(name=protocols,value=["TLSv1.2","TLSv1.3"])
# cipher-suite-filter 默认值 DEFAULT;用 : 分隔白名单,TLS1.3 套件走 cipher-suite-names
/subsystem=elytron/server-ssl-context=httpsSSC:write-attribute(name=cipher-suite-filter,value="TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256:TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384:TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256:TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256")
/subsystem=elytron/server-ssl-context=httpsSSC:write-attribute(name=cipher-suite-names,value="TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256")
# use-cipher-suites-order 默认 false(跟客户端顺序);设为 true 让服务端优先选 AEAD
/subsystem=elytron/server-ssl-context=httpsSSC:write-attribute(name=use-cipher-suites-order,value=true)
:reload

套件:对齐 Mozilla intermediate。Mozilla SSL Configuration Generator 的 intermediate 档位要求 ECDHE 密钥交换 + AEAD 加密,并保留少量 CBC 套件兼容旧客户端。静态 RSA 密钥交换(TLS_RSA_WITH_*)没有前向保密,建议一并剔除。

类别 示例套件 处置 原因
ECDHE + AEAD TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 / TLS_AES_128_GCM_SHA256 保留 前向保密 + AEAD
ECDHE + CBC TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 可选保留 兼容老客户端,注意 Lucky13
静态 RSA TLS_RSA_WITH_AES_128_GCM_SHA256 建议禁用 无前向保密
RC4 TLS_RSA_WITH_RC4_128_SHA 禁用 RFC 7465 明令禁止
3DES TLS_RSA_WITH_3DES_EDE_CBC_SHA 禁用 Sweet32 生日攻击
EXPORT 级 TLS_RSA_EXPORT_WITH_RC4_40_MD5 禁用 40 位密钥等同明文

OCSP/CRL 的边界要说清。JBoss 作为服务器不主动做 OCSP 装订,Undertow 至今没有对应实现,需要 Stapling 就放到前端 Nginx(ssl_stapling on;)或 Apache(SSLUseStapling on)。JBoss 作为客户端校验上游 HTTPS 服务时,可在 trust-manager 上启用吊销检查,ocsp 属性默认 off,可设为 on/required:

# 仅对“JBoss 主动发起 TLS 连接”的场景生效;ocsp 默认 off
/subsystem=elytron/trust-manager=serverTM:write-attribute(name=ocsp,value=required)

续期:别只导入 fullchain。Let’s Encrypt 证书有效期 90 天,据其官方文档推荐在到期前 30 天续期。certbot 默认每次续期生成新私钥,若只 keytool -importcert 导证书,keystore 里的私钥与证书将不匹配,握手直接报 no cipher suites in common 或 certificate_unknown。正确做法是用 key + fullchain 重建 PKCS12,再 reload:

# 存为 /etc/letsencrypt/renewal-hooks/deploy/reload-jboss.sh 并 chmod 700
#!/usr/bin/env bash
set -euo pipefail
DOMAIN=app.example.com
KS=/opt/jboss/keystore/server.p12
openssl pkcs12 -export -name server 
  -in "/etc/letsencrypt/live/$DOMAIN/fullchain.pem" 
  -inkey "/etc/letsencrypt/live/$DOMAIN/privkey.pem" 
  -out "$KS" -passout "env:JBOSS_KEYSTORE_PASS"
chown jboss:jboss "$KS" && chmod 640 "$KS"
# 单机 reload;集群/域模式逐节点执行,或由域控制器做滚动重启
su - jboss -c '/opt/jboss/bin/jboss-cli.sh --connect --command=":reload"'

监控:一条命令判断是否临近过期。-checkend 的返回码可直接喂给告警脚本,0 表示指定秒数内不过期,1 表示将要过期。30/15/7 天分别对应 2592000、1296000、604800 秒:

# 前面加 echo | 避免 s_client 卡在交互等待;-servername 传 SNI
echo | openssl s_client -connect app.example.com:8443 -servername app.example.com 2>/dev/null 
  | openssl x509 -noout -checkend 2592000 -enddate
# 输出示例:Not After : Jul 18 09:12:44 2025 GMT   (退出码 0)

密钥管理与 HSTS。keystore 权限设 640、属主为 JBoss 运行用户,这是最低要求;密码不要明文进 Git,Elytron 属性支持 ${env.VAR} 表达式替换,也可改用 credential-store。对外站点再补一个 HSTS 响应头,max-age 从 300 秒起步逐步拉到一年,避免回滚困难:

# 环境变量注入,避免明文密码写进 standalone.xml 或 CLI 脚本
/subsystem=elytron/key-store=serverKS:write-attribute(name=credential-reference,value={clear-text="${env.JBOSS_KEYSTORE_PASS}"})
# HSTS:先 max-age=300 验证,稳定后改 31536000
/subsystem=undertow/configuration=filter/response-header=hsts:add(header-name=Strict-Transport-Security,header-value="max-age=31536000; includeSubDomains")
/subsystem=undertow/server=default-server/host=default-host/filter-ref=hsts:add()

做完这套加固,一次完整的 JBoss SSL 证书安装才算收尾:证书链正确只是入场券,协议与套件的白名单、续期脚本的原子性、到期告警的闭环,才是长期不出事故的部分。

默认 https socket-binding 是 8443;改 需 root 或 authbind 启动。若不想改端口,可用 iptables -t nat -A PREROUTING -p tcp –dport 443 -j REDIRECT –to-port 8443,并确认防火墙放行 443。

Tomcat 改 server.xml 的 Connector;JBoss EAP 7.4/WildFly 31 改 undertow https-listener + security-realm 或 Elytron,不再读 server.xml。老 JBoss 6 才接近 Tomcat 的 Connector 写法,迁移时不能照抄。

核对 standalone.xml 的 keystore-password 与 keytool 生成时的 -storepass;PKCS12 还要让 key-password 等于 storepass。改完执行 jboss-cli.sh –connect –command=':reload',再查 server.log 是否还有 SSL 初始化异常。

CN 写主域名,SAN 必须包含所有访问域名,如 DNS:www.example.com,DNS:example.com。现代浏览器按 RFC 6125 以 SAN 为准,只有 CN 会报 No subject alternative names present。

内部系统或 API 用 DV 即可,约 ¥0-300/年、10 分钟签发;对外门户、需要组织身份展示选 OV,约 ¥800-3000/年、1-3 个工作日;EV 约 ¥3000-8000/年,浏览器 UI 差异已弱化。

可以,把 fullchain.pem 与 privkey.pem 用 openssl pkcs12 -export 转成 PKCS12,再让 Elytron key-store 读取。90 天续期用 certbot renew –deploy-hook 导入并 reload,注意集群逐节点执行。

用 openssl s_client -connect host:8443 -servername host -showcerts 看 serial/有效期,和 keytool -list -v -alias jboss 对比。再查 server.log 的 reload 时间与 ss -lntp 端口,确认没有旧进程占用 8443。


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

内容审核

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