UEFITool Documentation

File: README.md Copy Chapter

UEFITool

UEFITool is a viewer and editor of firmware images conforming to UEFI Platform Interface (PI) Specifications.

Very Brief Introduction to UEFI Copy Chapter

Unified Extensible Firmware Interface or UEFI is a post-BIOS firmware specification originally written by Intel for Itanium architecture and then adapted for X86 systems.
The first EFI-compatible x86 firmwares were used on Apple Macintosh systems in 2006, PC motherboard vendors started putting UEFI-compatible firmwares on their boards in 2011.
Today there are numerous systems using UEFI-compatible firmware including PCs, Intel-based Macs, Tablets and Smartphones on x86, x86-64, arm64 and RISC-V architectures.
More information on UEFI is available on UEFI Forum official site and in Wikipedia.

Very Brief Introduction to UEFITool Copy Chapter

UEFITool is a cross-platform open source application written in C++/Qt, that parses UEFI-compatible firmware image into a tree structure, verifies its integrity and provides a GUI to manipulate its elements.
Project development started in the middle of 2013 because of the lack of cross-platform open source utilities for tinkering with UEFI images.

In the beginning of 2015 the major refactoring round was started to make the program compatible with newer UEFI features including FFSv3 volumes and fixed image elements.
It's in development right now with the following features still missing:

• Editor part, i.e image reconstruction routines
• Console UI

The missing parts are in development and the version with a new engine will be made as soon as image reconstruction works again.

Derived projects Copy Chapter

There are some other projects that use UEFITool's engine:

• UEFIExtract, which uses ffsParser to parse supplied firmware image into a tree structure and dumps the parsed structure recursively on the FS. Jethro Beekman's tree utility can be used to work with the extracted tree.
• UEFIFind, which uses ffsParser to find image elements containing a specified pattern. It was developed for UBU project.

Alternatives Copy Chapter

Right now there are some alternatives to UEFITool that you could find useful too:

• FMMT by TianoCore. Python-based open source toolset for modifying EDK2-based UEFI firmware images. Does not support any IBV customizations, but is official, and lives in EDK2 repository.
• Fiano by Google and Facebook. Go-based cross-platform open source toolset for modifying UEFI firmware images.
• PhoenixTool by AndyP. Windows-only freeware GUI application written in C#. Used mostly for SLIC-related modifications, but it not limited to this task. Requires Microsoft .NET 3.5 to work properly. Supports unpacking firmware images from various vendor-specific formats like encrypted HP update files and Dell installers.
• uefi-firmware-parser by Teddy Reed. Cross-platform open source console application written in Python. Very tinker-friendly due to use of Python. Can be used in scripts to automate firmware patching.
• Chipsec by Intel. Cross-platform partially open source console application written in Python and C. Can be used to test Intel-based platforms for various security-related misconfigurations, but also has NVRAM parser and other components aimed to firmware modification.
• CERT UEFI Parser by CERT. Open source toolset for parsing firmware images written in Python.

Installation Copy Chapter

You can either use pre-built binaries or build the binaries yourself.

• To build a binary that uses Qt library (UEFITool) you need a C++ compiler and an instance of Qt5 or Qt6 library. Install both of them, get the sources, generate makefiles using qmake (qmake ./UEFITool/uefitool.pro) and use your system's make command on that generated files (i.e. nmake release, make release and so on). Qt6-based builds can also use CMAKE as an altearnative build system.
• To build a binary that doesn't use Qt (UEFIExtract, UEFIFind), you need a C++ compiler and CMAKE utility to generate a makefile for your OS and build environment. Install both of them, get the sources, generate makefiles using cmake (cmake UEFIExtract) and use your system's make command on that generated files (i.e. nmake release, make release and so on). Non-Qt builds can also use Meson as an alternative build system.

Known issues Copy Chapter

• Image editing is currently only possible using an outdated and unsupported UEFITool 0.28 (old_engine branch) and the tools based on it (UEFIReplace, UEFIPatch). This is the top priority issue #67, which is being worked on, albeit slowly (due to the amount of coding and testing required to implement it correctly).
• Some vendor-specific firmware update files can be opened incorrectly or can't be opened at all. This includes encrypted HP update files, Dell HDR and EXE files, some InsydeFlash FD files and so on. Enabling support for such files will require massive amount of reverse-engineering which is almost pointless because the updated image can be obtained from BIOS chip where it's already decrypted and unpacked.
• Intel Firmware Interface Table (FIT) editing is not supported right now. FIT contains pointers to various image components that must be loaded before executing the first CPU instruction from the BIOS chip. Those components include CPU microcode updates, binaries and settings used by BIOS Guard and Boot Guard technologies and some other stuff. More information on FIT can be obtained here.
• Windows builds of UEFIExtract and UEFIFind might encouter an issue with folder paths being longer than 260 bytes (MAX_PATH) on some input files (see issue #363). This is a known Windows limitation, that can be fixed by enabling long paths support via Windows Registry and adding a manifest to the executable file that requires such support. UEFIExtract has the required manifest additions since version A67, and the required registry file is provided by Microsoft on the page linked above, but this workaround is only awailable starting with Windows 10 build 1067.

GUID Database Copy Chapter

Every new release includes an update to the database of known UEFI-related GUIDs build with help of Linux Vendor Firmware Service.

You can download the up-to-date version of that database using this link.

File: README.rst Copy Chapter

UEFITool

.. image:: https://raw.githubusercontent.com/LongSoft/UEFITool/old_engine/uefitool.ico
|
| UEFITool is a cross-platform C++/Qt program for parsing, extracting and modifying UEFI firmware images.
| It supports parsing of full BIOS images starting with the flash descriptor or any binary files containing UEFI volumes.
| Original development was started here <http://forums.mydigitallife.info/threads/48979-UEFITool-UEFI-firmware-image-viewer-and-editor>_ at MDL forums as a cross-platform analog to PhoenixTool <http://forums.mydigitallife.info/threads/13194-Tool-to-Insert-Replace-SLIC-in-Phoenix-Insyde-Dell-EFI-BIOSes>'s structure mode with some additional features, but the program's engine was proven to be usefull for another projects like UEFIPatch <http://www.insanelymac.com/forum/topic/285444-uefipatch-uefi-patching-utility/>, UBU <http://www.win-raid.com/t154f16-Tool-quot-UEFI-BIOS-Updater-quot-UBU.html>_ and OZMTool <http://www.insanelymac.com/forum/topic/299711-ozmtool-an-ozmosis-toolbox/>_.

Installation Copy Chapter

| You can either use pre-built binaries for Windows and OSX <https://github.com/LongSoft/UEFITool/releases/latest>_ or build a binary yourself.
| To build a binary you need a C++ compiler and an instance of Qt4/Qt5 library for it.
| Install both of them, get the sources, generate makefiles using qmake (qmake UEFITool.pro) and use your make command on that generated files (i.e. nmake release, make release and so on).

Usage Copy Chapter

| The program can be started directly without any arguments or supplied with a single argument - a path to the UEFI image file to open after start.
|
| The program window is divided into three panels: Structure, Information and Messages.
| Structure of the image is represented as a tree of elements with different names, types and subtypes. If you select an element, Information panel will show the available information about the selected element based on it's type and contents.
| Messages panel show all messages from the engine, including structure warnings and search results. Most of messages can be double-clicked to select the element that causes the message.
|
| You can open a menu on each tree element to see what operations are possible for the selected element. This can include various types of Extract, Insert and Replace operations, as well as Remove and Rebuild.
| Extract has two variants: Extract as is and Extract body. The difference is that Extract as is extracts the element with it's header (GUID, size, attributes and other structure-related information are located there), and Extract body extracts the element data only.
| Replace has the same two variants as Extract with the same meaning.
| Insert has the three different variants: Insert before, Insert after and Insert into, which is only available for UEFI volumes and encapsulation sections.
| Remove marks an element for removal on image reconstuction.
| Rebuild marks an element for rebuilding on image reconstruction. Normally, all elements that aren't marked for rebuild won't be changed at all and if you need to correct some structure error (i.e. invalid data checksum) you must mark an element for rebuild manually. If you change an element all it's parents up to the tree root will be marked for rebuild automatically. If UEFI volume is marked for rebuild all uncompressed PEI files in it will also be marked for rebuild because they must be rebased in the reconstructed image to maintain the executable-in-place constraint.
|
| There is also a search function available from the File menu, you can search all tree elements for a specified hexadecimal pattern (spaces are not counted, dot symbol (.) is used as placeholder for a single hex digit), a specified GUID (rules are the same as for hex except for spaces) and a specified text (either Unicode or ASCII, case sensitive or not). Search results will be added into Messages panel, if anything is found.
|
| After you've finished the modifications, you need to initiate image reconstruction using Save image file command from the File menu. If anything goes wrong on the reconstruction, an error will pop up, otherwise the program will prompt if you need to open the reconstructed file. Don't rush it, because reconstruction process can also generate some usefull messages, which will be lost if you open the reconstructed file immediatelly.

Known issues Copy Chapter

• Some images has non-standard calculation of base address of TE images, so the program can rebase them incorrectly after modifications. Will be solved ASAP.
• Some images may not work after modification because of no FIT table support implemented yet. It's on my high priority features list, so I hope it will be corrected soon.
• The program is meant to work with BIOS images, not some vendor-specific BIOS update files, that is why some of that update file either can\t be opened at all or return errors on reconstruction. If someone wants to write an unpacker for such crappy files - I will be glad to use it.
• AMI-specific features like NCBs, ROM_AREA structure and other things like that can't be implemented by me because of the NDA I have.