# Win32 Kernel Chronicles: Building and Debugging a Windows Driver.
Alright internet, welcome to another blog post. As the title suggests, we're going to delve into building a Windows Driver. I want to make a quick disclaimer that there are multiple blog posts, videos, and resources for getting started with Windows Driver Development. This post just represents my take on the process, updated for 2023/2024 -- and *hopefully* a spring board into more advance topics down the road. I've recently transitioned from Full Stack Development to Windows Kernel Engineering, and this blog series will serve as a guide for that learning journey. The field of kernel development is 'quite niche', so if you find this post helpful, I'm glad to be of assistance!
## Prerequisites
If you hope to follow along with this article, we will need to set up a '***virtual development lab.***'
💡
A 'virtual development lab' is a requirement for kernel development. Why? Well, due to the nature of the Operating Systems Kernel, a logical/runtime error in our code will almost certainly result in a blue-screen-of-death (BSOD). Additionally, having a virtual computer also allows us to set breakpoints and effectively debug the driver.
*LeTs StArt CoOkiNg*, these will be our ingredients:
* A 64bit CPU architecture
* [Visual Studio Community Edition](https://visualstudio.microsoft.com/vs/community/)
* [Windows Software Development Kit](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/) (Windows SDK)
* [Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk) (Windows WDK)
* Virtualization software (I'll be using [VirtualBox](https://www.virtualbox.org/))
* [Windows 11 ISO](https://www.microsoft.com/software-download/windows11)
* [OSRLoader](https://www.osronline.com/article.cfm%5Earticle=157.htm)
### Lab Setup
Our lab will consist of two virtual machines. **A Development Machine** and **A Testing Machine**. Theoretically, you could get away with having 'only a testing machine' -- but by having a dedicated development machine, we'll be able to remotely debug over a virtual network. Below Are Screenshots of my Virtual Machine Configuration.
![](https://cdn.hashnode.com/res/hashnode/image/upload/v1699670229484/e0f88ebd-0562-4d7c-bc5d-f51dab79eef9.png align="center")
![](https://cdn.hashnode.com/res/hashnode/image/upload/v1699670275599/86f3f615-9b3a-4cd0-b955-65a535cc4783.png align="center")
### Lab Networking
After you successfully get two virtual machines up and running, configure a NAT Network for the machines to talk to each other over. In Virtual box this can be done by through the following:
![Create a new NAT Network](https://cdn.hashnode.com/res/hashnode/image/upload/v1699670480946/b76da037-0568-490b-bc44-7e4ec101963e.png align="center")
1. Create a new NAT Network
![](https://cdn.hashnode.com/res/hashnode/image/upload/v1699670679870/55d860ef-34be-4f1b-ad72-21e1b50acd98.png align="center")
1. Attach both the Developer and Testing machine's network interface to the created NAT Network.
2. Use the `ipconfig /all` command in `cmd.exe` to record your machine IP addresses. My configuration was as follows:
* NAT Network subnet: `10.0.2.0/24`
* **Developer Machine IP:** `10.0.2.15`
* **Testing Machine IP:** `10.0.2.4`
3. Verify your machines can ping each other.
```plaintext
C:\Users\starcoding>ping 10.0.2.4
Pinging 10.0.2.4 with 32 bytes of data:
Reply from 10.0.2.4: bytes=32 time=1ms TTL=128
Reply from 10.0.2.4: bytes=32 time=1ms TTL=128
Reply from 10.0.2.4: bytes=32 time=2ms TTL=128
Reply from 10.0.2.4: bytes=32 time=2ms TTL=128
Ping statistics for 10.0.2.4:
Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
Minimum = 1ms, Maximum = 2ms, Average = 1ms
C:\Users\starcoding>
```
### **Developer Machine Setup**
Nice! We now have some machines that can communicate with one another. Phew, yes... one of the most tedious parts about the Driver Development Process is how long it can take to get a lab successfully configured. With this, we will now install the software required to commence development! Recall from the prerequisite section the following:
* [Visual Studio Community Edition](https://visualstudio.microsoft.com/vs/community/)
* [Windows Software Development Kit](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/) (Windows SDK)
* [Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk) (Windows WDK)
Within the Visual Studio Installer, Install `Desktop Development with C++` and the Individual Components:
* `MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)`
* `MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest)`
![](https://cdn.hashnode.com/res/hashnode/image/upload/v1699674278312/2bd15151-ff88-40d7-bea0-d761615c765b.png align="center")
💡
For those curious MSVC stands for 'Microsoft Visual C++'. It comes with a suite of tools for compiling and developing C and C++ code on Windows Machines. It includes with a compiler cl.exe , a linker link.exe , a debugger, an automation build tool nmake and much more!
### **Testing Machine Setup (IMPORTANT!)**
**Boot Configuration Data**
For the test machine, we'll need to open up an administrative command prompt and make some changes to the '**Boot Configuration Data (BCD)**'. To do this, open an administrative command prompt `cmd.exe` and type these commands:
```plaintext
bcdedit /debug on
bcdedit /set testsigning on
```
As the command text suggests, this will **enable kernel debugging** and **enable test-signing** for our Windows machine! Microsoft is notorious for having strict driver security (*understandably so)* and requires a driver to have a signed-digital signature before allowing it to be executed.
💡
The practice of digitally signing drivers is part of Microsoft's strategy to mitigate risks associated with third-party software and to protect the overall integrity of the Windows Operating System.
[Install OSRLoader](https://www.osronline.com/article.cfm%5Earticle=157.htm)
OSR (Open System Resources) is a consulting company known for providing resources, information, and tools related to the Windows Kernel. As per the company website, "This GUI-based tool will make all the appropriate registry entries for your driver, and even allow you to start your driver without rebooting." Which is perfect for us in the development stage of our driver.
### Coding Time!
Still reading? Good! Yeah -- let's do what we came here to do, develop a driver! With all that setup stuff out of the way, lets open up Visual Studio 2022 on our development machine.
Lets create a Empty Kernel Mode Driver (**KMDF Project**), I'll be naming my project `kernalChronicles_1` but feel free to give it a name of your own.
![](https://cdn.hashnode.com/res/hashnode/image/upload/v1699681832151/147b105d-b179-407b-b320-97da1e268d83.png align="center")
Then, lets create a Source File called `Driver.c` (You can select a C++ file type in the selection menu, just give it a `.c` extension.)
![](https://cdn.hashnode.com/res/hashnode/image/upload/v1699682096707/20bf483e-54ae-4482-ab45-61ce099d72fb.png align="center")
All drivers require a [`DriverEntry`](https://learn.microsoft.com/en-us/windows-hardware/drivers/wdf/driverentry-for-kmdf-drivers) routine, which is responsible for the driver’s initialization. This is similar to the `main` function in standard C programs.
This is what our `DriverEntry` routine will look like:
```c
#include // Kernel header
NTSTATUS DriverEntry(_In_ PDRIVER_OBJECT driverObject, _In_ PUNICODE_STRING registryPath) {
KdPrint(("Hello World - I'm the DriverEntry Routine!\n"));
// - prints data when build settings are set to 'Debug',
// otherwise doesn't do anything
return STATUS_SUCCESS;
}
```
Great! Our Driver should now theoretically load into the kernel! However, it's important to note a key aspect of the lifecycle of a Windows Kernel Driver:
![](https://cdn.hashnode.com/res/hashnode/image/upload/v1699682880653/196c6f89-64d6-4db0-a1c2-dbba770f10b9.png align="center")
In many cases, drivers function as 'event-listeners' and don't terminate automatically. Drivers require manual unloading. Upon unloading, an 'exit' or 'unload' routine is invoked to free resources and prevent memory leaks. So lets make a `DriverUnload` routine.
```c
#include
// Our Unload Routine
NTSTATUS DriverUnload(_In_ PDRIVER_OBJECT driverObject) {
KdPrint(("Till Next Time! Goodbye!\n"));
return STATUS_SUCCESS;
}
// Our Entry Routine
NTSTATUS DriverEntry(_In_ PDRIVER_OBJECT driverObject, _In_ PUNICODE_STRING registryPath) {
KdPrint(("Hello World - I'm the DriverEntry Routine!\n"));
// - prints data when build settings are set to 'Debug',
// otherwise doesn't do anything
driverObject->DriverUnload = DriverUnload; // Set the unload function to DriverUnload
return STATUS_SUCCESS;
}
```
Let's build our solution and see what happens...
![](https://cdn.hashnode.com/res/hashnode/image/upload/v1699683935046/026faa80-2479-4166-a9a1-76d33677e7d5.png align="center")
Oop ;-; what's that? Dang, an error -- wait.. no that's just a warning? What gives?
Because the kernel is critical to operating System functionality -- **KMDF projects are configured to always treat warnings as errors**. While it is possible to disable this behavior, it is NOT recommended. Instead, we can use the macro `UNREFERENCED_PARAMETER(