92 lines
5.5 KiB
Markdown
92 lines
5.5 KiB
Markdown
# Domito
|
||
|
||
Windows kernel driver utilities library.
|
||
|
||
Work in progress, use with care 🔥
|
||
|
||
## About
|
||
|
||
Static library containing some unconventional and undocumented kernel space goodies for the adventurous kernel hacker 🙂 Although I aim for stable code, I can not recommend it for production use; but it's mighty helpful in a lab environment to say the least! You've been warned!
|
||
|
||
Most of the logic you find here has been discovered and provided by the fine folks listed in the credits section below, I merely touched it up and molded into an utilities library for easy consumption in your own kernel driver project.
|
||
|
||
## Conventions
|
||
|
||
Custom types are prefixed with an all upper case `DOMITO_` and functions are prefixed with a Pascal case `Domito` to avoid conflicts with any system-provided names. The word "domito" is latin for "to tame".
|
||
|
||
## Environment
|
||
|
||
Built for and tested on **Windows 10 version 1507 (or newer) x64/ARM64**. 32-Bit might work too but who cares about that 😆
|
||
|
||
## Goals
|
||
|
||
- Stick to C-compatible exports and consumable types only.
|
||
- I do not want to force any consumer of the library to drag C++ paradigms into their project. I do expect the user to utilize a modern compiler though, so the library sources themselves may have some 'C++-ish touches' here and there, for my own convenience 😉
|
||
- Compatibility with every Windows 10 version.
|
||
- APIs not available on older builds will give you a `STATUS_NOT_IMPLEMENTED` instead of hard-linking and therefore making your driver fail to load 🤞
|
||
- **Caution:** this claim comes with an asterisk though; due to PatchGuard (or some other security mechanism) I couldn't get run-time dynamic linking for `ci.dll` exports to work, so you need to actively avoid implementing code depending on exports that do not exist on earlier versions of Windows. Once I have a compatibility matrix for all of them I'll update the documentation accordingly.
|
||
- No conflicts with WDF or DMF
|
||
- The consuming driver *may* (but doesn't have to) utilize Microsoft WDF or DMF in addition without having to fear any incompatibilities 💪
|
||
- Reliable SAL annotations.
|
||
- I made sure to enrich the majority of the code with correct, tested annotations for Code Analysis to help you spot potential accidental API misuse 😎
|
||
|
||
## How to use
|
||
|
||
- Add the `include` directory to your project's headers search path.
|
||
- To make your life easier I recommend setting an environment variable named `DOMITO_INC_PATH` to `...\Domito\include` absolute path and...
|
||
- ...in your project add `$(DOMITO_INC_PATH);` to "Additional Include Directories".
|
||
- Add includes (preferably in the provided order):
|
||
```c
|
||
#include <ntddk.h>
|
||
#include <ntimage.h>
|
||
#include <bcrypt.h>
|
||
#include <Domito.h>
|
||
```
|
||
- Call `DomitoInit()` in your `DriverEntry` once to bootstrap internals.
|
||
|
||
### Manual linker settings
|
||
|
||
- Link against the resulting `Domito.lib` file for your desired architecture.
|
||
- To make your life easier I recommend setting an environment variable named `DOMITO_LIB_PATH` to `...\Domito\lib` absolute path and...
|
||
- ...in your project add `$(DOMITO_LIB_PATH)\$(DDKPlatform)\$(Configuration)\Domito.lib;$(DOMITO_LIB_PATH)\$(DDKPlatform)\ci.lib;` to "Additional Dependencies".
|
||
- Link against the provided `ci.lib` for the Code Integrity convenience functions.
|
||
- Link against `cng.lib` for the CNG BCrypt APIs.
|
||
- Done!
|
||
|
||
### Using the property sheet
|
||
|
||
Copy the provided `Domito.props` file into the directory of your `.vcxproj` file and customize it like below:
|
||
|
||
```xml
|
||
<!-- The rest of the project file -->
|
||
<ImportGroup Label="PropertySheets">
|
||
<Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
|
||
</ImportGroup>
|
||
<!-- Create or update the following section below the above snippet -->
|
||
<ImportGroup Label="PropertySheets">
|
||
<!-- potential other custom sheet references -->
|
||
<!-- Reference "Domito.props" here -->
|
||
<Import Project="Domito.props" />
|
||
</ImportGroup>
|
||
<!-- The rest of the project file -->
|
||
```
|
||
|
||
## Sources & 3rd party credits
|
||
|
||
This library benefits from these awesome projects ❤ (appearance in no special order):
|
||
|
||
- [GetProcAddress implementation - for the Kernel](https://github.com/nefarius/WDF-Utils/blob/master/Snippets/WDM/GetProcAddress.md)
|
||
- [Implementation of GetProcAddress and GetModuleHandle
|
||
for Windows NT3.51/NT4/2000/XP/2003/Vista/7/8 kernel mode,
|
||
both 32 and 64 bit platforms](http://alter.org.ua/en/docs/nt_kernel/procaddr/)
|
||
- [Use ci.dll API for validating Authenticode signature of files](https://github.com/Ido-Moshe-Github/CiDllDemo)
|
||
- [MiroKaku/CiDllDemo](https://github.com/MiroKaku/CiDllDemo)
|
||
- [MiroKaku/Veil](https://github.com/MiroKaku/Veil)
|
||
- [Helper functions for calculating the authenticode digest for a portable executable file](https://github.com/mihaly044/pedigest)
|
||
- Custom memory allocator exposure inspired by SDL
|
||
- [SDL_stdinc.h](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_stdinc.h)
|
||
- [SDL_malloc.c](https://github.com/libsdl-org/SDL/blob/main/src/stdlib/SDL_malloc.c)
|
||
- [Authenticode (I): Understanding Windows Authenticode – RME-DisCo Research Group (reversea.me)](https://reversea.me/index.php/authenticode-i-understanding-windows-authenticode/)
|
||
- [Verifying Windows binaries, without Windows](https://blog.trailofbits.com/2020/05/27/verifying-windows-binaries-without-windows/)
|
||
- [Authenticode certificates and checks from a KM driver](https://astralvx.com/authenticode-certificates-and-checks-from-a-km-driver/)
|