Installing ProtectToolkit on Linux Manually

The simplest way to complete installation or uninstallation of ProtectToolkit compnents, or to change the Cryptoki provider, is to use the Unix Installation Utility. The utility ensures that the correct commands for your platform are executed automatically. See Installing ProtectToolkit on Unix/Linux for more information.

You must become the superuser of the host system before adding or removing any packages.

NOTE   If you are installing ProtectToolkit 5.9.1 on an AIX system, you must first download ProtectToolkit 5.9 from the Thales Support Portal and install it by following the procedures described in this section.

If you wish to install ProtectToolkit components manually, use the commands described in this section after extracting the installation files you downloaded from the Thales Support Portal:

>Manual Linux Installation for Network Mode

>Manual Linux Installation for PCIe Mode

•Signing the ProtectServer PCIe 2 Driver for UEFI Secure Boot

>Manual Linux Installation for Net Server Mode

>Installing ProtectToolkit-C Manually on Linux

•Changing the Cryptoki Provider manually

>Installing ProtectToolkit-J Manually on Linux

>Installing the ProtectToolkit FMSDK Manually on Linux

>Configuring ProtectToolkit

Manual Linux Installation for Network Mode

Use the following commands to install or uninstall the Network Access Provider package. It includes the components required to access a ProtectServer HSM over the network, whether a ProtectServer External 2, ProtectServer External 2 Plus, or ProtectServer PCIe 2 configured for network access.

To install the Network Access Provider manually

Execute the following as root (where x.x.x-yy is the PTK version number). Specify the location you chose for the installation files:

# cd /output-unix/Linux64/network_hsm_access_provider
rpm -i PTKnethsm-x.x.x-yy.x86_64.rpm

To uninstall the Network Access Provider manually

Use the rpm(8) command with the appropriate package name as a parameter.

# rpm -e PTKnethsm

Manual Linux Installation for PCIe Mode

Use the following commands to install or uninstall the PCIe Access Provider package. It includes the device driver components for a ProtectServer PCIe 2 HSM installed in the host system.

To install the PCie access provider manually

Execute the following as root (where x.x.x-yy is the PTK version number). Specify the location you chose for the installation files:

# cd /output-unix/Linux64/pci_hsm_access_provider_PSI-E2
rpm -i PTKpcihsmK6-x.x.x-yy.x86_64.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 PCie access provider manually

Use the rpm(8) command with the appropriate package name as a parameter.

# rpm -e PTKpcihsmK6

Signing the ProtectServer PCIe 2 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 2 in 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 2 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 2 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 public and private keys named MOK.der and MOK.priv. You can use the default locations specified in the command below or specify your own filepaths.

# 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 2 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

Manual Linux Installation for Net Server Mode

Use the following commands to install or uninstall the Net Server Access Provider package. It includes the components required to make an installed ProtectServer PCIe 2 HSM available on the network to other ProtectToolkit clients. Requires an installed ProtectServer PCIe 2 and the PCIe HSM Access Provider package as prerequisites.

To install the Net Server Access Provider manually

Execute the following as root (where x.x.x-yy is the PTK version number). Specify the location you chose for the installation files:

# cd /output-unix/Linux64/hsm_net_server
rpm -i PTKnetsrv-x.x.x-yy.x86_64.rpm

To uninstall the Net Server Access Provider manually

Use the rpm(8) command with the appropriate package name as a parameter.

# rpm -e PTKnetsrv

Installing ProtectToolkit-C Manually on Linux

Use the following commands to install or uninstall ProtectToolkit-C.

To install ProtectToolkit-C manually

1.Choose the PTK-C package you wish to install:

•ProtectToolkit C Runtime: installs all the necessary tools and interfaces for a ProtectToolkit-C based Cryptoki service provider. Requires the correct Access Provider package for your deployment as a prerequisite.

•ProtectToolkit C SDK: installs the PTK-C software development platform. Header files are included, in addition to the PTK-C Runtime. Requires the correct Access Provider package for your deployment as a prerequisite.

NOTE   The Runtime and SDK packages cannot be installed concurrently. To switch from one package to the other, uninstall the package that is no longer required and then install the new one.

2.Execute the following as root for your selected package (where x.x.x-yy is the PTK version number). Specify the location you chose for the installation files:

•ProtectToolkit C Runtime:

# cd /output-unix/Linux64/PTKC_Runtime
rpm -i PTKcprt-x.x.x-yy.x86_64.rpm

•ProtectToolkit C SDK:

# cd /output-unix/Linux64/hsm_net_server
rpm -i PTKcpsdk-x.x.x-yy.x86_64.rpm

3.Add the /opt/safenet/protecttoolkit5/ptk/bin directory to the execution path and the /opt/safenet/protecttoolkit5/ptk/lib directory to the library path. The following commands may be used to configure your paths for the sh(1) shell.

Once installed, the software is ready to use under /opt/safenet/protecttoolkit5.

To uninstall the ProtectToolkit-C packages manually

Use the rpm(8) command with the appropriate package name as a parameter.

# rpm -e PTKcprt

# rpm -e PTKcpsdk

Changing the Cryptoki Provider manually

This section applies to the SDK package only.

Different ProtectToolkit-C Cryptoki provider files are required if an HSM is present (PCI or network mode) or not (software-only mode).

Both Cryptoki provider files are installed with the SDK package. On Unix/Linux systems, the software-only Cryptoki provider is made active by default.

To change the default Cryptoki provider selection

Remove the soft-link:

/opt/safenet/protecttoolkit5/ptk/lib/libcryptoki.so or
/opt/safenet/protecttoolkit5/ptk/lib/libcryptoki.a (for AIX)

and recreate it to point to the SafeNet HSM Cryptoki provider. For example, the following shell commands may be used to enable the HSM (executed as the super-user):

# cd /opt/safenet/protecttoolkit5/ptk/lib
# rm libcryptoki.so
# ln -s libcthsm.so libcryptoki.so

The following shell commands may be used to enable the software emulation (executed as the super-user):

# cd /opt/safenet/protecttoolkit5/ptk/lib
# rm libcryptoki.so
# ln -s libctsw.so libcryptoki.so

Installing ProtectToolkit-J Manually on Linux

Use the following commands to install or uninstall ProtectToolkit-J.

NOTE   PTK-J requires the PTK-C Runtime component as a prerequisite.

To install ProtectToolkit-J manually

1.First, install the ProtectToolkit J Runtime package, which includes all the necessary tools and interfaces for a PTK-J Cryptoki service provider, using the Java Cryptographic Architecture (JCA) / Java Cryptographic Extension (JCE) interface.

Execute the following as root (where x.x.x-yy is the PTK version number). Specify the location you chose for the installation files:

# cd /output-unix/Linux64/PTKJ_Runtime
rpm -i PTKjprov-x.x.x-yy.x86_64.rpm

2.If desired, install the ProtectToolkit J SDK, for developing Java applications for use with your ProtectServer HSM.

Execute the following as root (where x.x.x-yy is the PTK version number). Specify the location you chose for the installation files:

# cd /output-unix/Linux64/PTKJ_SDK
rpm -i PTKjpsdk-x.x.x-yy.x86_64.rpm

To uninstall the ProtectToolkit-J packages manually

Use the rpm(8) command with the appropriate package name as a parameter.

# rpm -e PTKjpsdk

# rpm -e PTKjprov

Installing the ProtectToolkit FMSDK Manually on Linux

Use the following commands to install or uninstall the ProtectToolkit Functionality Module Software Development Kit for building FMs or host applications.

To install the FMSDK packages manually

1.First, install the FMSDK package. Execute the following as root (where x.x.x-yy is the PTK version number). Specify the location you chose for the installation files:

# cd /output-unix/Linux64/fm_sdk
rpm -i PTKfmsdk-x.x.x-yy.x86_64.rpm

2.Install the FM Toolchain package, which includes the components required to compile and run your Functionality Modules.

Execute the following as root (where x.x.x is the PTK version number). Specify the location you chose for the installation files:

# cd /output-unix/Linux64/fm_toolchain
rpm -i eldk-x.x.x.i686.rpm

To uninstall the ProtectToolkit FMSDK packages manually

Use the rpm(8) command with the appropriate package name as a parameter.

# rpm -e eldk

# rpm -e PTKfmsdk

Configuring ProtectToolkit

When you have completed the installation, refer to Configuration Items for additional PTK client configuration options, then to the guides for your installed components:

>About the ProtectToolkit-C Administration Guide

>About the ProtectToolkit-J Reference Guide

>About the ProtectToolkit-M User Guide

>About the FM SDK Programming Guide

If you have installed ProtectToolkit-C and intend to use PCI or network operating modes:

>Configure the secure messaging system (SMS). Refer to Secure Messaging.

>Establish network communication (network operating mode only). by configuring the client to use one or more servers that are available on the same network. Refer to Specifying the Network Server(s).

If you have installed ProtectToolkit-C and intend to use software-only mode:

>Customize the installation to optimize performance. Refer to Software-Only Mode Configuration.