Create a Network Trust Link - Multi-step setup
To create a Network Trust Link (NTL), the Client and HSM appliance must first exchange certificates. Once the certificates have been exchanged, the Client registers the SafeNet Luna Network HSM’s certificate in a trust list, and the SafeNet Luna Network HSM appliance, in turn, registers the Client’s certificate in its list of clients. When the certificates have been exchanged and registered at each end, the NTL is ready to use.
"Ready to use" means that an application at the client host (such as LunaCM or your crypto-using application) can see the registered SafeNet Luna Network HSM application partitions as slots in the client slot list, can select such registered partitions by slot number, and can then perform cryptographic operations in those slots after providing appropriate partition authentication (Crypto Officer, Crypto User).
NOTE Administration commands can take a few seconds to be noted by NTLS. If you have added or deleted a client, wait a few seconds before connecting.
NOTE Secure Trusted Channel (STC) offers enhanced HSM-client message integrity, and an additional layer of protection for client-to-HSM communications, even over unsecured networks. To take advantage of this feature, see Creating a Client-Partition STC Connection. For more on the differences between NTLS and STC connections, see Comparing NTLS and STC.
To create a network trust link:
You must have administrator access to perform this procedure. Read/write access to the SafeNet Luna HSM Client installation directory is required for the certificate exchange.
1.Prepare the client workstation:
a.Install the SafeNet Luna HSM Client software. See SafeNet Luna HSM Client Software Installation in the Installation Guide for details.
b.Install an SSH client to provide secure shell access to the SafeNet appliance for certificate exchange and registration. The PuTTY SSH client (putty.exe) is included in the SafeNet Luna HSM Client for Windows.
c.Ensure that the client workstation has network access to the SafeNet Luna Network HSM appliance. The appliance auto-negotiates network bandwidth up to Gigabit Ethernet speeds. See Recommended Network Characteristics for more information.
2.Open a SafeNet Luna HSM Client session:
a.Open a command prompt or terminal window.
b.Go to the SafeNet Luna HSM Client installation directory:
| Windows | C:\Program Files\SafeNet\LunaClient |
| Linux/AIX | /usr/safenet/lunaclient/bin |
| Solaris | /opt/safenet/lunaclient/bin |
3.Use pscp (Windows) or scp (Linux/UNIX) to import the HSM Appliance Server Certificate (server.pem) from the SafeNet Luna Network HSM appliance to the SafeNet Luna HSM Client workstation. See SCP and PSCP for details. You require the SafeNet Luna Network HSM appliance admin password to complete this step.
If you are importing multiple SafeNet Luna Network HSM appliances' certificates to a client, we suggest that you import the certificates and process each one as it arrives. The vtl addServer command (just ahead) copies, moves and renames the current server.pem certificate to reflect the originating appliance's hostname or IP address, as appropriate, and you are always assured that the certificates that are registered in the .\cert\server folder are unique. In this method, each appliance server cert arrives in the SafeNet Luna HSM Client folder as (the default) "server.pem" and is safely registered uniquely (in the server cert folder) before the next server.pem arrives and overwrites any earlier version.
If you prefer to import server.pem certificates from multiple appliances, before registering them, then you must rename them as they arrive, to avoid overwriting and losing certificates that all arrive in the same folder with the same default filename.
NOTE When using scp or pscp over an IPv6 network, enclose addresses in square brackets.
| Windows |
Syntax: pscp [options] <user>@<host>:<source_filename> <target_filename> Example:To copy the server certificate from host myHSM to the current (.) directory, keeping the same name: pscp admin@myHSM:server.pem . server.pem | 1 kB | 1.1 kB/s | ETA: 00:00:00 | 100% |
| Linux/UNIX |
Syntax:scp [options] <user>@<host>:<source_filename> <target_filename> Example: To copy the server certificate from host IP 192.168.0.123 to the current (.) directory, keeping the same name: scp admin@192.168.0.123:server.pem .
|
You must accept the SSH certificate the first time you open an scp or SSH link. You can use the LunaSH command sysconf fingerprint ssh to check the certificate fingerprint.
If the HSM appliance IP or hostname is changed, SSH will detect a mismatch in the HSM appliance's server certification information and warn you of a potential security breach. To resolve this issue, delete the server's certificate information from the client’s known host file at: /<user home dir>/.ssh/known_hosts2, and re-import the server certificate.
NOTE On Windows, if the certificate fails to copy (but no error message appears), ensure the client machine is running with Administrator privileges. Alternatively, open the cmd prompt by right-clicking and selecting "Run as Administrator".
4.Register the HSM Server Certificate with the client, using the vtl addserver command. See vtl in the Utilities Reference Guide for full command syntax. The vtl command is not interactive. It is called from the command line or a shell prompt, completes its current task, and exits back to the shell:
>vtl addServer -n <Network_HSM_hostname_or_IP> -c <server_certificate>
If using a host name, ensure that the name you use is reachable over the network (ping <hostname>). To avoid network issues, it is recommended that you specify an IP address.
5.Create a certificate and private key for the client, using the vtl createcert command. See vtl in the Utilities Reference Guide for full command syntax:
>vtl createcert -n <SafeNet_HSM_client_hostname_or_IP>
NOTE The client hostname or IP address must be an exact match for the client hostname, as reported using the hostname command.
The certificate and private key are saved to the <client_install_dir>/cert/client directory and are named <client_hostname_or_IP>.pem and <client_hostname_or_IP>Key.pem, respectively. The vtl createcert command displays the full path-name to the key and certificate files that were generated.
6.Export the client certificate to the HSM appliance, using pscp (Windows) or scp (Linux/UNIX). You require the SafeNet Luna Network HSM appliance admin password to complete this step. You must scp to the admin account on the HSM appliance, or the client certificate will not register correctly. The file arriving at the HSM is automatically placed in the appropriate directory. Do not specify a target directory.
| Windows |
Syntax: pscp [options] <source_filename> <user>@<host>:[<target_filename>] Example:To copy the client certificate (myLunaClient.pem) to the myLunaSA appliance, keeping the same name: pscp "Program FileSafeNet\LunaClient\cert\client\myLunaClient.pem" admin@myLunaSA: |
| Linux/UNIX |
Syntax:scp [options] <source_filename> <user>@<host>:[<target_filename>] Example: To copy the client certificate (myLunaClient.pem) to the SafeNet Luna Network HSM appliance with IP 192.168.0.123, keeping the same name: scp <path>/myLunaClient.pem admin@192.168.0.123: |
7.Register the client certificate with the HSM appliance using the LunaSH client register command. You need an admin or operator-level account on the SafeNet Luna Network HSM appliance to complete this step.
a.Use an SSH client to connect to the SafeNet Luna Network HSM appliance and login using an admin or operator-level account.
b.Use the LunaSH client register command to register the client. See client register in the LunaSH Reference Guide for details.
| By hostname |
client register -client <client_name>
-hostname <client_hostname> Use this syntax if the client certificate was created using the client's hostname. You will then need to run client hostip command to map the hostname to an IP address. See Creating a Network Trust Link Between a Client and a Partition step 4 under sub-section "Assigning a Client to a Partition".) |
| By IP address |
client register -client <client_name>
-ip <client_IP_address> Use this syntax if the client certificate was created using the client's IP address as the certificate name. |
The <client_name> can be any string that allows you to easily identify this client. Many people use the hostname, but the <client_name> can be any string that you find convenient. This becomes especially useful if you are not using DNS - in that case, a well-considered <client_name> is likely going to be easier to remember or recognize than the client's IP address.
8.Restart the Network Trust Link service. After registering a client, with a hostname certificate, or after registering a client with an IP certificate and then mapping the client hostname to its IP, stop and start the NTL service, to ensure that the new client is included.
lunash:>service restart ntls
You can use the LunaSH client list command to verify the client registration.
De-registering and Re-registering Clients
If you have multiple HSM appliances connected and registered with a client and you de-register that client from one of the HSM appliances, then you must also de-register that HSM appliance on the client side. Failure to do so will result in a “Broken pipe” error, which indicates an incomplete registration.
If you wish to de-register a client and then re-register with a new certificate, on the same HSM appliance, then you must copy the certificate to the HSM appliance (HSM server) and stop and re-start the service called NTLS (see service list and service restart). Before such a restart, any connection attempts fail, and “Error on SSL accept” is logged.
