DetourCreateProcessWithDllEx

Microsoft Research Detours

DetourCreateProcessWithDllEx

Create a new process and load a DLL into it. Chooses the appropriate 32-bit or 64-bit DLL based on the target process.

Definition

BOOL DetourCreateProcessWithDllEx(
    _In_opt_    LPCTSTR lpApplicationName,
    _Inout_opt_ LPTSTR lpCommandLine,
    _In_opt_    LPSECURITY_ATTRIBUTES lpProcessAttributes,
    _In_opt_    LPSECURITY_ATTRIBUTES lpThreadAttributes,
    _In_        BOOL bInheritHandles,
    _In_        DWORD dwCreationFlags,
    _In_opt_    LPVOID lpEnvironment,
    _In_opt_    LPCTSTR lpCurrentDirectory,
    _In_        LPSTARTUPINFOW lpStartupInfo,
    _Out_       LPPROCESS_INFORMATION lpProcessInformation,
    _In_        LPCSTR lpDllName,
    _In_opt_    PDETOUR_CREATE_PROCESS_ROUTINEW pfCreateProcessW
    );

Parameters

lpApplicationName: Application name as defined for CreateProcess API.
lpCommandLine: Command line as defined for CreateProcess API.
lpProcessAttributes: Process attributes as defined for CreateProcess API.
lpThreadAttributes: Thread attributes as defined for CreateProcess API.
bInheritHandles: Inherit handle flags as defined for CreateProcess API.
dwCreationFlags: Creation flags as defined for CreateProcess API.
lpEnvironment: Process environment variables as defined for CreateProcess API.
lpCurrentDirectory: Process current directory as defined for CreateProcess API.
lpStartupInfo: Process startup information as defined for CreateProcess API.
lpProcessInformation: Process handle information as defined for CreateProcess API.
lpDllName: Pathname of the DLL to be insert into the new process. To support both 32-bit and 64-bit applications, The DLL name should end with "32" if the DLL contains 32-bit code and should end with "64" if the DLL contains 64-bit code. If the target process differs in size from the parent process, Detours will automatically replace "32" with "64" or "64" with "32" in the path name.
pfCreateProcessW: Pointer to program specific replacement for the CreateProcess API, or NULL if the standard CreateProcess API should be used to create the new process.

Return value

Returns TRUE if the new process was created; otherwise returns FALSE.

Error codes

See error code returned from CreateProcess.

Remarks

DetourCreateProcessWithDllEx creates a new process with the specified DLL inserted into it.

The process is created in a suspended state with the CREATE_SUSPENDED flag to CreateProcess. Detours then modifies the image of the application binary in the new process to include the specified DLL as its first import. Execution in the process is then resumed. When execution resumes, the Windows process loader will first load the target DLL and then any other DLLs in the application's import table, before calling the application entry point.

DetourCreateProcessWithDllEx modifies the in-memory import table of the target PE binary program in the new process it creates. The updated import table will contain a reference to function ordinal #1 exported from the target DLL. If the target process is 32-bit and the parent process is 64-bit, or if the target process is 64-bit and the parent process is 32-bit, DetourCreateProcessWithDllEx will use rundll32.exe to load the DLL into a helper process that matches the target process temporarily in order to update the target processes import table with the correct DLL.

Note: The new process will fail to start if the target DLL does not contain a exported function with ordinal #1.

After the target DLL has been loaded, it can reverse changes to the in-memory import table by calling DetourRestoreAfterWith. To facilitate reversing these changes, DetourCreateProcessWithDllEx copies relevant reversal data into a payload in the target process using the DetourCopyPayloadToProcess API. The loaded DLL should call the DetourRestoreAfterWith API to restores the contents of the import table.

previous page start next page

DetourCreateProcessWithDllEx

Microsoft Research Detours