Merge pull request #1799 from safing/fix/kext-doc

[kext] Fix dev build documentation

windows_kext/README.md

@@ -1,7 +1,7 @@
 # Portmaster Windows kext
 Implementation of Safing's Portmaster Windows kernel extension in Rust.
 
-### Documentation 
+### Documentation
 
 - [Driver](driver/README.md) -> entry point.
 - [WDK](wdk/README.md) -> Windows Driver Kit interface.
@@ -9,8 +9,11 @@ Implementation of Safing's Portmaster Windows kernel extension in Rust.
 - [Release](release/README.md) -> Guide how to do a release build.
 - [Windows Filtering Platform - MS](https://learn.microsoft.com/en-us/windows-hardware/drivers/network/roadmap-for-developing-wfp-callout-drivers) -> The driver is build on top of WFP.
 
+### Building (For release)
 
-### Building
+Please refer to [release/README.md](release/README.md) for details about the release procedure.
+
+### Building (For testing and development)
 
 The Windows Portmaster Kernel Extension is currently only developed and tested for the amd64 (64-bit) architecture.
 
@@ -53,23 +56,18 @@ __Build driver:__
 
 ```sh
     cd driver
-    cargo build
+    cargo build --release
 ```
 > Build also works on linux
 
 __Link and sign:__
-On a windows machine copy `driver.lib` form the project target directory (`driver/target/x86_64-pc-windows-msvc/debug/driver.lib`) in the same folder as `link.bat`.
+On a windows machine copy `driver.lib` from the project target directory (`driver/target/x86_64-pc-windows-msvc/release/driver.lib`) in the same folder as `link-dev.ps1`.
-Run `link.bat`.
+Run `link-dev.ps1`.
 
-`driver.sys` should appear in the folder. Load and use the driver.
+`driver.sys` should appear in the folder.
 
-### Test
+Sign the driver with the test certificate:
-- Install go
-    - https://go.dev/dl/
-
-```sh
-    cd kext_tester
-    go run .
 ```
-
+  SignTool sign /v /s TestCertStoreName /n TestCertName driver.sys
-> make sure the hardcoded path in main.go is pointing to the correct `.sys` file
+```
+Load and use the driver.

windows_kext/link-dev.ps1

@@ -0,0 +1,21 @@
+# Example script for creating debug builds. Libraries may change depending on the version of the WDK that is installed.
+
+$SDK_Version = "10.0.26100.0"
+
+link.exe /OUT:driver.sys `
+/MANIFEST:NO /PROFILE /Driver `
+"C:\Program Files (x86)\Windows Kits\10\lib\$SDK_Version\km\x64\wdmsec.lib" `
+"C:\Program Files (x86)\Windows Kits\10\lib\$SDK_Version\km\x64\ndis.lib" `
+"C:\Program Files (x86)\Windows Kits\10\lib\$SDK_Version\km\x64\fwpkclnt.lib" `
+"C:\Program Files (x86)\Windows Kits\10\lib\$SDK_Version\km\x64\BufferOverflowK.lib" `
+"C:\Program Files (x86)\Windows Kits\10\lib\$SDK_Version\km\x64\ntoskrnl.lib" `
+"C:\Program Files (x86)\Windows Kits\10\lib\$SDK_Version\km\x64\hal.lib" `
+"C:\Program Files (x86)\Windows Kits\10\lib\$SDK_Version\km\x64\wmilib.lib" `
+"C:\Program Files (x86)\Windows Kits\10\lib\wdf\kmdf\x64\1.15\WdfLdr.lib" `
+"C:\Program Files (x86)\Windows Kits\10\lib\wdf\kmdf\x64\1.15\WdfDriverEntry.lib" `
+ "driver.lib" `
+/RELEASE /VERSION:"10.0" /DEBUG /MACHINE:X64 /ENTRY:"FxDriverEntry" /OPT:REF /INCREMENTAL:NO /SUBSYSTEM:NATIVE",6.01" /OPT:ICF /ERRORREPORT:PROMPT /MERGE:"_TEXT=.text;_PAGE=PAGE" /NOLOGO /NODEFAULTLIB /SECTION:"INIT,d"
+
+if(!$?) {
+    Exit $LASTEXITCODE
+}

windows_kext/release/README.md

@@ -1,25 +1,31 @@
 # Kext release tool
 
-### Generate the zip file
+## Generate the zip file
+
+- Make sure the deriver version in `kextinterface/version.txt` is up to date
 
-- Make sure `kextinterface/version.txt` is up to date
 - Execute: `cargo run`  
-  * This will generate release `kext_release_vX-X-X.zip` file. Which contains all the necessary files to make the release.  
+  _This will generate release `portmaster-kext-release-bundle-vX-X-X-X.zip` file. Which contains all the necessary files to make the release._
 
-### Generate the cab file
+## Generate the cab file
 
-- Copy the zip and extract it on a windows machine.
+  **Precondition:** Visual Studio 2022 and WDK need to be installed.
-  * Visual Studio 2022 and WDK need to be installed.
-- From VS Command Prompt / PowerShell run:
-```
-cd kext_release_v.../
-./build_cab.bat
-```
-> Script is written for VS `$SDK_Version = "10.0.22621.0"`. If different version is used update the script.
 
-- Sing the cab file
+- copy the zip and extract it on a windows machine.
 
-### Let Microsoft Sign
+- update `.\build_cab.ps1`: set correct SDK version you use.
+  _e.g.: $SDK_Version = "10.0.26100.0" (see in `C:\Program Files (x86)\Windows Kits\10\Lib`)_
+
+- Use "Developer PowerShell for VS":
+
+  ```powershell
+  cd portmaster-kext-release-bundle-v...
+  .\build_cab.ps1
+  ```
+
+- Sing the the output cab file: `portmaster-kext-release-bundle-v...\PortmasterKext_v....cab`
+
+## Let Microsoft Sign
 
 - Go to https://partner.microsoft.com/en-us/dashboard/hardware/driver/New
 - Enter "PortmasterKext vX.X.X #1" as the product name

windows_kext/release/src/main.rs

@@ -10,13 +10,17 @@ static LIB_PATH: &'static str = "./build/x86_64-pc-windows-msvc/release/driver.l
 
 fn main() {
     build_driver();
-    println!(
+
-        "Building kext v{}-{}-{} #{}",
+    let filename = format!(
+        "portmaster-kext-release-bundle-v{}-{}-{}-{}.zip",
         VERSION[0], VERSION[1], VERSION[2], VERSION[3]
     );
 
+    println!("Building KEXT: {}", filename);
+
     // Create Zip that will hold all the release files and scripts.
-    let file = File::create("portmaster-kext-release-bundle.zip").unwrap();
+    let file = File::create(&filename).unwrap();
+
     let mut zip = zip::ZipWriter::new(file);
 
     // Write files to zip

windows_kext/release/templates/build_cab.ps1

@@ -1,7 +1,7 @@
 # Remove previous cab build
 Remove-Item -Path "PortmasterKext_v2-0-0.cab" -ErrorAction SilentlyContinue
 
-$SDK_Version = "10.0.22621.0"
+$SDK_Version = "10.0.26100.0"
 
 # Build metadata file
 rc -I "C:\Program Files (x86)\Windows Kits\10\Include\$SDK_Version\um" `