Tutorial: Use SSH to access the payShield manager for your payment HSM

After you Create an Azure Payment HSM, you can create a virtual machine on the same virtual network and use it to access the Thales payShield manager.

In this tutorial, you learn how to:

• Create a subnet for your virtual machine
• Create a virtual machine
• Test Connectivity to your VM, and from the VM to your payment HSM
• Log into the VM to access the payShield manager

To complete this tutorial you need:

• The name of your payment HSM's virtual network. This tutorial assumes the name used in the previous tutorial: "myVNet".
• The address space of your virtual network. This tutorial assumes the address space used in the previous tutorial: "10.0.0.0/16".

Create a VM subnet

Azure CLI

Create a subnet for your virtual machine, on the same virtual network as your payment HSM, using the Azure CLI az network vnet subnet create command. You must provide a value to the--address-prefixes argument that falls within the VNet's address space, but differs from the payment HSM subnet addresses.

az network vnet subnet create -g "myResourceGroup" --vnet-name "myVNet" -n "myVMSubnet" --address-prefixes "10.0.1.0/24"

The Azure CLI az network vnet show command lists two subnets associated with your VNet: the subnet with your payment HSM ("mySubnet"), and the newly created "myVMSubnet" subnet.

az network vnet show -n "myVNet" -g "myResourceGroup"

Azure PowerShell

First, save the details of your VNet to a variable using the Azure PowerShell Get-AzVirtualNetwork cmdlet:

$vnet = Get-AzVirtualNetwork -Name "myVNet" -ResourceGroupName "myResourceGroup"

Next, configure a subnet for your virtual machine, on the same virtual network as your payment HSM, using the Azure PowerShell New-AzVirtualNetworkSubnetConfig command. You must provide a value to the --address-prefixes argument that falls within the VNet's address space, but differs from the payment HSM subnet addresses.

$vmSubnet = New-AzVirtualNetworkSubnetConfig -Name "myVMSubnet" -AddressPrefix "10.0.1.0/24"  

Lastly, add the subnet configuration to your VNet variable, and then pass the variable to the Azure PowerShell Set-AzVirtualNetwork cmdlet:

$vnet.Subnets.Add($vmSubnet)
                   
Set-AzVirtualNetwork -VirtualNetwork $vnet

The Azure PowerShell Get-AzVirtualNetwork cmdlet lists two subnets associated with your VNet: the subnet with your payment HSM ("mySubnet"), and the newly created "myVMSubnet" subnet.

Get-AzVirtualNetwork -Name "myVNet" -ResourceGroupName "myResourceGroup"

Portal

Create your VM subnet using either Azure CLI or Azure PowerShell. You can use the portal to Create a VM.

Create a VM

Azure CLI

Create a VM on your new subnet, using the Azure CLI az vm create command. (In this example we create a Linux VM, but you could also create a Windows VM by augmenting the instructions found at Create a Windows virtual machine with the Azure CLI with the details below.)

az vm create \
  --resource-group "myResourceGroup" \
  --name "myVM" \
  --image "UbuntuLTS" \
  --vnet-name "myVNet" \
  --subnet "myVMSubnet" \
  --admin-username "azureuser" \
  --generate-ssh-keys

Make a note of where the public SSH key is saved, and the value for "publicIpAddress".

Azure PowerShell

To create a VM on your new subnet, first set your credentials with the Get-Credential cmdlet. Provide a username of "azureuser" and a password of your choice, saving the object as $cred.

$cred = Get-Credential

Now create your VM using the Azure PowerShell New-AzVm command. (In this example we create a Linux VM, but you could also create a Windows VM by augmenting the instructions found at Create a Windows virtual machine with the Azure PowerShell with the details below.)

New-AzVm `
    -ResourceGroupName "myResourceGroup" `
    -Name "myVM" `
    -Location "eastus" `
    -Image "UbuntuLTS" `
    -PublicIpAddressName "myPubIP" `
    -VirtualNetworkName "myVNet" `
    -SubnetName "myVMSubnet" `
    -OpenPorts 22 `
    -Credential $cred `
    -GenerateSshKey `
    -SshKeyName "myVM_key"

Make a note of where the private SSH key is saved, and the value for "FullyQualifiedDomainName".

Portal

To create a VM on your new subnet:

1. Select "Virtual machines" from the "Create a Resource" screen of the Azure portal:
2. On the "Basics" tab of the creation screen, select the resource group that contains your payment HSM ("myResourceGroup"):
3. On the "Networking" tab of the creation screen, select the VNet that contains your payment HSM ("myVNet"), and the subnet you created above ("myVMSubnet"):
4. At the bottom of the networking tab, select "Review and create".
5. Review the details of your VM, and select "Create".
6. Select "Download private key and create resource", and save your VM's private key to a location where you can access it later.

Test connectivity

To access connectivity to your virtual machine, and from your VM to the management NIC IP (10.0.0.4) and host NIC IP, SSH into your VM. Connect to either the public IP address (for example, azureuser@20.127.60.92) or the fully qualified domain name (for example, azureuser@myvm-b82fbe.eastus.cloudapp.azure.com)

Note

If created your VM using Azure PowerShell, the Azure portal, or if you did not ask Azure CLI to auto-generate ssh keys when you created the VM, you will need to supply the private key to the ssh command using the "-i" flag (for example, ssh -i "path/to/sshkey" azureuser@<publicIpAddress-or-FullyQualifiedDomainName>). Note that the private key must be protected ("chmod 400 myVM_key.pem").

ssh azureuser@<publicIpAddress-or-FullyQualifiedDomainName>

If ssh hangs or refuses the connection, review your NSG rules to ensure that you are able to connect to your VM.

If the connection is successful, you should be able to ping both the management NIC IP (10.0.0.4) and the host NIC IP (10.0.0.5) from your VM:

azureuser@myVM:~$ ping 10.0.0.4
PING 10.0.0.4 (10.0.0.4) 56(84) bytes of data.
64 bytes from 10.0.0.4: icmp_seq=1 ttl=63 time=1.34 ms
64 bytes from 10.0.0.4: icmp_seq=2 ttl=63 time=1.53 ms
64 bytes from 10.0.0.4: icmp_seq=3 ttl=63 time=1.40 ms
64 bytes from 10.0.0.4: icmp_seq=4 ttl=63 time=1.26 ms
^C
--- 10.0.0.4 ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 3005ms
rtt min/avg/max/mdev = 1.263/1.382/1.531/0.098 ms

azureuser@myVM:~$ ping 10.0.0.5
PING 10.0.0.5 (10.0.0.5) 56(84) bytes of data.
64 bytes from 10.0.0.5: icmp_seq=1 ttl=63 time=1.33 ms
64 bytes from 10.0.0.5: icmp_seq=2 ttl=63 time=1.25 ms
64 bytes from 10.0.0.5: icmp_seq=3 ttl=63 time=1.15 ms
64 bytes from 10.0.0.5: icmp_seq=4 ttl=63 time=1.37 ms

Access the payShield manager

To access the payShield manager associated with your payment HSM, SSH into your VM using the -L (local) option. If you needed to use the -i option in the test connectivity, you will need it again here.

The -L option will bind your localhost to the HSM resource. Pass to the -L flag the string "44300:<MGMT-IP-of-payment-HSM>:443", where <MGMT-IP-of-HSM-resource> represents the Management IP of your payment HSM.

ssh -L 44300:<MGMT-IP-of-payment-HSM>:443 azureuser@<publicIpAddress-or-FullyQualifiedDomainName>

For example, if you used "10.0.0.0" as the address prefix for your Payment HSM subnet, the Management IP will be "10.0.0.5" and your command would be:

ssh -L 44300:10.0.0.5:443 azureuser@<publicIpAddress-or-FullyQualifiedDomainName>

Now go to a browser on your local machine and open https://localhost:44300 to access the payShield manager.

Here you can commission the device, install or generate LMKs, test the API, and so on. Follow payShield documentation, and contact Thales support if any issues related to payShield commission, setup, and API testing.

Next steps

Advance to the next article to learn how to remove a commissioned payment HSM through the payShield manager.

Remove a commissioned payment HSM

More resources:

• Read an Overview of Payment HSM
• Find out how to get started with Azure Payment HSM
• Create a payment HSM