Fortanix DSM with Azure Key Vault Managed HSM External Key Management

1.0 Introduction

This article describes how to integrate Fortanix-Data-Security-Manager (DSM) with Azure Key Vault Managed HSM external key management to protect Azure data using encryption keys stored and managed exclusively within Fortanix DSM.

With this integration, Azure Managed HSM delegates all cryptographic operations such as, key wrapping and unwrapping to Fortanix DSM acting as an EKM proxy. Keys never leave the Fortanix DSM boundary; Azure holds only a reference to the external key identifier, while all cryptographic operations are performed inside Fortanix DSM.

2.0 Why Use Fortanix DSM with Azure Key Vault Managed HSM External Key Management?

Azure Key Vault Managed HSM external key management allows Azure services starting with Azure Blob Storage to use encryption keys managed entirely outside of Azure.

Fortanix DSM acts as the external key manager and performs cryptographic operations on these keys. Managed HSM interacts with Fortanix DSM through key references without accessing the underlying key material.

3.0 Prerequisites

Ensure the following:

• Fortanix DSM endpoint is reachable from Azure Managed HSM over HTTPS (TCP port 443).

• Fortanix DSM Fully Qualified Domain name (FQDN) resolves correctly and presents a valid TLS certificate chain.

4.0 Set Up Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible.

4.1 Signing Up

4.2 Creating an Account

Access <Your_DSM_Service_URL> in a web browser and enter your credentials to log in to Fortanix DSM.

5.0 Set Up Azure CLI Environment

This section describes how to prepare the client environment required to manage Azure Managed HSM external key management resources.

5.1 Installing Azure CLI

Perform the following steps:

1. Install the latest Azure CLI (version 2.x) if it is not already installed. For more information, refer to the Microsoft official documentation.

2. Run the following command to install the Azure Key Vault extension:

   az extension add --name keyvault

   If the extension is already installed, run the following command to update it to the latest version:

   az extension update --name keyvault

3. Run the following command to sign in to Azure:

   az login

4. If you have multiple subscriptions, run the following command to select the subscription containing your Managed HSM:

   az account set --subscription "<SUBSCRIPTION_ID>"

NOTE

This article uses the Azure CLI with the Azure Managed HSM EKM preview extension. All commands are executed using the standard az <command> syntax.

6.0 Configure Azure Managed HSM

6.1 Creating and Activating Azure Managed HSM

Perform the following steps:

NOTE

• If the Managed HSM instance is already set up and activated, skip to Step 3.

• Azure Managed HSM external key management is currently in public preview. After creating your Managed HSM instance, contact Microsoft to enable this feature for your Managed HSM instance before proceeding with the remaining steps in this document.

1. In the Azure Portal, create a new Managed HSM instance.

   • Use the default retention period of 7 days.

   • Enable Purge Protection.

2. The provisioned Managed HSM instance must be activated before it can be used.

   To activate it, generate three self-signed certificates and download the security domain. Run the following commands to generate the certificates.

   openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
   openssl req -newkey rsa:2048 -nodes -keyout cert_1.key -x509 -days 365 -out cert_1.ce
   openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert_2.cer

   These certificates are used to encrypt the security domain during HSM activation. A quorum of two certificates is required to unlock and restore the security domain.

   NOTE

   Store the generated certificate key files (cert_0.key, cert_1.key, cert_2.key) and the downloaded security domain file in a secure location. These are required for HSM recovery and cannot be regenerated.

3. Run the following command to download the security domain and activate the Managed HSM instance:

    az keyvault security-domain download \
     --hsm-name <MANAGED_HSM_NAME> \
     --sd-wrapping-keys ./cert_0.cer ./cert_1.cer ./cert_2.cer \
     --sd-quorum 2 \
     --security-domain-file <MANAGED_HSM_NAME>-SD.json

4. Verify that the command returns the following output confirming successful activation:

   {
     "status": "Success",
     "statusDetails": "The resource is active."
   }

NOTE

You can also configure Azure Managed HSM using the Azure portal instead of the Azure CLI. For detailed instructions, refer to the Microsoft Official documentation. If you use the Azure portal-based workflow, continue with the remaining Fortanix configuration steps in this guide after completing the Microsoft procedure.

6.2 Assigning Required Roles

Perform the following steps to assign the required roles to the Azure user:

1. Run the following command to sign in to the Azure CLI:

   az login

2. Authenticate using the browser. When prompted to select a subscription and tenant, press Enter to retain the current selection.

3. You can retrieve your user object ID from the Azure Portal or by running the following command in a new terminal tab:

   az ad user show --id <USER_PRINCIPAL_NAME> --query id -o tsv 

   Where, <USER_PRINCIPAL_NAME> is the Microsoft Entra ID user principal name. For example, user@contoso.com.

   Ensure to save the returned object ID value to be used in later steps.

4. Run the following command to assign the Managed HSM Crypto User role:

   az keyvault role assignment create \
     --hsm-name <MANAGED_HSM_NAME> \
     --role "Managed HSM Crypto User" \
     --assignee <YOUR_USER_OBJECT_ID> \
     --scope "/"

   A successful assignment returns a JSON object containing the role assignment details.

5. Run the following command to assign the Managed HSM EKM Administrator role:

   az keyvault role assignment create \
     --hsm-name <MANAGED_HSM_NAME> \
     --role "Managed HSM EKM Administrator" \
     --assignee <YOUR_USER_OBJECT_ID> \
     --scope "/"

   A successful assignment returns a JSON object containing the role assignment details.

   NOTE

   If the role assignment already exists, Azure returns a MatchingRoleAssignmentExists error message. No further action is required as the role is already assigned and active.

6.3 Enabling the External Key Management Feature on the Managed HSM Instance

Verify that the external key management feature is enabled for your Managed HSM instance. If the required Azure CLI commands are available and the Managed HSM is deployed in a supported region, proceed with Section 6.4: Configuring Diagnostic Logging.

6.4 Configuring Diagnostic Logging

Perform the following steps to configure audit logging for the Azure Managed HSM instance. For more information, refer to the Microsoft official documentation.

1. Create a Log Analytics Workspace in the same Azure subscription as the Managed HSM instance.

2. Run the following command to retrieve the Managed HSM resource ID:

   az keyvault show --hsm-name <MANAGED_HSM_NAME> --query id -o tsv

   Ensure to save the returned resource ID value to use it in Step 4.

3. Run the following command to retrieve the Log Analytics Workspace resource ID:

   az monitor log-analytics workspace show \
     --resource-group <RESOURCE_GROUP> \
     --workspace-name <WORKSPACE_NAME> \
     --query id -o tsv

   Ensure to save the returned workspace resource ID value to use it in Step 4.

4. Run the following command to configure diagnostic settings and link the Log Analytics Workspace to the Managed HSM instance:

   az monitor diagnostic-settings create \
     --name "<MANAGED_HSM_NAME>-Diagnostics" \
     --resource "<MANAGED_HSM_RESOURCE_ID>" \
     --logs '[{"category": "AuditEvent","enabled": true}]' \
     --workspace "<LOG_ANALYTICS_WORKSPACE_ID>"

   NOTE

   Alternatively, you can configure Diagnostic Settings through the Azure portal by navigating to Managed HSM → Monitoring → Diagnostic settings.

After the diagnostic settings are configured, audit events generated by Azure Key Vault Managed HSM are forwarded to the Log Analytics Workspace.

6.5 Retrieving the Managed HSM Client Certificate

Azure Key Vault Managed HSM presents a client certificate to Fortanix DSM during mutual TLS authentication.

Perform the following steps to retrieve the certificate details:

1. Run the following command to retrieve the Managed HSM client certificate and issuing Certificate Authority (CA) information:

   az keyvault ekm-connection certificate show --hsm-name <MANAGED_HSM_NAME>

   A successful response returns the following output:

   {
     "caCertificates": [
       "<BASE64_ENCODED_CERTIFICATE>"
     ],
     "subjectCommonName": "<MANAGED_HSM_NAME>.managedhsmclient.azure.net"
   }

   Where,

   • subjectCommonName: The DNS name used in the Managed HSM client certificate. For example, <MANAGED_HSM_NAME>.managedhsmclient.azure.net.

   • caCertificates: The Base64-encoded CA certificate presented by the Managed HSM to Fortanix DSM.

   Ensure to save both values to configure the Trusted CA application in Fortanix DSM in Section 6.9: Creating an Application.

6.6 Verifying Fortanix DSM Client Certificate

Before creating the external key management connection, verify that the Fortanix DSM instance is configured to request client certificates from connecting clients.

Perform the following steps:

1. Log in to Fortanix DSM as a System Administrator.

2. Navigate to System Administration → Settings → INTERFACES.

3. Confirm that the check box under the REQUEST CLIENT CERTIFICATE column is enabled for that host. If it is not enabled, perform the following steps:

   1. Click the check box under REQUEST CLIENT CERTIFICATE for the relevant host to enable it.

   2. Click SAVE CHANGES to apply.

6.7 Retrieving the Fortanix DSM Server CA Certificate

The Fortanix DSM server CA certificate chain is required when creating the external key management connection in Section 7.0: Create an External Key Management Connection.

Perform the following steps to retrieve the server CA certificate:

1. Open the Fortanix DSM URL in a browser.

2. Click the lock icon in the address bar and select Connection is secure, then More information.

3. View and download the full server certificate chain.

   NOTE

   Download the complete certificate chain, including any intermediate CA certificates. Do not provide only the leaf certificate.

4. Save the CA certificate chain to a local PEM file (for example, server-ca.pem) to use it later in Section 7.0: Create an External Key Management Connection.

   

6.8 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

1. In the DSM UI left navigation panel, click the Groups menu item, and then click ADD GROUP to create a new group.

   

2. On the Adding new group page:

   1. Title: Enter a name for your group.

   2. Description (optional): Enter a short description of the group.

3. Click SAVE to create the new group.

For more information about groups, refer to Definitions.

6.9 Creating an Application

Perform the following steps to create a Trusted CA app in the Fortanix DSM:

1. In the DSM UI left navigation panel, click the Apps menu item, and then click ADD APP to create a new app.

   

2. On the Adding new app page:

   1. App name: Enter the name for your application.

   2. ADD DESCRIPTION (optional): Enter a short description of the application.

   3. Authentication method: Select Trusted CA as the authentication method from the drop-down menu. For more information on this authentication method, refer to Authentication.

   4. In the Configure Subject Alternative Name (SAN) section:

      1. DNS Name: Enter the subjectCommonName value retrieved from Azure Managed HSM in Section 6.5: Retrieving the Managed HSM Client Certificate.

      2. UPLOAD TRUSTED CA CERT: Upload or paste the caCertificates value retrieved from Azure Managed HSM in Section 6.5: Retrieving the Managed HSM Client Certificate.

   5. Assigning the new app to groups: Select the group created in Section 6.8: Creating a Groupfrom the list.

3. Click SAVE to add the new application.

For more information about applications, refer to Definitions.

6.10 Copying the App UUID

Perform the following steps to copy the app UUID from the Fortanix DSM:

1. In the DSM left navigation panel, click the Apps menu item, and then click the app created in Section 6.9: Creating an Application to go to the detailed view of the app.

2. From the top of the app’s page, click the copy icon next to the app UUID to copy it to use it later in Section 7.0: Create an External Key Management Connection.

6.11 Creating a Security Object

Perform the following steps to generate an RSA key in the Fortanix DSM:

1. In the DSM left navigation panel, click the Security Objects menu item, and then click ADD SECURITY OBJECT to create a new security object.

   

2. On the Add new Security Object page:

   1. Security Object Name: Enter the name of your security object.

   2. Group: Select the group as created in Section 6.8: Creating a Group.

   3. Select GENERATE.

   4. In the Choose a type section, select the RSA key type to generate.

   5. In the Key Size section, select the size of the key in bits.

   6. In the Exponent section, select the value as required.

   7. In the Key operations permitted section, select the Encrypt and Decrypt key operations.

3. Click GENERATE to create the new security object.

For more information about security objects, refer to Definitions.

6.12 Copying the Security Object UUID (External Key ID)

Perform the following steps to copy the security object UUID from the Fortanix DSM:

1. In the DSM left navigation panel, click the Security Objects menu item, and then click the security object created in Section 6.11: Creating a Security Object to go to the detailed view of the security object.

2. From the top of the security object’s page, click the copy icon next to the UUID to copy it to use it later in Section 8.0: Create an External RSA Key Reference.

7.0 Create an External Key Management Connection

Perform the following steps to establish an external key management connection between Azure Key Vault Managed HSM and Fortanix DSM:

1. Run the following command to create the external key management connection:

   az keyvault ekm-connection create V\
     --hsm-name <MANAGED_HSM_NAME> \
     --host <DSM_HOSTNAME> \
     --server-ca-certificate <PATH_TO_DSM_CA_CHAIN>.pem \
     --path-prefix /crypto/v1/apps/<TRUSTED_CA_APP_UUID>/azure/ekm

   Where,

   • <MANAGED_HSM_NAME>: The name of your Azure Managed HSM instance.

   • <DSM_HOSTNAME>: The Fortanix DSM hostname. For example, amer.smartkey.io.

   • <PATH_TO_DSM_CA_CHAIN>.pem: The file path to the Fortanix DSM CA certificate chain saved in Section 6.7: Retrieving the Fortanix DSM Server CA Certificate.

   • <TRUSTED_CA_APP_UUID>: The UUID of the Trusted CA application copied in Section 6.10: Copying the App UUID.

   NOTE

   You must provide the full certificate chain instead of only the leaf certificate.

2. Verify that the command returns the following output confirming a successful external key management connection:

   {
     "apiVersion": "0.1-preview",
     "ekmProduct": "Fortanix Data Security Manager",
     "ekmVendor": "Fortanix, Inc.",
     "proxyName": "Fortanix Data Security Manager",
     "proxyVendor": "Fortanix, Inc."
   }

   NOTE

   If the external key management connection has already been established, the command returns a NotSupported: EKM connection is already setup error. This indicates the connection is active and no further action is required.

7.1 Verifying the Connection

Perform the following step to verify that Azure Managed HSM can reach the Fortanix DSM proxy:

1. Run the following command to verify the external key management connection:

   az keyvault ekm-connection check --hsm-name <MANAGED_HSM_NAME> 

   A successful response returns the following output:

   {
     "status": "Connected",
     "proxyVersion": "1.0.0",
     "vendor": "Contoso HSM"
   }

8.0 Create an External RSA Key Reference

Perform the following steps to create an external RSA key reference in Azure Managed HSM that points to the Fortanix DSM security object created in Section 6.11: Creating a Security Object.

1. Run the following command to create the external key reference:

   az keyvault key create \
     --external-key-id <SOBJECT_UUID> \
     --hsm-name <MANAGED_HSM_NAME> \
     --name <AZURE_KEY_NAME>

   Where,

   • <SOBJECT_UUID>: The Fortanix DSM security object UUID copied in Section 6.12: Copying the Security Object UUID (External Key ID).

   • <AZURE_KEY_NAME>: A name for the key in Azure Managed HSM. The name must conform to Azure key naming guidelines and must not contain underscores.

2. Verify the output:

   • kty must be RSA-HSM.

   • keyOps must include wrapKey and unwrapKey.

   • externalKeyId must match the Fortanix DSM security object UUID.

NOTE

The External RSA Key Reference creates a reference in Azure Managed HSM to the RSA key stored in Fortanix DSM. The key material remains securely stored in Fortanix DSM.

9.0 Configure Azure Blob Storage to Use the External Key

This section describes how to configure an Azure Storage Account to use the external RSA key created in Azure Managed HSM for customer-managed encryption.

9.1 Creating a Storage Account

Perform the following steps:

1. In the Azure Portal, create a new Storage Account in the same region as the Managed HSM.

2. Select Azure Blob Storage as the preferred storage type.

3. Optionally, place the Storage Account in the same resource group as the Managed HSM instance.

4. Enable encryption with customer-managed keys stored in the Managed HSM instance.

5. Run the following command to enable a system-assigned managed identity on the Storage Account:

   az storage account update \
     --name <STORAGE_ACCOUNT_NAME> \
     --resource-group <RESOURCE_GROUP> \
     --assign-identity

6. Run the following command to retrieve the Storage Account managed identity principal ID:

   az storage account show \
     --name <STORAGE_ACCOUNT_NAME> \
     --resource-group <RESOURCE_GROUP> \
     --query identity.principalId -o tsv

   Save the returned principal ID value to be used in Section 9.2: Granting Storage Account Access to the External Key.

9.2 Granting Storage Account Access to the External Key

Perform the following step to assign the Managed HSM Crypto Service Encryption User role to the Storage Account managed identity:

1. Run the following command using the Storage Account principal ID retrieved in Section 9.1: Creating a Storage Account and the Azure key name created in Section 8.0: Create an External RSA Key Reference:

   az keyvault role assignment create \
     --hsm-name <MANAGED_HSM_NAME> \
     --role "Managed HSM Crypto Service Encryption User" \
     --assignee <STORAGE_PRINCIPAL_ID> \
     --scope /keys/<AZURE_KEY_NAME>

   A successful response returns a JSON object containing the role assignment details.

NOTE

If a MatchingRoleAssignmentExists error is returned, the role assignment already exists, and no further action is required.

9.3 Enabling Customer-Managed Key Encryption

Ensure the following prerequisites are available before proceeding:

• The app UUID from Section 6.10: Copying the App UUID.

• The Fortanix DSM server CA certificate from Section 6.7: Retrieving the Fortanix DSM Server CA Certificate.

Perform the following steps to configure the Storage Account to use the external RSA key for encryption:

1. Run the following command to retrieve the Managed HSM URI:

   az keyvault show --hsm-name <MANAGED_HSM_NAME> --query properties.hsmUri -o tsv

   The output is in the format https://<MANAGED_HSM_NAME>.managedhsm.azure.net/.

2. Run the following command to configure the Storage Account encryption:

   az storage account update \
     --name <STORAGE_ACCOUNT_NAME> \
     --resource-group <RESOURCE_GROUP> \
     --encryption-key-name <AZURE_KEY_NAME> \
     --encryption-key-source Microsoft.Keyvault \
     --encryption-key-vault <MANAGED_HSM_URI>

10.0 Verify the Integration

Perform the following verification steps to verify end-to-end integration between Azure Managed HSM, Fortanix DSM, and Azure Storage.

10.1 Verifying External Key Management Connection

Confirm that the ekm-connection create command in Section 7.0: Create an External Key Management Connection returned a valid proxy metadata containing the Fortanix DSM vendor information.

10.2 Verifying Storage Encryption

Run the following command to verify Storage Account encryption configuration:

az storage account show \
  --name <STORAGE_ACCOUNT_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --query "encryption"

A successful response returns the following output:

{
  "encryptionIdentity": null,
  "keySource": "Microsoft.Keyvault",
  "keyVaultProperties": {
    "currentVersionedKeyExpirationTimestamp": "1970-01-01T00:00:00+00:00",
    "currentVersionedKeyIdentifier": "https://<MANAGED_HSM_NAME>.managedhsm.azure.net/keys/<AZURE_KEY_NAME>/<KEY_VERSION>",
    "keyName": "<AZURE_KEY_NAME>",
    "keyVaultUri": "https://<MANAGED_HSM_NAME>.managedhsm.azure.net/",
    "keyVersion": null,
    "lastKeyRotationTimestamp": "<TIMESTAMP>"
  },
  "requireInfrastructureEncryption": false
}

Confirm that the output shows:

• keySource: "Microsoft.Keyvault"

• keyVaultProperties.keyName matches the Azure key name created in Section 8.0: Create an External RSA Key Reference.

• keyVaultProperties.keyVaultUri matches the Managed HSM URI.

• keyVaultProperties.currentVersionedKeyIdentifier contains a valid key version URI.

10.3 Verifying Fortanix DSM Audit Logs

In the Fortanix DSM UI, navigate to the Audit Logs section and confirm that wrap and unwrap operations originating from the Azure Managed HSM are recorded. This confirms that cryptographic operations are being performed inside Fortanix DSM.

10.4 Verifying Azure Diagnostic Logs

In the Log Analytics Workspace configured in Section 6.4: Configuring Diagnostic Logging, query the audit log table and confirm that external key management-related AuditEvent entries are present for the Managed HSM instance.

The integration is successfully configured when Azure Key Vault Managed HSM can access the Fortanix DSM key through the external key management connection and Azure Storage encryption operations complete successfully using the external key.

11.0 Troubleshooting

This section describes common errors encountered during the integration of Fortanix DSM with Azure Key Vault Managed HSM external key management and the recommended resolution steps.