Installation

This page covers building Craton HSM from source, the artifacts the build produces, where to place the PKCS#11 library so that consumers can find it, and how to verify the build with a smoke test.

Prerequisites

Craton HSM is pure Rust. A working Rust toolchain is all that is strictly required for the core library; the gRPC daemon and the FIPS-validated backend pull in a few native tools.

Platform notes:

• Linux — confirmed on Debian 12, Ubuntu 22.04 / 24.04, Fedora 40, RHEL 9. libc 2.31+ recommended so that mlock behaves as expected.
• macOS — confirmed on macOS 13 and 14, both Apple Silicon and Intel.
• Windows — confirmed on Windows 10 and 11 with the MSVC toolchain; the module uses VirtualLock on this platform.

Platform bootstrap:

# Debian / Ubuntu
sudo apt-get install -y build-essential protobuf-compiler cmake

# Fedora / RHEL
sudo dnf install -y gcc gcc-c++ protobuf-compiler cmake

# macOS
brew install protobuf cmake

# Windows (PowerShell)
winget install Google.Protobuf Kitware.CMake

Build from source

git clone https://github.com/craton-co/craton-hsm-core.git
cd craton-hsm-core

# Core PKCS#11 library only
cargo build --release

# Library, daemon, admin CLI, spy wrapper
cargo build --release --workspace

The release profile enables LTO and symbol stripping. A full workspace build takes a few minutes on a modern laptop. Use --locked in CI to pin dependencies to the versions in Cargo.lock.

Build artifacts

cargo build --release --workspace writes the following binaries to target/release/:

The shared library is the surface that PKCS#11 consumers load via dlopen(3) or LoadLibrary. It has no runtime dependencies beyond libc / the CRT.

Placing the library

There is no OS-wide install step. Point your consumer directly at the build output, or copy the library to a stable location:

# Linux / macOS
sudo install -m 0755 target/release/libcraton_hsm.so /usr/local/lib/
sudo ldconfig

# macOS — common conventions
sudo install -m 0755 target/release/libcraton_hsm.dylib /usr/local/lib/

# Windows
Copy-Item target\release\craton_hsm.dll "C:\Program Files\Craton HSM\craton_hsm.dll"

Applications generally reference the library by absolute path (for example PKCS11_MODULE_PATH=/usr/local/lib/libcraton_hsm.so), so LD_LIBRARY_PATH tricks are rarely needed.

Installing the admin CLI

craton-admin is a standalone binary that drives token initialisation, PIN management, key browsing, audit export, and backups. Copy it to somewhere on PATH:

sudo install -m 0755 target/release/craton-admin /usr/local/bin/
craton-admin --help

On Windows, drop craton-admin.exe into a directory on PATH and verify:

craton-admin --help

The CLI reads the same craton_hsm.toml as the library and the daemon, so it must run in a directory where that file resolves (or under CRATON_HSM_CONFIG=/path/to/craton_hsm.toml).

Smoke test the build

Once the library and CLI are in place, verify that the module initialises and that its Power-On Self-Tests pass.

# 1. Confirm the library is loadable and POST passes.
pkcs11-tool --module /usr/local/lib/libcraton_hsm.so --show-info

Expected output shape:

Cryptoki version 3.0
Manufacturer     Craton Software
Library          Craton HSM (ver 0.9)
Using slot 0 with a present token (0x0)

# 2. List slots. A fresh install exposes one uninitialised slot.
pkcs11-tool --module /usr/local/lib/libcraton_hsm.so --list-slots

# 3. Run the test suite from the source tree. PKCS#11 keeps global state,
#    so the tests must run single-threaded.
cargo test --release -- --test-threads=1

A passing test run and a successful --show-info together confirm that:

• The binary links correctly.
• All 17 FIPS 140-3 Power-On Self-Tests (module integrity plus 16 KATs) pass on this host.
• Concurrency, session, persistence, and conformance suites all succeed.

Optional — release binaries and checksum verification

Signed release binaries are published for tagged versions. Prefer them over source builds when you need a reproducible artifact to ship to production or submit for audit.

For each release the project publishes:

• Platform archives (*.tar.gz for Linux and macOS, *.zip for Windows).
• A SHA256SUMS file listing the checksum of every archive.
• A detached signature over SHA256SUMS (GPG, and optionally cosign / Authenticode).

Verify a download before using it:

# Verify the signature on the checksum manifest.
gpg --verify SHA256SUMS.asc SHA256SUMS

# Verify the archive against the manifest.
sha256sum --check --ignore-missing SHA256SUMS

The published signing keys, verification commands for cosign and Authenticode, and the rotation schedule are documented in Release signing.

Next steps

• Quickstart — initialise a token and sign your first payload in under five minutes.
• First token — a deeper walkthrough of the slot/token model and PIN lifecycle.
• Configuration reference — all craton_hsm.toml fields and defaults.