pe: add Terse Executable (TE) support

Cargo.toml

@@ -19,7 +19,7 @@ include = [
     "LICENSE",
     "README.md",
 ]
-keywords = ["binary", "elf", "mach", "pe", "archive"]
+keywords = ["binary", "elf", "mach", "pe", "te", "archive"]
 license = "MIT"
 readme = "README.md"
 repository = "https://github.com/m4b/goblin"
@@ -38,7 +38,7 @@ version = "0.12"
 default_features = false
 
 [features]
-default = ["std", "elf32", "elf64", "mach32", "mach64", "pe32", "pe64", "archive", "endian_fd"]
+default = ["std", "elf32", "elf64", "mach32", "mach64", "pe32", "pe64", "te", "archive", "endian_fd"]
 std = ["alloc", "scroll/std"]
 alloc = ["scroll/derive", "log"]
 endian_fd = ["alloc"]
@@ -49,6 +49,7 @@ mach32 = ["alloc", "endian_fd", "archive"]
 mach64 = ["alloc", "endian_fd", "archive"]
 pe32 = ["alloc", "endian_fd"]
 pe64 = ["alloc", "endian_fd"]
+te = ["alloc", "endian_fd"]
 archive = ["alloc"]
 
 [badges.travis-ci]

README.md

@@ -97,6 +97,7 @@ Here are some things you could do with this crate (or help to implement so they
 * mach32 - 32-bit mach-o `repr(C)` struct defs
 * pe32 - 32-bit PE `repr(C)` struct defs
 * pe64 - 64-bit PE `repr(C)` struct defs
++ te - Terse Executable (TE) `repr(C)` struct defs
 * archive - a Unix Archive parser
 * endian_fd - parses according to the endianness in the binary
 * std - to allow `no_std` environments

src/lib.rs

@@ -229,14 +229,15 @@ pub enum Hint {
     Mach(HintData),
     MachFat(usize),
     PE,
+    TE,
     COFF,
     Archive,
     Unknown(u64),
 }
 
 macro_rules! if_everything {
     ($($i:item)*) => ($(
-        #[cfg(all(feature = "endian_fd", feature = "elf64", feature = "elf32", feature = "pe64", feature = "pe32", feature = "mach64", feature = "mach32", feature = "archive"))]
+        #[cfg(all(feature = "endian_fd", feature = "elf64", feature = "elf32", feature = "pe64", feature = "pe32", feature = "te", feature = "mach64", feature = "mach32", feature = "archive"))]
         $i
     )*)
 }
@@ -262,6 +263,7 @@ if_everything! {
         } else {
             match *&bytes[0..2].pread_with::<u16>(0, LE)? {
                 pe::header::DOS_MAGIC => Ok(Hint::PE),
+                pe::header::TE_MAGIC => Ok(Hint::TE),
                 pe::header::COFF_MACHINE_X86 |
                 pe::header::COFF_MACHINE_X86_64 |
                 pe::header::COFF_MACHINE_ARM64 => Ok(Hint::COFF),
@@ -290,6 +292,8 @@ if_everything! {
         Elf(elf::Elf<'a>),
         /// A PE32/PE32+!
         PE(pe::PE<'a>),
+        /// A TE!
+        TE(pe::TE<'a>),
         /// A COFF
         COFF(pe::Coff<'a>),
         /// A 32/64-bit Mach-o binary _OR_ it is a multi-architecture binary container!
@@ -309,6 +313,7 @@ if_everything! {
                     Hint::Mach(_) | Hint::MachFat(_) => Ok(Object::Mach(mach::Mach::parse(bytes)?)),
                     Hint::Archive => Ok(Object::Archive(archive::Archive::parse(bytes)?)),
                     Hint::PE => Ok(Object::PE(pe::PE::parse(bytes)?)),
+                    Hint::TE => Ok(Object::TE(pe::TE::parse(bytes)?)),
                     Hint::COFF => Ok(Object::COFF(pe::Coff::parse(bytes)?)),
                     Hint::Unknown(magic) => Ok(Object::Unknown(magic)),
                 }

src/pe/debug.rs

@@ -92,7 +92,7 @@ impl ImageDebugDirectory {
         )
     }
 
-    fn parse_with_opts(
+    pub(crate) fn parse_with_opts(
         bytes: &[u8],
         dd: data_directories::DataDirectory,
         sections: &[section_table::SectionTable],

src/pe/header.rs

@@ -1,5 +1,5 @@
 use crate::error;
-use crate::pe::{optional_header, section_table, symbol};
+use crate::pe::{data_directories, optional_header, section_table, symbol};
 use crate::strtab;
 use alloc::vec::Vec;
 use log::debug;
@@ -837,6 +837,147 @@ impl ctx::TryIntoCtx<scroll::Endian> for Header {
     }
 }
 
+/// The TE header is a reduced PE32/PE32+ header containing only fields
+/// required for execution in the Platform Initialization
+/// ([PI](https://uefi.org/specs/PI/1.8/V1_Introduction.html)) architecture.
+/// The TE header is described in this specification:
+/// <https://uefi.org/specs/PI/1.8/V1_TE_Image.html#te-header>
+#[cfg(feature = "te")]
+#[repr(C)]
+#[derive(Debug, Default, PartialEq, Copy, Clone, Pread, Pwrite)]
+pub struct TeHeader {
+    /// Te signature, always [TE_MAGIC]
+    pub signature: u16,
+    /// The machine type
+    pub machine: u16,
+    /// The number of sections
+    pub number_of_sections: u8,
+    /// The subsystem
+    pub subsystem: u8,
+    /// the amount of bytes stripped from the header when converting from a
+    /// PE32/PE32+ header to a TE header. Used to resolve addresses
+    pub stripped_size: u16,
+    /// The entry point of the binary
+    pub entry_point: u32,
+    /// The base of the code section
+    pub base_of_code: u32,
+    /// The image base
+    pub image_base: u64,
+    /// The size and address of the relocation directory
+    pub reloc_dir: data_directories::DataDirectory,
+    /// The size and address of the debug directory
+    pub debug_dir: data_directories::DataDirectory,
+}
+
+#[cfg(feature = "te")]
+#[doc(alias("IMAGE_TE_SIGNATURE"))]
+pub const TE_MAGIC: u16 = 0x5a56;
+
+#[cfg(feature = "te")]
+impl TeHeader {
+    /// Parse the TE header from the given bytes.
+    pub fn parse(bytes: &[u8], offset: &mut usize) -> error::Result<Self> {
+        let mut header: TeHeader = bytes.gread_with(offset, scroll::LE)?;
+        let adj_offset = header.stripped_size as u32 - core::mem::size_of::<TeHeader>() as u32;
+        header.fixup_header(adj_offset);
+        Ok(header)
+    }
+
+    /// Parse the sections from the TE header.
+    pub fn sections(
+        &self,
+        bytes: &[u8],
+        offset: &mut usize,
+    ) -> error::Result<Vec<section_table::SectionTable>> {
+        let adj_offset = self.stripped_size as u32 - core::mem::size_of::<TeHeader>() as u32;
+        let nsections = self.number_of_sections as usize;
+
+        // a section table is at least 40 bytes
+        if nsections > bytes.len() / 40 {
+            return Err(error::Error::BufferTooShort(nsections, "sections"));
+        }
+
+        let mut sections = Vec::with_capacity(nsections);
+        for i in 0..nsections {
+            let mut section = section_table::SectionTable::parse(bytes, offset, 0)?;
+            TeHeader::fixup_section(&mut section, adj_offset);
+            debug!("({}) {:#?}", i, section);
+            sections.push(section);
+        }
+        Ok(sections)
+    }
+
+    // Adjust addresses in the header to account for the stripped size
+    fn fixup_header(&mut self, adj_offset: u32) {
+        debug!(
+            "Entry point fixed up from: 0x{:x} to 0x{:X}",
+            self.entry_point,
+            self.entry_point.wrapping_sub(adj_offset)
+        );
+        self.entry_point = self.entry_point.wrapping_sub(adj_offset);
+
+        debug!(
+            "Base of code fixed up from: 0x{:x} to 0x{:X}",
+            self.base_of_code,
+            self.base_of_code.wrapping_sub(adj_offset)
+        );
+        self.base_of_code = self.base_of_code.wrapping_sub(adj_offset);
+
+        debug!(
+            "Relocation Directory fixed up from: 0x{:x} to 0x{:X}",
+            self.reloc_dir.virtual_address,
+            self.reloc_dir.virtual_address.wrapping_sub(adj_offset)
+        );
+        self.reloc_dir.virtual_address = self.reloc_dir.virtual_address.wrapping_sub(adj_offset);
+
+        debug!(
+            "Debug Directory fixed up from: 0x{:x} to 0x{:X}",
+            self.debug_dir.virtual_address,
+            self.debug_dir.virtual_address.wrapping_sub(adj_offset)
+        );
+        self.debug_dir.virtual_address = self.debug_dir.virtual_address.wrapping_sub(adj_offset);
+    }
+
+    // Adjust addresses in the section to account for the stripped size
+    fn fixup_section(section: &mut section_table::SectionTable, adj_offset: u32) {
+        debug!(
+            "Section virtual address fixed up from: 0x{:X} to 0x{:X}",
+            section.virtual_address,
+            section.virtual_address.wrapping_sub(adj_offset)
+        );
+        section.virtual_address = section.virtual_address.wrapping_sub(adj_offset);
+
+        if section.pointer_to_linenumbers > 0 {
+            debug!(
+                "Section pointer to line numbers fixed up from: 0x{:X} to 0x{:X}",
+                section.pointer_to_linenumbers,
+                section.pointer_to_linenumbers.wrapping_sub(adj_offset)
+            );
+            section.pointer_to_linenumbers =
+                section.pointer_to_linenumbers.wrapping_sub(adj_offset);
+        }
+
+        if section.pointer_to_raw_data > 0 {
+            debug!(
+                "Section pointer to raw data fixed up from: 0x{:X} to 0x{:X}",
+                section.pointer_to_raw_data,
+                section.pointer_to_raw_data.wrapping_sub(adj_offset)
+            );
+            section.pointer_to_raw_data = section.pointer_to_raw_data.wrapping_sub(adj_offset);
+        }
+
+        if section.pointer_to_relocations > 0 {
+            debug!(
+                "Section pointer to relocations fixed up from: 0x{:X} to 0x{:X}",
+                section.pointer_to_relocations,
+                section.pointer_to_relocations.wrapping_sub(adj_offset)
+            );
+            section.pointer_to_relocations =
+                section.pointer_to_relocations.wrapping_sub(adj_offset);
+        }
+    }
+}
+
 /// Convert machine to str representation. Any case of "COFF_UNKNOWN"
 /// should be expected to change to a more specific value.
 pub fn machine_to_str(machine: u16) -> &'static str {

src/pe/mod.rs

@@ -467,6 +467,98 @@ impl<'a> ctx::TryIntoCtx<scroll::Endian> for PE<'a> {
     }
 }
 
+/// An analyzed TE binary
+///
+/// A TE binary is a PE/PE32+ binary that has had it's header stripped and
+/// re-formatted to the TE specification. This presents a challenge for
+/// parsing, as all relative addresses (RVAs) are not updated to take this into
+/// account, and are thus incorrect. The parsing of a TE must take this into
+/// account by using the [header::TeHeader::stripped_size`] field of the TE
+/// header to adjust the RVAs during parsing.
+#[cfg(feature = "te")]
+#[derive(Debug)]
+pub struct TE<'a> {
+    /// The TE header
+    pub header: header::TeHeader,
+    /// A list of the sections in this TE binary
+    pub sections: Vec<section_table::SectionTable>,
+    /// Debug information, contained in the PE header
+    pub debug_data: debug::DebugData<'a>,
+    /// The offset to apply to addresses not parsed by the TE parser
+    /// itself: [header::TeHeader::stripped_size] - size_of::<[header::TeHeader]>()
+    pub rva_offset: usize,
+}
+
+#[cfg(feature = "te")]
+impl<'a> TE<'a> {
+    /// Reads a TE binary from the underlying `bytes`
+    pub fn parse(bytes: &'a [u8]) -> error::Result<Self> {
+        let opts = &options::ParseOptions {
+            resolve_rva: false,
+            parse_attribute_certificates: false,
+        };
+
+        let mut offset = 0;
+
+        // Parse the TE header and adjust the offsets
+        let header = header::TeHeader::parse(bytes, &mut offset)?;
+        let rva_offset = header.stripped_size as usize - core::mem::size_of::<header::TeHeader>();
+
+        // Parse the sections and adjust the offsets
+        let sections = header.sections(bytes, &mut offset)?;
+
+        // Parse the debug data. Must adjust offsets before parsing the image_debug_directory
+        let mut debug_data = debug::DebugData::default();
+        debug_data.image_debug_directory = debug::ImageDebugDirectory::parse_with_opts(
+            bytes,
+            header.debug_dir,
+            &sections,
+            0,
+            opts,
+        )?;
+        TE::fixup_debug_data(&mut debug_data, rva_offset as u32);
+        debug_data.codeview_pdb70_debug_info = debug::CodeviewPDB70DebugInfo::parse_with_opts(
+            bytes,
+            &debug_data.image_debug_directory,
+            opts,
+        )?;
+
+        Ok(TE {
+            header,
+            sections,
+            debug_data,
+            rva_offset,
+        })
+    }
+
+    /// Adjust all addresses in the TE binary debug data.
+    fn fixup_debug_data(dd: &mut debug::DebugData, rva_offset: u32) {
+        debug!(
+            "ImageDebugDirectory address of raw data fixed up from: 0x{:X} to 0x{:X}",
+            dd.image_debug_directory.address_of_raw_data,
+            dd.image_debug_directory
+                .address_of_raw_data
+                .wrapping_sub(rva_offset),
+        );
+        dd.image_debug_directory.address_of_raw_data = dd
+            .image_debug_directory
+            .address_of_raw_data
+            .wrapping_sub(rva_offset);
+
+        debug!(
+            "ImageDebugDirectory pointer to raw data fixed up from: 0x{:X} to 0x{:X}",
+            dd.image_debug_directory.pointer_to_raw_data,
+            dd.image_debug_directory
+                .pointer_to_raw_data
+                .wrapping_sub(rva_offset),
+        );
+        dd.image_debug_directory.pointer_to_raw_data = dd
+            .image_debug_directory
+            .pointer_to_raw_data
+            .wrapping_sub(rva_offset);
+    }
+}
+
 /// An analyzed COFF object
 #[derive(Debug)]
 pub struct Coff<'a> {

tests/bins/te/README.md

@@ -0,0 +1,24 @@
+# TE binaries
+
+Binaries located in this directory are precompiled PE32/PE32+ binaries using a
+terse executable (TE) header as defined in the Platform Initialization (PI)
+specification: [TE](https://uefi.org/specs/PI/1.8/V1_TE_Image.html#te-header).
+These binaries were compiled using the
+[EDK2](https://github.com/tianocore/edk2) build system.
+
+## test_image.te
+
+This binary is a simple Terse executable binary
+
+## test_image_loaded.bin
+
+This binary is the same as `test_image.te`, but it has been loaded by a loader,
+meaning the sections have been placed in the expected address. Please note that
+this particular binary has not been relocated, so no relocations have been
+applied
+
+## test_image_relocated.bin
+
+This binary is the same as `test_image.te`, but it has been loaded by a loader,
+meaning the sections have been placed in the expected address, and any any
+relocations have been applied.