Home >

Installation Guide > SafeNet Client Software Installation > Windows SafeNet HSM Client Installation

Windows SafeNet HSM Client Installation

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

Note:  Before installing a SafeNet HSM system, you should 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, please contact SafeNet Support immediately.

Required Client Software

Each computer that connects to the SafeNet 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 PCIe HSM or a SafeNet USB HSM must have the cryptoki library and other utilities and supporting files installed.

Windows Server Prerequisites

Before installing SafeNet Client on Windows Server 2012/2012R2, you must satisfy the following prerequisites:

Install .NET framework version 3.5: Other versions of .NET can be installed on your system simultaneously without conflict, but version 3.5 is required for SafeNet Client to launch HTL. For more information, see Windows Server 2012 SafeNet HSM Client Supplemental Configuration.

Install the Universal C Runtime and its prerequisites: The SafeNet 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 SafeNet Client 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:

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

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

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

Before Installing SafeNet Client on Windows Server 2008 R2:

See Microsoft Security Advisory 3033929 Availability of SHA-2 Code Signing Support for Windows 7 and Windows Server 2008 R2 https://technet.microsoft.com/en-us/library/security/3033929 and install the appropriate Windows update. This allows Windows 2008 R2 to recognize driver software signed with certificates based on the more secure SHA-256 mechanism. Without the update, the HSM drivers are prevented from working and any installed SafeNet HSMs are not visible as slots.  

Installing the SafeNet 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 for use with your applications as appropriate, but our supplied tools (lunacm, cmu, multitoken, etc.) are 64-bit versions only. This is because 64-bit tools are all that is needed on a 64-bit OS, but we mention it in case you were looking for 32-bit equivalents - there aren't any because none are needed.

For compatibility of our HSMs with Windows CAPI we have SafeNet CSP, and for the newer Windows CNG we have SafeNet KSP. If you are using either, then a section near the end of this chapter has additional specific instructions.

Interactive (prompted) and non-interactive (no prompts) installation options are available.

To install the SafeNet HSM client software

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

2.Insert the SafeNet Client Software DVD into your optical drive.

3.Click Start > Run and then type:

d:\windows\64\LunaClient.exe

where “d” is your CDROM drive

or  use Explorer to navigate the CD directories and double click the appropriate LunaClient.exe.

Note:  The installer is 64-bit only. If you have 32-bit applications, proceed with the 64-bit installation, then see Using 32-bit Applications With the SafeNet Client.

4.At the Welcome screen, click Next.

5.Accept the software license agreement.

6.In the Choose Destination Location dialog, accept the default that is offered, or make a change if you prefer.

7.Click to select any of the SafeNet Product software options that you wish to install. Any that are marked with a red "X" are currently de-selected and will not be installed when you proceed. You must accept at least the major feature for your HSM. You can select all, if you wish - there is no conflict.

The installer includes the SafeNet SNMP Subagent as an option with any of the SafeNet HSMs, except SafeNet Network HSM (which has agent and subagent built in). For any of SafeNet PCIe HSM, SafeNet USB HSM, or SafeNet Backup HSMs, include the subagent with any of the products, if desired - it doesn't matter which; it's the same subagent, and it goes to the same location on your hard disk.

After installation 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 the Administration Guide.


8.On the Ready to Install page click Install.

If you wish to modify any of your previous selections, you can still click Back to see previous pages. Once you click Install, you are committed to the installation.


9.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 SafeNet Client cannot function with any locally connected SafeNet hardware (which includes SafeNet PCIe HSM, SafeNet USB HSM, or SafeNet Remote Backup HSMs).

10.When the installation completes, click Finish.




11.Ensure that every copy of PuTTY that you have on any Windows host, that connects via SSH to the SafeNet Network HSM, is replaced by the version of PuTTY that accompanies the new client software.

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.

As a general rule, do not modify the Chrystoki.conf/crystoki.ini file, unless directed to do so by SafeNet Customer Support. If you do modify the file, never insert TAB characters - use individual space characters. Avoid modifying the PED timeout settings. These are now hardcoded in the appliance, but the numbers in the Chrystoki.conf file must match.

12.After the client software installation finishes, reboot the client computer.  

Scripted or unattended installation of the SafeNet Client

If desired, you can script the installation. Each Linux or UNIX version has its own method for unattended installations. Windows allows you to add flags following the LunaClient.exe command.

For more detailed information, see Scripted / Unattended Installation on Windows.

Java 

During the installation, if you allow our Java Security Provider to be installed, the SafeNet Java files are installed below C:\Program Files\Luna Client\JSP\lib. In order to use our JSP, you must have separately installed Java (JDK or run-time environment from the vendor of your choice) onto your system.

Copy the SafeNet Java files from their default location under C:\Program Files\SafeNet\Luna Client\JSP\lib to the Java environment directory, for example C:\Program Files\Java\jre6\lib\ext.

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 LunaAPI.dll file to C:\Windows\SysWOW64 (instead of C:\Windows\System32)

Java 7 and Java 8 Library Path Issue

SafeNet 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.    

OR

Put LunaAPI.dll in the Windows system folder: C:\Windows\System32
Use that destination for both 32-bit and 64-bit  

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 our (SafeNet) provider.

Once your client has externally logged in using salogin (see ) in the Reference section of this document) or your own HSM-aware utility, any application would be able to use 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.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 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 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 HSMs and our Java provider with SUN JDK for all platforms except AIX, and with IBM JDK for the AIX platform. We have not had problems with OpenJDK, although it has not been part of our formal test suite. 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 HSM with Microsoft CAPI, which is supported on 32-bit and on 64-bit Windows.

SafeNet KSP allows you to use the SafeNet 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.

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

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

Using 32-bit Applications With the SafeNet Client

Beginning with version 5.2, SafeNet discontinued SafeNet Client support for Windows 32-bit operating systems. We continue to supply 32-bit libraries that can be used on 64-bit Windows OS to support your older 32-bit client applications.

SafeNet Client 32-bit libraries (cryptoki.dll, cklog.dll, etc.) and versions of CSP and KSP libraries and tools are installed in the C:\Program Files\SafeNet\Luna Client\win32 directory.

The win32 directory content is as follows:

cklog201.dll

cklog201.dll.sig

cryptoki.dll

cryptoki.dll.sig

shim.dll

shim.dll.sig

jsp directory which contains:

LunaAPI.dll

If the SafeNet CSP (CAPI) / SafeNet KSP(CNG) feature is installed, the following are also installed under win32:

csp directory which contains:

keymap

LunaCSP.dll

LunaCSP.sig

ms2Luna

register

KSP directory that contains:

kspcmd

KspConfig

ksputil

ms2Luna

In order to properly use the 32-bit library and tools on 64-bit systems there are two basic approaches:   

Direct loading of library   

Set your application to load the 32-bit library installed under the win32 directory, and run your application. For an example on how to load the cryptoki library dynamically, please refer to the SafeNet SDK.

This should work for any application that directly points to the needed library, and represents the majority of customer applications.

Loading the library via the configuration file    

If you require your 32-bit Windows application to run on 64-bit Windows and your application uses the crystoki.ini to find the location of the cryptoki library (such as applications that use ckbridge - no longer distributed - or that use CSP), we recommend creating a new copy of the crystoki.ini file under the win32 directory to point to the 32-bit cryptoki library as described below:

Install SafeNet Client and configure the HSM or SA client as you would normally do.   

Create a copy of the crystoki.ini file and store it in the win32 directory.   

Modify the LibNT entry in the file (the copy in the win32 directory) to point to the cryptoki.dll library located in the win32 directory
LibNT=C:\Program Files\SafeNet\Luna Client\win32\cryptoki.dll   

Open a new DOS prompt (to be used to run your application).   

Set the ChrystokiConfigurationPath environment variable to point to the win32 directory set
ChrystokiConfigurationPath= C:\Program Files\SafeNet\Luna Client\win32\   

Run your application.

It is very possible to run 64-bit SafeNet tools (such as lunacm, ckdemo, cmu, vtl) in a Command Prompt window, while simultaneously running your 32-bit application in another Command Prompt window (using the 32-bit library by virtue of the ChrystokiConfigurationPath environment variable and the crystoki.ini file described above), and the two do not conflict, because the environments are independent. Where a problem might arise, however is if your use of the SafeNet tools were to make alterations to the original crystoki.ini file; we will call it the primary. Your application would be looking to the version of the crystoki.ini file in C:\Program Files\SafeNet\Luna Client\win32\ which would not contain the changes resulting from the SafeNet tools; we will call that one the secondary. To correct this, you must reproduce any changes from the primary crystoki.ini to the secondary, before relaunching your 32-bit application.

If a tool causes a change to the configuration file, it will be to the version of the file that exists in the directory where the 64-bit SafeNet tools are located. In order for the change to take effect for your 32-bit application(s), you must update the copy of the configuration file in the location pointed to by the ChrystokiConfigurationPath environment variable, with the new or revised entries.

Examples

When setting up or modifying a network trust link (NTL) connection with a SafeNet Network HSM partition, the vtl createcert, vtl addServer, vtl deleteServer, vtl replaceServer commands modify the Crystoki.ini file and make changes to ...certs/server/CAFile.pem. These occur in the folders associated with the 64-bit tools, and must all be replicated to the equivalent .ini file and folders for your 32-bit applications.

If you make any changes using vtl, check the file dates on crystoki.ini and the contents of the certs folders at the main SafeNet HSM Client install location. If any of them have changed compared to the equivalent files at your 32-bit location, make a backup of your 32-bit SafeNet files, and then replace the superseded files in your 32-bit folders with the newer versions from the 64-bit folders.

Running the stc enable or stc disable commands in lunacm will change the crystoki.ini file. Update the copy that you keep in your 32-bit location to match.

Uninstalling, Modifying, or Repairing the SafeNet Client Software

At any time, you might need to uninstall SafeNet Client, or to modify the installation (perhaps to add a component or product that you did not previously install), or to repair the installed software.

To uninstall, modify, or repair the SafeNet HSM client software

1.Run the LunaClient.exe program again. Because the software is already installed on your computer, after you click through the Welcome page, this dialog is displayed:

2.Choose the desired option, click Next, and follow the prompts. It is possible that you might see a message like this:

Ignore that message if you see it while uninstalling SafeNet Client. You do not need to restart your computer, and you will not be prompted to do so.

After Installation

When you have installed the software onto a Client, the next task is to configure the SafeNet 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 SafeNet 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 LunaClient.msi file and launch it there, which permits the needed services to load for HTL, PedClient, and other SafeNet features.

Administrator privileges

In Windows 7 or Windows 10, use the command net user administrator /active:yes to activate the native Administrator account. If Administrator remains disabled, you might need the intervention of your IT department or network admin.