[Step 7] Create a Network Trust Link Between the Client and the Appliance

The first step in preparing your clients to use the cryptographic resources provided by the HSM appliance is to create a secure network trust link (NTL) between the client and the appliance. After you create the NTL link between the client and the appliance, you can configure links to individual partitions on the appliance using NTL or Secure Trusted Channel (STC), as described in [Step 8] Enable the Client to Access a Partition.

About Network Trust Links

Network Trust Links (NTL) are secure, authenticated network connections between the SafeNet Network HSM and Clients. NTLs use two-way digital certificate authentication and TLS data encryption (version 1.2 is supported in SafeNet Network HSM 6.1) to protect sensitive data as it is transmitted between HSM Partitions on the SafeNet Network HSM and Clients. NTLs consist of the following parts:

•the Network Trust Link Service (NTLS). The NTL server daemon runs on the SafeNet Network HSM appliance and manages the NTL connections to the appliance. NTL uses port 1792 on the SafeNet Network HSM appliance.

•the Network Trust Link Agent (NTLA). The NTL agent runs on a SafeNet HSM client workstation and manages the NTL connections to the workstation. The NTL agent is included in the SafeNet HSM client software.

•The Network Trust Link itself, an encrypted, secure communications channel between the Client’s NTLA and the HSM appliance's NTLS.

Network Trust Links use digital certificates to verify the identities of connecting clients. During the initial HSM appliance configuration (see Generate a New HSM Server Certificate), the appliance administrator generated a unique certificate that identifies the HSM appliance. Similarly, each Client must generate its own certificate that identifies it uniquely. Both the Client and the HSM appliance use these certificates to verify the other’s identity before an NTL is created between them.

The Host Trust Link (HTL) Option for VM Clients

Clients running on virtual machines (VMs) are subject to an attack in which a clone of the VM instance is used to gain access to the HSM. To remove this risk, and ensure the integrity of the client, you can optionally specify that you want the network trust link to require host trust link (HTL) client authentication. HTL uses a client-specific, one-time-token on the client that is synchronized with the HSM server to ensure the integrity of the client, and prevent an unsynchronized cloned VM image from connecting to the HSM. See Host Trust Link Client Authentication in the Administration Guide for more information.

Although designed for VM clients, you can use HTL to secure the client on any NTL link.

CAUTION:  To avoid a VM clone attack, do not register a VM client without invoking the HTL option.

Invoking HTL

To invoke the HTL option when creating an NTL, you do the following:

1.Specify the -htl option when using the vtl addserver command to register the SafeNet Network HSM appliance with the SafeNet HSM client workstation.

2.Specify the -requirehtl option when using the LunaSH client register command to register the SafeNet HSM client workstation with the SafeNet Network HSM appliance.

3.Generate a one-time token for the SafeNet HSM client workstation using the LunaSH htl generateott command

4.Use scp/pscp to export the one-time-token to the SafeNet HSM client workstation

5.Rename the one-time-token with the hostname/IP of the SafeNet Network HSM appliance and place it in the <luna_client_root>/htl directory. The HTL link is established automatically during the next HTL polling interval.

These steps are included as options in the procedure To create a network trust link.

Creating a Network Trust Link

To create an NTL, the Client and HSM appliance must first exchange certificates. Once the certificates have been exchanged, the Client registers the SafeNet Network HSM’s certificate in a trust list, and the SafeNet 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 Network HSM application partition(s) as slot(s) 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 the NTLS. If you have added or deleted a client, wait a few seconds before connecting.

To create a network trust link

Note:  You must have administrator (or root) access to perform this procedure. Read/write access to the SafeNet HSM client installation directory is required for the certificate exchange.

Note:  Use of older PuTTY versions, and related tools, can result in the appliance refusing to accept a connection. This can happen if a security update imposes restrictions on connections with older versions. To ensure compatibility, always use the versions of executable files included with the current client installer.

1.Prepare the client workstation:

a.Install the SafeNet HSM client software. See SafeNet 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 HSM client for Windows. You should always use the executable provided with the client.

c.Ensure that the client workstation has network access to the SafeNet 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 HSM client session:

a.Open a command prompt or terminal window.

b.Go to the SafeNet HSM client installation directory:

3.Use pscp (Windows) or scp (Linux/UNIX) to import the HSM Appliance Server Certificate (server.pem) from the SafeNet Network HSM appliance to the SafeNet HSM client workstation. See SCP and PSCP for details. You require the SafeNet Network HSM appliance admin password to complete this step:

If you are importing multiple SafeNet Network HSM appliance's 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 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.

pscp admin@myHSM:server.pem . 
admin@myHSM's password:  

server.pem     | 1 kB |   1.1 kB/s | ETA: 00:00:00 | 100%

scp admin@192.168.0.123:server.pem . 
admin@192.168.0.123's password:   
server.pem      | 1 kB |   1.1 kB/s | ETA: 00:00:00 | 100%

Note:  When using scp or pscp over an IPv6 network, enclose addresses in square brackets.

Note:   You must accept the SSH certificate the first time you open an scp or ssh link. You can use lunash:> sysconf fingerprint -ssh to check the certificate fingerprint.

Note:   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.

4.Register the HSM Server Certificate with the client, using the vtl addserver command. Use the -htl option if the client is running in a VM, or if you want to the add extra client identity verification offered by HTL to the link (see The Host Trust Link (HTL) Option for VM Clients).

See VTL in the Utilities Reference Guide for full command syntax:

Note:  If you specify the -htl option, you must also specify the -requirehtl option when you register the client with the server, in a subsequent step. If you do not, the server will reject requests to create the link, since it expects an HTL connection to be present.

Note:  The vtl command is not interactive. It is called from the command line or a shell prompt, it completes its current task, and it exits back to the shell.

Examples:

The following command copies the server.pem file that was downloaded in the previous step, from <luna_install_dir> to <luna_install_dir>/cert/server, and registers the myLunaSA server certificate (<luna_install_dir>/cert/server/server.pem), with the client:

bash-2.05# ./vtl addServer -n myLunaSA -c server.pem

New server myLunaSA successfully added to the server list.

The following command copies the server.pem file that was downloaded in the previous step, from <luna_install_dir> to <luna_install_dir>/cert/server, and registers the server certificate for the SafeNet Network HSM appliance at IP address 192.168.0.123 (<luna_install_dir>/cert/server/server.pem), with the client and specifies that the link requires HTL client integrity verification:

bash-2.05# ./vtl addServer -n 192.168.0.123 -c server.pem -htl

New server 192.168.0.123 successfully added to the server list.

As shown, the server certificate from any SafeNet appliance arrives as the default named file server.pem. The vtl addserver command places a copy of the imported server.pem file in the ./cert/server folder, (re-)naming the new file with the hostname (or IP) that you supply with -n in the command. In one example, above, the new copy would be 192.168.0.123Cert.pem. In the other example, the new cert file would be myLunaSACert.pem. Additionally, the command updates the CAFile.pem at that location, adding the new, named SafeNet Network HSM server certificate to the list of certs that the client recognizes.

At a minimum you would have one named server certificate file along with the CAFile.pem containing a single entry, which must match the certificate. You could have as many unique certificates in that folder as you have SafeNet appliances, and the CAFile.pem would contain a matching entry for each cert. Server certificates that do not have an entry in the CAFile.pem are ignored. Entries in the CAFile.pem that do not correspond to a unique <servername>Cert.pem file are ignored.

The downloaded server.pem file, from the earlier step, is now redundant and can be deleted, or it will be replaced the next time you download a server certificate from a SafeNet appliance.

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 <Luna_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. If you create a certificate using a hostname parameter that is not an exact letter-case match for the client’s hostname, you will be unable to create an NTLS link.

If you are using an IPv6 address as the common name (the -n parameter), when creating a client-side certificate, keep note of the IPv6 address format that you used. In later steps, when certificates are registered with a network appliance, IPv6 compressed format addresses are not expanded, and expanded format addresses are not compressed. You must use the same IPv6 address format when creating your client certificate and when registering your client to avoid mismatch and failed registration.

For example, 2018:0001:0000:0000:0000:29ff:fe2e:b07f and 2018:1:0:0:0:29ff:fe2e:b07f and 2018:1::29ff:fe2e:b07f are equivalent addresses, but are not interchangeable when certificates are registered.

The certificate and private key are saved to the <luna_install_dir>/cert/client directory and are named <Luna_client_hostname_or_IP>.pem and <Luna_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.

Example: The following command creates a certificate and private key for the client named myLunaClient:

bash-2.05# ./vtl createCert -n myClient1

Private Key created and written to: /usr/safenet/lunaclient/bin/cert/client/myClientKey.pem

Certificate created and written to: /usr/safenet/lunaclient/bin/cert/client/myClient.pem

6.Export the client certificate to the HSM appliance, using pscp (Windows) or scp (Linux/UNIX). You require the SafeNet Network HSM appliance admin password to complete this step:

Note:  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.

pscp myLunaClient.pem admin@myLunaSA: 
admin@myLunaSA's password: ********  
myLunaClient.pem   | 1 kB |   1.1 kB/s | ETA: 00:00:00 | 100%

scp myLunaClient.pem admin@192.168.0.123: 
admin@192.168.0.123's password: ********  
myLunaClient.pem   | 1 kB |   1.1 kB/s | ETA: 00:00:00 | 100%

7.Register the client certificate with the HSM appliance using the LunaSH client register command. Use the -requirehtl, -ottexpiry, and -generateott options if the client is running in a VM, or if you want to add the extra client identity verification offered by HTL to the link (see The Host Trust Link (HTL) Option for VM Clients). You need an admin or operator-level account on the SafeNet Network HSM appliance to complete this step.

Note:  You must specify the -requirehtl option if you used the -htl option when you registered the server with the client. If you do not, the server will reject requests to create the link, since it expects an HTL connection to be present.

a.Use an SSH client to connect to the SafeNet 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.

Note:  The <client_name>, above 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 might sound a little redundant (naming the client twice in one command), but it 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.

Note:  If you are registering with HTL, you can omit the -ottexpiry parameter to use the default expiry; the default, and other options, are configurable. You can also use the htl commands to generate the one-time-token at a later time and configure the HTL options (see htl in the LunaSH Reference Guide for details). The one-time token is generated in the current directory with filename <client_hostname_or IP>.ott.

Examples:

The following command registers the client at IP address 123.65.98.7 and assigns it a <client_name> of Standard_Client:

lunash:> client register -client Standard_Client -ip 123.65.98.7

‘client register’ successful.

Command Result : 0 (Success)

The following command registers the client at IP address 74.123.33.2, assigns it a <client_name> of VM_Client, specifies that it requires HTL with the default expiry, and generates a one-time token for the client:

lunash:> client register -client VM_Client -ip 74.123.33.2 -requirehtl -generateott

‘client register’ successful.

One-time token for client VM_Client is ready to use.

Command Result : 0 (Success)

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

Note:  TCPKeepAliveTCPKeepAlive is a TCP stack option, available at the LunaClient, and at the SafeNet Network HSM appliance. For SafeNet purposes, it is controlled via an entry in the Chrystoki.conf /crystoki.ini file on the LunaClient, and in an equivalent file on SafeNet Network HSM. For SafeNet HSM 6.1 and newer, a fresh client software installation includes an entry "TCPKeepAlive=1" in the "LunaSA Client" section of the configuration file Chrystoki.conf (Linux/UNIX) or crystoki.ini (Windows). Config files and certificates are normally preserved through an uninstall, unless you explicitly delete them. As such, if you update (install) LunaClient software where you previously had an older LunaClient that did not have a TCPKeepAlive entry, one is added and set to "1" (enabled), by default. In the case of update, if TCPKeepAlive is already defined in the configuration file, then your existing setting (enabled or disabled) is preserved.
On the SafeNet Network HSM appliance, where you do not have direct access to the file system, the TCPKeepAlive= setting is controlled by the lunash:> ntls TCPKeepAlive set command.
The settings at the appliance and the client are independent. This allows a level of assurance, in case (for example) a firewall setting blocks in one direction.  

9.If you are not using the HTL option, this procedure is complete. You can use the LunaSH client list command to verify the client registration.
Go to [Step 8] Enable the Client to Access a Partition.

If you are using the HTL option, complete the remaining steps to import the HTL one-time token, rename it to use the SafeNet Network HSM appliance name rather than the SafeNet HSM client workstation name, and activate HTL on the link by placing the token in the <Luna_install_dir>/htl directory.

10.Use pscp (Windows) or scp (Linux/UNIX) to import the one-time-token (<SA_appliance_hostname_or_IP>.ott) from the SafeNet Network HSM appliance to the SafeNet HSM client workstation. See "Using the scp and pscp Utilities" on page 1 for details. You require the SafeNet Network HSM appliance admin password to complete this step:

11.Rename the HTL one-time token with the IP address or hostname, as relevant, of your SafeNet Network HSM appliance, and move it to the <Luna_client_install_dir>/htl directory to activate HTL on the link:

Example:

bash-2.05# cd /usr/safenet/lunaclient/bin

bash-2.05# mv myLunaClient.ott ./htl/myLunaSA.ott

bash-2.05# cd htl

bash-2.05# ls

myLunaSA.ott

12.This part of the procedure is complete. After the token has been moved to its correct location and renamed to reflect the SafeNet Network HSM hostname or IP, it will be used during the next HTL polling interval. This happens automatically.

You can use the LunaSH client list command to verify the client registration, and the LunaSH htl show command to confirm the status of the Host Trust Link. The HTL Status changes to "Up" and the OTT Status changes to "In use" after the client has successfully established a Host Trust Link.

Example:

lunash:>client list

registered client 1:  74.123.33.2

Command Result : 0 (Success)

lunash:>htl show

HTL Grace period   :  60 seconds

Default OTT expiry :  300 seconds

Client Name         HTL Status     OTT Status     OTT Expiry Time

-----------------------------------------------------------------

MyClient            Up             In Use         300 (default)

Command Result : 0 (Success)

De-registereing 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.

SafeNet Network HSM 6.3 Product Documentation
007-011136-015 Rev. A 14 July 2017 Copyright 2001-2017 Gemalto All rights reserved.