WebSphere SSL 证书配置实操指南:iKeyman、wsadmin 与 CWPKI0022E 排查
WebSphere SSL 证书配置的核心是把 cell/node/server 三级 SSL 配置库指向的 key.p12 与 trust.p12 换成含完整证书链的文件,默认类型 PKCS12、默认密码 WebAS,改完执行 syncNode 并重启 server1。 WAS 8.5.5 默认 TLSv1.2,WAS 9.0.5.5+ 才支持 TLSv1.3;用 AdminTask.createSSLConfig 的 -sslProtocol TLSv1.2 显式锁定协议,可避免端点继承到旧配置。 导入证书链用 keytool -importcert 把根证书导入 trust.p12,用 keytool -importkeystore 把叶证书加中间证书导入 key.p12,别名建议 was-prod-2025,链长保持 2-3。 报 CWPKI0022E 时先查 trust.p12 是否缺对端 signer,再查端点 WC_defaulthost_secure 绑定的 sslConfig 是否为新配置,最后确认是否执行过 syncNode。 验证用 openssl s_client -connect host:9443 -tls1_2 -showcerts,看到 Verify return code: 0 (ok) 且 Certificate chain 至少 2 张,才算 WebSphere SSL 证书配置生效。
问:WebSphere SSL 证书配置为什么总在握手阶段失败? 因为 WAS 并不是只改一个 server.xml 文件,它实际涉及三层对象:SSL 配置库、密钥库与信任库、端点绑定。只要其中任何一层没有生效,TCP 连接虽然能建立,TLS 仍会在 Certificate 或 Finished 阶段失败。
| 层级 | 默认对象/别名 | 默认文件/端口 | 常见误改 |
|---|---|---|---|
| SSL 配置库 | SSLConfig:CellDefaultSSLSettings、NodeDefaultSSLSettings、DefaultSSLSettings |
cell/node 级配置,不是 server.xml | 只改应用服务器,漏 cell 级 |
| 密钥库/信任库 | key.p12、trust.p12 |
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/<cell>/nodes/<node>/ |
把 CA 装进 key.p12,而非 trust.p12 |
| 端点绑定 | WC_defaulthost_secure=9443、WC_adminhost_secure=9043 |
端点配置 | 换证书后未重启或未同步 |
版本差异要先记住:WAS 8.5.5 起默认 storetype=PKCS12、默认密码 WebAS;WAS 7 及更早默认 JKS,升级后可能仍是 JKS。用 iKeyman 或 keytool 打开的都是同一份 trust.p12,先确认对端 signer 是否存在:
# 适用 WAS 8.5.5/9.0(默认 PKCS12/密码 WebAS);WAS 7 把 -storetype 改为 JKS
CELL=你的Cell名
NODE=你的Node名
TRUST=/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/$CELL/nodes/$NODE/trust.p12
keytool -list -v -keystore "$TRUST" -storetype PKCS12 -storepass WebAS
| grep -E 'Alias name|Owner|Issuer'
根因一:信任库缺对端 signer。 WAS 只信任 trust.p12 中的证书,不自动读取操作系统的 /etc/pki/ca-trust。对端换证书后未导入,典型报错是 PKIX path building failed;IBM Documentation 对 CWPKI0022E 的说明也会写出“signer … was sent from target host … may need to be added to local trust store”。把对端证书导入 trust.p12 后,要重启节点并同步。
根因二:协议或密码套件不匹配。 WAS 8.5.5.9+ 默认 TLSv1.2,客户端只发 TLSv1.0 会收到 handshake_failure;据 RFC 8446,TLSv1.3 需要 WAS 9.0.5.5+ 且客户端同样开启。用 wsadmin 查看 sslProtocol、keyStoreName、trustStoreName:
# 适用 WAS 8.5.5/9.0;在 profile/bin 下执行;默认 SOAP 端口 8879(dmgr)
./wsadmin.sh -lang jython -username admin -password '***'
-c "print AdminTask.getSSLConfig('-alias CellDefaultSSLSettings')"
根因三:证书 SAN 与访问主机名不一致。 Java 客户端默认启用主机名验证,证书只写 CN=was.example.com 而实际访问 10.0.0.12 时会报 No subject alternative names present;据 RFC 6125,主机名验证以 SAN 为准。用 OpenSSL 查:
# OpenSSL 1.0.2+ 均可;-noout -text 输出中找 Subject Alternative Name
openssl x509 -in was.crt -noout -text | grep -A1 "Subject Alternative Name"
问:dmgr 控制台改了 cell 级 SSL,为什么应用服务器还失败? 因为没执行 syncNode,节点上的 trust.p12 仍是旧文件,表现为控制台显示新配置、应用服务器仍握手失败,这也是 WebSphere SSL 证书配置最隐蔽的根因。在节点 profile 的 bin 下执行:
# 适用 WAS 8.5.5/9.0;8879 为 dmgr SOAP 端口默认值
./syncNode.sh dmgr.example.com 8879 -username admin -password '***'
排查顺序建议:先看报错里有没有 CWPKI0022E/PKIX,再用 keytool -list 查 trust.p12;若是 handshake_failure,就查 sslProtocol;若是 No subject alternative names present,就直接看 SAN。这样能把 WebSphere SSL 证书配置拆成可验证的三层,而不是反复重启。
WebSphere SSL 证书配置的完整实操步骤(6 步,从备份到重启)
WebSphere 的 SSL 配置分散在三层:密钥库文件(key.p12/trust.p12)、SSL 配置库(SSLConfig 别名)以及端点绑定(WC_defaulthost_secure 等)。任何一层漏改,重启后都会以 CWPKI0022E: SSL HANDSHAKE FAILURE 的形式报出来。下面 6 步按“先确认能力、再备份、后变更”的顺序执行,路径以 WAS 9.0.x 默认安装 /opt/IBM/WebSphere/AppServer 为例。
步骤 1:确认版本与补丁,别对着不支持 TLSv1.3 的版本配 TLSv1.3。先用版本脚本确认实际补丁级别,再对照下表决定 -sslProtocol 的取值。IBM 官方文档明确指出 TLSv1.3 支持从 9.0.5.5 起提供,8.5.5 全系列最高只到 TLSv1.2。
# 输出形如 "Version 9.0.5.11" 或 "Version 8.5.5.22",末段即补丁号
/opt/IBM/WebSphere/AppServer/bin/versionInfo.sh | head -5
| WAS 版本 | 可用的最高协议 | 默认 SSL 配置的 sslProtocol | 注意 |
|---|---|---|---|
| 8.5.5.0 – 8.5.5.x | TLSv1.2 | SSL_TLSv2(含 TLSv1.0/1.1/1.2) | 无 TLSv1.3,配置后启动即报握手失败 |
| 9.0.0 – 9.0.5.4 | TLSv1.2 | SSL_TLSv2 | 仍需显式收紧到 TLSv1.2 |
| 9.0.5.5 及以上 | TLSv1.3 | SSL_TLSv2 | 取值 TLSv1.3 或 TLSv1.2,TLSv1.3 |
步骤 2:备份密钥库并导出当前 SSL 配置。密钥库默认密码是 WebAS(安装时未改的情况下),默认算法为 PKCS12。除了配置文件,还必须到控制台“端口”页核对每个端点的实际绑定,因为 listSSLConfigs() 只列出配置库,不反映哪个端口在用哪个别名。
# 备份密钥库与信任库(默认位于 profile 的 config/cells/.../nodes/.../ 下)
mkdir -p /backup/$(date +%F)
cp -a key.p12 trust.p12 /backup/$(date +%F)/
# 导出变更前的 SSL 配置清单,用于回滚比对
/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin/wsadmin.sh -lang jython
-c 'AdminTask.listSSLConfigs()' > /backup/$(date +%F)/sslconfig-before.txt
步骤 3:生成密钥对与 CSR。别名建议带年份,便于轮换时区分。注意 -dname 中的 CN 必须与客户端访问的域名一致,否则即使链路正常也会触发主机名校验失败。
cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/config/cells
keytool -genkeypair -alias was-prod-2025 -keyalg RSA -keysize 2048
-sigalg SHA256withRSA -keystore key.p12 -storetype PKCS12 -storepass WebAS
-dname 'CN=was.example.com, O=Example, C=CN'
# 生成 CSR 交 CA 签发(Let's Encrypt、企业内 CA 均可)
keytool -certreq -alias was-prod-2025 -keystore key.p12 -storetype PKCS12
-storepass WebAS -file was-prod-2025.csr
步骤 4:导入证书链,先信任库后密钥库。顺序反了会报 keytool error: java.lang.Exception: Failed to establish chain from reply。链长控制在 2–3 级(叶证书 + 中间证书,根证书留在 trust.p12),据 Let’s Encrypt 与 RFC 8446 的实践,多带根证书只会增大握手包。
# 4a. 根证书进信任库
keytool -importcert -alias root-ca -file root.crt -keystore trust.p12
-storetype PKCS12 -storepass WebAS -noprompt
# 4b. 叶证书与中间证书拼接成完整链,回填到同一别名
cat was.example.com.crt intermediate.crt > fullchain.crt
keytool -importcert -alias was-prod-2025 -file fullchain.crt -keystore key.p12
-storetype PKCS12 -storepass WebAS -noprompt
# 4c. 验证链长与有效期
keytool -list -v -keystore key.p12 -storetype PKCS12 -storepass WebAS
-alias was-prod-2025 | grep -E "Certificate chain length|Valid from"
步骤 5:创建或修改 SSL 配置。securityLevel 默认即为 HIGH,取值范围 HIGH/MEDIUM/LOW,生产环境不要下调。
# 新建配置(别名 wasTLS12)
wsadmin.sh -lang jython -c "AdminTask.createSSLConfig('[-alias wasTLS12
-keyStoreName NodeDefaultKeyStore -trustStoreName NodeDefaultTrustStore
-sslProtocol TLSv1.2 -clientAuth false -securityLevel HIGH]'); AdminConfig.save()"
# 已有配置改为修改:只动协议与安全级别
wsadmin.sh -lang jython -c "AdminTask.modifySSLConfig('[-alias wasTLS12
-sslProtocol TLSv1.2 -securityLevel HIGH]'); AdminConfig.save()"
步骤 6:绑定端点、同步、重启、握手验证。控制台路径:服务器 > 服务器类型 > WebSphere Application Server > server1 > 端口 > WC_defaulthost_secure > SSL 配置选 wasTLS12。改完必须同步到节点,否则节点仍用旧配置启动。
# dmgr 侧同步(8879 为默认 SOAP 端口)
/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin/syncNode.sh dmgr-host 8879
# 重启应用服务器
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin/stopServer.sh server1
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin/startServer.sh server1
# 用 OpenSSL 做初步握手,确认协商出的协议与证书链
openssl s_client -connect was.example.com:9443 -servername was.example.com
-tls1_2 -showcerts /dev/null | openssl x509 -noout -subject -dates -issuer
若这一步返回 verify error:num=20:unable to get local issuer certificate,说明中间证书没进 key.p12;若返回 no protocols available,多半是步骤 1 的补丁级别与步骤 5 的 -sslProtocol 不匹配——这两类现象最终都会在服务端日志里落成 CWPKI0022E,排查时优先看 SystemOut.log 中紧随其后的 CWPKI 明细行,而不是只看异常标题。
WebSphere SSL 证书配置的命令与配置片段:wsadmin、keytool、iKeyman
刚用 wsadmin 建好 SSL 配置、重启后却发现配置“消失”,或者 key.p12 里只有一张叶证书导致浏览器报“证书链不完整”?下面按“配置库—密钥库—图形界面—抓包调试”四步,给出可直接复制的命令片段。
怎么用 wsadmin 一次列出并核对所有 SSL 配置?
# 进入 wsadmin(WAS 8.5.5 / 9.0 通用,profile 名按实际替换)
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin/wsadmin.sh -lang jython -user wasadmin -password '******'
# 1) 列出当前 cell 中所有 SSL 配置别名
print AdminTask.listSSLConfigs()
# 输出形如:[CellDefaultSSLSettings NodeDefaultSSLSettings wasTLS12]
# 2) 查看单个配置的协议、密钥库、信任库
print AdminTask.getSSLConfig('[-alias wasTLS12]')
# 3) 新建配置时必须显式指定协议,并立刻保存
AdminTask.createSSLConfig('[-alias wasTLS12 -keyStoreName CellDefaultKeyStore -trustStoreName CellDefaultTrustStore -sslProtocol TLSv1.2]')
AdminConfig.save() # 关键行:不执行 save(),配置只存在于当前会话,重启即丢
据 IBM Documentation 对 createSSLConfig 的说明,-sslProtocol 省略时会继承父级(默认 CellDefaultSSLSettings)的设置,而父级在 8.5.5 早期版本中仍可能是 SSL_TLS。因此生产环境务必显式写 -sslProtocol TLSv1.2,否则同一 cell 里新旧节点协议会不一致,表现为部分节点握手成功、部分节点报 CWPKI0022E: SSL HANDSHAKE FAILURE。
keytool 怎么确认 p12 里是完整链而不是一张叶证书?
# WAS 默认密钥库 key.p12,类型 PKCS12,默认密码 WebAS(WAS 8.5.5 起默认 PKCS12)
keytool -list -v -keystore key.p12 -storetype PKCS12 -storepass WebAS
# 判定标准:
# Entry type: PrivateKeyEntry ← 私钥条目,服务端证书必须在此
# Certificate chain length: 3 ← 叶 + 中间 + 根,2 表示缺根或仅中间
# Valid from: ... until: ... ← 核对有效期,避免导入过期证书
# 信任库(trust.p12)里看到的应为 Entry type: trustedCertEntry
keytool -list -v -keystore trust.p12 -storetype PKCS12 -storepass WebAS
如何把 Let’s Encrypt 的 fullchain 完整导入 key.p12?
# 先把 PEM 链转成 PKCS12(临时口令仅用于传输)
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem
-name was-prod-2025 -out fullchain.p12 -passout pass:TempPwd123
# 整库导入到 WAS 使用的 key.p12,保留别名
keytool -importkeystore
-srckeystore fullchain.p12 -srcstoretype PKCS12 -srcstorepass TempPwd123 -srcalias was-prod-2025
-destkeystore key.p12 -deststoretype PKCS12 -deststorepass WebAS -destalias was-prod-2025
只导入叶证书是最常见的坑:服务端握手时只发一张证书,客户端无法补链,Java 客户端报 PKIX path building failed,浏览器则显示“证书链不完整”。据 Let’s Encrypt 文档,其 fullchain.pem 已包含中间证书,导入时应整链导入而非只取 cert.pem。
| 方式 | 适用场景 | 优势 | 局限 |
|---|---|---|---|
iKeyman(ikeyman.sh) |
单机首次导入、需要肉眼核对证书链 | 图形化展示链结构,支持 PKCS12/JKS/CMS | 无法脚本化、无审计记录、远程需 X11 转发 |
| keytool | 批量节点、CI/CD、容器镜像构建 | 命令可复现、可 diff、与 OpenJDK/IBM JDK 通用 | 不改 WAS 配置库,端点绑定仍需 wsadmin |
| wsadmin(AdminTask) | SSL 别名、协议版本、端点绑定 | 幂等、可 AdminConfig.save() 落库 |
不直接修改密钥库内容,须与 keytool 配合 |
iKeyman 在 9.0 里怎么打开?执行 /opt/IBM/WebSphere/AppServer/bin/ikeyman.sh,打开 key.p12 时类型选 PKCS12、密码填 WebAS;在“个人证书”中导入 .p12 或 .pem 链,在“签名者证书”中导入根证书与中间证书。iKeyman 适合一次性操作,批量环境优先用上面的 keytool 脚本。
握手失败时怎么抓现场?在 server1 的 JVM 参数中临时追加 -Djavax.net.debug=ssl:handshake,SystemOut.log 会输出 Found trusted certificate 或 alert handshake_failure,据此判断是协议版本不匹配还是信任库缺链。生产环境用完即删——该开关在高并发下可让 SystemOut.log 每小时增长数百 MB。
IBM JDK 的 cacerts 能当 WAS 的 truststore 吗?不能想当然。WAS 默认使用配置库中的 trust.p12,只有显式设置 -Djavax.net.ssl.trustStore 才会改变,但这样会绕过端点级 SSL 配置(com.ibm.ssl.trustStore 属性),不建议在生产使用。
WebSphere SSL 证书配置参数对比与方案选型表
“同一个 WebSphere 环境,为什么同事说密钥库是 key.p12,我这边却是 key.jks?”——因为密钥库类型、协议级别和作用域这三项参数在 WAS 7 到 WAS 9 之间都改过默认值。下面用四张对比表把选型说清楚,每张表后面给出可直接执行的命令。
问题一:key.p12 和 trust.p12 该用 PKCS12、JKS 还是 JCEKS?
据 IBM Knowledge Center 的 SSL configurations 文档,WAS 8.5.5 起新建 profile 的默认密钥库类型已由 JKS 改为 PKCS12,默认密码统一为 WebAS,文件位于 <profile>/etc/key.p12 与 trust.p12。JCEKS 虽然能存证书,但它的设计目标是保护对称密钥(如 WAS 的 LTPA 密钥),用来做 SSL 密钥库会在链校验时踩坑,不建议。
| 对比项 | PKCS12(推荐) | JKS(旧环境) | JCEKS |
|---|---|---|---|
| WAS 默认版本 | 8.5.5 及以上 | 7.0 及更早 | 非 SSL 默认类型 |
| 默认密码 | WebAS | WebAS | WebAS |
| 证书链支持 | 完整链,中间证书可随私钥一起存 | 有限,导入时易丢中间证书 | 支持,但为对称密钥设计 |
| 工具兼容 | keytool、openssl、iKeyman | keytool、iKeyman | keytool、iKeyman |
| 迁移建议 | 新环境直接用 | 升级后逐步转 PKCS12 | 不要作为 SSL 密钥库 |
从旧 JKS 迁移到 PKCS12 只需一条 keytool -importkeystore,注意 -deststorepass 必须写成 WAS 配置里登记的密码,否则启动时会报 CWPKI0022E: SSL HANDSHAKE FAILURE 一类的密钥库打不开错误:
# 将旧 JKS 个人证书库转为 PKCS12;WAS 8.5.5+ 的 key.p12 默认密码为 WebAS
# 适用:keytool 来自 JDK 8+(WAS 自带 IBM JDK 的 keytool 参数一致)
keytool -importkeystore
-srckeystore /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/etc/key.jks
-srcstoretype JKS -srcstorepass WebAS
-destkeystore /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/etc/key.p12
-deststoretype PKCS12 -deststorepass WebAS
# 导入根 CA 到信任库,-storetype 必须与 WAS 控制台里登记的“密钥库类型”完全一致
keytool -importcert -trustcacerts -alias rootca -file /tmp/root_ca.pem
-keystore /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/etc/trust.p12
-storetype PKCS12 -storepass WebAS -noprompt
问题二:cell、node、server、endpoint 四层配置,到底哪个生效?
WebSphere 的 SSL 配置是逐层继承的,排查 websphere ssl证书配置 问题时按 endpoint > server > node > cell 的顺序自下而上确认实际生效值,不要一上来就改 cell 级。
| 作用域 | 配置对象 | 影响范围 | 优先级 |
|---|---|---|---|
| endpoint | 端点(如 WC_defaulthost)绑定的 SSL 配置别名 | 单个端口 | 最高 |
| server | DefaultSSLSettings | 单台服务器 | 高 |
| node | NodeDefaultSSLSettings | 单个节点 | 中 |
| cell | CellDefaultSSLSettings | 所有节点 | 最低 |
# wsadmin -lang jython,适用 WAS 8.5.5 / 9.0.x
# 1) 列出所有 SSL 配置别名,确认待查对象存在
print AdminTask.listSSLConfigs('[-listAll true]')
# 2) 端点级优先级最高:返回空串才说明未绑定,会回退到 server/node/cell 默认值
ep = AdminConfig.getid('/Cell:cell01/Node:node01/Server:server1/EndPoint:WC_defaulthost/')
print 'endpoint sslConfig ->', AdminConfig.showAttribute(ep, 'sslConfig')
问题三:协议与安全级别怎么选?
PCI DSS 要求对外服务使用 TLSv1.2 及以上,TLSv1.0/1.1 应关闭。WAS 8.5.5 选 TLSv1.2 即可;WAS 9.0.5.5 起可在同一 SSL 配置里让 TLSv1.2 与 TLSv1.3 并存(RFC 8446)。注意:只要还有只支持 TLSv1.0 的老客户端,就不要直接禁用 TLSv1.2 换成纯 TLSv1.3。
| 安全级别 | 禁用内容 | 适用场景 |
|---|---|---|
| HIGH | SSLv3、RC4、DES/3DES | 公网、合规审计环境 |
| MEDIUM | 保留部分弱套件 | 必须兼容老系统的内网 |
| CUSTOM | 由 enabledCiphers 逐项指定 | 仅有明确兼容清单时才用,排错成本高 |
问题四:控制台、wsadmin、keytool、iKeyman 用哪个导入?
| 方式 | 适用场景 | 可重复性 | 注意 |
|---|---|---|---|
| 管理控制台 | 1–2 个节点的小环境 | 低 | 保存后需 syncNode 并重启 |
| wsadmin | 批量、多节点 | 高 | 脚本可纳入版本控制 |
| keytool | CI/自动化流水线 | 高 | 直接改 p12 文件,需重启生效 |
| iKeyman | 排障时可视化检查证书链 | 中 | 需图形环境 |
# 四条路径改的是同一批 key.p12 / trust.p12,改完必须同步并重启才生效
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin/syncNode.sh node01
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin/stopServer.sh server1 -username admin -password 你的密码
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin/startServer.sh server1
验证是否真正生效,别只看控制台:用 Mozilla SSL Configuration Generator 同级别的测试思路,在客户端跑 openssl s_client -connect host:9443 -tls1_2,看输出的 Protocol 与 Cipher 是否与所选安全级别一致;若握手仍失败且日志出现 CWPKI0022E,优先回头核对密钥库类型与别名,而不是继续调协议。
WebSphere SSL 证书配置常见报错与排查:CWPKI0022E、PKIX path building failed
为什么 WebSphere 的 SSL 报错总在握手阶段才暴露?因为 WAS 的 JSSE 实现把信任库校验推迟到实际建连时,配置写错(路径、scope、别名)在启动日志里往往只是一行 CWPKI 警告,真正炸出来是在应用首次调用对端或客户端首次连 9443 时。先记住一张对照表,按报错前缀直接定位:
| 报错标识 | 典型根因 | 先跑这条命令验证 |
|---|---|---|
| CWPKI0022E | trust.p12 里没有对端签发者(根/中间) | keytool -list -keystore trust.p12 -storepass WebAS |
| PKIX path building failed | 服务端未发送中间证书,链不完整 | openssl s_client -showcerts |
| Received fatal alert: handshake_failure | TLS 版本或密码套件无交集 | openssl s_client -tls1_2 / -tls1_3 |
| No subject alternative names present | 证书 SAN 缺少实际访问主机名 | openssl x509 -text | grep -A1 "Alternative" |
| CWPKI0820A / CWPKI0033E | keyStoreName 指向的路径在该节点不存在 | ls -l <profile>/etc/key.p12 |
CWPKI0022E: SSL HANDSHAKE FAILURE: A signer with SubjectDN … was sent from target host …,怎么处理?这是 WAS 作为 SSL 客户端时,对端返回的证书签发者不在本地信任库里。WAS 9.0 默认信任库是 <PROFILE_ROOT>/etc/trust.p12(PKCS12,默认密码 WebAS),必须把对端根证书和中间证书都导进去,只导叶子证书无效:
# 1) 抓取对端完整链(根 + 中间),WAS 8.5.5 / 9.0 通用
openssl s_client -connect peer.example.com:443 -servername peer.example.com
-showcerts </dev/null 2>/dev/null > peer-chain.pem
# 2) 导入默认信任库;-noprompt 免交互,别名建议用签发者 CN
# keytool 位于 $JAVA_HOME/bin,密码默认 WebAS(安装时未改的话)
keytool -importcert -alias peer-ca -file peer-chain.pem
-keystore /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/etc/trust.p12
-storetype PKCS12 -storepass WebAS -noprompt
# 3) 重启节点;DMGR 环境先 syncNode 再重启,避免配置回滚
./stopServer.sh server1 && ./startServer.sh server1
PKIX path building failed 和 CWPKI0022E 有什么区别?前者来自 JDK 原生 JSSE(javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target),说明链在中间证书处断了,Java 8u181 之后不再回退匹配 CN。据 Oracle JSSE Reference Guide,默认只信任 cacerts,WAS 通过自定义 trust store 覆盖。用下面命令看服务端到底发了几层:
openssl s_client -connect was.example.com:9443 -showcerts </dev/null 2>/dev/null
| grep -E "^(depth|verify|s:|i:)"
# 正常链长 2-3 层(depth=0 叶子、1 中间、2 根)
# 只出现 depth=0 即服务端未配置中间证书,需在 key.p12 侧补齐链
Received fatal alert: handshake_failure 该怎么拆?先分版本探测,不要一上来就翻 trace:
openssl s_client -connect was.example.com:9443 -tls1_2 </dev/null
openssl s_client -connect was.example.com:9443 -tls1_3 </dev/null
若 -tls1_2 成功而 -tls1_3 失败,说明 WAS 侧未启用 TLSv1.3 或补丁级别不足(TLSv1.3 需较新的 WAS 9.0.5.x fix pack,并在 SSL 配置里显式勾选);反之若 -tls1_2 失败,检查客户端是否只发 TLSv1.0——WAS 9.0 默认已禁用 TLSv1.0,这与 Mozilla Server Side TLS 指南的推荐方向一致。
CertificateException: No subject alternative names present 说明什么?证书里 CN 写的是主机名,但 SAN 为空或缺少实际访问地址。重新签发时务必把全部入口写进 SAN,例如 DNS:was.example.com, DNS:was.internal, IP:10.0.0.12,不要只依赖 CN。据 Let’s Encrypt 文档,其签发的证书自 2018 年起 SAN 必填,CN 仅作展示用途。
CWPKI0820A: The keyStore … does not exist 与 CWPKI0033E 怎么修?本质是 scope 不匹配:在 dmgr 上配了 node 级 SSL 配置,路径却是 dmgr 自己的 etc/key.p12。用 wsadmin 查实际值再核对文件:
# 查看指定 scope 的 SSL 配置(jython,WAS 9.0 自带)
/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin/wsadmin.sh -lang jython
-user admin -password '******'
-c "print AdminTask.getSSLConfig('-scopeName (cell):cell01:(node):node01')"
# 到对应节点确认文件真实存在
ls -l /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/etc/key.p12
SSL0222E: SSL Handshake Failed 但日志不给细节怎么办?先在 SystemOut.log 里筛 CWPKI 前缀拿到真正的根因,再临时开 trace:
grep -n "CWPKI" .../logs/server1/SystemOut.log | tail -20
# 控制台路径:Troubleshooting > Logs and Trace > server1 > Diagnostic Trace
# 或在 wsadmin 中动态开启(无需重启)
AdminControl.invoke(AdminControl.completeObjectName('type=TraceService,process=server1,*'),
'setTraceSpecification', 'com.ibm.ws.security.ssl.*=all:com.ibm.websphere.ssl.*=all')
trace 默认按 50 MB 轮转、仅保留有限个历史文件,复现后立刻把级别改回 *=info,否则高并发下几小时就能写满磁盘。这也是 WebSphere SSL 证书配置排查中最容易被忽略的一步:先定性(信任库 / 链 / 协议 / 主机名),再开 trace 定量,顺序反了只会得到一堆无法定位的堆栈。
如何验证 WebSphere SSL 证书配置已生效?5 个可复现检查
WebSphere 的 SSL 配置”改完不生效”,十次里有八次不是配置没保存,而是端点级 SSL 配置覆盖了别名级配置——你在 wasTLS12 里把 sslProtocol 设成 TLSv1.2,但 WC_defaulthost_secure 端口仍绑着 NodeDefaultSSLSettings。下面 5 个检查由外到内,全部可复现。环境:WebSphere Application Server 传统版 8.5.5.x / 9.0.5.x,IBM SDK 8,命令在 <WAS_HOME>/bin 与 <WAS_HOME>/java/bin 下执行。
检查一:openssl 从外部看握手与证书链
# -servername 不能省,否则 SNI 场景下可能拿到默认主机证书
openssl s_client -connect was-host:9443 -servername was-host -tls1_2 -showcerts </dev/null
# 通过标准:
# Verify return code: 0 (ok)
# Certificate chain 段至少有 0 和 1 两个编号
# ——只有 0 号说明缺中间证书,浏览器/客户端会报 unable to get local issuer certificate
# WAS 9.0.5.6+ 且 JDK 8 SR6 FP10+ 才支持 TLS 1.3,先确认是否要兼容
openssl s_client -connect was-host:9443 -servername was-host -tls1_3 </dev/null | head -5
检查二:keytool 看信任库内容
# PKCS12 是 8.5.5.13 之后的默认 storetype,此前为 JKS;默认密码 WebAS
keytool -list -v -keystore trust.p12 -storetype PKCS12 -storepass WebAS
| grep -E 'Alias|Valid|Entry type|Owner|DNSName'
# 三条判据:对端根证书在库中、Valid 剩余 > 30 天、SAN 含实际访问域名
检查三:wsadmin 核对协议与端口绑定
wsadmin -lang jython -user admin -password *****
# 别名是否存在
AdminTask.listSSLConfigs()
# 期望输出含 sslProtocol=TLSv1.2、securityLevel=HIGH(HIGH 为默认值,可选 HIGH/MEDIUM/LOW/CUSTOM)
print AdminTask.getSSLConfig('[-alias wasTLS12]')
# 再回控制台 服务器 > 端口,确认 WC_defaulthost_secure 的 SSL 配置是 wasTLS12
# 而不是 NodeDefaultSSLSettings —— 这是最常见的失效根因
检查四:日志里有没有 CWPKI 报错
grep -E 'CWPKI0022E|CWPKI0820A' <PROFILE>/logs/server1/SystemOut.log
# 典型报错:CWPKI0022E: SSL HANDSHAKE FAILURE: A signer with SubjectDN "CN=peer" was sent
# 临时加 JVM 通用参数后重启:-Djavax.net.debug=ssl:handshake
# 正常时能看到 "Found trusted certificate" 与 TLSv1.2 的具体 cipher suite 名
检查五:nmap 枚举协议与套件
nmap --script ssl-enum-ciphers -p 9443 was-host
# 通过标准:只列 TLSv1.2 / TLSv1.3 与 HIGH 套件
# 若仍出现 TLSv1.0,说明 sslProtocol 被端点级配置覆盖,回到检查三
| 检查 | 失败指向 | 耗时 |
| openssl s_client | 证书链不完整、SNI 配错 | 秒级 |
| keytool -list | 信任库缺根证书或已过期 | 秒级 |
| wsadmin getSSLConfig | 协议/强度不符预期 | 需认证 |
| SystemOut.log | 握手失败的真实原因 | 需重启 |
| nmap | 端点级覆盖、遗留弱协议 | 分钟级 |
据 IBM Documentation 对 AdminTask.getSSLConfig 的说明,securityLevel 取值为 HIGH/MEDIUM/LOW/CUSTOM,其中 HIGH 才强制 128 位以上套件;这与 NIST SP 800-52r2 对 TLS 1.2 的最低要求一致,也是排查”证书没问题但握手被拒”时优先看的一项。
WebSphere SSL 证书配置的轮换与到期管理:30 天告警与 15 分钟回滚
先说结论:WebSphere 不会在证书到期前主动发告警。WAS 只在 TLS 握手失败时才写 CWPKI0022E(“A signer with SubjectDN … was sent during the handshake, but was not found in the local truststore”),此时业务已经中断。因此一次完整的 websphere ssl证书配置 生命周期,必须由外部脚本兜住“到期前 30 天 / 7 天”两级预警。据 IBM 文档,WAS 9.0 默认密钥库为 key.p12 / trust.p12(PKCS#12 格式,取代 8.5.5 之前的 JKS),密码保存在 security.xml 中,因此脚本必须显式提供 -storepass。
下面的脚本用 keytool -list -v 解析 Valid from ... until ...,只对 PrivateKeyEntry 告警,避免把一堆根证书误报成“即将过期”:
#!/bin/bash
# was-cert-expiry.sh —— 适用 WAS 8.5.5.x / 9.0.x,使用 WAS 自带 JDK 的 keytool
KEYSTORE=/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/cell01/keystores/key.p12
PASSFILE=/secure/was-key.p12.pwd # 明文密码单独存放,chmod 600,勿放配置目录
NOW=$(date +%s)
keytool -list -v -keystore "$KEYSTORE" -storetype PKCS12
-storepass "$(cat $PASSFILE)" 2>/dev/null
| awk -v now="$NOW" '
/^Alias name:/ { alias=$3; pk=0 }
/^Entry type: PrivateKeyEntry/ { pk=1 }
/^Valid from:/ && pk { u=$0; sub(/.*until: /,"",u);
cmd="date -d "" u "" +%s"; cmd|getline exp; close(cmd);
d=int((exp-now)/86400);
if (d<=7) printf "[CRIT] %s 剩余 %d 天n", alias, d;
else if (d30 天
轮换顺序不能反。很多人图省事直接 keytool -importcert 覆盖旧别名,结果旧会话的证书指纹与新证书不一致,客户端缓存导致握手随机失败。正确做法是新开别名、验证链、再切绑定:
cd /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/cell01/keystores
# 1) 改前备份,文件名带日期,便于 15 分钟回滚
cp -a key.p12 key.p12.bak.$(date +%F)
cp -a trust.p12 trust.p12.bak.$(date +%F)
# 2) 导入为新别名 new-was-2026(PKCS#12 源用 importkeystore,不能 importcert)
keytool -importkeystore -srckeystore /tmp/new-was-2026.p12 -srcstoretype PKCS12
-srcstorepass '源密码' -destkeystore key.p12 -deststoretype PKCS12
-deststorepass "$(cat /secure/was-key.p12.pwd)" -destalias new-was-2026 -noprompt
# 3) 验证链完整:length 应为 2 或 3,末条 Issuer=根 CA
keytool -list -v -alias new-was-2026 -keystore key.p12 -storetype PKCS12
-storepass "$(cat /secure/was-key.p12.pwd)"
| grep -E 'Certificate chain length|Owner:|Issuer:'
链验证通过后,在低峰期用 wsadmin 把 SSL 配置的服务器证书别名切过去(defaultServerCertificateAlias 是 SSLConfig 的真实属性名),再 syncNode.sh + 重启 server1,观察 10 分钟 SystemOut.log 无 CWPKI 报错,才删除旧别名。回滚同样只依赖备份文件:还原 key.p12/trust.p12 → syncNode → 重启,三步 15 分钟内可完成,前提是备份文件名可预测($(date +%F))。
多节点环境靠人工逐个点开控制台不现实,用 jython 遍历 AdminTask.listSSLConfigs() 输出 CSV 交给监控平台:
# list-ssl-certs.py —— wsadmin.sh -lang jython -f list-ssl-certs.py
# 适用 WAS 8.5.5.x / 9.0.x;到期时间由上面的 keytool 脚本补齐
out = open('/tmp/was-ssl-certs.csv','w'); out.write('SSLConfig,KeyStore,Scope,Aliasn')
def scope_of(cid):
p = cid.split('|')[0].split('/')
if p[0]=='cells': return '(cell):%s' % p[1]
if p[0]=='nodes': return '(node):%s' % p[1]
if p[0]=='servers': return '(server):%s' % p[2]
return '(cell):%s' % AdminControl.getCell()
for cid in AdminConfig.list('SSLConfig').splitlines():
cid = cid.strip()
if not cid: continue
name = AdminConfig.showAttribute(cid,'name')
ks = AdminConfig.showAttribute(cid,'keyStoreName')
sc = scope_of(cid)
try:
al = AdminTask.listPersonalCertificates(
'[-keyStoreName %s -keyStoreScope %s]' % (ks, sc)).splitlines()
except:
al = ['<ERROR>']
for a in al:
if a.strip(): out.write('%s,%s,%s,%sn' % (name, ks, sc, a.strip()))
out.close(); print 'written /tmp/was-ssl-certs.csv'
最后是选型:公共 CA 与内部 CA 在 WAS 上的差异不在“能不能用”,而在 trust.p12 里缺什么。据 CA/Browser Forum 基线要求,公共 TLS 证书有效期上限为 398 天(2026-03-15 起缩至 200 天),这意味着 websphere ssl证书配置 的轮换频率会显著上升,脚本化不是可选项。
| 维度 | 公共 CA(DV / OV) | 内部 CA(企业 PKI) |
|---|---|---|
| 年费 | DV 约 0–300 元,OV 约 800–3000 元 | 无证书费,成本在人力与 HSM/CA 运维 |
| 根证书是否已在 WAS 默认 trust.p12 | 主流根(DigiCert、Entrust 等)通常已内置 | 必须手工导入根证书 |
| 中间证书 | 不保证内置,需 -importcert -alias inter 补入 trust.p12 |
根与中间证书都必须导入 |
| 有效期上限 | 398 天(2026-03-15 起 200 天) | 自定,常见 1–5 年 |
| 吊销检查 | OCSP/CRL 公网可达 | 内网 CRL 分发点须对 WAS 节点可达,否则握手超时 |
缺中间证书是 CWPKI0022E 最常见成因:客户端只信任根,服务端只发叶子证书,链就断了。因此每次轮换后的 Certificate chain length 检查,比重启本身更值得花时间。
WebSphere SSL 证书配置与 Liberty、IHS、Nginx 的差异:什么时候不该改 WAS
问:同样是 IBM 的 Java 容器,Liberty 改 SSL 为什么比 WAS 传统版快那么多?
因为配置模型不同。Liberty 是”文件即配置”,SSL 定义在 server.xml 的 <ssl> 元素里,重启一个 JVM 即生效;WAS 传统版把密钥库(KeyStore)、信任库(TrustStore)、SSL 配置(SSLConfig)和端点绑定(Endpoint)拆成配置库里的四类对象,改动要经过 AdminConfig.save() → syncNode → 重启 node agent 与 server 才落地。步骤多,但 ND 环境下一次修改能推到整个 cell,这正是集中管理的价值。
<!-- /opt/IBM/WebSphere/Liberty/usr/servers/defaultServer/server.xml -->
<ssl id="defaultSSLConfig"
keyStoreRef="defaultKeyStore"
trustStoreRef="defaultTrustStore"
sslProtocol="TLSv1.2" /> <!-- 默认 TLSv1.2;TLSv1.3 需 19.0.0.4+ 且客户端兼容 -->
<keyStore id="defaultKeyStore" location="key.p12" password="changeit" type="PKCS12"/>
# Liberty 生效与验证(无需 syncNode)
/opt/IBM/WebSphere/Liberty/bin/server stop defaultServer
/opt/IBM/WebSphere/Liberty/bin/server start defaultServer
# 成功标志:CWWKO0219I: TCP Channel defaultHttpEndpoint-ssl is now listening on host * port 9443
WAS 传统版则用 wsadmin 改配置库,再同步、再重启:
# was_ssl.py —— 适用 WAS 9.0.5 ND,jython 语法,wsadmin -lang jython 执行
AdminTask.modifySSLConfig('[-alias NodeDefaultSSLSettings -scopeName (cell):cell01:(node):node01 '
'-sslProtocol TLSv1.2 ' # 取值 SSL_TLS / TLS / TLSv1.2 / TLSv1.3(9.0.5.5+)
'-keyStoreName NodeDefaultKeyStore '
'-trustStoreName NodeDefaultTrustStore]')
AdminConfig.save()
# 顺序不可颠倒:保存 → 同步 → 重启 node agent → 重启 server
/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin/wsadmin.sh -lang jython -f was_ssl.py
/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin/wsadmin.sh -lang jython
-c "AdminNodeManagement.syncActiveNodes()"
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin/stopNode.sh
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin/startNode.sh
# 端点绑定变更不支持热加载,只重启应用无效
| 维度 | Liberty | WAS 传统版(Base/ND) |
|---|---|---|
| 配置载体 | server.xml 的 <ssl>/<keyStore> |
配置库 security.xml 等,经 wsadmin/控制台修改 |
| 生效路径 | server stop/start(秒级到十几秒) | save → syncNode → 重启 node agent + server(分钟级) |
| 多节点一致性 | 各节点文件独立,靠 include 或打包共享 | 一次修改同步全网,天然集中 |
| 典型报错 | CWWKO0801E 握手失败 | CWPKI0022E、CWPKI0824E |
问:能不能直接在 IHS 或 Nginx 上改证书,代替 WebSphere SSL 证书配置?
不能替代,只能前置。IHS 走 httpd.conf 的 SSLProtocol、SSLCertificateFile、SSLCertificateKeyFile;Nginx 走 ssl_certificate、ssl_certificate_key、ssl_protocols;Tomcat 则在 server.xml 的 Connector 上写 keystoreFile、keystorePass、sslProtocol。WAS 的证书链、别名和端点绑定都在配置库中,前端 Web 服务器只负责卸载 TLS,回源到 WAS 的 9443 或 9080 仍按 WAS 自己的配置握手。
# Nginx 侧(卸载 TLS,回源 WAS 内部端口)
ssl_protocols TLSv1.2 TLSv1.3;
ssl_certificate /etc/nginx/certs/fullchain.pem;
ssl_certificate_key /etc/nginx/certs/privkey.pem;
proxy_pass https://was-node01:9443;
# IHS 侧 /opt/IBM/HTTPServer/conf/httpd.conf
SSLProtocol -all +TLSv1.2 +TLSv1.3
SSLCertificateFile /opt/IBM/HTTPServer/ssl/server.crt
SSLCertificateKeyFile /opt/IBM/HTTPServer/ssl/server.key
问:什么时候不该动 WAS 的 SSL 配置?当 TLS 已在 F5、HAProxy 或 Nginx 卸载时,WAS 只需保留内部 HTTP 监听器,或沿用自签证书走内网。此时再往 WAS 里灌公网证书,等于多一个轮换点、多一次 node agent 重启、多一份密钥保管责任,而对外可见的证书链毫无变化。判断依据很简单:用浏览器打开业务域名,看证书颁发者是否来自 WAS 即可。
问:合规和性能上还有哪些硬约束?PCI DSS 要求 TLSv1.2 及以上,WAS 8.5.5.9 起默认已禁用 SSLv3,无需额外加固;据 RFC 8446,TLSv1.3 把完整握手压到 1-RTT,但 WAS 传统版要到 9.0.5.5+ 才支持 TLSv1.3 取值,升级前务必在测试环境验证客户端与 IHS 插件兼容性:
# 确认服务端协议版本与证书有效期(替换主机名)
openssl s_client -connect was.example.com:9443 -tls1_2 -servername was.example.com </dev/null 2>/dev/null
| openssl x509 -noout -subject -dates
openssl s_client -connect was.example.com:9443 -tls1_3 </dev/null # 报 handshake failure 说明未启用
真实报错:
CWPKI0022E: SSL HANDSHAKE FAILURE: A signer with SubjectDN "CN=*.example.com" was sent from target host "was-node01:9443". The signer may need to be added to local trust store ...—— 这条几乎总是信任库缺签名字段,而不是 SSL 协议写错;据 IBM 文档,处理方式是导入签名者证书后重新同步配置库。
WAS 8.5.5 起默认是 /config/cells//nodes//key.p12 与 trust.p12,类型 PKCS12,默认密码 WebAS;WAS 7 及更早默认 JKS。升级后如果未迁移,路径不变但 storetype 可能仍是 JKS。
Deployment Manager 环境里 cell 级配置保存在 dmgr,节点上的 key.p12 与 trust.p12 是独立副本;不执行 syncNode.sh dmgr-host 8879,节点仍用旧文件,表现为控制台新配置不生效。
先把对端根证书和中间证书导入本端 trust.p12,命令是 keytool -importcert -alias peer-ca -file peer-ca.crt -keystore trust.p12 -storetype PKCS12 -storepass WebAS -noprompt,再 syncNode 并重启 server1;仍失败就用 openssl s_client -showcerts 检查对端链是否完整。
WAS 传统版用 SSL 配置库加 key.p12 与 trust.p12 再加端点绑定,需要 wsadmin、syncNode 和重启;Liberty 用 server.xml 的 元素,改完重启 server 即可,配置更集中但缺少 WAS 的 cell/node 分级。
不支持。TLSv1.3 需要 WAS 9.0.5.5 及以上补丁,且客户端也要支持;WAS 8.5.5 建议锁定 TLSv1.2,并用 openssl s_client -tls1_2 验证,不要为了兼容 TLSv1.3 去改 JVM 参数绕过配置库。
执行 openssl s_client -connect was-host:9443 -servername was-host -tls1_2 -showcerts
先在 key.p12 导入新别名并验证链完整,低峰期切换端点绑定的 SSL 配置,重启 server1 后观察 10 分钟无 CWPKI 报错,再删除旧别名;改前备份 key.p12 与 trust.p12,回滚可在 15 分钟内完成。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。