Skip to content

Setting up HSM with Firefly

This guide provides step-by-step instructions for configuring Firefly to use a Hardware Security Module (HSM) for secure key storage and signing operations. By following this guide, you will enable Firefly to leverage HSMs for enhanced security and compliance with enterprise policies.

Prerequisites

Before you begin, review the following requirements:

  • A Linux VM or container runtime environment (e.g., Kubernetes or Docker) where Firefly will be running.
  • An HSM device. Currently, we support Luna Network HSM.
  • Client software for your HSM installed on the host or container where Firefly will be running:
    • When installing, you need to identify the Partition Label, PIN, and PKCS#11 library, as you'll need these later on.
    • For added security, the checksum of the PKCS#11 library can be used to ensure Firefly is using an approved library.
  • Download the firefly-pkcs11 binary:
    • Latest Release
    • Specific Version: https://dl.venafi.cloud/firefly/{version}/firefly-pkcs11_linux_amd64.zip(replace {version} with the desired version, e.g., 1.4.0)
  • Access to configure the config.yaml file for Firefly. 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 Firefly will be running. Follow the instructions provided by your HSM vendor.
  2. Verify the installation is successful. For example, if you were installing Luna Network HSM, you could run vtl verify.

Step 2: Configure the config.yaml file

  1. Edit the config.yaml file to add the PKCS#11 library path and other necessary configurations. Learn more 

    # Example config.yaml
bootstrap:
  vaas:
    auth:
      privateKeyFile: /root/firefly/svc-acct.pvk
      clientID: 3e6c5fc1-1f79-11ef-9d15-7e27f5fb02e1
    csr:
      instanceNaming: Firefly-RHEL8
    pkcs11:
      clientLibraryPath: /usr/safenet/lunaclient/lib/libCryptoki2_64.so
server:
  grpc:
    port: 8081
    tls:
      dnsNames:
        - sample.Venafi.example
      ipAddress: 192.0.2.1
  graphql:
    port: 8123
    playground: true
    tls:
      dnsNames:
        - sample.Venafi.example
      ipAddress: 192.0.2.1
  rest:
    port: 8281
    tls:
      dnsNames:
        - sample.Venafi.example
      ipAddress: 192.0.2.1
    Note: Replace the data in the sample YAML with your specific data.

  2. (Optional) Calculate the SHA-256 checksum of the PKCS#11 library file for additional security. 

    sha256sum /usr/safenet/lunaclient/lib/libCryptoki2_64.so
    Note: Specify the path of the PKCS#11 library file that Firefly will be using.

Step 3: Configure the HSM in the SubCA provider

  1. In the Venafi Control Plane, navigate to Policies in the left-hand menu.
  2. Click Firefly Sub CA Providers.
  3. Click New and select the appropriate CA provider (e.g., Venafi Built-In CA).
  4. Enable the Require HSM option.
  5. Enter the Partition Label and PIN details.
  6. (Optional) Provide the Partition Serial Number if the HSM has more than one partition with the same label.
  7. (Optional) Provide the checksums of the client libraries that Firefly is allowed to use.

Testing

To validate the configuration, start Firefly and check the logs for entries indicating successful connection and key generation using the HSM.

# Example command to start Firefly with the configured yaml file
firefly-pkcs11 run --config /path/to/your/config.yaml

NOTE

Because the signing private key is HSM-protected, there's a much lower risk associated with the Firefly process' memory being paged out to disk. If the remaining risk is acceptable, you can add the --disable-mlock parameter to the command line to allow memory paging.

Look for a log entry similar to the following:

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

This confirms that Firefly is using the HSM for key operations.