PEB

The Process Environment Block (PEB) is a process’s user-mode representation. It has the highest-level knowledge of a process in kernel mode and the lowest-level in user mode. The PEB is created by the kernel but is mostly operated on from user mode. If a (system) process has no user-mode footprint, it has no PEB. If only in principle, if anything about a process is shared with kernel mode but can be properly managed in user mode without needing a transition to kernel mode, it goes in the PEB. If anything about a process might usefully be shared between user-mode modules, then it’s at least a candidate for going in the PEB for easy access. Very much more in principle than in practice, data may go into the PEB for sharing between processes more easily than by any formal inter-process communication.

Access

User-mode code can easily find its own process’s PEB, albeit only by using undocumented or semi-documented behaviour. While a thread executes in user mode, its fs or gs register, for 32-bit and 64-bit code respectively, addresses the thread’s TEB. That structure’s ProcessEnvironmentBlock member holds the address of the current process’s PEB. In NTDLL version 5.1 and higher, this simple work is available more neatly as an exported function, named RtlGetCurrentPeb, but it too is undocumented. Its implementation is something very like

PEB *RtlGetCurrentPeb (VOID)
{
    return NtCurrentTeb () -> ProcessEnvironmentBlock;
}

For its own low-level user-mode programming, Microsoft has long had a macro or inlined routine, apparently named NtCurrentPeb, which reads directly from fs or gs, e.g.,

PEB *NtCurrentPeb (VOID)
{
    return (PEB *) __readfsdword (FIELD_OFFSET (TEB, ProcessEnvironmentBlock));
}

The difference between an exported function (RtlGetCurrentPeb) and a macro or inlined routine (NtCurrentPeb) scarcely matters at run time but has forensic significance because use of the latter in a high-level module, e.g., for MSHTML.DLL from Internet Explorer 6, not only shows that Microsoft’s application programmers had undocumented knowledge of the PEB and TEB but also suggests they had access to otherwise private headers (if not to use them in their build, then at least to reproduce from them).

Other Processes

User-mode code can less easily access the PEB of any process for which it has a handle and sufficient access rights. The gatekeeper is the NtQueryInformationProcess function. This is exported by NTDLL in all known Windows versions. Its ProcessBasicInformation case fills a PROCESS_BASIC_INFORMATION structure whose member named PebBaseAddress is, unsurprisingly, the address of the queried process’s PEB. Of course, the address thus obtained is not directly usable. It is meaningful in the queried process’s address space. Even just to read that process’s PEB then requires such functions as ReadProcessMemory and the corresponding permission. To do much with what’s read may require synchronisation with or defence against changes being made by the queried process’s own threads—and writing to the queried process’s PEB certainly requires such synchronisation. In consequence, safe use of another process’s PEB is beyond many programers who attempt it, e.g., for malware and more notably for some of what gets foisted onto consumers as anti-malware or merely recommended to them as supposedly helpful system tools.

Documentation Status

In an ideal world, the PEB might be opaque outside the kernel and a few low-level user-mode modules such as NTDLL and KERNEL32. But, as noted in remarks above about forsensic signfiicance, various high-level modules supplied with Windows over the years have used a few members of the PEB, and this eventually had to be disclosed. A new header, named WINTERNL.H, for previously internal APIs was added to the Software Development Kit (SDK) apparently in 2002 as the main (if insubstantial) outcome of an anti-trust settlement, and remains to this day. It originally presented a modified PEB that has just the BeingDebugged and SessionId members, plus padding that gets these members to the same offsets as in the true structure. More members have been included in this modified PEB over the years: Ldr, ProcessParameters and PostProcessInitRoutine in the SDK for Windows 7; and AtlThunkSListPtr and AtlThunkSListPtr32 in the SDK for Windows 8. Notwithstanding the header’s warnings, it seems unlikely that Microsoft will change the PEB in any way that moves any of these members.

Layout

Indeed, the PEB is highly stable across Windows versions. When members fall out of use the space they occupied tends to be left in place, often to be reused eventually, but without shifting other members. Many members that are useful—to know about not just when debugging but also when studying malware—have kept their positions through all the known history. The PEB has grown mostly by adding new members at its end. The following sizes are known (with caveats that follow the table):

These sizes, and the offsets, types and names in the tables that follow, are from Microsoft’s symbol files for the kernel starting with Windows 2000 SP3 and for NTDLL starting with Windows XP, but are something of a guess for earlier versions since the symbol files for these do not contain type information for the PEB. What’s known of Microsoft’s names and types for earlier versions is instead inferred from what use NTOSKRNL and various low-level user-mode modules such as NTDLL are seen to make of the PEB. Exhaustively tracking down all such use would be difficult, if not impossible, even with source code.

Original (More or Less)

The very first member is arguably too much overlooked, given that so many programmers with backgrounds in Unix seem to think that assessment of Windows as an operating system begins and ends with whether Windows truly can fork a process. It is here thought to have been followed by unlabelled alignment space until version 3.51 defined the next two booleans.

BOOLEAN InheritedAddressSpace;

BOOLEAN ReadImageFileExecOptions;

BOOLEAN BeingDebugged;

BOOLEAN SpareBool;

union {
    UCHAR BitField;
    struct {
        /*  bit fields, follow link  */
    };

};

UCHAR Padding0 [4];

HANDLE Mutant;

These first eight bytes of the PEB have a separate identity as an INITIAL_PEB structure, apparently only for passing parameters to the kernel’s internal routine that creates a PEB. No trace of this INITIAL_PEB ever shows in public symbol files but it is known from the USERKDX debugger extension that Microsoft supplied with the Device Driver Kit (DDK) for Windows NT 4.0 and again for Windows 2000.

The kernel sets BeingDebugged to indicate that the process has a debug port. The (documented) KERNEL32 function IsDebuggerPresent does nothing more than read BeingDebugged from the current PEB.

Whether the byte at offset 0x03 was labelled explicitly as a spare boolean concurrently with definition of the two booleans at offsets 0x01 and 0x02 is not certain but is at least plausible. It anyway never was used as a boolean but started getting used as bit fields in the build of version 5.2 that first put the CPU’s support for large pages to use as an efficiency for executable images. The individual bits are presented separately, description being complicated because Windows 8.1 deleted one of them (IsLegacyProcess) and thus changed the masks for accessing the others.

PVOID ImageBaseAddress;

PEB_LDR_DATA *Ldr;

RTL_USER_PROCESS_PARAMETERS *ProcessParameters;

PVOID SubSystemData;

PVOID ProcessHeap;

Of the original PEB members, Ldr and ProcessParameters are arguably the most used by Microsoft’s higher-level modules and Microsoft eventually included them in the reduced PEB that’s published in WINTERNL.H for all the world to know about. In any world in which such publication had any self-consistency, the ProcessHeap wouldn’t be far behind: the ancient (documented) KERNEL32 function GetProcessHeap has always done nothing more than read ProcessHeap from the current PEB, but very many Microsoft programs and DLLs instead read ProcessHeap by themselves (as if GetProcessHeap is inlined for their use).

At the other extreme, the SubSystemData is about as obscure as anything gets in Windows programming for ordinary purposes. As its name suggests, it is intended for subsystems that don’t have enough of Microsoft’s attention to justify defining their own members in the PEB itself. A subsystem, such as supported by PSXDLL.DLL, can point SubSystemData at its own collection of per-process data.

PVOID FastPebLock;

RTL_CRITICAL_SECTION *FastPebLock;

PVOID FastPebLockRoutine;

PVOID SparePtr1;

PVOID AtlThunkSListPtr;

PVOID FastPebUnlockRoutine;

PVOID SparePtr2;

PVOID IFEOKey;

In early versions, NTDLL supports its exported (undocumented) RtlAcquirePebLock and RtlReleasePebLock functions by storing in the PEB the addresses not just of a FastPebLock variable in the NTDLL data but of two routines for acquiring and releasing whatever is this lock. Though it does happen that the lock is a critical section and the routines are just the expected RtlEnterCriticalSection and RtlLeaveCriticalSection, not until version 5.1 is the lock’s nature formalised in the PEB and not until version 5.2 does NTDLL stop saving the routines’ addresses in the PEB. 

You might wonder why they ever were saved in the PEB. After all, the RtlAcquirePebLock and RtlReleasePebLock functions ought to suffice for Microsoft’s user-mode code that’s outside NTDLL and wants to synchronise its access to the PEB with access by other threads in the same process. What fascinates me, and prompts this digression, is that the only use I know of FastPebLock from outside NTDLL is in kernel mode. Moreover, it also uses the long-gone FastPebLockRoutine and FastPebUnlockRoutine members. Go back far enough and this is done by linking the exact same implementations of the RtlAcquirePebLock and RtlReleasePebLock functions into both NTDLL and the kernel—yes, with the kernel finding the PEB from the TEB, in turn found from the fs register as described above. Version 5.1 re-implemented so that the kernel instead progresses through structures that have no user-mode susceptibility, thus from the fs register to the KPCR to the KTHREAD to the EPROCESS for its pointer to the PEB. If this change was motivated by thoughts of security, it was worse than pointless because the kernel does not just follow the FastPebLockRoutine and FastPebUnlockRoutine pointers in the PEB but calls through them to execute (what it hopes to be) NTDLL code at its user-mode address. Do not miss that whatever is there gets executed with ring 0 privilege.

This trick that is plainly too clever for anyone’s good was ended for version 5.2 in 2003, which surely is everyone’s gain, yet it was retained even for the long-lived last service pack of version 5.1 in 2008, apparently without Microsoft ever warning anyone of it. In the very earliest versions, it had extensive use. Among the reasons the kernel would access the PEB in ways that needed synchronisation with access by other threads (most likely in user mode) were such things as the kernel allocating from and freeing to the process heap. Even as late as version 5.1, this execution of user-mode code with kernel-mode prvilege was still being done for the exported (and documented) function RtlQueryRegistryValues to expand environment variables whose names are found between percent signs in registry data that has the REG_EXPAND_SZ type.

Can it really be that Microsoft was never called out for this grotesqueness?

ULONG EnvironmentUpdateCount;

union {
    ULONG CrossProcessFlags;
    struct {
        /*  bit fields, follow link  */
    };
};

UCHAR Padding1 [4];

PVOID KernelCallbackTable;

union {
    PVOID KernelCallbackTable;
    PVOID UserSharedInfoPtr;
};

ULONG SystemReserved [2];

ULONG SystemReserved [1];

ULONG SystemReserved;

HANDLE EventLogSection;

PVOID EventLog;

struct {
    ULONG ExecuteOptions : 2;
    ULONG SpareBits : 30;
};

ULONG SpareUlong;

ULONG AtlThunkSListPtr32;

No use is known of the preceding 0x10 bytes in version 3.10. It seems more than merely plausible that the explicit reservation of two dwords as SystemReserved, as known from symbol files for late service packs of Windows 2000, started as four.

In those versions that have it, the EnvironmentUpdateCount is incremented when an attempt to set the current directory gets as far as NTDLL’s RtlSetCurrentDirectory_U function. What this has to do with any sort of environment is not known. Windows Vista anyway replaced this counter with a set of flags.

What KernelCallbackTable points to is an array of function pointers to support the exported (undocumented) KiUserCallbackDispatcher function. This is one of the relatively few functions that NTDLL exports not to be imported by other user-mode modules but to be found by the kernel. The function is called by the kernel when a driver, typically WIN32K.SYS, calls the kernel export KeUserModeCallback. Of course, the NTDLL function is not actually called by the kernel. It instead becomes the target address for the kernel’s exit from ring 0 to ring 3. Still, KiUserCallbackDispatcher perceives that it has been called and that among its arguments is an index into the KernelCallbackTable. This selects where further to dispatch the execution deeper into user mode. Getting back to kernel mode with the appearance of returning from a call to user mode is important enough to have a dedicated interrupt number, 0x2B.

The array of function pointers that is the KernelCallbackTable is set into place by USER32.DLL during its initialisation, but not until after USER32 connects to the CSRSS server. Starting with version 6.0, if the process is a so-called protected process, the KernelCallbackTable pointer is first put to double duty as the UserSharedInfoPtr. Just while connecting, it becomes a side-channel for receiving a SHAREDINFO structure directly from WIN32K.SYS.

Windows XP and Windows Server 2003 got into some sort of tussle about using the last of the previously reserved dwords. The ExecuteOptions certainly are used in the early releases of both. These two bits do not, however, have the same meaning as later flags for the Data Execution Prevention (DEP) that came with the late builds of these versions. They are concerned instead with checking for stack overflow.

PEB_FREE_BLOCK *FreeList;

ULONG SparePebPtr0;

PVOID ApiSetMap;

The PEB_FREE_BLOCK is simply a pointer to the Next of its type, presumably to make a single-linked list, and a 32-bit unsigned Size. The suggestion is of caching freed memory, but although FreeList is defined in symbol files, no use is known of it in any version. The ApiSetMap that replaces it is the process’s pointer to the kernel’s representation of the API Set Schema of redirections that NTDLL is to apply when loading DLLs. What the kernel points ApiSetMap to is a read-only mapping into the process’s address space. Pointing ApiSetMap elsewhere would seem to be not just possible but attractive, whether for mischief or for the supposedly well-intentioned intrusiveness of security tools as an alternative to hooking API functions by such techniques as patching code.

ULONG TlsExpansionCounter;

UCHAR Padding2 [4];

PVOID TlsBitmap;

ULONG TlsBitmapBits [2];

PVOID ReadOnlySharedMemoryBase;

PVOID ReadOnlySharedMemoryHeap;

PVOID HotpatchInformation;

PVOID SparePvoid0;

PVOID SharedData;

PVOID *ReadOnlyStaticServerData;

PVOID AnsiCodePageData;

PVOID OemCodePageData;

PVOID UnicodeCaseTableData;

ULONG NumberOfProcessors;

ULONG NtGlobalFlag;

LARGE_INTEGER CriticalSectionTimeout;

The NtGlobalFlag member is intially the process’s copy of the kernel’s (exported) NtGlobalFlag variable as it was when the kernel created the PEB.

Before version 5.0, having an NtGlobalFlag in the PEB is nothing but a convenience for NTDLL to initialise its own (internal) NtGlobalFlag variable without having to call through NtQuerySystemInformation. It’s the internal variable that gets per-processor adjustments, e.g., from the GlobalFlag value in the Image File Execution Options or from applicable fields in the Configuration Directory. It’s the internal variable that matters. The NtGlobalFlag in the PEB can be just a stale record of what the process started with.

See that version 3.51 didn’t just append new members but instead inserted two. One was in what looks to have been unused alignment space, but the other turns CriticalSectionTimeout into the oldest known case of any PEB member shifting between versions.

Appended for Windows NT 3.51

ULONG_PTR HeapSegmentReserve;

ULONG_PTR HeapSegmentCommit;

ULONG_PTR HeapDeCommitTotalFreeThreshold;

ULONG_PTR HeapDeCommitFreeBlockThreshold;

ULONG NumberOfHeaps;

ULONG MaximumNumberOfHeaps;

PVOID *ProcessHeaps;

Appended for Windows NT 4.0

PVOID GdiSharedHandleTable;

PVOID ProcessStarterHelper;

ULONG GdiDCAttributeList;

UCHAR Padding3 [4];

PVOID LoaderLock;

RTL_CRITICAL_SECTION *LoaderLock;

ULONG OSMajorVersion;

ULONG OSMinorVersion;

USHORT OSBuildNumber;

USHORT OSCSDVersion;

ULONG OSPlatformId;

ULONG ImageSubsystem;

ULONG ImageSubsystemMajorVersion;

ULONG ImageSubsystemMinorVersion;

UCHAR Padding4 [4];

KAFFINITY ImageProcessAffinityMask;

KAFFINITY ActiveProcessAffinityMask;

ULONG GdiHandleBuffer [0x22];

ULONG GdiHandleBuffer [0x3C];

The point to the several members starting at OSMajorVersion is very much that they need not be truly the operating system’s version numbers. They can instead be whatever version numbers are meant to be perceived by user-mode code in the process. Whether this happens depends on the Win32VersionValue in the image header of the process’s executable. To this day, 30th March 2019, Microsoft’s documentation would have it that “this member is reserved and must be 0.” If, however, it is non-zero, as can have been arranged using the linker’s undocumented /win32version switch, then the kernel overrides the true Windows version numbers that would otherwise be set into these PEB members:

• OsMajorVersion from bits 0 to 7 of the Win32VersionValue;
• OSMinorVersion from bits 8 to 15;
• OSBuildNumber from bits 16 to 29;
• OSCSDVersion from the CSDVersion member of the IMAGE_LOAD_CONFIG_DIRECTORY, if non-zero, in version 5.0 and higher;
• OSPlatformId from bits 30 to 31 of the Win32VersionValue, with 0, 1, 2 and 3 mapping respectively to 2 (VER_PLATFORM_WIN32_NT), 3, 0 and 1.

Appended for Windows 2000

VOID (*PostProcessInitRoutine) (VOID);

PVOID TlsExpansionBitmap;

ULONG TlsExpansionBitmapBits [0x20];

ULONG SessionId;

UCHAR Padding5 [4];

The SessionId is one of the two PEB members that Microsoft documented when required to disclose use of internal APIs by so-called middleware.

Insertion of the next three members for Windows XP produces the last known case of members whose offset varies between versions. Don’t miss the irony that this was done in the name of application compatibility.

ULARGE_INTEGER AppCompatFlags;

ULARGE_INTEGER AppCompatFlagsUser;

PVOID pShimData;

PVOID AppCompatInfo;

UNICODE_STRING CSDVersion;

The AppCompatFlags and AppCompatFlagsUser members are set by APPHELP.DLL from TAG_FLAG_MASK_KERNEL (0x5005) and TAG_FLAG_MASK_USER (0x5008) tags for the process’s description in an SDB file. In the XML that SDB files are compiled from, the two are evaluated from the MASK attribute in a <FLAG> tag whose TYPE attribute is KERNEL or USER, respectively.

Appended for Windows XP

ACTIVATION_CONTEXT_DATA const *ActivationContextData;

ASSEMBLY_STORAGE_MAP *ProcessAssemblyStorageMap;

ACTIVATION_CONTEXT_DATA const *SystemDefaultActivationContextData;

ASSEMBLY_STORAGE_MAP *SystemAssemblyStorageMap;

ULONG_PTR MinimumStackCommit;

Appended for Windows Server 2003

FLS_CALLBACK_INFO *FlsCallback;

PVOID SparePointers [4];

LIST_ENTRY FlsListHead;

PVOID FlsBitmap;

ULONG FlsBitmapBits [4];

ULONG SpareUlongs [5];

ULONG FlsHighIndex;

Appended for Windows Vista

PVOID WerRegistrationData;

PVOID WerShipAssertPtr;

Appended for Windows 7

PVOID pContextData;

PVOID pUnused;

PVOID pImageHeaderHash;

union {
    ULONG TracingFlags;
    struct {
        /*  bit fields, follow link  */
    };
};

Appended for Windows 8

ULONGLONG CsrServerReadOnlySharedMemoryBase;

Appended Later in Windows 10

ULONG TppWorkerpListLock;

LIST_ENTRY TppWorkerpList;

PVOID WaitOnAddressHashTable [0x80];

PVOID TelemetryCoverageHeader;

ULONG CloudFileFlags;

ULONG CloudFileDiagFlags;

CHAR PlaceholderCompatibiltyMode;

CHAR PlaceholderCompatibilityModeReserved [7];

LEAP_SECOND_DATA *LeapSecondData;

union {
    ULONG LeapSecondFlags;
    struct {
        ULONG SixtySecondEnabled : 1;
        ULONG Reserved : 31;
    };
};

ULONG NtGlobalFlag2;

The NtGlobalFlag2 member is indeed named for being in some sense an extension of the much older NtGlobalFlag. Each corresponds to a registry value that can be in either or both of two well-known keys. Each also is the name of a variable in the kernel (one exported, the other only internal), which the kernel initialises from the corresponding registry value in the Session Manager key. This then provides the initial value for the corresponding PEB member, which may then be re-initialised from the same-named registry value in the program’s subkey of the Image File Execution Options.

Only one flag in the new set of them is yet known to be defined. A set 0x00000001 bit in the data for the GlobalFlag2 registry value becomes a set 0x00000001 bit in the NtGlobalFlag2 member. From there it may set the SixtySecondEnabled bit in union with the LeapSecondFlags. The intended effect is that the newly exported RtlpTimeFieldsToTime and RtlpTimeToTimeFields functions become leap-second-aware: when LeapSecondData is available, these functions accommodate 60 as the seconds field in a time.

This support for leap seconds was all new for the 1809 release and thus was also still new, roughly, for the article Leap Seconds for the IT Pro: What you need to know at a Microsoft blog dated Feb 14 2019. Years later, on 27th January 2023, this is still the only match that Google finds when asked to search microsoft.com for pages that contain GlobalFlag2. This is a good example of a trend in what passes as documentation. At various levels of Windows administration and programming, it is often that Microsoft’s only disclosure of some new feature, large or small, is a blog. Administrators and programmers are inevitably grateful that Microsoft employees take the time to blog. But let’s please not overlook that these blogs are not documentation. The helpfulness of Microsoft’s employees in explaining new features in fast-moving development, and the readiness of occasionally desperate administrators and programmers to latch on to this help, disguises that Microsoft is systematically skipping the work of documenting these features.