Windows SafeNet Luna HSM Client Installation

This section describes how to install the SafeNet Luna HSM Client software on Windows. It contains the following topics:

>Required Client Software

>Prerequisites

>Installing the Luna HSM Client Software

>Modifying the Installed Windows Luna HSM Client Software

>Java

>CSP and KSP

>Uninstalling the SafeNet Luna HSM Client Software

>After Installation

>Troubleshooting

Applicability to specific versions of Windows is summarized in the Customer Release Notes for this release.

NOTE   Before installing a SafeNet Luna HSM system, confirm that the product you have received is in factory condition and has not been tampered with in transit. Refer to the Startup Guide included with your product shipment. If you have any questions about the condition of the product that you have received, contact Technical Support immediately.

Required Client Software

Each computer that connects to a SafeNet Luna Network HSM as a Client must have the cryptoki library, the vtl client shell and other utilities and supporting files installed.

Each computer that contains, or is connected to a SafeNet Luna PCIe HSM or a SafeNet Luna USB HSM must have the cryptoki library and other utilities and supporting files installed.

Prerequisites

The Luna HSM Client installer requires the Microsoft Universal C Runtime (Universal CRT) to run properly. Universal CRT requires your Windows machine to be up to date. Before running the installer, ensure that you have the Universal C Runtime in Windows (KB2999226) update and its prerequisites installed on your machine. The following updates must be installed in order:

1.March 2014 Windows servicing stack update (See https://support.microsoft.com/en-us/help/2919442)

2.April 2014 Windows update (See https://support.microsoft.com/en-us/help/2919355)

3.Universal C Runtime update (See https://support.microsoft.com/en-us/kb/2999226)

Installing the Luna HSM Client Software

The supported Windows servers are 64-bit. They allow running of 32-bit or 64-bit applications.

For compatibility of our HSMs with Windows in general, we provide both 32-bit and 64-bit libraries and tools for use with your applications as appropriate. Hardware drivers are 64-bit only.

For compatibility of our HSMs with Windows CAPI we have SafeNet CSP, and for the newer Windows CNG we have SafeNet KSP. See CSP and KSP for more information.

Interactive (prompted, this page) and non-interactive (no prompts Scripted/Unattended Windows Installation/Uninstallation) installation options are available.

To install the Luna HSM client software:

1.Log into Windows as “Administrator”, or as a user with administrator privileges (see Troubleshooting).

2.Uninstall any previous versions of the Client software before you proceed (see Uninstalling the SafeNet Luna HSM Client Software).

NOTE   If you do not uninstall previous Luna HSM Client versions, you might face installation issues, such as failure to install the new client.

3.Download the Luna HSM Client from the Thales Support Portal at https://supportportal.gemalto.com and extract the .zip to an appropriate folder.

4.In the extracted directory, locate the folder for your Windows architecture and double click LunaHSMClient.exe.

5.The Custom Setup dialog allows you to choose which software components you wish to install. Click a product to select the components to install, or click Select All to install all available components.

The installer includes the SafeNet SNMP Subagent as an option with any of the SafeNet Luna HSMs, except SafeNet Luna Network HSM, which has agent and subagent built in. After installation of the SafeNet SNMP Subagent is complete, you will need to move the SafeNet MIB files to the appropriate directory for your SNMP application, and you will need to start the SafeNet subagent and configure for use with your agent, as described in SNMP Monitoring in the Administration Guide.

After you select the components you want to install, click Install.

a.Agree to the terms of the License Agreement to proceed with installation. To view the agreement text, click the link in the dialog. The installer loads a PDF version if a PDF reader is available; otherwise it launches a text editor and a plain-text version of the agreement.

b.If Windows presents a security notice asking if you wish to install the device driver from SafeNet, click "Always trust software from SafeNet Canada" and click Install to accept.

c.If you choose not to install the driver(s), your Luna HSM Client cannot function with any locally-connected SafeNet hardware (which includes SafeNet Luna PCIe HSM, SafeNet Luna USB HSM, or SafeNet Luna Backup HSMs).

6.When the installation completes, the button options are Uninstall, Modify, or Quit; click Quit to finish.

If you launch the installer again, you should see the final dialog, above, allowing you to modify the current Luna HSM Client installation if desired, or to uninstall.

7.[Optional] For easy use of the Luna HSM Client command-line tools, add the directory to the system PATH variable.

"C:\Program Files\SafeNet\Lunaclient"

Modifying the Installed Windows Luna HSM Client Software

If you wish to modify the installation (perhaps to add a component or product that you did not previously install), you must re-run the current installer and ensure that the desired options are selected.

NOTE   This feature has software and/or firmware dependencies. See Version Dependencies by Feature for more information.

To modify the installed Luna HSM client software

1.Run the LunaHSMClient.exe program again. Because the software is already installed on your computer, the following dialog is displayed (in this example, devices and features were previously installed, and the task is to uninstall a couple of items):

2.Select or deselect individual Devices or Features, as desired.

3.Click Modify. The client software is updated (items are added or removed).

If you are uninstalling some items, or if you are adding features, the dialog shows a progress bar briefly, and then shows the current status.

If you are adding a Luna Device, then you might be prompted with the operating system pop-up to accept/trust the driver. Do so.

4.Click Quit when the modification is complete.

NOTE   You can also use Programs and Features in the Windows Control Panel to launch the Uninstall/Modify dialog for the client software.

Java

If you want the Luna Java Security Provider (JSP) to be installed, the SafeNet Java files are installed in the C:\Program Files\LunaClient\JSP\lib folder. You install the Java JDK or run-time environment from the vendor of your choice to use the Luna JSP. Refer to the Customer Release Notes for supported Java versions.

Copy the SafeNet Java files from their default location under C:\Program Files\SafeNet\LunaClient\JSP\lib to the Java environment directory, for example C:\Program Files\Java\jdk1.8.0_92\bin.

NOTE   The exact directory might differ depending on where you obtained your Java system, the version, and any choices that you made while installing and configuring it.

Using a 32-bit JDK on a 64-bit OS

If you install a 32-bit JDK on a 64-bit OS, you must copy the 32-bit LunaAPI.dll file to the 32-bit JDK bin folder. For example, C:\Program Files (x86)\Java\jdk1.8.0_92\bin.

Java Library Path Issue

Thales has traditionally recommended that you put LunaAPI.dll in the <java_install_dir>/lib/ext folder.

Java 7/8/9 for Windows has removed that directory from the Java library path. As a result, when a Java application on Windows uses the SafeNet provider, it cannot find the LunaAPI.dll library, causing the application to fail.

To address this problem, we suggest that you use one of the following methods to add LunaAPI.dll to the Java search path:

>Put LunaAPI.dll in an arbitrary folder and add that folder to the system path. Java will search the system path for LunaAPI.dll.

>Put LunaAPI.dll in the <java_install_dir>/bin folder.

Alternatively, at the command line, specify: "%JAVA_HOME%/jre/bin/java" -Djava.library.path="C:\path\to\lunaapi.dll" -jar jMultitoken.jar

For additional Java-related information,see Java Interfaces in the SDK Reference Guide. 

JSP Static Registration

You would choose static registration of providers if you want all applications to default to the SafeNet provider.

Edit the java.security file located in the \jre\lib\security directory of your Java SDK/JRE 7/8/9 installation to read as follows:

security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.net.ssl.internal.ssl.Provider
security.provider.3=com.safenetinc.luna.provider.LunaProvider
security.provider.4=com.sun.rsajca.Provider
security.provider.5=com.sun.crypto.provider.SunJCE
security.provider.6=sun.security.jgss.SunProvider

You can set our provider in first position for efficiency if SafeNet Luna HSM operations are your primary mode. However, if your application needs to perform operations not supported by the LunaProvider (secure random generation or random publickey verification, for example) then it would receive error messages from the HSM and would need to handle those gracefully before resorting to providers further down the list. We have found that having our provider in third position works well for most applications.

The modifications in the "java.security" file are global, and they might result in the breaking of another application that uses the default KeyPairGenerator without logging into the SafeNet Luna Network HSM first. This consideration might argue for using dynamic registration, instead.

JSP Dynamic Registration

For your situation, you may prefer to employ dynamic registration of Providers, in order to avoid possible negative impacts on other applications running on the same machine. As well, the use of dynamic registration allows you to keep installation as straightforward as possible for your customers.

Compatibility

We formally test SafeNet Luna HSMs and our Java provider with Oracle JDK for all platforms except AIX, and with IBM JDK for the AIX platform. The SafeNet JCE provider is compliant with the JCE specification, and should work with any JVM that implements the Java language specification.

Occasional problems have been encountered with respect to IBM JSSE.

GNU JDK shipped with most Linux systems has historically been incomplete and not suitable.

CSP and KSP

SafeNet CSP allows you to use the SafeNet Luna HSM with Microsoft CAPI, which is supported on 32-bit and on 64-bit Windows.

SafeNet KSP allows you to use the SafeNet Luna HSM with Microsoft CNG, which is newer, has additional functions, and supersedes CAPI.

Both of these require modifications to the Windows Registry.

SafeNet CSP

For SafeNet CSP, the utility register.exe takes care of the registry.

Just remember to run the 64-bit version, the 32-bit version, or both, depending on the applications you are running.

>Register the csp dll:

# register.exe /library

>Register the partition:

# register <no arguments>

SafeNet KSP

For SafeNet KSP, the utility KspConfig.exe takes care of the registry. Follow instructions for the use of the graphical KspConfig.exe as described in KSP for CNG in the SDK Reference Guide. Just remember to run the 64-bit version, the 32-bit version, or both, depending on the applications you are running.

If SafeNet CSP (CAPI) / SafeNet KSP(CNG) is selected at installation time then the SafeNetKSP.dll file is installed in these two locations:

>C:\Windows\System32 (used for 64-bit KSP)

>C:\Windows\SysWOW64 (used for 32-bit KSP)

NOTE   The cryptoki.ini file, which specifies many configuration settings for your HSM and related software, includes a line that specifies the path to the appropriate libNT for use with your application(s). Verify that the path is correct.

USB-powered PED

The SafeNet Luna PIN Entry Device (PED) v2.8 contains new hardware that enables the PED to be USB-powered; there is no longer a requirement for an external DC power Adapter. PED v2.8 is functionally equivalent to your existing (previous-generation) PEDs and is compatible with HSM versions, 5.x, 6.x, and 7.x.

PED v2.8 ships with firmware 2.8.0. Note that you cannot upgrade existing PEDs to the 2.8.0 version; existing PEDs continue to need a separate DC power adapter for remote PED and upgrade use. The model number on the manufacturer's label identifies the refreshed PED: PED-06-0001. An installed driver is required; see step 1, below.

To use the new USB-powered PED

1.Ensure the SafeNet Luna HSM Client software is installed on the Windows computer that will act as the PED Server to your SafeNet Luna HSM. Installing the Remote PED component of the SafeNet Luna client installs the required driver.

NOTE   A USB connection, without the driver software, only illuminates the PED screen, with no menu. An installed and running PED driver, on the connected computer, is required for the PED to fully boot and to display its menu.

2.Connect the PED to the computer where you installed the Remote PED component of the SafeNet Luna client, using the USB micro connector on the PED and a USB socket on your computer.

3.After you connect the PED to the host computer, it will take 30 to 60 seconds for initial boot-up, during which time a series of messages are displayed, as listed below:

BOOT V.1.1.0-1

CORE V.3.0.0-1

Loading PED...

Entering...

4.After the boot process is complete, the PED displays Local PED mode and the Awaiting command... prompt. Your new PED is now ready for use.

5.To enter Remote PED mode, if needed, exit Local PED mode with the "< " key, and from the Select Mode menu, select option 7  Remote PED.

Uninstalling the SafeNet Luna HSM Client Software

You need to uninstall SafeNet Luna HSM Client before installing a new version. If you wish to modify the installation (perhaps to add a component or product that you did not previously install), you must uninstall the current installation and re-install with the desired options. If you have a SafeNet Luna Backup HSM connected to the client workstation, either disconnect it or stop the PEDclient service (pedclient mode stop) before you proceed.

To uninstall the Luna HSM client software:

1.Run the LunaHSMClient.exe program again. Because the software is already installed on your computer, the following dialog is displayed, showing which components are currently installed (for this example, all Devices and all Features were previously installed):

2.Click Uninstall. The client software is uninstalled.

3.When the uninstallation is complete, click OK to dismiss the operating system's confirmation dialog.

NOTE   You can also use Programs and Features in the Windows Control Panel to uninstall the client software.

Uninstall if not present

If the Luna HSM Client software has been uninstalled, and you launch the installer in uninstall mode, from the command line, the installer starts, looks for the installed software, fails to find it, and presents a Windows dialog to that effect.

If the Luna HSM Client software has been uninstalled, nothing related to the client appears in Windows Control Panel, so nothing exists to launch from that avenue.

After Installation

When you have installed the software, the next task is to configure the SafeNet Luna HSM, as described in the Configuration Guide.

Open a new command-line/console window to allow the library path to be found before you run LunaCM or other utilities that require the library.

Troubleshooting

If you are not the Administrator of the computer on which Luna HSM Client is being installed, or if the bundle of permissions in your user profile does not allow you to launch the installer with "Run as Administrator", then some services might not install properly. One option is to have the Administrator perform the installation for you.

Another approach might be possible. If you have sufficient elevated permissions, you might be able to right-click and open a Command Prompt window as Administrator.

If that option is available, then you can use the command line to move to the location of the LunaHSMClient.exe file and launch it there, which permits the needed services to load for PEDclient. See Scripted/Unattended Windows Installation/Uninstallation for instructions on how to install the client software from the command line.