Utimaco CryptoServer integration in Kubernetes
The Utimaco CryptoServer HSM sidecar container enables integrating the application container to a network attached Utimaco CryptoServer. The following covers how to set up the integration in Kubernetes.
For more general information on the HSM integration with PKCS#11, see HSM Integration .
Container |
|
Current Version |
|
Privileges | Running as unprivileged user 10001:0. |
License | Rights to redistribute the binary PKCS#11 library has been obtained. |
Prerequisites
Before using this container, you need the following:
A pre-installed Utimaco network attached HSM (or emulator for testing)
At least one PKCS#11 slot with soft authentication and a known passphrase
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.
Mandatory. HSM server location: Configured as
Device
in[CryptoServer]
. An example is displayed at line 57 in the Kubernetes Manifest below, specified in the formatport@dnsname-or-ip
. The default port is 288 for the netHSM and 3001 for the emulator.Optionally configured additional parameters as required.
apiVersion: v1
kind: ConfigMap
metadata:
name: ejbca-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
#[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"
Configure Deployment
The following provides an example of customizing the deployment using Helm. 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.
Ensure that the deployment is allowed an Egress to the physical HSM.
ejbca:
# signserver:
env:
TLS_SETUP_ENABLED: "later"
LOG_AUDIT_TO_DB: true
# More convenient way to integrate with HSM will be available soon
# Extra init containers to be added to the deployment
initContainers:
- name: hsm-driver-init
image: registry.primekey.com/primekey/hsm-driver-utimaco:4.51.0.1
command:
[
"sh",
"-c",
"cp --preserve --recursive /opt/keyfactor/p11proxy-client/* /mnt/driver/",
]
volumeMounts:
- name: p11proxy-client
mountPath: /mnt/driver/
# Extra sidecar containers to be added to the deployment
sidecarContainers:
- name: hsm
image: registry.primekey.com/primekey/hsm-driver-utimaco:4.51.0.1
volumeMounts:
- name: cs-pkcs11-r3-cfg
mountPath: /opt/utimaco/cs_pkcs11_R3.cfg
subPath: cs_pkcs11_R3.cfg
# Extra volumes to be added to the deployment
volumes:
- name: p11proxy-client
emptyDir: {}
- name: cs-pkcs11-r3-cfg
configMap:
name: ejbca-utimaco-configmap
items:
- key: "cs_pkcs11_R3.cfg"
path: "cs_pkcs11_R3.cfg"
# Extra volume mounts to be added to the deployment
volumeMounts:
- name: p11proxy-client
mountPath: /opt/keyfactor/p11proxy-client
# needed to make softhsm volume mount to work
podSecurityContext:
fsGroup: 10001
ingress:
enabled: true
className: "nginx"
annotations:
nginx.ingress.kubernetes.io/auth-tls-verify-client: "optional_no_ca"
#nginx.ingress.kubernetes.io/auth-tls-secret: "playground/ejbca-ingress-trust-secret"
nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
hosts:
- host: "ejbcaca.testdomain.se"
paths:
- path: /
pathType: Prefix
#tls:
# - hosts:
# - "ejbcaca.testdomain.se"
# secretName: ingress-nginx-credential-secret-ca
Create and verify HSM crypto token
To create a crypto token and then test the HSM key, do the following:
In the EJBCA menu, click CA Functions > Crypto Tokens.
Click Create new and specify the following on the New Crypto Token page:
Name: Specify a name for the crypto token.
Type: Select PKCS#11 NG.
Auto-activation: Select use to allow EJBCA to save the password and reapply it after a restart so that the CA is always available.
For PKCS#11 : Reference Type, select Slot/Token Label.
For PKCS#11 : Reference, select one of the listed slots available in the HSM.
Authentication Code: Enter a password for auto-activation, same as provided for the slot or token in the HSM.
Click Save to create the crypto token.
Next, you can generate key pairs and any existing key pairs on the HSM iare also shown.
To verify that the HSM key is operational, click Test.
Advanced deployments
The EJBCA Enterprise configuration export/import tool EJBCA ConfigDump allows you to deploy EJBCA with automation. For information on deploying EJBCA with automation, using a soft HSM integration suitable for testing, see Deploy EJBCA as CA with automation with SoftHSM2 .
Utimaco HSM installations can also be automated using the EJBCA ConfigDump tool. For information on how to configure the tool in Kubernetes, see EJBCA Configdump in Kubernetes .
The following provides example deployment artifacts:
For an example Kubernetes ConfigMap with ejbca-ca-init-configmap.yaml
HSM configurations
ConfigDump resources
(Optional) Script executed to create key pair during EJBCA installation
Helm chart values file (values.yaml): values-ca-full-doc.yaml