Edit

Quickstart: Create your first external key using the Azure CLI

In this quickstart, you connect your external HSM to Managed HSM, create an external key reference, and test the key-protection path. You then use the Managed HSM key URI to configure customer-managed-key (CMK) encryption at rest in a compatible Azure service.

For the encryption model and service compatibility, see What is Managed HSM external key management?

If you prefer to use the Azure portal, see Quickstart: Create your first external key using the Azure portal.

Prerequisites

Before you begin, you need:

  • An existing Managed HSM deployed in any Azure public region, in a subscription enabled for external key management. To create a Managed HSM, see Quickstart: Provision and activate a Managed HSM using Azure CLI.
  • An operational EKM Proxy reachable from Azure. The proxy must implement the EKM Proxy API specification. For supported vendors, see What is Managed HSM external key management?.
  • A key created in your external HSM with a known external key identifier. The external key identifier is the identifier your proxy uses to look up the key.
  • The root CA certificate (PEM format) that signed your proxy's TLS server certificate.
  • Azure CLI version 2.x with the latest keyvault extension installed. Run az extension add --name keyvault or az extension update --name keyvault to get the latest version.
  • The Managed HSM EKM Administrator role to manage external key management connections, and the Managed HSM Crypto User role to create and use keys. For role assignment steps, see Managed HSM access control.

Sign in to Azure

az login

Set your subscription if you have more than one:

az account set --subscription "<subscription-id>"

Show the Managed HSM client certificate

Managed HSM presents an X.509 client certificate to your EKM Proxy on every inbound mutual TLS (mTLS) connection. Before you create the external key management connection, retrieve the certificate subject common name and the root CA certificate and allow-list it at your proxy. This lets the proxy validate that the connection comes from your Managed HSM, not an arbitrary caller.

az keyvault ekm-connection certificate show --hsm-name <Managed HSM Name>

The output looks similar to this:

{
  "caCertificates": [
    "MIIDj...<truncated>...MrY="
  ],
  "subjectCommonName": "contoso.managedhsmclient.azure.net"
}

Configure your proxy to trust connections that present certificate with the subjectCommonName and rooted to one of the certificates in caCertificates list above. The exact steps depend on your proxy vendor.

Note

For rotation steps and certificate lifecycle details, see Configure networking and mTLS for Managed HSM external key management.

Create the external key management connection

The external key management connection binds your Managed HSM to a single EKM Proxy. It contains the proxy address, the server CA trust anchor, and an optional path prefix.

This section creates a public internet connection. For Private Link, follow Configure the Azure Private Link model (preview) instead, then continue with Verify the connection.

az keyvault ekm-connection create \
    --hsm-name <Managed HSM Name> \
    --host <EKMProxy Host> \
    --server-ca-certificate <Root cert> \
    [--path-prefix <prefix>]

Parameter reference:

  • --hsm-name: The name of your Managed HSM.
  • --host: The fully qualified hostname of your EKM Proxy. For example, proxy.contoso.com. The proxy must listen on TCP port 443; a nonstandard port isn't supported.
  • --server-ca-certificate: Specifies the path to the root CA certificate file (PEM or DER format) used to verify the proxy's TLS server certificate.
  • --path-prefix (optional): A URL path prefix if your proxy multiplexes multiple customers or pools by path. For example, /contoso/prod.

Note

Pass the root CA certificate to --server-ca-certificate, not the proxy's leaf certificate. Managed HSM uses this CA to validate the entire certificate chain presented by your proxy during the mTLS handshake. Passing the leaf certificate instead causes the handshake to fail for any certificate renewal.

Verify the connection

After creating the connection, verify that Managed HSM can reach your proxy:

az keyvault ekm-connection check --hsm-name <Managed HSM Name>

This command calls the proxy's /info endpoint through the configured connection. Successful output looks similar to this:

{
  "apiVersion": "1.0",
  "ekmProduct": "Contoso HSM v1.0.0",
  "ekmVendor": "Contoso HSM",
  "proxyName": "Contoso Proxy Service",
  "proxyVendor": "Contoso Proxy"
}

Common failure causes include firewall rules blocking the proxy port, an incorrect --host value, or the proxy rejecting the Managed HSM client certificate. For remediation steps, see Troubleshoot Managed HSM external key management.

Create the external key

Create a Managed HSM key reference that points at the external key in your HSM. Managed HSM doesn't generate any key material. This command registers a reference to an existing key identified by its external key identifier.

az keyvault key create \
    --external-key-id <external-key-identifier> \
    --hsm-name <Managed HSM Name> \
    --name <key-ref-name>

Parameter reference:

  • --external-key-id: The external key identifier registered at your proxy. This is the identifier the proxy uses to look up the correct key in your external HSM.
  • --hsm-name: The name of your Managed HSM.
  • --name: The name you want to give the Managed HSM key reference. This becomes part of the key URI that Azure services use.

Important

The external key identifier is immutable for the lifetime of a key version. You can't change it after creation. To rotate the key, create a new key version with a new external key identifier using az keyvault key create with the same --name. The key URI (HSM URI + key name) stays stable across versions; only the version segment changes.

The command returns the key URI in the form https://<hsm-name>.managedhsm.azure.net/keys/<key-ref-name>/<version>. Keep this URI for configuring your Azure service.

Verify wrap/unwrap

Test the key protection path with a wrap and unwrap round trip. The external HSM performs the operations through your proxy, and Managed HSM returns the result. This test confirms the key path works. It doesn't configure or validate an Azure service's CMK integration.

Note

Use the wrapkey and unwrapkey data-plane endpoints with az rest for this test. az keyvault key encrypt calls a different key API operation and isn't a substitute for wrapping a data encryption key.

  1. Create a request body for the wrap operation. Set value to the base64url-encoded key material you want to wrap.

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

    Save it as wrapkey.json. For AES external keys, use "alg": "A256KW" instead of RSA-OAEP-256.

  2. Call the wrapkey endpoint on your key reference:

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

    The response returns the key version (kid) and a value field containing the base64url-encoded wrapped key. Copy the value for the next step.

  3. Create a request body for the unwrap operation, using the wrapped value from the previous step:

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

    Save it as unwrapkey.json.

  4. Call the unwrapkey endpoint to confirm round-trip correctness:

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

    A successful response returns the original plaintext value you wrapped in the first step. If the unwrap fails, see Troubleshoot Managed HSM external key management for proxy error codes and remediation steps.

Use the key with an Azure service

Complete the workload integration by following your Azure service's CMK configuration documentation:

  1. Confirm that the service supports CMKs with Managed HSM and that your external key's type and algorithm meet its requirements.
  2. Grant the identity used by the service the required Managed HSM local RBAC permissions. For role assignment guidance, see Managed HSM access control.
  3. Configure the service's CMK settings with your Managed HSM key URI. Use the versioned or unversioned URI format required by that service. For Azure Storage, see Configure customer-managed keys with Azure Key Vault Managed HSM.
  4. Confirm that the service reports the expected CMK configuration, then perform a read/write operation on the protected workload. Review the service's diagnostics and Managed HSM external key management logs if the operation fails.

The Azure service uses its existing Managed HSM integration. It doesn't need your external HSM's vendor-specific API or credentials.

View audit logs

Every EKM Proxy call produces an EkmProxyOperation entry in your Managed HSM diagnostic logs. To query these in Log Analytics:

AzureDiagnostics
| where ResourceProvider == "MICROSOFT.KEYVAULT"
| where OperationName contains "Ekm"
| project TimeGenerated, Resource, OperationName, requestUri_s, ResultType, ResultDescription

The log includes the operation type (wrap or unwrap), the external key identifier, the HTTP status code returned by the proxy, and the round-trip latency. For the full logging and monitoring guide, including alert configuration and proxy-side log correlation, see Logging and monitoring for Managed HSM external key management.

Clean up resources

If you configured an Azure service to use this key, migrate the workload to another key before deleting the reference or connection. Retain the external key and its connection for as long as the workload's data, backups, or snapshots require it.

To remove the resources created in this quickstart:

  1. Delete the Managed HSM key reference:

    az keyvault key delete \
    --hsm-name <Managed HSM Name> \
    --name <key-ref-name>

  2. Delete the external key management connection:

    az keyvault ekm-connection delete \
    --hsm-name <Managed HSM Name>

Deleting the Managed HSM key reference doesn't affect the key material in your external HSM. That key remains in your HSM until you remove it there.

Next steps

  • Last updated on