**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](https://www.entrust.com/products/hsm/nshield-5c) 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:

> [!WARNING]
> The HSM integration is not supported and will not function on FIPS-enabled machines. Ensure FIPS is disabled on all nodes hosting the Edge for Private Cloud cluster.

### 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.

> [!IMPORTANT]
> Cryptographic operations using the HSM (like signing/decryption during TLS handshake) introduce network and hardware latency. TrustStores only contain public certificates and do not require HSM-level protection. Keeping the TrustStore in software avoids unnecessary HSM round-trips, significantly improving TLS handshake performance while keeping private keys secure.

### 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
```

> [!NOTE]
> The identifiers `unique_keystore_ref1` and `unique_truststore_ref1` are custom names. You can define multiple references to support different API proxies.

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
```

> [!WARNING]
> If `conf_system_apigee.hsm.enabled` is `true` but the properties file is missing or inaccessible, the Message Processor will fail to start.

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](https://docs.apigee.com/private-cloud/v4.53.01/hsm-integration-southbound.md.txt#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

> [!WARNING]
> Disabling HSM globally will cause all API proxies using `hsmref://` to fail at runtime with `500 Internal Server Error`. Reconfigure or undeploy these proxies before proceeding.

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](https://www.entrust.com/products/hsm/nshield-5c) 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

| Fault Code | HTTP Status | Description / Cause |
|---|---|---|
| `entities.HsmConfigNotEnabled` | 500 | An API proxy attempted to use `hsmref://` at runtime, but HSM is disabled globally (`conf_system_apigee.hsm.enabled=false`) on the Message Processor. |

## 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.