c-apiworks-dwflags.txt

Cracker终结者——提供最优秀的软件保护技术

  dwFlags are:
  *) attributes for PE hooking: HOOK_LOAD_IMPORT, HOOK_LOAD_EXPORT, HOOK_SPECIAL
  *) attributes for code/PE hooking: HOOK_HARD, HOOK_NOT_9X, HOOK_NOT_NT
  *) flags for PE hooking: HOOK_BY_NAME, HOOK_BY_ADDRESS,
                           HOOK_OVERWRITE, HOOK_ALL_SAFE, HOOK_EXPORT
  *) flags for code hooking: HOOK_RAW


  HOOK_OVERWRITE/RAW has higher priority than PE hooking flags (these are ignored).


  Hooks aren't reapplied when location to change points to HookAddress already
  -> prevents double hooking partially. Partially means: as long as our hooks
  aren't overhooked by other hooking program, they aren't hooked.
  


  dwFlags member of API_HOOK structure can be:

  XXXX << 16      (e.g. 0, 0x12340000) ignore this API_HOOK structure (and go on with
                  the next),

  otherwise it can be a combination of the following flags (attributes):


  HOOK_BY_NAME    changes address of ApiNameOrOrd
                  in ModuleImport's import (ModuleImport.PE.IAT).
                  ApiNameOrOrd is found according to API name/ordinal number match
                  (ModuleImport's APIname table must be correct, which is not true
                  for e.g. Delphi and packed modules). If ModuleExport == MAIN_MODULE,
                  HOOK_BY_NAME is ignored (you can use ModuleExport == main module
                  name instead, e.g. ModuleExport == "winword.exe").

                 Examples:
                  1) You want to hook lstrcmpi. Then this and only this API will
                  be hooked in ModuleImport. Doesn't matter if other APIs have
                  the same original address (case of lstrcmpiA API).  

                  2) You want to hook ZwClose. Then this and only this API will
                  be hooked in ModuleImport. Doesn't matter if other APIs have
                  the same original address (case of NtClose).

                 Note: Some PE modules (e.g. packed, crypted or produced by Delphi
                  or MS LINK version < 3.00) don't have "Import Address Table Directory"
                  (=APIname table). Such a modules cannot be hooked using HOOK_BY_NAME.

  HOOK_BY_ADDRESS changes address of ApiNameOrOrd in ModuleImport's import
                  (ModuleImport.PE.IAT).
                  ApiNameOrOrd is found according address match (GetProcAddress (GPA)
                  is called) - this hook type fails in Win9x when Target is debugged.
                  Because standard GPA is used, it is not possible to hook 9x KERNEL32
                  APIs specified by ordinal - GPA is cripled). 

                  HOOK_BY_ADDRESS can be used together with HOOK_BY_NAME.

                 Examples:
                  1) You want to hook lstrcmpi. Then this API and then all other APIs
                  with the same address (lstrcmpiA) will be hooked in ModuleImport.

                  2) You want to hook ZwClose. Then this API and then all other APIs
                  with the same address (NtClose) will be hooked in ModuleImport.

  HOOK_HARD       attribute ignored in NT. Developer tells ApiWorks he knows of the fact
                  that this hook can affect more processes (hook is global).
                  When there's need to change IAT (BY_NAME, BY_ADDRESS) or API-beginning
                  (OVERWRITE) lying in shared section or above 2GB, HOOK_HARD attribute must
                  be specified.
                  When hook type is RAW, AH can't estimate if place to change lies within
                  shared section - be aware of it. 
                  Example: Win9x's WINSPOOL.DRV has IAT in shareable section. It is hooked
                  only if HOOK_HARD is set in dwFlags.
                  Also for hooking modules lying above 2GB (system DLLs) in Windows 9x
                  HOOK_HARD attribute must be used (see 9xGlobal section later in this text).
                  When HOOK_OVERWRITE/RAW+HOOK_HARD was specified and the hooked location
                  lies above 2GB, calls from all modules from all processes to this
                  API/location are intercepted.                

  HOOK_LOAD_IMPORT use when you want to load ModuleImport immediatelly before
                  hooks application. ModuleImport is loaded (via LoadLibraryA) only if there
                  is also HOOK_BY_NAME or HOOK_BY_ADDRESS among dwFlags: if there's only
                  HOOK_BY_ADDRESS, the module is loaded only if ModuleExport.ApiNameOrOrd
                  in the appropriate API_HOOK exists; if there's only HOOK_BY_NAME,
                  ModuleImport is preloaded always.
                  ModuleImport can be specified with PathTo. Note that ModuleImport
                  specified with PathTo needn't be in Target's search path. You can
                  specify this dwFlag only once in one (1st) API_HOOK structure containing
                  wanted ModuleImport.
                  ModuleImport is loaded after Hooks_DLL's DllMain(DLL_PROCESS_ATTACH).
                  If you want to load it before DllMain, Hooks_DLL must import from it (but
                  you risk that Hooks_DLL will not be loaded due to ModuleImport impresence).

  HOOK_SPECIAL    ignored in NT. In 9X zeroes HOOK_BY_ADDRESS flag.
                  Useful when hooking APIs which share address but not parameter
                  types with other APIs (observed in retail builds of 9X only).

  HOOK_NOT_NT     ignore this API_HOOK structure in NT and go on with the next.
                  = Hook is aplied in 9X only. 

  HOOK_NOT_9X     ignore this API_HOOK structure in 9X and go on with the next.
                  = Hook is aplied in NT only. 

  HOOK_OVERWRITE  other hooking method. It can't be combined with HOOK_BY_NAME or
                  HOOK_BY_ADDRESS. Location to hook is found using GetProcAddress.
                  If GPA fails (e.g. in case of 9x KERNEL32 API specified by ordinal)
                  location is found using OWN GetProcAddress. OWN GPA is not able to
                  resolve forwarded APIs yet - don't use it on them.
                  See OverWrite section later in this text. 

  HOOK_RAW        allows HOOK_OVERWRITE-like hooking of non-PE-exported code. It can't
                  be combined with HOOK_BY_NAME or HOOK_BY_ADDRESS.
                  Useful for hooking using symbols.
                  See Examples\C-ApiWorks\ASM\HOOK_RAW.

  HOOK_ALL_SAFE   try to hook using HOOK_OVERWRITE;
                  If hooking using HOOK_OVERWRITE fails
                  (e.g. *) API is not overwritable (see OverWrite section below).
                        *) Heap memory can't be allocated.
                        *) OS is Win9x and API lies above 2GB or in shareable memory.
                  ) 
                  try to hook using (HOOK_BY_NAME | HOOK_BY_ADDRESS) && (ModuleImport = ALL_MODULES)
                  ApiHookChain must lie within writable memory - API_HOOK containing
                  HOOK_ALL_SAFE is filled according to used hook type.
                  Suitable for soft in-process intercepting of ModuleExport.ApiNameOrOrd.
                  See Examples\C-ApiWorks\C\GlobalC.

  HOOK_LOAD_EXPORT use when you want to load ModuleExport immediatelly before
                  hooks application. ModuleExport is loaded (via LoadLibraryA) only if hook
                  was not ruled out by HOOK_NOT_NT or HOOK_NOT_9X dwFlags.
                  ModuleExport can be specified with PathTo. Note that ModuleExport
                  specified with PathTo needn't be in Target's search path. You can
                  specify this dwFlag only once in one (1st) API_HOOK structure containing
                  wanted ModuleExport.
                  ModuleExport is loaded after Hooks_DLL's DllMain(DLL_PROCESS_ATTACH).
                  If you want to load it before DllMain, Hooks_DLL must import from it (but
                  you risk that Hooks_DLL will not be loaded due to ModuleExport impresence).
                  In the case of HOOK_ALL_SAFE resulting to HOOK_BY_ADDRESS | HOOK_BY_NAME
                  is ModuleExport loaded twice.

  HOOK_EXPORT     "undocumented" dwFlag. ModuleExport.PE.EAT is changed so that it points
                  to HookAddress. It is impossible to unhook this hook type (Hooks_DLL
                  can be unloaded due to process termination only; in case of HARD hook
                  must be Hooks_DLL never unloaded!). Use this flag besides HOOK_ALL_SAFE
                  when you resign on unhooking. This hook will be applied when the API/code
                  is not overwriteable due to instruction design. CallOrigFn fails with
                  ErrorAMApi when there's HOOK_EXPORT but no HOOK_OVERWRITE/RAW set in dwFlags.

-----------------------
  9X abnormalities:

               A) Nonwriteable sections of modules lying above 2GB in 9X can't be
                  modified normally. These modules are visible to every process and
                  their change would affect any (new) process. Specify HOOK_HARD
                  attribute in dwFlags to force modification of such modules. Then
                  your Hooks_DLL should be also loaded above 2GB (see 9xGlobal section).

               B) Some APIs in 9X retail builds (typically APIs which set LastError to
                  ERROR_CALL_NOT_IMPLEMENTED; it means 98% of *W functions and also 
                  some NT only functions like Get*Times, VirtualAllocEx,...) share the
                  same address and parameters number but not parameter types. This is
                  serious problem when you want to work with parameters (and for example
                  emulate the API). Specify HOOK_SPECIAL in dwFlags to be sure the parameter
                  types are what you expect.

                 Examples:
                  1) You want to hook WriteConsoleW. It is supported by NT so it should
                  be hooked as HOOK_BY_ADDRESS. However, in 9X would HOOK_BY_ADDRESS
                  hook also VirtualAllocEx, GetProcTimes, GetThreadTimes,...
                  You can't distinguish which function was called (parameter types
                  are undefined) in retail build of 9X -> you can't work with parameters.
                  HOOK_SPECIAL ensures that only WriteConsoleW is hooked and parameters
                  types are correct.

-----------------------
  9xGlobal:

  Because system libraries (KERNEL32, USER32, GDI32, ADVAPI32, ...) of
Windows 9x are located in the shared area between 2 and 3 GB it is not
possible to hook them normally (VirtualProtect and WriteProcessMemory
fail on read-only sections). 
  When HOOK_HARD attribute is used (of course together with other flags)
then 9x libraries lying >= 2GB and modules having code/PE.IAT in shared sections
can be hooked. The changes are visible to every process where hooked module is loaded.
  9xGlobal Hooks_DLL can be used as single process Hooks_DLL in NT usually.

  What does it mean?
1) Hooks_DLL must be located in shared memory. 
   Such a DLL can be created as follows:
    a) All writeable PE sections must have SHARED flag (0x010000000) set.
    b) Image base must be in <0x80000000 .. 0xC0000000) interval.
2) Hooks are global.
   Handles and other process specific "values" (like heaps) can't be used.
   Code/data below 2GB can be called/accessed only if they exist there.
3) Unhooking is required when Hooks_DLL is unloaded.
4) It is not good to mix 9x global hooks with local hooks in one Hooks_DLL.
5) HOOK_OVERWRITE or HOOK_RAW should be used for safe unhooking.
6) If Hooks_DLL contains global hooks only, it is good to load it into
   KERNEL32.DLL process (can't be terminated).
7) Hooks_DLL must be compiled with none/own startupcode only, because it
   may get more DLL_PROCESS_* notifications that may confuse default
   startup code (C, Delphi startup codes reset initialized pointers -> crash).

  Even APIs/code in Win9x nonshared libraries (e.g. winsock, shell32,..) can be
hooked globally. It is done via hooking CallProgramEntry in KERNEL32.DLL.
This hook then checks all calls to module-entries (~ DllMain, WinMain) and
applies nonshared hooks whenever appropriate module is loaded.
See Examples\F-Advanced\C\WSLogHARD.

-----------------------
  OverWrite:

  ApiHooks offers OVERWRITE/RAW method of hooking: overwriting the beginning
of API by JMP NewAPI - such a hook is not module selective. Then it is possible
to intercept all calls to API, including internal calls. If developer wants this
method, specifies HOOK_OVERWRITE/RAW among/in API_HOOK.dwFlags. Effect can be compared
with HOOK_BY_NAME + HOOK_BY_ADDRESS + ALL_MODULES + intramodule_calls, so HOOK_OVERWRITE
can't be used for module selective hooks. HOOK_OVERWRITE/RAW is the only method which will
work with running process (-o switch) where some modules were packed. Combinations with
HOOK_BY_NAME and HOOK_BY_ADDRESS flags are senseless. On the other hand HOOK_OVERWRITE/RAW
can be combined with HOOK_NOT_9X, HOOK_NOT_NT and HOOK_HARD.
Because API address remains constant, unhooking is always safe. In case of global hooks,
pointer-to-routine-to-jump-to-original-API must be non-NULL (routine must be above 2GB).
  When there's HOOK_OVERWRITE/RAW among/in API_HOOK.dwFlags, API_HOOK.ModuleImport is
thought as pointer to pointer-to-original API. Only pointer-to-original-API must
be used for calling original API in HOOK_OVERWRITE case. Jumping-to/calling original
API via import table is possible only from non-HOOK_OVERWRITE/RAW-NewApi. The same would,
in the case of HOOK_OVERWRITE/RAW, cause infinite cycle or stack overflow (JMP/CALL<->JMP).
 ApiHooks uses for HOOK_OVERWRITE/RAW disassembler similar to the one in MS Research Detours
package (but strongly enhanced).

Requirements:
 *) Exported API must be code only (= not data, like is possible in other
    hook types).
 *) API must be at least 5 bytes long. Region <API-8 .. API+8> must be accessible.
 *) Several 1st instructions of API shouldn't contain many prefixes.
 *) 2nd to 5th byte of API mustn't be target of any instruction. This is the case of
    some of Win9x(retail) GDI32 and USER32 APIs! (e.g. 9x GDI32.EndPage will not be
    overwritten for safety!).
 *) Supported are Intel Pentium III- instructions.

Notes:
 *) If there's short JMP, RET, RET XX or INT 3 among several 1st instructions of API,
    API is evaluated as short and will not be hooked. This is case of most
    of Win9x(retail) GDI32 and USER32 APIs! (e.g. 9x(retail) GDI32.EndDoc and many other
    APIs will not be overwritten for safety!).
 *) API shouldn't be of 9X ERROR_CALL_NOT_IMPLEMENTED type (= unknown API,
    undefined parameters types).
 *) LOOP* and JECXZ translation is not perfect - affects Flags
    (also don't forget to restore CPU Flags before LOOPNZ/E, /LOOPZ/E).