From 6ed2547ce21938b59ae0f3862598b9b7f710bb98 Mon Sep 17 00:00:00 2001 From: Oliver Smith-Denny Date: Fri, 28 Jun 2024 12:35:19 -0700 Subject: [PATCH] Update Memory Protection Feature Documentation (#831) ## Description Update the feature_memory_protection readme to add a debugging section and recent changes made. - [ ] Impacts functionality? - **Functionality** - Does the change ultimately impact how firmware functions? - Examples: Add a new library, publish a new PPI, update an algorithm, ... - [ ] Impacts security? - **Security** - Does the change have a direct security impact on an application, flow, or firmware? - Examples: Crypto algorithm change, buffer overflow fix, parameter validation improvement, ... - [ ] Breaking change? - **Breaking change** - Will anyone consuming this change experience a break in build or boot behavior? - Examples: Add a new library class, move a module to a different repo, call a function in a new library class in a pre-existing module, ... - [ ] Includes tests? - **Tests** - Does the change include any explicit test code? - Examples: Unit tests, integration tests, robot tests, ... - [x] Includes documentation? - **Documentation** - Does the change contain explicit documentation additions outside direct code modifications (and comments)? - Examples: Update readme file, add feature readme file, link to documentation on an a separate Web page, ... ## How This Was Tested N/A ## Integration Instructions N/A --- Docs/alignment_mu.png | Bin 0 -> 28304 bytes Docs/feature_memory_protection.md | 546 ++++++++++++++++++++++++++++++ Docs/guardpages_mu.png | Bin 0 -> 19919 bytes 3 files changed, 546 insertions(+) create mode 100644 Docs/alignment_mu.png create mode 100644 Docs/feature_memory_protection.md create mode 100644 Docs/guardpages_mu.png diff --git a/Docs/alignment_mu.png b/Docs/alignment_mu.png new file mode 100644 index 0000000000000000000000000000000000000000..d71ed4f6e9f3133b2eaf840b116a3ff9daa1e271 GIT binary patch literal 28304 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 +#include +``` + +and somewhere within the code doing something like: + +```C + DXE_MEMORY_PROTECTION_SETTINGS DxeSettings; + MM_MEMORY_PROTECTION_SETTINGS MmSettings; + + DxeSettings = (DXE_MEMORY_PROTECTION_SETTINGS)DXE_MEMORY_PROTECTION_SETTINGS_DEBUG; + MmSettings = (MM_MEMORY_PROTECTION_SETTINGS)MM_MEMORY_PROTECTION_SETTINGS_DEBUG; + + BuildGuidDataHob ( + &gDxeMemoryProtectionSettingsGuid, + &DxeSettings, + sizeof (DxeSettings) + ); + + BuildGuidDataHob ( + &gMmMemoryProtectionSettingsGuid, + &MmSettings, + sizeof (MmSettings) + ); +``` + +This will also require you to add gMemoryProtectionSettingsGuid under the Guids section in the relevant INF. + +If you want to deviate from one of the settings profile definitions in DxeMemoryProtectionSettings.h +and/or MmMemoryProtectionSettings, it is recommended +that you start with the one which most closely aligns with your desired settings and update from there in a +manner similar to below: + +```C + MmSettings.HeapGuardPolicy.Fields.MmPageGuard = 0; + MmSettings.HeapGuardPolicy.Fields.MmPoolGuard = 0; + DxeSettings.ImageProtectionPolicy.Fields.ProtectImageFromUnknown = 1; +``` + +before building the HOB. + +## Memory Protection Special Regions + +Memory protection is not activated until the CPU Architecture Protocol has been installed +because the protocol facilitates access to the attribute manipulation functions in CpuDxe +which update the translation/page tables. Many allocations and image loads will have occurred +by the time the protocol is published so careful accounting is required to ensure appropriate +attributes are applied. An event notification triggered on the CPU Architecture Protocol +installation will combine the GCD and EFI memory maps to create a full map of memory for use +internally by the memory protection initialization logic. Because image memory is allocated +for the entire image and not each section (code and data), the images are separated within +the combined map so NX can be applied to data regions and RO can be applied to code regions. +After breaking up the map so each DXE image section has its own descriptor, every non-image +descriptor will have its attributes set based on its EFI memory type. There are cases where +the platform will want to apply attributes to a region of memory which is different than what +would be applied based on its EFI memory type. In this case, + +platforms can utilize the Memory Protection Special Region interface to specify regions +which should have specific attributes applied during memory protection initialization. + +### Example Declaration of Special Region in PEI + +```C +#include + +MEMORY_PROTECTION_SPECIAL_REGION SpecialRegion; +SpecialRegion.Start = 0x1000; +SpecialRegion.Length = 0x1000; +SpecialRegion.Attributes = EFI_MEMORY_RO; + +BuildGuidDataHob ( + &gMemoryProtectionSpecialRegionHobGuid, + &SpecialRegion, + sizeof (SpecialRegion) + ); + +``` + +### Example Declaration of Special Region in DXE + +```C +#include + +MEMORY_PROTECTION_SPECIAL_REGION_PROTOCOL *SpecialRegionProtocol = NULL; +EFI_PHYSICAL_ADDRESS BufferStart = 0x1000; +UINT64 BufferLength = 0x1000; +UINT64 BufferAttributes = EFI_MEMORY_RO; + +Status = gBS->LocateProtocol (&gMemoryProtectionSpecialRegionProtocolGuid, NULL, (VOID **)&SpecialRegionProtocol); +ASSERT_EFI_ERROR (Status); +if (SpecialRegionProtocol != NULL) { + Status = SpecialRegionProtocol->AddSpecialRegion ( + BufferStart, + BufferLength, + BufferAttributes + ); + + ASSERT_EFI_ERROR (Status); +} +``` + +These special regions also may be used during paging audit tests which check if the +page table has secure attributes. For example, an existing test checks to see if there +are any Read/Write/Execute memory regions and fail if true. During this test, if a +Read/Write/Execute region is found, it will be checked against the special regions +and a test failure will not be emitted if the page attributes are consistent with the +attributes identified in the overlapping special region. + +## Debugging + +After a page fault is triggered, it is time to debug what caused it. The following is +an example of debugging an x86 platform. The same principles apply to ARM platforms +though the register names and Assembly instructions will be different. + +### Example 1 + +Page faults result in an exception message in UEFI, such as the example exception below: + +```text +!!!! X64 Exception Type - 0E(#PF - Page-Fault) CPU Apic ID - 00000000 !!!! +ExceptionData - 0000000000000002 I:0 R:0 U:0 W:1 P:0 PK:0 SS:0 SGX:0 +RIP - 000000007A5B100A, CS - 0000000000000038, RFLAGS - 0000000000000206 +RAX - 0000000000000000, RCX - 0000000000000001, RDX - 000000007A127C00 +RBX - 00000000FFFFFFFF, RSP - 000000007EEDC5F0, RBP - 000000007A5CAFC8 +RSI - 000000007A5D2E98, RDI - 000000007A128000 +R8 - 0000000000000000, R9 - 000000007CC24938, R10 - 000000007D0212A0 +R11 - 0000000000000000, R12 - 0000000000000000, R13 - 0000000000000000 +R14 - 000000000000017D, R15 - 0000000000000000 +DS - 0000000000000030, ES - 0000000000000030, FS - 0000000000000030 +GS - 0000000000000030, SS - 0000000000000030 +CR0 - 0000000080010033, CR2 - 000000007A128000, CR3 - 000000007EC01000 +CR4 - 0000000000000668, CR8 - 0000000000000000 +DR0 - 0000000000000000, DR1 - 0000000000000000, DR2 - 0000000000000000 +DR3 - 0000000000000000, DR6 - 00000000FFFF0FF0, DR7 - 0000000000000400 +GDTR - 000000007E50BF30 0000000000000057, LDTR - 0000000000000000 +IDTR - 000000007D044000 0000000000000FFF, TR - 0000000000000048 +FXSAVE_STATE - 000000007E50B380 +``` + +The exception information contains a dump of the register values of the CPU +that tripped the exception. One item to note is `CR2`, which is the Page Fault +Linear Address (PFLA) register. When a page fault occurs, `CR2` is filled with +the address that was accessed and triggered the page fault. + +To help decipher the information, it is also helpful to have the following item: + +- Debug Log from the system +- Access to the binary files +- Access to the build folders + +From the exception information, find the RIP, which gives the memory address +that was being executed when the exception was triggered. In this case it is +`000000007A5B100A`. + +From the debug log, find the driver associated with instruction pointer address. +This can usually be done by masking off the lower bits of the instruction pointer, +in this case looking for `7A5B0000` results in the line: + +```text +Loading driver at 0x0007A5B0000 EntryPoint=0x0007A5B1160 MemoryFaultApp.efi +InstallProtocolInterface: BC62157E-3E33-4FEC-9920-2D3B36D750DF 7A5C6F88 +ProtectUefiImageMu - 0x7A5D2EA0 + 0x000000007A5B0000 - 0x000000000000C000 + CreateImagePropertiesRecord - Enter... + Image: Build\QemuQ35Pkg\DEBUG_VS2022\X64\MemoryFaultApp\MemoryFaultApp\DEBUG\MemoryFaultApp.pdb +``` + +`7A5B100A - 7A5B0000 = 100A` which is the the offset within the image where the +page fault occurred. + +If the driver binary is available, `dumpbin` can be helpful. Dumpbin is part +of Visual Studio and can be used to disassemble the executable to locate +the instruction which triggered the page fault. The command is: +`dumpbin.exe /disasm /out:outputfile.txt` + +Note: If this is performed on the system where the PDB files still exist, the disassembly +will contain function names. Otherwise the disassembly will only contain Assembly code. + +Without PDB Files: + +```text + 0000000000001000: 57 push rdi + 0000000000001001: 4C 89 C0 mov rax,r8 + 0000000000001004: 48 89 CF mov rdi,rcx + 0000000000001007: 48 87 CA xchg rcx,rdx + 000000000000100A: F3 AA rep stos byte ptr [rdi] + 000000000000100C: 48 89 D0 mov rax,rdx + 000000000000100F: 5F pop rdi + 0000000000001010: C3 ret +``` + +With PDB Files: + +```text +InternalMemSetMem: + 0000000000001000: 57 push rdi + 0000000000001001: 4C 89 C0 mov rax,r8 + 0000000000001004: 48 89 CF mov rdi,rcx + 0000000000001007: 48 87 CA xchg rcx,rdx + 000000000000100A: F3 AA rep stos byte ptr [rdi] + 000000000000100C: 48 89 D0 mov rax,rdx + 000000000000100F: 5F pop rdi + 0000000000001010: C3 ret +``` + +In this case, the store string instruction `stos` caused the page fault. Checking RDI and seeing +that its value is `000000007A128000`, gives a clue that the instruction appears to accessing +memory that is not inside of the image. This memory may be allocated. Checking the +RCX shows that the `rep` is almost of the end of the loop that it is executing, meaning +that this scenario may be that the loop is writing to past the memory that it allocated. + +If the map file is available, it's possible to work back to the function name that triggered the +page fault. The map file is usually located in the same directory as the PDB file. In the Map +file, the `Rva+Base` is the starting address of the function, and `100A` falls into the +`InternalMemSetMem` function. + +```text + Address Publics by Value Rva+Base Lib:Object + + 0001:00000000 InternalMemSetMem 0000000000001000 BaseMemoryLibRepStr:SetMem.obj + 0001:00000020 InternalMemSetMem64 0000000000001020 BaseMemoryLibRepStr:SetMem64.obj + 0001:00000040 InternalMemSetMem32 0000000000001040 BaseMemoryLibRepStr:SetMem32.obj + 0001:00000060 CpuPause 0000000000001060 BaseLib:CpuPause.obj +``` + +From this information, it should be possible to examine the source code and determine what +functions could trigger this fault, and fix any logic error that caused the page fault to trigger. + +### Example 2 + +Another example, this time of a NULL pointer dereference. + +```text +INFO - !!!! X64 Exception Type - 0E(#PF - Page-Fault) CPU Apic ID - 00000000 !!!! +INFO - ExceptionData - 0000000000000000 I:0 R:0 U:0 W:0 P:0 PK:0 SS:0 SGX:0 +INFO - RIP - 000000007A642A67, CS - 0000000000000038, RFLAGS - 0000000000000246 +INFO - RAX - 0000000000000000, RCX - 0000000000000000, RDX - 0000000000000000 +INFO - RBX - 00000000FFFFFFFF, RSP - 000000007EEDC600, RBP - 000000007A65BFC8 +INFO - RSI - 000000007A663E98, RDI - 0000000000000000 +INFO - R8 - 000000007EA803D0, R9 - 000000007CE24D50, R10 - 000000007D0BF2A0 +INFO - R11 - 000000007EEDC5A0, R12 - 0000000000000000, R13 - 0000000000000000 +INFO - R14 - 000000000000017D, R15 - 0000000000000000 +INFO - DS - 0000000000000030, ES - 0000000000000030, FS - 0000000000000030 +INFO - GS - 0000000000000030, SS - 0000000000000030 +INFO - CR0 - 0000000080010033, CR2 - 0000000000000010, CR3 - 000000007EC01000 +INFO - CR4 - 0000000000000668, CR8 - 0000000000000000 +INFO - DR0 - 0000000000000000, DR1 - 0000000000000000, DR2 - 0000000000000000 +INFO - DR3 - 0000000000000000, DR6 - 00000000FFFF0FF0, DR7 - 0000000000000400 +INFO - GDTR - 000000007E9A9F30 0000000000000057, LDTR - 0000000000000000 +INFO - IDTR - 000000007D0E2000 0000000000000FFF, TR - 0000000000000048 +``` + +Please note that the `CR2` register, PFLA, is `10h`. When a page fault occurs, +the PFLA register is filled with the address that the offending code attempts to +access, in this case it is address `10h`. Based on the `CR2` value, and knowing +that this is in the first page of memory on the system, we can assume this is a +NULL pointer dereference. But to be sure, following the same steps as above +will lead to the offending code. + +Finding the module that the `000000007A642A67` memory address references from +the debug log. + +```text +Loading driver at 0x0007A641000 EntryPoint=0x0007A642160 MemoryFaultApp.efi +SecurityCookie set to -7238034631654355074 +InstallProtocolInterface: BC62157E-3E33-4FEC-9920-2D3B36D750DF 7A657F88 +ProtectUefiImageMu - 0x7A663EA0 + - 0x000000007A641000 - 0x000000000000C000 +CreateImagePropertiesRecord - Enter... + Image: Build\QemuQ35Pkg\DEBUG_VS2022\X64\MemoryFaultApp\MemoryFaultApp\DEBUG\MemoryFaultApp.pdb +``` + +From the Loading Driver address, it shows that offset `0x1A67` is the code that triggered the +page fault. + +Running `dumpbin` over the binary, and finding instructions at address `1A67`. + +```text + 0000000000001A5A: 8B D3 mov edx,ebx + 0000000000001A5C: 8B CB mov ecx,ebx + 0000000000001A5E: E8 41 36 00 00 call ShellPrintEx + 0000000000001A63: 33 D2 xor edx,edx + 0000000000001A65: 33 C9 xor ecx,ecx + 0000000000001A67: FF 14 25 10 00 00 call qword ptr [10h] + 00 +``` + +In this case, there is a call to a function whose address is supposed to be stored + +at memory address 10h. This address is in the first page of memory, which is protected +by the NULL page guard. This indicates that a NULL pointer is being dereferenced. diff --git a/Docs/guardpages_mu.png b/Docs/guardpages_mu.png new file mode 100644 index 0000000000000000000000000000000000000000..5a3e3929f5ca96559874635f77208c23f7b3cd63 GIT binary patch literal 19919 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 x@&FdN1cB82I3MbCNkEML|9|^G*c