Solaris SafeNet Luna HSM Client Installation
These instructions assume that you have already acquired the SafeNet Luna HSM client software, in the form of a downloaded .tar archive.
You must install the SafeNet Luna HSM client software on each client workstation you will use to access a SafeNet Luna HSM. This section describes how to install the client on a workstation running Solaris, and contains the following topics:
>Installing the Client Software
>Controlling User Access to Your Attached HSMs and Partitions
>Uninstalling the SafeNet Luna HSM Client Software
>Scripted or Unattended Installation
>Interrupting the installation - [Ctrl] [C]
Applicability to specific versions of Solaris is summarized in the Customer Release Notes for the current release.
NOTE Before installing a SafeNet 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, contact Gemalto Support.
Each computer that connects to the SafeNet Luna Network HSM appliance 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 USB HSM or a SafeNet Luna PCIe HSM must have the cryptoki library and other utilities and supporting files installed.
NOTE This example shows all the SafeNet Luna HSM client products and components. Some items are not supported on all operating systems and therefore do not appear as you proceed through the installation script.
Prerequisites
Before starting the installation, ensure that you have satisfied the following prerequisites:
Random Number Generator (RNG) or Entropy Gathering Daemon (EGD)
Ensure that you have a Random Number Generator (RNG) or Entropy Gathering Daemon (EGD) on your system in one of the following locations:
>/dev/egd-pool
> /etc/egd-pool,
> /etc/entropy
>/var/run/egd-pool
RNG/EGD
Cryptographic algorithms, including those that assure the security of communication – such as in OpenSSL and other protocols – depend upon random numbers for the creation of strong keys and certificates. A readily available source of random data is the entropy that exists in complex computer processes. Utilities exist for every operating system, to gather bits of system entropy into a pool, which can then be used by other processes.
Windows and Linux have these installed by default. Other systems might not. See your system administrator.
Entropy Pool
In the case of SafeNet Luna Network HSM, the SafeNet Luna HSM Client administration tool (vtl) expects to find a source of randomness at /dev/random. If one is not found, vtl fails, because the link cannot be secured from the Client end.
If your system does have an entropy pool, but the random number generator (RNG) is not in the expected place, then you can create a symbolic link between the actual location and one of the following:
>/dev/random
> /dev/egd-pool
> /etc/egd-pool
>/etc/entropy
>/var/run/egd-pool
If your system does not have an entropy-gathering daemon or random number generator, please direct your system administrator to install one, and point it to one of the named devices.
Installing the Client Software
It is recommended that you refer to the SafeNet Luna HSM Customer Release Notes for any installation-related issues or instructions before you begin the following software installation process.
CAUTION! You must be logged in as root when you run the installation script.
By default, the Client programs are installed in the /opt/safenet/lunaclient/bin directory.
To install the SafeNet Luna HSM client software on a Solaris workstation
1.Log on to the client system, open a console or terminal window, and use su to gain administrative permissions for the installation.
2.Access the SafeNet Luna HSM client software:
a.Copy or move the .tar archive to a suitable directory where you can untar the archive and launch the installation script.
b.Extract the contents from the archive:
tar xvf <filename>.tar
3.Go to the install directory for your architecture:
| Architecture | Path |
|---|---|
| Solaris Sparc 32-bit | LunaClient_7.X.0_SolarisXXSparc/32 |
| Solaris Sparc 64-bit | LunaClient_7.X.0_SolarisXXSparc/64 |
| Solaris x86 32-bit | LunaClient_7.X.0_SolarisXXx86/32 |
| Solaris x86 64-bit | LunaClient_7.X.0_SolarisXXx86/64 |
4.To see the help, or a list of available installer options, type:
sh install.sh -? or sh install.sh --help
To install all available products and optional components, type:
sh install.sh all
To selectively install individual products and optional components, type the command without arguments:
sh install.sh
5.Type y
if you agree to be bound by the license agreement.
6.A list of installable SafeNet products is displayed (might be different, depending on your platform). Select as many as you require, by typing the number of each (in any order) and pressing Enter. As each item is selected, the list updates, with a "*" in front of any item that has been selected. The following example shows that items 1 and 3 have been selected, and item 4 is about to be selected.
Products Choose Luna Products to be installed
*[1]: SafeNet Luna Network HSM [2]: SafeNet Luna PCIe HSM
*[3]: SafeNet Luna USB HSM
[4]: SafeNet Luna Backup HSM [N|n]: Next [Q|q]: Quit
Enter selection: 4
7.When the selection is complete, type N or n for "Next", and press Enter. If you wish to make a change, simply type a number again and press Enter to de-select a single item.
8.The next list is titled "Advanced" and includes additional items to install. Some items might be pre-selected to provide the optimum SafeNet Luna HSM experience for the majority of customers, but you can change any selection in the list. When the Components list is adjusted to your satisfaction, press Enter.
NOTE The installer includes the SafeNet SNMP Subagent as an option. If you select this option, you will need to move the SafeNet MIB files to the appropriate directory for your SNMP application after installation is complete, and you will need to start the SafeNet subagent and configure for use with your agent. See the Administration Guide for more information.
9.If the script detects an existing cryptoki library, it stops and suggests that you uninstall your previous SafeNet software before starting the SafeNet Luna HSM Client installation again.
10.The system installs all packages related to the products and any optional components that you selected.
11.Although FMs are supported on Linux and Windows clients only in this release, the FM architecture requires a configuration file setting to allow partition login on an FM-enabled HSM. If the HSM you will be using with this client is FM-enabled (see Preparing the SafeNet Luna Network HSM to Use FMs for more information), you must add the following entry to the [Misc] section of the Chrystoki.conf file:
[Misc]
LoginAllowedOnFMEnabledHSMs=1
NOTE As a general rule, do not modify the Chrystoki.conf/crystoki.ini file, unless directed to do so by Gemalto Technical 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.
Controlling User Access to Your Attached HSMs and Partitions
By default, only the root user has access to your attached HSMs and partitions. You can specify a set of non-root users that are permitted to access your attached HSMs and partitions, by adding them to the hsmusers group.
NOTE The client software installation automatically creates the hsmusers group if one does not already exist on your system. The hsmusers group is retained when you uninstall the client software, allowing you to upgrade your client software while retaining your hsmusers group configuration.
Adding users to hsmusers group
To allow non-root users or applications access your attached HSMs and partitions, assign the users to the hsmusers group. The users you assign to the hsmusers group must exist on the client workstation. Users you add to the hsmusers group are able to access your attached HSMs and partitions. Users who are not part of the hsmusers group are not able to access your attached HSMs and partitions.
To add a user to hsmusers group
1.Ensure that you have sudo privileges on the client workstation.
2.Add a user to the hsmusers group:
sudo gpasswd --add <username> hsmusers
where <username> is the name of the user you want to add to the hsmusers group.
Removing users from hsmusers group
Should you wish to rescind a user's access to your attached HSMs and partitions, you can remove them from the hsmusers group.
NOTE The user you delete will continue to have access to the HSM until you reboot the client workstation.
To remove a user from hsmusers group
1.Ensure that you have sudo privileges on the client workstation.
2.Remove a user from the hsmusers group:
sudo gpasswd -d <username> hsmusers
where <username> is the name of the user you want to remove from the hsmusers group. You must log in again to see the change.
Uninstalling the SafeNet Luna HSM Client Software
1.cd /opt/safenet/lunaclient/bin
2.sh uninstall.sh
Java (JSP or JCPROV)
During the installation, the script provides the opportunity to install SafeNet Java components. If you select Java components, the SafeNet Java files are installed below /opt/safenet/lunaclient/jsp/ for JSP and /opt/safenet/lunaclient/jcprov/ for JCPROV. In order to use Java, you must have separately installed Java (JDK or run-time environment from the vendor of your choice) onto your system.
To install JSP
1.Copy the SafeNet Java library and jar files from their default location under /opt/safenet/lunaclient/jsp/lib to the Java environment directory, for example /opt/jre/lib/ext.
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.
To install JCPROV
1.Copy the SafeNet JCPROV library and jar files from their default location under /opt/safenet/lunaclient/jcprov/lib to the Java environment directory, for example /opt/jre/lib/ext.
For additional Java-related information, see Java Interfaces in the SDK Reference Guide.
JSP Static Registration
NOTE This section applies to JSP, not to JCPROV.
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 or your own HSM-aware utility, any application would be able to use SafeNet product without being designed to log in to the HSM Partition.
Edit the java.security file located in the /jre/lib/security directory of your Java SDK/JRE 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.
Removing components
To uninstall the JSP component or the JCPROV component, you must manually remove them from the locations where they were copied.
sh uninstall.sh
Scripted or Unattended Installation
If you prefer to run the installation from a script, rather than interactively, run the command with the options -p <list of SafeNet products> and -c <list of SafeNet components>. To see the syntax, run the command with help like this:
[myhost]$ sudo sh install.sh help
[sudo] password for fred
At least one product should be specified.
usage:
install.sh - Luna Client install through menu
install.sh help - Display scriptable install options
install.sh all - Complete Luna Client install
install.sh -p [sa|pci|g5|rb] [-c sdk|jsp|jcprov|ldpc|snmp]
-p <list of Luna products>
-c <list of Luna components> - Optional. All components are installed if not provided
Luna products options
sa - SafeNet Luna Network HSM
pci - SafeNet Luna PCIe HSM
g5 - SafeNet Luna USB HSM
rb - SafeNet Luna Backup HSM
Luna components options
sdk - Luna SDK
jsp - Luna JSP (Java)
jcprov - Luna JCPROV (Java)
snmp - Luna SNMP subagent
[myhost]$
For scripted/automated installation, your script will need to capture and respond to the License Agreement prompt, and to the confirmation prompt. For example:
[myhost]$ sudo sh install.sh all
IMPORTANT: The terms and conditions of use outlined in the software
license agreement (Document #008-010005-001_053110) shipped with the product
("License") constitute a legal agreement between you and SafeNet Inc.
Please read the License contained in the packaging of this
product in its entirety before installing this product.
Do you agree to the License contained in the product packaging?
If you select 'yes' or 'y' you agree to be bound by all the terms
and conditions se out in the License.
If you select 'no' or 'n', this product will not be installed.
(y/n) y
Complete Luna Client will be installed. This includes SafeNet Luna Network HSM,
SafeNet Luna PCIe HSM, SafeNet Luna USB HSM AND SafeNet Luna Backup HSM.
Select 'yes' or 'y' to proceed with the install.
Select 'no' or 'n', to cancel this install.
Continue (y/n)? y
Interrupting the installation - [Ctrl] [C]
Do not interrupt the installation script in progress, and ensure that your host computer is served by an uninterruptible power supply (UPS). If you press [Ctrl] [C], or otherwise interrupt the installation (OS problem, power outage, other), some components will not be installed. It is not possible to resume an interrupted install process. The result of an interruption depends on where, in the process, the interruption occurred (what remained to install before the process was stopped).
As long as the cryptoki package is installed, any subsequent installation attempt results in refusal with the message "A version of Luna Client is already installed." Removing the library allows the script to clean up remaining components, so that you can install again.
What to do if installation is incomplete or damaged
1.If SNFTlibcryptoki has been installed, uninstall it manually.
2.Run the Client install script again. Now that SNFTlibcryptoki is removed, the install script removes any stray packages and files.
3.Install again, to perform a clean installation.
After Installation
When you have installed the software onto a Client, the next task is to configure the SafeNet Luna HSM, as described in the Configuration Guide.
