Hardware Security Module (HSM) Support for Private Keys

Preparation

In order to use the NitroKey HSM card with OTRS it is necessary to first configure OpenSSL to work with libp11. While there are different ways to do this it is recommended to create a custom configuration file and include at the beginning the main OpenSSL configuration file. An example of this custom configuration file is shown below:

openssl_conf = openssl_init

[openssl_init]
engines = engine_section

[engine_section]
pkcs11 = pkcs11_section

[pkcs11_section]
engine_id = pkcs11
dynamic_path = <libpkcs11_PATH>
MODULE_PATH = opensc-pkcs11.so
init = 0

[req]
distinguished_name = req_distinguished_name

[req_distinguished_name]

Where <libpkcs11_PATH> is the path to the engine module provided by libp11 such as:

/usr/lib/ssl/engines/libpkcs11.so
/usr/local/lib/engines-1.1/libpkcs11.dylib
...

Depending on the version, the operating system and the way it was installed this can be different in your situation. Please refer to the documentation of lib11 to find the correct paths according to your installation.

Save the file for example in /etc/openssl/hsm.cnf and include a link to this file in the beginning of the OpenSSL original configuration file as:

# OpenSSL example configuration file.
# This is mostly being used for generation of certificate requests.
#
# Note that you can include other files from the main configuration
# file using the .include directive.
# .include filename
.include /etc/openssl/hsm.cnf

Settings

1. Set the correct path and enable SMIME::PKCS15ToolBin. If the pkcs15-tool is correctly installed the path can be found by executing the which pkcs15-tool command. The result should be copied and pasted into the setting.

2. Set the correct path and enable SMIME::HSMPrivatePath. It is recommended to create a new directory different than SMIME::PrivatePath to prevent any confusions and left overs.

3. Set the correct HSM card serial number and user PIN in SMIME::HSMCard::PIN. The current card serial number can be obtained by using the Maint::SMIME::HSMCard::Check console command. The current user PIN is the one used in the initialization. The card serial numbers for example cards can be removed.

4. Enable the HSM card usage in setting SMIME::UseHSM.

Checking Environment

Execute the Maint::SMIME::HSMCard::Check console command. The output should look like this:

Reading HSM card information...
+-----------------+--------------------+
| Label | SmartCard-HSM                |
| Serial number   | DENK0100003        |
| Manufacturer ID | www.CardContact.de |
| User PIN        | Verified           |
+-----------------+--------------------+
Checking OpenSSL engines...
+--------------------------------+-------------+
| Dynamic engine loading support | Available   |
| pkcs11 engine                  | Available   |
| Intel RDRAND engine            | Available   |
+--------------------------------+-------------+
Done

It is important that the User PIN is verified and that the pkcs11 engine is available. If any other listed engine is not available, it does not necessarily mean a problem.

Importing HSM Card Certificates and Keys

While signing and decryption of the messages is done in the HSM card it is still needed that OTRS imports certain information from the HSM card. The public certificates needs to be copied from the card to the file system. This can be done in the usual SMIME::CertPath setting.

A stub file with some private key meta data needs to be generated and placed in the path that was set in SMIME::HSMPrivatePath setting. This meta data includes the HSM card serial number, the key ID, label, hash, modulus, etc.

To accomplish this task, a new Maint::SMIME::HSMCard::Sync console command has been created. The output should look like this:

Syncronizing certificates and private keys metadata...
  Reading HSM card information... OK
  Reading HSM card objects... OK
  Processing HSM certificates and keys...
  ID 'a1b2e3d4'... OK
  ID 'f5d6e7c8'... OK
Done.

Usage

The HSM card should now be ready for use and the usage should now be transparent for the users, e.g. creating a new email ticket.

Make sure to use a queue where the system address has a certificate and a private key in the HSM module and choose to sign the email with S/MIME from the security options field. The submitting of the form might be slightly slower as the HSM card needs to be unlocked and perform the operation.

Settings

It is needed to set the card user PIN as the stored key password in the PGP::Key::Password setting. For example, if the key ID is 11223344 and the card user PIN is 123456, create a new item in the setting and in the first part set 11223344 and then set 123456 as the value.

To get the key ID:

1. Open the PGP Keys module in the administrator interface.

2. Check the ID for the key in the Key column.

Usage

The usage should now be transparent for the users, e.g. creating a new email ticket. Make sure to use a queue where the system address has a public and private key pair in the secure card and choose to sign the email with PGP from the security options field.