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:
>Installing the Luna HSM Client Software
>Java
>Uninstalling or Modifying the SafeNet Luna Client Software
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) and non-interactive (no prompts) 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 or Modifying the SafeNet Luna Client Software).
3.Download the Luna HSM Client from the Thales Group 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.At the Welcome screen, click Install.
The Welcome screen is updated to show the Setup Progress, and the Luna HSM Client Setup Wizard is displayed in a new window.
6.Click Next on the Luna HSM Client Setup Wizard Welcome screen.
The End-User License Agreement dialog is displayed.
7.Click the I accept the terms in the License Agreement checkbox and click Next. Click Print if you would like to print the End-User License Agreement.
The Custom Setup dialog is displayed.
8.The Custom Setup dialog allows you to choose which software components you wish to install. Click on a product to select the components to install, as follows. You can click on the + icon for a product to show each of the individual components.
|
Install this component. If you select this option for a product, only the most commonly used components are installed. Use the + icon to show which components are included. |
|
Install all of the components for the product. |
|
Do not install this component. |
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 Next.
The Ready to Install dialog is displayed.
9.Click Install to install the selected components.
10.If Windows presents a security notice asking if you wish to install the device driver from SafeNet, click Install to accept.
NOTE If you choose not to install the driver, 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).
11.When the installation completes, click Finish.
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 7 and Java 8 Library Path Issue
Thales has traditionally recommended that you put LunaAPI.dll in the <java_install_dir>/lib/ext folder.
However, Java 7 and Java 8 for Windows have removed that directory from the Java library path. As a result, when a Java 7 or Java 8 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 7 or Java 8 search path:
>Put LunaAPI.dll in an arbitrary folder and add that folder to the system path. Java 7 or Java 8 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.
Once your client has externally logged in using salogin (see salogin in the Utilities Reference Guide) or your own HSM-aware utility, any application is able to use the SafeNet product without being designed to login to the HSM Partition.
Edit the java.security file located in the \jre\lib\security directory of your Java SDK/JRE 7 or 8 installation to read as follows:
security.provider.1=sun.security.provider.Sunsecurity.provider.2=com.sun.net.ssl.internal.ssl.Providersecurity.provider.3=com.safenetinc.luna.provider.LunaProvidersecurity.provider.4=com.sun.rsajca.Providersecurity.provider.5=com.sun.crypto.provider.SunJCEsecurity.provider.6=sun.security.jgss.SunProviderYou 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
Uninstalling or Modifying the SafeNet Luna Client Software
You need to uninstall SafeNet Luna Client before installing a new version. If you wish 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.
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:
2.Click the Uninstall button. The client software is uninstalled. Click Close when the uninstallation is complete.
NOTE You can also use Programs and Features in the Windows Control Panel to uninstall the client software.
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.
