Southbound Hardware Security Module Integration Guide for Apigee Edge for Private Cloud

Release Version: Edge for Private Cloud v4.53.01.02 Patch Release and later.

This page explains how to configure southbound TLS connections (from Apigee Message Processors to backend target services) using Entrust nShield® 5c network Hardware Security Modules (HSMs).

Third-Party Content Disclaimer: This page provides configuration steps for Entrust nShield hardware as they relate to Apigee Edge integration. These steps are based on standard integration patterns and are provided for informational purposes only. Entrust configurations are subject to change by the manufacturer. Please consult the official Entrust Documentation Portal for authoritative specifications, security configurations, and current hardware requirements.

Overview

Hardware Security Modules (HSMs) provide a dedicated, hardened environment for secure key storage and cryptographic operations. By integrating Apigee Edge for Private Cloud with Entrust nShield HSMs, you can secure the private keys used in southbound TLS and mTLS handshakes.

Apigee supports HSM integration for outgoing southbound HTTPS traffic across the following components:

• Target Endpoints
• Target Servers
• Service Callout policies
• Message Logging policies
• JavaScript policies

Prerequisites

Ensure the following prerequisites are met before configuring the HSM integration:

1. Software Version Requirements

• The Apigee Edge for Private Cloud cluster must be running on version 4.53.01.02 or higher.
• The HSM integration is natively included in the following RPM versions (or higher):
  • 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. Infrastructure and operating system configuration

• The OS hosting the Edge for Private Cloud cluster must have FIPS disabled.
• The HSM client and Security World must be installed and configured on all Message Processor nodes.
• Important: These steps must be performed by the apigee user.

Verify the HSM client installation is correctly configured and accessible by the apigee user by running the standard JCA/JCE CSP installation test provided in the official Entrust nShield documentation. Ensure this test completes successfully on all Message Processor nodes.

Supported Configurations

You can configure Apigee to use HSM in two modes:

1. HSM Mixed Mode (Recommended)

In this mode, only the private keys (KeyStore) are stored in the HSM, while the trusted certificates (TrustStore) remain in standard Apigee software stores.

2. Full HSM Mode

In this mode, both the KeyStore (private keys) and the TrustStore (trusted certificates) are stored in the HSM. This mode is supported but may introduce additional latency.

Step 1: Enable HSM on Message Processors

Perform these steps on each Message Processor node, one at a time:

1. Stop the Message Processor

apigee-service edge-message-processor stop

2. Verify HSM Keystore Data File

Ensure the HSM Keystore Data File (referencing the keys loaded in HSM) is present on the Message Processor node and owned by the apigee user:

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

3. Create the HSM Configuration File

Create or update the configuration file at /opt/apigee/hsm-config.properties. Define the location and passwords for the HSM keystores and (optionally) truststores.

Example configuration (supporting both mixed and full HSM proxies):

# 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

Set correct permissions:

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

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

4. Configure Message Processor Properties

Create or edit /opt/apigee/customer/application/message-processor.properties and add the following:

# 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

Ensure correct ownership:

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

5. Reconfigure and Restart

apigee-service edge-message-processor configure

apigee-service edge-message-processor restart

6. Validate Initialization

Check the system log /opt/apigee/var/log/edge-message-processor/logs/system.log for successful initialization messages:

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

Step 2: Configure API Proxies

Update the SSLInfo block in the API proxy configuration (TargetEndpoint, ServiceCallout, or policies). Use the hsmref:// prefix to reference HSM-managed stores, and ref:// (or standard reference name) for software stores.

1. HSM Mixed Mode Configuration (Recommended)

Uses HSM for KeyStore (client authentication) and Software for TrustStore.

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

2. Full HSM Configuration

Uses HSM for both KeyStore and TrustStore.

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

Deployment-Time Validation Bypass

To facilitate deployment without uploading private keys to Apigee's Cassandra database, Apigee automatically bypasses environment keystore/truststore existence checks during deployment for any reference starting with the hsmref:// prefix.

Operations: Adding New HSM Keystores/Truststores

To add a new HSM keystore or truststore to an existing running environment:

1. Load the keys/certs into the physical HSM (see Loading Keystores/Truststores into HSM).
2. Copy the new Keystore Data File to the Message Processor nodes and set ownership to apigee.
3. Update /opt/apigee/hsm-config.properties on all Message Processor nodes with the new reference:

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

4. Restart the Message Processor on each node:

   apigee-service edge-message-processor restart

5. Update the API proxy configuration to use the new hsmref://new_keystore_ref and deploy.

Disabling HSM Globally

To disable HSM:

1. Update all active proxies using hsmref:// to use standard software references (ref://).
2. On each Message Processor node, edit /opt/apigee/customer/application/message-processor.properties and set:

   conf_system_apigee.hsm.enabled=false

3. Reconfigure and restart the Message Processor:

   apigee-service edge-message-processor configure

   apigee-service edge-message-processor restart

Limitations and Caveats

• Supported hardware: Limited to Entrust nShield 5c network HSMs.
• Maintenance: Customers are responsible for HSM server/client maintenance.
• Latency: Additional latency may occur due to network negotiations with the HSM. Using HSM Mixed Mode mitigates this to some extent.
• HSM Restart: If the HSM hardserver restarts, you must restart the edge-message-processor on the connected Message Processor nodes.

Loading Keystores/Truststores into HSM

Consult the official Entrust nShield Documentation Portal for the exact keytool commands required to import a PKCS12 keystore or PEM certificate into the HSM.

To ensure compatibility with Apigee, the resulting HSM keystore files must meet the following requirements:

• Directory: Must be saved to /opt/apigee/ (e.g., /opt/apigee/hsmks.keystore)
• Permissions: Must be owned by the apigee user (chown apigee:apigee /opt/apigee/<filename>)
• Readability: Must be readable by the edge-message-processor service.

Error Reference

Legal Notices

Entrust and nShield are trademarks or registered trademarks of Entrust Corporation or its affiliates. All other trademarks are the property of their respective owners.