wolfssl-src

Build-script crate that compiles wolfSSL from C source as part of a Cargo build. Used by wolfcrypt-sys when its vendored feature is enabled, modelled on the openssl-src / openssl-sys pattern.

Why

The three-crate split (wolfssl-src → wolfcrypt-sys → wolfcrypt-rs) separates concerns so each layer can change independently:

• wolfssl-src owns the C build; it can be versioned independently of the FFI or the safe Rust API.
• wolfcrypt-sys owns the FFI boundary and bindgen invocation.
• wolfcrypt-rs owns the safe Rust wrapper and re-exports build metadata.

Having the C build in its own crate means multiple crates in the same workspace (wolfcrypt-sys, wolftpm-sys, wolfhsm-sys) can share the compiled wolfSSL without recompiling it.

Usage

This crate is normally consumed transitively through wolfcrypt-sys:

[dependencies]
wolfcrypt-sys = { version = "0.1", features = ["vendored"] }

For direct use in your own build pipeline:

[dependencies]
wolfssl-src = "0.1"

// Build wolfSSL from source and report where the artefacts landed.
let artifacts = wolfssl_src::Build::new()
    .fips(false)              // pass true for FIPS 140-3 builds (commercial)
    .build();

println!("lib dir:      {}", artifacts.lib_dir.display());
println!("include dir:  {}", artifacts.include_dir.display());
println!("settings dir: {}", artifacts.settings_include_dir.display());

Artifacts exposes the static-archive directory, the wolfSSL header include path, the directory containing the active user_settings.h, and the parsed set of #define names from that settings file.

When using wolfssl-src from another crate's build.rs, declare it as a regular [dependency] (not a [build-dependency]) so Cargo propagates the DEP_WOLFSSL_SRC_* metadata to your build script.

Source resolution

Build::build() discovers the wolfSSL source tree in this priority order:

1. Build::source_dir(...) — explicit programmatic override.
2. WOLFSSL_SRC environment variable.
3. Bundled submodule at wolfssl-src/wolfssl/ (after git submodule update --init).
4. pkg-config — looks for a wolfssl package whose prefix contains source files.

FIPS 140-3

wolfCrypt is FIPS 140-3 validated. FIPS builds require:

• The specific wolfSSL source tree submitted for validation (not an arbitrary checkout) — supplied by wolfSSL Inc. under commercial license.
• A user_settings_fips.h configuration header in this crate's manifest directory.

Set Build::fips(true) to enable the FIPS code path. Contact wolfSSL for a commercial FIPS license and the validated source tree.

How it works

build.rs selects one of several pre-configured user_settings.h files based on Cargo features, then uses the cc crate to compile the wolfSSL source tree against that settings file. Feature precedence is cryptocb-pure > cryptocb-only > riscv-bare-metal > default (verified in src/lib.rs).

The compiled static library and include directory are exposed via Cargo metadata (DEP_WOLFSSL_SRC_*) so that downstream sys crates can link against them without re-running the C build.

References

• wolfcrypt-sys — primary consumer; the FFI binding layer
• wolfcrypt-rs — typed Rust wrapper above wolfcrypt-sys
• wolfhsm-src — sibling source-build crate for wolfHSM
• wolftpm-src — sibling source-build crate for wolfTPM
• wolfSSL repository
• wolfSSL documentation
• cc crate — C build dependency
• workspace README

Copyright

Copyright (C) 2006-2026 wolfSSL Inc.

License

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

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