About IRP_MJ_CREATE and minifilter design considerations - Part II

Since we've discussed the concepts last time we can finally start looking at the debugger. Because we're mostly interested in the create operation from a filter perspective, I put a breakpoint on fltmgr!FltpCreate so that we can see exactly what the stack looks like when the request reaches a filter. Let's say we're trying open the file "C:\Foo\Bar.txt". Here is what the stack looks like.

00 9b5c5a70 828484bc fltmgr!FltpCreate
01 9b5c5a88 82a4c6ad nt!IofCallDriver+0x63
02 9b5c5b60 82a2d26b nt!IopParseDevice+0xed7
03 9b5c5bdc 82a532d9 nt!ObpLookupObjectName+0x4fa
04 9b5c5c38 82a4b62b nt!ObOpenObjectByName+0x165
05 9b5c5cb4 82a56f42 nt!IopCreateFile+0x673
06 9b5c5d00 8284f44a nt!NtCreateFile+0x34

In order to discuss the flow of the IO through the OS we're going to look at what each of these functions does.

nt!NtCreateFile

This is how the OS receives a request to open a file or a device (at this level there is no distinction between the two yet). NtCreateFile doesn't really do much, it's just a wrapper over an internal OS function (IopCreateFile). The file name here is something like "\??\C:\Foo\Bar.txt".

nt!IopCreateFile

This is the function to open a device (or a file) at the IO manager level. This is an internal function where most requests to open a file or a device end up (NtOpenFile, IoCreateFile and friends and so on). This is what happens here:

1. The parameters for the operation are validated and checked to see if they make sense. Here is where STATUS_INVALID_PARAMETER is returned if you do something like ask for DELETE_ON_CLOSE but not ask for DELETE access… There are a lot of checks to validate the parameters, but no actual security or sharing checks.
   
2. A very important structure is allocated, the OPEN_PACKET. This is an internal structure to the IO manager and it is the context that the IO manager has for this create. The create parameters are copied in initially. This is a structure that's available in the debugger:
   

   1: kd> dt nt!_OPEN_PACKET
       +0x000 Type             : Int2B
       +0x002 Size             : Int2B
       +0x004 FileObject       : Ptr32 _FILE_OBJECT
       +0x008 FinalStatus      : Int4B
       +0x00c Information      : Uint4B
       +0x010 ParseCheck       : Uint4B
       +0x014 RelatedFileObject : Ptr32 _FILE_OBJECT
       +0x018 OriginalAttributes : Ptr32 _OBJECT_ATTRIBUTES
       +0x020 AllocationSize   : _LARGE_INTEGER
       +0x028 CreateOptions    : Uint4B
       +0x02c FileAttributes   : Uint2B
       +0x02e ShareAccess      : Uint2B
       +0x030 EaBuffer         : Ptr32 Void
       +0x034 EaLength         : Uint4B
       +0x038 Options          : Uint4B
       +0x03c Disposition      : Uint4B
       +0x040 BasicInformation : Ptr32 _FILE_BASIC_INFORMATION
       +0x044 NetworkInformation : Ptr32 _FILE_NETWORK_OPEN_INFORMATION
       +0x048 CreateFileType   : _CREATE_FILE_TYPE
       +0x04c MailslotOrPipeParameters : Ptr32 Void
       +0x050 Override         : UChar
       +0x051 QueryOnly        : UChar
       +0x052 DeleteOnly       : UChar
       +0x053 FullAttributes   : UChar
       +0x054 LocalFileObject  : Ptr32 _DUMMY_FILE_OBJECT
       +0x058 InternalFlags    : Uint4B
       +0x05c DriverCreateContext : _IO_DRIVER_CREATE_CONTEXT
    

   This structure is pretty important to the flow of the IO operation but there is no way to access it as a developer so it's going to be just an important concept to remember later on.
   
3. Finally, since we've copied all internal parameters and all the IO manager has at this point is an OB manager path (in the ObjectAttributes paramater to the call), it must call the OB manager to open the device (ObOpenObjectByName, see below).
   
4. After ObOpenObjectByName returns this function cleans up and returns.
   

nt!ObOpenObjectByName

This the call to have the OB manager create a handle for object when we know the name. This isn't a public interface since 3rd party drivers only need to open objects that have their own create or open APIs (for example ZwCreateFile, ZwOpenKey, ZwOpenSection, ZwCreateSection, ZwOpenProcess and so on). Another thing to note about the OB APIs is that they fall largely into two classes:

1. Functions that reference objects (that just operate on the reference count of objects), like ObReferenceObject, ObReferenceObjectByName and ObReferenceObjectByPointer.
   
2. Function that create handles to object in addition to referencing them (which is called an "open"), like ObOpenObjectByName and ObOpenObjectByPointer.
   

Anyway, this is roughly what goes on in here:

1. Capture the security context for this open, so that whoever needs to open the actual object can perform access checks. This also means that the file system itself doesn't rely on the thread context being the same and instead uses the context captured here. So minifilters should to the same when they care about the security context of a create.
   
2. Call the actual function that looks up the path in the namespace (ObpLookupObjectName, see below)
   
3. If ObpLookupObjectName was able to find an object then a handle is created for that object (since this was an open type function).
   

nt!ObpLookupObjectName

This is the function where the OB manager actually looks in the namespace for the path it needs to open (which at this point is still "\??\C:\Foo\Bar.txt"). One thing to note is that the OB namespace has a hierarchical structure, with DIRECTORY_OBJECT types of objects that hold other objects. The root of the namespace ("\") is such a DIRECTORY_OBJECT.
Anyway this is what happens in this function. The parsing starts at the root at the namespace, "\". This is a loop until we find the final object to return to the user or find that there is no object by that name (and therefore fail the request):

1. If the current directory is the root directory then check if the name starts with "\??\" and make it point to the \GLOBAL?? directory. This is a hardcoded hack in IO manager (which is why calling "!object \" in WinDbg doesn't show a "??" folder). (so our name becomes "\GLOBAL??\C:\Foo\Bar.txt")
   
2. Find the first component in the path (which is GLOBAL??) in the current directory.
   
3. If the component found is a DIRECTORY_OBJECT, open it and continue parsing from that point using the rest of the name (in our case, "C:\Foo\Bar.txt" is the remaining name). Continue the loop with remaining path.
   
4. if the object has a parse procedure, call that parse procedure and give it the rest of the path. if the parse procedure returns STATUS_REPARSE (and it hasn't reparsed too many times already), start again at the root of the namespace with the new name returned by the parse procedude. Otherwise the parse procedure should either return STATUS_SUCCESS and return an object or a failure status.
   

Some notable things are:

• OB will do a case sensitive or a case insensitive search of the OB namespace, depending on the OBJ_CASE_INSENSITIVE flag that is passed into the OBJECT_ATTRIBUTES, which is why it's important to set this correctly when calling FltCreateFile in a filter (specifically from a NormalizeNameComponent callback) since if it's not correctly set the request might not make it down the IO stack at all
  
• the OB namespace uses symlinks quite a lot. OB symlinks are a special type of object that has a string member that points to a different point in the namespace, and a parse procedure:
  

  0: kd> dt _OBJECT_SYMBOLIC_LINK
   nt!_OBJECT_SYMBOLIC_LINK
      +0x000 CreationTime     : _LARGE_INTEGER
      +0x008 LinkTarget       : _UNICODE_STRING
      +0x010 DosDeviceDriveIndex : Uint4B
   

  So in our example, when OB gets to "\GLOBAL??\C:" it discovers it is a symlink and it calls the parse procedure with the rest of the remaining name ("\Foo\Bar.txt"). In The symlink for "\GLOBAL??\C:" points to "\Device\HarddiskVolume2" and the symlink's parse procedure concatenates that name with the remaining path that it got and so the new name after the symlink is "\Device\HarddiskVolume2\Foo\Bar". See this:
  

  0: kd> !object \GLOBAL??\C:
   Object: 96f7f188  Type: (922b7f78) SymbolicLink
       ObjectHeader: 96f7f170 (new version)
       HandleCount: 0  PointerCount: 1
       Directory Object: 96e08f38  Name: C:
       Target String is '\Device\HarddiskVolume2'
       Drive Letter Index is 3 (C:)
   

  The parse procedure of a symlink always returns STATUS_REPARSE.
  
• Once we get to the "\Device\HarddiskVolume2\Foo\Bar.txt" path, while parsing OB will find that "\Device\HarddiskVolume2" is a DEVICE_OBJECT type of object and that it has a parse procedure. The parse procedure for a DEVICE_OBJECT is IopParseDevice, so that function gets called.
  
• Another thing to note that there is a limit to the number of times OB will reparse and each time it sees a STATUS_REPARSE counts against that limit (so it doesn't matter whether it was a reparse from a symlink or a DEVICE_OBJECT, everything counts). So it is possible to reparse to the point where OB won't reparse anymore.
  

nt!IopParseDevice

The name here is just "\Foo\Bar.txt" and the parse procedure gets a reference to the device where the path should be searched. This is where the difference between a file and a device becomes relevant. If there is no remaining path, this is treated as an open to the device. If there is a path, then this is assumed to be a file (or directory) open. This is a pretty involved function with many special cases. However, there are only a couple of steps that we're going to talk about:

1. Get the context for this create, which is the OPEN_PACKET structure from before. This works because the OPEN_PACKET is IO manager's structure passed from IopCreateFile to IopParseDevice. This is important because this is a nice way to have context across calls through other subsystems (OB manager) and still keep context that is opaque to those subsystems. This isn't always the case unfortunately and whenever two subsystems share the same structure the architecture gets complicated.
   
2. Check to see if a file system is mounted on this device and if not then mount it.
   
3. Process the device hint if there was any.
   
4. Allocate the IRP_MJ_CREATE irp
   
5. Allocate the FILE_OBJECT that will represent the open file.
   
6. Call the FastIoQueryOpen function (which minifilters see as the IRP_MJ_NETWORK_QUERY_OPEN). The IRP parameter to this call is the IRP that was just allocated.
   
7. If the FastIoQueryOpen didn't work, send the full Irp to the file system stack by calling IoCallDriver.
   
8. Wait for IRP to complete (i.e. the IRP is synchronized by the IO manager).
   
9. If the request was a STATUS_REPARSE, then first check if it is a directory junction or a symlink and do some additional processing for those. Anyway, copy the new name to open from the FILE_OBJECT (the actual name to open is passed in and out this function through a parameter).
   
10. If the status from the Irp was not a success status or it was a STATUS_REPARSE, cleanup the FILE_OBJECT and release the references associated with it. The irp is always released anyway.
    
11. Return the status. If this was successful, the FILE_OBJECT will be the one used to represent the file.
    

This is a pretty high level view of the process but it should explain why some of the things we're going to talk in future posts work the way they do.