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

WebSphere SSL 证书配置实操指南:iKeyman、wsadmin 与 CWPKI0022E 排查

websphere ssl证书配置 — 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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

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