Edit

Quickstart: Create an Azure Payment HSM v2

Azure Payment HSM v2 is a highly available, single-tenant payment hardware security module (HSM) service for payment processing, credential issuance, PIN processing, key management, and authentication data protection. Azure Payment HSM v2 helps service providers and financial institutions modernize their payment systems and adopt the public cloud. For more information, see What is Azure Payment HSM v2?

This quickstart describes how to onboard and deploy an Azure Payment HSM v2 cluster within your private virtual network.

Prerequisites

Prepare your environment

  • Use Azure Cloud Shell or install Azure PowerShell. If you use Azure PowerShell locally, sign in to Azure.
  • Install OpenSSL to create the certificate.
  • Use an identity that has permission to create resource groups, virtual networks, private endpoints, private Domain Name System (DNS) zones, and Payment HSM v2 resources. The identity also needs permission to register Azure subscription features.
  • During preview, deploy Payment HSM v2 only in the West US or West Europe region.

Establish Azure and Utimaco accounts

Before onboarding Azure Payment HSM v2, confirm that your organization has an active Azure account and subscription, as well as a registered Utimaco Support Portal account. You need these accounts to provision resources, access software and documentation, and receive onboarding support.

Azure account

You must have an active Azure account and Azure subscription before onboarding Azure Payment HSM v2. If you don't have an Azure account, create a free account before you begin.

Utimaco account

Azure Payment HSM v2 onboarding requires an active Utimaco account and entitlement before provisioning. During public preview, after Microsoft approves your onboarding request, Microsoft connects you with the Utimaco Azure team. The team works directly with you to complete onboarding. New Utimaco account requests can take up to 48 hours to process and activate. If you don't have a Utimaco account, see Create an account in the Utimaco portal for instructions.

Receive and verify the onboarding welcome package

Utimaco provides the welcome package required for Azure Payment HSM v2 onboarding. The package includes the Secure Configuration Assistant (SCA) application, C3 Key Loading Device (KLD), smart cards, and related onboarding materials. Verify receipt of all package contents before you continue with onboarding activities.

Customer actions

  1. Confirm receipt of the onboarding welcome package and all materials included.
  2. Verify delivery of the SCA application, C3 KLD, smart cards, and supporting documentation.
  3. Send acknowledgment of package receipt to both Microsoft and Utimaco before you continue to the next onboarding step.

Establish client trust

To establish mutual trust between your environment and Azure Payment HSM v2, configure a trusted certification authority (CA) certificate for the management interface and the application interface. Use these certificates for client authentication and to establish secure, mutually authenticated connectivity to Azure Payment HSM v2. Create self-signed root CA certificates, and confirm that each certificate uses an elliptic curve (EC) public key on the National Institute of Standards and Technology (NIST) P-256 curve. Use the following example to generate certificates.

For the trust model behind these certificates, including the separate management and application trust anchors and why the service supports only self-signed P-256 root CAs, see Authentication and access control for Azure Payment HSM v2.

Create CA authentication certificates

Generate elliptic curve key pairs and create self-signed CA certificates by using the following OpenSSL commands.

Important

Use a self-signed root CA for each trusted issuer certificate. The certificate must use an EC public key on the NIST P-256 (prime256v1) curve. Azure Payment HSM v2 doesn't support intermediate CA certificates or certificates that use other cryptographic algorithms or key types.

  • Management-port trust CAs go in certs-mgmt/.
  • Application-port trust CAs go in certs/.

Generate CA keys and self-signed certificates

openssl ecparam -list_curves
openssl ecparam -genkey -name prime256v1 -out management-ca.key
openssl req -x509 -new -SHA384 -nodes -key management-ca.key -days 3650 -out management-trusted-ca.pem
openssl ecparam -genkey -name prime256v1 -out application-ca.key
openssl req -x509 -new -SHA384 -nodes -key application-ca.key -days 3650 -out application-trusted-ca.pem

Register the AllowPrivateEndpoints feature

Azure Payment HSM v2 requires a private endpoint. During public preview, Azure doesn't automatically register this capability. Register the AllowPrivateEndpoints feature for the Microsoft.Network resource provider on each subscription where you deploy the service. If you don't register this feature, the networking steps later in this quickstart fail.

Important

The Azure Payment HSM v2 team registers your Payment HSM v2 resource. Register the AllowPrivateEndpoints feature yourself on each subscription where you deploy the service. Registration can take a few minutes to complete. Wait until the feature shows a Registered state before you continue to Create a client virtual network and private DNS zone.

Set your subscription context, register the feature, and then verify the registration.

# Set your subscription context
Set-AzContext -Subscription "<subscription-id>"

# Register the AllowPrivateEndpoints feature
Register-AzProviderFeature -FeatureName "AllowPrivateEndpoints" -ProviderNamespace "Microsoft.Network"

# Verify the registration state (wait until it shows "Registered")
Get-AzProviderFeature -FeatureName "AllowPrivateEndpoints" -ProviderNamespace "Microsoft.Network" |
    Select-Object -ExpandProperty RegistrationState

Deploy Azure Payment HSM v2

Create a Payment HSM v2 instance

The following example creates a resource group and a Payment HSM v2 instance. Run the example from the directory that contains management-trusted-ca.pem and application-trusted-ca.pem. Set the subscription context and update the location, resource name, and resource group name to match your environment.

Important

Choose a unique HSM name. If you specify an HSM name that already exists in the chosen region, your deployment fails.

# Convert the PEM certificates to the Base64-encoded values required by the resource provider
$managementCertificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]::CreateFromPem(
    (Get-Content -Raw "management-trusted-ca.pem")
)
$managementTrustedIssuer = [Convert]::ToBase64String($managementCertificate.RawData)

$applicationCertificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]::CreateFromPem(
    (Get-Content -Raw "application-trusted-ca.pem")
)
$applicationTrustedIssuer = [Convert]::ToBase64String($applicationCertificate.RawData)

# Define variables for your Payment HSM v2 deployment
$server = @{
    Location = "<region-name>"
    Sku = @{ Family = "B"; Name = "Payments_v2" }
    ResourceName = "<hsm-name>"
    ResourceType = "Microsoft.HardwareSecurityModules/paymentHsmClusters"
    ResourceGroupName = "<hsm-resource-group-name>"
    ApiVersion = "2025-12-01-preview"
    Properties = @{
        autoGeneratedDomainNameLabelScope = "TenantReuse"
        applicationTrustedIssuer          = $applicationTrustedIssuer
        managementTrustedIssuer           = $managementTrustedIssuer
        publicNetworkAccess               = "Disabled"
    }
    Force = $true
}

# Create the HSM cluster resource group
New-AzResourceGroup -Name $server.ResourceGroupName -Location $server.Location -Force

# Create the HSM cluster and retain its resource ID for the private endpoints
$hsm = New-AzResource @server -Verbose

Note

Deploy your Payment HSM v2 resources in a separate resource group from your related client virtual network and virtual machine (VM) resources. Separate resource groups provide better management and security isolation.

Create a client virtual network and private DNS zone

Deploy your client virtual network and VM in the same region as your HSM resource. Update the resource group and virtual network names to match your environment. The following example creates a resource group, a virtual network with separate management and application subnets, and a private DNS zone. The example then links the zone to the virtual network.

$client = @{
    Location              = $server.Location
    ResourceGroupName     = "<client-resource-group-name>"
    ZoneName              = "privatelink.phsm.azure.net"
    VirtualNetworkName    = "<virtual-network-name>"
    ManagementSubnetName  = "management"
    ApplicationSubnetName = "application"
}

# Create the client resource group
New-AzResourceGroup -Name $client.ResourceGroupName -Location $client.Location -Force

# Create the virtual network
$vnet = New-AzVirtualNetwork -Name $client.VirtualNetworkName -ResourceGroupName $client.ResourceGroupName -Location $client.Location -AddressPrefix "10.0.0.0/16"

# Add the management subnet
$vnet = Add-AzVirtualNetworkSubnetConfig -Name $client.ManagementSubnetName -VirtualNetwork $vnet -AddressPrefix "10.0.2.0/24"

# Add the application subnet
$vnet = Add-AzVirtualNetworkSubnetConfig -Name $client.ApplicationSubnetName -VirtualNetwork $vnet -AddressPrefix "10.0.3.0/24"

# Commit the subnet configuration
$vnet = Set-AzVirtualNetwork -VirtualNetwork $vnet

# Retrieve the created subnet objects for use when you create the private endpoints later in this quickstart
$vnet = Get-AzVirtualNetwork -Name $client.VirtualNetworkName -ResourceGroupName $client.ResourceGroupName
$managementSubnet = $vnet.Subnets | Where-Object Name -eq $client.ManagementSubnetName
$applicationSubnet = $vnet.Subnets | Where-Object Name -eq $client.ApplicationSubnetName

# Create the private DNS zone and link it to the virtual network
$zone = New-AzPrivateDnsZone -ResourceGroupName $client.ResourceGroupName -Name $client.ZoneName
New-AzPrivateDnsVirtualNetworkLink -ResourceGroupName $client.ResourceGroupName -ZoneName $client.ZoneName -Name "privateDnsLink" -VirtualNetworkId $vnet.Id -EnableRegistration:$false

Create a private endpoint for Azure Payment HSM v2

Azure Payment HSM v2 exposes two private-link group IDs: management on port 7005 and application on port 2200. Create a separate private endpoint for each group ID by using the corresponding subnet from Create a client virtual network and private DNS zone. Create both endpoints for full administrative and payment-application access. If you need only administrative access, such as for the Utimaco Key Loading Device (KLD), create only the management endpoint.

First, create both private endpoints:

# Management endpoint (port 7005) - also used by the Utimaco Key Loading Device (KLD)
$managementConnection = New-AzPrivateLinkServiceConnection `
    -Name "$($server.ResourceName)-management-connection" `
    -PrivateLinkServiceId $hsm.ResourceId `
    -GroupId "management"

$managementEndpoint = New-AzPrivateEndpoint `
    -Name "$($server.ResourceName)-management-pe" `
    -ResourceGroupName $client.ResourceGroupName `
    -Location $client.Location `
    -Subnet $managementSubnet `
    -PrivateLinkServiceConnection $managementConnection

# Application endpoint (port 2200) - payment application data plane
$applicationConnection = New-AzPrivateLinkServiceConnection `
    -Name "$($server.ResourceName)-application-connection" `
    -PrivateLinkServiceId $hsm.ResourceId `
    -GroupId "application"

$applicationEndpoint = New-AzPrivateEndpoint `
    -Name "$($server.ResourceName)-application-pe" `
    -ResourceGroupName $client.ResourceGroupName `
    -Location $client.Location `
    -Subnet $applicationSubnet `
    -PrivateLinkServiceConnection $applicationConnection

Then, connect both endpoints to the private DNS zone so that their hostnames resolve from your virtual network:

$zoneConfig = New-AzPrivateDnsZoneConfig `
    -Name "phsmv2-private-dns-config" `
    -PrivateDnsZoneId $zone.ResourceId

New-AzPrivateDnsZoneGroup `
    -ResourceGroupName $client.ResourceGroupName `
    -PrivateEndpointName $managementEndpoint.Name `
    -Name "management-phsmv2-private-dns-zone-group" `
    -PrivateDnsZoneConfig $zoneConfig

New-AzPrivateDnsZoneGroup `
    -ResourceGroupName $client.ResourceGroupName `
    -PrivateEndpointName $applicationEndpoint.Name `
    -Name "application-phsmv2-private-dns-zone-group" `
    -PrivateDnsZoneConfig $zoneConfig

Tip

Private endpoints connect your virtual network to Azure Payment HSM v2 through Azure Private Link. Traffic between your virtual network and the service stays on the Microsoft network. This private connectivity reduces exposure to the public internet, as described in Network security for Azure Payment HSM v2.

Connect to Azure Payment HSM v2

After you provision your Payment HSM v2 instance and establish the private endpoints, set up connectivity to both the management and application interfaces of the Azure Payment HSM v2 cluster. Azure Private Link provides connectivity from the virtual network. To connect from an on-premises network, including the Utimaco Key Loading Device (KLD), use a site-to-site virtual private network (VPN) or another approved hybrid connection. Individual workstations can use a point-to-site VPN or Secure Shell (SSH) port forwarding through an Azure VM.

The APM on LS2 Operational Instructions document in the Utimaco portal provides detailed installation, configuration, validation, and troubleshooting procedures. Access to the document requires an active Utimaco portal account and registration.

Important

To reach the management interface from outside the Azure virtual network, connect through an approved VPN or SSH tunnel. Provide network connectivity to the management port (7005) and application port (2200) from authorized management workstations and payment applications.

Customer actions

  1. Deploy or use an existing Azure VM within an Azure virtual network to access the Azure Payment HSM v2 environment.
  2. Connect to the HSM management interface by using the Utimaco Secure Configuration Assistant (SCA) utility, C3 Key Loading Device (KLD), and administrator or backup smart cards.
  3. Establish access to the HSM management port through an approved connectivity method, such as SSH port forwarding or VPN.
  4. Verify successful connectivity to the HSM management interface and complete initial HSM administration tasks.
  5. Connect to the HSM application interface and verify application connectivity by using existing payment applications and test transactions.

Management port and application port information

Management port: 7005 - Administrative and management operations.

  • mgmt<node-number>.<pool-name>-<unique-string>.privatelink.phsm.azure.net, where <node-number> is 1, 2, or 3

Application port: 2200 - Payment application data plane for Atalla commands and cryptographic operations.

  • app<node-number>.<pool-name>-<unique-string>.privatelink.phsm.azure.net, where <node-number> is 1, 2, or 3

Deploy an Azure virtual machine within an Azure virtual network

Use Quickstart: Create a Linux VM in the Azure portal to deploy an Azure VM that runs Ubuntu Server 22.04 LTS. During network configuration, select the client virtual network and management subnet that you created earlier.

Configure VPN or SSH port forwarding to connect to your Payment HSM v2

Connect to your Azure Payment HSM v2 management interface by using one of the following approved methods.

Site-to-site VPN connected to the Azure virtual network hosting the management endpoint:

Point-to-site VPN connected to the Azure virtual network hosting the management endpoint:

SSH local port forwarding through an Azure VM (jump box) deployed within your Azure virtual network:

ssh -L "<local-port>:<payment-hsm-management-fqdn>:<management-port>" "<username>@<jump-box-fqdn>"

For example:

ssh -L 7005:mgmt1.contosophsmv2-e9gudbaag0bdhcbu.privatelink.phsm.azure.net:7005 azureuser@jumpbox.contoso.com

Related content

  • Last updated on