The following provides information for the Thales ProtectServer 2 and 3.

Install Software

Install the software according to the installation instructions for the ProtectServer. Below are sample commands for installing the SDK rpm on an Ubuntu system, which means first converting it to a deb.

Using the SDK you can use the SDK as a good emulator for testing and development. If you are installing with a real ProtectServer you should install the Runtime instead of the SDK.

As primary option, same for both ProtectServer 2 and 3, run the HSM installs script.


# Unpack downloaded file, in this example PTK software 5.9
# CD into the directory SDK2/Linux64 (for a Linux system of course=
sudo apt install alien 
sudo ./safeNet-install.sh
# Install a package (option 3) then install the SafeNet ProtectToolkit C SDK for the Emulator, or the Runtime for the real HSM
# On Debian/Ubuntu use alien, on RHEL use rpm directly
CODE

Optionally, you can also install the RPM manually, but you then want to run the installer to create symbolic links.

# Unpack downloaded file, in this example PTK software 5.9
cd SDKs
# On Debian/Ubuntu use alien, on RHEL use rpm directly
sudo alien -i Linux64/ptkc_sdk/PTKcpsdk-5.9.0-RC5.x86_64.rpm
sudo ./safeNet-install.sh
# Select option 5 (Set the default cryptoki and/or hsm link)
BASH

The software will now be installed in /opt/safenet/protecttoolkit5 for the ProtectServer 2 and /opt/safenet/protecttoolkit7 for the ProtectServer 3. For ProtectServer 3, wherever it says protecttoolkit5 below, simply replace with protecttoolkit7.

Set passwords for admin SO och admin user

export LD_LIBRARY_PATH=/opt/safenet/protecttoolkit5/ptk/lib
XML

Create 10 slots

cd /opt/safenet/protecttoolkit5/ptk
bin/ctconf -c10
BASH

Set no public crypto

See Programming in FIPS mode in the Protect Toolkit-C Programmers Manual for information about this flag.

bin/ctconf -fc
BASH

Initialize slot 1 and 2, set SO and user password, and label

bin/ctkmu t -s1 -lprotserver1
bin/ctkmu t -s2 -lprotserver2
XML

Generate keys on slot 1

Using the Java PKCS#11 Provider

./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/PTK/lib/libcryptoki.so 2048 defaultSign 1
./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/PTK/lib/libcryptoki.so 2048 default 1
./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/PTK/lib/libcryptoki.so 512 test 1
BASH

If JBoss was started you have to restart JBoss before the keys becomes available in EJBCA.

Or if using PKCS#11 NG:

./p11ng-cli.sh generatekeypair --lib-file /opt/safenet/protecttoolkit5/ptk/lib/libctsw.so --slot-ref SLOT_LABEL --slot protserver1 --alias rsakey2048 --key-spec RSA2048
CODE

Where keys will be available after a short while when cache refreshes.

Using the Admin UI

Ensure that you have a line in web.properties finding the ProtectServer Gold PKCS#11 driver. It is default from EJBCA 8.0, before this older versions of the driver with an older path is default.

cryptotoken.p11.lib.12.name=SafeNet ProtectServer Gold Emulator
cryptotoken.p11.lib.12.file=/opt/safenet/protecttoolkit5/ptk/lib/libctsw.so
BASH

With this you should be able to create Crypto Tokens in the Admin UI using either the PKCS#11 Crypto Token or PKCS#11 NG Crypto Token

Test and list keys on slot 1

./ejbcaClientToolBox.sh PKCS11HSMKeyTool test /opt/PTK/lib/libcryptoki.so 1
...
Testing of key: test
SunJCE version 1.7SunPKCS11-libcryptoki.so-slot3 version 1.7; modulus length: 2048; byte length 53. The docoded byte string is equal to the original!
SunPKCS11-libcryptoki.so-slot3 RSA private key, 512 bits (id 4, token object, sensitive, extractable)
Signature test of key test1: signature length 64; first byte 3d; verifying true
Signings per second: 257
Decryptions per second: 260
BASH

The attributes are listed as token object, sensitive, extractable, and here is important that is says sensitive (extractable only means that the key can be backed up securely using Thales tools).

Or if using PKCS#11 NG, using listslots to find the slot ID:


./p11ng-cli.sh listslots --lib-file /opt/safenet/protecttoolkit5/ptk/lib/libctsw.so
./p11ng-cli.sh signperformancetest --lib-file /opt/safenet/protecttoolkit5/ptk/lib/libctsw.so --slot 1 --alias rsakey2048 --time-limit 1000
...
Running signing test with 1 threads using signature algorithm SHA256withRSA.
Using cache for reading keys.
Starting thread 0
Number of operations for thread 0: 7
Total number of signings: 7
Signings per second: 5.838198498748957
CODE

Backup and restore

When you have tested that all keys are working you should back them up. Read about how this is done in the ProtectServer documentation. Then clear the slot that you have just backed up:

ctkmu -s <slot nr> t
BASH

Then restore the backup according to the ProtectServer documentation and run the clientToolBox test as above. Now when you now that the keys of the slot could be restored from the backup medium you should set the attributes of them so that they could not be extracted from the HSM by any means. Unfortunate this could not be done with the ctkmu CLI tool since the private key got no label. Use the GUI kmu instead. For each key do:

  1. Select the token and login to it.
  2. Double click on the private key that you want to protect.
  3. Uncheck the Exportable box and press OK
  4. Verify that the Exportable and the Extractable boxes are unchecked and can't be changed
  5. Verify that the Private and the Sensitive boxes are checked and can't be changed

Now it should be impossible to do any backup of the key. If you got a key ceremony protocol it could be a good idea to note that keys were made unexportable. Also note that the Exportable attribute has to be unchecked each time the backup is restored.

The emulator has an annoying feature (only emulator not real HSM). Each key of same length that are generated is the same, because the seed for the random number generator is static. This means that a slot may only have one key. If a second key is generated for a slot the certificate object for the first key is deleted before writing the certificate object for the new key. This is done since the Sun p11 wrapper provider does not allow two keys that are equal to be present in a keystore. To fix this you should set the environment variable ET_PTKC_SW_AUTOSEEDRNG=true.

Generating keys using ProtectServer tools

You can also generate keys, and the needed self-signed certificate, using the Thales tools delivered with the HSM. This is for example suitable when you want to generate ECC keys with curves not supported by JDK (although you may still have to patch the JDK in order to use them anyhow).

For example, the below commands generate an ECC key with curve P-256 on slot 1, storing it on the HSM with alias foo, assigning a self-signed certificate to it and finally listing the object of slot 1.

cd /opt/safenet/protecttoolkit5/ptk/bin
./ctkmu c -tec -nfoo -aPSVXxTRD -s1 -CP-256
./ctcert c -s1 -lfoo
./ctkmu l -s1
BASH

Or you can wrap it all up in a single command...

./ctcert c -k -lfoo -tec -s1 -CP-256 -d30y
XML

If JBoss was started you have to restart JBoss before the keys becomes available in EJBCA.