From 145f5e67dee8f49cd7ac8170610fdc3ee3f1033c Mon Sep 17 00:00:00 2001
From: Vladimir Stoilov <vladimir@safing.io>
Date: Mon, 28 Oct 2024 08:35:02 +0200
Subject: [PATCH] [windows_kext] Improve documentation (#1719)
---
windows_kext/README.md | 46 ++++++++++++++++++---------------
windows_kext/protocol/README.md | 39 ++++++++++++++++++++++++++++
windows_kext/release/README.md | 5 ++--
3 files changed, 67 insertions(+), 23 deletions(-)
diff --git a/windows_kext/README.md b/windows_kext/README.md
index f77de347..ce80d0b1 100644
--- a/windows_kext/README.md
+++ b/windows_kext/README.md
@@ -5,51 +5,55 @@ Implementation of Safing's Portmaster Windows kernel extension in Rust.
- [Driver](driver/README.md) -> entry point.
- [WDK](wdk/README.md) -> Windows Driver Kit interface.
-- [Packet Path](PacketDoc.md) -> Detiled documentation of what happens to a packet when it enters the kernel extension.
-- [Release](release/README.md) -> Guide how to do a release build
+- [Packet Path](PacketFlow.md) -> Detailed documentation of what happens to a packet when it enters the kernel extension.
+- [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
The Windows Portmaster Kernel Extension is currently only developed and tested for the amd64 (64-bit) architecture.
-__Prerequesites:__
+__Prerequirements:__
- Visual Studio 2022
- Install C++ and Windows 11 SDK (22H2) components
- Add `link.exe` and `signtool` in the PATH
-- Rust
+- Windows Driver Kit
+ - https://learn.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk
+- Rust (Can be separate machine)
- https://www.rust-lang.org/tools/install
-- Cargo make(optional)
- - https://github.com/sagiegurari/cargo-make
__Setup Test Signing:__
-In order to test the driver on your machine, you will have to test sign it (starting with Windows 10).
+> Not recommended for a work machine. Usually done on virtual machine dedicated for testing.
+In order to test the driver on your machine, you will have to sign it (starting with Windows 10).
Create a new certificate for test signing:
- :: Open a *x64 Free Build Environment* console as Administrator.
+```ps1
+ # Open a *x64 Free Build Environment* console as Administrator.
- :: Run the MakeCert.exe tool to create a test certificate:
+ # Run the MakeCert.exe tool to create a test certificate:
MakeCert -r -pe -ss PrivateCertStore -n "CN=DriverCertificate" DriverCertificate.cer
- :: Install the test certificate with CertMgr.exe:
+ # Install the test certificate with CertMgr.exe:
CertMgr /add DriverCertificate.cer /s /r localMachine root
-
+```
Enable Test Signing on the dev machine:
-
- :: Before you can load test-signed drivers, you must enable Windows test mode. To do this, run this command:
+```ps1
+ # Before you can load test-signed drivers, you must enable Windows test mode. To do this, run this command:
Bcdedit.exe -set TESTSIGNING ON
- :: Then, restart Windows. For more information, see The TESTSIGNING Boot Configuration Option.
-
+ # Then, restart Windows. For more information, see The TESTSIGNING Boot Configuration Option.
+```
__Build driver:__
-```
-cd driver
-cargo build
+```sh
+ cd driver
+ cargo build
```
> Build also works on linux
@@ -63,9 +67,9 @@ Run `link.bat`.
- Install go
- https://go.dev/dl/
-```
-cd kext_tester
-go run .
+```sh
+ cd kext_tester
+ go run .
```
> make sure the hardcoded path in main.go is pointing to the correct `.sys` file
diff --git a/windows_kext/protocol/README.md b/windows_kext/protocol/README.md
index cde5d85c..2547f988 100644
--- a/windows_kext/protocol/README.md
+++ b/windows_kext/protocol/README.md
@@ -2,3 +2,42 @@
Defines protocol that communicates with `kextinterface` / Portmaster.
+The crate implements simple binary protocol. The communications is designed to be concurrent stream of packets.
+Input and output work independent of each other.
+ - Pormtaster can read multiple info packets from the queue with single read request.
+ - Portmaster can write one command packet to the kernel extension with single write request.
+
+## Info: Kext -> Portmaster
+
+Info is a packet that sends information/events from the kernel extension to portmaster.
+For example: `new connection`, `end of connection`, `bandwidth stats` ... check `info.rs` for full list.
+
+The Info packet contains a header that is 5 bytes
+```
+0 1 2 3 4
+0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| Info Type | Length |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+> Note that one tick mark represents one bit position.
+
+The header is followed by the info data.
+
+
+## Command: Portmaster -> Kext
+
+Command is a packet that portmaster sends to the kernel extension.
+For example: `verdict response`, `shutdown`, `get logs` ... check `command.rs` for full list.
+
+The header of the command packet is 1 byte
+```
+0 1 2 3 4 5 6 7
++-+-+-+-+-+-+-+-+
+| Command Type |
++-+-+-+-+-+-+-+-+
+```
+> Note that one tick mark represents one bit position.
+
+Rest of the packet will be the payload of the command (some commands don't contain payload just the command type).
+
diff --git a/windows_kext/release/README.md b/windows_kext/release/README.md
index 939f88d6..28898c9d 100644
--- a/windows_kext/release/README.md
+++ b/windows_kext/release/README.md
@@ -7,12 +7,13 @@
### Generate the cab file
- Copy the zip and extract it on a windows machine.
- * Some version Visual Studio needs 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.
3. Sing the cab file
@@ -25,4 +26,4 @@ cd kext_release_v.../
- Wait for the process to finish, download the `.zip`.
The zip will contain the release files.
-> Optionally sign the .sys file.
+> Optionally sign the .sys file, with company certificate.