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.

important

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.

Prerequisites

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

important

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.

   note

   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:

   • Enables the Luna HSM plugin using --security-module=luna-hsm.
   • Specifies the alias of the private key in the HSM using --plugin-luna-hsm-private-key-alias.
   • Specifies the alias of the public key in the HSM using --plugin-luna-hsm-public-key-alias.
   • Specifies the slot in which the keys are stored using --plugin-luna-hsm-slot.
   • Specifies the location of the password file created earlier using --plugin-luna-hsm-password-file.
   • Enables monitoring using --metrics-enabled.
   • Specifies the metrics categories to track using --metrics-category.
   note

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