Steps to configure the Futurex PKCS #11 Library with the Protegrity Data Security Platform

The Protegrity documentation suite for 7.2.1 contains a guide named Protegrity Key Management Guide.

Perform initial configuration

Requirements for the Protegrity Data Security Platform include the following specifications:

Protegrity Data Security Platform 7.2.1 runs on Debian 9 with OpenSSL 1.0.2, so it needs a Futurex PKCS #11 build for Debian 9 and OpenSSL 1.0.2. The x64/OpenSSL-1.0.x build in the standard Linux package links against libssl.so.1.0.0 and libcrypto.so.1.0.0, but Debian 9 provides libssl.so.1.0.2 and libcrypto.so.1.0.2, so the library doesn’t load. Request the Debian 9 build from Futurex, and use its x64/OpenSSL-1.0.x/libfxpkcs11.so.

Perform the following configuration steps:

Zip the following files (Protegrity recommends putting all files in a tgz archive):

server and client certificate files
client private key file
pkcs11 driver (libfxpkcs11.so)
fxpkcs11.cfg

Upload the files and extract them to the /opt/protegrity/hsm/external folder.

Set the file permissions to 744 and ensure the file owner is service_admin.

Set the following environment variables in the /opt/protegrity/hsm/external/hsm.env configuration file, as shown in the following example:

None

export PTY_PKCS11_LIBRARY=${HSM_DIR}/libfxpkcs11.so
export PTY_PKCS11_ENV_KEY=FXPKCS11_CFG
export PTY_PKCS11_ENV_VALUE=${HSM_DIR}/fxpkcs11.cfg
export PTY_PKCS11_SLOT=<slot_id>

Update the fxpkcs11.cfg as shown in the following example:

Section	Parameter in the `.cfg` file	Description	Value
Config	`<LOG-FILE>`	Sets the log file location	/opt/protegrity/hsm/external/fxpkcs11.log
HSM	`<SLOT>`	Sets the PKCS #11 slot for the HSM
HSM	`<CRYPTO-OPR>`	Sets the Crypto Operator username to login to the Futurex HSM	protegrity
HSM	`<ADDRESS>`	Sets the IP address of the Futurex HSM
HSM	`<PROD-PORT>`	Sets the production port
HSM	`<PROD-TLS-CA>`	Sets the path to the HSM Server Certificate file	/opt/protegrity/hsm/external/<server_ca_file.pem>
HSM	`<PROD-TLS-CERT>`	Sets the path to the HSM Client Certificate file	/opt/protegrity/hsm/external/<client_cert_file.pem>
HSM	`<PROD-TLS-KEY>`	Sets the path to the HSM Client Private Key file	/opt/protegrity/hsm/external/<client_priv_key_file.pem>
HSM	`<PROD-TLS-KEY-PASS>`	Sets the passphrase for the HSM Client Private Key file

Restart the gateway and set the PIN

After you complete the configuration, perform the following steps to restart the HSM Gateway service on ESA and set the crypto user PIN:

On the ESA Web UI, go to System > Services.

Restart the HSM Gateway service.

To set the user pin for the ESA to connect to the HSM, first go to Key Management > HSM > HSM on the ESA Web UI.

Select [ Set User Pin ].

Set the user PIN in the dialog box.

Test the configuration

The ESA UI has built-in functionality to verify the configuration. The test verifies connectivity and authentication to the HSM and validates whether the HSM generates random bytes to confirm successful authentication and connection.

On the ESA Web UI, go to Key Management > HSM > HSM.

Select [ Test ].

The Test HSM Connection dialog box appears. If the test succeeds, green icons appear for the tests you performed.

Select [ OK ].

Activate the configuration

Perform the following steps to set the HSM as active:

On the ESA Web UI, go to Key Management > HSM > HSM.

Select [ Set As Active ].

A confirmation message box appears.

Select [ OK ].

​Perform initial configuration

​Restart the gateway and set the PIN

​Test the configuration

​Activate the configuration

Perform initial configuration

Restart the gateway and set the PIN

Test the configuration

Activate the configuration