Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/usmansaleem/besu-pkcs11-plugin
A Besu security module plugin showcasing PKCS11 with SoftHSM
https://github.com/usmansaleem/besu-pkcs11-plugin
besu besu-plugin blockchain ethereum java
Last synced: about 1 month ago
JSON representation
A Besu security module plugin showcasing PKCS11 with SoftHSM
- Host: GitHub
- URL: https://github.com/usmansaleem/besu-pkcs11-plugin
- Owner: usmansaleem
- License: apache-2.0
- Created: 2024-06-13T03:10:28.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2024-08-20T06:05:12.000Z (5 months ago)
- Last Synced: 2024-10-14T00:40:59.747Z (3 months ago)
- Topics: besu, besu-plugin, blockchain, ethereum, java
- Language: Java
- Homepage:
- Size: 76.2 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE-2.0
Awesome Lists containing this project
README
# Besu Plugin - PKCS11 SoftHSM
A [Besu plugin][1] that provides a custom security module to load the [node key][2] from an HSM, such as [SoftHSM][3],
using PKCS11 libraries.
[1]:
[2]:
[3]:
## Build Instructions
You can either use pre-built jar from Assets section in [releases](https://github.com/usmansaleem/besu-pkcs11-plugin/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](https://github.com/hyperledger/besu/releases) for latest stable version and update it in
[`gradle/libs.versions.toml`](gradle/libs.versions.toml). For example:
```toml
[versions]
besu = "24.8.0"
```
- Build the plugin:
```shell
./gradlew clean build
```
The plugin jar will be available at `build/libs/besu-pkcs11-plugin-.jar`.
## Usage
Drop the `besu-pkcs11-plugin-.jar` in the `/plugins` folder under Besu installation. This plugin will expose
following additional cli options:
```shell
--plugin-pkcs11-hsm-config-path=
Path to the PKCS11 configuration file
--plugin-pkcs11-hsm-key-alias=
Alias or label of the private key that is stored in the HSM
--plugin-pkcs11-hsm-password-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:
```shell
--security-module=pkcs11-hsm
```
## Docker setup
- The plugin can be tested as a docker image. The provided [`Dockerfile`](./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`](./docker/scripts/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](https://besu.hyperledger.org/public-networks/get-started/install/run-docker-image) for
further details about other docker options required to run Besu.
- See the sample [Besu config file](./docker/volumes/config) that defines minimal options required to use the plugin.
- Following is an example to build the docker image:
```shell
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:
```shell
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](LICENSE-APACHE-2.0) or )
* MIT license ([LICENSE-MIT](LICENSE-MIT) or )
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.