Domito/README.md

5.5 KiB
Raw Permalink Blame History

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

  <!-- 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):