Craton HSM

NXP HSE Backend

NXP HSE Backend

The craton-hsm-nxp crate implements the CryptoBackend trait for NXP's Hardware Security Engine (HSE) firmware running on S32G / S32R / S32K3 automotive SoCs. Cryptographic requests are dispatched through the Messaging Unit (MU) to the HSE core, which holds all key material in hardware.

  • Crate: craton-hsm-nxp
  • Backend type: NxpHseBackend
  • License: BSL 1.1
  • MSRV: Rust 1.75
  • Status: pre-release (stub build is stable; hw feature not yet validated end-to-end against production HSE firmware)

Hardware Support

  • NXP S32G274A (GoldBox)
  • NXP S32G399A
  • NXP S32K344 / S32K358

Other S32 family parts with compatible HSE firmware may work but have not been exercised. Legacy S32G1 / legacy S32K parts are unsupported.

Feature Flag

FlagDefaultEffect
hwoffEnable real HSE hardware calls via the Messaging Unit.

Stub vs. Hardware Modes

Without the hw feature (the default build) this backend is a stub. Every CryptoBackend method returns HsmError::FunctionNotSupported, and the constructor emits a tracing::warn! on first use. The runtime helper NxpHseBackend::is_stub() reports the build mode.

The default stub behaviour is deliberate: accidentally depending on this crate without configuring hardware fails loudly rather than silently falling back to software crypto.

With --features hw and the NXP HSE SDK linked in, the same API dispatches crypto calls to the HSE core through the vendor FFI.

use craton_hsm_nxp::NxpHseBackend;
use craton_hsm::crypto::backend::CryptoBackend;

// Default build — stub; every op returns FunctionNotSupported.
let backend = NxpHseBackend::new();
assert!(NxpHseBackend::is_stub());

// With --features hw and the NXP HSE SDK available, the same code
// dispatches crypto calls to the HSE core via the Messaging Unit.

Hardware Build

Add the feature to your Cargo.toml:

[dependencies]
craton-hsm-nxp = { path = "../craton-hsm-nxp", features = ["hw"] }

Obtain the NXP HSE SDK for your target (distributed by NXP under separate NDA / license terms — not bundled with this repository). Build the host library libhse.a or libhse.so following NXP's instructions, then point the Rust build at it:

export HSE_SDK_ROOT=/path/to/nxp-hse-sdk
export HSE_LIB_DIR=$HSE_SDK_ROOT/lib

cargo build -p craton-hsm-nxp --features hw

Cross-compiling to S32G (ARM Cortex-A53)

rustup target add aarch64-unknown-linux-gnu

export CC_aarch64_unknown_linux_gnu=aarch64-linux-gnu-gcc

cargo build -p craton-hsm-nxp --features hw \
    --target aarch64-unknown-linux-gnu

Target OS

Typically an RTOS (AUTOSAR, FreeRTOS) or Linux running on the Cortex-A / Cortex-M cores of the target SoC.

Safety

The default stub build is #![deny(unsafe_code)] at the crate root. Under --features hw the unsafe FFI is scoped to the ffi submodule, which binds to the vendor SDK's own FFI layer.

Security Considerations

  • Under hw, all key material is held in the HSE hardware; nothing leaves the HSE core via this crate.
  • The default stub build is intentionally non-functional to prevent silent software fallback.
  • Ed25519 is not part of the HSE crypto menu on current-generation parts. Ed25519 operations return HsmError::MechanismInvalid under hw.

Error Reporting

Failures surface through craton_hsm::error::HsmError. NxpHseBackend::is_stub() distinguishes the build mode at runtime so callers can branch on whether hardware is actually present.

Limitations

  • Pre-release. The hw feature has not been validated end-to-end against production HSE firmware. Interfaces may change.
  • Vendor SDK required. The NXP HSE SDK is distributed under a separate NDA / license agreement with NXP. This crate does not bundle vendor headers or firmware.
  • Linux-only cross toolchain currently documented. RTOS targets are supported in principle; exact build recipes depend on your BSP / AUTOSAR integration.

Related Documents