SignServer Thales Luna Integration in Kubernetes

Enterprise

The Thales Luna HSM sidecar container enables an application container to communicate with a network-attached Thales Luna HSM. The sidecar runs alongside the main application container in the same Kubernetes pod, handling the HSM network connection so the application can use the HSM as a cryptographic provider without direct network configuration.

The following describes how to configure this integration in Kubernetes.

Prerequisites

Before using the Thales Luna sidecar container, you need the following:

• Luna7 net-HSM with fully configured secured network access.

  • The IP address/hostname of the HSM

  • server.pem certificate

• Administrative access on the HSM for registering a client and assigning partitions to the client.

• The P11 Proxy must have network access to the HSM service (security groups, network ACLs, and so on)

• An existing key pair credential for the client (HSM driver container) to communicate with the HSM.

Deployment Parameters for the HSM Driver Container

The following lists environment variables and volume mount parameters for the HSM sidecar container:

Environment Variables

The following environment variables configure the HSM sidecar container:

Volume Mount Parameters

The volume mount parameters are mandatory and only need to be configured in the HSM sidecar container. These mounts are defined in the Helm chart values.yaml file using a combination of ConfigMap and Secret resources.

You can verify the configuration by checking the corresponding files inside the container after deployment.

Step 1 - Prepare HSM Configuration

Configure the server certificate and client credentials:

1. Create a Kubernetes secret with the client private key to communicate with the HSM.

   • The file name inside the secret must be dockerlunaclientKey.pem.

   • Replace <namespace> with the namespace of your deployment.

   • The name of this secret must be referenced later in the Helm values.yaml.

     Bash

     kubectl create secret generic hsm-luna-secret-client-key \
          -n signservernamespace --from-file=dockerlunaclientKey.pem=dockerlunaclientKey.pem
     

2. Create a Kubernetes ConfigMap to configure the HSM server certificate and client certificate.

   • The HSM server certificate and client certificate values in the values.yaml may be adjusted in the next section.

Example (certificate contents truncated):

configMaps:
  - name: luna-serverpem
    data:
      server.pem: |
        -----BEGIN CERTIFICATE-----
        MIIDKzCCAhOgAwIBAgIBADANBgkqhkiG9w0BAQsFADBZMQswCQYDVQQGEwJDQTEQ
        .....truncated.....
        Kf/NEBK9vrVTT1Lnpv/oaXunE/X5ZnX7HgoAvB91osDyWoWPDs8Oc2f/kD4aaZCK
        vHi8vXeUfZPBNyYoryNkM+yDHewlEahvb7AfGuzxUJ4MLCDC4j9RWOb0+LwMrx4=
        -----END CERTIFICATE-----
  - name: luna-client
    data:
      dockerlunaclient.pem: |
        -----BEGIN CERTIFICATE-----
        MIIDHTCCAgWgAwIBAgIBADANBgkqhkiG9w0BAQsFADBSMQswCQYDVQQGEwJDQTEQ
        .....truncated.....
        EofLJ18/a4pERXZurLotJRqP3Gzm2IKv0uTaAk1UxKkWKe9xJ4K7MxgFvHF+4I1q
        NJ60RtvgYsAMARWFM58kV6ASYi3y08UAgYJqwHUy/rkU
        -----END CERTIFICATE-----

3. Optional: Create a Secret for Chrystoki.conf
   This is the only supported way to configure multiple HSMs as a cluster.
   If you need to connect to multiple HSMs or use a clustered configuration, you must supply a custom Chrystoki.conf. For example, using a single HSM, see Chrystoki-example.conf. To configure the HSM server details, such as the IP and port, you only need to edit the LunaSA Client block.

   kubectl create secret generic -n signservernamespace \
         hsm-luna-chrystokisecret \
       --from-file=Chrystoki.conf=production-chrystoki.conf
   

Step 2 - Configure Deployment

Use Helm to customize your deployment. A base configuration is provided in values.yaml. Use this as a starting point and extend it for your environment.

The following parameters are not included in values.yaml and must be configured manually before deploying:

• Database connection: Connection string to the database used by the application.

• imagePullSecrets: Required if your cluster pulls images from a private registry.

• TLS connection: Requiring a CA to issue server/client certificates.

Example: Configuration using server_name

The following example only includes the values relevant for the HSM sidecar container. Adjust the values for the HSM server environment variable (server_name) and any required secrets:

signserver:
  # Extra init containers to be added to the deployment
  initContainers:
  - name: p11proxy
    image: keyfactor.jfrog.io/dev-oci/keyfactor-commons/hsm-driver-luna7/images/hsm-driver-luna7:0.6.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: luna-hsm
    image: keyfactor.jfrog.io/dev-oci/keyfactor-commons/hsm-driver-luna7/images/hsm-driver-luna7:0.6.0
    imagePullPolicy: IfNotPresent
    env:
      - name: SERVER_NAME
        value: <server ip>
    volumeMounts:
      - name: volume-luna-server
        mountPath: /opt/luna/certs-server/server.pem
        subPath: server.pem

      - name: volume-luna-clientkey
        mountPath: /opt/luna/certs-client/dockerlunaclientKey.pem
        subPath: dockerlunaclientKey.pem

      - name: volume-luna-client
        mountPath: /opt/luna/certs-client/dockerlunaclient.pem
        subPath: dockerlunaclient.pem
  volumes:
  - name: volume-luna-server
    configMap:
      name: luna-serverpem

  - name: volume-luna-clientkey
    secret:
      secretName: hsm-luna-secret-client-key

  - name: volume-luna-client
    configMap:
      name: luna-client
  
  - name: p11proxy-client
    emptyDir: {}

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

Example: Configuration using Chrystoki.conf

Alternatively, mount in Chrystoki.conf via the secret created in the last step.

signserver:
  # Extra init containers to be added to the deployment
  initContainers:
  - name: p11proxy
    image: keyfactor.jfrog.io/dev-oci/keyfactor-commons/hsm-driver-luna7/images/hsm-driver-luna7:0.6.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: luna-hsm
    image: keyfactor.jfrog.io/dev-oci/keyfactor-commons/hsm-driver-luna7/images/hsm-driver-luna7:0.6.0
    imagePullPolicy: IfNotPresent
    volumeMounts:
      - name: volume-luna-server
        mountPath: /opt/luna/certs-server/server.pem
        subPath: server.pem

      - name: volume-luna-clientkey
        mountPath: /opt/luna/certs-client/dockerlunaclientKey.pem
        subPath: dockerlunaclientKey.pem

      - name: volume-luna-client
        mountPath: /opt/luna/certs-client/dockerlunaclient.pem
        subPath: dockerlunaclient.pem

      - name: volume-chrystoki-conf
        mountPath: /opt/keyfactor/Chrystoki.conf
        subPath: Chrystoki.conf
  volumes:
  - name: volume-luna-server
    configMap:
      name: luna-serverpem

  - name: volume-luna-clientkey
    secret:
      secretName: hsm-luna-secret-client-key

  - name: volume-chrystoki-conf
    secret:
      secretName: hsm-luna-chrystokisecret

  - name: volume-luna-client
    configMap:
      name: luna-client
  
  - name: p11proxy-client
    emptyDir: {}

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

Step 3 - Create and Verify HSM Crypto Token

After SignServer is running with the Thales Luna HSM sidecar, create the Crypto Token:

1. In the SignServer Admin Web, click the Add… link.

2. Click FROM TEMPLATE button.

3. Select p11ng-crypto.properties from the drop-down menu.

4. Configure the Crypto Worker with the following options:

5. 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.