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
SoftHSM is the software implementation of an HSM. It can be installed from the EPEL repository. The configuration of SoftHSM can be found at /etc/softhsm2.conf (CentOS 7), or /etc/softhsm.conf (CentOS 6).
The following describes how to configure SoftHSM.
NOTE: Depending on the exact SoftHSM solution that you are using, the steps described here may slightly differ.
NOTE: The following steps assume that:
Prerequisites
The indexer user/group has the rights to read the data directory of SoftHSM and its contents, which defaults to /var/lib/softhsm.
To configure SoftHSM
-
Initialize directories for SoftHSM.
mkdir -p /var/lib/softhsm
chgrp -R indexer /var/lib/softhsm
-
Configure slots for softhsm1 (CentOS 6). For softhsm2 (CentOS 7), you can skip this step.
cat /etc/softhsm.conf
0:/var/lib/softhsm/slot0.db
1:/var/lib/softhsm/slot1.db
-
Initialize slot 0 (softhsm1).
softhsm --init-token --slot 0 --label "<your-slot-label>" –-<so-pin> topsecret --pin <your-SoftHSM-PIN>
-
Initialize a new slot (softhsm2) and get the slot ID:
softhsm2-util --init-token --free --label "<your-slot-label>" --<so-pin> topsecret --pin <your-SoftHSM-PIN>
SLOT_ID=$(softhsm2-util --show-slots | grep -B 15 "<your-slot-label>" | grep "Slot [0-9]" | head -n 1 | cut -d ' ' -f 2)
-
Import your keys. Your keys must be in the .der format.
For softhsm1, use:
pkcs11-tool --module /usr/lib/softhsm/libsofthsm.so -l -y privkey --slot 0 -w key.der -d 001 -a <your-key-label> --pin <your-SoftHSM-PIN>
For softhsm2, use:
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so -l -y privkey --slot 0 -w key.der -d 001 -a <your-key-label> --pin <your-SoftHSM-PIN>
-
Make sure that the indexer user/group has execute right to the token directory and read right to the token files below the /var/lib/softhsm/tokens/ directory.
-
Test your SoftHSM configuration with the indexer.
source /etc/indexer/external-indexer.env
indexerworker -l -v 7 --pkcs11-lib "<your-SoftHSM-library>" --pkcs11-slot-id 0 --pkcs11-pin "<your-SoftHSM-PIN>"
-
Encrypt the PKCS#11 PIN(s). For detailed instructions, see Encrypting a PKCS#11 PIN.
-
Update the "pkcs11" object in the /etc/indexer/indexerworker.cfg file.
...
"pkcs11": {
"slots": [
{
"library": "/usr/lib/softhsm/libsofthsm.so",
"slot_id": 0,
"pin": "<your-encrypted-PIN>"
}
]
}
...
Amazon Web Services (AWS) CloudHSM provides hardware security modules in the AWS Cloud.
The following describes how to configure CloudHSM.
NOTE: The following steps assume that:
-
You have set up your AWS CloudHSM, that is, you have created a user for the indexer, imported/generated keys, and so on.
For detailed information on AWS CloudHSM, see the AWS CloudHSM User Guide.
-
The CloudHSM PKCS#11 library is installed.
-
The external indexer has been installed.
To configure CloudHSM
-
Test your environment as described in Setting up and testing the environment.
Note that you will need to provide your CloudHSM PIN in the following format:
"<your-CloudHSM-username:your-CloudHSM-PIN>"
-
Encrypt the PKCS#11 PIN(s). For detailed instructions, see Encrypting a PKCS#11 PIN.
-
Update the "pkcs11" object in the /etc/indexer/indexerworker.cfg file.
...
"pkcs11": {
"custom_password": true
"slots": [
{
"library": "/opt/cloudhsm/lib/libcloudhsm_pkcs11.so",
"slot_id": 1,
"pin": "<your-encrypted-PIN>"
}
]
}
...
