在 IBM WebSphere Application Server (WAS) 中，SSL 配置依賴密鑰管理器 (Key Manager) 提供私鑰與證書鏈以進行身分驗證與加密通訊。預設使用 IBMJSSE2 提供者的 IbmX509 演算法。當需整合硬體安全模組 (HSM)、自定義憑證存儲 (如資料庫、LDAP、雲端 KMS) 或實作特殊金鑰選擇邏輯時，需建立自定義密鑰管理器。本文詳細說明建立流程、作用域選擇與綁定 SSL 配置步驟。

前置條件與作用域決策

• 實作介面：Java 類需實作 javax.net.ssl.X509KeyManager，可選實作 com.ibm.wsspi.ssl.KeyManagerExtendedInfo 提供額外中繼資料。
• 部署封裝：編譯為 JAR，放置於 ${WAS_HOME}/lib/ext 或共享庫 (Shared Library) 並關聯至應用/伺服器類載入器。
• 作用域選擇 (決定可見性)：
  • Cell 級 (單元作用域)：所有節點、伺服器、叢集的 SSL 配置均可引用。路徑：Security → SSL certificate and key management → Key managers。
  • Node/Server/Cluster 級 (端點安全配置)：僅對同層級或子層級 SSL 配置可見。路徑：Security → SSL certificate and key management → Manage endpoint security configuration → {Inbound | Outbound} → → Key managers。
• 可見性規則：SSL 配置只能看見「同層級或父層級」的密鑰管理器。子層級無法看見父層級以外的自定義管理器。

建立自定義密鑰管理器步驟 (以 Cell 級為例)

1. 登入 WAS 管理主控台 (ISC/Administrative Console)。
2. 導航：Security → SSL certificate and key management → Key managers。
3. 點擊 New 建立新密鑰管理器。
4. Name：輸入唯一名稱 (如 CustomHSMKeyManager)。
5. Implementation type：選擇 Custom。
6. Class name：輸入完整類名 (如 com.mycorp.security.HSMKeyManager)。確保 JAR 已正確部署且類可載入。
7. 點擊 Apply。
8. (可選) Custom Properties：點擊「Custom properties」添加實作所需參數 (如 HSM 槽位號、PIN、KMS 端點、API 金鑰等)，每組鍵值對一行，完成後 OK → Save。
9. 返回 SSL certificate and key management 主頁。

將自定義密鑰管理器綁定至 SSL 配置

1. 在 SSL certificate and key management 頁面，選擇目標 SSL 配置範圍：
   • Cell 級 SSL 配置：點擊 SSL configurations (Additional Properties 區)。
   • 端點級 SSL 配置：點擊 Manage endpoint security configuration 選擇層級與方向 (Inbound/Outbound) 後進入具體 SSL 配置。
2. 點擊目標 SSL 配置連結 (如 NodeDefaultSSLSettings)。
3. 在 Additional Properties 區點擊 Trust and key managers → Key managers。
4. 下拉選單選擇剛建立的自定義密鑰管理器 (如 CustomHSMKeyManager)。
   注意：若未出現，檢查 SSL 配置作用域是否與密鑰管理器作用域相同或為子層級。
5. 點擊 OK → Save 至主配置倉儲。
6. 同步節點：System administration → Nodes → 勾選節點 → Full Resynchronize。
7. 重啟受影響伺服器 使變更生效 (或動態 SSL 重載支援環境下可免重啟)。

驗證與故障排查

• 啟動日誌：檢查 SystemOut.log 是否有 CWPKI0027I: Disabling default key manager 或自定義管理器初始化訊息。
• SSL 通訊測試：使用 openssl s_client -connect host:port -debug 或 WAS 內建 SSLClient 測試雙向認證握手成功。
• 常見錯誤：
  • ClassNotFoundException：JAR 未放入正確類載入器路徑，或共享庫未關聯。
  • NoSuchAlgorithmException: IbmX509：自定義管理器未正確註冊為安全提供者，或演算法名稱不匹配。
  • 私鑰不可用：HSM 連線失敗、PIN 錯誤、憑證鏈不完整、金鑰用法 (KeyUsage) 不含 digitalSignature/keyEncipherment。

進階：將自定義密鑰管理器註冊為 JCE 提供者 (可選)

若需在 Java 安全提供者清單中註冊 (供非 WAS 代碼如 JDBC、JMS、第三方庫使用)：

1. 實作 java.security.Provider 子類，put("KeyManagerFactory.X509", "com.mycorp.security.HSMKeyManagerFactory")。
2. java.security 檔案添加 security.provider.N=com.mycorp.security.HSMProvider 或程式碼動態 Security.insertProviderAt(new HSMProvider(), 1)。
3. 在 WAS jvm.options 添加 -Djava.security.properties==${WAS_HOME}/properties/java.security.custom。

但對於純 WAS 內部 SSL (HTTP 通道、RMI/IIOP、管理服務)，僅需上述 SSL 配置綁定步驟，無需註冊為 JCE 提供者。

最佳實務提醒

• 自定義管理器類 不可序列化，避免跨節點序列化問題。
• 敏感參數 (PIN、API Key) 勿寫死代碼/配置檔，使用 Credential Vault / WebSphere Credential Store / HashiCorp Vault / AWS Secrets Manager / Azure Key Vault 運行時注入。
• 實作 chooseClientAlias/chooseServerAlias 時，務必處理 null 返回 (無合適別名) 避免 NPE 導致握手失敗。
• 建立完整單元/整合測試：正常握手、客戶端認證、伺服器認證、憑證過期/吊銷/路徑驗證失敗、HSM 故障降級邏輯。
• 變更管理：納入 CAB 流程，保留舊密鑰管理器備份以利快速回滾。

自定義密鑰管理器是 WAS SSL 可擴展性的核心擴展點，正確建立與綁定流程，配合 HSM/雲端 KMS/硬體加密卡，能滿足金融級、政府級、合規要求嚴格的私鑰託管與雙向認證需求，是零信任架構中「機器身分」信任錨的關鍵實作。