{"componentChunkName":"component---src-templates-post-template-js","path":"/windows-windriver-001-tutorial-en","result":{"data":{"markdownRemark":{"id":"aad3f4db-704d-5969-beb3-6aa1495dcf7b","html":"
\n

This page has been machine-translated from the original page.

\n
\n

When I tried Windows kernel debugging, one obstacle I ran into was that there are very few kernel drivers with detailed public specifications.

\n

If there wasn’t one, I figured I would just make one myself, so I started developing a kernel driver.

\n

For kernel driver development, I am basically using the following book as a reference.

\n

Reference: Windows Kernel Driver Programming

\n

I summarized how to configure kernel debugging in the following article.

\n

Reference: A First Step Toward Kernel Debugging a Windows 10 Environment with WinDbg

\n\n

Table of Contents

\n\n

Create your first driver

\n

Let’s start by creating our first driver.

\n

Create a WDM project in Visual Studio.

\n

At the time of writing this article, on 2021/12/01, Visual Studio 2022 did not support kernel driver development.

\n

For that reason, if you have updated to Visual Studio 2022 or later, you need to be careful because you will not be able to create a WDM project.

\n

This time I am using Visual Studio 2019.

\n

What is WDM?

\n

WDM stands for Microsoft Windows Driver Model, and it is the architecture for device drivers on Windows 2000 and later.

\n

It is now a deprecated driver model.

\n

If you are creating a kernel driver today, Windows Driver Foundation(WDF) or universal Windows drivers are probably the mainstream choice.

\n

Reference: Introduction to WDM - Windows drivers | Microsoft Docs

\n

There are three types of WDM drivers:

\n\n

Reference: Bus Drivers - Windows drivers | Microsoft Docs

\n

Reference: Function Drivers - Windows drivers | Microsoft Docs

\n

Reference: Filter Drivers - Windows drivers | Microsoft Docs

\n

Simple code

\n

After creating a WDM project in Visual Studio, add a C++ source file with any name and add the following code.

\n
#include <ntddk.h>\n\nvoid FirstDriverUnload(_In_ PDRIVER_OBJECT DriverObject)\n{\nUNREFERENCED_PARAMETER(DriverObject);\n}\n\nextern "C"\nNTSTATUS\nDriverEntry(_In_ PDRIVER_OBJECT DriverObject, _In_ PUNICODE_STRING RegistryPath)\n{\nUNREFERENCED_PARAMETER(DriverObject);\nUNREFERENCED_PARAMETER(RegistryPath);\n\nreturn STATUS_SUCCESS;\n}
\n

DriverEntry

\n

DriverEntry is the entry point of the driver module.

\n

DriverEntry is called by a system thread (kernel-mode system thread) at IRQL IRQL_PASSIVE_LEVEL(0).

\n

FirstDriverUnload

\n

FirstDriverUnload defines the unload routine for the driver.

\n

There is no problem if you change the function name to something other than FirstDriverUnload.

\n

Although it is not yet defined in the sample code above, assigning it to DriverObject’s DriverUnload defines the function that is called when the driver module is unloaded.

\n
// アンロードルーチンを定義\nDriverObject->DriverUnload = FirstDriverUnload;
\n

In the case of a kernel driver, resources such as memory need to be released when it is unloaded, so cleanup processing is defined in this unload routine.

\n

System threads (kernel-mode system threads)

\n

The threads running in the System process (Process ID 4) are system threads, and they run in kernel mode.

\n

System threads execute kernel-mode code in Ntoskrnl.exe or in loaded device drivers.

\n

Reference: Inside Windows 7th Edition, Part 1

\n

Build the driver

\n

Once you have created the minimum code, build the kernel driver.

\n

For now, build it as a debug build by pressing [Ctrl+Shift+B].

\n

Set the target platform

\n

This time, because I am building a driver module for an x64 environment, I set [Active solution platform] to [x64] in the Visual Studio project properties.

\n

\n \n \n \n \n \n \n \n \n

\n

If you leave this at the default setting, a driver module for an x86 environment will be built, which causes the problem that it fails even if you try to start it on 64-bit Windows.

\n

Load the kernel driver

\n

Once the driver has been built, place the built driver module in the virtual machine as Z:\\FirstDriverSample.sys.

\n

Note: Any folder and driver name are fine here.

\n

Next, use the sc command to load the driver you created as the 001_sample service.

\n
sc create 001_sample type= kernel binPath= Z:\\FirstDriverSample.sys
\n

If it succeeds, you will see a screen like the following, and the service you added is registered under HKLM\\SYSTEM\\CurrentControlSet\\Services in the registry.

\n

\n \n \n \n \n \n \n \n \n

\n

Next, start the service you added.

\n

If you run the sc start 001_sample command, startup fails.

\n
> sc start 001_sample\n[SC] StartService FAILED 1275:\nこのドライバーの読み込みはブロックされています
\n

This is because 64-bit system drivers require a signature, while the driver I created myself does not have one.

\n

To work around this error, boot the virtual machine you use to verify the driver in test-signing mode.

\n

Run the following command and reboot.

\n
bcdedit /set testsigning on
\n

Note: The system does not switch to test-signing mode until the OS is rebooted.

\n

Note: If Secure Boot is enabled, switching to test-signing mode will fail.

\n

To reboot, run the following command from a command prompt started with administrator privileges.

\n
shutdown /r /t 0
\n

After rebooting, if you start the service again, the registered service starts.

\n
> sc start 001_sample\nSERVICE_NAME: sample\n        TYPE               : 1  KERNEL_DRIVER\n        STATE              : 4  RUNNING\n                                (STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN)\n        WIN32_EXIT_CODE    : 0  (0x0)\n        SERVICE_EXIT_CODE  : 0  (0x0)\n        CHECKPOINT         : 0x0\n        WAIT_HINT          : 0x0\n        PID                : 0\n        FLAGS              :
\n

Next, stop the service.

\n

The service cannot be stopped

\n

Even if you try to stop the service with the driver module up to this point, stopping fails.

\n
> sc stop 001_sample\n[SC] ControlService FAILED 1052:s\n要求された制御はこのサービスに対して無効です。
\n

The same happens if you use a tool such as ProcessHacker to stop the service.

\n

\n \n \n \n \n \n \n \n \n

\n

This is because the unload routine mentioned earlier has not been implemented in the device driver.

\n

Reference: Checking the Basic Behavior of Windows Device Drivers (1) - Fixstars Tech Blog /proc/cpuinfo

\n

For that reason, I modified the code as follows.

\n
#include <ntddk.h>\n\nvoid FirstDriverUnload(_In_ PDRIVER_OBJECT DriverObject)\n{\nUNREFERENCED_PARAMETER(DriverObject);\n}\n\nextern "C"\nNTSTATUS\nDriverEntry(_In_ PDRIVER_OBJECT DriverObject, _In_ PUNICODE_STRING RegistryPath)\n{\nUNREFERENCED_PARAMETER(RegistryPath);\n\n    // アンロードルーチンを定義\nDriverObject->DriverUnload = FirstDriverUnload;\n\nreturn STATUS_SUCCESS;\n}
\n

After reloading the device driver with this change and starting the service, running the sc stop 001_sample command makes it possible to stop the service.

\n
> sc stop 001_sample\nSERVICE_NAME: 001_sample\n        TYPE               : 1  KERNEL_DRIVER\n        STATE              : 1  STOPPED\n        WIN32_EXIT_CODE    : 0  (0x0)\n        SERVICE_EXIT_CODE  : 0  (0x0)\n        CHECKPOINT         : 0x0\n        WAIT_HINT          続いて、サービスの確認を行います。
\n

Reload the service

\n

To reload the service, you need to delete the service you previously registered once.

\n

The following commands let you delete and re-register the service, so save them as an appropriate batch file such as reload.bat and use that.

\n
sc stop 001_sample\nsc delete 001_sample\nsc create 001_sample type= kernel binPath= Z:\\FirstDriverSample.sys\nsc start 001_sample
\n

Next, check the registered kernel driver service.

\n

Check the service

\n

Before that, let me briefly touch on what a service is.

\n

In Windows, a service refers to a process started by the Service Control Manager (SCM).

\n

When you add a kernel driver, it is added as a service, which is confusing, but in many cases it seems that “Windows services” and “driver services” are distinguished.

\n

Inside Windows also explicitly states that a “service” is a user-mode process started by the SCM, and that device drivers are not treated as services.

\n

Reference: Inside Windows 7th Edition, Part 1

\n

Reference: Service Control Manager - Win32 apps | Microsoft Docs

\n

As confirmed earlier, a kernel driver is registered as a subkey under HKLM\\SYSTEM\\CurrentCntrolSet\\Services and is started by the SCM.

\n

Here, the services registered under HKLM\\SYSTEM\\CurrentCntrolSet\\Services are distinguished between kernel drivers and Windows services, and when the value of each subkey’s [Type] is a low numeric value, it means the service is a kernel driver; a value of 0x10 or 0x20 means it is registered as a Windows service.

\n

You can verify the registered kernel driver service using tools such as ProcessHacker or Proexp.

\n

\n \n \n \n \n \n \n \n \n

\n

As shown in the image, you can confirm that the driver module you created is loaded.

\n

Add the KdPrint macro

\n

Next, add a print routine to the device driver.

\n

Before that, to make DebugView capture the output of KdPrint from the kernel driver, create a [Debug Print Filter] subkey under HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager, add a DWORD key named DEFAULT, and set its value to 1.

\n

Note: You need to reboot the OS for this setting to take effect.

\n

\n \n \n \n \n \n \n \n \n

\n

Next, rewrite the device driver code as follows, and after building, reload the device driver.

\n
#include <ntddk.h>\n\nvoid FirstDriverUnload(_In_ PDRIVER_OBJECT DriverObject)\n{\nUNREFERENCED_PARAMETER(DriverObject);\n\nKdPrint(("This driver unloaded\\n"));\n}\n\nextern "C"\nNTSTATUS\nDriverEntry(_In_ PDRIVER_OBJECT DriverObject, _In_ PUNICODE_STRING RegistryPath)\n{\nUNREFERENCED_PARAMETER(RegistryPath);\n\nDriverObject->DriverUnload = FirstDriverUnload;\n\nOSVERSIONINFOEXW osVersionInfo;\nNTSTATUS status = STATUS_SUCCESS;\nosVersionInfo.dwOSVersionInfoSize = sizeof(OSVERSIONINFOEXW);\nstatus = RtlGetVersion((POSVERSIONINFOW)&osVersionInfo);\n\nKdPrint(("This is my first sample driver\\n"));\nKdPrint(("OS version is : %d.%d.%d\\n", osVersionInfo.dwMajorVersion, osVersionInfo.dwMinorVersion, osVersionInfo.dwBuildNumber));\n\nreturn STATUS_SUCCESS;\n}
\n

Here, I use the KdPrint macro to output the current OS version information.

\n

I use RtlGetVersion to obtain the OS version information.

\n

Reference: RtlGetVersion function (wdm.h) - Windows drivers | Microsoft Docs

\n

The information obtained is returned as an OSVERSIONINFOEXW structure.

\n

Reference: OSVERSIONINFOA (winnt.h) - Win32 apps | Microsoft Docs

\n
typedef struct _OSVERSIONINFOA {\n  DWORD dwOSVersionInfoSize;\n  DWORD dwMajorVersion;\n  DWORD dwMinorVersion;\n  DWORD dwBuildNumber;\n  DWORD dwPlatformId;\n  CHAR  szCSDVersion[128];\n} OSVERSIONINFOA, *POSVERSIONINFOA, *LPOSVERSIONINFOA;
\n

Configure DebugView

\n

Use Sysinternals DebugView to capture the output of the KdPrint macro.

\n

First, start the application and enable [Capture Kernel] and [Enable Verbose Output] from [Capture].

\n

\n \n \n \n \n \n \n \n \n

\n

Now, if you start the service while capture is running after pressing the capture button on the toolbar, you can see the OS version information in DebugView.

\n

\n \n \n \n \n \n \n \n \n

\n

Finally, I will try kernel-debugging the custom driver with WinDbg (the main topic at last).

\n

Analyze the custom driver with kernel debugging

\n

First, enable kernel debugging.

\n
bcdedit /debug on\nbcdedit /dbgsettings serial debugport:1 baudrate:115200\nshutdown /r /t 0
\n

I summarized the detailed setup method in the following article.

\n

Reference: A First Step Toward Kernel Debugging a Windows 10 Environment with WinDbg

\n

Once the kernel debugging connection succeeds, add the pdb file for the driver you built this time to Sympath.

\n
.sympath+ C:\\Users\\Tadpole01\\source\\repos\\Try2WinDbg\\drivers\\FirstDriverSample\\x64\\Debug
\n

If you look at the module list, you can confirm that FirstDriverSample exists.

\n
kd> lm\nstart             end                 module name\nfffff800`64520000 fffff800`64527000   FirstDriverSample   (deferred)             \nfffff801`74000000 fffff801`747cc000   nt         (pdb symbols)          C:\\ProgramData\\Dbg\\sym\\ntkrnlmp.pdb\\F7971FB6AA7E450CBCA7054A98D659421\\ntkrnlmp.pdb\nUnloaded modules:\nfffff800`62c80000 fffff800`62c8f000   dump_storport.sys\nfffff800`62cc0000 fffff800`62ce5000   dump_storahci.sys\nfffff800`62d10000 fffff800`62d2c000   dump_dumpfve.sys\nfffff800`63400000 fffff800`63413000   dam.sys \nfffff800`61ec0000 fffff800`61ed0000   WdBoot.sys\nfffff800`62ba0000 fffff800`62bae000   hwpolicy.sys
\n

Because the symbols are loaded, you can also confirm the function names.

\n
kd> x /D /f FirstDriverSample!d*\nfffff800`64521020 FirstDriverSample!DriverEntry (struct _DRIVER_OBJECT *, struct _UNICODE_STRING *)\nfffff800`645210f7 FirstDriverSample!DbgPrint (DbgPrint)
\n

Use the uf command to look at the disassembly result of the entry function.

\n
kd> uf FirstDriverSample!DriverEntry\nFirstDriverSample!DriverEntry [C:\\Users\\Tadpole01\\source\\repos\\Try2WinDbg\\drivers\\FirstDriverSample\\FirstDriver.cpp @ 13]:\n   13 fffff800`64521020 4889542410      mov     qword ptr [rsp+10h],rdx\n   13 fffff800`64521025 48894c2408      mov     qword ptr [rsp+8],rcx\n   13 fffff800`6452102a 4881ec68010000  sub     rsp,168h\n   13 fffff800`64521031 488b05c81f0000  mov     rax,qword ptr [FirstDriverSample!__security_cookie (fffff800`64523000)]\n   13 fffff800`64521038 4833c4          xor     rax,rsp\n   13 fffff800`6452103b 4889842450010000 mov     qword ptr [rsp+150h],rax\n   16 fffff800`64521043 488b842470010000 mov     rax,qword ptr [rsp+170h]\n   16 fffff800`6452104b 488d0daeffffff  lea     rcx,[FirstDriverSample!FirstDriverUnload (fffff800`64521000)]\n   16 fffff800`64521052 48894868        mov     qword ptr [rax+68h],rcx\n   19 fffff800`64521056 c744242000000000 mov     dword ptr [rsp+20h],0\n   20 fffff800`6452105e c74424301c010000 mov     dword ptr [rsp+30h],11Ch\n   21 fffff800`64521066 488d4c2430      lea     rcx,[rsp+30h]\n   21 fffff800`6452106b ff158f0f0000    call    qword ptr [FirstDriverSample!_imp_RtlGetVersion (fffff800`64522000)]\n   21 fffff800`64521071 89442420        mov     dword ptr [rsp+20h],eax\n   23 fffff800`64521075 488d0d74010000  lea     rcx,[FirstDriverSample! ?? ::FNODOBFM::`string' (fffff800`645211f0)]\n   23 fffff800`6452107c e876000000      call    FirstDriverSample!DbgPrint (fffff800`645210f7)\n   24 fffff800`64521081 448b4c243c      mov     r9d,dword ptr [rsp+3Ch]\n   24 fffff800`64521086 448b442438      mov     r8d,dword ptr [rsp+38h]\n   24 fffff800`6452108b 8b542434        mov     edx,dword ptr [rsp+34h]\n   24 fffff800`6452108f 488d0d7a010000  lea     rcx,[FirstDriverSample! ?? ::FNODOBFM::`string' (fffff800`64521210)]\n   24 fffff800`64521096 e85c000000      call    FirstDriverSample!DbgPrint (fffff800`645210f7)\n   26 fffff800`6452109b 33c0            xor     eax,eax\n   27 fffff800`6452109d 488b8c2450010000 mov     rcx,qword ptr [rsp+150h]\n   27 fffff800`645210a5 4833cc          xor     rcx,rsp\n   27 fffff800`645210a8 e823000000      call    FirstDriverSample!__security_check_cookie (fffff800`645210d0)\n   27 fffff800`645210ad 4881c468010000  add     rsp,168h\n   27 fffff800`645210b4 c3              ret
\n

This time, it is not a kernel driver with much behavior, so I will stop here for now.

\n

From next time onward, I plan to perform live debugging against a custom driver.

\n

Summary

\n

I started developing a kernel driver in order to verify kernel-mode debugging.

\n

WinDbg-related articles are collected here.

\n

Reference: Debugging and Troubleshooting Techniques with WinDbg

","fields":{"slug":"/windows-windriver-001-tutorial-en","tagSlugs":["/tag/win-dbg-en/","/tag/kernel-en/","/tag/kernel-driver-en/","/tag/reversing-en/","/tag/english/"]},"frontmatter":{"date":"2021-12-22","description":"","tags":["WinDbg (en)","Kernel (en)","KernelDriver (en)","Reversing (en)","English"],"title":"Building a Custom Windows Kernel Driver and Analyzing It with WinDbg","socialImage":{"publicURL":"/static/1d61c36eea0cac0d4e6ab1a46fc920c4/windows-windriver-001-tutorial.png"}}}},"pageContext":{"slug":"/windows-windriver-001-tutorial-en"}},"staticQueryHashes":["251939775","401334301","825871152"]}