Document and format smb-msg (#157)

* Add more documentation to the smb-msg crate, and improve code
formatting.

* **Bug Fixes & Improvements**
  * Improved message structure parsing and validation
  * Better support for SMB2/SMB3 feature detection and negotiation

* **Chores**
  * Workspace reorganization with modular crate structure
  * Added safety constraints across crates

Author: afiffon

.github/ISSUE_TEMPLATE/bug_report.md

@@ -19,7 +19,7 @@ Contain a code snippet that uses the crate, and reproduces the bug.
 
 - If this is a runtime failure, please provide:
   - SMB server software and version (e.g. Samba 4.15.0 or Windows Server 2022)
-  - Authentication method, if relevant
+  - Authentication method, if relevant (ntlm/kerberos - domain environment?)
   - Custom configuration or used features, if relevant
 
 - Crate version: [e.g. 0.8.1]

.github/copilot-instructions.md

@@ -0,0 +1,19 @@
+# Utility for documenting structures based on MSDN specifications
+
+- When you document a structure, the *final* document you use should be official Microsoft documentation.
+
+- Structure documentation should include:
+  - A brief description of the structure's purpose.
+  - A reference to the page. Use the index of specifications (MS-SMB2 X.Y.Z...), do not put url parts.
+  - Field documentation should be brief and helpful, if any critical information is provided, include it.
+- Never include constant names or values in the documentation! especially bit shift flags, or arbitrary symbols.
+- Don't make up stuff! Always base documentation on official documentation.
+- Avoid documenting for the sake of documenting. If the documentation doesn't add value, don't add it. (e.g. don't just repeat the field name in the field documentation...).
+- Do not summarize or put again the instructions, that just makes me pay for more tokens.
+
+- If the structure is under the `smb-msg` crate, you can look up the documentation.
+  - Make sure that the documentation is MS-SMB2 2.* indexed - that's where structures are documented.
+  - Request the documentation page to be used, do not try to look it up yourself. It won't work!
+  - Do not simple document helper structures that are not part of the specification and/or produced by macros.
+  - This does NOT apply to enums that represent possible field values, for example, or bitfield structs - of course!
+  - NEVER document reserved fields.

.github/workflows/build.yml

@@ -59,19 +59,18 @@ jobs:
         run: |
           rustup component add clippy
           cargo clippy --verbose --no-default-features --features "${{ matrix.compile_features }},${COMMON_FEATURES}" -- -Dclippy::all
+      - name: Build/${{ matrix.compile_features }}
+        run: |
+          cargo build --no-default-features --features "${{ matrix.compile_features }},${COMMON_FEATURES}"
       - name: Tests/${{ matrix.compile_features }}
         run: |
-          cargo test -p smb-msg --features both -- --nocapture
+          cargo test -p smb-msg --features server --no-default-features -- --nocapture
+          cargo test -p smb-msg --features both --no-default-features -- --nocapture
+
+          # Full client tests with all features
           cargo test --no-default-features --features "${{ matrix.compile_features }},${COMMON_FEATURES}" -- --nocapture
-          # Test without encryption and compression
-          cargo test --no-default-features --features "${{ matrix.compile_features }},sign" -- --nocapture
-          # Test signing with specific algorithms
-          cargo test --no-default-features --features "${{ matrix.compile_features }},sign_cmac" -- --nocapture
-          cargo test --no-default-features --features "${{ matrix.compile_features }},sign_gmac" -- --nocapture
-          cargo test --no-default-features --features "${{ matrix.compile_features }},sign_hmac" -- --nocapture
-      - name: Build/${{ matrix.compile_features }}
+      - name: Doc/${{ matrix.compile_features }}
         run: |
-          cargo build --no-default-features --features "${{ matrix.compile_features }},${COMMON_FEATURES}"
           cargo doc --no-default-features --features "${{ matrix.compile_features }},${COMMON_FEATURES}"
 
   build:

Cargo.lock

@@ -1,5 +1,5 @@
 [workspace]
-members = ["crates/*"]
+members = ["crates/*", "smb-cli"]
 resolver = "2"
 
 [workspace.package]
@@ -16,6 +16,19 @@ readme = "README.md"
 version = "0.10.4"
 
 [workspace.dependencies]
+# Crates in this workspace
+smb = { path = "crates/smb", version = "0.10.4", default-features = false }
+smb-tests = { path = "crates/smb-tests", version = "0.10.4" }
+smb-msg = { path = "crates/smb-msg", version = "0.10.4", default-features = false, features = [
+    "client",
+] }
+smb-msg-derive = { path = "crates/smb-msg-derive", version = "0.10.4" }
+smb-dtyp = { path = "crates/smb-dtyp", version = "0.10.4" }
+smb-dtyp-derive = { path = "crates/smb-dtyp-derive", version = "0.10.4" }
+smb-rpc = { path = "crates/smb-rpc", version = "0.10.4" }
+smb-fscc = { path = "crates/smb-fscc", version = "0.10.4" }
+smb-transport = { path = "crates/smb-transport", version = "0.10.4", default-features = false }
+
 # Binary encoding/decoding
 binrw = "0.15.0"
 modular-bitfield = "0.11.2"

Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "smb-dtyp-derive"
+description = "Derive macros for smb-dtyp, and general smb* crates."
+readme = "README.md"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+authors.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[lib]
+proc-macro = true
+
+[dependencies]
+quote = "1"
+proc-macro2 = "1"
+syn = { version = "2", features = ["full"] }

crates/smb-dtyp-derive/Cargo.toml

@@ -0,0 +1,19 @@
+use proc_macro::TokenStream;
+
+/// A helper macro that invokes `modular_bitfield` and `binrw` derives for bitfield structs.
+/// Those must be installed as dependencies in the crate where this macro is used.
+///
+/// Adds derives for `Debug`, `Default`, `Clone`, `Copy`, `PartialEq`, and `Eq`.
+#[proc_macro_attribute]
+pub fn mbitfield(_attr: TokenStream, input: TokenStream) -> TokenStream {
+    let input = syn::parse_macro_input!(input as syn::ItemStruct);
+    quote::quote! {
+        #[::modular_bitfield::bitfield]
+        #[derive(::binrw::BinWrite, ::binrw::BinRead)]
+        #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+        #[bw(map = |&x| Self::into_bytes(x))]
+        #[br(map = Self::from_bytes)]
+        #input
+    }
+    .into()
+}

crates/smb-dtyp-derive/src/lib.rs

@@ -17,6 +17,7 @@ modular-bitfield = { workspace = true }
 time = { workspace = true }
 pastey = { workspace = true }
 rand = { workspace = true }
+smb-dtyp-derive = { workspace = true }
 
 [dev-dependencies]
-smb-tests = { path = "../smb-tests", version = "0.10.4" }
+smb-tests = { workspace = true }

crates/smb-dtyp/Cargo.toml

@@ -1,4 +1,4 @@
-//! [`Boolean`][crate::Boolean] implementation for binrw.
+//! [`Boolean`] implementation for binrw.
 
 use binrw::{Endian, prelude::*};
 use std::io::{Read, Seek, Write};

crates/smb-dtyp/src/binrw_util/boolean.rs

@@ -24,7 +24,7 @@ pub fn read_u48() -> binrw::BinResult<u64> {
 
 /// Utility binrw parser function that reads an optional value of type `T`
 /// if there is _ANY_ data left in the stream
-/// (any data, not enough data - for Option<u32> it's 1 byte in the stream).
+/// (any data, not enough data - even for [`Option<u32>`] it's 1 byte in the stream).
 #[binrw::parser(reader, endian)]
 pub fn binread_if_has_data<T>() -> BinResult<Option<T>>
 where