Skip to main content

Configure Luna hardware security module access

Connect Hyperledger Besu to a Luna hardware security module (HSM) to use the node's keys stored on the device.


The Luna HSM plugin can only be used to store the node's public and private key file. The plugin cannot be used to store transaction signing keys.


  • The Luna client software and Luna HSM must be configured before configuring Hyperledger Besu access.

Set the environment variables that specify the location of the Luna HSM library and Chrystoki.conf file if not located in the default locations. For example:

export LD_LIBRARY_PATH=/home/myuser/luna-hsm/elab/jsp/lib/
export ChrystokiConfigurationPath=/home/myuser/luna-hsm/
  • The nodes private and public keys have been created in the HSM.

Configure Hyperledger Besu

  1. Copy the Luna client's LunaProvider.jar file into the plugins directory.


    The plugins directory is located in the pegasys-plus-<release> directory when installed from a packaged binary.

  2. Create a plain text file containing the password to access the HSM. Ensure the password is located on the first line of the file.

  3. Start Hyperledger Besu:

    besu --security-module=luna-hsm \
    --plugin-luna-hsm-private-key-alias="node1PrivateKey" \
    --plugin-luna-hsm-public-key-alias="node1PublicKey" \
    --plugin-luna-hsm-slot=0 \
    --plugin-luna-hsm-password-file=./password.txt \
    --metrics-enabled --metrics-category=JVM,RPC,LUNA_HSM

    The command line:

    The `LUNA_HSM` metric's category allows you to monitor the Hyperledger Besu and Luna HSM
    connection. The category is not enabled by default.