From d94a7680397494a2c3b09533b873861f2a59c25d Mon Sep 17 00:00:00 2001
From: Usman Saleem <usman@usmans.info>
Date: Tue, 9 Jul 2024 16:41:13 +1000
Subject: [PATCH 1/3] feat: Dockerfile to test the plugin

---
 .dockerignore                                 | 10 +++
 .gitignore                                    |  4 +
 Dockerfile                                    | 44 ++++++++++
 README.md                                     | 53 +++++++++--
 docker/clean_volumes.sh                       |  3 +
 docker/scripts/entrypoint.sh                  | 88 +++++++++++++++++++
 docker/volumes/config/besu-dev.toml           | 19 ++++
 docker/volumes/config/pkcs11-hsm-password.txt |  1 +
 docker/volumes/config/pkcs11-softhsm.cfg      | 11 +++
 .../besu/plugin/softhsm/Pkcs11HsmPlugin.java  | 17 ++--
 .../softhsm/Pkcs11PluginCliOptions.java       |  2 +-
 .../softhsm/Pkcs11SecurityModuleService.java  | 16 +++-
 12 files changed, 255 insertions(+), 13 deletions(-)
 create mode 100644 .dockerignore
 create mode 100644 Dockerfile
 create mode 100755 docker/clean_volumes.sh
 create mode 100644 docker/scripts/entrypoint.sh
 create mode 100644 docker/volumes/config/besu-dev.toml
 create mode 100644 docker/volumes/config/pkcs11-hsm-password.txt
 create mode 100644 docker/volumes/config/pkcs11-softhsm.cfg

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..e783d81
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,10 @@
+# Copyright 2024, Usman Saleem.
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+# Exclude everything
+*
+
+# Include specific files and directories needed for the build
+!docker/scripts/entrypoint.sh
+!Dockerfile
+!build/libs/
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index ab5e240..82718d3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,7 @@
 build
 
 .idea
+
+# Ignore data and tokens in volume directory
+docker/volumes/data
+docker/volumes/tokens
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..6c93d13
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,44 @@
+# syntax=docker/dockerfile:1
+# Copyright 2024, Usman Saleem.
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+# Start from the latest Hyperledger Besu image
+FROM hyperledger/besu:latest
+
+# Switch to root to install packages
+USER 0
+
+# Install additional packages for SoftHSM2 and OpenSC
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    openssl \
+    libssl3 \
+    softhsm2 \
+    opensc \
+    gnutls-bin && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Create a directory for SoftHSM2 tokens. This can be overridden using a volume mount to persist.
+RUN mkdir -p /var/lib/tokens && chmod 755 /var/lib/tokens && chown besu:besu /var/lib/tokens
+
+# Switch back to the besu user
+USER besu
+
+# Update workdir to Besu home directory
+WORKDIR /opt/besu
+
+# Set environment variables for SoftHSM2 configuration
+ENV SOFTHSM2_CONF=/opt/besu/softhsm2.conf
+
+# Copy the PKCS11 plugin JAR to the plugins directory
+COPY --chown=besu:besu ./build/libs/besu-pkcs11-plugin-*.jar ./plugins/
+
+# Copy the initialization script
+COPY --chown=besu:besu --chmod=755 ./docker/scripts/entrypoint.sh ./entrypoint.sh
+
+# Create a custom SoftHSM2 configuration file in besu home directory
+RUN echo "directories.tokendir = /var/lib/tokens" > ./softhsm2.conf
+
+# Set the entrypoint to our new script
+ENTRYPOINT ["/opt/besu/entrypoint.sh"]
\ No newline at end of file
diff --git a/README.md b/README.md
index 5846c0e..79d2d4f 100644
--- a/README.md
+++ b/README.md
@@ -37,14 +37,57 @@ The plugin jar will be available at `build/libs/besu-pkcs11-plugin-<version>.jar
 
 Drop the `besu-pkcs11-plugin-<version>.jar` in the `/plugins` folder under Besu installation. This plugin will expose 
 following additional cli options:
-`TBA`
+```shell
+--plugin-pkcs11-softhsm-config-path=<path>
+                             Path to the PKCS11 configuration file
+--plugin-pkcs11-softhsm-key-alias=<path>
+                             Alias or label of the private key that is stored in the HSM
+--plugin-pkcs11-softhsm-password-path=<path>
+                             Path to the file that contains password or PIN to access PKCS11 token
+```
 
-## Linux SoftHSM Setup
-Following steps are tested on Ubuntu 24.04 LTS. Install following packages.
-`TBA`
 
 ## Docker setup 
-See Dockerfile for details.
+- 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 `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.
+- To persist SoftHSM data, a volume should be mounted to `/softhsm2`. The host directory should have ownership of userid 1000:1000.
+- Decide the token/pin to use for SoftHSM.
+- See [Besu documentation](https://besu.hyperledger.org/public-networks/get-started/install/run-docker-image) for further details about other docker options.
+- 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. Will be mounted to `/var/lib/besu`
+    - `./docker/volumes/tokens` for SoftHSM data. Will be mounted to `/var/lib/tokens`
+    - `./docker/volumes/config` for Besu and PKCS11 config files. Will be mounted to `/etc/besu/config`. This directory already contains 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
 
diff --git a/docker/clean_volumes.sh b/docker/clean_volumes.sh
new file mode 100755
index 0000000..c26e96a
--- /dev/null
+++ b/docker/clean_volumes.sh
@@ -0,0 +1,3 @@
+#! /bin/sh
+rm -rf ./volumes/data
+rm -rf ./volumes/tokens
\ No newline at end of file
diff --git a/docker/scripts/entrypoint.sh b/docker/scripts/entrypoint.sh
new file mode 100644
index 0000000..7fa6f53
--- /dev/null
+++ b/docker/scripts/entrypoint.sh
@@ -0,0 +1,88 @@
+#!/bin/bash
+# Copyright 2024, Usman Saleem.
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+# Set default values for PIN and SO_PIN
+DEFAULT_PIN="test123"
+DEFAULT_SO_PIN="sotest123"
+
+# Path to the PIN file
+PIN_FILE="/etc/besu/config/pkcs11-hsm-password.txt"
+
+# Read PIN from file if it exists, otherwise use environment variable or default value
+if [ -f "$PIN_FILE" ]; then
+    PIN=$(cat "$PIN_FILE")
+else
+    PIN="${PIN:-$DEFAULT_PIN}"
+fi
+
+# Use environment variables if set, otherwise use default values
+SO_PIN="${SO_PIN:-$DEFAULT_SO_PIN}"
+
+# Set up cleanup trap
+trap 'rm -f /tmp/ec-secp256k1-*.pem' EXIT
+
+# Check if SoftHSM module exists
+SOFTHSM_MODULE="/usr/lib/softhsm/libsofthsm2.so"
+if [ ! -f "$SOFTHSM_MODULE" ]; then
+    echo "SoftHSM module not found: $SOFTHSM_MODULE"
+    exit 1
+fi
+
+# Check if token already exists
+if ! softhsm2-util --show-slots | grep -q "testtoken"; then
+    echo "Initializing SoftHSM token ..."
+    if ! softhsm2-util --init-token --slot 0 --label "testtoken" --pin "$PIN" --so-pin "$SO_PIN"; then
+        echo "Failed to initialize token"
+        exit 1
+    fi
+
+    echo "Generating SECP256K1 private key using openssl ..."
+    # Generating temporary SECP256K1 private key (-noout=not encoded)
+    if ! openssl ecparam -name secp256k1 -genkey -noout -out /tmp/ec-secp256k1-priv-key.pem; then
+        echo "Failed to generate private key"
+        exit 1
+    fi
+
+    # Generate public key from private key
+    if ! openssl ec -in /tmp/ec-secp256k1-priv-key.pem -pubout -out /tmp/ec-secp256k1-pub-key.pem; then
+        echo "Failed to generate public key"
+        exit 1
+    fi
+
+    # Generate a self-signed certificate
+    if ! openssl req -new -x509 -key /tmp/ec-secp256k1-priv-key.pem -out /tmp/ec-secp256k1-cert.pem -days 365 -subj '/CN=example.com'; then
+        echo "Failed to generate self-signed certificate"
+        exit 1
+    fi
+
+    echo "Importing openssl secp256k1 key into softhsm id: 1, label: testkey ..."
+    # Importing private key and cert in softhsm. Note we have to specify --usage-derive for ECDH key agreement to work
+    if ! pkcs11-tool --module "$SOFTHSM_MODULE" --login --pin "$PIN" \
+    --write-object /tmp/ec-secp256k1-priv-key.pem --type privkey --usage-derive --id 1 --label "testkey" \
+    --token-label "testtoken"; then
+        echo "Failed to import private key"
+        exit 1
+    fi
+
+    if ! pkcs11-tool --module "$SOFTHSM_MODULE" --login --pin "$PIN" \
+    --write-object /tmp/ec-secp256k1-pub-key.pem --type pubkey --usage-derive --id 1 --label "testkey" \
+    --token-label "testtoken"; then
+        echo "Failed to import public key"
+        exit 1
+    fi
+
+    if ! pkcs11-tool --module "$SOFTHSM_MODULE" --login --pin "$PIN" \
+    --write-object /tmp/ec-secp256k1-cert.pem --type cert --id 1 --label "testkey" \
+    --token-label "testtoken"; then
+        echo "Failed to import certificate"
+        exit 1
+    fi
+
+    echo "Token and keys initialized successfully."
+else
+    echo "Token already exists. Skipping initialization."
+fi
+
+# Launch Besu with the provided arguments
+exec besu "$@"
\ No newline at end of file
diff --git a/docker/volumes/config/besu-dev.toml b/docker/volumes/config/besu-dev.toml
new file mode 100644
index 0000000..7e87d87
--- /dev/null
+++ b/docker/volumes/config/besu-dev.toml
@@ -0,0 +1,19 @@
+network="dev"
+miner-enabled=true
+miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"
+rpc-http-cors-origins=["all"]
+host-allowlist=["*"]
+rpc-ws-enabled=true
+rpc-http-enabled=true
+data-path="/var/lib/besu"
+
+# plugins options
+plugin-pkcs11-hsm-config-path="/etc/besu/config/pkcs11-softhsm.cfg"
+plugin-pkcs11-hsm-key-alias="testkey"
+plugin-pkcs11-hsm-password-path="/etc/besu/config/pkcs11-hsm-password.txt"
+
+# security module
+security-module="pkcs11-hsm"
+
+# Logging
+logging="DEBUG"
\ No newline at end of file
diff --git a/docker/volumes/config/pkcs11-hsm-password.txt b/docker/volumes/config/pkcs11-hsm-password.txt
new file mode 100644
index 0000000..274c005
--- /dev/null
+++ b/docker/volumes/config/pkcs11-hsm-password.txt
@@ -0,0 +1 @@
+1234
\ No newline at end of file
diff --git a/docker/volumes/config/pkcs11-softhsm.cfg b/docker/volumes/config/pkcs11-softhsm.cfg
new file mode 100644
index 0000000..a4e620f
--- /dev/null
+++ b/docker/volumes/config/pkcs11-softhsm.cfg
@@ -0,0 +1,11 @@
+name = Softhsm-Besu-SM
+library = /usr/lib/softhsm/libsofthsm2.so
+# Instead of slot = xxx, use slotListIndex
+slotListIndex = 0
+showInfo = false
+
+# In order for ECDHA Key Agreement to work, we need following for derived secrets
+attributes(generate,CKO_SECRET_KEY,CKK_GENERIC_SECRET) = {
+  CKA_SENSITIVE = false
+  CKA_EXTRACTABLE = true
+}
\ No newline at end of file
diff --git a/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11HsmPlugin.java b/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11HsmPlugin.java
index 18f095f..599c5d8 100644
--- a/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11HsmPlugin.java
+++ b/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11HsmPlugin.java
@@ -7,6 +7,7 @@
 import org.hyperledger.besu.plugin.BesuPlugin;
 import org.hyperledger.besu.plugin.services.PicoCLIOptions;
 import org.hyperledger.besu.plugin.services.SecurityModuleService;
+import org.hyperledger.besu.plugin.services.securitymodule.SecurityModule;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -48,11 +49,17 @@ private void registerCliOptions(final BesuContext besuContext) {
    */
   private void registerSecurityModule(final BesuContext besuContext) {
     // lazy-init our security module implementation during register phase
-    besuContext
-        .getService(SecurityModuleService.class)
-        .orElseThrow(
-            () -> new IllegalStateException("Expecting SecurityModuleService to be present"))
-        .register(SECURITY_MODULE_NAME, () -> new Pkcs11SecurityModuleService(cliParams));
+    final SecurityModuleService securityModuleService =
+        besuContext
+            .getService(SecurityModuleService.class)
+            .orElseThrow(
+                () -> new IllegalStateException("Expecting SecurityModuleService to be present"));
+
+    securityModuleService.register(SECURITY_MODULE_NAME, this::getSecurityModuleSupplier);
+  }
+
+  private SecurityModule getSecurityModuleSupplier() {
+    return new Pkcs11SecurityModuleService(cliParams);
   }
 
   @Override
diff --git a/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11PluginCliOptions.java b/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11PluginCliOptions.java
index d616716..6b05464 100644
--- a/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11PluginCliOptions.java
+++ b/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11PluginCliOptions.java
@@ -27,7 +27,7 @@ public class Pkcs11PluginCliOptions {
       names = "--plugin-" + SECURITY_MODULE_NAME + "-key-alias",
       description = "Alias or label of the private key that is stored in the HSM",
       required = true,
-      paramLabel = "<path>")
+      paramLabel = "<label>")
   private String privateKeyAlias;
 
   /** Default constructor. Performs no initialization. */
diff --git a/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11SecurityModuleService.java b/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11SecurityModuleService.java
index 75bc3d8..83fcc11 100644
--- a/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11SecurityModuleService.java
+++ b/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11SecurityModuleService.java
@@ -60,10 +60,22 @@ private void loadPkcs11Provider() {
     LOG.info("Initializing PKCS11 provider ...");
 
     try {
-      provider =
-          Security.getProvider("SUNPKCS11").configure(cliParams.getPkcs11ConfigPath().toString());
+      final Provider sunPKCS11Provider = Security.getProvider("SunPKCS11");
+      if (sunPKCS11Provider == null) {
+        throw new SecurityModuleException("SunPKCS11 provider not found");
+      }
+      // configure the provider with the PKCS11 configuration file
+      provider = sunPKCS11Provider.configure(cliParams.getPkcs11ConfigPath().toString());
+      if (provider == null) {
+        throw new SecurityModuleException("Unable to configure SunPKCS11 provider");
+      }
+      // finally add configured provider.
       Security.addProvider(provider);
     } catch (final Exception e) {
+      if (e instanceof SecurityModuleException) {
+        throw (SecurityModuleException) e;
+      }
+
       throw new SecurityModuleException(
           "Error encountered while loading SunPKCS11 provider with configuration: "
               + cliParams.getPkcs11ConfigPath().toString(),

From 34caa4e4afe3bf6c40eb4d80dbb99926c1d18c17 Mon Sep 17 00:00:00 2001
From: Usman Saleem <usman@usmans.info>
Date: Tue, 9 Jul 2024 17:47:15 +1000
Subject: [PATCH 2/3] Use constant for SECP256K1 curve

---
 .../softhsm/Pkcs11SecurityModuleService.java  | 13 ++++---
 .../usmans/besu/plugin/softhsm/SECP256K1.java | 29 +++++++++++++++
 .../besu/plugin/softhsm/SignatureUtil.java    | 35 ++++++++++++++-----
 3 files changed, 62 insertions(+), 15 deletions(-)
 create mode 100644 src/main/java/info/usmans/besu/plugin/softhsm/SECP256K1.java

diff --git a/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11SecurityModuleService.java b/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11SecurityModuleService.java
index 83fcc11..92ff5ee 100644
--- a/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11SecurityModuleService.java
+++ b/src/main/java/info/usmans/besu/plugin/softhsm/Pkcs11SecurityModuleService.java
@@ -13,7 +13,6 @@
 import java.security.Security;
 import java.security.cert.Certificate;
 import java.security.interfaces.ECPublicKey;
-import java.security.spec.ECParameterSpec;
 import javax.crypto.KeyAgreement;
 import org.apache.tuweni.bytes.Bytes32;
 import org.hyperledger.besu.plugin.services.securitymodule.SecurityModule;
@@ -26,12 +25,14 @@
 /** A PKCS11 based implementation of Besu SecurityModule interface. */
 public class Pkcs11SecurityModuleService implements SecurityModule {
   private static final Logger LOG = LoggerFactory.getLogger(Pkcs11SecurityModuleService.class);
+  private static final String SIGNATURE_ALGORITHM = "NONEWithECDSA";
+  private static final String KEY_AGREEMENT_ALGORITHM = "ECDH";
+
   private final Pkcs11PluginCliOptions cliParams;
   private Provider provider;
   private KeyStore keyStore;
   private PrivateKey privateKey;
   private ECPublicKey ecPublicKey;
-  private ECParameterSpec secp256k1Param;
 
   public Pkcs11SecurityModuleService(final Pkcs11PluginCliOptions cliParams) {
     LOG.debug("Creating Pkcs11SecurityModuleService ...");
@@ -148,8 +149,6 @@ private void loadPkcs11PublicKey() {
           "Public Key is not a valid ECPublicKey for alias: " + cliParams.getPrivateKeyAlias());
     }
     ecPublicKey = (ECPublicKey) publicKey;
-    // we could use a constant, for now we will get it from the public key
-    secp256k1Param = ecPublicKey.getParams();
   }
 
   @Override
@@ -158,7 +157,7 @@ public Signature sign(Bytes32 dataHash) throws SecurityModuleException {
       // Java classes generate ASN1 encoded signature,
       // Besu needs P1363 i.e. R and S of the signature
       final java.security.Signature signature =
-          java.security.Signature.getInstance("SHA256WithECDSA", provider);
+          java.security.Signature.getInstance(SIGNATURE_ALGORITHM, provider);
       signature.initSign(privateKey);
       signature.update(dataHash.toArray());
       final byte[] sigBytes = signature.sign();
@@ -181,11 +180,11 @@ public Bytes32 calculateECDHKeyAgreement(PublicKey theirKey) throws SecurityModu
     LOG.debug("Calculating ECDH key agreement ...");
     // convert Besu PublicKey (which wraps ECPoint) to java.security.PublicKey
     java.security.PublicKey theirPublicKey =
-        SignatureUtil.eCPointToPublicKey(theirKey.getW(), secp256k1Param, provider);
+        SignatureUtil.eCPointToPublicKey(theirKey.getW(), provider);
 
     // generate ECDH Key Agreement
     try {
-      final KeyAgreement keyAgreement = KeyAgreement.getInstance("ECDH", provider);
+      final KeyAgreement keyAgreement = KeyAgreement.getInstance(KEY_AGREEMENT_ALGORITHM, provider);
       keyAgreement.init(privateKey);
       keyAgreement.doPhase(theirPublicKey, true);
       return Bytes32.wrap(keyAgreement.generateSecret());
diff --git a/src/main/java/info/usmans/besu/plugin/softhsm/SECP256K1.java b/src/main/java/info/usmans/besu/plugin/softhsm/SECP256K1.java
new file mode 100644
index 0000000..5cbe0d8
--- /dev/null
+++ b/src/main/java/info/usmans/besu/plugin/softhsm/SECP256K1.java
@@ -0,0 +1,29 @@
+// Copyright 2024, Usman Saleem.
+// SPDX-License-Identifier: (Apache-2.0 OR MIT)
+package info.usmans.besu.plugin.softhsm;
+
+import java.security.spec.ECParameterSpec;
+import org.bouncycastle.asn1.sec.SECNamedCurves;
+import org.bouncycastle.asn1.x9.X9ECParameters;
+import org.bouncycastle.crypto.params.ECDomainParameters;
+import org.bouncycastle.jce.spec.ECNamedCurveSpec;
+
+/** Constants for the SECP256K1 curve. */
+public class SECP256K1 {
+
+  public static final ECParameterSpec SECP256K1_PARAM_SPEC;
+
+  static {
+    // Get the named curve parameters
+    X9ECParameters params = SECNamedCurves.getByName("secp256k1");
+
+    // Create the ECDomainParameters
+    ECDomainParameters ecParams =
+        new ECDomainParameters(params.getCurve(), params.getG(), params.getN(), params.getH());
+
+    // Create the ECParameterSpec
+    SECP256K1_PARAM_SPEC =
+        new ECNamedCurveSpec(
+            "secp256k1", ecParams.getCurve(), ecParams.getG(), ecParams.getN(), ecParams.getH());
+  }
+}
diff --git a/src/main/java/info/usmans/besu/plugin/softhsm/SignatureUtil.java b/src/main/java/info/usmans/besu/plugin/softhsm/SignatureUtil.java
index 135fdce..4aec45b 100644
--- a/src/main/java/info/usmans/besu/plugin/softhsm/SignatureUtil.java
+++ b/src/main/java/info/usmans/besu/plugin/softhsm/SignatureUtil.java
@@ -7,7 +7,6 @@
 import java.security.NoSuchAlgorithmException;
 import java.security.Provider;
 import java.security.PublicKey;
-import java.security.spec.ECParameterSpec;
 import java.security.spec.ECPoint;
 import java.security.spec.ECPublicKeySpec;
 import java.security.spec.InvalidKeySpecException;
@@ -20,6 +19,10 @@
 
 /** Helper class to provide signature utility methods. */
 public class SignatureUtil {
+  private static final BigInteger SECP_256K1_CURVE_ORDER =
+      new BigInteger("FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141", 16);
+  private static final BigInteger HALF_CURVE_ORDER = SECP_256K1_CURVE_ORDER.shiftRight(1);
+
   /**
    * Uses Bouncycastle to decode DER signature. A DER signature format is SEQUENCE := {r INTEGER, s
    * INTEGER}
@@ -37,29 +40,45 @@ public static Signature extractRAndSFromDERSignature(final byte[] der) {
       final ASN1Integer r = (ASN1Integer) seq.getObjectAt(0);
       final ASN1Integer s = (ASN1Integer) seq.getObjectAt(1);
 
-      return new SignatureImpl(r.getPositiveValue(), s.getPositiveValue());
+      return canonicalizeSignature(r.getPositiveValue(), s.getPositiveValue());
     } catch (final Exception e) {
       throw new SecurityModuleException(e);
     }
   }
 
+  private static SignatureImpl canonicalizeSignature(final BigInteger r, final BigInteger s) {
+    // Check if R is within the valid range
+    if (r.signum() <= 0 || r.compareTo(SECP_256K1_CURVE_ORDER) >= 0) {
+      throw new SecurityModuleException("Invalid signature: R is out of range");
+    }
+
+    // Check if S is in the upper half of the curve order
+    // If S is in the upper half, subtract it from the curve order
+    final BigInteger sCopy =
+        s.compareTo(HALF_CURVE_ORDER) > 0 ? SECP_256K1_CURVE_ORDER.subtract(s) : s;
+
+    // Final check to ensure S is still in the valid range after canonicalization
+    if (sCopy.signum() <= 0 || sCopy.compareTo(SECP_256K1_CURVE_ORDER) >= 0) {
+      throw new SecurityModuleException(
+          "Invalid signature: S is out of range after canonicalization");
+    }
+
+    return new SignatureImpl(r, sCopy);
+  }
+
   /**
    * Converts ECPoint to PublicKey using PKCS11 provider.
    *
    * @param theirECPoint ECPoint of other party
-   * @param secp256k1ParamSpec SECP256K1 parameter spec
    * @param pkcs11Provider PKCS11 provider
    * @return PublicKey of other party generated from ECPoint
    * @throws SecurityModuleException wrapping cause of original exception =
    */
   public static PublicKey eCPointToPublicKey(
-      final ECPoint theirECPoint,
-      final ECParameterSpec secp256k1ParamSpec,
-      final Provider pkcs11Provider)
-      throws SecurityModuleException {
+      final ECPoint theirECPoint, final Provider pkcs11Provider) throws SecurityModuleException {
     try {
       return KeyFactory.getInstance("EC", pkcs11Provider)
-          .generatePublic(new ECPublicKeySpec(theirECPoint, secp256k1ParamSpec));
+          .generatePublic(new ECPublicKeySpec(theirECPoint, SECP256K1.SECP256K1_PARAM_SPEC));
     } catch (InvalidKeySpecException | NoSuchElementException | NoSuchAlgorithmException e) {
       throw new SecurityModuleException("Unexpected error converting ECPoint to PublicKey", e);
     }

From 1e920b796813dc9c3f12c4bcc80c3ae5d1d366b4 Mon Sep 17 00:00:00 2001
From: Usman Saleem <usman@usmans.info>
Date: Tue, 9 Jul 2024 18:01:08 +1000
Subject: [PATCH 3/3] cleanup docs

---
 README.md | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 79d2d4f..1ec150a 100644
--- a/README.md
+++ b/README.md
@@ -38,17 +38,21 @@ The plugin jar will be available at `build/libs/besu-pkcs11-plugin-<version>.jar
 Drop the `besu-pkcs11-plugin-<version>.jar` in the `/plugins` folder under Besu installation. This plugin will expose 
 following additional cli options:
 ```shell
---plugin-pkcs11-softhsm-config-path=<path>
+--plugin-pkcs11-hsm-config-path=<path>
                              Path to the PKCS11 configuration file
---plugin-pkcs11-softhsm-key-alias=<path>
+--plugin-pkcs11-hsm-key-alias=<label>
                              Alias or label of the private key that is stored in the HSM
---plugin-pkcs11-softhsm-password-path=<path>
+--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:
+```shell
+--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.
+- 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:
 
 ```
@@ -59,21 +63,21 @@ apt-get install -y --no-install-recommends \
     opensc \
     gnutls-bin
 ```
-- The Dockerfile uses `scripts/entrypoint.sh` as entrypoint. This script initializes SoftHSM and generates a private key 
-if required.
+- 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.
-- To persist SoftHSM data, a volume should be mounted to `/softhsm2`. The host directory should have ownership of userid 1000:1000.
-- Decide the token/pin to use for SoftHSM.
-- See [Besu documentation](https://besu.hyperledger.org/public-networks/get-started/install/run-docker-image) for further details about other docker options.
+- 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. Will be mounted to `/var/lib/besu`
-    - `./docker/volumes/tokens` for SoftHSM data. Will be mounted to `/var/lib/tokens`
-    - `./docker/volumes/config` for Besu and PKCS11 config files. Will be mounted to `/etc/besu/config`. This directory already contains sample configurations.
+    - `./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