Module 3: LibTCG — The Tradecraft Garden

The shared PE loading library that gives every Crystal Palace loader its foundation — PE parsing, section loading, import resolution, relocations, and PEB-based hash resolution.

1. What Is LibTCG?

LibTCG stands for Library for the Tradecraft Garden. It is a shared C library that provides the common PE loading and API resolution primitives needed by any Crystal Palace-based loader. Rather than writing manual mapping code from scratch each time, LibTCG encapsulates the entire process in a clean, reusable interface.

When Crystal Palace processes a mergelib directive, it extracts the COFF objects from the zip archive and links them directly into your PIC output. The functions become available as if they were defined in your own source files. This modular approach means you can write a loader that is only a few dozen lines of C, delegating all the heavy lifting to LibTCG.

2. Key Types and Macros

The tcg.h header defines several structures, typedefs, and macros that the entire LibTCG API depends on. Understanding these is essential before looking at any function implementation.

IMPORTFUNCS

This structure holds the two Win32 API function pointers that LibTCG needs for import resolution. These are resolved by the loader before calling any LibTCG PE loading functions:

C — tcg.htypedef struct {
    __typeof__(LoadLibraryA)   * LoadLibraryA;     // Pointer to kernel32!LoadLibraryA
    __typeof__(GetProcAddress) * GetProcAddress;   // Pointer to kernel32!GetProcAddress
} IMPORTFUNCS;

DLLDATA

This structure is populated by ParseDLL() and carries parsed PE header pointers through the entire loading pipeline:

C — tcg.htypedef struct {
    IMAGE_DOS_HEADER      * DosHeader;       // Pointer to the MZ header
    IMAGE_NT_HEADERS      * NtHeaders;       // Pointer to PE\0\0 + COFF + Optional
    IMAGE_OPTIONAL_HEADER * OptionalHeader;  // Pointer to the Optional Header
} DLLDATA;

Every subsequent LibTCG function takes a pointer to a DLLDATA struct. It acts as a parsed view into the raw PE bytes, avoiding redundant re-parsing at each stage.

Function Pointer Typedefs

C — tcg.h// Standard DllMain signature for reflective DLL loading
typedef BOOL WINAPI (*DLLMAIN_FUNC)(HINSTANCE, DWORD, LPVOID);

// Entry point for PIC Object (PICO) payloads
typedef void (* PICOMAIN_FUNC)(char * arg);

Utility Macros

C — tcg.h// Pointer arithmetic: advance pointer x by y bytes
#define PTR_OFFSET(x, y)  ( (void *)(x) + (ULONG)(y) )

// Dereference a pointer-sized value at the given address
#define DEREF(name)        *(UINT_PTR *)(name)

// Get the caller's return address (MinGW built-in)
#define WIN_GET_CALLER()   __builtin_extract_return_addr(__builtin_return_address(0))

3. PE Loading Pipeline

LibTCG implements the full manual mapping pipeline as a series of composable functions. Each function handles one stage of the PE loading process. The loader calls them in sequence to transform raw PE bytes into an executable image in memory.

ParseDLL(src, &data)

The first step in the pipeline. ParseDLL takes a pointer to the raw PE bytes and populates the DLLDATA struct with pointers into the PE structure:

C// ParseDLL validates the DOS header and locates the NT headers
void ParseDLL(char * src, DLLDATA * data)
{
    // 1. Cast the start of the buffer to a DOS header
    data->DosHeader = (IMAGE_DOS_HEADER *)src;

    // 2. Validate the MZ magic number (0x5A4D)
    //    If this check fails, the payload is not a valid PE

    // 3. Use e_lfanew to locate the NT headers
    //    e_lfanew is a LONG at offset 0x3C in the DOS header
    //    It contains the file offset to the PE signature
    data->NtHeaders = (IMAGE_NT_HEADERS *)PTR_OFFSET(src,
                          data->DosHeader->e_lfanew);

    // 4. Extract the Optional Header pointer
    //    The Optional Header immediately follows the COFF File Header
    data->OptionalHeader = &data->NtHeaders->OptionalHeader;
}

SizeOfDLL(&data)

Returns the total virtual size needed for the fully loaded image:

C// SizeOfDLL returns the total memory required for the mapped image
DWORD SizeOfDLL(DLLDATA * data)
{
    // SizeOfImage from the Optional Header tells us the total virtual
    // size of the PE when loaded into memory, including all sections
    // aligned to SectionAlignment boundaries
    return data->OptionalHeader->SizeOfImage;
}

The caller uses this value to allocate a contiguous memory region (via VirtualAlloc or NtAllocateVirtualMemory) before calling LoadDLL. The SizeOfImage field accounts for section alignment padding, so it is always larger than the raw file size.

LoadDLL(&dll, src, dst)

Copies the PE headers and all sections from the source buffer to the destination buffer at their correct virtual offsets:

C// LoadDLL maps the PE into the destination buffer
void LoadDLL(DLLDATA * dll, char * src, char * dst)
{
    // 1. Copy the PE headers (DOS + NT + Section Table)
    //    Size = OptionalHeader->SizeOfHeaders
    memcpy(dst, src,
           dll->OptionalHeader->SizeOfHeaders);

    // 2. Get the first section header
    PIMAGE_SECTION_HEADER section = IMAGE_FIRST_SECTION(dll->NtHeaders);
    WORD numSections = dll->NtHeaders->FileHeader.NumberOfSections;

    // 3. Iterate each section and copy raw data to virtual address
    for (WORD i = 0; i < numSections; i++) {
        if (section[i].SizeOfRawData > 0) {
            char * rawSrc  = src + section[i].PointerToRawData;
            char * rawDest = dst + section[i].VirtualAddress;
            memcpy(rawDest, rawSrc, section[i].SizeOfRawData);
        }
    }
}

ProcessRelocations(&dll, src, dst)

When a DLL is loaded at a base address different from its preferred ImageBase, all absolute addresses embedded in the code must be patched. This is what the .reloc section is for:

C// ProcessRelocations patches absolute addresses for the new base
void ProcessRelocations(DLLDATA * dll, char * src, char * dst)
{
    // 1. Calculate the delta between actual and preferred base
    UINT_PTR delta = (UINT_PTR)dst -
                     dll->OptionalHeader->ImageBase;

    if (delta == 0) return;  // Loaded at preferred base, no fixups needed

    // 2. Locate the Base Relocation Directory
    PIMAGE_DATA_DIRECTORY relocDir = &dll->OptionalHeader->
        DataDirectory[IMAGE_DIRECTORY_ENTRY_BASERELOC];

    PIMAGE_BASE_RELOCATION reloc = (PIMAGE_BASE_RELOCATION)
        PTR_OFFSET(dst, relocDir->VirtualAddress);

    // 3. Walk each relocation block
    while (reloc->VirtualAddress != 0) {
        DWORD numEntries = (reloc->SizeOfBlock - sizeof(IMAGE_BASE_RELOCATION))
                           / sizeof(WORD);
        PWORD entries = (PWORD)(reloc + 1);

        for (DWORD i = 0; i < numEntries; i++) {
            WORD type   = entries[i] >> 12;        // Top 4 bits = type
            WORD offset = entries[i] & 0x0FFF;     // Bottom 12 bits = offset

            if (type == IMAGE_REL_BASED_DIR64) {   // Type 10: 64-bit fixup
                PUINT_PTR patchAddr = (PUINT_PTR)PTR_OFFSET(
                    dst, reloc->VirtualAddress + offset);
                *patchAddr += delta;               // Apply the delta
            }
        }
        // Advance to next relocation block
        reloc = (PIMAGE_BASE_RELOCATION)PTR_OFFSET(reloc, reloc->SizeOfBlock);
    }
}

ProcessImports(&funcs, &dll, dst)

Walks the Import Directory Table and resolves every imported function into the IAT:

C// ProcessImports resolves all imported DLLs and functions
void ProcessImports(IMPORTFUNCS * funcs, DLLDATA * dll, char * dst)
{
    // 1. Locate the Import Directory
    PIMAGE_DATA_DIRECTORY importDir = &dll->OptionalHeader->
        DataDirectory[IMAGE_DIRECTORY_ENTRY_IMPORT];

    PIMAGE_IMPORT_DESCRIPTOR importDesc = (PIMAGE_IMPORT_DESCRIPTOR)
        PTR_OFFSET(dst, importDir->VirtualAddress);

    // 2. Walk each import descriptor (one per imported DLL)
    while (importDesc->Name != 0) {
        // Resolve the imported DLL by name
        char * dllName = (char *)PTR_OFFSET(dst, importDesc->Name);
        HMODULE hModule = funcs->LoadLibraryA(dllName);

        // 3. Walk the ILT (Import Lookup Table) and IAT simultaneously
        PUINT_PTR thunk    = (PUINT_PTR)PTR_OFFSET(dst,
                              importDesc->OriginalFirstThunk);
        PUINT_PTR iatEntry = (PUINT_PTR)PTR_OFFSET(dst,
                              importDesc->FirstThunk);

        while (*thunk != 0) {
            if (IMAGE_SNAP_BY_ORDINAL(*thunk)) {
                // Import by ordinal
                *iatEntry = (UINT_PTR)funcs->GetProcAddress(hModule,
                             (LPCSTR)IMAGE_ORDINAL(*thunk));
            } else {
                // Import by name
                PIMAGE_IMPORT_BY_NAME nameEntry = (PIMAGE_IMPORT_BY_NAME)
                    PTR_OFFSET(dst, *thunk);
                *iatEntry = (UINT_PTR)funcs->GetProcAddress(hModule, nameEntry->Name);
            }
            thunk++;
            iatEntry++;
        }
        importDesc++;
    }
}

EntryPoint(&dll, base)

Computes the address of the DLL's entry point in the mapped image and returns it as a DLLMAIN_FUNC pointer ready to call:

C// EntryPoint calculates the entry point address
DLLMAIN_FUNC EntryPoint(DLLDATA * dll, void * base)
{
    // AddressOfEntryPoint is an RVA in the Optional Header
    // Add it to the base to get the absolute address
    return (DLLMAIN_FUNC)PTR_OFFSET(base,
                      dll->OptionalHeader->AddressOfEntryPoint);
}

The returned DLLMAIN_FUNC pointer is called directly with DLL_PROCESS_ATTACH. For a Cobalt Strike Beacon DLL, this is where execution begins after the reflective load completes.

4. PEB Walking — findModuleByHash()

Before the PE loading pipeline can run, the loader needs LoadLibraryA and GetProcAddress. But you cannot call GetProcAddress to find GetProcAddress — that is circular. The solution is to walk the Process Environment Block (PEB) to find loaded modules by hash, then walk their Export Address Table to find functions by hash.

Cchar * findModuleByHash(DWORD moduleHash)
{
    // 1. Read the PEB from the GS segment register (x64)
    //    On x64, gs:[0x60] points to the PEB
    PPEB pPeb = (PPEB)__readgsqword(0x60);

    // 2. Access the Ldr (PEB_LDR_DATA) which tracks all loaded modules
    //    InMemoryOrderModuleList is a doubly-linked list of
    //    LDR_DATA_TABLE_ENTRY structures
    PLIST_ENTRY head  = &pPeb->Ldr->InMemoryOrderModuleList;
    PLIST_ENTRY entry = head->Flink;

    // 3. Walk the linked list
    while (entry != head) {
        // CONTAINING_RECORD macro: given a list entry pointer,
        // recover the enclosing LDR_DATA_TABLE_ENTRY
        PLDR_DATA_TABLE_ENTRY mod = CONTAINING_RECORD(
            entry, LDR_DATA_TABLE_ENTRY, InMemoryOrderLinks);

        // 4. Hash the module's BaseDllName (Unicode, case-insensitive)
        //    using the ROR13 algorithm
        DWORD nameHash = ror13_unicode(mod->BaseDllName.Buffer,
                                       mod->BaseDllName.Length);

        // 5. Compare against the target hash
        if (nameHash == moduleHash)
            return mod->DllBase;  // Return the module's base address

        entry = entry->Flink;    // Advance to next module
    }
    return NULL;  // Module not found
}

5. EAT Walking — findFunctionByHash()

Once findModuleByHash() returns a module's base address, findFunctionByHash() searches that module's Export Address Table (EAT) for a function matching a given ROR13 hash:

Cvoid * findFunctionByHash(char * src, DWORD wantedFunction)
{
    // 1. Parse PE headers to find the Export Directory
    PIMAGE_DOS_HEADER dos = (PIMAGE_DOS_HEADER)src;
    PIMAGE_NT_HEADERS nt  = (PIMAGE_NT_HEADERS)
        PTR_OFFSET(src, dos->e_lfanew);

    PIMAGE_EXPORT_DIRECTORY exports = (PIMAGE_EXPORT_DIRECTORY)
        PTR_OFFSET(src,
            nt->OptionalHeader.DataDirectory[IMAGE_DIRECTORY_ENTRY_EXPORT]
            .VirtualAddress);

    // 2. Retrieve the three parallel arrays
    PDWORD names     = (PDWORD)PTR_OFFSET(src, exports->AddressOfNames);
    PDWORD functions = (PDWORD)PTR_OFFSET(src, exports->AddressOfFunctions);
    PWORD  ordinals  = (PWORD) PTR_OFFSET(src, exports->AddressOfNameOrdinals);

    // 3. Iterate through all named exports
    for (DWORD i = 0; i < exports->NumberOfNames; i++) {
        // Resolve the function name string
        char * name = (char *)PTR_OFFSET(src, names[i]);

        // Hash the name and compare
        if (ror13_ascii(name) == wantedFunction)
            return PTR_OFFSET(src, functions[ordinals[i]]);
    }
    return NULL;  // Function not found
}

The Three Parallel Arrays

The Export Directory uses three arrays that work together to map function names to their code addresses. Understanding how they link together is critical:

6. The ROR13 Hash Algorithm

LibTCG uses the ROR13 (Rotate Right by 13) hash algorithm to identify modules and functions without embedding their plaintext names in the shellcode. This is the same algorithm used in Metasploit's block_api stager and has been a shellcode convention for over a decade.

C// ROR13 hash for ASCII strings (function names)
DWORD ror13_ascii(const char * str)
{
    DWORD hash = 0;
    while (*str) {
        hash = (hash >> 13) | (hash << 19);  // Rotate right 13 bits
        hash += (DWORD)*str++;                // Add current character
    }
    return hash;
}

// ROR13 hash for Unicode strings (module names, case-insensitive)
DWORD ror13_unicode(const WCHAR * str, DWORD len)
{
    DWORD hash = 0;
    DWORD chars = len / sizeof(WCHAR);
    while (chars--) {
        WCHAR c = *str++;
        if (c >= L'A' && c <= L'Z')
            c += 0x20;  // Convert to lowercase for case-insensitive matching
        hash = (hash >> 13) | (hash << 19);
        hash += (DWORD)c;
    }
    return hash;
}

Pre-Computed Hashes in Crystal-Loaders

Crystal Palace's dfr (define function reference) directive computes ROR13 hashes at build time and embeds them as DWORD immediates in the PIC output. For example, in loader.c:

C — loader.c// The NTDLL hash used in Crystal-Loaders
#define NTDLL_HASH      0x3CFA685D

// At runtime, the loader calls:
char * ntdll = findModuleByHash(NTDLL_HASH);

// The dfr directive in the .spec file tells Crystal Palace
// to resolve function references the same way:
//   dfr kernel32.dll, LoadLibraryA
//   dfr kernel32.dll, GetProcAddress
// Crystal Palace pre-computes the hashes and generates
// the findModuleByHash + findFunctionByHash calls automatically

7. PICO Functions

Beyond traditional PE/DLL loading, LibTCG also supports PICOs (Position Independent Code Objects). PICOs are a Crystal Kit concept for modular evasion components that differ from standard PIC in one critical way: they keep code and data in separate allocations.

Crystal Kit uses PICOs for modular evasion primitives — sleep masks, call stack spoofers, and other components that can be composed and swapped independently. LibTCG provides the loading machinery; the PICO format and its tooling come from the broader Crystal Kit ecosystem.