T Configuring HSM Support

This appendix describes the procedure for configuring RUEI to access private keys stored on HSM devices. Note that this functionality is available on beta basis. You should have access to your HSM vendor's documentation before starting.

T.1 Introduction

A Hardware Security Module (HSM) is a device that can be attached to a server system to manage digital keys. It provides both logical and physical protection of these materials from non-authorized use.

HSM support within RUEI is based on OpenSSL. A detailed description of the OpenSSL project is available at http://www.openssl.org/. The monitoring support provided by RUEI has been verified against the Thales nCipher product line. However, other OpenSSL-based implementations should also work.

T.2 Installing and Configuring the HSM Vendor Software

Do the following:

Install the HSM vendor software on each required Collector system. For information on the installation procedure, refer to your HSM vendor documentation.
Configure each required Collector system in the security domain of the HSM. For information on how to do this, refer to your HSM vendor documentation.
If applicable, make the HSM vendor libraries available to OpenSSL either via ldconfig or by exporting the LD_LIBRARY_PATH environment variable. For example, within the Thales nCipher product line, assuming that the software is installed in the directory /opt/nfast, this is achieved by issuing the following commands:
```
echo /opt/nfast/toolkits/hwcrhk > /etc/ld.so.conf.d/ncipher.conf
ldconfig
```

T.3 Configuring the Collector Systems

To configure the required Collector systems, do the following:

Obtain a list of the currently defined Collector profiles by issuing the following command as the RUEI_USER on the Reporter system:
```
execsql config_get_profiles
```
All Collector systems within the relevant profile(s) will need to be configured for connection to the HSM device as described in the rest of this section.
In order for RUEI to access private keys stored on an HSM device, a connection is required to the HSM device. This is established through an OpenSSL engine (such as chil). Issue the following command to test whether the required OpenSSL engine is supported on each required Collector system:
```
openssl engine -c engine
```
where engine specifies your vendor's OpenSSL engine. The following output example shows support for the cswift engine.
```
(cswift) CryptoSwift hardware engine support
  [RSA, DSA, DH, RAND]
```
Test whether the selected OpenSSL engine is actually available for connection to the HSM device by issuing the following command:
```
openssl engine -c -tt engine
```
Output similar to the following indicates that the OpenSSL engine is available:
```
(cswift) CryptoSwift hardware engine support
[RSA, DSA, DH, RAND]
[ available ]
```
Check your HSM implementation's log file to ensure successful connection from the Collector system(s) to the HSM device. For example, within the Thales nCipher product line, this is located at /opt/nfast/log/hardserver.log. For further information, refer to your HSM vendor documentation.
Configure the required OpenSSL engine for each Collector system by issuing the following command on the Reporter system as RUEI_USER:
```
execsql config_set_profile_value wg profile ssl SSLUseEngine replace engine
```
where profile specifies the required Collector profile.
Restart each required Collector. To do so, select Configuration, and then Collector profiles. Select the required Collector profile. For each Collector assigned to the selected profile, select Restart from the context menu.

Note:

When the collector running on the Reporter system, identified by localhost, is not used for HSM integration or is disabled in your environment you should still prepare this collector for HSM integration. This is because the SSL key verification takes place using the localhost collector. Make sure this collector is enabled while uploading the HSM key to RUEI. Once the key is uploaded the localhost collector may be disabled again.

T.4 Configuring HSM Keys

In order for RUEI to be able to decrypt any HSM-encrypted traddic, you will first need to import your existing HSM keys into RUEI. You need to ensure that they are in the embed format and are module protected. All keys must be stored within the HSM device as module protected. That is, a module key is used to protect user authentication tokens. Such keys have no passphase, and can be accessed by any application that is connected to the HSM device within the appropriate security domain. Note that this description is specific to the Thales product line.

If your existing keys do not meet the above requirements, you will need to retarget them before importing them into RUEI. Consult your HSM vendor documentation for information on the procedure to do this.

After generation or retargeting, a special PEM file is created by the HSM software. This file can be imported into RUEI (as described in Section 13.5, "Managing SSL Keys"). Note that the public certificate must be included in the PEM file. If the generated PEM file does not contain the public certificate, you will need to manually append it to the PEM file. The special PEM file does not actually contain the SSL key, but references the key that is stored on the HSM.

T.5 Verifying Correct Monitoring of HSM-Based Traffic

To verify that the keys stored on the HSM device are being successfully decrypted, review the information within the SSL encryption tab in the Collector Statistics window. The use of this facility is described in Section 15.2, "Viewing the Status of the Collectors".