DEV Community: MachineHunter

How to Reverse UEFI modules (DXE Driver)

MachineHunter — Wed, 09 Nov 2022 16:27:36 +0000

Unlike executables running above OS, UEFI modules doesn't have import functions or systemcalls which is usually the important factor in reverse engineering. Therefore, things to focus on when reversing UEFI modules and executables above OS are quite different.
In this post, I'll explain what factors am I focusing on when reversing UEFI modules.

Abstract

The important factors, which I think should be focused on are below.

UEFI Services
UEFI Protocols
Register and those IO types info of devices

UEFI Services and Protocols are the most valuable information (just like Windows API and system call when reversing above OS executables) and this can be auto-analyzed by plugins of decompilers such as Ghidra and IDA. Therefore, I'll mostly focus around device-specific register here.

Environment Setup

UEFI Services and Protocols can be auto-analyzed by below plugins. I'll be using Ghidra+efiseek in this post.

efiseek (for Ghidra)
efiXplorer (for IDA Pro)

UEFI Services

While Protocols are mostly for accessing devices' functionality, UEFI Services are for offering more general functionality. Therefore, if you want to reverse malware that infect boot chains or UEFI applications (not DXE drivers or the modules before DXE), UEFI Services are the most important factor to focus on.

Entrypoint of UEFI modules

Most UEFI modules derives EFI_SYSTEM_TABLE as a second parameter of entrypoint.



EFI_STATUS EFIAPI UefiMain(
  IN EFI_HANDLE ImageHandle,
  IN EFI_SYSTEM_TABLE *SystemTable
)

UEFI Services can be accessed from this EFI_SYSTEM_TABLE.

SystemTable->BootServices
SystemTable->RuntimeServices

In most cases, these BootServices and RuntimeServices are stored in a global variable like below. (When developing UEFI modules in EDK2, people mostly include <Library/UefiBootServicesTableLib.h> or <Library/UefiRuntimeServicesTableLib.h> and these offeres gBS and gRT)

You also can see HOBs and DXE Service Tables are stored in global variables DAT_8000f120 and DAT_8000f128. These can be seen in DXE driver's entrypoint. Main function is the function that has the above feature (refer ghidra comment).

Analyzing UEFI Services

For this, just google the UEFI Service you want to analyze and rename arguments. In this post, I'll just explain below.

Memory Allocation (AllocatePool, AllocatePages)
Protocol (LocateProtocol, InstallMultipleProtocolInterfaces)
Events (CreateEvent, CreateEventEx, RegisterProtocolNotify)

I'll explain Protocol in the Protocol section so I'm going to explain the other two.

Memory Allocation

This is like UEFI version of heap allocation.
In UEFI, memory is seperated into several regions and these can be referenced by gBS->GetMemoryMap. You can specify where in this region to allocate by EFI_MEMORY_TYPE argument of below function.

gBS->AllocatePool (for small 8B aligned buffer)
gBS->AllocatePages (for large 4KB aligned buffer)

Events

UEFI Events are created by these 2 BootServices.

gBS->CreateEvent
gBS->CreateEventEx (Ex can specify event groups named by GUID)

For both functions, it will execute the 3rd argument (EFI_EVENT_NOTIFY) function when the events specified by last
argument (EFI_EVENT) is signaled.

There are actually 2 types of event EVT_NOTIFY_SIGNAL(0x200) and EVT_NOTIFY_WAIT(0x100) which can be specified in the 1st argument. The way of signaling the event differs among this argument as follows.

EVT_NOTIFY_SIGNAL(0x200): gBS->SignalEvent
EVT_NOTIFY_WAIT(0x100): gBS->CheckEvent, gBS->WaitForEvent

But mostly in DXE drivers, you'll see gBS->RegisterProtocolNotify used as a set with gBS->CreateEvent.

gBS->RegisterProtocolNotify is a function that signals 2nd argument (EFI_EVENT) when protocol specified with the 1st argument (EFI_GUID) is installed.
More detailed information about UEFI Events can be found here.

UEFI Protocols

If you want to analyze some device specific functions or DXE driver, the most important factor is UEFI Protocol.

Analyzing Protocol's function usage

If you want to see the use of Protocol's function, you can search by the GUID of protocol, and use xref to find gBS->LocateProtocol.

Then the handle of that protocol is stored in the last argument of LocateProtocol, so you can see if any function call is made like handleOfProtocol[offset](args...).

Analyzing Protocol's functions

If you want to analyze specific function of a protocol, you first have to look for the installation of that protocol. This can be done by searching binary with protocol's GUID and refer to that xref to find the gBS->InstallProtocolInterface or gBS->InstallMultipleProtocolInterfaces.

In most cases, you can find a list of protocols that the DXE driver produces by looking for InstallMultipleProtocolInterfaces called mostly in the driver's entrypoint.

For example, if we have below lines, it means,

DAT_80000518: function list of EFI_TREE_PROTOCOL
DAT_80000550: function list of Protocol that has GUID in DAT_800003f0
DAT_80000560: function list of Protocol that has GUID in DAT_80000400
DAT_80000590: function list of EFI_TCG_PRIVATE_INTERFACE

(Actually, efiseek is a bit old. It's not TreeProtocol which is for TPM1.2 but it's Tcg2Protocol for TPM2.0)

So, if we want to analyze this SubmitCommand of Tcg2Protocol,

you have to look at below's address 0x800034CC.
(My Ghidra's ImageBase is 0x80000000)

Then, if you jump to that address, there will be the content of SubmitCommand as below.

Register and those IO types info of devices

When you want to see the actual interaction with the device, you first need to know what kind of register does that device has, and how can we access to that register (the IO type).
As an example, I will use TPM and analyze the above SubmitCommand function (Tcg2Protocol's function).

Knowing Device's registers

You have to refer to that device's specification for this (though, some devices specify the way to IO in their spec). For TPM, the list of registers are defined in here (PTP spec).
(There are FIFO and CRB columns but you can ignore CRB)

Each register's explanaitions are written in the following page of the link above. There are tons of registers so you can refer to this when you actually see the access to that register.

Knowing Device's IO types

For this, you actually have to see the platform (SoC) specification not the device's specification. Because the "connection" between device and the cpu is defined in SoC like below.

(This is from "Intel® Pentium® and Celeron® Processor N- and J- Series Datasheet")

In this SoC specification, the IO of every device is listed like below.

We can see here that, TPM's IO type is MMIO (Memory Mapped IO). MMIO is an IO that maps device's register to the specific memory range, so that you can read/write register values by read/write to that memory address.

We also can see from the specification that the TPM is mapped to the memory address 0xFED40000 (We have 2 TPM in the spec but ignore the 0xFED41000 one).

Reversing SubmitCommand

Now we know that the TPM's register is mapped to 0xFED40000 and we know where to look at for each register's definition. Then you can reverse the function below.

We see the exact same address above. Let's see inside FUN_8000d1bc to see how this address specified in the first argument is used.

We can see a lots of *TpmMmioBase & 0x20 here. *TpmMmioBase means it's referring the first content of the mapped register so let's look at the PTP spec to find out this register.

It's TPM_ACCESS_0 so *TpmMmioBase & 0x20 is equivalent to TpmMmioBase->TPM_ACCESS_0 & 0x20. 0x20 = 0b00100000 so it's checking the 6th bit of TPM_ACCESS_0 register is set or not.
Therefore, let's look at the 6th bit of TPM_ACCESS_0 register in the same spec.

Now We can see that it's checking if this activeLocality is set or not.

You can create struct refering to the spec to make decompile more readable. As an example, it will get clean like this.

Before

After

(By the way, EFI_STATUS values can be found referring UefiBaseType.h and Base.h of EDK2.)

How to make custom UEFI Protocol

MachineHunter — Sun, 31 Jul 2022 09:13:02 +0000

DXE Driver's main task is to create and install Protocols. In this post, I will explain how to create Protocol in EDK2 and how to use that protocol from other UEFI module.

UEFI Protocol Explanation

DXE Driver abstract the access to the device by creating Protocols. For example, you can use Tcg2Protocol to access TPM2.0 functionality rather than accessing it via things like MMIO or Port IO. Protocols are data structures containing function pointers and the actual function's contents are in the DXE Driver which installed that Protocol. The Protocol (data structure) itself is also in that DXE Driver (usually in .data section).

(Image from EDK2 UEFI Driver Writer's Guide 3.6.2)

Each Protocol has its own GUID and this is used for other UEFI modules to locate this Protocol. Several Protocols can be grouped and this group is identified by Handle. Therefore, you can use gBS->LocateHandle first to locate Handle and then locate the Protocol inside. However, it might be more simpler to use gBS->LocateProtocol to locate Protocol by GUID directly.

Protocols are stored into a single database because it has to be accessible via any UEFI modules. In order to store the protocol to this database, the DXE Driver which create the protocol has to use gBS->InstallMultipleProtocolInterfaces inside.

Implementation

MyDxe2.inf

Let's start with the inf file. The main point is to write gEfiDummyProtocol to the [Protocols]. We have to write the Protocols this DXE Driver produce and also consume.



[Defines]

  INF_VERSION                    = 0x00010006

  BASE_NAME                      = MyDxe2

  FILE_GUID                      = 9d46dccd-ea11-4808-93e9-9b7021889b2d

  MODULE_TYPE                    = DXE_DRIVER

  VERSION_STRING                 = 1.0

  ENTRY_POINT                    = MyDxeEntry

[Sources]

    MyDxe2.h

    MyDxe2.c

[Packages]

    MdePkg/MdePkg.dec

    MdeModulePkg/MdeModulePkg.dec

[LibraryClasses]

    UefiDriverEntryPoint

    UefiRuntimeServicesTableLib

    UefiBootServicesTableLib

    UefiLib

    PrintLib

[Protocols]

    gEfiDummyProtocolGuid   ## PRODUCES

[Depex]

    TRUE

MyDxe2.h

This is the header file. This mainly defines types like EFI_DUMMY_PROTOCOL or DUMMY_FUNC1, so that you can use it in MyDxe2.c. Definition of gEfiDummyProtocolGuid will be defined in the separate place.



#include <Uefi.h>

  
  
  include <Library/UefiLib.h>



  
  
  include <Library/PrintLib.h>



  
  
  include <Library/UefiDriverEntryPoint.h>



  
  
  include <Library/UefiRuntimeServicesTableLib.h>



  
  
  include <Library/UefiBootServicesTableLib.h>





typedef EFI_STATUS (EFIAPI DUMMY_FUNC1)();

typedef EFI_STATUS (EFIAPI DUMMY_FUNC2)();

// e9811f61-14bd-4637-8d17-aec540d8f508

#define EFI_DUMMY_PROTOCOL_GUID \

    { 0xe9811f61, 0x14bd, 0x4637, { 0x8d, 0x17, 0xae, 0xc5, 0x40, 0xd8, 0xf5, 0x08 } }



extern EFI_GUID gEfiDummyProtocolGuid;

typedef struct _EFI_DUMMY_PROTOCOL {

    DUMMY_FUNC1 DummyFunc1;

    DUMMY_FUNC2 DummyFunc2;

} EFI_DUMMY_PROTOCOL;

MyDxe2.c

This is the DXE Driver's contents. mDummy is the actual data structure of this Protocol and this Protocol is installed by gBS->InstallMultipleProtocolInterfaces. The content of DummyFunc1 and DummyFunc2 can be any, but in this example, I'm storing the message "DummyFuncN called" in UEFI variable called MyDxeStatus, so that, you can check if the Protocols is really running correctly.



#include "MyDxe2.h"



UINT32 myvarSize      = 30;

CHAR8  myvarValue[30] = {0};

CHAR16 myvarName[30]  = L"MyDxeStatus";

// eefbd379-9f5c-4a92-a157-ae4079eb1448

EFI_GUID myvarGUID = { 0xeefbd379, 0x9f5c, 0x4a92, { 0xa1, 0x57, 0xae, 0x40, 0x79, 0xeb, 0x14, 0x48 }};

EFI_HANDLE mDummyHandle = NULL;

EFI_STATUS EFIAPI DummyFunc1() {

    AsciiSPrint(myvarValue, 18, "DummyFunc1 called");

    gRT->SetVariable(

            myvarName,

            &myvarGUID,

            EFI_VARIABLE_NON_VOLATILE | EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS,

            myvarSize,

            myvarValue);

    return EFI_SUCCESS;

}

EFI_STATUS EFIAPI DummyFunc2() {

    AsciiSPrint(myvarValue, 18, "DummyFunc2 called");

    gRT->SetVariable(

            myvarName,

            &myvarGUID,

            EFI_VARIABLE_NON_VOLATILE | EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS,

            myvarSize,

            myvarValue);

    return EFI_SUCCESS;

}

EFI_DUMMY_PROTOCOL mDummy = {

    DummyFunc1,

    DummyFunc2

};

EFI_STATUS EFIAPI MyDxeEntry(IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable) {

    gBS->InstallMultipleProtocolInterfaces(&mDummyHandle, &gEfiDummyProtocolGuid, &mDummy, NULL);

<span class="n">EFI_TIME</span> <span class="n">time</span><span class="p">;</span>
<span class="n">gRT</span><span class="o">-&gt;</span><span class="n">GetTime</span><span class="p">(</span><span class="o">&amp;</span><span class="n">time</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span>
<span class="n">AsciiSPrint</span><span class="p">(</span><span class="n">myvarValue</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="s">"%2d/%2d %2d:%2d"</span><span class="p">,</span> <span class="n">time</span><span class="p">.</span><span class="n">Month</span><span class="p">,</span> <span class="n">time</span><span class="p">.</span><span class="n">Day</span><span class="p">,</span> <span class="n">time</span><span class="p">.</span><span class="n">Hour</span><span class="p">,</span> <span class="n">time</span><span class="p">.</span><span class="n">Minute</span><span class="p">);</span>

<span class="n">gRT</span><span class="o">-&gt;</span><span class="n">SetVariable</span><span class="p">(</span>
        <span class="n">myvarName</span><span class="p">,</span>
        <span class="o">&amp;</span><span class="n">myvarGUID</span><span class="p">,</span>
        <span class="n">EFI_VARIABLE_NON_VOLATILE</span> <span class="o">|</span> <span class="n">EFI_VARIABLE_BOOTSERVICE_ACCESS</span> <span class="o">|</span> <span class="n">EFI_VARIABLE_RUNTIME_ACCESS</span><span class="p">,</span>
        <span class="n">myvarSize</span><span class="p">,</span>
        <span class="n">myvarValue</span><span class="p">);</span>

<span class="k">return</span> <span class="n">EFI_SUCCESS</span><span class="p">;</span>



}

MdeModulePkg.dec

We should define gEfiDummyProtocolGuid to MdeModulePkg.dec in order to use gEfiDummyProtocolGuid in the other UEFI module. Inside MdeModulePkg.dec, add the definition like below.



[Protocols]

...

  ## MyDxe/MyDxe2.h

  gEfiDummyProtocolGuid = { 0xe9811f61, 0x14bd, 0x4637, { 0x8d, 0x17, 0xae, 0xc5, 0x40, 0xd8, 0xf5, 0x08 } }

MdeModulePkg.dsc



[Components]

  MdeModulePkg/MyDxe/MyDxe2.inf

  ...

Build it

Make sure you have ACTIVE_PLATFORM = MdeModulePkg/MdeModulePkg.dsc in Conf/target.txt and let's build it. Then, construct FFS file like I explained in the previous post, add the FFS file to the BIOS image, and flash the SPI flash chip with that image.

Using DummyProtocol

Next, let's write a module that uses this Protocol. I will be writing a UEFI module that runs from a USB memory in BDS phase, so that I can print the output to the screen easily.
Create a folder named AppPkg/ under edk2/ and will be creating these files.



AppPkg/

├── AppPkg.dec

├── AppPkg.dsc

└── Applications/

    └── UseDummyProtocol/

        ├── UseDummyProtocol.c

        └── UseDummyProtocol.inf

AppPkg.dec

FirstPkg can be any name.



[Defines]

  DEC_SPECIFICATION              = 0x00010005

  PACKAGE_NAME                   = FirstPkg

  PACKAGE_GUID                   = 75281f80-8657-4cf2-837f-04d73179c590

  PACKAGE_VERSION                = 0.1

AppPkg.dsc



[Defines]

  PLATFORM_NAME                  = FirstPkg

  PLATFORM_GUID                  = 7b86cb02-9fbb-4f77-8d93-35c8c90f2488

  PLATFORM_VERSION               = 0.1

  DSC_SPECIFICATION              = 0x00010005

  OUTPUT_DIRECTORY               = Build/FirstPkg$(ARCH)

  SUPPORTED_ARCHITECTURES        = IA32|X64

  BUILD_TARGETS                  = DEBUG|RELEASE|NOOPT

  DEFINE DEBUG_ENABLE_OUTPUT     = TRUE

[LibraryClasses]

  # Entry point

  UefiApplicationEntryPoint|MdePkg/Library/UefiApplicationEntryPoint/UefiApplicationEntryPoint.inf

  ShellCEntryLib|ShellPkg/Library/UefiShellCEntryLib/UefiShellCEntryLib.inf

# Common Libraries

  BaseLib|MdePkg/Library/BaseLib/BaseLib.inf

  BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf

  PcdLib|MdePkg/Library/BasePcdLibNull/BasePcdLibNull.inf

  UefiBootServicesTableLib|MdePkg/Library/UefiBootServicesTableLib/UefiBootServicesTableLib.inf

  !if $(DEBUG_ENABLE_OUTPUT)

    DebugLib|MdePkg/Library/UefiDebugLibConOut/UefiDebugLibConOut.inf

    DebugPrintErrorLevelLib|MdePkg/Library/BaseDebugPrintErrorLevelLib/BaseDebugPrintErrorLevelLib.inf

  !else   ## DEBUG_ENABLE_OUTPUT

    DebugLib|MdePkg/Library/BaseDebugLibNull/BaseDebugLibNull.inf

  !endif  ## DEBUG_ENABLE_OUTPUT

UefiLib|MdePkg/Library/UefiLib/UefiLib.inf

  PrintLib|MdePkg/Library/BasePrintLib/BasePrintLib.inf

  MemoryAllocationLib|MdePkg/Library/UefiMemoryAllocationLib/UefiMemoryAllocationLib.inf

  UefiRuntimeServicesTableLib|MdePkg/Library/UefiRuntimeServicesTableLib/UefiRuntimeServicesTableLib.inf

  UefiBootServicesTableLib|MdePkg/Library/UefiBootServicesTableLib/UefiBootServicesTableLib.inf

  DevicePathLib|MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.inf

  RegisterFilterLib|MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.inf

[Components]

  AppPkg/Applications/UseDummyProtocol/UseDummyProtocol.inf

UseDummyProtocol.inf



[Defines]

  INF_VERSION                    = 0x00010006

  BASE_NAME                      = UseDummyProtocol

  FILE_GUID                      = 5765e8dd-c97a-4ce2-891e-9e24b94d654b

  MODULE_TYPE                    = UEFI_APPLICATION

  VERSION_STRING                 = 0.1

  ENTRY_POINT                    = UefiMain

[Sources]

  UseDummyProtocol.c

[Packages]

  MdePkg/MdePkg.dec

  MdeModulePkg/MdeModulePkg.dec

[LibraryClasses]

  UefiLib

  ShellCEntryLib

  UefiBootServicesTableLib

  UefiRuntimeServicesTableLib

[Protocols]

  gEfiDummyProtocolGuid  ## CONSUME

UseDummyProtocol.c

This is checking UEFI variable MyDxeStatus by GetVariable before and after calling DummyFunc1 (the DummyProtocol's function). DummyFunc1 will change the value of MyDxeStatus to a DummyFunc1 called which was originally the current time set when this DXE Driver was executed.



#include <Uefi.h>

  
  
  include <Library/UefiLib.h>



  
  
  include <Library/UefiBootServicesTableLib.h>



  
  
  include <Library/UefiRuntimeServicesTableLib.h>



  
  
  include <MyDxe/MyDxe2.h>



  
  
  include <Library/BaseMemoryLib.h>





EFI_STATUS EFIAPI UefiMain(IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE SystemTable) {

    EFI_DUMMY_PROTOCOL DummyProtocol;

    gBS->LocateProtocol(&gEfiDummyProtocolGuid, NULL, (VOID**)&DummyProtocol);

<span class="n">CHAR8</span> <span class="n">myvarValue</span><span class="p">[</span><span class="mi">30</span><span class="p">];</span>
<span class="n">UINT64</span> <span class="n">myvarSize</span> <span class="o">=</span> <span class="mi">30</span><span class="p">;</span>
<span class="n">UINT32</span> <span class="n">Attributes</span> <span class="o">=</span> <span class="n">EFI_VARIABLE_NON_VOLATILE</span> <span class="o">|</span> <span class="n">EFI_VARIABLE_BOOTSERVICE_ACCESS</span> <span class="o">|</span> <span class="n">EFI_VARIABLE_RUNTIME_ACCESS</span><span class="p">;</span>
<span class="n">EFI_GUID</span> <span class="n">myvarGUID</span> <span class="o">=</span> <span class="p">{</span> <span class="mh">0xeefbd379</span><span class="p">,</span> <span class="mh">0x9f5c</span><span class="p">,</span> <span class="mh">0x4a92</span><span class="p">,</span> <span class="p">{</span> <span class="mh">0xa1</span><span class="p">,</span> <span class="mh">0x57</span><span class="p">,</span> <span class="mh">0xae</span><span class="p">,</span> <span class="mh">0x40</span><span class="p">,</span> <span class="mh">0x79</span><span class="p">,</span> <span class="mh">0xeb</span><span class="p">,</span> <span class="mh">0x14</span><span class="p">,</span> <span class="mh">0x48</span> <span class="p">}};</span>

<span class="n">Print</span><span class="p">(</span><span class="s">L"[Before Calling Protocol] MyDxeStatus:</span><span class="se">\r\n</span><span class="s">"</span><span class="p">);</span>
<span class="n">gRT</span><span class="o">-&gt;</span><span class="n">GetVariable</span><span class="p">(</span>
        <span class="s">L"MyDxeStatus"</span><span class="p">,</span>
        <span class="o">&amp;</span><span class="n">myvarGUID</span><span class="p">,</span>
        <span class="o">&amp;</span><span class="n">Attributes</span><span class="p">,</span>
        <span class="o">&amp;</span><span class="n">myvarSize</span><span class="p">,</span>
        <span class="n">myvarValue</span><span class="p">);</span>

<span class="n">AsciiPrint</span><span class="p">(</span><span class="s">"%a</span><span class="se">\n\n</span><span class="s">"</span><span class="p">,</span> <span class="n">myvarValue</span><span class="p">);</span>

<span class="n">DummyProtocol</span><span class="o">-&gt;</span><span class="n">DummyFunc1</span><span class="p">();</span>

<span class="n">Print</span><span class="p">(</span><span class="s">L"[After Calling Protocol] MyDxeStatus:</span><span class="se">\r\n</span><span class="s">"</span><span class="p">);</span>
<span class="n">gRT</span><span class="o">-&gt;</span><span class="n">GetVariable</span><span class="p">(</span>
        <span class="s">L"MyDxeStatus"</span><span class="p">,</span>
        <span class="o">&amp;</span><span class="n">myvarGUID</span><span class="p">,</span>
        <span class="o">&amp;</span><span class="n">Attributes</span><span class="p">,</span>
        <span class="o">&amp;</span><span class="n">myvarSize</span><span class="p">,</span>
        <span class="n">myvarValue</span><span class="p">);</span>

<span class="n">AsciiPrint</span><span class="p">(</span><span class="s">"%a</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">myvarValue</span><span class="p">);</span>

<span class="k">while</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>



}

Build and Execute it

Before build, change to ACTIVE_PLATFORM = AppPkg/AppPkg.dsc in the Conf/target.txt. Then, build it.
This time, I will store the generated UseDummyProtocol.efi to the USB memory. In USB memory, make a directory EFI/BOOT/ and rename UseDummyProtocol.efi into bootx64.efi and put that into the folder.

Plug the USB into the PC you flashed the BIOS before, and boot that machine. If you see below output, then it's a success.

(I missed specifing the string length...)

Using Intel DCI on ISS to debug UEFI module

MachineHunter — Tue, 26 Jul 2022 11:09:51 +0000

In the previous post, I explained what is Intel DCI and how to setup Intel System Debugger (ISS). In this post, I'll explain how to use ISS to debug UEFI modules. Usage is not really different from other debugger, but it's good to see examples to get the image what it is like.

Breaking at target UEFI module

First of all, there are lots of UEFI modules running in the bootphase. Considering this, the easiest way to break at the UEFI module you want to debug is to put dead-loop at the top of the module. You can just put EB FE at the place you want to break and the execution will stop there. Then, you can use "Move To Line" to exit dead-loop.

Unstable DCI Problem

In some platform or BIOS, DCI maybe unstable. For example, if you suspend the machine, put breakpoint somewhere and resume, then the ISS will say that the system is already running. Also there might be cases, DCI connection resets repeatedly. Several reasons for unstable DCI connection are stated in the Intel System Debugger manual's "Limitation of JTAG Debugging" section which can be found at IntelSWTools/system_studio_2020/documentation_2020/en/debugger/system_studio_2020/system_debugger/system_debug/User_Guide.pdf. But I think most of the cases is because of WatchDog Timers (WDT). This timer checks platform's "heartbeat" condition, and if the "heartbeat" is stopped, platform will reset. Debugger stops execution so WDT will think something went wrong and makes platform resets, which closes the DCI connection. Therefore, you might want to disable WDT if your DCI connection is unstable.

Preparing desired window in ISS

You can get your desired window here.

Connect/Disconnect/Resume/Suspend/Reset/Debug

Breakpoints

Software Breakpoint

You can just double click the narrow space next to the address you want to set a software BP like below (the red square). You can see the list of BPs in the Breakpoints window.

Hardware Breakpoint

Memory Breakpoint (Watchpoint)

There are no such thing called Memory Breakpoint in ISS, but you can use ISS's special BP called Watchpoint to do similar thing. To add Watchpoint, press the below red squared button.

If you want to break when there was a write on the address 0xcafebabe, you can set it like below.

As you can see, you can also use Watchpoint to break on read, and also specify address with range.

Modifing Registers

You can just double click to change value like this in the Registers window.

Memory Browser (Hex View)

You can use Memory Browser window to check hex view around specified address.

You can change the cell size like below.

I couldn't find Stack view in ISS, but you can put rsp value in this Memory Browser to see the stack instead.

ISD Shell (Python Scripts)

You can use ISD Shell to automate operations by python scripts. However, I couldn't find any documentation explaining about the API, so I refered the source code in C:\IntelSWTools\system_studio_2020\tools\ to find out objects or functions, and also used python functions like dir(Object) to check what methods are in that object. I'll leave some of the codes that I used personally, just to get the image how the code will look like.

# Writing value 1 to MSR 0x1d9
threads[0].msr.write(0x1d9, 1)

# Setting 0x7764e7d7 to RIP
next(r for r in threads[0].registers.list() if r.name=="rip").set(0x7764e7d7) 

# Resume
threads[0].runcontrol.resume()

Trace

LBR Trace

LBR (Last Branch Record) is a feature of Intel CPU to record branch trace to MSR. This is hardware mechanism and could be easily enabled by setting MSR IA32_DEBUGCTL (0x1d9) to 1. This article is a good reference to look at about LBR tracing.

To use LBR Trace in ISS, open Instruction Trace View window, and click the red squared button.

Then, change the type to "LBR" and click OK.

After that, click below button to start capturing.

Now let's try it. Put some BP somewhere and press resume. After you hit the BP, you'll see the results shown like this.

You can maximize the view by clicking above button (Press "Restore" to go back to the original view).

Intel Processor Trace (Intel PT)

Intel PT stores trace record to memory rather than MSR. Therefore, this could store far more record than LBR at a time. But actually, it doesn't really matter because ISS can read LBR and keep the data in the memory of analysis machine.

The advantages of using PT is that, PT allows you to configure the trace options more specifically. This is stated in Intel® System Debugger - System Debug User and Reference Guide, but in my ISS, somehow there were no place to configure these options...
The disadvantages of using PT is that, since PT uses memory to store trace information, it's a bit troublesome to enable it (do below two).

set MSR IA32_RTIT_CTL (0x570) to 1
enable PT in the BIOS SETUP screen and allocate enough size of memory you need

To use PT in ISS, you only have to select "PT" in this configuration window.

Reading PCR value from UEFI

MachineHunter — Mon, 25 Jul 2022 12:15:28 +0000

PCR is one of the most-used TPM functionality in UEFI security. Measured boot which ensures integrity of UEFI firmware is a good example of the use of PCR. In this post, I will explain how to read PCR value from UEFI module.
If you are not familiar with TPM programming from UEFI, it might be better to start with my Accessing TPM2.0 from UEFI module Series.

PCR explanaition

PCRs (Platform Configuration Registers) in TPM holds measurements of software states. UEFI uses this value to ensure if none of the code during the bootphase are modified. Value in PCR is actually a hash and this can only be updated by an operation called extend (or system reset). Before executing the next program (e.g. DxeCore, bootloader), the caller extend the PCR value by calculating PCR[i] = H(PCR[i]||m). PCR[i] is the i th PCR's value, H() is the hash function and m is the new measurement of the next program going to be executed.

TPM allows you to control access towards entities depending on PCR value. For example, if you want to have a key which is only accessible during specific part in the bootphase, you can authenticate the key with a policy which only allows reading operation when PCR has specific value.

There are at least 24 PCRs on any platform. Each PCRs are meant to store different software's measurements, and typical example is like below.

(Image from A Practical Guide to TPM 2.0)

The actual allocation depends on PC client, but in this post, I'll read the value of PCR[0].

PCR bank is a group of PCR with same hash algorithm. Simple example is like below.



PCR bank 0 (sha1)
  * PCR[0]: sha1 value
  * ...
  * PCR[23]: sha1 value

PCR bank 1 (sha256)
  * PCR[0]: sha256 value
  * ...
  * PCR[23]: sha256 value

This is to handle issues like compatibility for old application only using old hash, or new application restricting to use only strong hash. When extending PCR[i] value, TPM should extend each bank's PCR[i] if that PCR is present in bank. There are cases when PCR[i] is implemented in bank0 but not in bank1. I will be reading from PCR bank with sha256 hash.

For further description of PCR, you can refer to TCG spec part1.

Implementation

I will be using EDK2 to build the UEFI module. There are actually two ways to access PCR from UEFI.

Using Tcg2Protocol.GetActivePcrBanks
Using Tcg2Protocol.SubmitCommand to send TPM2_PCR_Read command I will be using 2 in this post.

TPM2_PCR_Read format

Looking at TCG spec part3, you can check the command's format as follows.

TPML_PCR_SELECTION

Structure's definition can be found at TCG spec part2, and the actual definition of the structure in EDK2 can be found in MdePkg/Include/IndustryStandard/Tpm20.h. To summarize the TPML_PCR_SELECTION structure, it is like follows.



* [TPML_PCR_SELECTION] pcrSelectionIn/pcrSelectionOut
   * [UINT32]             count
   * [TPMS_PCR_SELECTION] pcrSelections[count] (max: HASH_COUNT)
      * [TPMI_ALG_HASH][TPM_ALG_ID][UINT16] hash
      * [UINT8]                             sizeofSelect (min: PCR_SELECT_MIN)
      * [BYTE]                              pcrSelect[sizeofSelect] (max: PCR_SELECT_MAX)

Below are the related constants.



HASH_COUNT         = 5;
PCR_SELECT_MIN     = ((PLATFORM_PCR + 7) / 8) = 3;
PLATFORM_PCR       = 24;
PCR_SELECT_MAX     = ((IMPLEMENTATION_PCR + 7) / 8) = 3;
IMPLEMENTATION_PCR = 24;

IMPLEMENTATION_PCR maybe the actual number of PCR in your PC client, and since EDK2 doesn't know it, you have to change it to the appropriate value. But since we're only accessing only PCR[0], it doesn't matter to keep it this way.

Each pcrSelections specify PCR bank, and each bit in pcrSelect specify PCR. You might wonder why PCR_SELECT_MIN and PCR_SELECT_MAX are 3, but BYTE is 8bit and 3*8=24, which means, each bit specifies the PCR index you want to read. So for example, if you want PCR[0] and PCR[10], you will set pcrSelect for pcrSelectIn like the following (Omitting SwapBytes for simplicity).



pcrSelect[0] = 00000001 = 1
pcrSelect[1] = 00000100 = 4
pcrSelect[2] = 00000000 = 0

TPML_DIGEST

This is where you get the actual value of PCR specified in the pcrSelectionIn. This structure is way simpler than TPML_PCR_SELECTION because it is just a list of digest. But, it might be confusing if you requested multiple PCR values: what value is in what index of digest. This order is actually noted in the description of TPM2_PCR_Read in the spec.

TPM will process the list of TPMS_PCR_SELECTION in pcrSelectionIn in order

Within each TPMS_PCR_SELECTION, the TPM will process the bits in the pcrSelect array in ascending PCR order

Source code

Here is the whole source code getting PCR[0] value from sha256 PCR bank.



#include <Uefi.h>
#include <Library/UefiLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Protocol/Tcg2Protocol.h>
#include <IndustryStandard/Tpm20.h>

#pragma pack(1)
    typedef struct {
        UINT32 count;
        TPMS_PCR_SELECTION pcrSelections[1];
    } ORIG_TPML_PCR_SELECTION;

    typedef struct {
        TPM2_COMMAND_HEADER Header;
        ORIG_TPML_PCR_SELECTION pcrSelectionIn;
    } TPM2_PCR_READ_COMMAND;

    typedef struct {
        TPM2_RESPONSE_HEADER Header;
        UINT32 pcrUpdateCounter;
        ORIG_TPML_PCR_SELECTION pcrSelectionOut;
        TPML_DIGEST pcrValues;
    } TPM2_PCR_READ_RESPONSE;
#pragma pack()


EFI_STATUS EFIAPI UefiMain(IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable) {
    UINT32 i,j;
    EFI_TCG2_PROTOCOL *Tcg2Protocol;
    SystemTable->BootServices->LocateProtocol(&gEfiTcg2ProtocolGuid, NULL, (VOID**)&Tcg2Protocol);

    ORIG_TPML_PCR_SELECTION pcrSelectionIn;
    pcrSelectionIn.count                         = SwapBytes32(1);
    pcrSelectionIn.pcrSelections[0].hash         = SwapBytes16(TPM_ALG_SHA256);
    pcrSelectionIn.pcrSelections[0].sizeofSelect = PCR_SELECT_MIN;

    for(i=0; i<PCR_SELECT_MIN; i++)
        pcrSelectionIn.pcrSelections[0].pcrSelect[i] = 0;

    UINT32 pcrId;
    for(pcrId=0; pcrId<PLATFORM_PCR; pcrId++) {
        if(pcrId==0)
            pcrSelectionIn.pcrSelections[0].pcrSelect[pcrId/8] |= (1<<(pcrId%8));
    }


    TPM2_PCR_READ_COMMAND CmdBuffer;
    UINT32 CmdBufferSize;
    TPM2_PCR_READ_RESPONSE RecvBuffer;
    UINT32 RecvBufferSize;

    CmdBuffer.Header.tag         = SwapBytes16(TPM_ST_NO_SESSIONS);
    CmdBuffer.Header.commandCode = SwapBytes32(TPM_CC_PCR_Read);
    CmdBuffer.pcrSelectionIn     = pcrSelectionIn;
    CmdBufferSize = sizeof(CmdBuffer.Header) + sizeof(CmdBuffer.pcrSelectionIn);
    CmdBuffer.Header.paramSize = SwapBytes32(CmdBufferSize);

    Print(L"sending TPM command...\r\n");

    RecvBufferSize = sizeof(RecvBuffer);
    EFI_STATUS stats = Tcg2Protocol->SubmitCommand(Tcg2Protocol, CmdBufferSize, (UINT8*)&CmdBuffer, RecvBufferSize, (UINT8*)&RecvBuffer);
    if(stats==EFI_SUCCESS)
        Print(L"SubmitCommand Success!\r\n");
    else
        Print(L"stats: 0x%x (EFI_DEVICE_ERROR:0x%x, EFI_INVALID_PARAMETER:0x%x, EFI_BUFFER_TOO_SMALL:0x%x)\r\n", stats, EFI_DEVICE_ERROR, EFI_INVALID_PARAMETER, EFI_BUFFER_TOO_SMALL);


    // parse response
    UINT16 res = SwapBytes32(RecvBuffer.Header.responseCode);
    Print(L"ResponseCode is %d (0x%X)\r\n", res, res);

    UINT32 pcrUpdateCounter = SwapBytes32(RecvBuffer.pcrUpdateCounter);
    Print(L"Pcr Update Counter: %d (0x%X)\r\n", pcrUpdateCounter, pcrUpdateCounter);

    UINT32 cntSelectionOut = SwapBytes32(RecvBuffer.pcrSelectionOut.count);
    Print(L"pcrSelectionOut.count (should be 1): %d\r\n", cntSelectionOut);

    TPMS_PCR_SELECTION* pcrSelections = (TPMS_PCR_SELECTION*)RecvBuffer.pcrSelectionOut.pcrSelections;
    for(i=0; i<cntSelectionOut; i++) {
        UINT8 sizeofSelect = pcrSelections[i].sizeofSelect;
        Print(L"pcrSelections[%d].sizeofSelect (should be 3): %d\r\n", i, sizeofSelect);
        for(j=0; j<sizeofSelect; j++) {
            Print(L"pcrSelections[%d].pcrSelect[%d]: %1x\r\n", i, j, pcrSelections[i].pcrSelect[j]);
        }
    }

    UINT32 cntDigest = SwapBytes32(RecvBuffer.pcrValues.count);
    Print(L"Number of digests: %d\r\n", cntDigest);

    TPM2B_DIGEST* digests = (TPM2B_DIGEST*)RecvBuffer.pcrValues.digests;
    for(i=0; i<cntDigest; i++) {
        UINT16 size = SwapBytes16(digests[i].size);
        BYTE buf[size];
        for(j=0; j<size; j++)
            buf[size-j-1] = digests[i].buffer[j];

        Print(L"pcrValues.digest[%d] (size %d):\r\n", i, size);
        for(j=0; j<size; j++) {
            Print(L"%2X", buf[j]);
        }
        Print(L"\r\n");
        digests = (TPM2B_DIGEST*)(((void*)digests)+sizeof(UINT16)+size);
    }

    while(1);
    return 0;
}

How to add DXE Driver to BIOS image

MachineHunter — Sun, 26 Jun 2022 15:24:53 +0000

In my previous post, I showed you how to make DXE Driver which stores current time in UEFI variable, and convert that into FFS file. To execute this DXE Driver, I'll show you how to add this FFS file into extracted BIOS image from UP2 Pro Board. I will be using followings in this post.

UP Squared Pro ATOM Quad Core 04/64 (UP2 board)
SF100 SPI NOR Flash Programmer (SF100)
ISP Testclip SO8 (TestClip)
UEFITool
UEFI Shell (which is installed by default on UP2 board)

Download UEFITool

UEFITool is an opensource tool to parse and edit UEFI image. I will be using this tool to add FFS file into UEFI image. Don't use the version with "NE" in the name because this version has some restricted functionality.

Extract UEFI image by SF100

First you need to extract UEFI image from UP2 board. You can do this by using SF100, and I explained how to do this in my previous post.

Insert FFS file by UEFITool

Open UEFITool and Drag&Drop UEFI image file extracted by SF100. Then, locate DXE Volume which is a volume that DXE Drivers are stored by searching the string "DXE" by Ctrl-F and double-clicking one of the results.

Go to the last DXE Driver in the volume and right click that.

You will see "Insert after..." if you have downloaded the right version of UEFITool so click on that and select the ffs file generated in the previous post. If successfully added, you will see the result like below.

Press Ctrl-S and save this BIOS image somewhere.

Flashing the UEFI with SF100

Again using SF100, flash the modified UEFI image to the UP2 board. This is also explained in my previous post.

Checking MyDxeStatus Variable to see if DXE Driver executed successfully

Power on the board and see if it boots successfully first. If display won't show up, then there might be some errors in DXE Driver. You can debug DXE Driver by using Intel DCI and I also explained this method in my previous post.

If diplay does show up, it's time to check the UEFI variable. You can execute dmpstore <UEFI variable name> to check UEFI variable values from UEFI Shell.

How to build DXE Driver by EDK2

MachineHunter — Sun, 26 Jun 2022 14:47:00 +0000

In this series, I will show you how to build custom DXE Driver by EDK2 and execute it on UP2 Pro (Single Board Computer). To check if it was executed successfully, this DXE Driver will store current time in UEFI Variable so that, you can check if the time was stored correctly from UEFI Shell.

Preparing EDK2

sudo apt install build-essential uuid-dev iasl nasm git python python3-distutils python3-apt acpica-tools
go to your project's folder and git clone https://github.com/tianocore/edk2.git
cd edk2 and git submodule update --init
make -C BaseTools
source edksetup.sh

BaseTool is a set of tools to build UEFI modules and format the module to EFI_SECTION, FFS, FV and so on. By executing edksetup.sh, you can execute commands in BaseTool without specifying 'PATH'. You might want to take a brief look at the link to know what kind of tools are in BaseTools and what kind of arguments you can specify.

Configuration of EDK2 for making DXE Drivers

1: Editing target.txt

Edit edk2/Conf/target.txt like this (Comments excluded).

ACTIVE_PLATFORM = MdeModulePkg/MdeModulePkg.dsc
TARGET          = DEBUG
TARGET_ARCH     = X64
TOOL_CHAIN_CONF = Conf/tools_def.txt
TOOL_CHAIN_TAG  = GCC5
BUILD_RULE_CONF = Conf/build_rule.txt

You might want to execute build in edk2/ and see if it returns - Done -. If you got any fails at this point, then some configs on your edk2 are wrong.

2: Making necessary files

Make folder for your DXE Driver inside edk2/MdeModulePkg/ and prepare two files inside it like this.

MyDxe
├── MyDxe.c
└── MyDxe.inf

3: Editing MdeModulePkg.dsc

Add your module under the [Component] section inside edk2/MdeModulePkg/MdeModulePkg.dsc like followings.

[Components]
  MdeModulePkg/MyDxe/MyDxe.inf # add only this
  MdeModulePkg/Application/HelloWorld/HelloWorld.inf
  MdeModulePkg/Application/DumpDynPcd/DumpDynPcd.inf
  MdeModulePkg/Application/MemoryProfileInfo/MemoryProfileInfo.inf

Configuring MyDxe.inf

[Defines]
  INF_VERSION                    = 0x00010006
  BASE_NAME                      = MyDxe
  FILE_GUID                      = <put your GUID generated by uuidgen>
  MODULE_TYPE                    = DXE_DRIVER
  VERSION_STRING                 = 1.0
  ENTRY_POINT                    = MyDxeEntry

[Sources]
    MyDxe.c

[Packages]
    MdePkg/MdePkg.dec
    MdeModulePkg/MdeModulePkg.dec

[LibraryClasses]
    UefiDriverEntryPoint
    UefiRuntimeServicesTableLib
    UefiLib
    PrintLib

[Protocols]

[Depex]
    TRUE

I'm not using any Protocols in this DXE Driver so I left [Protocols] blank. If this DXE Driver has to be executed after specific Protocols are installed, you have to put that into [Depex], but I'm not using any Protocols so I just put TRUE. For further details, you can check CodeRush's post in Win-Raid Forum.

Source Code of DXE Driver (MyDxe.c)

#include <Uefi.h>
#include <Library/UefiLib.h>
#include <Library/PrintLib.h>
#include <Library/UefiDriverEntryPoint.h>
#include <Library/UefiRuntimeServicesTableLib.h>

EFI_STATUS EFIAPI MyDxeEntry(IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable) {
    UINT32 myvarSize      = 30;
    CHAR8  myvarValue[30] = {0};
    CHAR16 myvarName[30]  = L"MyDxeStatus";
    EFI_TIME time;

    // 11223344-5566-7788-99aa-bbccddeeff00
    EFI_GUID myvarGUID = { 0x11223344, 0x5566, 0x7788, { 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff, 0x00 }};

    gRT->GetTime(&time, NULL);

    AsciiSPrint(myvarValue, 12, "%2d/%2d %2d:%2d", time.Month, time.Day, time.Hour, time.Minute);

    gRT->SetVariable(
            myvarName,
            &myvarGUID,
            EFI_VARIABLE_NON_VOLATILE | EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS,
            myvarSize,
            myvarValue);

    return EFI_SUCCESS;
}

This will create UEFI variable named "MyDxeStatus" and stores current time derived by GetTime function in the Runtime Services. To prepare format string, I used AsciiSPrint from
PrintLib Library.

Build DXE Driver

You can execute build to build this driver. If there were no errors, it will show Done at the end and output files can be found in edk2/Build/MdeModule/DEBUG_GCC5/X64/MdeModulePkg/MyDxe/MyDxe/OUTPUT.

Generating FFS File from the DXE Driver

If you want to add this DXE Driver into BIOS image, you have to convert this into Fimware FileSystem (FFS) format. FFS is consisted of EFI_SECTION Files, which in most case are below 4 sections.

DXE dependency section
PE32 image section
User interface section
Version section

You can refer to EDK2 Build Specification for the information related to these. But anyway, you have to first generate these section files and then, combine them to construct FFS File. Generating section files can be done by using GenSec command from BaseTools. Also, there is GenFfs command from BaseTools to combine them into FFS file.

Inside edk2/Build/MdeModule/DEBUG_GCC5/X64/MdeModulePkg/MyDxe/MyDxe/OUTPUT/, I made a folder "FFS" and put the generated files there. Section files are generated by the following commands.

GenSec MyDxe.efi -S EFI_SECTION_PE32 -o FFS/MyDxe.pe32
GenSec MyDxe.efi -S EFI_SECTION_USER_INTERFACE -o FFS/MyDxe.ui -n "MyDxe"
GenSec MyDxe.efi -S EFI_SECTION_VERSION -o FFS/MyDxe.ver

cd FFS
GenFfs -t EFI_FV_FILETYPE_DRIVER -d 1 -g "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -i MyDxe.pe32 -i MyDxe.ui -i MyDxe.ver -o MyDxe.ffs

You need to generate GUID for this FFS and specify it in GenFfs. In this DXE Driver, I didn't use DEPEX so I didn't put that, but if you have, you can execute GenSec MyDxe.depex -S EFI_SECTION_DXE_DEPEX -o FFS/MyDxe.depex (MyDxe.depex is already built with build command in the OUTPUT folder) and specify that with -i option in GenFfs command.

Getting Serial Output from UART on UP2 Pro Board

MachineHunter — Sat, 04 Jun 2022 20:51:53 +0000

If you have UART debug port on your device, you can retrieve various information from there. If you are dealing with IoT, you can access to the shell via UART on some device. Also, if you are dealing with PC, you can retrieve output from the UEFI/BIOS early in the boot phase. Retrieving outputs from serial connection is often better because, such interface like HDMI aren't accessible until late in the boot phase.
In this post, I'll explain how to get the serial output from UART on UP squared pro Atom board.

Environment

I will be using followings in this article (hereinafter, these are called by the terms in parentheses).

Windows 10 PC that has USB 3.0 port (Host PC)
UP Squared Pro Atom Quad Core 04/64 (UP2 board)
USB to 3.3v TTL Header (USB to TTL cable)
USB 2.0 pin header cable EP-CBUSB10PFL01 (pin header cable)
Male-to-Male Jumper Wire 3x (jumper wire)

Followings are needed for flashing the BIOS to the one that's build with DEBUG mode.

Install FTDI Driver

In order to use USB to TTL cable, you have to install FTDI Driver in your Host PC if you don't have one. You can download from here by clicking "Windows FTDI Driver" under "Software & Drivers". This is because the above cable uses FTDI chip for handling USB. FTDI chip is one of the most popular USB to TTL converter IC, and this helps converting USB signal to UART signal (FTDI is a company name).

You will see the following installer so execute it to install the FTDI Driver.

To check if you have installed it correctly, connect USB to TTL cable to your Host PC and open device manager. If you have "USB Serial Converter", then the installation is success.

Flashing BIOS to the DEBUG built image

BIOS image built with DEBUG mode often outputs debug info to the serial output. This step is not necessary if you have some module that outputs message to the serial output, but if you don't have any, you can use this to check if the setup is successful.

The BIOS image I will be using is Intel Atom® Processor E3900 Series (Apollo Lake) Up Squared Board Flash Images R .71. You will see two images included in the file, one with "R" and one with "D" in the name. Use the image with "D" in and flash that image to UP2 board. How to flash BIOS is explained in my previous post.

Setting up the UART connection

Connect just like the above image. The pins which is important when using UART is GND, TXD, and RXD. Looking at up-community wiki, it says black cable is GND, white cable is TXD, and red cable is RXD. You have to connect to the coresponding pin shown below.

(image from Gearmo Site)

Other important information to use UART besides pin is baudrate. This is the speed of serial connection. It says on the wiki that the baudrate is 115200bps for this board.

After connecting, you need to configure serial client. Download PuTTY on your Windows host if you don't have one. Open PuTTY and select "Session" from the Category. Then, configure it like below.

For serial line, you can check the device manager to see what COM port it is. In my case, it was "COM3".

Next, select "Serial" under "Connection" in the Category and configure it like below.

These configurations are written in the wiki.

Testing

Now let's give it a shot. Make sure you plugged the USB to TTL cable to your Host PC and had the PuTTY configured. Click "Open" button in the PuTTY window, and if all the configuration are successful, black screen will show up without any errors. After that, power on UP2 board and see if it outputs tons of debug information.

Reference

Setup Intel DCI Debugging on UP Squared Board

MachineHunter — Wed, 25 May 2022 09:00:00 +0000

Using Intel DCI (Direct Connect Interface), you can debug a whole system including the boot phase via USB cable. In this post, I'll first summarize the related technology of Intel DCI. After that, I'll show you how I setup the environment for Intel DCI Debugging on UP Squared board.

Intel DCI and its surroundings

Intel Trace Hub

(image from Using the Intel Trace Hub for at-speed printf by Alan Sguigna)

Intel Trace Hub is a mechanism that collects hardware/software events for the entire system, formats them with a time stamp, and records them in the trace destination. It acts like a PCI device and consisted of below 4 components.

Trace Source: sources of log such as internal hw signals, SoC performance data, software/firmware trace, and debug data from the Software Trace Hub
Trace Destination: It can be MTB, system memory, or DCI
Global Trace Hub: routes the data from the trace sources to the trace destinations according to the user’s configuration
Trigger Unit: controls the starting and stopping of tracing operations

In other words, DCI is possible based on log information of the entire system provided by Intel Trace Hub.

JTAG

JTAG is a mechanism to communicate with IC by serial communication. The interface specifications are defined by IEEE 11149.1, but in reality, semiconductor manufacturers extend them using private instructions and option registers. Functions such as CPU debugging and FPGA/CPLD sequences are realized using private instructions and option registers, so in many cases, only the semiconductor manufacturer and a third party that sined NDA can know.

Intel DCI

Intel DCI is a function that allows you to debug the whole system including SMM and reset vector with just USB. More specifically, this allows you to JTAG debug a Intel CPU, with a trace data sent by Intel Trace Hub via USB.

You can connect target device and the analysis PC with a USB debug cable, and run Intel System Debugger on the analysis PC to debug.

(image from OSFC 2019 - Debugging Intel Firmware using DCI & USB 3.0 by OSFC)
As you can see, there are two types of connections.

out-of-band (DCI OOB): This method uses USB but don't use USB protocol or USB controller, so we need external adapter
in-band (USB Debug Class): This method uses USB protocol. Supported in 7th gen and later

Intel SVT CCA (Silicon View Technology Closed Chassis Adaptor)

(image from Source Level Debugging with Intel(R) SVT CCA by Slim Bootloader)

DCI OOB requires this adapter. This allows access to JTAG or Run-Control via USB3 port on silicon or platform which DCI is enabled.

ISS (Intel System Studio)

(image from Introduction of System Debug and Trace in Intel® System Studio 2018 by Intel)

You have to install Intel System Debug in your analysis PC (host PC) to debug using Intel DCI, and System Debug is part of the tools in ISS. ISS debug tools includes the followings.

System Debug: For source-level debugging of EFI
System Trace: Realtime capture of logs of BIOS and CSME
Intel Debug Extension for Windbg

Methods of connecting target and host

(image from Introduction of System Debug and Trace in Intel® System Studio 2018 by Intel)

ISS provides below 3 methods to connect target and host.

ITP-XDP3: Oldest methods. Directly connect to the JTAG socket. Costs about 3000 USD.
CCA (Closed Chassis Adapter
DbC (DCI USB Native Debug Class)

Setup Intel DCI Environment on UP2 board

Environment

Windows PC that has USB 3.0 port (Host PC)
UP Squared ATOM Quad Core 08/64 (UP2 board)
SF100 SPI NOR Flash Programmer (SF100) + ISP Testclip SO8 (TestClip)
UEFITool v2.8 (UEFITool)
Ghidra
Intel System Studio (ISS)
USB3.0 Debug Cable (Debug Cable)

DCI Support on UP2 board

In order to use Intel DCI, your BIOS needs to support DCI. Looking at the BIOS history of UP2 board, we can see that the DCI Debug Interface is supported since UPA1AM31. However, it is disabled as a default for formal release version since UPA1AM36. My board had UPA1AM52 flashed (I found out by looking at BIOS SETUP screen), so we have to enable DCI in BIOS configuration first.

Usually, there is a configuration called HDCIEN in the BIOS SETUP, and by enabling this, it should set the bit inside IA32_DEBUG_INTERFACE MSR and enable DCI. However, on this BIOS, enabling HDCIEN which was under [CRB Setup] > [CRB Chipset] > [South Cluster Configuration] > [Miscellaneous Configuration] > [DCI enabled (HDCIEN)] doesn't seem like to enable specific bit in the IA32_DEBUG_INTERFACE.

Intel has open source BIOS image here, which is supposed to enable DCI on UP2 Atom board. However, it seems to not boot when I flash the BIOS with this image. Also, it seems like a common problem as the same problem is discussed in up2 forum.

So, I asked Tanda-san (the questioner of the above forum) how he managed to solve this problem, and he gave me a hacky solution. That is, to patch MSR initialization code to set the bit of IA32_DEBUG_INTERFACE on UP2 BIOS.

Enabling DCI on UP2 board

I used SF100 to extract/write BIOS and the method is explained in my previous post, so I will skip the details of this.

After you extracted UPA1AM52 BIOS image from UP2 board and saved as a .bin file, you can look at what kind of modules are included in that image by using UEFITool. If you look for the byte sequence b9 80 0c 00 00 (mov ecx, 0xc80 while 0xc80 is the number of MSR IA32_DEBUG_INTERFACE), you'll probably find 2 hits like below.

If you double click the result, youl'll find that they are both in the same PEI module.

UEFITool v2.8 can replace module in the image, but it has a disadvantage that it's hard to understand what module it is. By using different version of UEFITool, you can see that the PEI module is called SiInit PEI module.

Let's extract SiInit PEI module by right clicking TE image section and selecting Extract body.

Then, we open this module in ghidra. Ghidra recognizes this module as Raw binary but just go on with it, select x86 64bit Visual Studio and analyze. After that, again, search for the byte pattern b9 80 0c 00 00.

Disassembling around the first search result, you should get something like this.

We have bits that enables DCI on the first bit of IA32_DEBUG_INTERFACE, so lets modify 0x40000000 to 0x40000001 (you can patch instruction on ghidra by Ctrl-Shift-G).

Also, the second result looks like this.

Samely, modify 0x40000000 to 0x40000001.
After that, File > Export Program, set Binary as a format and save this patched PEI module to somewhere.

Now let's go back to the UEFITool and locate that SiInit module again. Right click on the TE image section and select Replace Body, then select the patched module.

Once succeeded, you'll see some Rebuild displayed on the other module but that's normal behavior, so just Ctrl-S to save this.

Now, you made the patched UPA1AM52 BIOS image that has IA32_DEBUG_INTERFACE[0] set. Flash the BIOS with this image and you are ready to go.

Intel System Debugger Setup

ISS Installation

You can download ISO installer from this download link. If you look inside iso file, you'll see some files like this.

Double click install.exe, click Next a bunch of time and install ISS.

Usage of ISS are documented in C:/IntelSWTools/system_studio_2020/documentation_2020/ (though it depends where you installed IntelSWTools). Some path of documents that I found useful are the followings.

Target Indicator: documentation_2020/en/debugger/system_studio_2020/system_debugger/target_indicator/TargetIndicator.pdf
How to connect System Debugger: documentation_2020/en/debugger/system_studio_2020/system_debugger/system_debug/Getting_Started.pdf
How to use System Debug: documentation_2020/en/debugger/system_studio_2020/system_debugger/system_debug/User_Guide.pdf

Connecting Intel System Debugger

First, make sure your UP2 board is powered on. Then, on the host PC, run Intel System Debugger Target Indicator 2020. When you run Target Indicator, it seems nothings happened but it's actually executed in the background.

If you right click the red square icon and select Intel(R) System Debugger Target Indicator, you can check the current status of the connection.

Then, connect the UP2 board and host PC with USB3.0 debug cable (I always connect target first and then to host). UP2 board have 3 USB3.0 port and not all the port works for this. In my UP2 board, it only recognizes when I plugged it to the port below.

I had trouble recognizing it first, but after I pull out debug cable from the host, reboot the target with the debug cable still plugged in and then, connect to the host again, it worked. Other methods of solving unrecognizing issue were stated here but I haven't tried that out.

If connection works, Target Indicator should appear like follows.

Then, run Intel System Studio.

After closing the "Getting Started", we'll define connection like follows.

If the connection is established, you will see something like this.

If it didn't detect the target properly, you can "Manually Select Target" or try with different USB3.0 port on the target.

If you press Finish, you'll see the screen as follows.

Next, you have to setup Debug Configuration. Open the Debug Configuration as follows.

Select Intel System Debugger and click Apply without changing any configuration.

You will see a popup like this, so click Switch.

Eventually, you'll get this kind of screen.

Try suspending PC from System Debugger

Now if you click Suspend like below, and target freezes, then it's a success! Assembly will be displayed after you suspended.

If you want to debug boot phase, you can just reboot target.

Second time connecting Intel System Debugger

For the second time debugging, you can follow these.

Power on UP2 board
Run Target Indicator on host
Connect debug cable
Open ISS and use previous workspace
Click Verify Connected Target to see if successfully connected
Click "Connect Button" to connect (tiny green icon)
Click icon with a "bug" to run with the previous Debug Configuration

Acknowledgement

Again, great thanks to Satoshi Tanda for the support.

Read&Write BIOS Image using Dediprog SF100 SPI NOR Flash Programmer

MachineHunter — Tue, 24 May 2022 14:33:55 +0000

SPI flash stores most of the module executed by UEFI BIOS. If you want to extract actual UEFI module to take a look at, or modify some of the content, SPI flash programmer is a perfect solution. Moreover, some BIOS images are distributed as .bin file, and you can use SPI flash programmer to update BIOS with those image.

Environment

I will be using followings in this article.

Windows PC that has USB 3.0 port (Host PC)
UP Squared ATOM Quad Core 08/64 (UP2 board)
SF100 SPI NOR Flash Programmer (SF100)
ISP Testclip SO8 (TestClip)

Finding SPI Flash Chip and detecting Device ID

For UP2 board, you first have to take off heatsink like this.

Most SPI flash chip is manufactured by winbond, so it is one way to find a chip that has a letter "winbond" written. In my UP2 board, it was located here. It first had a seal on so I had to take off the seal to find this.

It's too small to look from above picture, but it says winbond 25Q128JWSQ 2117 which we can tell that the device ID for this chip is W25Q128JW.

Setup for using SF100

Download the following three items from here.

Latest version of software for using SF100
- I downloaded version 7.3.90.46
USB driver
USB Driver User Guide for Win 8/8.1/10

You will be asked to enter your email and serial number when downloading. The serial number is written on the back of the SF100.

Once downloaded, run .msi installer to install the software. If the following 4 app shortcuts are generated on the desktop (note that I have moved contents to a folder), then the installation is complete.

After that, you have to setup the USB driver.
Let's connect SF100 and TestClip like this.

You can referer to the "USB Driver User Guide" from now on, but here's what I did. First, connect the above to the Host PC (which you will be using for manipulating SF100) and check the device manager. It should be like this.

Right click the above "SF100-ISP" and select "Update Driver Software...". Then follow the steps below.

Browse my computer for driver software
Let me pick from a list of device drivers on my computer
Click Next without selecting any
Click Have Disk
Browse and locate the USB driver we downloaded before dediprog.inf and click OK
Select "DediProg SF Programmer driver" and click Next
Installation will start and if nothing goes wrong, "Window has successfully updated your driver software" will be shown.
Again if you open device manager and see this, then it's a success

Recognize SPI flash from Host PC

Now let's clip the SPI flash with the TestClip. Looking closely, you will see a dot on flash chip, and small white paintings on the TestClip. Make sure you clip it the right way, so that the white paint and the dot on the chip are in the same position.

After that, connect USB cable to the host PC and run the software "DediProg Engineering" which is one of the 4 shortcuts created after installation.

If it recognized correctly, the software asks you to select SPI flash Chip ID. You have found out that the device ID was W25Q128JW so select that. If there's no error, then the recognition is success.

Reading SPI flash

( The usage of SF100 software is written in "DediProg Help" which is one of the four desktop shortcuts created at installation )

To read the SPI flash content, click the Edit icon and then, press Read.... While reading, busy lamp glows orange on SF100, and the percentage of progress will be displayed on the place where Read... button was located.

After reading is complete, you can press Chip Buffer to File to save image as a .bin file.

After saving file, you might get an error message like an unnamed file contains ..., but you can ignore that. If you are not sure you've read the flash contents successfully, check if the contents start with the flash descriptor's magic byte 5A A5 F0 0F.

Writing SPI flash

Click Config icon and select/check the following two items.

Download a whole file to chip (Without Blank Check)…
Reload file each time Then, press OK. There will be about two warning messages showing up, but you can ignore those. Next, click File icon and do the followings.
click Find and select the BIOS image file you want to write in
select Raw Binary and make sure you don't check Trucate file to...

After pressing OK, check if you have Operation completed. Finally, press the Batch icon and start flashing.

You can check if flashing is over by seeing if busy lamp becomes pass. You will see this kind of log output if it succeeded.

If you want to restore it, you can use the flash content file read in the previous section.

Acknowledgement

Great thanks to Satoshi Tanda for the support and for introducing this wonderful topic.

TPM2_NV_DefineSpace from UEFI

MachineHunter — Tue, 24 May 2022 00:24:49 +0000

We can say that the most complicated part of TPM2.0 is authentication/session. My previous post's TPM2_GetRandom and TPM2_GetCapability didn't require session (as we specified TPM_ST_NO_SESSIONS in the Header tag) so it was relatively easy to implement. However, commands which requires session are much more difficult than those. In this article, we will define 128bit (16byte) of space in NVRAM of TPM by using TPM2_NV_DefineSpace.

Parameters of TPM2_NV_DefineSpace

Sessions

If command requires session, we have to specify TPM_ST_SESSIONS in the tag of Command Header. Session in TPM is quite a complex concept. For details, I want you to look at TCG spec Part1 19.5 or other materials. In this case, session is used for authorization of the use of authHandle because it has @ mark.

Now, one of the trickiest pitfall here is that, where to write the actual content of the session. It is not explicitly written in the above table, but looking at TCG spec Part1 18.9 and 18.10, it says that we have to insert some authorization-related structure like below.

These structures are defined as TPMS_AUTH_COMMAND and TPMS_AUTH_RESPONSE.

When sending command, we have to put TPMS_AUTH_COMMAND (the actual content of the session) above the thick line which is between handle and command-specific parameters. For the response, there will be only parameterSize above the thick line and other information (TPMS_AUTH_RESPONSE) is appended at last. These authorization-related structures will exists for any command which requires sessions.

Implementation

The whole code will be as follows.

#include <Uefi.h>
#include <Library/UefiLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Protocol/Tcg2Protocol.h>
#include <IndustryStandard/Tpm20.h>

#pragma pack(1)
    typedef struct {
        TPMI_SH_AUTH_SESSION sessionHandle;
        UINT16 nonceSizeZero;
        TPMA_SESSION sessionAttributes;
        UINT16 hmacSizeZero;
    } ORIG_AUTH_AREA;

    typedef struct {
        UINT16 size;
        TPMI_RH_NV_INDEX nvIndex;
        TPMI_ALG_HASH nameAlg;
        /*TPMA_NV attributes;*/
        UINT32 attributes;
        UINT16 authPolicySizeZero;
        UINT16 dataSize;
    } ORIG_NV_PUBLIC;

    typedef struct {
        TPM2_COMMAND_HEADER Header;
        TPMI_RH_PROVISION authHandle;
        UINT32 authSize;
        ORIG_AUTH_AREA authArea;
        /*TPM2B_AUTH auth;*/
        UINT16 authSizeZero;
        /*TPM2B_NV_PUBLIC publicInfo;*/
        ORIG_NV_PUBLIC publicInfo;
    } TPM2_NV_DEFINE_SPACE_COMMAND;

    typedef struct {
        TPM2_RESPONSE_HEADER Header;
    } TPM2_NV_DEFINE_SPACE_RESPONSE;
#pragma pack()


EFI_STATUS EFIAPI UefiMain(IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable) {
    EFI_TCG2_PROTOCOL *Tcg2Protocol;
    SystemTable->BootServices->LocateProtocol(&gEfiTcg2ProtocolGuid, NULL, (VOID**)&Tcg2Protocol);


    // Auth Area
    UINT32 authSize;
    ORIG_AUTH_AREA authArea;
    authArea.sessionHandle = SwapBytes32(TPM_RS_PW);
    authArea.nonceSizeZero = SwapBytes16(0);
    authArea.sessionAttributes.continueSession = 0;
    authArea.sessionAttributes.auditExclusive  = 0;
    authArea.sessionAttributes.auditReset      = 0;
    authArea.sessionAttributes.reserved3_4     = 0;
    authArea.sessionAttributes.decrypt         = 0;
    authArea.sessionAttributes.encrypt         = 0;
    authArea.sessionAttributes.audit           = 0;
    authArea.hmacSizeZero = SwapBytes16(0);
    authSize = sizeof(authArea);


    // publicInfo area
    ORIG_NV_PUBLIC publicInfo;
    publicInfo.nvIndex = SwapBytes32(NV_INDEX_FIRST);
    publicInfo.nameAlg = SwapBytes16(TPM_ALG_SHA1);
    /*
     *TPMA_NV attributes;
     *attributes.TPMA_NV_PPWRITE        = 1;
     *attributes.TPMA_NV_OWNERWRITE     = 1;
   *attributes.TPMA_NV_AUTHWRITE      = 1;
   *attributes.TPMA_NV_POLICYWRITE    = 1;
   *attributes.TPMA_NV_COUNTER        = 0;
   *attributes.TPMA_NV_BITS           = 0;
   *attributes.TPMA_NV_EXTEND         = 0;
   *attributes.reserved7_9            = 000;
   *attributes.TPMA_NV_POLICY_DELETE  = 0;
   *attributes.TPMA_NV_WRITELOCKED    = 0;
   *attributes.TPMA_NV_WRITEALL       = 1;
   *attributes.TPMA_NV_WRITEDEFINE    = 0;
   *attributes.TPMA_NV_WRITE_STCLEAR  = 1;
   *attributes.TPMA_NV_GLOBALLOCK     = 0;
   *attributes.TPMA_NV_PPREAD         = 1;
   *attributes.TPMA_NV_OWNERREAD      = 1;
   *attributes.TPMA_NV_AUTHREAD       = 1;
   *attributes.TPMA_NV_POLICYREAD     = 1;
   *attributes.reserved20_24          = 00000;
   *attributes.TPMA_NV_NO_DA          = 1;
   *attributes.TPMA_NV_ORDERLY        = 0;
   *attributes.TPMA_NV_CLEAR_STCLEAR  = 0;
   *attributes.TPMA_NV_READLOCKED     = 0;
   *attributes.TPMA_NV_WRITTEN        = 0;
   *attributes.TPMA_NV_PLATFORMCREATE = 0;
   *attributes.TPMA_NV_READ_STCLEAR   = 0;
   * => 00000010000011110101000000001111
     * => 0x20f500f
     */
    publicInfo.attributes = SwapBytes32(0x20f500f);
    publicInfo.authPolicySizeZero = SwapBytes16(0);
    publicInfo.dataSize = SwapBytes16(16);
    publicInfo.size = SwapBytes16(sizeof(publicInfo) - sizeof(publicInfo.size));


    TPM2_NV_DEFINE_SPACE_COMMAND CmdBuffer;
    UINT32 CmdBufferSize;
    TPM2_NV_DEFINE_SPACE_RESPONSE RecvBuffer;
    UINT32 RecvBufferSize;

    // set parameters
    CmdBuffer.Header.tag         = SwapBytes16(TPM_ST_SESSIONS);
    CmdBuffer.Header.commandCode = SwapBytes32(TPM_CC_NV_DefineSpace);
    CmdBuffer.authHandle         = SwapBytes32(TPM_RH_OWNER);
    CmdBuffer.authSize           = SwapBytes32(authSize);
    CmdBuffer.authArea           = authArea;
    CmdBuffer.authSizeZero       = SwapBytes16(0);
    CmdBuffer.publicInfo         = publicInfo;
    CmdBufferSize = sizeof(CmdBuffer.Header) + sizeof(CmdBuffer.authHandle) + sizeof(CmdBuffer.authSize) + sizeof(CmdBuffer.authArea) + sizeof(CmdBuffer.authSizeZero) + sizeof(CmdBuffer.publicInfo);
    CmdBuffer.Header.paramSize = SwapBytes32(CmdBufferSize);


    // send TPM command
    Print(L"sending TPM command...\r\n");
    RecvBufferSize = sizeof(RecvBuffer);
    EFI_STATUS stats = Tcg2Protocol->SubmitCommand(Tcg2Protocol, CmdBufferSize, (UINT8*)&CmdBuffer, RecvBufferSize, (UINT8*)&RecvBuffer);
    if(stats==EFI_SUCCESS)
        Print(L"SubmitCommand Success!\r\n");
    else
        Print(L"stats: 0x%x (EFI_DEVICE_ERROR:0x%x, EFI_INVALID_PARAMETER:0x%x, EFI_BUFFER_TOO_SMALL:0x%x)\r\n", stats, EFI_DEVICE_ERROR, EFI_INVALID_PARAMETER, EFI_BUFFER_TOO_SMALL);


    UINT32 res = SwapBytes32(RecvBuffer.Header.responseCode);
    Print(L"responseCode is %d\r\n", res);


    while(1);
    return 0;
}

TPMS_AUTH_COMMAND

This is the session content mentioned above. There are 3 ways of authentication in TPM.

Password
HMAC
Policy

In this example, I'm using password (TPM_RS_PW) which is the easiest authentication method.

When using tpm2-tool and you didn't specify any of these authentication, it defaults to use password authentication with blank password.

You may notice I'm not using TPMS_AUTH_COMMAND even though it's defined in Tpm20.h. Most of the attributes are same as TPMS_AUTH_COMMAND, but nounceSizeZero and hmacSizeZero are redefined. This is actually one of the pitfalls: TPM's canonicalization. For example, nonce has a type of TPM2B_NONCE which is same as TPM2B_DIGEST, and if you lookup this definition in Tpm20.h, it's defined like this.

typedef struct {
  UINT16    size;
  BYTE      buffer[sizeof (TPMT_HA)];
} TPM2B_DATA;

Normally, if you set size=0 and buffer=NULL, total size of data actually sent will be sizeof(UINT16)+sizeof(TPMT_HA). However, in TPM, size of data sent will only be sizeof(UINT16). If size=2 and buffer="A\0" then the data size sent will be sizeof(UINT16)+2.

Therefore, if you have structures with TPM2B_ prefix, you have to redefine that structure and adjust the size of buffer field to the actual data size you're trying to put. This is called canonicalization.

auth parameter

If you read authorization-related section of TCG spec or Practical Guide to TPM2.0, you will see a lots of word authValue. This is roughly an input for authorization, so in password authentication, this value is the actual password. Also, authValue is specified by different parameter in different commands. In TPM2_NV_DefineSpace, the parameter for authValue is auth parameter.

I wanted to use blank password for this authentication so that is why I redefined TPM2B_AUTH auth to UINT16 authSizeZero.

publicInfo Area

This parameter is the configuration of NVRAM space we're trying to define. To expand TPM2B_NV_PUBLIC structure, it will be like follows.

* TPM2B_NV_PUBLIC
  * UINT16 size
  * TPMS_NV_PUBLIC nvPublic
    * [UINT32] [TPM_HANDLE] TPMI_RH_NV_INDEX nvIndex
    * [UINT16] [TPM_ALG_ID] TPMI_ALG_HASH nameAlg
    * [UINT32 bitfield] TPMA_NV attributes
    * TPM2B_DIGEST authPolicy
      * UINT16 size
      * BYTE buffer[]
    * UINT16 dataSize

NV Index and Name

NV Index is something like a handle for the specific NVRAM space. There are constants NV_INDEX_FIRST and NV_INDEX_LAST so you can specify any value in this range for nvIndex. TPM uses "Name" as an unique identifier for TPM entities. We must specify by what algorithm we generate Name so there is nameAlg parameter.

TPMA_NV

We have to take roundabout method to send TPMA_ structure. Since TPM require us to send data in big endian, we have to SwapBytes TPMA_, but SwapBytes32 doesn't allow UINT32 bitfield. You can use union to cast it into UINT32 or just do it manually like above code.

TPMA_NV determines the core configuration of the NV Index we're trying to create. For detailed meanings of each bit, you can look at TCG spec Part2, and here, I will just explain the points.

There are mainly 4 types of NV Index: Ordinary, Bit Field, Extend, Hybrid NV Indexes.
I'm specifying NV Ordinary Index which is a type we can put unstructured data with any size
We can specify separate authorization for the read and write to this NV Index
NV Index can be locked to prevent read or write

Running the code

You will get this kind of output if it succeeded. My response code is 332 which means the NV Index I specified is already in use and actually it is, but if it isn't, you should get response code 0. Also, after defining this, you can run this program again and see if you get 332.

Summary

This article was mainly about how to implement TPM commands which requires authorization and session.

If command requires session, we have to specify TPM_ST_SESSIONS in the tag of Command Header
session is required to authorize the use of parameter which has @ mark
TPMS_AUTH_COMMAND and TPMS_AUTH_RESPONSE should be placed as written in TCG spec Part1 18.9 and 18.10
TPMS_AUTH_COMMAND and TPMS_AUTH_RESPONSE is required for every command that requires session
There are 3 ways of authentication in TPM: Password, HMAC, and Policy
Canonicalization: TPM sends only sizeof(UINT16) if you specify 0 for size, even though you had buffer[MAX_...] in the structure
We have to redefine structure if we have struct with TPM2B_ prefix due to canonicalization
authValue is roughly an input required for authorization
NV Index is something like a handle for the specific NVRAM space
TPM uses "Name" as an unique identifier for TPM entities
How to swap bytes of TPMA_ object and broad explanation of TPMA_NV

TPM2_GetCapability from UEFI

MachineHunter — Sun, 22 May 2022 19:58:03 +0000

In my previous post, I introduced how to submit very easy command TPM2_GetRandom to TPM from UEFI. TPM2_GetCapability is also an easy command, but we need to specify more parameters and those meanings are bit more complex than TPM2_GetRandom. TPM2_GetCapability is a command frequently used to check the current status of your TPM, so it is helpful to have one program already implemented.

parameters of TPM2_GetCapability

Put simply, we specify what kind of information we want in capability. and request the result in the range of [property:property+propertyCount].

The types of capability we can specify is listed in the command desription.

In this post, we will use TPM2_GetCapability to list out supported commands by specifying TPM_CAP_COMMANDS as a capability parameter.

Implementation

The whole code looks like this.

#include <Uefi.h>
#include <Library/UefiLib.h>
#include <Protocol/Tcg2Protocol.h>
#include <IndustryStandard/Tpm20.h>

#pragma pack(1)
    typedef struct {
        TPM2_COMMAND_HEADER Header;
        TPM_CAP capability;
        UINT32 property;
        UINT32 propertyCount;
    } TPM2_GET_CAPABILITY_COMMAND;

    typedef struct {
        TPM2_RESPONSE_HEADER Header;
        TPMI_YES_NO moreData;
        TPMS_CAPABILITY_DATA capabilityData;
    } TPM2_GET_CAPABILITY_RESPONSE;
#pragma pack()

EFI_STATUS EFIAPI UefiMain(IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable) {
    EFI_TCG2_PROTOCOL *Tcg2Protocol;
    SystemTable->BootServices->LocateProtocol(&gEfiTcg2ProtocolGuid, NULL, (VOID**)&Tcg2Protocol);


    TPM2_GET_CAPABILITY_COMMAND CmdBuffer;
    UINT32 CmdBufferSize;
    TPM2_GET_CAPABILITY_RESPONSE RecvBuffer;
    UINT32 RecvBufferSize;

    // set command parameters
    CmdBuffer.Header.tag         = SwapBytes16(TPM_ST_NO_SESSIONS);
    CmdBuffer.Header.commandCode = SwapBytes32(TPM_CC_GetCapability);
    CmdBuffer.capability         = SwapBytes32(TPM_CAP_COMMANDS);
    CmdBuffer.property           = SwapBytes32(TPM_CAP_FIRST);
    CmdBuffer.propertyCount      = SwapBytes32(MAX_CAP_CC);
    CmdBufferSize = sizeof(CmdBuffer.Header) + sizeof(CmdBuffer.capability) + sizeof(CmdBuffer.property) + sizeof(CmdBuffer.propertyCount);
    CmdBuffer.Header.paramSize = SwapBytes32(CmdBufferSize);


    // send TPM command
    RecvBufferSize = sizeof(RecvBuffer);
    EFI_STATUS stats = Tcg2Protocol->SubmitCommand(Tcg2Protocol, CmdBufferSize, (UINT8*)&CmdBuffer, RecvBufferSize, (UINT8*)&RecvBuffer);
    if(stats==EFI_SUCCESS)
        Print(L"SubmitCommand Success!\r\n");
    else
        Print(L"stats: 0x%x (EFI_DEVICE_ERROR:0x%x, EFI_INVALID_PARAMETER:0x%x, EFI_BUFFER_TOO_SMALL:0x%x)\r\n", stats, EFI_DEVICE_ERROR, EFI_INVALID_PARAMETER, EFI_BUFFER_TOO_SMALL);


    // parse response
    UINT16 res = SwapBytes32(RecvBuffer.Header.responseCode);
    Print(L"ResponseCode is %d\r\n", res);
    Print(L"moreData: %d\r\n", RecvBuffer.moreData);

    UINT32 i;
    UINT32 count = SwapBytes32(RecvBuffer.capabilityData.data.command.count);
    Print(L"--- %d commands supported ---\r\n", count);

    TPMA_CC* tpmacc = (TPMA_CC*)RecvBuffer.capabilityData.data.command.commandAttributes;
    for(i=0; i<count; i++) {
        union {
            UINT32 tpma_cc_uint32;
            TPMA_CC buf;
        } castbuf;
        castbuf.buf = tpmacc[i];
        UINT32 tpmacc32 = SwapBytes32(castbuf.tpma_cc_uint32);

        if((UINT16)tpmacc32 == TPM_CC_NV_DefineSpace) {
            Print(L"TPM2_NV_DefineSpace is supported: %X\r\n", tpmacc32);
        }
    }

    while(1);
    return 0;
}

command parameter description

Again, we have to send data in BigEndian to TPM so there are lots of SwapBytes. Macros like TPM_CAP_COMMANDS and TPM_CAP_FIRST are searched in the Tpm20.h which is located in MdePkg/Include/IndustryStandard/Tpm20.h. Notice we're requesting MAX_CAP_CC as propertyCount parameter, which we can guess moreData parameter in the response will be 0.

response description

Parsing response is the main part of this article.
We can find out typedef BYTE TPMI_YES_NO; in Tpm20.h and since it says "YES_NO", we can easily tell moreData takes 1 or 0 as a value. However, capabilityData parameter which has a type TPMS_CAPABILITY_DATA is more complex. By looking it up on Tpm20.h, we can find out TPMS_CAPABILITY_DATA structure is as follows.

* [struct] TPMS_CAPABILITY_DATA
  * [UINT32] TPM_CAP capability
  * [union] TPMU_CAPABILITIES
    * [struct] TPML_ALG_PROPERTY algorithms;
      * [UINT32] UINT32 count
      * [struct] TPMS_ALG_PROPERTY algProperties[MAX_CAP_ALGS];
        * [UINT16] TPM_ALG_ID alg
        * [UINT32(bitfield)] TPMA_ALGORITHM algProperties
    * ...

Name Prefix Convention

Looking at TPM macros above, we notice there are some convention in the prefix of its name. Name Prefix Convention is defined in TCG spec Part2 4.16. Here are the part of it.

The prefix you must be aware of is TPM2B_ prefix. Structures with this prefix vary in size depending on the data they hold. There aren't any in TPMS_CAPABILITY_DATA, but if this structure is included, you can't just define response structure and access via that structure just like what I'm doing in the above code. This will be described afterwards when this actually appears. For now, it is enough to know that, you can know what type of data it is from the prefix.

bitfield to UINT32

This is not TPM specific thing, but we often see bitfield (the one with TPMA_ prefix) in TPM structure. Since TPM treats data in big endians, we have to swap it, but SwapBytes32 is for UINT32 and not for UINT32 bitfields. Therefore, we need to first convert it to UINT32. In order to convert bitfield to UINT32, you can define union as follows.

union {
  UINT32 tpma_cc_uint32;
  TPMA_CC buf;
} castbuf;
castbuf.buf = /*TPMA_CC object*/;
Print(L"%d", SwapBytes32(castbuf.tpma_cc_uint32));

Running the code

You will get this kind of output if it succeeded. If you get errors, you can check my previous posts on how to evaluate them.

0x240012A is 00 0 0 001 0 0 1 000000 0000000100101010 so TPMA_CC values for TPM2_NV_DefineSpace are as follows.

commandIndex: 0x12A
nv: 1
extensive: 0
flushed: 0
cHandles: 1
rHandle: 0
V: 0
Res: 0

Summary

TPM2_GetCapability is a command frequently used to check the current status of TPM
How to set parameters of TPM2_GetCapability
Name Prefix Convention of TPM macros
How to convert bitfields to integer value in order to swap bytes

TPM2_GetRandom from UEFI

MachineHunter — Wed, 18 May 2022 18:39:30 +0000

Using TPM2.0 from UEFI module is a painstaking task.
TPM offers APIs called TSS (TCG Software Stack) for software to easily communicate with TPM. Also there are tools to interact with TPM via command line (i.e. tpm2-tools). However, both runs above kernel so we can't use them from UEFI module.

UEFI access to various devices via "protocol". TPM is also a device, so UEFI provides Tcg2Protocol for communicating TPM. To let TPM do something, we need to send "TPM command" to the TPM. Tcg2Protocol has a function called "SubmitCommand" to do this.

To be more precise, fTPM is not a physical device but you can use Tcg2Protocol to communicate with them just like discrete TPM.

The format of TPM Command is defined in TCG spec. TCG spec is consisted of 4 part so make sure to download all of these (Part 3 & 4 has two specs but using only the one which involves code is fine).

Learning about TPM is also hard, since there are only few resources out there. Most popular resource you can use to understand about TPM is maybe Practical Guide to TPM2.0 which you can download kindle version from amazon for free, but both TCG spec and this book doesn't provides us sample code. Therefore, it often takes you long time to write the first working code.

It took me really long time to be able to write code accessing TPM from UEFI module, so I hope this series of article helps someone who is also having trouble.

Starting with very easy command: TPM2_GetRandom

I strongly recommend implementing easy TPM command first.　Implementation difficulty varies greatly between TPM commands, but even with easy TPM command, there are several pitfalls that you must be aware of.

I will be using EDK2 to build UEFI module. Also, make sure the machine you're running this module has TPM2.0 (either fTPM or discrete TPM) and the bios supports TCG2 protocol.

EDK2 settings to use Tcg2Protocol

Just add this in .inf file.

[Protocols]
  gEfiTcg2ProtocolGuid

Then, you can start using Tcg2Protocol like this (I will put the whole source code at the end).

#include <Uefi.h>
#include <Library/UefiLib.h>
#include <Protocol/Tcg2Protocol.h>
#include <IndustryStandard/Tpm20.h>

EFI_STATUS EFIAPI UefiMain(IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable) {
    EFI_TCG2_PROTOCOL *Tcg2Protocol;
    SystemTable->BootServices->LocateProtocol(&gEfiTcg2ProtocolGuid, NULL, (VOID**)&Tcg2Protocol);

    EFI_STATUS stats = Tcg2Protocol->SubmitCommand(Tcg2Protocol, CmdBufferSize, (UINT8*)&CmdBuffer, RecvBufferSize, (UINT8*)&RecvBuffer);

    while(1);
    return 0;
}

Looking for TPM2_GetRandom format in TCG spec

You can check the format in Part3 spec. Just Ctrl-F with command name, in this case, TPM2_GetRandom. You will see table like this.

Writing the code

I recommend you to start with defining the structure just like the table above.

#pragma pack(1)                                     
  typedef struct {
    TPM2_COMMAND_HEADER Header;
    UINT16 bytesRequested;
  } TPM2_GET_RANDOM_COMMAND;

  typedef struct {
    TPM2_RESPONSE_HEADER Header;
    TPM2B_DIGEST randomBytes;
  } TPM2_GET_RANDOM_RESPONSE;                       
#pragma pack()

Parameters in the header are common to all TPM command so specific struct is defined in Tpm20.h. Tpm20.h is located in MdePkg/Include/IndustryStandard/Tpm20.h and I recommend looking this while writing.
Also, using #pragma pack(1) to disable alignment is one of the pitfalls so don't forget this.

Next, assign the Command parameters as follows.

TPM2_GET_RANDOM_COMMAND CmdBuffer;
UINT32 CmdBufferSize;
TPM2_GET_RANDOM_RESPONSE RecvBuffer;
UINT32 RecvBufferSize;

CmdBuffer.Header.tag         = SwapBytes16(TPM_ST_NO_SESSIONS);
CmdBuffer.Header.commandCode = SwapBytes32(TPM_CC_GetRandom);
CmdBuffer.bytesRequested     = SwapBytes16(16);
CmdBufferSize = sizeof(CmdBuffer.Header) + sizeof(CmdBuffer.bytesRequested);
CmdBuffer.Header.paramSize = SwapBytes32(CmdBufferSize);

"Session" is some authorization related thing, but we don't need this in this command. We request 16 bytes of random value in this command.
You can see SwapBytes in the code and this is another one of the pitfalls. We have to send data to TPM in BIG ENDIAN.

SwapBytes is a EDK2 specific function and we need to specify bits at the end. In the spec's table it says, TPC_CC_GetRandom has a type of TPM_CC and I found out this is 32bit by searching TPM_CC in Tpm20.h. It should be defined like this.

// Table 11 - TPM_CC Constants (Numeric Order)
typedef UINT32 TPM_CC;

Finally, send command and parse response like this.

// send
RecvBufferSize = sizeof(RecvBuffer);
EFI_STATUS stats = Tcg2Protocol->SubmitCommand(Tcg2Protocol, CmdBufferSize, (UINT8*)&CmdBuffer, RecvBufferSize, (UINT8*)&RecvBuffer);
if(stats==EFI_SUCCESS)
  Print(L"SubmitCommand Success!\r\n");
else
  Print(L"stats: 0x%x (EFI_DEVICE_ERROR:0x%x, EFI_INVALID_PARAMETER:0x%x, EFI_BUFFER_TOO_SMALL:0x%x)\r\n", stats, EFI_DEVICE_ERROR, EFI_INVALID_PARAMETER, EFI_BUFFER_TOO_SMALL);


// show result
UINT16 res = SwapBytes32(RecvBuffer.Header.responseCode);
Print(L"ResponseCode is %d\r\n", res);

UINT16 i;
UINT16 size = SwapBytes16(RecvBuffer.randomBytes.size);
Print(L"generated value: ");
for(i=0; i<size; i++)
  Print(L"%X", RecvBuffer.randomBytes.buffer[size-i-1]);
Print(L"\r\n");

If you don't get EFI_SUCCESS, then you might not have TPM2.0 or something is wrong with the TPM (I also had a problem that TPM2_CreatePrimary returns EFI_DEVICE_ERROR on fTPM). Other than that, all the error information is in the response code.

Running the code

If you get screen like this, then it's a success! (response code should be 0 if any command succeeded).

Evaluating errors

Mostly, you'll get errors and response code will not be 0. It's hard to identify what is wrong since the only information given is this response code, but you can follow these steps.

Decode response code by tpm2_rc_decode to know the abstract information of error
Read each command's "Detailed Actions" section in TCG spec Part3 to know exactly where in the process you're stuck at
Read the index of subsections in the TCG spec Part3 Chapter5 Command Processing to know what process you have passed and what you haven't

Decode response code by tpm2_rc_decode to know the abstract information of error

Firstly, you have to parse this response code. The most easy way is to use tpm2-tools's tpm2_rc_decode command. You can install tpm2-tools by apt install tpm2-tools. For example, if the response code was 725 in decimal, you can use this command like this.

$ tpm2_rc_decode 725
tpm:parameter(2):structure is the wrong size

We can know that the second parameter's size is wrong from this message.

Read each command's "Detailed Actions" section in TCG spec Part3 to know exactly where in the process you're stuck at

If this information is not enough, you can see each command's "Detailed Actions". Taking TPM2_NV_DefineSpace as an example, if you got an error tpm:handle(1):inconsistent attributes, you can look at the "Detailed Actions" and find out what condition you didn't pass.

Read the index of subsections in the TCG spec Part3 Chapter5 Command Processing to know what process you have passed and what you haven't

You might also wonder, what part did you passed and what you didn't. Command Processing order can be found out by looking at index of Chapter5 of TCG spec Part3.

So, if you had parameter related error, it means you have passed all of the above part such as header validation or authorization checks.

Summary

That's it for this post. Below is the summary.

You can't use tpm2-tools or TSS from UEFI
How to setup EDK2 to use Tcg2Protocol
You can use Tcg2Protocol->SubmitCommand to send command to TPM from UEFI
Looking at TCG spec and Tpm20.h while writing the code is recommended
You have to send data in Big Endian to TPM
You have to disable alignment by #pragma pack(1)
How to evaluate error

Full source code

#include <Uefi.h>
#include <Library/UefiLib.h>
#include <Protocol/Tcg2Protocol.h>
#include <IndustryStandard/Tpm20.h>

#pragma pack(1)
    typedef struct {
        TPM2_COMMAND_HEADER Header;
        UINT16 bytesRequested;
    } TPM2_GET_RANDOM_COMMAND;

    typedef struct {
        TPM2_RESPONSE_HEADER Header;
        TPM2B_DIGEST randomBytes;
    } TPM2_GET_RANDOM_RESPONSE;
#pragma pack()

EFI_STATUS EFIAPI UefiMain(IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable) {
    EFI_TCG2_PROTOCOL *Tcg2Protocol;
    SystemTable->BootServices->LocateProtocol(&gEfiTcg2ProtocolGuid, NULL, (VOID**)&Tcg2Protocol);

    TPM2_GET_RANDOM_COMMAND CmdBuffer;
    UINT32 CmdBufferSize;
    TPM2_GET_RANDOM_RESPONSE RecvBuffer;
    UINT32 RecvBufferSize;

    CmdBuffer.Header.tag         = SwapBytes16(TPM_ST_NO_SESSIONS);
    CmdBuffer.Header.commandCode = SwapBytes32(TPM_CC_GetRandom);
    CmdBuffer.bytesRequested     = SwapBytes16(16);
    CmdBufferSize = sizeof(CmdBuffer.Header) + sizeof(CmdBuffer.bytesRequested);
    CmdBuffer.Header.paramSize = SwapBytes32(CmdBufferSize);


    // send
    RecvBufferSize = sizeof(RecvBuffer);
    EFI_STATUS stats = Tcg2Protocol->SubmitCommand(Tcg2Protocol, CmdBufferSize, (UINT8*)&CmdBuffer, RecvBufferSize, (UINT8*)&RecvBuffer);
    if(stats==EFI_SUCCESS)
        Print(L"SubmitCommand Success!\r\n");
    else
        Print(L"stats: 0x%x (EFI_DEVICE_ERROR:0x%x, EFI_INVALID_PARAMETER:0x%x, EFI_BUFFER_TOO_SMALL:0x%x)\r\n", stats, EFI_DEVICE_ERROR, EFI_INVALID_PARAMETER, EFI_BUFFER_TOO_SMALL);


    // show result
    UINT16 res = SwapBytes32(RecvBuffer.Header.responseCode);
    Print(L"ResponseCode is %d\r\n", res);

    UINT16 i;
    UINT16 size = SwapBytes16(RecvBuffer.randomBytes.size);
    Print(L"generated value: ");
    for(i=0; i<size; i++)
        Print(L"%X", RecvBuffer.randomBytes.buffer[size-i-1]);
    Print(L"\r\n");

    while(1);
    return 0;
}