From 32d6e1cb045860f3194c097547eaf6482b83c0d9 Mon Sep 17 00:00:00 2001 From: Vladimir Stoilov 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 ce80d0b15..0e4daa80b 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`. - -`driver.sys` should appear in the folder. Load and use the driver. +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`. -### Test -- Install go - - https://go.dev/dl/ +`driver.sys` should appear in the folder. -```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 000000000..39ba4e3d3 --- /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 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 0e4daa80b..4d2628b9e 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 319bbd2ce..d9e7692a3 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 + + **Precondition:** Visual Studio 2022 and WDK need to be installed. + +- copy the zip and extract it on a windows machine. + +- 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`)_ -### Generate the cab file +- Use "Developer PowerShell for VS": -- 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. + ```powershell + cd portmaster-kext-release-bundle-v... + .\build_cab.ps1 + ``` -- Sing the cab file +- Sing the the output cab file: `portmaster-kext-release-bundle-v...\PortmasterKext_v....cab` -### Let Microsoft Sign +## 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 b956322f3..81bf1e812 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 aefce0487..802a4103d 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" `