Click Here to Download: Code Associated With This Article Zip Archive, 10KB

Every once in a while we here at OSR need to step out of the more esoteric areas of driver development to address some fundamental questions that plague neophyte driver writers everywhere. Today we’re going to talk about sharing events between a user mode application and a kernel mode driver and hopefully shed some light on this oft discussed topic.

There are a handful of different ways to share events. Some of the most popular include:

• The user-mode app creates the event, and passes the handle to the event to the driver via an IOCTL;
• The driver creates an event, and passes the handle to the event to the user mode app via an IOCTL;
• The user-mode app creates the event with a pre-determined name, which the driver then opens;
• The driver creates the event with a pre-determined name, which the user-mode app then opens.

There are advantages and (naturally) disadvantages, some of them potentially fatal, to each of these approaches.  Let’s talk about them one at a time

Sharing an Event by Handle

The implementation that seems to be everyone’s favorite is to open a handle to an event in user mode and then pass that handle to the driver via an IOCTL. Within the dispatch routine, a quick call to ObReferenceObjectByHandle(...) increments the reference count on the event (so it won’t be deleted even if the user closes it), and returns you a pointer to a KEVENT that can be used to signal the event to the user mode application. QED.  Now that you’ve solved your programming problem for the day, you pat yourself on the back and head to the break room to try and beat the ungodly scores on the pinball machines.

Well hold on there Tommy. This design has a few subtle flaws and though it will work in some cases it can fail in others. The fly doing the backstroke in this soup is a little thing called context. A user mode handle is nothing but an index into a per process handle table, so you had better be 100% sure that you call ObReferenceObjectByHandle within the application’s process context. There are situations in which you are absolutely sure of this (for extra credit, name two such situations). If, on the other hand, your driver happens to be in the middle of a stack of other drivers and doesn’t directly export a named device object, you really can’t be sure of the context in which your dispatch routine is running. Not to mention the fact that if you follow Microsoft doctrine and use IoRegisterDeviceInterface(…), then IRPs will go to the top of the stack that your device object is in. So if you’re a filter driver sitting just above the disk port driver and you export a device interface, the requests that are sent to that device interface (i.e. “directly to you”) go to the top of the stack…thus you can be in an arbitrary context when you get the IOCTL.

For the sake of argument let’s say that you know that you’re in the correct context because you’re a legacy device driver that has exported a named device object and so your dispatch routine is guaranteed to be in the calling processes’ context. The next thing you need to make sure of is that you correctly use ObReferenceObjectByHandle. The optional ObjectType parameter should be set to *ExEventObjectType.  This will prevent a malicious user from passing something other than an event handle and simply return STATUS_OBJECT_TYPE_ MISMATCH if the handle is not an event.  There’s a funny story about why this parameter is optional. Well, at least I hope there is since I can’t see any reason why you wouldn’t want to validate what kind of handle you have. The other parameter that you need to be aware of is the AccessMode parameter, which should be set to UserMode. What this will do for you is check to make sure that the calling application has sufficient access to this handle; yet another reason to make absolutely sure that you are in the calling processes’ context. So, assuming that the above steps are followed, this option isn’t a bad option but I’m not picking up the whole check at the end of this date, if you know what I mean.

Note that the inverse of this implementation, opening an event in kernel mode and passing down a handle for use in user mode, is an absolutely terrible idea. The first hurdle you’d encounter would be trying to convert the pointer to a KEVENT object returned from IoCreateNotification Event(…) into a HANDLE value with a proper reference count and that a user mode application could use. Why not just use the handle returned by IoCreateNotification Event(…)?  Well, for one reason, because (at least as of Windows .NET) the handle that is returned is a kernel mode only handle!  Of course, you could put yourself through the pain of trying to get a proper handle to return, but the necessary APIs are not documented.  So, you see, the entire process is sort of like trying to solve your pest problem by throwing a disco party. It just doesn’t make much sense and when it’s all over you’re going to be left standing in the middle of a big mess. I’d highly recommend choosing another implementation approach.

Sharing Events by Name

So, tall drink of water with a bowl cut, how the heck else can my app and driver share an event if I don’t share a handle? Actually, it’s quite simple. While handles are extremely volatile and should generally not be trusted, there’s no reason why a user mode app can’t create a named event that you then open from within your driver. This implementation is devoid of all of the restrictions of the previous implementation approaches since context is no longer an issue. Named objects within the object manager are available from all process contexts and carry the security attributes with them, so there is no need to check the permissions within the calling application’s context. This makes this implementation even more appealing because you’ll be able to use it in any driver that you write and not have to worry about whether or not your current driver project adheres to all of the restrictions of the previous implementation.

Enough talk already.  Let’s see some code to demonstrate sharing an event by name. To create the event in user mode we use the SDK function CreateEvent(…)

SharedEvent = CreateEvent(NULL, TRUE, FALSE, "SharedEvent");

If our call to CreateEvent succeeded we should be able to see our named event within the object manager. There are several utilities that will allow you to do this but I’ll shamelessly suggest OSR’s ObjDir (available free at www.osr.com/ resources_downloads.shtml). When you create an event in user mode, it’s put in the \BaseNamedObjects directory, so that’s where you’re going to need to go to look for it. Figure 1 shows what it looked like when I ran it on my system

As you can see, my event SharedEvent has been created.

So there you have it. You can now use the variable SharedEvent as a parameter to KeSetEvent(…), which will signal your user mode event handle.

Create the Event in Kernel Mode?

Now there’s only one question left to ask: Is the inverse of this last implementation – creating the named event in kernel mode and opening it in user mode – an absolutely terrible idea also? The definitive answer to this question is, of course, “sort of”. First of all you’d need to make sure that the event is created under \BaseNamedObjects, which we’ve already seen how to do since IoCreateNotificationEvent will create the event if it doesn’t already exist. One caveat to remember: if your driver is going to be loaded at boot time, it’ll be loaded before Win32, which creates the BaseNamedObjects directory. Should you try to create your event in your DriverEntry routine before Win32 initializes, you’re probably not going to end up with the results that you expected.

Then there’s the issue of security.  You’ll notice that IoCreateNotificationEvent doesn’t have a parameter to specify the security attributes of the event and so the security applied to the event is that of the current thread. That means that if you are running in the context of the system process when you create the event (as you will be during DriverEntry, AddDevice, and at several other times) a user application will need to be running under the Administrator account in order to be able to access the event.

But who cares really? If the user creates the event then they have access to it (I’ll have to verify this through intense “objective external analysis”  but I’m pretty sure it’s the case), and because your driver is privileged it’s not going to get hassled when it attempts to get a reference to the object. Since there’s no benefit at all to creating the event in kernel mode, just have the app create it and you’ll be able to get back to working on your pinball scores in no time.

Full source code for a driver that opens a named event previously created in a user mode application can be downloaded from the link at the beginning of this article.