Breadcrumbs

Setting Up GP HSMaaS Connection

  1. Copy the downloaded software to the appropriate location on the BIG-IP machine.

  2. Create a directory /etc/utimaco. Copy the Utimaco PKCS#11 configuration file cs_pkcs11_R3.cfg into this directory. It is located in Linux/Crypto_APIS/PKCS11_R3/sample.

  3. Edit the cs_pkcs11_R3.cfg file located at “/etc/utimaco/” and update the Device value to the HSM IP.

[Global]
# Path to the logfile (name of logfile is attached by the API)
# For Unix:
Logpath = /tmp
# Loglevel (0 = NONE; 1 = ERROR; 2 = WARNING; 3 = INFO; 4 = TRACE)
Logging = 1
# Maximum size of the logfile in bytes (file is rotated with a backup file if full)
Logsize = 10mb

# If true, every session establishes its own connection
SlotMultiSession = true

# If false, multiple users are allowed to log in as one session, leading to the permissions being added up
SlotLoginRestriction = true

# Maximum number of slots that can be used
SlotCount = 10

# If true, leading zeroes of decryption operations will be kept
KeepLeadZeros = false

# Prevents expiring session after inactivity of 15 minutes
KeepAlive = true

# Timeout of the open connection command in ms
ConnectionTimeout = 5000

# Timeout of command execution in ms
CommandTimeout = 60000

# Set the Device to connect with
#[CryptoServer]
# Device specifier
Device = TLS:<port>@<HSMaaS_IP>

  1. Create utimaco folder under /opt directory and further create two directories: /etc/utimaco/bin and /etc/utimaco/lib.

  2. Copy pkcs11 library file libcs_pkcs11_R3.so from Linux\Crypto_APIs\PKCS11_R3\lib directory to the /opt/utimaco/lib directory and make the file executable.

image-20250814-135708.png

libcs_pkcs11_R3.so file and path


  1. Copy the csadm and p11tool2 files from Linux\Administration directory to /opt/utimaco/bin directory and make both the files executable.

image-20250814-133016.png

csadm and p11tool2 files

  1. Copy the CA certificate, client certificate and key to /etc/utimaco

  2. Create a script named startup_script_pkcs11d_fix.sh under the /config directory and update with the content provided below. Make sure to replace the client certificate, CA certificate, and client key filenames according to the files downloaded from the HSM portal.

#!/bin/bash
source /usr/lib/bigstart/bigip-ready-functions
wait_bigip_ready
 
PKCS11D_SCRIPT="/etc/bigstart/scripts/pkcs11d"
 
sed -i '/^export TLS_CLIENT_CERT=/d' "$PKCS11D_SCRIPT"
sed -i '/^export TLS_CLIENT_KEY=/d' "$PKCS11D_SCRIPT"
sed -i '/^export TLS_CA_BUNDLE=/d' "$PKCS11D_SCRIPT"
sed -i '/^export TLS_SKIP_DN_VERIFY=/d' "$PKCS11D_SCRIPT"
sed -i '/^export TLS_VERBOSE=/d' "$PKCS11D_SCRIPT"
sed -i '/^export TLS_DEBUG=/d' "$PKCS11D_SCRIPT"
sed -i '/^export CS_PKCS11_R3_CFG=/d' "$PKCS11D_SCRIPT"
 
sed -i '/^service=pkcs11d/a \
export TLS_CLIENT_CERT=/etc/utimaco/<GPHSMaaS-TLS-client certificate>.crt\n\
export TLS_CLIENT_KEY=/etc/utimaco/<GPHSMaaS-TLS-clientkey>.pem\n\
export TLS_CA_BUNDLE=/etc/utimaco/<GPHSMaaS-chain>.crt\n\
export TLS_SKIP_DN_VERIFY=1\n\
export TLS_VERBOSE=1\n\
export TLS_DEBUG=1\n\
export CS_PKCS11_R3_CFG=/etc/utimaco/cs_pkcs11_R3.cfg\n' \
"$PKCS11D_SCRIPT"
 
bigstart restart pkcs11d >/dev/null 2>&1

  1. Make the script executable.

  2. Append the following line to the bottom of the /config/startup file

 /config/startup_script_pkcs11d_fix.sh

  1. Update the .bashrc file with the following content, or define these environment variables locally on the BIG‑IP machine.Make sure to replace the client certificate, CA certificate, and client key filenames according to the files downloaded from the HSM portal.

export TLS_CLIENT_CERT=/etc/utimaco/<GPHSMaaS-TLS-client certificate>.crt
export TLS_CLIENT_KEY=/etc/utimaco/<GPHSMaaS-TLS-clientkey>.pem
export TLS_CA_BUNDLE=/etc/utimaco/<GPHSMaaS-chain>.crt
export TLS_SKIP_DN_VERIFY=1
export TLS_VERBOSE=1
export TLS_DEBUG=1
export CS_PKCS11_R3_CFG=/etc/utimaco/cs_pkcs11_R3.cfg

  1. Restart pkcs11d service.

#bigstart restart pkcs11d
#bigstart restart

  1. Run below command to check the connection established or not.

#./csadm dev=TLS:<port>@<HSMaaS IP> GetState


Update the certificate names according to the received certificates.

To simplify your testing process, it's recommended that you enable the PKCS#11 log file by adjusting the logging settings. Specifically:

  • Set the LogPath to a writable directory (not a specific file).

  • Set the Logging Loglevel to 1 for basic logging. Increase it to 4 for more detailed output during testing.

This will generate a log file named cs_pkcs11_R3.log within the specified LogPath directory. Reviewing this log can help with troubleshooting if you encounter issues.

Once testing is complete, it's advisable to reduce Logging Loglevel to 1 or 2 to limit output to only critical or important messages.