11 releases (6 breaking)
0.7.0 | Apr 26, 2025 |
---|---|
0.6.0 | Apr 18, 2025 |
0.5.1 | Mar 31, 2025 |
0.4.3 | Mar 27, 2025 |
0.1.0 | Feb 7, 2025 |
#357 in Network programming
324 downloads per month
595KB
14K
SLoC
smb-rs: The SMB2 Client in Rust
This project is the first rust implementation of SMB2 & 3 client -- the protocol that powers Windows file sharing and remote services. The project is designed to be used as a crate, but also includes a CLI tool for basic operations.
While most current implementations are mostly bindings to C libraries (such as libsmb2, samba, or windows' own libraries), this project is a full implementation in Rust, with no dependencies on C libraries!
Getting started
Running the project is as simple as:
cargo run -- --help
Check out the info
and the copy
sub-commands for more information.
For advanced usage, and crate usage, see the Advanced Usage section.
Features
General
- ✅ SMB 2.X & 3.X support.
- ✅ Async (
tokio
)/Multi-threaded/Single-threaded client. - ✅ Compression & Encryption support.
- ✅ Supports SMB over TCP (445) & SMB over QUIC.
- ✅ NTLM & Kerberos authentication (using the
sspi
crate). - ✅ Cross-platform (Windows, Linux, MacOS).
You are welcome to see the project's roadmap in the GitHub Project.
Features
Type | Algorithm | Feature Name | |
---|---|---|---|
Authentication | Kerberos | ✅ | kerberos |
Transport | QUIC | ✅ | quic |
Signing | * | sign |
|
Signing | HMAC_SHA256 | ✅ | sign_hmac |
Signing | AES-128-GCM | ✅ | sign_gmac |
Signing | AES-128-CCM | ✅ | sign_cmac |
Encryption | * | encrypt |
|
Encryption | AES-128-CCM | ✅ | encrypt_aes128ccm |
Encryption | AES-128-GCM | ✅ | encrypt_aes128gcm |
Encryption | AES-256-CCM | ✅ | encrypt_aes256ccm |
Encryption | AES-256-GCM | ✅ | encrypt_aes256gcm |
Compression | * | compress |
|
Compression | LZ4 | ✅ | compress_lz4 |
Compression | Pattern_V1 | 🟡 | compress_pattern_v1 * |
Compression | LZNT1/LZ77/+Huffman | ❌ | - |
[!NOTE] Some of SMB's suported compression algorithms are missing, since no proper crates are available for them.
Advanced Usage
Using the crate
Check out the Client
struct, exported from the smb
crate, to initiate a connection to an SMB server:
let unc_path = smb::UncPath::from_str(r"\\server\share\\file.txt")?;
let smb = smb::Client::new(smb::ClientConfig::default());
smb.share_connect(&unc_path, "username", "password".to_string()).await?;
Opening a file for reading:
let file: smb::File = smb.create_file(&unc_path,
&FileCreateArgs::make_open_existing(
FileAccessMask::new().with_generic_read(true),
)).try_into()?;
// .. perform operations on the file
[!tip] Check out
smb-cli
's commands implementation for more examples of how to use the crate.
Switch Threading model
The project supports async, multi-threaded, and single-threaded backends. The async
backend is the default one, but you can enable the other backends by using the following features:
async
: Enables the async backend (default)single_threaded
: Enables the single-threaded backend. Must disable default features.multi_threaded
: Enables the multi-threaded backend. Must disable default features.
For example, to run the CLI using multi-threaded backend, you can run:
cargo run --no-default-feature --features "multi_threaded,sign,encrypt,compress" -- --help
If you're using the crate, you can enable the features in your Cargo.toml
file:
[dependencies]
smb = { version = "0.1", features = ["multi_threaded", "sign", ...], no-default-features = true }
Dependencies
~17–50MB
~787K SLoC