Besu Plugin - PKCS11 SoftHSM

A Besu plugin that provides a custom security module to load the node key from an HSM, such as SoftHSM, using PKCS11 libraries.

GitHub Release

Build Instructions

You can either use pre-built jar from Assets section in releases or build it yourself.

[!NOTE] This project requires Java 21 or later. If it is not available, the gradle build will attempt to download one and use it.

Check Besu releases for latest stable version and update it in gradle/libs.versions.toml. For example:

[versions]
besu = "24.8.0"

Build the plugin:

./gradlew clean build

The plugin jar will be available at build/libs/besu-pkcs11-plugin-<version>.jar.

Usage

Drop the besu-pkcs11-plugin-<version>.jar in the /plugins folder under Besu installation. This plugin will expose following additional cli options:

--plugin-pkcs11-hsm-config-path=<path>
                             Path to the PKCS11 configuration file
--plugin-pkcs11-hsm-key-alias=<label>
                             Alias or label of the private key that is stored in the HSM
--plugin-pkcs11-hsm-password-path=<path>
                             Path to the file that contains password or PIN to access PKCS11 token

The security module provided by this plugin can be loaded with following cli option:

--security-module=pkcs11-hsm

Docker setup

The plugin can be tested as a docker image. The provided Dockerfile is based on Besu's official docker image. It installs following additional package to manage SECP256K1 private keys and SoftHSM:

apt-get install -y --no-install-recommends \
    openssl \
    libssl3 \
    softhsm2 \
    opensc \
    gnutls-bin

The Dockerfile uses a custom script entrypoint.sh as entrypoint. This script initializes SoftHSM and generates a private key if required.
The Dockerfile copies the plugin jar to /plugins folder.
See Besu documentation for further details about other docker options required to run Besu.
See the sample Besu config file that defines minimal options required to use the plugin.
Following is an example to build the docker image:
```
docker build --no-cache -t besu-pkcs11:latest .
```
To run Besu node for testing with SoftHSM, Following directories be mounted as volumes. Change the path according to your requirements:
- ./docker/volumes/data for Besu data. It should be mounted to /var/lib/besu
- ./docker/volumes/tokens for SoftHSM data. It should be mounted to /var/lib/tokens
- ./docker/volumes/config for Besu and PKCS11 config files. It MUST be mounted to /etc/besu/config. This directory contains the sample configurations.

[!NOTE] To initialize the SoftHSM tokens, the entrypoint script will attempt to generate a SECP256K1 private key and initialize SoftHSM on the first run. The SoftHSM PIN is defined in ./docker/volumes/config/pkcs11-hsm-password.txt. The SO_PIN can be overridden via environment variable, however, it is not required once initialization is done.

To run the Besu node:

docker run --rm -it \
-v ./docker/volumes/data:/var/lib/besu \
-v ./docker/volumes/tokens:/var/lib/tokens \
-v ./docker/volumes/config:/etc/besu/config \
besu-pkcs11:latest --config-file=/etc/besu/config/besu-dev.toml

License

Licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option. SPDX-License-Identifier: (Apache-2.0 OR MIT)

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

usmansaleem / besu-pkcs11-plugin