Linux Luna HSM Client Installation

Installing the Luna HSM Client

You must install the Luna HSM Client software on each client workstation you will use to access a Luna HSM. This section describes how to install the client on a workstation running Linux, and contains the following topics:

>Prerequisites

>Where to install, and SELinux

>Installing the Client Software

>Installing the Minimal Client Software

>Controlling User Access to Your Attached HSMs and Partitions

>Uninstalling the Client Software or Removing Components

>Java

>Scripted or Unattended Installation

>Interrupting the Installation

>Modifying the Number of Luna Backup HSM Slots

Refer to the Customer Release Notes for a complete list of the supported Linux operating systems. These instructions assume that you have already acquired the Luna HSM Client software.

Prerequisites

Before starting the installation, ensure that you have satisfied the following prerequisites:

Components Required to Build the PCIe Driver and the Backup HSM Driver

On Linux, the PCIe driver module (and optionally the Backup HSM driver) is built by the client as part of the installation if you choose to install the Luna PCIe HSM component or the Backup HSM. To build the driver, the client requires the following items:

>Kernel headers for build

>kernel-devel package

>rpmbuild package

>C and C++ compilers

>make command

If any one of these items is missing, the driver build will fail and the client software will not be installed.

Debian Requires alien

The Luna HSM Client software is provided as RPM packages. If you are installing on a Debian system, you must have alien installed to allow the Luna HSM Client installation script to convert the RPM packages to DEB packages. The installation script will stop with a message if you attempt to install on a Debian system without alien installed. This applies to any other supported Debian-based Linux distribution, such as Ubuntu.

SUSE Linux on IBM PPC

JCE un-restriction files must be downloaded from IBM, not from SUN, for this platform. Attempting to use SUN JCE un-restriction files on IBM PowerPC systems with SUSE Linux causes signing errors.

Where to install, and SELinux

The instructions on this page assume that much of the installation goes into /usr. If you retain that default location, installation "should just work" uneventfully.

You can change that install location (see Flexible Install paths). There might be some interaction with SELinux that you would need to consider.

Security Enhanced Linux or SELinux is a security mechanism built into the Linux kernel used by RHEL-based distributions.

By default, in CentOS8 and newer, SELinux is enabled and in enforcing mode.

SELinux adds an additional layer of security to the system by allowing administrators and users to control access to objects based on policy rules.

SELinux policy rules specify how processes and users interact with each other as well as how processes and users interact with files. When there is no rule explicitly allowing access to an object, such as for a process opening a file, access is denied.

SELinux has three modes of operation:

•Enforcing: SELinux allows access based on SELinux policy rules.

•Permissive: SELinux only logs actions that would have been denied if running in enforcing mode. This mode is useful for debugging and creating new policy rules.

•Disabled: No SELinux policy is loaded, and no messages are logged.

So if, for example, your non- /usr installation completes uneventfully, but pedclient errors show up in the logs, then consider setting SELinux to "Permissive" mode. Or set explicit rules that will make SELinux happy when it is in Enforcing mode.

Installing the Client Software

It is recommended that you refer to the Luna HSM Customer Release Notes for any installation-related issues or instructions before installing the client software.

CAUTION!   You must install the client software using root-level privileges. For security reasons, we recommend that you do not log in as root (or use su root) to run the installation script, but instead use the sudo command to run the installation script, as detailed below.

The installation script

The installation script is install.sh and is usually launched with sh install.sh followed by any options or parameters.

>interactive: sh install.sh [-install_directory <prefix>]

>all: sh install.sh all [-install_directory <prefix>]

>scriptable: sh install.sh -p [network|pci|usb|backup|ped] [-c sdk|jsp|jcprov|snmp]|fmsdk|fm_tools [-install_directory </usr>]  

The options on the script are:

>device(s)

•"network" is the Luna Network HSM (software only, no drivers)

•"pci" is the Luna PCIe HSM (software plus driver for the PCI HSM)

•"usb" is the Luna USB and Backup HSMs (software plus driver for the G5-based and G7-based HSMs)

•"backup" is software to enable Remote Backup

•"ped" is software for the Luna Remote PED

>components include the optional Software Development kit, Java providers, SNMP instance (not needed for Network HSM which has it built in), Functional Module tools, and the Functional Module SDK

By default, the Client programs are installed in the /usr/safenet/lunaclient directory.

Flexible Install paths

An administrative (root) user, in charge of installing and uninstalling the software, has access wherever the installed material eventually resides. However, the operational, application-level use of Luna HSM Client might be assigned to a non-root user with constrained access and privileges. That non-root user might be a person or a departmental function or an application. By changing the install path to (for example) %home/bigapplication/safenet/luna you allow that non-root user access to tools and files for connecting to the HSM and using HSM partitions.

You can change the installation path for scriptable (non-interactive) installs by changing the prefix with the script option -install_directory <prefix>

The prefix, or major location is your choice, and replaces the /usr default portion. (See mention of SELinux, earlier on this page)

The script option -install_directory <prefix> is available for scriptable installation, where either "all" or a list of products and components is specified on the command line. The script option -install_directory <prefix> is not used with interactive installation; instead, you are prompted.

The /safenet/lunaclient portion is appended by the install script, and provides a predictable structure for additional subdirectories to contain certificate files, and optionally STC files.

Regardless of -install_directory <prefix> provided, some files are not affected by that option (for example, the Chrystoki.conf configuration file goes under /etc, service files need to be in the service directory expected by Linux in order to run at boot time, and so on).

To install the Luna HSM Client software on a Linux workstation

1.Ensure that you have sudo privileges on the client workstation.

2.Access the installation software:

Copy or move the .tar archive to a suitable directory where you can untar the archive and extract the contents:

tar xvf <filename>.tar

3.Go to the untarred directory for your operating system (32 or 64-bit):

cd /<untarred_dir>/<32/64>

4.To install the software, run the install.sh installation script. You can run the script in interactive mode, or you can script the installation, as described in Scripted or Unattended Installation.

•To display the help, or a list of available installer options, type:

sudo sh install.sh -? or sudo sh install.sh help

•To install all available products and optional components, type:

sudo sh install.sh all

•To selectively install individual products and optional components, type the command without arguments:

sudo sh install.sh

NOTE   Do not interrupt the installation script in progress. An uninterruptible power supply (UPS) is recommended. See Interrupting the Installation for more information.

5.Type y if you agree to be bound by the license agreement. You must accept the license agreement before you can install the software.

6.A list of installable Luna devices is displayed. 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.

This example shows items 1 and 3 have been selected, and item 4 is about to be selected. The selections work as a toggle - if you wish to make a change, simply type a number again and press Enter to de-select it.

Products
Choose Luna Products to be installed

    *[1]: Luna Network HSM      

     [2]: Luna PCIe HSM   

    *[3]: Luna USB HSM  


     [4]: Luna Backup HSM

     [5]: Luna Remote PED	   

     [N|n]: Next

     [Q|q]: Quit

Enter selection: 4

When selection is complete, type N or n for "Next", and press Enter. The "Advanced" menu is displayed.

Advanced
Choose Luna Components to be installed

  [1]: Luna SDK

  [2]: Luna JSP (Java)

  [3]: Luna JCProv (Java)

  [4]: Luna SNMP subagent

  [5]: Luna Functionality Module Tools

  [6]: Luna Functionality Module Software Development Kit

  [B|b]: Back to Products selection

  [I|i]: Install

  [Q|q]: Quit

 Enter selection:

7.Select or de-select any additional items you want to install. Selected items are indicated with a *. Some items might be pre-selected to provide the optimum 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.

If the script detects an existing cryptoki library, it stops and suggests that you uninstall your previous Luna software before starting the Luna HSM Client installation again.

8.The system installs all packages related to the products and any optional components that you selected.

9.[Optional] For easy use of the Luna HSM Client tools, add their directories to the $PATH.

a.Edit your system's bash_profile file using an editing tool.

vi ~/.bash_profile

b.Add the following lines to the end of the file:

export PATH="$PATH:/usr/safenet/lunaclient/bin"

export PATH="$PATH:/usr/safenet/lunaclient/sbin"

c.Source the updated bash_profile.

source ~/.bash_profile

Installing the Minimal Client Software

The minimal client package contains the minimum run-time libraries required for a cryptography application to connect to Luna Network HSM using PKCS#11 or Java APIs, or Functionality Modules on an FM-enabled HSM. Minimal client install is intended for container instances to interact with Luna HSM partitions or services.

Installing is as simple as copying the tarball and untarring it where you want it. A copy of a configured Chrystoki.conf file, along with client and server certificate files (and optionally, STC configuration files) must be available to any instance of Luna Minimal Client at run time.

See Luna Minimal Client Install for Linux - Overview for a general example using Docker.

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 Client Software or Removing Components

You may need to uninstall the client software before upgrading to a new version, or if it is no longer required.

To uninstall the client software

1.Ensure that you have sudo privileges on the client workstation.

2.Go to the client installation directory:

cd /usr/safenet/lunaclient/bin

3.Run the uninstall script:

sudo sh uninstall.sh

CAUTION!   The hsmusers group is not removed when the client software is uninstalled. Should you install the client again on the same system, all users previously in the group will have access to your attached HSMs and partitions by default. You must remove users from the group if you want to restrict their access. See Removing users from hsmusers group.

To remove individual components

To uninstall the JSP component or the SDK component, you must uninstall Luna HSM Client completely, then re-run the installation script without selecting the unwanted component(s).

Java

If you install the Luna Java Security Provider (JSP), refer to Luna JSP Overview and Installation for additional setup procedures for your operating system.

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 Luna products> and -c <list of Luna 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 [network|pci|usb|backup|ped] [-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
   network - Luna Network HSM
   pci     - Luna PCIe HSM
   usb     - Luna USB HSM
   backup  - Luna Backup HSM 
   ped     - Luna Remote PED

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 Luna Network HSM,
Luna PCIe HSM, Luna USB HSM, Luna Backup HSM and Luna Remote PED.

Select 'yes' or 'y' to proceed with the install.

Select 'no' or 'n', to cancel this install. 

Continue (y/n)?  y  

Interrupting the Installation

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 RPM package is installed, any subsequent installation attempt results in refusal with the message "A version of Luna HSM Client is already installed."

If components are missing or are not working properly after an interrupted installation, or if you wish to install any additional components at a later date (following an interrupted installation, as described), you would need to uninstall everything first. If sh uninstall.sh is unable to do it, then you must uninstall all packages manually.

Modifying the Number of Luna Backup HSM Slots

By default, the Luna HSM Client allows for three slots reserved for each model of Luna Backup HSM. You can edit Chrystoki.conf to modify the number of reserved slots. See also Configuration File Summary.

To modify the number of reserved Backup HSM slots

1.Navigate to the Chrystoki.conf file and open in a text editor.

2.Add the following line(s) to the CardReader section of the file:

•For Luna Backup HSM (G5):

LunaG5Slots = <value>;

•For Luna Backup HSM (G7):

LunaG7Slots = <value>;

Effects of Kernel Upgrades

If you upgrade the Linux kernel after successful installation of Luna Client, then you must install the kernel-headers for the new kernel and build the UHD, K6 and K7 drivers again for the new kernel. The new kernel takes effect after reboot.

To update the kernel and then bring the system back to readiness:

1.Install development tools if not already installed.

2.Update kernel if needed.

3.Reboot.

4.Install kernel-headers for the new kernel, example: yum install kernel-headers-$(uname -r)

5.Rebuild the drivers for the new kernel: rpmbuild --rebuild uhd-7.3.0-165.src
Do the same for k6 and k7 drivers.

Troubleshooting

No slots visible for Luna Network HSM = user can’t read certs directory.

No slots visible for Luna PCIe HSM or Luna USB HSM = user can’t read device (/dev/k7pf0, /dev/viper0, or /dev/lunauhd0).

You might have left a user out of hsmusers group, or you might have set an overly restrictive umask.