Crate smolder_core

Expand description

Protocol and transport primitives for Smolder.

The published package name is smolder-smb-core, while the Rust library crate name remains smolder_core.

§Feature Flags

The supported cargo features are:

kerberos: stable public Kerberos API plus the current password-backed backend
kerberos-sspi: backend-only flag for the current password-backed Kerberos implementation
kerberos-gssapi: Unix ticket-cache and keytab backend using system GSS/Kerberos libraries
quic: feature-gated SMB over QUIC transport primitives

The default build enables none of these features and stays the most static-friendly profile. kerberos-gssapi is intentionally independent from kerberos-sspi, so enabling Unix GSS credential-store support does not also pull in the SSPI backend.

It owns SMB auth/session state, request dispatch, and transport logic. High-level SMB file facades, execution flows, and other operator workflows belong in the smolder package, not this crate.

This crate is the reusable library layer for:

SMB negotiate, session setup, signing, and encryption
NTLM/SPNEGO authentication primitives, with optional Kerberos support
Tree/file operations, compound dispatch, and credit-aware request flow
DFS referral helpers
Named-pipe and DCE/RPC transport on top of SMB
Durable/reconnect and resiliency primitives

The most common imports are re-exported in prelude.

§Usage model

Use smolder_core when you want typed SMB/RPC client primitives or the new embedded-client facade in facade. If you want operator-facing workflows such as smbexec and psexec, use the smolder package instead.

§Start here

The fastest supported entry points are:

cargo run -p smolder-smb-core --example client_session_connect
cargo run -p smolder-smb-core --example client_share_list
cargo run -p smolder-smb-core --example client_file_roundtrip
cargo run -p smolder-smb-core --example ntlm_tree_connect
cargo run -p smolder-smb-core --example named_pipe_rpc_bind
cargo run -p smolder-smb-core --features kerberos --example kerberos_tree_connect
cargo run -p smolder-smb-core --features quic --example client_quic_session_connect

Supporting project docs:

§Public API Tiers

The intended entry points for most consumers are:

facade::Client and facade::ClientBuilder for embedded client usage
facade::Session, facade::Share, facade::File, and facade::OpenOptions for authenticated-session, share, and file flows
client::Connection plus its typestate markers for negotiate, session, tree, and file operations
pipe::SmbSessionConfig, pipe::connect_tree, and pipe::NamedPipe for IPC$ and named-pipe transport
rpc::PipeRpcClient for reusable DCE/RPC over SMB named pipes
auth credential/authenticator types and error::CoreError
transport::SmbTransport or transport::Transport when embedding the client over a custom transport

Lower-level signing, preauth, and raw crypto helpers remain available for expert users, but they are not the recommended starting surface. The repo’s API audit notes are in https://github.com/M00NLIG7/smolder/blob/main/docs/reference/smolder-core-api.md.

Modules§

auth: Authentication providers and protocol helpers.
client: Typestate SMB client built on top of wire-level packet codecs.
compression: SMB 3.1.1 compression helpers.
crypto: SMB cryptographic key-derivation helpers.
dfs: DFS-aware UNC parsing and referral resolution helpers.
error: Errors returned by the core client/session layer.
facade: High-level embedded client facade built on top of the typestate SMB client.
lsarpc: Typed lsarpc DCE/RPC helpers built on top of named pipes.
pipe: Reusable IPC$ and named-pipe primitives built on top of the typestate client.
prelude: Curated imports for the intended smolder_core entry points.
rpc: Reusable DCE/RPC transport primitives built on top of named pipes.
samr: Typed samr DCE/RPC helpers built on top of named pipes.
srvsvc: Typed srvsvc DCE/RPC helpers built on top of named pipes.
transport: Async transports used by the SMB client.