wolfhsm-src 0.2.0

Compile wolfHSM from source for use by wolfhsm-sys
docs.rs failed to build wolfhsm-src-0.2.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

wolfhsm-src

Build-script crate that compiles wolfHSM from C source as part of a Cargo build. Used internally by wolfhsm-sys; has no public Rust API.

Why

Cargo cannot compile C libraries on behalf of an arbitrary crate — each crate that links a C library needs a build.rs that drives the C compiler. Splitting the C build into its own crate (the same pattern used by wolfssl-src and wolftpm-src in this workspace) keeps concerns separate:

  • wolfhsm-src owns the C build — it can be versioned and replaced without touching the FFI or the safe Rust API.
  • wolfhsm-sys owns the FFI boundary — bindgen runs there, consuming the DEP_WOLFHSM_SRC_* metadata emitted by this crate.
  • wolfhsm owns the safe Rust API.
  • links = "wolfhsm_src" prevents two copies of the wolfHSM static archive being linked into the same binary.

Usage

This crate is normally pulled in transitively via wolfhsm-sys or wolfhsm. Add one of those instead of depending on wolfhsm-src directly.

If you need to build a different FFI crate against the same wolfHSM build, declare wolfhsm-src as a regular [dependency] (not a [build-dependency]) so Cargo propagates the DEP_WOLFHSM_SRC_* metadata to your build script:

[dependencies]
wolfhsm-src = "0.1"

Supplying the wolfHSM source

Two ways to provide the wolfHSM C source tree:

Environment variable (recommended for development):

export WOLFHSM_SRC=/path/to/wolfHSM
cargo build -p wolfhsm-sys

Bundled submodule:

git submodule update --init wolfhsm-src/wolfhsm
cargo build -p wolfhsm-sys

The submodule tracks the upstream wolfSSL/wolfHSM main branch.

Supplying wolfSSL headers

wolfHSM uses wolfSSL/wolfCrypt for all cryptographic operations. Supply the headers via any of:

Variable Description
WOLFSSL_DIR Install prefix — headers at $WOLFSSL_DIR/include
WOLFSSL_INCLUDE_DIR Direct path to the wolfSSL include directory
WOLFSSL_SRC wolfSSL source tree root (vendored build)

The pre-built wolfSSL must have been compiled with WOLF_CRYPTO_CB enabled.

How it works

build.rs performs five steps:

  1. Locate wolfHSM source — checks WOLFHSM_SRC first, then falls back to the bundled git submodule at wolfhsm-src/wolfhsm/.
  2. Locate wolfSSL headers — checks WOLFSSL_INCLUDE_DIR, WOLFSSL_DIR, then WOLFSSL_SRC in that priority order (same as the rest of the workspace).
  3. Generate wolfhsm_cfg.h in OUT_DIR — wolfHSM's wh_settings.h unconditionally #includes wolfhsm_cfg.h. The generated file enables the POSIX time hook (WOLFHSM_CFG_PORT_GETTIME), client-side functionality (WOLFHSM_CFG_ENABLE_CLIENT), and CryptoCb support (WOLF_CRYPTO_CB). When the she Cargo feature is enabled it also defines WOLFHSM_CFG_SHE_EXTENSION.
  4. Compile wolfHSM — uses the cc crate to compile the client-side sources (wh_client.c, wh_client_crypto.c, wh_comm.c, message layer files, and more) together with the POSIX transport implementations (posix_transport_tcp.c, posix_transport_shm.c, posix_transport_uds.c) when present.
  5. Emit Cargo metadata — DEP_WOLFHSM_SRC_INCLUDE (wolfHSM source root) and DEP_WOLFHSM_SRC_LIB (directory holding libwolfhsm.a and wolfhsm_cfg.h) for consumption by wolfhsm-sys.

Features

Feature Description
she Enable SHE (Secure Hardware Extension) AutoSAR automotive key management — defines WOLFHSM_CFG_SHE_EXTENSION in the generated wolfhsm_cfg.h. Requires WOLFSSL_AES_DIRECT and HAVE_AES_ECB in the linked wolfSSL.

References

Copyright

Copyright (C) 2006-2026 wolfSSL Inc.

wolfHSM is copyright wolfSSL Inc. and its contributors.

License

GPL-3.0-only OR LicenseRef-wolfSSL-commercial.

The underlying wolfHSM C library is licensed under GPL-3.0-or-later with a commercial option available from wolfSSL Inc.