smolder_core/
lib.rs

1//! Protocol and transport primitives for Smolder.
2//!
3//! The published package name is `smolder-smb-core`, while the Rust library
4//! crate name remains `smolder_core`.
5//!
6//! # Feature Flags
7//!
8//! The supported cargo features are:
9//!
10//! - `kerberos`: stable public Kerberos API plus the current password-backed
11//!   backend
12//! - `kerberos-sspi`: backend-only flag for the current password-backed
13//!   Kerberos implementation
14//! - `kerberos-gssapi`: Unix ticket-cache and keytab backend using system
15//!   GSS/Kerberos libraries
16//!
17//! The default build enables none of these features and stays the most
18//! static-friendly profile. `kerberos-gssapi` is intentionally independent from
19//! `kerberos-sspi`, so enabling Unix GSS credential-store support does not also
20//! pull in the SSPI backend.
21//!
22//! It owns SMB auth/session state, request dispatch, and transport logic.
23//! High-level SMB file facades, execution flows, and other operator workflows
24//! belong in the `smolder` package, not this crate.
25//!
26//! This crate is the reusable library layer for:
27//!
28//! - SMB negotiate, session setup, signing, and encryption
29//! - NTLM/SPNEGO authentication primitives, with optional Kerberos support
30//! - Tree/file operations, compound dispatch, and credit-aware request flow
31//! - DFS referral helpers
32//! - Named-pipe and DCE/RPC transport on top of SMB
33//! - Durable/reconnect and resiliency primitives
34//!
35//! The most common imports are re-exported in [`prelude`].
36//!
37//! # Usage model
38//!
39//! Use `smolder_core` when you want typed SMB/RPC client primitives and are
40//! comfortable orchestrating the protocol yourself. If you want a higher-level
41//! share/file API or operator-facing workflows such as `smbexec` and `psexec`,
42//! use the `smolder` package instead.
43//!
44//! # Start here
45//!
46//! The fastest supported entry points are:
47//!
48//! - `cargo run -p smolder-smb-core --example ntlm_tree_connect`
49//! - `cargo run -p smolder-smb-core --example named_pipe_rpc_bind`
50//! - `cargo run -p smolder-smb-core --features kerberos --example kerberos_tree_connect`
51//!
52//! Supporting project docs:
53//!
54//! - [docs/guide/examples.md](/Users/cmagana/Projects/smolder/docs/guide/examples.md)
55//! - [docs/guide/cookbook.md](/Users/cmagana/Projects/smolder/docs/guide/cookbook.md)
56//! - [docs/reference/support-policy.md](/Users/cmagana/Projects/smolder/docs/reference/support-policy.md)
57//! - [docs/reference/versioning-policy.md](/Users/cmagana/Projects/smolder/docs/reference/versioning-policy.md)
58//!
59//! # Public API Tiers
60//!
61//! The intended entry points for most consumers are:
62//!
63//! - [`client::Connection`] plus its typestate markers for negotiate, session,
64//!   tree, and file operations
65//! - [`pipe::SmbSessionConfig`], [`pipe::connect_tree`], and
66//!   [`pipe::NamedPipe`] for `IPC$` and named-pipe transport
67//! - [`rpc::PipeRpcClient`] for reusable DCE/RPC over SMB named pipes
68//! - [`auth`] credential/authenticator types and [`error::CoreError`]
69//! - [`transport::Transport`] when embedding the client over a custom transport
70//!
71//! Lower-level signing, preauth, and raw crypto helpers remain available for
72//! expert users, but they are not the recommended starting surface. The repo's
73//! API audit notes are in
74//! [docs/reference/smolder-core-api.md](/Users/cmagana/Projects/smolder/docs/reference/smolder-core-api.md).
75//!
76//! Copyright (c) 2025 M00NLIG7
77
78#![cfg_attr(docsrs, feature(doc_cfg))]
79#![forbid(unsafe_code)]
80#![warn(missing_docs)]
81
82pub mod auth;
83pub mod client;
84pub mod crypto;
85pub mod dfs;
86pub mod error;
87pub mod pipe;
88pub mod rpc;
89pub mod prelude {
90    //! Curated imports for the intended `smolder_core` entry points.
91    //!
92    //! Prefer this module when you want the supported high-level primitives
93    //! without pulling in every expert-only module directly.
94
95    pub use crate::auth::{
96        AuthProvider, NtlmAuthenticator, NtlmCredentials, NtlmRpcPacketIntegrity,
97        NtlmSessionSecurity,
98    };
99    #[cfg(feature = "kerberos-api")]
100    #[cfg_attr(
101        docsrs,
102        doc(cfg(any(feature = "kerberos", feature = "kerberos-gssapi")))
103    )]
104    pub use crate::auth::{
105        KerberosAuthenticator, KerberosBackendKind, KerberosCredentialSourceKind,
106        KerberosCredentials, KerberosTarget,
107    };
108    pub use crate::client::{
109        Authenticated, CompoundRequest, CompoundResponse, Connected, Connection, DurableHandle,
110        DurableOpenOptions, Negotiated, ResilientHandle, TreeConnected,
111    };
112    pub use crate::crypto::{derive_encryption_keys, EncryptionKeys};
113    pub use crate::dfs::{resolve_unc_path, DfsReferral, UncPath};
114    pub use crate::error::CoreError;
115    pub use crate::pipe::{connect_tree, NamedPipe, PipeAccess, SmbSessionConfig};
116    pub use crate::rpc::PipeRpcClient;
117    pub use crate::transport::{TokioTcpTransport, Transport};
118}
119
120pub mod transport;
smolder_core/lib.rs

smolder_core/
lib.rs
