1.18.0 1.17.5
Auto Light Dark
Auto Light Dark
1.18.0 1.17.5

Installation and Configuration of Utimaco SecurityServer Software

Downloading and Installing Utimaco Software

If you have not already done so, please create and request a Utimaco Support Portal Account.
This will allow you to download the software components needed for this installation.

  1. Copy the downloaded software to the appropriate location on the Cloudflare Keyless SSL Server.

  2. Create the required directories under /opt/utimaco.

sudo mkdir -p /opt/utimaco/bin
sudo mkdir -p /opt/utimaco/lib
  1. Copy the PKCS#11 library (libcs_pkcs11_R3.so) to the library directory.

sudo cp ~/path_to_application_folder/lib/libcs_pkcs11_R3.so /opt/utimaco/lib/
  1. Copy the required Utimaco utilities (csadm and p11tool2) to the binary directory.

cd ~/path_to_application_folder
sudo cp csadm p11tool2 /opt/utimaco/bin/
  1. Make the binaries executable.

sudo chmod +x /opt/utimaco/bin/csadm /opt/utimaco/bin/p11tool2


u.trust GP HSM PKCS#11 Configuration

  1. Create a directory to store the PKCS#11 configuration file.

sudo mkdir -p /opt/utimaco/PKCS11_R3
  1. Navigate to the PKCS#11 sample configuration directory in the Utimaco software package and copy the configuration file.

cd <install_directory>/Software/Linux/x86-64/Crypto_APIS/PKCS11_R3/sample
sudo cp cs_pkcs11_R3.cfg /opt/utimaco/PKCS11_R3/
  1. Move to the configuration directory.

cd /opt/utimaco/PKCS11_R3
  1. Update the PKCS#11 configuration fileEdit the configuration file.

sudo vi /opt/utimaco/PKCS11_R3/cs_pkcs11_R3.cfg

Update the configuration as shown below.

[Global]
# For unix:
Logpath = /tmp
# Loglevel (0 = NONE; 1 = ERROR; 2 = WARNING; 3 = INFO; 4 = TRACE)
Logging = 1
Keepalive = true
# Set the Device to connect with
[CryptoServer]
# Device specifier
Device = <HSM_IP>
  1. Set proper permissions (required for GoKeyless).

sudo chown -R gokeyless:gokeyless /opt/utimaco/PKCS11_R3
  1. Run the following command to validate HSM connectivity and PKCS#11 configuration.

./p11tool2 ListSlots
image-20260605-080035.png

Listing available HSM slots with p11tool2

For more information regarding the commands and command parameters, please
check the u.trust GP HSM documentation. The device may be a u.trust GP HSM
(PCIe or LAN) device.
The device line will follow one of these patterns, based on the HSM form-factor:

Device = 288@<HSM IP address> Hardware (LAN) HSM
OR
Device = /dev/cs2.0 Hardware (PCIe) HSM

To make your testing easier, you can enable the PKCS#11 log file.
That can be enabled by editing the Logging Loglevel. Set the LogPath and Logging
Loglevel to 1. For testing you may want to increase it to 4.
The added LogPath points to a writable directory, not to a file.
If you encounter problems, check the log file named cs_pkcs11_R3.log in the
LogPath defined directory. When you are done testing, you should change Logging
to 1 or 2. This will limit the logging to only critical and important messages.

u.trust GP HSM Simulator Setup and Initialization

This section describes how to set up and start the u.trust GP HSM Simulator on the Keyless server for testing purposes.

  1. Copy the simulator package (sim5_linux) to the designated directory on the server.

sudo mkdir -p /opt/utimaco/Simulator
sudo cp -r <path_to_sim5_linux> /opt/utimaco/Simulator/
  1. Assign execution permissions to the simulator binaries.

cd /opt/utimaco/Simulator/sim5_linux
sudo chmod +x *
  1. Install the required 32-bit libraries (if not already installed).

sudo dnf update -y
sudo dnf install glibc.i686 libstdc++.i686 zlib.i686 -y
  1. Verify required system library.

ls /lib/ld-linux.so.2

The file path should be displayed. If not, install missing dependencies.

  1. Navigate to the simulator directory and start the simulator.

cd /opt/utimaco/Simulator/sim5_linux
./bl_sim5 -h -o -d ../devices
image-20260605-082412.png

Utimaco HSM simulator successfully started

The simulator setup described in this guide is optional and intended for lab and testing purposes only.

For production deployments, it is recommended to use a physical u.trust GP HSM, as it provides the required security, performance, and compliance characteristics expected in a production environment.

Create SO User and Initialize a Slot

This section describes how to create Security Officer (SO) and User accounts, initialize a slot, and update default credentials on the u.trust GP HSM Simulator.

Prerequisites:

  • the HSM Simulator is running and accessible (e.g., 127.0.0.1).

  • the csadm utility is available in the current directory or PATH.

  • the admin key file (e.g., ADMIN_SIM.key) is available.

Steps:

  1. Create a user assigned to the slot.

./csadm dev=3001@127.0.0.1 LogonSign=ADMIN,./ADMIN_SIM.key AddUser=USR_0000,00000022{CXI_GROUP=SLOT_0000},hmacpwd,87654321
  1. Create the SO user for slot management.

./csadm dev=3001@127.0.0.1 LogonSign=ADMIN,./ADMIN_SIM.key AddUser=SO_0000,00000200{CXI_GROUP=SLOT_0000},hmacpwd,87654321
  1. Change the default password for the SO user.

./csadm dev=3001@127.0.0.1 Logonpass=SO_0000,87654321 ChangeUser=SO_0000,Cloud123
  1. Change the default password for the user.

./csadm dev=3001@127.0.0.1 Logonpass=USR_0000,87654321 ChangeUser=USR_0000,Cloud123
  1. List all users to confirm successful creation.

./csadm dev=3001@127.0.0.1 LogonSign=ADMIN,./ADMIN_SIM.key ListUsers
image-20260605-083136.png

Utimaco HSM user configuration details

  • Replace 127.0.0.1 with the actual HSM IP address if using a remote device.

  • Replace passwords (87654321, Cloud123) with secure values as per policy.

  • Ensure the slot name (SLOT_0000) matches your configuration.

  • The group assignment {CXI_GROUP=SLOT_0000} links the user to the corresponding slot.

The SO is responsible for slot initialization and user management, while the User account is used for cryptographic operations via PKCS#11 (e.g., GoKeyless integration).

Installation and Configuration of Cloudflare Keyless SSL

Installation of GoKeyless

  1. Update the System Packages. First, ensure that the system package repository is up to date.

sudo dnf update -y

This command updates all installed packages to their latest versions to ensure compatibility and avoid dependency-related issues during installation.

  1. Install the necessary tools required for downloading and managing packages.

sudo dnf install -y wget curl tar

wget and curl are used for downloading files from external sources.tar is used for extracting compressed archives if required during setup.

  1. Install the DNF plugins package and add the Cloudflare GoKeyless repository.

sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://pkg.cloudflare.com/gokeyless.repo

dnf-plugins-core enables repository management features. The Cloudflare repository is added to allow installation of the GoKeyless package directly using the package manager.

  1. Install the GoKeyless package from the configured repository.

sudo dnf install -y gokeyless

This installs the Cloudflare GoKeyless daemon, which acts as a bridge between Cloudflare’s edge servers and the private key stored in the HSM.

image-20261015-052259.png

GoKeyless setup and package installation

  1. Configure file permissions.

sudo chmod 644 /etc/keyless/gokeyless.yaml
  1. Add the required user (e.g., build) to the keyless group.

sudo usermod -aG keyless build
  1. Check the installed GoKeyless version.

gokeyless --version
image-20261015-052348.png


GoKeyless version details

Cloudflare Dashboard Configuration

  1. Log in to the Cloudflare Dashboard.
    Navigate to the Cloudflare portal and log in using your credentials.

  2. Select the Domain.
    After logging in, select the required domain from the list of configured domains. This ensures that all subsequent configurations are applied to the correct domain associated with the Keyless SSL setup.

image-20260609-083448.png

Cloudflare domain overview dashboard

  1. Navigate to the DNS Configuration.
    Go to the DNS section of the selected domain. The DNS section is used to manage domain records, which are required to route traffic correctly between Cloudflare, the key server, and the origin server.

  2. Create DNS Records.
    Create the required DNS records for both the key server and user-facing application.

Key Server DNS Record

Hostname: kms.utimaco.ssl4saas.com  
Type: A  
Proxy Status: DNS only (Grey Cloud)

The key server hostname must be configured as DNS-only to allow Cloudflare to directly communicate with the GoKeyless server over port 2407 without proxy interference.

User Access DNS Record

Hostname: utimaco.ssl4saas.com  
Type: A  
Proxy Status: Proxied (Orange Cloud)

The user-facing hostname must be proxied through Cloudflare to enable SSL termination at the Cloudflare edge and to utilize the Keyless SSL configuration.

image-20260609-083543.png

Cloudflare DNS records configuration