Domito/README.md

# 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.
- 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!

## 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/)