Edit

Configure networking and mTLS for Managed HSM external key management

This article covers the network and transport-layer security configuration required to connect Managed HSM to your EKM Proxy. It's aimed at network and security engineers who are setting up or maintaining an external key management deployment.

You'll learn how to choose a connectivity model, what outbound traffic Managed HSM generates, and how to provision and rotate the mutual TLS (mTLS) certificates that authenticate both sides of the connection.

This connection carries key-protection requests for your Azure service integration, not workload data. For the encryption model, see How CMK encryption at rest works.

For the end-to-end architecture and request flow, see Managed HSM external key management architecture. For command-level setup steps, see Quickstart: Create your first external key using the Azure CLI.

Connectivity models

Managed HSM initiates an outbound mTLS connection to your EKM Proxy. Two connectivity models are supported:

  • Public internet. The EKM Proxy is reachable over the public internet on a publicly resolvable FQDN. Choose this model for the simplest setup.
  • Azure Private Link (preview). Managed HSM reaches the EKM Proxy through a managed private endpoint to an Azure Private Link Service that you publish in front of the proxy. Choose this model when your security or compliance requirements prohibit exposing the proxy to the public internet.

Security doesn't depend on network-layer restrictions in either model. The connection is protected by mutual TLS (mTLS): both sides present and verify X.509 certificates before any payload is exchanged. Private Link adds network isolation on top of mTLS; it doesn't replace it. Managed HSM source IPs aren't static and can't be allow-listed, so certificate-based identity is the supported security mechanism in both models.

Configure the public-internet model

In this model, the EKM Proxy is reachable over the public internet on a publicly resolvable FQDN.

  1. Deploy the EKM Proxy on a host with a public IP and a DNS record.
  2. Obtain a TLS server certificate from a certificate authority (CA) whose root certificate you'll register on the external key management connection.
  3. Configure the proxy to listen on TCP port 443 with TLS 1.3 enabled. Port 443 is required.
  4. Create the external key management connection with --host set to the public FQDN and --server-ca-certificate set to the root CA in PEM format.

For the full az keyvault ekm-connection create command, see Quickstart: Create your first external key using the Azure CLI.

Note

Even though the proxy is publicly reachable, the connection is still mutually authenticated. An attacker who reaches the proxy endpoint without a valid Managed HSM client certificate can't complete the handshake.

Important

Azure Private Link integration for Managed HSM external key management is in preview. Preview features are made available to you on the condition that you agree to the supplemental terms of use. Some aspects of this integration might change before general availability. The core external key management feature is generally available.

In the Private Link model, you publish your EKM Proxy behind an Azure Private Link Service, and Managed HSM connects to it through a managed private endpoint. Traffic flows over the Microsoft backbone network instead of the public internet.

For portal steps with screenshots, see Connect through Azure Private Link in the portal quickstart. The following sections use the Azure CLI and REST APIs.

Create the private endpoint separately from the external key management connection. The Private Link Service owner must approve the endpoint before you can use it in an external key management connection.

Prerequisites

Before you begin, you need:

  • An existing Managed HSM pool in a subscription enabled for external key management, and the Managed HSM EKM Administrator role. For role assignment guidance, see Managed HSM access control.
  • Azure CLI signed in to the correct tenant and subscriptions.
  • An EKM Proxy behind a Standard Azure Load Balancer, with the proxy listening on TCP 443 with TLS 1.3 enabled.
  • An Azure Private Link Service in front of the load balancer's frontend IP configuration. Obtain its alias, and arrange for its owner to approve the connection request.
  • The proxy's TLS server certificate, its root CA certificates, and an optional URL path prefix. Identify a proxy server name that matches the certificate's subject alternative name (SAN).
  • A proxy configured to trust your Managed HSM client certificate. See Show the Managed HSM client certificate.

The following steps use az rest to call the Managed HSM data-plane APIs. The examples use pe1 as the private endpoint name. A pool supports up to two EKM Proxy private endpoints, but still has one external key management connection.

Create the private endpoint

Save the following JSON as pe-body.json. Replace privateLinkServiceId with your Private Link Service alias.

{
  "privateLinkServiceId": "<Private Link Service alias>",
  "requestMessage": "Request from Managed HSM for EKM Proxy private endpoint"
}

Create the endpoint:

az rest --method POST \
    --uri "https://<Managed HSM Name>.managedhsm.azure.net/ekm/privateendpoint/pe1" \
    --resource "https://managedhsm.azure.net" \
    --headers "Content-Type=application/json" \
    --body "@pe-body.json"

This operation runs asynchronously. Copy the jobId from the response for the next step.

Wait for endpoint creation

Wait 10 seconds, then retrieve the operation status, replacing <jobId> with the returned identifier:

az rest --method GET \
    --uri "https://<Managed HSM Name>.managedhsm.azure.net/ekm/privateendpoint/operations/<jobId>" \
    --resource "https://managedhsm.azure.net"

Repeat the query while status is Running, waiting 10 seconds between requests. Continue only when status is Succeeded. If the operation finishes with another status, inspect statusDetails and error, and resolve the failure before continuing.

The Private Link Service owner approves the connection in the subscription that contains the service. This approval authorizes the private endpoint connection and is separate from the automatically approved subscription feature registration.

First, find the pending connection request for the endpoint you created:

az network private-link-service show \
    --resource-group <Resource Group> \
    --name <Private Link Service Name>

The connection name is listed under privateEndpointConnections. Approve that connection:

az network private-link-service connection update \
    --resource-group <Resource Group> \
    --service-name <Private Link Service Name> \
    --name <Connection Name> \
    --connection-status Approved \
    --description "Approved"

Verify endpoint approval

Retrieve the endpoint from Managed HSM:

az rest --method GET \
    --uri "https://<Managed HSM Name>.managedhsm.azure.net/ekm/privateendpoint/pe1" \
    --resource "https://managedhsm.azure.net"

Verify that privateLinkServiceConnectionState.status is Approved before creating or updating the external key management connection. A successful creation operation doesn't replace this approval check. If the endpoint isn't approved, connection creation or update returns an error.

Create the external key management connection

Save the following JSON as ekm-create-body.json:

{
  "host": "pe1",
  "connectivity_mode": "PrivateEndpoint",
  "server_subject_common_name": "<EKM Proxy server name matching the certificate SAN>",
  "server_ca_certificates": [
    "<Base64-encoded DER root CA certificate>"
  ],
  "path_prefix": "/api/v1"
}

In PrivateEndpoint mode, host is the name of the approved private endpoint in your Managed HSM pool, not a Private Link Service alias, DNS name, or IP address. Set server_subject_common_name to a proxy server name that matches the certificate's SAN so Managed HSM can authenticate the server independently of the endpoint name. Remove path_prefix if your proxy doesn't use a path prefix.

For REST requests, server_ca_certificates contains Base64-encoded DER certificates, not file paths or PEM text. Use your proxy's root CA certificates, not its leaf certificate. If a root certificate is in PEM format, you can convert it with OpenSSL:

openssl x509 -in root-ca.pem -outform DER -out root-ca.der
openssl base64 -A -in root-ca.der

Copy the encoded value into server_ca_certificates, then create the connection:

az rest --method POST \
    --uri "https://<Managed HSM Name>.managedhsm.azure.net/ekm/create" \
    --resource "https://managedhsm.azure.net" \
    --headers "Content-Type=application/json" \
    --body "@ekm-create-body.json"

If you already have an external key management connection, update it by following Change from public internet to Private Link (preview) instead.

Verify the external key management connection

Check that Managed HSM can reach and authenticate to your proxy:

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

Note

Private Link provides network isolation, but mTLS still applies. The EKM Proxy must continue to validate the Managed HSM client certificate on every connection, and Managed HSM still validates the proxy's server certificate against the registered root CA.

To change an existing external key management connection:

  1. Complete the private endpoint setup (preview) through Verify endpoint approval. Wait for endpoint creation to succeed, approve the connection on the Private Link Service, and verify that Managed HSM reports privateLinkServiceConnectionState.status as Approved. Don't create another external key management connection.

  2. Save the following JSON as ekm-update-body.json, using the approved endpoint's name:

    {
  "host": "pe1",
  "connectivity_mode": "PrivateEndpoint"
}

  3. Update the existing connection:

    az rest --method PATCH \
    --uri "https://<Managed HSM Name>.managedhsm.azure.net/ekm" \
    --resource "https://managedhsm.azure.net" \
    --headers "Content-Type=application/json" \
    --body "@ekm-update-body.json"

  4. Verify connectivity after the update:

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

mTLS overview

The connection between Managed HSM and the EKM Proxy uses mutual TLS (mTLS). Both sides present X.509 certificates and both sides verify the peer's certificate before exchanging any payload.

  • Server certificate: the EKM Proxy presents this certificate to Managed HSM. Managed HSM validates it against the root CA you registered on the external key management connection.
  • Client certificate: Managed HSM presents this certificate to the EKM Proxy. The proxy must validate it and reject connections from unknown issuers.

This bidirectional authentication is what establishes identity. Managed HSM source IPs aren't stable and aren't customer-pinnable, so IP-based allow-listing is insufficient. Certificate-based identity is the only supported mechanism.

TLS requirements:

  • Minimum version: TLS 1.3.
  • Required cipher suites: TLS_AES_256_GCM_SHA384, TLS_AES_128_GCM_SHA256.

Server certificate (proxy → Managed HSM)

The proxy's server certificate is a standard PKIX certificate. You're responsible for provisioning, renewing, and revoking it.

What Managed HSM validates:

  • The certificate chains to the root CA registered on the external key management connection through --server-ca-certificate or the REST server_ca_certificates field.
  • The certificate is within its validity window.
  • In the public-internet model, the subject alternative name (SAN) matches the configured proxy hostname.
  • In the Private Link model, the SAN matches server_subject_common_name. The private endpoint name in host isn't the proxy's certificate identity.

What --server-ca-certificate accepts:

A root CA certificate in PEM or DER format. Pass the file path to the certificate when running az keyvault ekm-connection create or az keyvault ekm-connection update. In the Azure portal upload flow, use PEM format with a .cer extension.

Rotating the server certificate:

  • If the new certificate chains to the same root CA already registered on the external key management connection, deploy the new certificate to the proxy. No change to the external key management connection is required.

  • If the new certificate uses a different root CA, update the external key management connection with the new CA before you deploy the new certificate:

    az keyvault ekm-connection update \
  --hsm-name <Managed HSM Name> \
  --server-ca-certificate oldandnewrootcas.pem

    Update the connection first to avoid a window where the proxy presents a certificate that Managed HSM can't validate.

Client certificate (Managed HSM → proxy)

Managed HSM presents a pool-specific X.509 client certificate to the proxy on every connection. Microsoft issues and manages this certificate.

Retrieve information about the client certificate Managed HSM uses to authenticate to the EKM Proxy:

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

The command returns the client certificate's subject common name and an array of X.509 root certificates, where each certificate is encoded as Base64 DER.

Configure the proxy to accept the certificate:

The proxy must allow-list both:

  • The client certificate's subject common name (subjectCommonName).
  • The root certificates (caCertificates) returned by the command.

Because allow-listing is based on the subject common name and root CA rather than a specific certificate fingerprint, the proxy continues to accept connections after Managed HSM rotates the client certificate, as long as the subject common name and root CA are unchanged.

mTLS client certificate rotation

Microsoft rotates the Managed HSM client certificate on a schedule. The new certificate is issued before the old one expires, and Managed HSM presents the new certificate automatically after rotation.

Because the proxy allow-lists by subject common name and root certificates rather than by a specific certificate, no action is required when the certificate rotates, as long as the subject common name and caCertificates are unchanged.

Monitoring strategy:

  1. Run az keyvault ekm-connection certificate show --hsm-name <Managed HSM Name> on a schedule (for example, weekly by using a cron job or Azure Automation runbook).
  2. Watch for changes to the returned caCertificates array.
  3. If the caCertificates change, retrieve the new caCertificates array and allow-list them on your EKM Proxy side.

Firewall and DNS requirements

Configure both firewall rules and DNS on the network where your EKM Proxy runs.

Firewall rules

Public-internet model. Configure the firewall on the network segment where the proxy runs to:

  • Allow inbound TCP 443 from the public internet. Port 443 is required. Managed HSM source IPs aren't static and can't be allow-listed, so you can't restrict inbound traffic to only Managed HSM.
  • Allow inbound TLS 1.3 with the required cipher suites.

Private Link model. The proxy doesn't need to accept inbound traffic from the public internet. It receives traffic from your Private Link Service through the load balancer, so you can restrict inbound rules to the load balancer or Private Link Service subnet. The proxy still listens on TCP 443 with TLS 1.3 and the required cipher suites.

Note

No Azure service tags exist for Managed HSM EKM outbound traffic. Because Managed HSM source IPs aren't static, IP-based allow-listing isn't supported. In the public-internet model, the proxy must accept TCP 443 from any source. mTLS client certificate validation is the sole supported access control mechanism.

Don't rely on IP-based allow-listing as a security control. mTLS client certificate validation is the authentication mechanism that protects the proxy.

DNS requirements

  • Public-internet model. The proxy FQDN configured on the external key management connection must resolve to a publicly reachable address from Managed HSM's perspective.
  • Private Link model. Managed HSM connects through the approved private endpoint named in host rather than resolving or routing to the proxy by its FQDN. No public or customer-managed private DNS zone is required for the proxy's name. The proxy's server name still identifies it during TLS authentication: set server_subject_common_name to a name that matches the certificate's SAN.
  • If you change the proxy server name used for certificate validation, update the external key management connection to reflect the new value.

Troubleshooting common networking failures

For the full troubleshooting guide, see Troubleshoot Managed HSM external key management. The three most common networking-specific symptoms are:

Certificate mismatch

The mTLS handshake fails because the proxy's server certificate doesn't chain to the CA registered on the external key management connection, or the Managed HSM client certificate's subject name or root CA isn't in the proxy's allow-list. Check az keyvault ekm-connection certificate show and verify the proxy allow-list is current. Verify the external key management connection's --server-ca-certificate matches the root CA that issued the current proxy certificate.

Name resolution failure

Managed HSM can't resolve the proxy FQDN. This happens when the public DNS record for the proxy is missing or stale. Confirm that the FQDN in the external key management connection resolves to the correct public IP.

Connection timeout

The TCP connection to the proxy times out. A common cause is a firewall rule blocking inbound traffic on the proxy port. Check firewall logs and verify the proxy is listening on the expected port.

Related content

  • Last updated on