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 }