Apigee Edge Private Cloud 南向硬體安全模組整合指南

發布版本：Edge for Private Cloud v4.53.01.02 修補程式版本和後續版本。

本頁說明如何使用 Entrust nShield® 5c 網路硬體安全模組 (HSM)，設定南向 TLS 連線 (從 Apigee Message Processor 到後端目標服務)。

第三方內容免責事項：本頁面提供 Entrust nShield 硬體的設定步驟，與 Apigee Edge 整合相關。這些步驟是以標準整合模式為依據，僅供參考。Entrust 設定可能會由製造商變更。如需權威規格、安全性設定和目前硬體需求，請參閱官方 Entrust 文件入口網站。

總覽

硬體安全模組 (HSM) 提供專用的強化環境，可安全儲存金鑰及執行加密編譯作業。將 Apigee Edge for Private Cloud 與 Entrust nShield HSM 整合後，您就能保護用於南向 TLS 和 mTLS 交握的私密金鑰。

Apigee 支援 HSM 整合，可透過下列元件傳送外向南向 HTTPS 流量：

• 目標端點
• 目標伺服器
• 服務呼叫政策
• 訊息記錄政策
• JavaScript 政策

必要條件

設定 HSM 整合功能前，請確認符合下列必要條件：

1. 軟體版本需求

• Apigee Edge for Private Cloud 叢集必須執行4.53.01.02 以上版本。
• 下列 RPM 版本 (或更新版本) 原生支援 HSM 整合：
  • edge-management-server-4.53.01-0.0.60380.noarch.rpm
  • edge-message-processor-4.53.01-0.0.60380.noarch.rpm
  • edge-gateway-4.53.01-0.0.60380.noarch.rpm

2. 基礎架構和作業系統設定

• 託管 Edge for Private Cloud 叢集的 OS 必須停用 FIPS。
• 所有訊息處理器節點都必須安裝及設定 HSM 用戶端和 Security World。
• 重要事項：這些步驟必須由apigee使用者執行。

請執行官方 Entrust nShield 文件中提供的標準 JCA/JCE CSP 安裝測試，確認 HSM 用戶端安裝設定正確無誤，且 apigee 使用者可存取。請確保所有訊息處理器節點都順利完成這項測試。

支援的設定

您可以設定 Apigee，透過下列兩種模式使用 HSM：

1. HSM 混合模式 (建議)

在這個模式中，只有私密金鑰 (KeyStore) 會儲存在 HSM 中，信任憑證 (TrustStore) 則會保留在標準 Apigee 軟體儲存空間。

2. 完整 HSM 模式

在此模式下，KeyStore (私密金鑰) 和 TrustStore (信任的憑證) 都會儲存在 HSM 中。支援此模式，但可能會導致延遲時間提高。

步驟 1：在訊息處理器上啟用 HSM

在每個訊息處理器節點上，一次一個執行下列步驟：

1. 停止訊息處理工具

apigee-service edge-message-processor stop

2. 驗證 HSM Keystore 資料檔案

請確認 HSM Keystore Data File (參照 HSM 中載入的金鑰) 位於訊息處理器節點上，且由 apigee 使用者擁有：

chown apigee:apigee /opt/apigee/{name_of_the_Keystore_Data_File}

3. 建立 HSM 設定檔

在 /opt/apigee/hsm-config.properties 建立或更新設定檔。定義 HSM Keystore 和 (選用) Truststore 的位置和密碼。

設定範例 (同時支援混合和完整 HSM Proxy)：

# HSM KeyStore Reference
hsm.property.unique_keystore_ref1.keystore.file.location=/opt/apigee/ks.keystore
hsm.property.unique_keystore_ref1.keystore.password=keystore_password

# HSM TrustStore Reference (Optional, only needed for Full HSM Mode)
hsm.property.unique_truststore_ref1.truststore.file.location=/opt/apigee/ts.truststore
hsm.property.unique_truststore_ref1.truststore.password=truststore_password

設定正確的權限：

chown apigee:apigee /opt/apigee/hsm-config.properties

chmod 600 /opt/apigee/hsm-config.properties

4. 設定訊息處理工具屬性

建立或編輯 /opt/apigee/customer/application/message-processor.properties，並新增下列項目：

# Enable HSM Integration
conf_system_apigee.hsm.enabled=true

# HSM Configuration File Path
conf_system_apigee.hsm.properties.file=/opt/apigee/hsm-config.properties

# Advanced Custom HSM Port Support (Optional, default is 9000/9001)
# conf_system_apigee.hsm.priv_port=9001
# conf_system_apigee.hsm.nonpriv_port=9000

確認擁有權正確無誤：

chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

5. 重新設定並重新啟動

apigee-service edge-message-processor configure

apigee-service edge-message-processor restart

6. 驗證初始化

檢查系統記錄 /opt/apigee/var/log/edge-message-processor/logs/system.log，確認是否出現初始化成功訊息：

main INFO  SECURITY-CONTEXT - SSLPreEvaluationContext.isHSMConfigEnabled() : HSM_FLOW : HSM config is enabled
main INFO  SECURITY-CONTEXT - SSLPreEvaluationContext.loadProperties() : HSM_FLOW :  HSM config properties loaded from file /opt/apigee/hsm-config.properties

步驟 2：設定 API Proxy

更新 API Proxy 設定中的 SSLInfo 區塊 (TargetEndpoint、ServiceCallout 或政策)。使用 hsmref:// 前置字串參照 HSM 管理的商店，並使用 ref:// (或標準參照名稱) 參照軟體商店。

1. HSM 混合模式設定 (建議)

使用 HSM 進行 KeyStore (用戶端驗證)，並使用軟體進行 TrustStore。

<SSLInfo>
    <Enabled>true</Enabled>
    <ClientAuthEnabled>true</ClientAuthEnabled>
    <KeyStore>hsmref://unique_keystore_ref1</KeyStore>
    <TrustStore>ref://mySoftwareTrustStoreRef</TrustStore>
</SSLInfo>

2. 完整 HSM 設定

KeyStore 和 TrustStore 都使用 HSM。

<SSLInfo>
    <Enabled>true</Enabled>
    <ClientAuthEnabled>true</ClientAuthEnabled>
    <KeyStore>hsmref://unique_keystore_ref1</KeyStore>
    <TrustStore>hsmref://unique_truststore_ref1</TrustStore>
</SSLInfo>

略過部署期間驗證

為方便部署，不必將私密金鑰上傳至 Apigee 的 Cassandra 資料庫，Apigee 會在部署期間，自動略過以 hsmref:// 前置字元開頭的任何參照，進行環境金鑰儲存區/信任儲存區存在性檢查。

作業：新增 HSM 金鑰儲存區/信任儲存區

如要在現有執行環境中新增 HSM 金鑰儲存區或信任儲存區，請按照下列步驟操作：

1. 將金鑰/憑證載入實體 HSM (請參閱「將金鑰儲存區/信任儲存區載入 HSM」)。
2. 將新的金鑰儲存庫資料檔案複製到訊息處理器節點，並將擁有權設為 apigee。
3. 在所有訊息處理器節點上更新 /opt/apigee/hsm-config.properties，換成新的參照：

   hsm.property.new_keystore_ref.keystore.file.location=/opt/apigee/new_ks.keystore
   hsm.property.new_keystore_ref.keystore.password=new_password
       

4. 在每個節點上重新啟動訊息處理器：

   apigee-service edge-message-processor restart

5. 更新 API Proxy 設定，使用新的 hsmref://new_keystore_ref 並部署。

在全球停用 HSM

如要停用 HSM：

1. 使用 hsmref:// 更新所有有效 Proxy，改用標準軟體參照 (ref://)。
2. 在每個訊息處理器節點上，編輯 /opt/apigee/customer/application/message-processor.properties 並設定：

   conf_system_apigee.hsm.enabled=false

3. 重新設定並重新啟動訊息處理器：

   apigee-service edge-message-processor configure

   apigee-service edge-message-processor restart

限制和注意事項

• 支援的硬體：僅限 Entrust nShield 5c 網路 HSM。
• 維護：客戶必須負責維護 HSM 伺服器/用戶端。
• 延遲：與 HSM 進行網路交涉時，可能會發生額外延遲。使用 HSM 混合模式可減輕這類問題。
• HSM 重新啟動：如果 HSM 硬體伺服器重新啟動，您必須在已連線的 訊息處理器 節點上重新啟動 edge-message-processor。

將金鑰儲存區/信任儲存區載入 HSM

如要瞭解將 PKCS12 金鑰儲存區或 PEM 憑證匯入 HSM 時所需的確切 keytool 指令，請參閱官方 Entrust nShield 說明文件入口網站。

為確保與 Apigee 相容，產生的 HSM 金鑰儲存區檔案必須符合下列規定：

• 目錄：必須儲存至 /opt/apigee/ (例如 /opt/apigee/hsmks.keystore)
• 權限：必須由 apigee 使用者 (chown apigee:apigee /opt/apigee/<filename>) 擁有
• 可讀性：必須可供 edge-message-processor 服務讀取。

錯誤參考資料

法律聲明

Entrust 和 nShield 是 Entrust Corporation 或其關係企業的商標或註冊商標。所有其他商標為其各自所屬擁有者的財產。