This module allows to use a Nitrokey NetHSM as a backend for PKCS#11 operations.

See the list of supported features for more details.

Download the latest binary from the release page.

Follow the documentation for usage instructions.

nethsm-pkcs11 is compatible with these NetHSM versions:

Full compatibility means that all features of the NetHSM PKCS#11 module can be used with this version. Limited compatibility means that only some features are available for this version. See the changelog for more detailed information on the version requirements for new features.

Set the RUST_LOG env variable to trace, debug, info, warn or err to change the logging level.

For testing and development purposes there are two examples using the PKCS11 driver with Nginx and Apache.

They require each a certificate built with the container/<server>/generate.sh.

They can be built with:

# Building the images 
docker build -t nginx-testing -f container/nginx/Dockerfile .
docker build -t apache-testing -f container/apache/Dockerfile .

Assuming that a NetHSM is runnig on localhost:8443, they can then be run with :

docker run --net=host nginx-testing:latest
docker run --net=host apache-testing:latest

The NetHSM is expected to have be provisionned with the following configuration:

nitropy nethsm --host localhost:8443 --no-verify-tls provision -u 0123456789 -a Administrator
nitropy nethsm --host localhost:8443 --no-verify-tls add-user -n Operator -u operator -p opPassphrase -r Operator

There is a set of tests that run with multiple instances and test the retry and timeout mechanisms. They require: access to sudo (or being run as root) and podman. You can run the command:

USE_SUDO=true cargo t -p nethsm_pkcs11 --test basic -- multi_instance_retries
# Or remove the use of sudo if running as root
cargo t -p nethsm_pkcs11 --test basic -- multi_instance_retries

Required are gcc and a working Rust toolchain of at least version (MSRV) 1.70.

cargo build --release

The dynamic library will be in ${CARGO_TARGET_DIR:-target}/release/libnethsm_pkcs11.so.

You need to install musl-dev and gcc:

apk add musl-dev gcc

To build on Alpine Linux you will need to add the C argument target-feature=-crt-static:

RUSTFLAGS="-C target-feature=-crt-static" cargo build --release