a-core.txt

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

  ApiHooks' core contains code that can execute user code (Scout) in the context
of specified process (Target) and wait for result for given time (ExpTime):

1) Scout is copied to local memory and fixed.

2) If Target == CurrentProcess
     2a) (ExpTime is ignored) and (current thread executes fixed Scout).
     2b) When RCINFO.RCFlags.RC_FL_OWNFREE wasn't set, local memory (ThreadBody) is freed.
   Else
     2a) Target is opened.
     2b) Memory (ThreadBody) is allocated in Target.
     2c) Fixed Scout is copied to ThreadBody.
     2d) Remote thread is created in Target and executes Scout.
     2e) AH waits for ExpTime for thread to be signaled (for thread "return").
     2f) According to result and RCINFO.RCFlags is thread terminated
         and ThreadBody or ThreadStack freed.

NT Note: AH doesn't enable/disable any privileges. It's up to developer if he enables
     DEBUG ("Debug Programs") privilege that can be applied when openning Target.

--------------------------------------------------------------------------------------------------------------------------------------------------------------------
  Controlling remote execution
  ----------------------------

  All AH functions that execute Scouts, require pointer to RCINFO structure (PRCINFO,
passed as first parameter) that contains important flags and is filled according to result
of operation.

 typedef   struct _RCINFO {
  DWORD    RCFlags;
  DWORD    ProcFlags;
  LPVOID   (WINAPI *RtlAllocMem)(HANDLE, DWORD);
  BOOL     (WINAPI *RtlFreeMem)(HANDLE, LPVOID);
  HANDLE   hProcess;
  DWORD    ProcessId;
  HANDLE   hThread;
  DWORD    ThreadId;
  LPVOID   ThreadBody;
  LPVOID   ThreadStack;
 } RCINFO, *PRCINFO;

RCFlags [in/out] can contain combination of these bit flags:
  RC_FL_OWNTIMEOUT  - if ExpTime expires and remote thread is still active (is Timeout):
                      a) fill in all other RCINFO fields;
                      b) if remote thread won't free ThreadBody if it exits, set RC_FL_OWNFREE;
  RC_FL_TERMINATE   - if is Timeout:
                      a) try to terminate remote thread;
                      b) if remote thread was terminated (and is signaled), free ThreadStack
                           and if RC_FL_OWNFREE wasn't set, free ThreadBody too;
  RC_FL_OWNFREE     - don't free ThreadBody;
                      Note: This is not [in] only flag, AH can set it in the case of
                            Timeout && (RC_FL_TIMEOUT - b)).
  More on Timeout in D-Timeout.txt

  RC_FL_UNHIDE9X    - Win9x only flag. By default, in Win9x, remote thread used for executing
                      Scout doesn't call DllMains of loaded DLLs with DLL_THREAD_ATTACH.
                      It is because DLLs could get this notification before DLL_PROCESS_ATTACH
                      if Target is not initialized. Set this flag if you are _sure_ that
                      Win9x Target is initialized and if you _really_ need to know of remote
                      thread executing Scout (e.g. for coordination - you have a DLL in Target
                      which cooperates with Scout).

  RC_FL_DEFSD       - NT only flag.
                        When set, AH creates remote thread with default security descriptor.
                        When not set, AH tries to create remote thread with security descriptor
                      with DACL from Target's SD. Process access flags are mapped to thread
                      access flags. Of course, this is an approximation, but more suitable
                      (remote thread has "better" access to itself usually) for intercontext
                      calls than creation with default SD.
                        If you want change thread's SD, priority, context, etc..., call AH
                      function with dwMilliseconds==0 and RCINFO.RCFlags == RC_FL_OWNTIMEOUT.
                      The thread is then created suspended. Resume it after all changes.
                      See Examples\D-Timeout\ThreadControl.  

ProcFlags [out] contains information about Target, important for remote execution
and for identifying errors. AH sets ProcFlags always, except (Target == Current Process)
or (case of ErrorAHException). AH can set these bit flags:
  RC_PF_DEBUGGED    - Target is under control of user-mode debugger.
                      This can be source of Timeout.
  RC_PF_16TERM      - Target is 16bit (Win9x) process or is terminating/terminated.
  RC_PF_NOOPEN      - Invalid (or signaled) ProcessId or hProcess was passed to AH function.
                      NT also: Target can't be opened for QUERY_INFORMATION and VM_READ (security).
  RC_PF_NATIVE      - NT only: 
                      * (h)GetProcFlags: Target is native process (mayn't contain KERNEL32.dll)
                         probably. This can be source of ErrorAHRemote.
                      * Functions creating remote thread: see Notes.
                      
  RC_PF_NOTINITED   - NT only: Target is not initialized yet.
                      AH executes Scout even if it can't initialize Target. Target's behaviour
                      can then be undefined.


LPVOID (WINAPI *RtlAllocMem)(HANDLE hProcess, DWORD mSize) [out] contains pointer to function
that can allocate memory of size mSize bytes in hProcess. hProcess must have VM_OPERATION
access. Allocated memory has EXECUTE_READWRITE (maximum) access.

BOOL (WINAPI *RtlFreeMem)(HANDLE hProcess, LPVOID AllocBase) [out] contains pointer to function
able to free memory starting at AllocBase in hProcess. hProcess must have VM_OPERATION
access. Memory had to be allocated via RtlAllocMem or by AH (ThreadBody, ThreadStack).

hProcess [out] valid only in the case of (Timeout && RC_FL_TIMEOUT) or (RC_FL_OWNFREE).
It is noninheritable handle with VM_OPERATION, VM_READ, VM_WRITE, CREATE_THREAD, QUERY_INFORMATION,
and optionally SYNCHRONIZE and READ_CONTROL access to Target.
Pass this handle to call to RtlFreeMem or to any AH (h) function requiring process handle. Handle
doesn't have to grant SYNCHRONIZE and READ_CONTROL.

ProcessId [out] filled always except (Target == Current Process) or (case of ErrorAHException).
Process identifier of Target.

hThread [out] valid only in the case of (Timeout && RC_FL_TIMEOUT).
It is noninheritable handle with THREAD_ALL_ACCESS access to remote thread executing Scout
in Target. Thread's security descriptor has DACL equal to DACL in Target's SD. When Target
can't be opened for READ_CONTROL or RC_FL_DEFSD was set, thread is created using default SD.

ThreadId [out] valid only in the case of (Timeout && RC_FL_TIMEOUT).
Thread identifier of remote thread executing Scout in Target.

ThreadBody [out] valid only in the case of (Timeout && RC_FL_TIMEOUT) or (RC_FL_OWNFREE).
Contains address of memory block containing Scout in Target.
ThreadBody can be freed using RtlFreeMem only.

ThreadStack [out] valid only in the case of (Timeout && RC_FL_TIMEOUT).
Contains address of memory block containing stack of remote thread executing Scout.
ThreadStack can be freed using RtlFreeMem only.


Notes:
  Scout isn't executed when remote process can't be opened, is terminated or (nearly) terminating
(even if execution in terminating process is possible). Scout isn't also executed in 9X 16bit processes.

NT:  Scout is executed after Target is initialized in NT (statically loaded DLLs got DLL_PROCESS_ATTACH),
but even if AH can't initialize Target (see Notes 3)).
  When thread starts, DLLs in Target get DLL_THREAD_ATTACH notification.
  When thread  exits, DLLs in Target get DLL_THREAD_DETACH notification.
  Some AH functions require HANDLE to Target - hProcess. It must have at least QUERY_INFORMATION
and VM_READ access. Calling hAH functions with hProcess having access to Target, mentioned
in RCINFO.hProcess description, is optimal.
  When RC_PF_NATIVE is set in RCINFO.ProcFlags at return from AH functions that create remote thread
(case of native Targets and Targets in other terminal sessions), the created (native) thread will not
be able to create threads and processes, to work with console, to initialize some system libraries, etc..
in Target. However, you may try to make such a thread Win32, see SesOff, NtLoad and Win32Thread
in Examples\F-Advanced\C.

9X:  Scout can be executed before Target is initialized (= before DllMains are called
with DLL_PROCESS_ATTACH) in Win9x. If RC_FL_UNHIDE9X wasn't set && Win9x Target
is not initialized && Scout loads some module(s), initialized are only DLLs loaded
module(s) (and oher modules loaded due to them) import(s) from. When is Win9x Target
initialized, DLLs get DLL_THREAD_DETACH notification when thread exits. When RC_FL_UNHIDE9X
was set, DLLs get DLL_THREAD_ATTACH when thread starts to execute.




  Initializing RCINFO
  -------------------

PRCINFO __stdcall GetDefaultRCInfo(VOID) function returns pointer to default RCINFO.
Default RCINFO is used when is AH function called with NULL as pRCI (first parameter)
Default RCINFO can be changed (lies in readwrite memory), but chage it only in single-thread
applications.

 RCINFO l_RCI;
static RCINFO g_RCI;
PRCINFO pRCI = NULL;

if(I am _sure_ that only _one_ thread will call AH functions) { //single-thread environment
  pRCI = GetDefaultRCInfo();
}
else {
  if(I will not pass pRCI to other thread) {
    pRCI = &lRCI;
  }
  else {
    // use global static variable
         pRCI = &g_RCI;
    // or allocate it:
         pRCI = AllocMemory(sizeof(RCINFO));
  }
  memcpy(pRCI, GetDefaultRCInfo(), sizeof(RCINFO));
}
pRCI->RCFlags = 0;

  Notes:
  1) AHFunction(NULL, a, b, c) == AHFunction(GetDefaultRCInfo(), a, b, c)

  2) If your module is linked with ApiHooks statically, call GetDefaultRCInfo
     as soon as possible (for example in DllMain) even if you don't use it.
     It is important to initialize AH as soon as possible. All AH functions
     initialize AH.

--------------------------------------------------------------------------------------------------------------------------------------------------------------------
  AH libraries export the following 2 functions, which try to get information about Target
or any other process represented by ProcessId or hProcess (with QUERY_INFORMATION and
VM_READ access):

  DWORD __stdcall  GetProcFlags(DWORD ProcessId);
  DWORD __stdcall hGetProcFlags(HANDLE hProcess);

  Returned DWORD contains RC_PF_* flags (same as RCINFO.ProcFlags would contain).
   
  Example:
    if(hGetProcFlags(GetCurrentProcess()) & RC_PF_DEBUGGED)
      printf("I'm debugged.");

    if(GetProcFlags(GetCurrentProcessId()) & RC_PF_DEBUGGED)
      printf("I'm debugged.");

--------------------------------------------------------------------------------------------------------------------------------------------------------------------
  AH libraries export the following 2 functions, which try to execute user code in
Target:

  DWORD __stdcall  RemoteExecute(PRCINFO pRCI, DWORD ProcessId, LONG dwMilliseconds, LPVOID lpBlock, DWORD BlockSize, LPVOID lpParameter);
  DWORD __stdcall hRemoteExecute(PRCINFO pRCI, HANDLE hProcess, LONG dwMilliseconds, LPVOID lpBlock, DWORD BlockSize, LPVOID lpParameter);

  Parameters:
  pRCI       - pointer to RCINFO structure, NULL for default RCINFO.
  ProcessId  - identifier of Target to execute user code.
  hProcess   - handle with at least PROCESS_QUERY_INFORMATION and PROCESS_VM_READ access to Target.
  dwMilliseconds - time to wait for remote thread to be signaled.
  lpBlock    - pointer to a block of code and data; this block will be copied to
               the Target and executed there. Although declared as LPVOID, Block
               can lie in read-only memory (is left intact).
  BlockSize  - the size of the block. _Always add 3 to real size of block._
  lpParameter- is passed to function located at the beginning of lpBlock.
               If lpParameter == RCThreadBodyAlias, lpParameter is replaced by current ThreadBody
               and RemoteFunction retrieves this value.

   
  lpBlock must have this structure:
  {
    DWORD __stdcall RemoteFunction(LPVOID lpParameter) {
      DWORD RFResult; 
      // ... RFResult = ...
      return(RFResult);
    }
    PrivateCodeOrData:
  }

  Although is RemoteFunction declared as __stdcall (WINAPI), it can destroy all registers
  but ESP (must end with "RET 4"; stack preservation is crucial). Moreover RemoteFunction
  is in try/except block - every exception is caught and ErrorAHRemote is returned. Pointers
  used in RemoteFunction must be valid in Target (it is not possible to simply call
  a function like GetVersion(), but ValidPointers->pGetVersion(); on assembly language level,
  so-called delta offsets must be used in pointers - remote code must be self-relative).

!!! RemoteFunction must return (in EAX register) codes different from ErrorAH* codes
    and DBG_TERMINATE_THREAD !!!

  If user requested not to free ThreadBody, lpBlock starts at ThreadBody+RCBlockStart
  and can be accessed via ReadProcessMemory (see Examples\A-Core\ASM\ShowLA).

  Return code:
  If all was successful - value (RFResult) returned by RemoteFunction
  else - ErrorAH* codes.

  See:
  Examples\A-Core.

--------------------------------------------------------------------------------------------------------------------------------------------------------------------
  Notes:
  1) It must be ensured there is nothing (e.g. debugger) that manipulates with
     Target during AH/remote function execution.

  2) When is Target debuggged, error codes of AH functions can be undefined.

  3) NT: If AH can't initialize Target, behaviour of Target can be undefined after
     remote execution.

  4) NT: Remote execution in Target, that [is debugged and not initialized], can be
     completed only during debugger's WaitForDebugEvent. Behaviour of such a Target
     can be undefined after remote execution. Avoid these issues using SAFE_DEBUGGEE
     technique shown in Examples\C-ApiWorks\C\GlobalC.

  5) NT4: Remote execution in Target, that [is debugged], can be completed only during
     debugger's WaitForDebugEvent.

  6) dwMilliseconds is the time programmer gives AH function to do its job. The whole
     time can be consumed (= calling thread is not responsible; if it maintains user
     interface, UI is not responsible). It is good idea to create special thread
     for calling AH function. Optimal dwMilliseconds depends on 'length' of remote
     code, 'length' of Hooks_DLL/Module's DllMain, etc...