Playing with the Windows Notification Facility (WNF)

ExSubscribeWnfStateChange

NTSTATUS
ExSubscribeWnfStateChange (
    _Out_ptr_ PWNF_SUBSCRIPTION* Subscription,
    _In_ PWNF_STATE_NAME StateName,
    _In_ ULONG DeliveryOption,
    _In_ WNF_CHANGE_STAMP CurrentChangeStamp,
    _In_ PWNF_CALLBACK Callback,
    _In_opt_ PVOID CallbackContext
    );

ExSubscribeWnfStateChange enables the registration of a new subscription in the WNF engine. It takes as parameters, among other things, a StateName specifying the type of event we are interested in and a Callback that will be called whenever the notification is triggered. It also returns a new Subscription pointer that can be used to query data associated with the notification.

Internally, this function only transfers execution flow to its private counterpart (ExpWnfSubscribeWnfStateChange) which handles all the processing.

As WNF State Names are stored in an opaque format, ExpWnfSubscribeWnfStateChange first decodes the "clear" version of the ID with ExpCaptureWnfStateName.

This clear WNF State Name can be decoded as follows:

#define WNF_XOR_KEY 0x41C64E6DA3BC0074

ClearStateName = StateName ^ WNF_XOR_KEY;
Version = ClearStateName & 0xf;
LifeTime = (ClearStateName >> 4) & 0x3;
DataScope = (ClearStateName >> 6) & 0xf;
IsPermanent = (ClearStateName >> 0xa) & 0x1;
Unique = ClearStateName >> 0xb;

In a more formal way, this gives the following structure:

typedef struct _WNF_STATE_NAME_INTERNAL
{
    ULONG64 Version : 4;
    ULONG64 Lifetime : 2;
    ULONG64 DataScope : 4;
    ULONG64 IsPermanent : 1;
    ULONG64 Unique : 53;
} WNF_STATE_NAME_INTERNAL, *PWNF_STATE_NAME_INTERNAL;

Then, ExpWnfSubscribeWnfStateChange calls ExpWnfResolveScopeInstance. This latter retrieves the Server Silo Globals (or nt!PspHostSiloGlobals in the case where no server silo is involved) and goes through several structures in order to find the WNF_SCOPE_INSTANCE to which the name instance belongs. If this Scope Instance doesn’t exist, it is created and added to the corresponding WNF_SCOPE_MAP list. This is shown below:

From this Scope Instance structure, ExpWnfSubscribeWnfStateChange searches (with ExpWnfLookupNameInstance) for a WNF_NAME_INSTANCE matching the given WNF State Name.

If no match is found, it creates a new WNF_NAME_INSTANCE by using ExpWnfCreateNameInstance. This new instance is added to the binary tree rooted off the WNF_SCOPE_INSTANCE.

The next step for the function is to call ExpWnfSubscribeNameInstance to create a new subscription object. As it was explained previously, this object will hold all the information that the engine needs in order to trigger notifications.

Finally, ExpWnfSubscribeWnfStateChange calls ExpWnfNotifySubscription to insert the new subscription in a pending queue and trigger a notification.

ExQueryWnfStateData

NTSTATUS
ExQueryWnfStateData (
    _In_ PWNF_SUBSCRIPTION Subscription,
    _Out_ PWNF_CHANGE_STAMP ChangeStamp,
    _Out_ PVOID OutputBuffer,
    _Out_ OPULONG OutputBufferSize
);

This function is quite simple as it only performs two actions. First it retrieves the WNF_NAME_INSTANCE from the Subscription with ExpWnfAcquireSubscriptionNameInstance. Then, it reads the data stored in it with ExpWnfReadStateData and tries to copy it in Buffer. If this buffer is too small, it will only write the size needed in OuputBufferSize and return with STATUS_BUFFER_TOO_SMALL.

For the record, all WNF State Names store their data in memory under a WNF_STATE_DATA structure. This structure holds various metadata such as the data size and the number of times it has been updated (called the ChangeStamp). A pointer to the WNF_STATE_DATA is kept directly in the WNF_NAME_INSTANCE, as shown below.

Alex would also like me to point out that WNF State Names can be marked as persistent, which means that the data (and change stamp) will be retained accross reboots (obviously by using a secondary data store). More details on this will be available in our presentation!

Looking for the right WNF State Name

As a hint for retrieving the WNF State Name, Bruce provided a link to a blog post and the name of a library (contentDeliveryManager_Utilities.dll).

In their blog entry, Redplait defined several State Names used by WNF. Unfortunately, the one we are looking for is not listed. However, that still gives us a good start, for we now know what WNF State Names look like.

One naive approach to find what we are looking for is to grep for one of the blog's WNF State Names in contentDeliveryManager_Utilities.dll and hope that other IDs will be around... Luckily, this works pretty well! By following the cross reference of the matched pattern in IDA, we can reach a full list of WNF State Names referenced in the DLL. Each entry in this list comes with its name and description which is really handy for our purposes! (For further information, this list is used by GetWellKnownWnfStateByName).

We now just have to look for the one specific to the microphone (remember the exercise? :p)

.rdata:00000001800E3680  dq offset WNF_AUDC_CAPTURE
.rdata:00000001800E3688  dq offset aWnf_audc_captu ; "WNF_AUDC_CAPTURE"
.rdata:00000001800E3690  dq offset aReportsTheNu_0 ; "Reports the number of, and process ids "...
// “Reports the number of, and process ids of all applications currently capturing audio.
//  Returns a WNF_CAPTURE_STREAM_EVENT_HEADER data structure”

It should be noted that the same table is also available with the``perf_nt_c.dll`` library that is included with Windows Performance Analyzer.

Subscribing to the event

To subscribe a new event, we just have to call ExSubscribeWnfStateChange in our driver with the WNF State Name we found out from above. This function is exported but not defined in any header, therefore we have to manually declare it ourselves by pasting the definition from above. Note that ntoskrnl.lib contains the import library stub, so there is no need to retrieve its address by hand (thanks Alex for the protip ;)).

The only thing that needs to be done here is to call the function with the right parameters:

NTSTATUS
CallExSubscribeWnfStateChange (
    VOID
    )
{
    PWNF_SUBSCRIPTION wnfSubscription= NULL;
    WNF_STATE_NATE stateName;
    NTSTATUS status;

    stateName.Data = 0x2821B2CA3BC4075; // WNF_AUDC_CAPTURE

    status = ExSubscribeWnfStateChange(&wnfSubscription, &stateName, 0x1, NULL, &notifCallback, NULL);
    if (NT_SUCCESS(status)) DbgPrint("Subscription address: %p\n", Subscription_addr);

    return status;
}

Defining the callback

As we saw previously, ExSubscribeWnfStateChange takes among its parameters a callback that will be called every time the event is triggered. This callback will be used to get and process event data relative to the notification.

The callback prototype looks like that:

NTSTATUS
notifCallback (
    _In_ PWNF_SUBSCRIPTION Subscription,
    _In_ PWNF_STATE_NAME StateName,
    _In_ ULONG SubscribedEventSet,
    _In_ WNF_CHANGE_STAMP ChangeStamp,
    _In_opt_ PWNF_TYPE_ID TypeId,
    _In_opt_ PVOID CallbackContext
    );

To obtain the data in our callback, we have to call ExQueryWnfStateDataName. Once again this function is exported but not defined in any header so we have to define it ourselves:

NTSTATUS
ExQueryWnfStateData (
    _In_ PWNF_SUBSCRIPTION Subscription,
    _Out_ PWNF_CHANGE_STAMP CurrentChangeStamp,
    _Out_writes_bytes_to_opt_(*OutputBufferSize, *OutputBufferSize) PVOID OutputBuffer,
    _Inout_ PULONG OutputBufferSize
    );
[...]

We need to call this API twice: once to get the size needed to allocate a buffer for the data and the second time to actually retrieve the data.

NTSTATUS
notifCallback(...)
{
    NTSTATUS status = STATUS_SUCCESS;
    ULONG bufferSize = 0x0;
    PVOID pStateData;
    WNF_CHANGE_STAMP changeStamp = 0;

    status = ExQueryWnfStateDataFunc(Subscription, &changeStamp, NULL, &bufferSize);
    if (status != STATUS_BUFFER_TOO_SMALL) goto Exit;

    pStateData = ExAllocatePoolWithTag(PagedPool, bufferSize, 'LULZ');
    if (pStateData == NULL) {
        status = STATUS_UNSUCCESSFUL;
        goto Exit;
    }

    status = ExQueryWnfStateDataFunc(Subscription, &changeStamp, pStateData, &bufferSize);
    if (NT_SUCCESS(status)) DbgPrint("## Data processed: %S\n", pStateData);

    [...] // do stuff with the data

Exit:
    if (pStateData != nullptr) ExFreePoolWithTag(pStateData, 'LULZ');
    return status;
}

Cleaning the mess when unloading the driver

If you blindly try the code above, you'll get an ugly blue screen of death as I painfully learnt the first time I tried the exercise and unloaded my driver! :P We need to delete our subscription beforehand.

For this purpose, we can call ExUnsubscribeWnfStateChange in the driver unload routine (and make sure that PWNF_SUBSCRIPTION wnfSubscription is made into a global variable).

PVOID
ExUnsubscribeWnfStateChange (
    _In_ PWNF_SUBSCRIPTION Subscription
    );

VOID
DriverUnload (
    _In_ PDRIVER_OBJECT DriverObject
    )
{
   [...]
   ExUnsubscribeWnfStateChange(g_WnfSubscription);
}

Quite an epic fail

All we have to do now is to start the driver, enable Cortana, play a little bit with it and wait for the event to trigger.

...

Aaaand...! Nothing!

My exercise result totally failed as I forgot that I didn't have a sound card on my Virtual Machine (probably the reason why I couldn’t start any of the sound related apps..? >.>’) and most importantly, due to my host configuration, I couldn't make it work at all (don't ask).

Still, in order to ensure that my driver works correctly I had to choose another event (sigh) and went for WNF_SHEL_DESKTOP_APPLICATION_STARTED. This notification is signaled anytime a desktop application launches. In return, it simply outputs the application name that was started. With this WNF State Name, it was pretty straightforward to get some results:

Keeping up to date with WNF

I showed earlier a simple way of looking up WNF names by just searching for the name in IDA in one of the DLLs that contains the table. A more reliable way and extensible approach would be to retrieve the WNF State Names by parsing the DLL to find the table and dumping it. Although this wasn't the approach I used in the exercise, Alex had a need for easily keeping up to date with changes in the WNF State Names (additions/removals/modifications) due to his unhealthy obsession with diff-ing every build of the kernel, and I came up with a script to help him do so.

Since I forgot to mention it at BlackHat, I feel like doing some advertising now. :-^ This script can be used to diff two DLLs and quickly get the differences in the tables, as well as just dump the table data from a single DLL. The output is one that Alex and I used for our wnftool applications, and can easily be adapted for use in other C and Python programs.

$ python .\StateNamediffer.py -h
usage: StateNamediffer.py [-h] [-dump | -diff] [-v] [-o OUTPUT] [-py]
file1 [file2]

Stupid little script to dump or diff wnf name table from dll

positional arguments:
    file1
    file2 Only used when diffing

optional arguments:
    -h, --help show this help message and exit
    -dump Dump the table into a file
    -diff Diff two tables and dump the difference into a file
    -v, --verbose Print the description of the keys
    -o OUTPUT, --output OUTPUT Output file (Default: output.txt)
    -py, --python Change the output language to python (by default it's c)

Example of output (I will publish the script once the November embargo is lifted):

typedef struct _WNF_NAME
{
    PCHAR Name;
    ULONG64 Value;
} WNF_NAME, *PWNF_NAME;

WNF_NAME g_WellKnownWnfNames[] =
{
    {"WNF_A2A_APPURIHANDLER_INSTALLED", 0x41877c2ca3bc0875}, // An app implementing windows.AppUriHandler contract has been installed
    {"WNF_AAD_DEVICE_REGISTRATION_STATUS_CHANGE", 0x41820f2ca3bc0875}, // This event is signalled when device changes status of registration in Azure Active Directory.
    {"WNF_AA_CURATED_TILE_COLLECTION_STATUS", 0x41c60f2ca3bc1075}, // Curate tile collection for all allowed apps for current AssignedAccess account has been created
    {"WNF_AA_LOCKDOWN_CHANGED", 0x41c60f2ca3bc0875}, // Mobile lockdown configuration has been changed
    [...]
}