nefarius
a491bbd3f8
Fix process-name ownership and module lookup outputs, add explicit SPKI hashing and bounded chain access, and improve WDM integration. Deprecate superseded entry points with migration guidance and align branch code and tests with the library style.
120 lines
7.1 KiB
Markdown
120 lines
7.1 KiB
Markdown
# Domito
|
||
|
||
Windows kernel driver utilities library.
|
||
|
||
## 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!~~
|
||
|
||
Time to retire this disclaimer; it has done well for a couple years now on like half a million installs and counting so I think we're good 😉
|
||
|
||
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 🤞
|
||
- CI entry points are currently static imports from `ci.lib`; consumers must avoid imports unavailable on their target Windows builds. The [CI API compatibility matrix](docs/ci-api-compatibility.md) records all ten named exports across 20 exact Windows 10/11 x64 and ARM64 CI files. Export lookup uses the correct name-ordinal mapping and rejects forwarders. Runtime ABI verification remains separate; see the remaining-work ledger below.
|
||
- 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 😎
|
||
|
||
## Authenticode validation helpers
|
||
|
||
The [CI validation helpers](docs/ci-validation-helpers.md) provide shared result
|
||
ownership/cleanup, file-object validation with explicit selection policy, and
|
||
algorithm-explicit embedded verification using CI. First-success selection is
|
||
an opt-in x64 experiment; existing APIs retain their behavior. Always enforce
|
||
the expected signer/trust policy separately from a successful CI return status.
|
||
|
||
## Consumer helpers
|
||
|
||
[Migration and contracts](docs/consumer-helpers.md) cover file-handle/path CI
|
||
validation, bounded x64 chain views, optional publisher-name extraction,
|
||
certificate/SPKI hashing (including explicit legacy content-only pins), strict
|
||
hex conversion, process-name cleanup and combined module/export lookup.
|
||
Application authorization and trust policies remain caller-provided.
|
||
|
||
## 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
|
||
|
||
Import `Domito.props` from the Domito package, or set `DomitoRootPath` explicitly
|
||
if copying the sheet elsewhere. Its default root is its own directory. The sheet
|
||
links both WDM and KMDF final drivers; static-library consumers must also import
|
||
it into the final driver project. `DomitoLibraryPlatform` defaults to `$(Platform)`.
|
||
For example:
|
||
|
||
```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 -->
|
||
```
|
||
|
||
## Code Integrity API notes
|
||
|
||
- [Algorithm-explicit Authenticode hashing and legacy catalog policy](docs/authenticode-digests.md)
|
||
- [Mincrypt contracts, lifetimes, flags and opt-in x64 26100 layouts](docs/mincrypt-contracts.md)
|
||
- [Implemented corrections and remaining VM/binary work](docs/implementation-status.md)
|
||
|
||
- [CiValidateFileObject flag 0x20: evidence, limitations, and kernel test procedure](docs/ci-validate-file-object.md)
|
||
|
||
## 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/)
|