It is possible to use a hardware security module (HSM) or a smart card to store the decryption keys required for decrypting audit trails. An HSM or a smart card is a tamper-resistant physical, software, or cloud solution that can securely store digital keys used for authentication.
The main steps of configuring a hardware security module (HSM) or smart card to integrate with an external indexer are as follows:
-
Set up and test the environment.
-
Encrypt the PKCS#11 PIN.
To see examples of how to configure various HSM or smart card solutions that you wish to integrate with your external indexer(s), consult the following sections:
Detailed information about this topic
To access an HSM or smart card with the external indexer, a PKCS#11 shared library plugin must be used. In most cases, these libraries also need a background daemon or environment variables set. The PKCS#11 library must be accessible to the external indexer with a proper environment.
To set up the environment and test it, complete the following steps.
-
Load the environment for the indexer commands:
source /etc/indexer/external-indexer.env
-
Test your environment.
-
Option #1: Use the pkcs11-tool to test your environment:
-
List the available slots.
pkcs11-tool --modul <path-to-pkcs11-library> -L
-
List the objects in a slot.
pkcs11-tool --modul <path-to-pkcs11-library> -l --slot <id> -O
-
Option #2: Use the indexerworker with the log level set to dump to see the available keys:
indexerworker -l -v 7 --pkcs11-lib <path-to-pkcs11-library> --pkcs11-slot-id <id> --pkcs11-pin <pin>
-
Assuming that the environment is ready, the external indexer must be configured to use the PKCS#11 library. To do so, edit /etc/indexer/indexerworker.cfg as follows:
...
"settings": {
"pkcs11": {
"custom_password": false
"slots": [
{
"library": "<path-to-pkcs11-library>",
"slot_id": <slot-number>,
"pin": "<your-encrypted-PIN>"
}
]
}
}
...
The PKCS#11 PIN(s) must be protected by additional encryption. The indexerconfigcrypter tool must be used to encrypt the PIN(s).
To encrypt the PIN(s)
-
Encrypt the PIN.
The PINs can be encrypted with a custom passphrase or a default one is used if no custom passphrase is provided. A custom passphrase is more secure, but interaction is needed to start or restart the external-indexer service. Using a custom passphrase is supported on hosts running CentOS 7 or later.
Issue either of the following commands:
It is possible to configure multiple slots. In that case, the PINs must be encrypted using the same passphrase.
-
Update the "pkcs11" object in the indexerworker.cfg file.
The encrypted PINs must be stored in the "pin" field of the configuration file (in the example, a SoftHSM is used):
...
"pkcs11": {
"custom_password": true
"slots": [
{
"library": "/usr/lib/softhsm/libsofthsm.so",
"slot_id": 0,
"pin": "<your-encrypted-PIN>"
}
]
}
...
When you choose to encrypt the PKCS#11 PIN(s) using a custom password, on starting or restarting the external-indexer service, you are asked to enter your password using a special tool.
To provide your password using the required tool
-
Start the external-indexer service:
systemctl start external-indexer
-
The external-indexer service prompts you to provide a password using the systemd-ask-password tool. Issue:
systemd-tty-ask-password-agent
-
Provide the password at the prompt. You can use multiple agents to enter the password.
-
Once the external indexer(s) have been started or restarted, make sure that all the indexers have started up successfully.
For example, on CentOS 7, you can use:
systemctl status external-indexer
