Detours Introduction


Click here to change the theme.

Microsoft Detours is a project of Microsoft Research. Detours can be used to intercept function calls to any DLL in the system and in any process. The technology used by Detours is patented by Microsoft (see Patent US20100095281 - Internal Function Debugger). There are both a Detours Professional and a Detours Express. Detours Professional must be purchased and is expensive but includes a commercial use license that allows its use in commercial products. Detours Express is free and has less features than the proessional edition.

Do you need to intercept native calls to Windows API functions such as MessageBox and alter what is done by that call? For example, you could change the text of the message or the MessageBox caption. Or you could change the name of a file to be opened; not the file itself, but the filename that is to be opened. Or perhaps you simply need to know what file that some other software is using. Detours can do that plus much more. If you have software that draws text graphically and you need to grab that text programmatically, Detours can do that. Detours is unrelated to hooks such as what is installed using SetWindowsHookEx.

Detours is very powerful and equally dangerous. It is complex and highly technical. I don't understand the internals of how it does what it does. To use Detours, you must have an understanding of how Windows works at the Windows API level at least. You need to understand how native Windows DLLs work. If your understanding of what a DLL is is that a DLL is something you add to a project by creating a refence, then you need to learn more about DLLs before you can use Detours.

Interception code can be injected into a process during execution using code that is similar to the Windows API function CreateRemoteThread. The injected code actually is a DLL and the
DllMain function exeuctes in the other thread. The DllMain function sets up one or more detours which intercept calls to specified "target functions". When detoured, calls (from a "source function") to the target function are redirected to a "detour function". The address of the detoured function is saved (in a "trampoline function") so that the detour function can call the original detoured function before and/or after doing whatever the detour function needs to do.

Detours is primarily used to intercept calls to native DLLs. The Windows API is an example of native DLLs; most of the API exists in a few DLLs. Normally, the source function (in the calling program) calls the target function in a DLL and the DLL function executes then returns control back to the calling program. The normal flow without Detours would generally be:

  1. Source function
  2. Target function
  3. Source function

In other words, the DLL function is called. When a function is intercepted using Detours, the flow would generally be:

  1. Source function
  2. Detour function
  3. [Optional] Trampoline (Target) function
  4. Detour function
  5. Source function

As stated above, the call from the Detour function to the Trampoline (Target) function is optional; the Detour function can entirely replace the Target function simply by not calling the Trampoline. In that case, the flow would generally be:

  1. Source function
  2. Detour function
  3. Source function

If the Detour function does not call the Target function then the Detour can provide totally different behavior without making any changes whatsoever to the Source function software.

To intercept a call occuring in another process, a Detour function must exist in a native DLL with unmanaged code. Since injected code must exist in a native DLL, it is not possible to make a DLL with managed code that is to to be injected into another process. It is possible however to use Platform Iinvoke to call the functions that create Detours. Also, Detours can actually be useful for intercepting calls to a DLL from within the same process that creates the Detour. This article includes a simple sample use of Detours from managed code that sets up a managed code function as a Detour so you can use entirely managed code to experience how awesome Detours is.

Installing Detours

To use Detours, you must download and install it. You also need to build it; the source code for Detours is provided but the executable is not provided. After installing Detours, open the README.TXT file for build instructions. It says that you need to copy the entire contents of the detours directory to somewhere else that you have write access. Then you need to open a command prompt, execute the vcvars32.bat file in the Visual C++ bin directory to update the path environment variable. Then change the current directory to the directory that you copied Detours to. Then use the command "nmake". You should get a large amount of messages sent to the console window. The build will execute for approximately a couple of minutes. All of this is relatively crude; it is not the friendliest way to install software.

Definitions

When I first learned about Detours, the terminology was confusing. I was not sure what a trampoline is. I hope this article helps make that clear.

target function
function to intercept
detour function
function that is called instead of the target function
trampoline function
the original function that the detour function can (and usually does) call