[windows_kext] Improve documentation (#1719)

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

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).
+

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.