Build an HSM-enabled container image for Distributed Issuer¶

The PKCS#11 version of Distributed Issuer uses third-party HSM client libraries for key protection. These libraries are licensed and distributed separately by HSM vendors. To run Distributed Issuer with HSM support in Kubernetes, you need to build a container image that includes both the Distributed Issuer PKCS#11 binary and your HSM vendor's client library.

PKCS#11 Client¶

Review the instructions provided by your HSM vendor for building Linux container images that work with their product. You will need to acquire the applicable HSM client software that includes a PKCS#11 library.

• Thales: Installing Luna Minimal Client on Linux using Docker
• AWS: How to run AWS CloudHSM workloads in container environments
• Entrust: nShield Container Option Pack: Application Containers

Sample: Luna Network HSM using Red Hat Universal Base Image (UBI)¶

Step 1: Build the image using Docker¶

1. Prepare a Dockerfile that looks something like this for a UBI based image:

   # FROM registry.ngts.paloaltonetworks.com/distributed-issuer-public/distributed-issuer-base-pkcs11:v1.11.0 AS distributed-issuer-base
   # or
   FROM registry.ngts.paloaltonetworks.com/distributed-issuer/distributed-issuer-base-pkcs11-fips:v1.11.0 AS distributed-issuer-base
   
   FROM registry.access.redhat.com/ubi8/ubi@sha256:bcfca5f27e2d2a822bdbbe7390601edefee48c3cae03b552a33235dcca4a0e24
   
   RUN yum install -y tar glibc.i686
   
   WORKDIR /tmp
   COPY ./610-000401-010_SW_Linux_Luna_Minimal_Client_V10.7.0_RevA.tar lunaclient.tar
   
   RUN mkdir -p /usr/local/luna
   RUN tar xvf /tmp/lunaclient.tar --strip 1 -C /usr/local/luna
   RUN rm /tmp/lunaclient.tar
   ENV ChrystokiConfigurationPath=/usr/local/luna/config
   ENV PATH="/usr/local/luna/bin/64:${PATH}"
   
   COPY --from=distributed-issuer-base /ko-app/distributed-issuer /ko-app/distributed-issuer
   
   LABEL org.opencontainers.image.vendor="Palo Alto Networks, Inc."
   LABEL org.opencontainers.image.licenses="EULA - https://www.paloaltonetworks.com/legal"
   LABEL org.opencontainers.image.authors="support@paloaltonetworks.com"
   LABEL org.opencontainers.image.title="Distributed Issuer"
   LABEL org.opencontainers.image.url="https://www.cyberark.com/products/workload-identity-manager/"
   LABEL org.opencontainers.image.documentation="https://docs.cyberark.com/mis-saas/firefly/overview/"
   
   USER 65532:65532
   
   ENTRYPOINT [ "/ko-app/distributed-issuer" ]
   

   False positive CVEs

   Scanners may report CVE-2025-15467, CVE-2025-69419, and CVE-2026-0861 in the distributed-issuer-base-pkcs11 images. These are false positives. The affected libraries (libssl, libc) are included in the base image but are not used by Distributed Issuer, and are not present after you copy the binary out as described below.

2. Build the container image. This command assumes the Dockerfile and the HSM client software tarball:

   docker build . --tag distributed-issuer-luna-network-hsm:sample
   

Step 2: Test the image using Docker¶

1. Prepare a Distributed Issuer config.yaml similar to the following:

   config.yml

   bootstrap:
     ngts:
       connection:
         inline:
           tsgID: "1426959155"
   
           jwt:
             - file:
                 path: /container-mount/built-in-account.key
             - privateKeyJWT:
                 clientID: 00000000-0000-0000-0000-000000000000
       csr:
         instanceNaming: Distributed-Issuer
       pkcs11:
         clientLibraryPath: /usr/local/luna/libs/64/libCryptoki2_64.so
   server:
     grpc:
       port: 8001
       tls:
         dnsNames:
           - distributed-issuer.example.com
         ipAddress: 10.20.30.40
     rest:
       port: 8002
       tls:
         dnsNames:
           - distributed-issuer.example.com
         ipAddress: 10.20.30.40
   

2. Run the container. This command assumes the Distributed Issuer config.yaml and service account private key file are in the current directory, and the Chrystoki.conf and HSM certificate files are in the luna/ subdirectory:

   docker run --rm \
         --cap-add=IPC_LOCK \
         -p 8001:8001 -p 8002:8002 \
         -v ./built-in-account.key:/container-mount/built-in-account.key:ro \
         -v ./config.yaml:/container-mount/config.yaml:ro \
         -v ./luna:/usr/local/luna/config:ro \
         distributed-issuer-luna-network-hsm:sample \
         run -c /container-mount/config.yaml