SignServer Utimaco uTrust and CryptoServer Integration in Kubernetes

Enterprise

The Utimaco HSM sidecar container integrates the SignServer container with a network-attached Utimaco uTrust or CryptoServer HSM. The sidecar runs the p11proxy server using the Utimaco PKCS#11 driver, configured with a file called cs_pkcs11_R3.cfg.

For a general overview of how the PKCS#11 sidecar integration works, see HSM Integration.

Prerequisites

Before using this container, you need the following:

A pre-installed Utimaco network-attached HSM (or Utimaco emulator for testing).
At least one PKCS#11 slot configured with soft authentication and a known passphrase.

Step 1 - Prepare HSM Configuration

The HSM driver client needs to be configured to communicate with the Utimaco HSM. The configuration file cs_pkcs11_R3.cfg is shared with the HSM driver (sidecar) container as a Kubernetes ConfigMap.

Configure HSM Server Location

The configuration must define the HSM location using either:

A [HSMCluster] section, or
A [CryptoServer] section (deprecated by Utimaco)

Only one of these sections may be present.

The following shows a typical configuration:

[HSMCluster]
ClusterID = 0000
Devices = 192.168.8.101

Configuration using explicit port and IP

[HSMCluster]
ClusterID = 0000
Devices = 3001@192.168.8.101

Configuration using domain name (must not contain hyphens)

[HSMCluster]
ClusterID = 0000
Devices = 4001@hsmdomain

Legacy configuration form, without ClusterID

[HSMCluster]
Devices = 192.168.28.28

Deprecated configuration using [CryptoServer]

[CryptoServer]
Device = 3001@utimaco-emulator

For reference, the default ports are:

288 for netHSM
3001 for the Utimaco emulator

Example Kubernetes Manifest

The configuration supports several additional parameters such as logging, connection timeouts, session handling, and key-storage settings. Modify the values as required for your environment.

YAML

configMaps:
  - name: signserver-utimaco-configmap
    data:
      cs_pkcs11_R3.cfg: |
        [Global]
        # Path to the logfile (name of logfile is attached by the API)
        # For unix:
        Logpath = /opt/utimaco

        # Loglevel (0 = NONE; 1 = ERROR; 2 = WARNING; 3 = INFO; 4 = TRACE)
        Logging = 0
        # Maximum size of the logfile in bytes (file is rotated with a backupfile if full)
        Logsize = 0

        # Created/Generated keys are stored in an external or internal database
        KeysExternal = false

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

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

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

        # Configures load balancing mode ( == 0 ) or failover mode ( > 0 )
        # In failover mode, n specifies the interval in seconds after which a reconnection attempt to the failed CryptoServer is started.
        FallbackInterval = 0

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

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

        # Timeout of command execution in ms
        CommandTimeout = 60000

        # List of official PKCS#11 mechanisms which should be customized
        #CustomMechanisms = { CKM_AES_CBC CKM_AES_ECB }

        # Enforce thread-safety by using the operating system locking primitives
        #ForceOSLocking = true

        # The [HSMCluster] section replaces the deprecated [CryptoServer] section. For backwards-
        # compatibility, a [CryptoServer] section can still be used, but it MUST NOT be mixed with
        # [HSMCluster] sections.
        [HSMCluster]
        # Device specifier (here: local simulator)
        Devices = 3001@127.0.0.1

        # Device specifier (here: cluster of simulators)
        #Devices = { 3001@127.0.0.1 3003@127.0.0.1 }

        # Device specifier (here: cHSM on remote u.trust Anchor device - port = base port (4000) + cHSM slot (1))
        #Devices = 4001@192.168.0.1

        # Device specifier (here: remote device with IP address 192.168.0.1)
        #Devices = 192.168.0.1

        # Device specifier (here: cluster of remote devices - first as above, others using format <port>@<ip>)
        #Devices = { 192.168.0.1 288@192.168.0.2 4001@192.168.0.3 }

        #[CryptoServer]
        # Device specifier (here: CryptoServer is internal PCI device)
        # For unix:
        #Device = /dev/cs2
        # For windows:
        #Device = PCI:0  

        #[CryptoServer]
        # Device specifier (here: CryptoServer is CSLAN with IP address 192.168.0.1) 
        #Device = 3001@utimaco-emulator

        #[CryptoServer]
        # Device specifier (here: CryptoServer is logical failover device of CSLANs with IP address 192.168.0.2 and IP address 192.168.0.3) 
        #Device = { 192.168.0.2 192.168.0.3 }

        #[CryptoServer]
        # Device specifier Simulator 
        #Device = { 3001@127.0.0.1 3003@127.0.0.1 }

        #[Slot]
        # Slotsection for slot with number 0
        #SlotNumber = 0

        #[KeyStorage]

        # Legacy SDB file
        #KeyStorageType = Legacy
        # Path to the external keystore
        # If KeyStore is defined the external keystore will be created and used at the defined location
        # For unix:
        #KeyStore = /tmp/P11.pks
        # For windows:
        #KeyStore = C:/ProgramData/Utimaco/PKCS11_R3/P11.pks

        # Database via ODBC
        #KeyStorageType = odbc
        #KeyStorageConfig = "DSN=PSQL Ucapi External Storage"

Step 2 - Configure Deployment

The following provides an example of customizing the deployment using Helm. The sidecarContainers section is configured to use the Utimaco HSM with the ConfigMap just created.

Note that the Helm chart values file values.yaml describes an example test deployment and does not include:

Database connection.
Configured imagePullSecrets that may be required.
TLS connection required after the deployment and creation of the CAs.

YAML

signserver:
  initContainers:
  - name: p11proxy
    image: keyfactor.jfrog.io/dev-oci/keyfactor-commons/hsm-driver-utimaco/images/hsm-driver-utimaco:0.4.0
    imagePullPolicy: IfNotPresent
    command:
      [
        "sh",
        "-c",
        "cp --preserve --recursive /opt/keyfactor/p11proxy-client/* /mnt/",
      ]
    volumeMounts:
      - name: p11proxy-client
        mountPath: /mnt
  # Extra sidecar containers to be added to the deployment
  sidecarContainers:
  - name: utimaco
    image: keyfactor.jfrog.io/dev-oci/keyfactor-commons/hsm-driver-utimaco/images/hsm-driver-utimaco:0.4.0
    imagePullPolicy: IfNotPresent
    volumeMounts:
      - name: volume-utimaco-conf
        mountPath: /etc/cs_pkcs11_R3.cfg
        subPath: cs_pkcs11_R3.cfg

  volumes:
  - name: p11proxy-client
    emptyDir: {}

  - name: volume-utimaco-conf
    configMap:
      name: signserver-utimaco-configmap

  volumeMounts:
    - name: p11proxy-client
      mountPath: /opt/keyfactor/p11proxy-client

configMaps:
  - name: signserver-utimaco-configmap
    data:
      cs_pkcs11_R3.cfg: |
        [Global]
        # Path to the logfile (name of logfile is attached by the API)
        # For unix:
        Logpath = /opt/utimaco

        # Loglevel (0 = NONE; 1 = ERROR; 2 = WARNING; 3 = INFO; 4 = TRACE)
        Logging = 0
        # Maximum size of the logfile in bytes (file is rotated with a backupfile if full)
        Logsize = 0

        # Created/Generated keys are stored in an external or internal database
        KeysExternal = false

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

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

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

        # Configures load balancing mode ( == 0 ) or failover mode ( > 0 )
        # In failover mode, n specifies the interval in seconds after which a reconnection attempt to the failed CryptoServer is started.
        FallbackInterval = 0

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

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

        # Timeout of command execution in ms
        CommandTimeout = 60000

        # List of official PKCS#11 mechanisms which should be customized
        #CustomMechanisms = { CKM_AES_CBC CKM_AES_ECB }

        # Enforce thread-safety by using the operating system locking primitives
        #ForceOSLocking = true

        # The [HSMCluster] section replaces the deprecated [CryptoServer] section. For backwards-
        # compatibility, a [CryptoServer] section can still be used, but it MUST NOT be mixed with
        # [HSMCluster] sections.
        [HSMCluster]
        # Device specifier (here: local simulator)
        Devices = 3001@127.0.0.1

        # Device specifier (here: cluster of simulators)
        #Devices = { 3001@127.0.0.1 3003@127.0.0.1 }

        # Device specifier (here: cHSM on remote u.trust Anchor device - port = base port (4000) + cHSM slot (1))
        #Devices = 4001@192.168.0.1

        # Device specifier (here: remote device with IP address 192.168.0.1)
        #Devices = 192.168.0.1

        # Device specifier (here: cluster of remote devices - first as above, others using format <port>@<ip>)
        #Devices = { 192.168.0.1 288@192.168.0.2 4001@192.168.0.3 }

        #[CryptoServer]
        # Device specifier (here: CryptoServer is internal PCI device)
        # For unix:
        #Device = /dev/cs2
        # For windows:
        #Device = PCI:0  

        #[CryptoServer]
        # Device specifier (here: CryptoServer is CSLAN with IP address 192.168.0.1) 
        #Device = 3001@utimaco-emulator

        #[CryptoServer]
        # Device specifier (here: CryptoServer is logical failover device of CSLANs with IP address 192.168.0.2 and IP address 192.168.0.3) 
        #Device = { 192.168.0.2 192.168.0.3 }

        #[CryptoServer]
        # Device specifier Simulator 
        #Device = { 3001@127.0.0.1 3003@127.0.0.1 }

        #[Slot]
        # Slotsection for slot with number 0
        #SlotNumber = 0

        #[KeyStorage]

        # Legacy SDB file
        #KeyStorageType = Legacy
        # Path to the external keystore
        # If KeyStore is defined the external keystore will be created and used at the defined location
        # For unix:
        #KeyStore = /tmp/P11.pks
        # For windows:
        #KeyStore = C:/ProgramData/Utimaco/PKCS11_R3/P11.pks

        # Database via ODBC
        #KeyStorageType = odbc
        #KeyStorageConfig = "DSN=PSQL Ucapi External Storage"

Step 3 - Create and Verify HSM Crypto Token

After SignServer is running with the Utimaco sidecar, create the Crypto Token:

In the SignServer Admin Web, click the Add… link.
Click FROM TEMPLATE button.
Select p11ng-crypto.properties from the drop-down menu.
Configure the Crypto Worker with the following options:

Field	Value
`WORKERGENID1.NAME`	A descriptive name, for example, `Utimaco-Token`
`WORKERGENID1.SHAREDLIBRARYNAME`	P11 Proxy
`WORKERGENID1.SLOTLABELTYPE`	`SLOT_INDEX`, `SLOT_NUMBER`, or `SLOT_LABEL`
`WORKERGENID1.PIN`	Optional password for the slot. If specified, the token is “auto-activated”.

Click APPLY.

Once created, you can generate new key pairs or view any existing key pairs on the HSM.

To verify that communication with the HSM is functional, click on the Crypto Worker and go to the Crypto Token tab, and try to generate a key pair.