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. When using the SDK you may use /opt/ETcpsdk/lib/linux-x86_64 instead of /opt/PTK/lib

fakeroot alien -c $CDROM/Linux64/ptkc_sdk/ETcpsdk-3.32.00-1.x86_64.rpm
sudo dpkg -i ./etcpsdk_3.32.00-2_amd64.deb

Set passwords for admin SO och admin user

LD_LIBRARY_PATH=/opt/PTK/lib /opt/PTK/bin/ctconf

Create 10 slots

LD_LIBRARY_PATH=/opt/PTK/lib /opt/PTK/bin/ctconf -c10

Set no public crypto

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

LD_LIBRARY_PATH=/opt/PTK/lib /opt/PTK/bin/ctconf -fc

Initialize slot 5. Sets SO and user password

LD_LIBRARY_PATH=/opt/PTK/lib /opt/PTK/bin/ctkmu t -s5 -lroot

Generate keys on slot 5

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

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

Contents of CA Token Properties

When you create the CA in EJBCA you can now use the simple CA token properties below.

certSignKey defaultSign
crlSignKey defaultSign
defaultKey default
testKey test
sharedLibrary=/opt/PTK/lib/libcryptoki.so
slotLabelType=SLOT_NUMBER
slotLabelValue=5

Test and list keys on slot 5

./ejbcaClientToolBox.sh PKCS11HSMKeyTool test /opt/PTK/lib/libcryptoki.so 5
...
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

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).

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

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:

Select the token and login to it.
Double click on the private key that you want to protect.
Uncheck the Exportable box and press OK
Verify that the Exportable and the Extractable boxes are unchecked and can't be changed
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/ETCprt/bin/linux-x86-64
./ctkmu c -tec -nfoo -aPSVXxTRD -s1 -CP-256
./ctcert c -s1 -lfoo
./ctkmu l -s1

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

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

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