Skip to content

Configure an HSM for Distributed Issuer

This guide explains how to configure Distributed Issuer (formerly known as Firefly) to use a Hardware Security Module (HSM) for secure key storage and signing operations.

Prerequisites

To complete these steps, you'll need:

  • To run Distributed Issuer, a Linux host or container runtime environment, for example Kubernetes or Docker. See Build an HSM-enabled container image.
  • An HSM device; currently, we support Luna Network HSMs.
  • Client software for your HSM installed on the host or container where Distributed Issuer will run.
    • When installing, you need to identify the Partition Label, PIN, and PKCS#11 library.
    • For added security, use the checksum from the PKCS#11 library to ensure Distributed Issuer is using an approved library.

  • The latest Distributed Issuer PKCS#11 binary. Use crane to download the container image and extract the binary:

    crane export registry.ngts.paloaltonetworks.com/distributed-issuer-public/distributed-issuer-base-pkcs11:v1.11.0 | tar --strip=1 -xf - /ko-app/distributed-issuer

  • Access to configure a config.yaml file for Distributed Issuer. Learn more

Step 1: Install and configure the HSM client software

  1. Install the client software for your HSM on the host or container where Distributed Issuer will be running. Follow the instructions provided by your HSM vendor.
  2. Verify the installation is successful. For example, if installing Luna Network HSM, run vtl verify.

Step 2: Add a configuration file

  1. Edit the config.yml file to add the PKCS#11 library path and other necessary configurations, replacing the data in this example with yours. Learn more

    config.yml
    bootstrap:
  ngts:
    connection:
      inline:
        tsgID: "1426959155"

        jwt:
          - file:
              path: /path/to/your/built-in-account.key
          - privateKeyJWT:
              clientID: 00000000-0000-0000-0000-000000000000
    csr:
      instanceNaming: Distributed-Issuer
    pkcs11:
      clientLibraryPath: /usr/safenet/lunaclient/lib/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. (Optional) Calculate the SHA-256 checksum of the PKCS#11 library file for additional security, specifying the path of the PKCS#11 library file that Distributed Issuer will use. 

    sha256sum /usr/safenet/lunaclient/lib/libCryptoki2_64.so

Step 3: Configure the HSM in the SubCA provider

  1. In Next-Gen Trust Security, go to Configuration > Issuer Sub CA Providers.
  2. Click New and select a CA provider.
  3. Fill out the CA provider details and enable Require HSM.
  4. Enter a Partition Label and PIN.
  5. (Optional) If the HSM has more than one partition with the same label, enter the Partition Serial Number.
  6. (Optional) In Allowed Client Libraries, add the checksums for the client libraries that Distributed Issuer is allowed to use.

Step 4: Test the configuration

To test the configuration, start Distributed Issuer and check the logs for entries indicating successful connection and key generation using the HSM.

# Example command to start Distributed Issuer with the configured yaml file
distributed-issuer run --config /path/to/your/config.yaml

Disabling memory lock

To enable memory paging, add the --disable-mlock parameter. Since the signing private key is HSM-protected, there's a lower risk of the Distributed Issuer process memory being paged out to disk.

Look for a log entry similar to the following:

"msg"="generating key pair on external pkcs11 device"
"logger"="agent.bootstrap.vaas"

This confirms that Distributed Issuer is using the HSM for key operations.