Original text by Yarden Shafir
Recently I had to write a kernel-mode driver. This has made a lot of people very angry and been widely regarded as a bad move. (Douglas Adams, paraphrased)
Like any other piece of code written by me, this driver had several major bugs which caused some interesting side effects. Specifically, it prevented some other drivers from loading properly and caused the system to crash.
As it turns out, many drivers assume their initialization routine (DriverEntry) is always successful, and don’t take it well when this assumption breaks. j00rudocumented some of these cases a few years ago in his blog, and many of them are still relevant in current Windows versions. However, these buggy drivers are not really the issue here, and j00ru covered it better than I could anyway. Instead I focused on just one of these drivers, which caught my attention and dragged me into researching the so-called “windows kernel host extensions” mechanism.
The lucky driver is Bam.sys (Background Activity Moderator) — a new driver which was introduced in Windows 10 version 1709 (RS3). When its DriverEntry fails mid-way, the call stack leading to the system crash looks like this:
From this crash dump, we can see that Bam.sys registered a process creation callback and forgot to unregister it before unloading. Then, when a process was created / terminated, the system tried to call this callback, encountered a stale pointer and crashed.
The interesting thing here is not the crash itself, but rather how Bam.sys registers this callback. Normally, process creation callbacks are registered via nt!PsSetCreateProcessNotifyRoutine(Ex), which adds the callback to the nt!PspCreateProcessNotifyRoutine array. Then, whenever a process is being created or terminated, nt!PspCallProcessNotifyRoutines iterates over this array and calls all of the registered callbacks. However, if we run for example “!wdbgark.wa_systemcb /type process“ in WinDbg, we’ll see that the callback used by Bam.sys is not found in this array.
Instead, Bam.sys uses a whole other mechanism to register its callbacks.
If we take a look at nt!PspCallProcessNotifyRoutines, we can see an explicit reference to some variable named nt!PspBamExtensionHost (there is a similar one referring to the Dam.sys driver). It retrieves a so-called “extension table” using this “extension host” and calls the first function in the extension table, which is bam!BampCreateProcessCallback.
If we open Bam.sys in IDA, we can easily find bam!BampCreateProcessCallbackand search for its xrefs. Conveniently, it only has one, in bam!BampRegisterKernelExtension:
As suspected, Bam!BampCreateProcessCallback is not registered via the normal callback registration mechanism. It is actually being stored in a function table named Bam!BampKernelCalloutTable, which is later being passed, together with some other parameters (we’ll talk about them in a minute) to the undocumented nt!ExRegisterExtension function.
I tried to search for any documentation or hints for what this function was responsible for, or what this “extension” is, and couldn’t find much. The only useful resource I found was the leaked ntosifs.h header file, which contains the prototype for nt!ExRegisterExtension as well as the layout of the _EX_EXTENSION_REGISTRATION_1 structure.
Prototype for nt!ExRegisterExtension and _EX_EXTENSION_REGISTRATION_1, as supplied in ntosifs.h:
NTKERNELAPI NTSTATUS ExRegisterExtension (
_Outptr_ PEX_EXTENSION *Extension,
_In_ ULONG RegistrationVersion,
_In_ PVOID RegistrationInfo
);
typedef struct _EX_EXTENSION_REGISTRATION_1 {
USHORT ExtensionId;
USHORT ExtensionVersion;
USHORT FunctionCount;
VOID *FunctionTable;
PVOID *HostInterface;
PVOID DriverObject;
} EX_EXTENSION_REGISTRATION_1, *PEX_EXTENSION_REGISTRATION_1;
After a bit of reverse engineering, I figured that the formal input parameter “PVOID RegistrationInfo” is actually of type PEX_EXTENSION_REGISTRATION_1.
The pseudo-code of nt!ExRegisterExtension is shown in appendix B, but here are the main points:
- nt!ExRegisterExtension extracts the ExtensionId and ExtensionVersion members of the RegistrationInfo structure and uses them to locate a matching host in nt!ExpHostList (using the nt!ExpFindHost function, whose pseudo-code appears in appendix B).
- Then, the function verifies that the amount of functions supplied in RegistrationInfo->FunctionCount matches the expected amount set in the host’s structure. It also makes sure that the host’s FunctionTable field has not already been initialized. Basically, this check means that an extension cannot be registered twice.
- If everything seems OK, the host’s FunctionTable field is set to point to the FunctionTable supplied in RegistrationInfo.
- Additionally, RegistrationInfo->HostInterface is set to point to some data found in the host structure. This data is interesting, and we’ll discuss it soon.
- Eventually, the fully initialized host is returned to the caller via an output parameter.
We saw that nt!ExRegisterExtension searches for a host that matches RegistrationInfo. The question now is, where do these hosts come from?
- During its initialization, NTOS performs several calls to nt!ExRegisterHost. In every call it passes a structure identifying a single driver from a list of predetermined drivers (full list in appendix A). For example, here is the call which initializes a host for Bam.sys:
- nt!ExRegisterHost allocates a structure of type _HOST_LIST_ENTRY(unofficial name, coined by me), initializes it with data supplied by the caller, and adds it to the end of nt!ExpHostList. The _HOST_LIST_ENTRYstructure is undocumented, and looks something like this:
struct _HOST_LIST_ENTRY
{
_LIST_ENTRY List;
DWORD RefCount;
USHORT ExtensionId;
USHORT ExtensionVersion;
USHORT FunctionCount; // number of callbacks that the extension
// contains
POOL_TYPE PoolType; // where this host is allocated
PVOID HostInterface; // table of unexported nt functions,
// to be used by the driver to which
// this extension belongs
PVOID FunctionAddress; // optional, rarely used.
// This callback is called before
// and after an extension for this
// host is registered / unregistered
PVOID ArgForFunction; // will be sent to the function saved here
_EX_RUNDOWN_REF RundownRef;
_EX_PUSH_LOCK Lock;
PVOID FunctionTable; // a table of the callbacks that the
// driver “registers”
DWORD Flags; // Only uses one bit.
// Not sure about its meaning.
} HOST_LIST_ENTRY, *PHOST_LIST_ENTRY;
- When one of the predetermined drivers loads, it registers an extension using nt!ExRegisterExtension and supplies a RegistrationInfo structure, containing a table of functions (as we saw Bam.sys doing). This table of functions will be placed in the FunctionTable member of the matching host. These functions will be called by NTOS in certain occasions, which makes them some kind of callbacks.
Earlier we saw that part of nt!ExRegisterExtension functionality is to set RegistrationInfo->HostInterface (which contains a global variable in the calling driver) to point to some data found in the host structure. Let’s get back to that.
Every driver which registers an extension has a host initialized for it by NTOS. This host contains, among other things, a HostInterface, pointing to a predetermined table of unexported NTOS functions. Different drivers receive different HostInterfaces, and some don’t receive one at all.
For example, this is the HostInterface that Bam.sys receives:
So the “kernel extensions” mechanism is actually a bi-directional communication port: The driver supplies a list of “callbacks”, to be called on different occasions, and receives a set of functions for its own internal use.
To stick with the example of Bam.sys, let’s take a look at the callbacks that it supplies:
- BampCreateProcessCallback
- BampSetThrottleStateCallback
- BampGetThrottleStateCallback
- BampSetUserSettings
- BampGetUserSettingsHandle
The host initialized for Bam.sys “knows” in advance that it should receive a table of 5 functions. These functions must be laid-out in the exact order presented here, since they are called according to their index. As we can see in this case, where the function found in nt!PspBamExtensionHost->FunctionTable[4] is called:
To conclude, there exists a mechanism to “extend” NTOS by means of registering specific callbacks and retrieving unexported functions to be used by certain predetermined drivers.
I don’t know if there is any practical use for this knowledge, but I thought it was interesting enough to share. If you find anything useful / interesting to do with this mechanism, I’d love to know 🙂
Appendix A — Extension hosts initialized by NTOS:
Appendix B — functions pseudo-code:
NTSTATUS ExRegisterExtension(_Outptr_ PEX_EXTENSION *Extension, _In_ ULONG RegistrationVersion, _In_ PREGISTRATION_INFO RegistrationInfo)
{
// Validate that version is ok and that FunctionTable is not sent without FunctionCount or vise-versa.
if ( (RegistrationVersion & 0xFFFF0000 != 0x10000) || (RegistrationInfo->FunctionTable == nullptr && RegistrationInfo->FunctionCount != 0) )
{
return STATUS_INVALID_PARAMETER;
}
// Skipping over some lock-related stuff,
// Find the host with the matching version and id.
PHOST_LIST_ENTRY pHostListEntry;
pHostListEntry = ExpFindHost(RegistrationInfo->ExtensionId, RegistrationInfo->ExtensionVersion);
// More lock-related stuff.
if (!pHostListEntry)
{
return STATUS_NOT_FOUND;
}
// Verify that the FunctionCount in the host doesn't exceed the FunctionCount supplied by the caller.
if (RegistrationInfo->FunctionCount < pHostListEntry->FunctionCount)
{
ExpDereferenceHost(pHostListEntry);
return STATUS_INVALID_PARAMETER;
}
// Check that the number of functions in FunctionTable matches the amount in FunctionCount.
PVOID FunctionTable = RegistrationInfo->FunctionTable;
for (int i = 0; i < RegistrationInfo->FunctionCount; i++)
{
if ( RegistrationInfo->FunctionTable[i] == nullptr )
{
ExpDereferenceHost(pHostListEntry);
return STATUS_ACCESS_DENIED;
}
}
// skipping over some more lock-related stuff
// Check if there is already an extension registered for this host.
if (pHostListEntry->FunctionTable != nullptr || FlagOn(pHostListEntry->Flags, 1) )
{
// There is something related to locks here
ExpDereferenceHost(pHostListEntry);
return STATUS_OBJECT_NAME_COLLISION;
}
// If there is a callback function for this host, call it before registering the extension, with 0 as the first parameter.
if (pHostListEntry->FunctionAddress)
{
pHostListEntry->FunctionAddress(0, pHostListEntry->ArgForFunction);
}
// Set the FunctionTable in the host to the table supplied by the caller, or to MmBadPointer if a table wasn't supplied.
if (RegistrationInfo->FunctionTable == nullptr)
{
pHostListEntry->FunctionTable = nt!MmBadPointer;
}
else
{
pHostListEntry->FunctionTable = RegistrationInfo->FunctionTable;
}
pHostListEntry->RundownRef = 0;
// If there is a callback function for this host, call it after registering the extension, with 1 as the first parameter.
if (pHostListEntry->FunctionAddress)
{
pHostListEntry->FunctionAddress(1, pHostListEntry->ArgForFunction);
}
// Here there is some more lock-related stuff
// Set the HostTable of the calling driver to the table of functions listed in the host.
if (RegistrationInfo->HostTable != nullptr)
{
*(PVOID)RegistrationInfo->HostTable = pHostListEntry->hostInterface;
}
// Return the initialized host to the caller in the output Extension parameter.
*Extension = pHostListEntry;
return STATUS_SUCCESS;
}
ExRegisterExtension.c hosted with ❤ by GitHub
NTSTATUS ExRegisterHost(_Out_ PHOST_LIST_ENTRY ExtensionHost, _In_ ULONG Unused, _In_ PHOST_INFORMATION HostInformation)
{
NTSTATUS Status = STATUS_SUCCESS;
// Allocate memory for a new HOST_LIST_ENTRY
PHOST_LIST_ENTRY p = ExAllocatePoolWithTag(HostInformation->PoolType, 0x60, 'HExE');
if (p == nullptr)
{
return STATUS_INSUFFICIENT_RESOURCES;
}
//
// Initialize a new HOST_LIST_ENTRY
//
p->Flags &= 0xFE;
p->RefCount = 1;
p->FunctionTable = 0;
p->ExtensionId = HostInformation->ExtensionId;
p->ExtensionVersion = HostInformation->ExtensionVersion;
p->hostInterface = HostInformation->hostInterface;
p->FunctionAddress = HostInformation->FunctionAddress;
p->ArgForFunction = HostInformation->ArgForFunction;
p->Lock = 0;
p->RundownRef = 0;
// Search for an existing listEntry with the same version and id.
PHOST_LIST_ENTRY listEntry = ExpFindHost(HostInformation->ExtensionId, HostInformation->ExtensionVersion);
if (listEntry)
{
Status = STATUS_OBJECT_NAME_COLLISION;
ExpDereferenceHost(p);
ExpDereferenceHost(listEntry);
}
else
{
// Insert the new HOST_LIST_ENTRY to the end of ExpHostList.
if ( *lastHostListEntry != &firstHostListEntry )
{
__fastfail();
}
firstHostListEntry->Prev = &p;
p->Next = firstHostListEntry;
lastHostListEntry = p;
ExtensionHost = p;
}
return Status;
}
ExRegisterHost.c hosted with ❤ by GitHub
PHOST_LIST_ENTRY ExpFindHost(USHORT ExtensionId, USHORT ExtensionVersion)
{
PHOST_LIST_ENTRY entry;
for (entry == ExpHostList; ; entry = entry->Next)
{
if (entry == &ExpHostList)
{
return 0;
}
if ( *(entry->ExtensionId) == ExtensionId && *(entry->ExtensionVersion) == ExtensionVersion )
{
break;
}
}
InterlockedIncrement(entry->RefCount);
return entry;
}
ExpFindHost.c hosted with ❤ by GitHub
void ExpDereferenceHost(PHOST_LIST_ENTRY Host)
{
if ( InterlockedExchangeAdd(Host.RefCount, 0xFFFFFFFF) == 1 )
{
ExFreePoolWithTag(Host, 0);
}
}
ExpDereferenceHost.c hosted with ❤ by GitHub
Appendix C — structures definitions:
struct _HOST_INFORMATION
{
USHORT ExtensionId;
USHORT ExtensionVersion;
DWORD FunctionCount;
POOL_TYPE PoolType;
PVOID HostInterface;
PVOID FunctionAddress;
PVOID ArgForFunction;
PVOID unk;
} HOST_INFORMATION, *PHOST_INFORMATION;
struct _HOST_LIST_ENTRY
{
_LIST_ENTRY List;
DWORD RefCount;
USHORT ExtensionId;
USHORT ExtensionVersion;
USHORT FunctionCount; // number of callbacks that the
// extension contains
POOL_TYPE PoolType; // where this host is allocated
PVOID HostInterface; // table of unexported nt functions,
// to be used by the driver to which
// this extension belongs
PVOID FunctionAddress; // optional, rarely used.
// This callback is called before and
// after an extension for this host
// is registered / unregistered
PVOID ArgForFunction; // will be sent to the function saved here
_EX_RUNDOWN_REF RundownRef;
_EX_PUSH_LOCK Lock;
PVOID FunctionTable; // a table of the callbacks that
// the driver “registers”
DWORD Flags; // Only uses one flag.
// Not sure about its meaning.
} HOST_LIST_ENTRY, *PHOST_LIST_ENTRY;;
struct _EX_EXTENSION_REGISTRATION_1
{
USHORT ExtensionId;
USHORT ExtensionVersion;
USHORT FunctionCount;
PVOID FunctionTable;
PVOID *HostTable;
PVOID DriverObject;
}EX_EXTENSION_REGISTRATION_1, *PEX_EXTENSION_REGISTRATION_1;