Installation for PCIe Mode

This chapter provides instructions for installing the ProtectServer PCIe HSM Access Provider. Please see the appropriate section for your host system:

>Windows Installation for PCIe Mode

>Linux Installation for PCIe Mode

•Signing the ProtectServer PCIe HSM Driver for UEFI Secure Boot

Windows Installation for PCIe Mode

This section provides instructions for Windows operating systems. The latest versions of the client software and HSM firmware can be found on the Thales Technical Support Customer Portal. See Support Contacts for more information.

Before following the procedure below, ensure that you are logged in as a member of the Windows administrator group.

Upgrading

If you are upgrading the access provider, you must uninstall any currently-installed version by using the Windows Programs and Features control panel.

CAUTION!   If uninstallation is not carried out first, the system may lock up. See Troubleshooting for recovery instructions.

To install the ProtectServer PCIe HSM Access Provider

1.Locate the installer directory and execute the file PTKpcihsm2.msi.

2.Work through the installation wizard.

By default, the ProtectServer PCIe HSM Access Provider package is installed in the following directory:

\Program Files\SafeNet\Protect Toolkit 5\PCI HSM 2

3.A prompt during the installation allows you to change the default destination. Unless there is good reason, the default should be accepted.

4.You will be prompted to install the driver. The driver is required.

NOTE   A reboot may be required to successfully load the driver.

To verify correct installation

From a command prompt, execute the hsmstate utility. If the adapter has been correctly installed, the response will include:

HSM in NORMAL MODE. RESPONDING

For more information, see hsmstate.

Making Configuration Changes

Finally, make any necessary configuration changes. Currently, the only configurable setting in PCIe mode is the ET_HSM_PCICLIENT_READ_TIMEOUT_SECS variable. This setting determines the time in seconds the PCIe driver will wait before timing out on a read operation. It should be set long enough to avoid an unintentional timeout, which causes the driver to shut down the HSM. See Configuration Items for instructions on how to change this setting, and PCI Mode Client Configuration Items for a description of the variable.

Linux Installation for PCIe Mode

This chapter provides instructions for Linux operating systems.

The Unix Installation Utility

The simplest way to install or uninstall an access provider package on any of the Linux/Unix platforms is to use the Unix Installation Utility. The utility ensures that the correct commands for your platform are automatically executed.

If you wish to enter Linux commands manually, see Manual Linux Installation Commands.

Linux install preparation

Before adding or removing any packages, you must become the super-user on the host system.

The Linux driver is distributed as source code and must be compiled for the running kernel before loading as a dynamic module. In most cases, the installation script will do this automatically, provided the following conditions are met:

>The same version of the C compiler (gcc) used to compile the kernel must be available.

>The rpmbuild package is installed.

>The appropriate kernel source package for the running system is installed. The kernel source is usually installed in /usr/src/linux-<VER> with a symbolic link from either:

•/lib/modules/<VER>/build or

•/lib/modules/<VER>/source

where <VER> is the kernel version as reported by uname –r

To install the ProtectServer PCIe HSM Access Provider

1.Mount the installation CD-ROM and navigate to its directory. For example:

# cd /cdrom/cdrom0/

2.Use the Unix Installation Utility.

Select the ProtectServer PCIe HSM Access Provider device driver package from the Install Menu. This will install the ProtectServer PCIe HSM Access Provider package, including the device driver and test utilities, as well as the manual pages for these programs to the default directory (/opt/safenet).

See Using the Unix Installation Utility for more information.

NOTE   A reboot may be required to successfully load the driver.

Manual Linux Installation Commands

To install the access provider manually

The access provider is installed by executing the following as root (super-user):

# cd /cdrom/cdrom0/Linux/pci_hsm_access_provider
rpm -i PTKpcihsm2-X.X-X.i386.rpm

If the compile fails, or the driver does not come up automatically (hsmstate fails), you will need to correct the problem and then cd /opt/ETpcihsm/src and invoke make(1) as root. The Makefile in that directory has some notes to help you get the driver compiled correctly.

To uninstall the access provider manually

To remove the software from your host system, simply use the rpm(8) command with the appropriate package name as a parameter.

For example:

# rpm -e PTKpcihsm2

Making Configuration Changes

Finally, make any necessary configuration changes. Currently, the only configurable setting in PCIe mode is the ET_HSM_PCICLIENT_READ_TIMEOUT_SECS variable. This setting determines the time in seconds the PCIe driver will wait before timing out on a read operation. It should be set long enough to avoid an unintentional timeout, which causes the driver to shut down the HSM. See Configuration Items for instructions on how to change this setting, and PCI Mode Client Configuration Items for a description of the variable.

Signing the ProtectServer PCIe HSM Driver for UEFI Secure Boot

Red Hat Enterprise Linux 7 (RHEL 7) can be installed and run on systems where UEFI Secure Boot is enabled. With Secure Boot enabled, the RHEL kernel requires all kernel modules, including device drivers, to be signed by a key that is trusted by the EFI boot loader. If a module is not signed, it is prevented from loading at runtime and the dependent device will not work.

To use ProtectServer PCIe HSMin a Secure Boot-enabled environment, the driver must be signed and trusted by the OS and boot loader.

The following procedure includes:

>Generating RSA signing keys and certificates

>Signing the ProtectServer PCIe driver

>Enrolling the signing public key into the system keyring

>Loading the signed driver

Prerequisites

>UEFI Secure Boot must be enabled on the Linux system.

>The ProtectServer PCIe HSM Access Provider must be installed.

The driver will fail to load and service vkd status may return vkd is not running.

System logs might display the error message could not insert module vkd.ko: Required key not available. This appears because the driver module vkd.ko needs to be signed.

>Driver signing requires that the following tools be available on the system:

Tool	Provided by Package	Used on	Purpose
openssl	openssl	Build system	Generates public and private X.509 key pair
sign-file	kernel-devel	Build system	Perl script used to sign kernel modules
perl	perl	Build system	Perl interpreter used to run the signing script
mokutil	mokutil	Target system	Optional tool used to manually enroll the public key
keyctl	keyutils	Target system	Optional tool used to display public keys in the system key ring

To sign and load the ProtectServer PCIe HSM driver

1.Create a configuration file with parameters for generating a key pair that satisfies RHEL 7 kernel module signing requirements.

# vi <configuration_filename>.config

[ req ]
default_bits = 4096
distinguished_name = req_distinguished_name
prompt = no
string_mask = utf8only
x509_extensions = myexts

[ req_distinguished_name ]
O = Organization
CN = Organization signing key
emailAddress = E-mail address

[ myexts ]
basicConstraints=critical,CA:FALSE
keyUsage=digitalSignature
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid

2.Use the openssl tool to generate a signing key pair. Specify the configuration file you created and unique file names for the public and private keys.

# openssl req -x509 -new -nodes -utf8 -sha256 -days 36500 -batch -config <configuration_filename>.config -outform DER -out <public_keyname>.der -keyout <private_keyname>.priv

3.Use the Machine Owner Key utility (mokutil) to enroll your public key on the machine(s) where you wish to load the ProtectServer PCIe HSM driver. When RHEL 7 boots on a UEFI Secure Boot-enabled system, the keys on the MOK list are added to the system keyring.

a.Request that your public key be added to the MOK list.

# mokutil --import <public_keyname>.der

You are prompted to enter and confirm a password for the request.

b.Reboot the machine.

During reboot, the MOK enrollment request is noticed by shim.efi, which launches MokManager.efi so that you can complete the enrollment from the UEFI console.

c.When prompted, press any key to perform MOK management.

d.From the list of options, select Enroll MOK.

e.Select Continue and then Yes to confirm that you want to enroll the key.

f.Enter the password you created for the enrollment request.

g.Select Reboot to reboot the machine.

4.Sign the ProtectServer PCIe HSM driver with the private key. This is accomplished using a perl script. You must specify both the private and public key files and the driver file that you wish to sign (vkd.ko).

# perl /usr/src/kernels/$(uname -r) /scripts/sign-file sha256 <private_keyname>.priv <public_keyname>.der /lib/modules/$(uname -r)/kernel/drivers/crypto/vkd.ko

5.Load the ProtectServer PCIe driver.

# service vkd restart