From 32d6e1cb045860f3194c097547eaf6482b83c0d9 Mon Sep 17 00:00:00 2001
From: Vladimir Stoilov <github@pendsv.com>
Date: Tue, 28 Jan 2025 11:46:15 +0200
Subject: [PATCH 1/2] [kext] Fix dev build documentation
---
windows_kext/README.md | 26 ++++++++++----------------
windows_kext/link-dev.ps1 | 21 +++++++++++++++++++++
2 files changed, 31 insertions(+), 16 deletions(-)
create mode 100644 windows_kext/link-dev.ps1
diff --git a/windows_kext/README.md b/windows_kext/README.md
index ce80d0b1..0e4daa80 100644
--- a/windows_kext/README.md
+++ b/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,7 @@ 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
+### Building (For testing and development)
The Windows Portmaster Kernel Extension is currently only developed and tested for the amd64 (64-bit) architecture.
@@ -53,23 +52,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`.
-Run `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-dev.ps1`.
-`driver.sys` should appear in the folder. Load and use the driver.
+`driver.sys` should appear in the folder.
-### Test
-- Install go
- - https://go.dev/dl/
-
-```sh
- cd kext_tester
- go run .
+Sign the driver with the test certificate:
```
-
-> make sure the hardcoded path in main.go is pointing to the correct `.sys` file
+ SignTool sign /v /s TestCertStoreName /n TestCertName driver.sys
+```
+Load and use the driver.
diff --git a/windows_kext/link-dev.ps1 b/windows_kext/link-dev.ps1
new file mode 100644
index 00000000..39ba4e3d
--- /dev/null
+++ b/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
+}
From 857df4086f0ce448ed9e581b96b6e8abc768ebb6 Mon Sep 17 00:00:00 2001
From: Alexandr Stelnykovych <stenya@gmail.com>
Date: Tue, 28 Jan 2025 14:26:44 +0200
Subject: [PATCH 2/2] [kext] Fix dev build documentation (releasing procedure)
---
windows_kext/README.md | 4 +++
windows_kext/release/README.md | 34 ++++++++++++--------
windows_kext/release/src/main.rs | 10 ++++--
windows_kext/release/templates/build_cab.ps1 | 2 +-
4 files changed, 32 insertions(+), 18 deletions(-)
diff --git a/windows_kext/README.md b/windows_kext/README.md
index 0e4daa80..4d2628b9 100644
--- a/windows_kext/README.md
+++ b/windows_kext/README.md
@@ -9,6 +9,10 @@ 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)
+
+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.
diff --git a/windows_kext/release/README.md b/windows_kext/release/README.md
index 319bbd2c..d9e7692a 100644
--- a/windows_kext/release/README.md
+++ b/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.
- * 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.
+ **Precondition:** Visual Studio 2022 and WDK need to be installed.
-- 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
diff --git a/windows_kext/release/src/main.rs b/windows_kext/release/src/main.rs
index b956322f..81bf1e81 100644
--- a/windows_kext/release/src/main.rs
+++ b/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
diff --git a/windows_kext/release/templates/build_cab.ps1 b/windows_kext/release/templates/build_cab.ps1
index aefce048..802a4103 100644
--- a/windows_kext/release/templates/build_cab.ps1
+++ b/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" `