From 4907ae8421a5ba248b7dc22772ce6b311fed12e0 Mon Sep 17 00:00:00 2001 From: Vladimir Stoilov Date: Fri, 18 Oct 2024 18:11:17 +0300 Subject: [PATCH] [windows_kext] Improve documentation --- windows_kext/README.md | 32 +++++++++++++++------------ windows_kext/protocol/README.md | 39 +++++++++++++++++++++++++++++++++ windows_kext/release/README.md | 5 +++-- 3 files changed, 60 insertions(+), 16 deletions(-) diff --git a/windows_kext/README.md b/windows_kext/README.md index f77de3479..282a1c4a6 100644 --- a/windows_kext/README.md +++ b/windows_kext/README.md @@ -5,45 +5,49 @@ 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. +- [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. +```ps + # 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: +```ps + # 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:__ diff --git a/windows_kext/protocol/README.md b/windows_kext/protocol/README.md index cde5d85c9..2547f9882 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 939f88d6e..28898c9d1 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.