适用于私有云的 Apigee Edge 的南向硬件安全模块集成指南

发布版本：Edge for Private Cloud v4.53.01.02 补丁版本及更高版本。

本页面介绍了如何使用 Entrust nShield® 5c 网络硬件安全模块 (HSM) 配置南向 TLS 连接（从 Apigee 消息处理器到后端目标服务）。

第三方内容免责声明：本页面提供了与 Apigee Edge 集成相关的 Entrust nShield 硬件配置步骤。这些步骤基于标准集成模式，仅供参考。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 或更高版本。
• HSM 集成原生包含在以下 RPM 版本（或更高版本）中：
  • 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 Private Cloud 集群的操作系统必须停用 FIPS。
• 必须在所有消息处理器节点上安装并配置 HSM 客户端和 Security World。
• 重要提示：这些步骤必须由 apigee 用户执行。

运行官方 Entrust nShield 文档中提供的标准 JCA/JCE CSP 安装测试，验证 HSM 客户端安装是否已正确配置且可供 apigee 用户访问。确保此测试在所有消息处理器节点上成功完成。

支持的配置

您可以将 Apigee 配置为以两种模式使用 HSM：

1. HSM 混合模式（推荐）

在此模式下，只有私钥 (KeyStore) 存储在 HSM 中，而受信任的证书 (TrustStore) 仍保留在标准 Apigee 软件存储区中。

2. 完整 HSM 模式

在此模式下，密钥库（私钥）和信任库（受信任的证书）都存储在 HSM 中。此模式受支持，但可能会增加延迟。

第 1 步：在消息处理器上启用 HSM

在每个消息处理器节点上逐一执行以下步骤：

1. 停止消息处理器

apigee-service edge-message-processor stop

2. 验证 HSM Keystore 数据文件

确保 HSM 密钥库数据文件（引用 HSM 中加载的密钥）位于消息处理器节点上，并且归 apigee 用户所有：

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

3. 创建 HSM 配置文件

在 /opt/apigee/hsm-config.properties 中创建或更新配置文件。定义 HSM 密钥库和（可选）信任库的位置和密码。

配置示例（同时支持混合 HSM 代理和完整 HSM 代理）：

# 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 代理

更新 API 代理配置（TargetEndpoint、ServiceCallout 或政策）中的 SSLInfo 块。使用 hsmref:// 前缀引用 HSM 管理的存储空间，并使用 ref://（或标准引用名称）引用软件存储空间。

1. HSM 混合模式配置（推荐）

使用 HSM 作为密钥库（客户端身份验证），使用软件作为信任库。

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

2. 完整的 HSM 配置

将 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 代理配置以使用新的 hsmref://new_keystore_ref 并进行部署。

全局停用 HSM

如需停用 HSM，请执行以下操作：

1. 更新所有使用 hsmref:// 的有效代理，以使用标准软件引用 (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 hardserver 重启，您必须在连接的消息处理器节点上重启 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 或其关联公司的商标或注册商标。所有其他商标均为其各自所有者的财产。