Microsoft Azure Key Vault Managed HSM

Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.

Create a partition that will be later on used by Managed HSM via EKM Proxy.

Create and exchange certificates between the Luna Network HSM and client system. Register client and assign partition to create an NTLS connection.

Initialize Crypto Officer and Crypto User roles for the registered partition.

Ensure that each partition is successfully registered and configured. Use the following command to view the registered partitions:

# /usr/safenet/lunaclient/bin/lunacm

Upon successful execution, you should observe an output similar to the example provided below:

lunacm (64-bit) v10.9.0-65. Copyright (c) 2025 Thales Group. All rights reserved.

Available HSMs:
Slot Id ->              0
Label ->                TPA01
Serial Number ->        1312109862206
Model ->                LunaSA 7.8.4
Firmware Version ->     7.8.4
Bootloader Version ->   1.1.2
Configuration ->        Luna User Partition With SO (PW) Key Export
                        With Cloning Mode
Slot Description ->     Net Token Slot
FM HW Status ->         Non-FM

For PED-authenticated HSM, enable partition policies 22 and 23 to allow activation and auto-activation.

For detailed instructions on configuring Luna HSM, including creating an NTLS connection, initializing partitions, and assigning user roles, refer to the Luna HSM documentation.

Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means.

Extract the .zip file into a directory on your client workstation.

Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.

tar -xvf cvclient-min.tar

Run the setenv script to generate a new configuration file with the necessary information for the Luna Cloud HSM service. Right-click setenv.cmd and select Run as Administrator.

To add the configuration to an already installed UC client, use the –addcloudhsm option when running the setenv script.

Run the LunaCM utility and verify that the Cloud HSM service is listed.

Before generating the key pair, decide on a unique label and id for the key. The label can be any name you choose. The id must be a 16-byte hexadecimal value (GUID) that uniquely identifies the key. The id attribute is used by Azure Key Vault Managed HSM to locate the key through the Luna EKM Proxy, so ensure that each KEK is assigned a unique id.

You can use an online GUID generator to generate a unique GUID: https://www.guidgenerator.com

Alternatively, use one of the following Linux commands to generate a 16-byte (32-character) hexadecimal value for the id attribute:
# head -c16 </dev/urandom | xxd -p -u
# xxd -len 16 -plain /dev/urandom

Generate an RSA key pair by running the following command on your workstation, replacing the label and id values with your own:

# /usr/safenet/lunaclient/bin/cmu generatekeypair -modulusBits=2048 -publicExponent=65537 -label=EKMKey1 -encrypt=1 -decrypt=1 -wrap=1 -unwrap=1 -id=54F32D6571E9541C7E2C47395FC269DD

Where:

• label specifies the name of the key.

• id specifies the 16-byte hexadecimal value (GUID) generated in the previous step, which uniquely identifies the key.

Enter the partition password when prompted, and select PKCS as the mechanism type.

Verify that the key pair has been created by running the following command. When prompted, enter the partition password.

# /usr/safenet/lunaclient/bin/cmu list

Ensure that OpenSSL 3.x is installed on the system where the Luna Client is installed and an NTLS connection to the Luna HSM is configured. Install OpenSSL if it is not already available.

Open the <OPENSSLDIR>/openssl.cnf file in a text editor and update the [CA_default] section as follows:

dir             = /etc/pki/CA
new_certs_dir   = $dir/certs

You can change the value of dir to a different location. If you do so, use the updated path consistently throughout the remaining steps.

Create the directory for storing generated certificates if it does not already exist.

# mkdir -p /etc/pki/CA/certs

Create the following files:

• /etc/pki/CA/index.txt

• /etc/pki/CA/serial

Open /etc/pki/CA/serial, enter the value 01 on the first line, save the file, and close it.

Open <OPENSSLDIR>/openssl.cnf again and update the [v3_ca] section as follows:

[ v3_ca ]

subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer
basicConstraints = critical,CA:true
keyUsage = critical, digitalSignature, cRLSign, keyCertSign

Create the required directories for the Luna EKM Proxy.

# mkdir -p /opt/ekm/bin
# mkdir -p /opt/ekm/conf
# mkdir -p /opt/ekm/certs

Change to the /opt/ekm/certs directory. The remaining steps generate the Certificate Authority (CA) certificate and the EKM Proxy server certificate used to establish a TLS connection with Azure Key Vault Managed HSM.

Generate the CA private key.

# openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out ca.key

Generate a Certificate Signing Request (CSR) using the CA private key.

# openssl req -key ca.key -new -out ca.csr

Generate the CA certificate by signing the CSR with the CA private key.

# openssl x509 -signkey ca.key -in ca.csr -req -extfile /etc/pki/tls/openssl.cnf -extensions v3_ca -days 365 -out ca.crt

Generate the EKM Proxy server private key.

# openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out server.key

Generate a CSR for the EKM Proxy server. The Common Name (CN) in the server certificate must match the EKM Proxy endpoint hostname or the hostname configured in Azure Key Vault Managed HSM. For example, if the public endpoint is server.ekmproxy.example.com, specify either server.ekmproxy.example.com or *.ekmproxy.example.com as the CN.

# openssl req -key server.key -new -out server.csr

Sign the EKM Proxy server CSR using the CA certificate and private key to generate the server certificate.

# openssl ca -policy policy_anything -cert ca.crt -keyfile ca.key -in server.csr -out server.crt

Copy the downloaded EKM Proxy binary to the /opt/ekm/bin directory and make it executable.

# cp ekm_proxy /opt/ekm/bin/
# chmod +x /opt/ekm/bin/ekm_proxy

Create the EKM Proxy configuration file used by the service at startup.

# vi /opt/ekm/conf/ekm_proxy.conf

Add the following configuration and update the parameter values to match your environment.

ChrystokiConfigurationPath=/etc
HOST=server.ekmproxy.example.com
PORT=443
P11_LIB=/usr/safenet/lunaclient/lib/libCryptoki2_64.so
P11_TOKEN=TPA01
P11_PIN=userpin1
USER_TYPE=1
CACHING_ENABLED=false
DEBUG_LOGGING_ENABLED=true
TLS_CERT=/opt/ekm/certs/server.crt
TLS_KEY=/opt/ekm/certs/server.key
TLS_CA=/opt/ekm/certs/ca.crt
TLS_CLIENT_CN=EKM-Client
PERFORMANCE_LOGGING_ENABLED=true
CACHE_TTL_MINUTES=10

The following table describes the EKM Proxy configuration parameters:

Create a user account and assign the required permissions to run the EKM Proxy service. Skip this step if the service will be run as the root user.

# useradd ekmuser
# gpasswd --add ekmuser hsmusers
# chown -R ekmuser:hsmusers /opt/ekm
# chmod -R 755 /opt/ekm/bin

Create a systemd service to run the EKM Proxy as a system service under a non-privileged user account.

# vi /etc/systemd/system/ekm_proxy.service

Add the following configuration to the ekm_proxy.service file.

[Unit]
Description=EKM Proxy Service
After=network.target

[Service]
Type=simple
User=ekmuser
Group=hsmusers
Restart=on-failure

# Required to allow a non-privileged user to bind to port 443.
AmbientCapabilities=CAP_NET_BIND_SERVICE

RestartSec=5
EnvironmentFile=-/opt/ekm/conf/ekm_proxy.conf
ExecStart=/opt/ekm/bin/ekm_proxy

[Install]
WantedBy=multi-user.target

Reload the systemd configuration, enable the EKM Proxy service, and start the service.

# systemctl daemon-reload
# systemctl enable ekm_proxy
# systemctl start ekm_proxy

Verify that the EKM Proxy service is running.

# systemctl status ekm_proxy -l --no-pager

Sign in to Azure using Azure CLI.

# az login

Verify that the Azure Key Vault Managed HSM is provisioned and accessible. The command returns details about the Managed HSM. Verify that it is in an active state before proceeding.

# az keyvault show --hsm-name <MHSM-Name>

Retrieve the Root CA certificate and the CN of the Azure Key Vault Managed HSM client certificate.

# az keyvault ekm-connection certificate show --hsm-name <MHSM-Name>

Save the Root CA certificate and CN. The EKM Proxy uses these values to authenticate incoming TLS connections. It will only trust a connection if the presented certificate matches the specified CN and is signed by the specified CA certificate.

Copy the Root CA certificate from the command output and save it as /opt/ekm/certs/mhsm-ca.crt in PEM format.

-----BEGIN CERTIFICATE-----
<paste the copied certificate here>
-----END CERTIFICATE-----

Open the EKM Proxy configuration file and update the TLS_CA and TLS_CLIENT_CN parameters with the CA certificate and CN values retrieved in the previous steps.

# vi /opt/ekm/conf/ekm_proxy.conf

TLS_CA=/opt/ekm/certs/mhsm-ca.crt
TLS_CLIENT_CN=<subjectCommonName>

Restart the EKM Proxy service.

# systemctl restart ekm_proxy

Ensure that the service restarts successfully without any errors.

Create the EKM connection on Azure Key Vault Managed HSM.

# az keyvault ekm-connection create --hsm-name <MHSM-Name> --host <EKM-Proxy-Host-Name> --server-ca-certificate <EKM-Proxy-Server-CA-Certificate>

Where:

• --server-ca-certificate specifies the EKM Proxy server CA certificate (/opt/ekm/certs/ca.crt) that was generated using OpenSSL and used to sign the EKM Proxy server TLS certificate.

• --host specifies the EKM Proxy endpoint in the format hostname or hostname:port. If no port is specified, Azure uses the default HTTPS port (443).

Verify the EKM connection.

# az keyvault ekm-connection check --hsm-name <MHSM-Name>

Create a key reference in Azure Key Vault Managed HSM that points to an existing KEK in the Luna HSM.

# az keyvault key create --external-key-id <key-id-of-KEK> --hsm-name <MHSM-Name> --name <Managed-HSM-Key-Name>

Where:

• --external-key-id specifies the unique identifier (id) of the KEK created on the Luna HSM. The EKM Proxy uses this identifier to locate the corresponding key.

• --name specifies the name of the key reference created in Azure Key Vault Managed HSM.

No key material is generated or stored in Azure Key Vault Managed HSM. The command creates only a reference to the external key stored in the Luna HSM.

Both RSA and AES KEKs are supported. Ensure that the value specified for --external-key-id matches the id assigned to the KEK when it was created on the Luna HSM.

Verify that the key reference has been created by opening the Keys page for your Azure Key Vault Managed HSM in the Azure portal.

Retrieve the Key Identifier (KID) of the key reference.

# az keyvault key show --hsm-name <MHSM-Name> --name <Managed-HSM-Key-Name> --query "key.kid" -o tsv

The KID uniquely identifies the key reference within Azure Key Vault Managed HSM.

After the key reference has been created, Azure services can use it for cryptographic operations. During these operations, Azure Key Vault Managed HSM forwards the requests to the EKM Proxy, which performs the requested operation using the corresponding key stored in the Luna HSM. To verify the integration, perform a wrap and unwrap operation as follows.

Create the request body for the wrap operation. Set the value field to the Base64URL-encoded plaintext key material to be wrapped, and save the file as wrapkey.json.

{
  "alg": "RSA-OAEP-256",
  "value": "<base64url-encoded-plaintext-key>"
}

For AES KEKs, specify "A256KW" or "A256KWP" instead of "RSA-OAEP-256" for the alg parameter.

Invoke the wrapkey endpoint on the Azure Key Vault Managed HSM key reference.

# az rest --method POST --uri "https://<Managed-HSM-Name>.managedhsm.azure.net/keys/<key-reference-name>/wrapkey?api-version=0.1" --resource "https://managedhsm.azure.net" --headers "Content-Type=application/json" --body @wrapkey.json

Create the request body for the unwrap operation using the wrapped value returned by the previous step. Save the file as unwrapkey.json.

{
  "alg": "RSA-OAEP-256",
  "value": "<wrapped-value>"
}

For AES KEKs, specify "A256KW" or "A256KWP" instead of "RSA-OAEP-256" for the alg parameter.

Call the unwrapkey endpoint to confirm round-trip correctness.

# az rest --method POST --uri "https://<Managed-HSM-Name>.managedhsm.azure.net/keys/<key-reference-name>/unwrapkey?api-version=0.1" --resource "https://managedhsm.azure.net" --headers "Content-Type=application/json" --body @unwrapkey.json

Create a new Storage Account in the "US Central EUAP" region, using Azure Blob Storage as the preferred storage type. Replace the placeholder values in angle brackets with your own unique values.

# az storage account create --name <account-name> --resource-group <resource-group> --location centraluseuap --sku Standard_RAGRS --kind StorageV2 --min-tls-version TLS1_2 --allow-blob-public-access false

Assign an identity to the storage account. Replace the placeholder values in angle brackets with your own unique values.

# az storage account update --name <account-name> --resource-group <resource-group> --assign-identity

Assign the Managed HSM Crypto Service Encryption User role to the storage account's managed identity, so that the storage account has permissions to access the Managed HSM.

Get the storage account's managed identity. Replace the placeholder values in angle brackets with your own unique values.

# az storage account show --name <account-name> --resource-group <resource-group> --query "identity.principalId" -o tsv

Assign the role to the storage account's managed identity.

# az keyvault role assignment create --hsm-name <MHSM-Name> --assignee <storage-account-principal-id> --role "Managed HSM Crypto Service Encryption User" --scope /keys/<managed-hsm-key-name>

Get the Managed HSM URI.

# az keyvault show --hsm-name <MHSM-Name> --query "properties.hsmUri" -o tsv

Configure Azure Storage encryption with a customer-managed key by using a key stored in the Managed HSM. Replace the placeholder values in angle brackets with your own unique values.

# az storage account update --name <account-name> --resource-group <resource-group> --encryption-key-source Microsoft.Keyvault --encryption-key-name <managed-hsm-key-name> --encryption-key-vault <managed-hsm-uri>

The storage account will be encrypted using the Managed HSM key, which in turn uses the Key Encryption Key generated on the Luna HSM. An output similar to the following will be displayed:

# az storage account update --name ekmteststorage01 --resource-group ResourceT0323769 --encryption-key-source Microsoft.Keyvault --encryption-key-name RSA-KEK --encryption-key-vault https://mhsmekmproxy.managedhsm.azure.net/
.
.
.
  "encryption": {
    "encryptionIdentity": null,
    "keySource": "Microsoft.Keyvault",
    "keyVaultProperties": {
      "currentVersionedKeyExpirationTimestamp": "1970-01-01T00:00:00+00:00",
      "currentVersionedKeyIdentifier": "https://mhsmekmproxy.managedhsm.azure.net/keys/RSA-KEK/d0f8e7d25f6647cb26f0b3f20a203b30",
      "keyName": "RSA-KEK",
      "keyVaultUri": "https://mhsmekmproxy.managedhsm.azure.net/",
      "keyVersion": null,
      "lastKeyRotationTimestamp": "2026-07-07T16:11:05.428337+00:00"
    },
.
.
.

Run the following command to query the encryption status.

# az storage account show --name <account-name> --resource-group <resource-group> --query "encryption" -o json

Log in to the Azure Portal and open the Encryption configuration of the Storage Account. The Encryption Type will be displayed as Customer-managed keys.