hsminer

hsminer is a Zig-based project designed to interact with a Hardware Security Module (HSM) using the PKCS#11 standard. It allows you to encrypt or decrypt text using cryptographic keys.

Building hsminer

Use Zig to build the project:

zig build

Running hsminer

Use Zig to build and run the project:

zig build run -- -c cert.pem -k key.pem /usr/lib/softhsm/libsofthsm2.so "${SLOT_ID}" "${PIN}"

or HSMiner binary directly:

./hsminer -c cert.pem -k key.pem /usr/lib/softhsm/libsofthsm2.so "${SLOT_ID}" "${PIN}"

Command Arguments:

-h, --help Display this help and exit.
-c, --cert Path to certificat file.
-k, --key Path to key file.
-p, --port Listening port.
Path to PKCS11 module.
Slot identifier.
Pin (4-255).

Enviroment

Make sure the following tools are installed on your system:

OpenSSL – for generating self-signed certificates.
SoftHSM – a software-based HSM that supports PKCS#11.
pkcs11-tool – a command-line utility to interact with PKCS#11 modules.
Zig – the programming language used to build and run this project.

Or build a docker image with:

docker build -t hsminer .

And run it with:

docker run -it --rm -p 3000:3000 -v "${PWD}":/hsminer -v "${PWD}"/tokens:/var/lib/softhsm/tokens -w /hsminer hsminer bash

Generating Certificate and Key

Before running hsminer, generate a self-signed certificate and a private key:

openssl req -x509 -nodes -days 365 -sha256 -newkey rsa:2048 -keyout key.pem -out cert.pem

This creates:

key.pem: the private key.
cert.pem: the matching self-signed certificate.

Initialize the Token

softhsm2-util --init-token --free --label "HSMiner" --so-pin "${PIN}" --pin "${PIN}"

Generate a Key

pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so --slot "${SLOT_ID}" --login --pin "${PIN}" --keygen --key-type aes:32 --label "key 1"

This command creates a 256-bit AES key with the label key 1 in the initialized slot.

Dependencies

README