Class UnmanagedPEFileBuilder

Namespace

AsmResolver.PE.Builder

Assembly

AsmResolver.PE.dll

Provides a mechanism for constructing PE files containing unmanaged code or metadata, based on a template PE file.

public class UnmanagedPEFileBuilder : PEFileBuilder<UnmanagedPEFileBuilder.BuilderContext>, IPEFileBuilder

Inheritance

object

PEFileBuilder<UnmanagedPEFileBuilder.BuilderContext>

UnmanagedPEFileBuilder

Implements

IPEFileBuilder

Inherited Members

PEFileBuilder<UnmanagedPEFileBuilder.BuilderContext>.CreateFile(PEImage)

PEFileBuilder<UnmanagedPEFileBuilder.BuilderContext>.GetFileAlignment(UnmanagedPEFileBuilder.BuilderContext, PEFile)

PEFileBuilder<UnmanagedPEFileBuilder.BuilderContext>.GetSectionAlignment(UnmanagedPEFileBuilder.BuilderContext, PEFile)

PEFileBuilder<UnmanagedPEFileBuilder.BuilderContext>.GetImageBase(UnmanagedPEFileBuilder.BuilderContext, PEFile)

PEFileBuilder<UnmanagedPEFileBuilder.BuilderContext>.ComputeHeaderFields(UnmanagedPEFileBuilder.BuilderContext, PEFile)

PEFileBuilder<UnmanagedPEFileBuilder.BuilderContext>.ComputeOptionalHeaderFields(UnmanagedPEFileBuilder.BuilderContext, PEFile)

PEFileBuilder<UnmanagedPEFileBuilder.BuilderContext>.ComputeFileHeaderFields(UnmanagedPEFileBuilder.BuilderContext, PEFile)

PEFileBuilder<UnmanagedPEFileBuilder.BuilderContext>.CreateDebugDirectory(UnmanagedPEFileBuilder.BuilderContext)

PEFileBuilder<UnmanagedPEFileBuilder.BuilderContext>.CreateExportDirectory(UnmanagedPEFileBuilder.BuilderContext)

PEFileBuilder<UnmanagedPEFileBuilder.BuilderContext>.CreateResourcesDirectory(UnmanagedPEFileBuilder.BuilderContext)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This PE file builder attempts to preserve as much data as possible in the original executable file, and is well suited for input binaries that contain unmanaged code and/or depend on raw offsets, RVAs or similar. However, it may therefore not necessarily produce the most space-efficient output binaries, and may leave in original data directories or sometimes entire PE sections that are no longer in use.

This class might modify the final imports directory (exposed by the Imports property), as well as the base relocations directory (exposed by the Relocations property). In particular, it might add or remove the entry to mscoree.dll!_CorExeMain or mscoree.dll!_CorDllMain, and it may also add a reference to kernel32.dll!VirtualProtect in case dynamic initializers need to be injected to initialize reconstructed some parts of the original import address tables (IATs).

By default, the Import Address Table (IATs) and .NET's VTable Fixup Table are not reconstructed and are preserved. When changing any imports or VTable fixups in the PE image, set the appropriate TrampolineImports or TrampolineVTableFixups properties to true. This will instruct the builder to patch the original address tables and trampoline them to their new layout. This may also result in the builder injecting additional initializer code to be inserted in .auxtext, depending on the type of imports that are present. This initialization code is added as a TLS callback to the final PE file.

This class will add at most 5 new auxiliary sections to the final output PE file, next to the sections that were already present in the input PE file, to fit in reconstructed data directories that did not fit in the original location.

Constructors

UnmanagedPEFileBuilder()

Creates a new unmanaged PE file builder.

public UnmanagedPEFileBuilder()

UnmanagedPEFileBuilder(IErrorListener)

Creates a new unmanaged PE file builder using the provided error listener.

public UnmanagedPEFileBuilder(IErrorListener errorListener)

Parameters

errorListener IErrorListener

The error listener to use.

UnmanagedPEFileBuilder(IErrorListener, PEFile?)

Creates a new unmanaged PE file builder using the provided error listener and base PE file.

public UnmanagedPEFileBuilder(IErrorListener errorListener, PEFile? baseFile)

Parameters

errorListener IErrorListener

The error listener to use.

baseFile PEFile

The template file to base the resulting file on.

Properties

BaseFile

Gets or sets the template file to base the resulting file on.

public PEFile? BaseFile { get; set; }

Property Value

PEFile

ErrorListener

Gets or sets the service used for registering exceptions that occur during the construction of the PE.

public IErrorListener ErrorListener { get; set; }

Property Value

IErrorListener

ImportedSymbolClassifier

Gets or sets the service that is used for determining whether an imported symbol is a function or a data symbol. This is required when TrampolineImports is set to true and the IAT is reconstructed.

public IImportedSymbolClassifier ImportedSymbolClassifier { get; set; }

Property Value

IImportedSymbolClassifier

TrampolineImports

Gets or sets a value indicating whether the imports directory of the new file is supposed to be reconstructed and that the old, existing imports directory should be patched and rewired via trampolines.

public bool TrampolineImports { get; set; }

Property Value

bool

TrampolineVTableFixups

Gets or sets a value indicating whether the VTable fixups directory of the new file is supposed to be reconstructed and that the old, existing VTable fixups directory should be patched and rewired via trampolines.

public bool TrampolineVTableFixups { get; set; }

Property Value

bool

Methods

AssignDataDirectories(BuilderContext, PEFile)

Creates the data directory headers stored in the optional header of the PE file.

protected override void AssignDataDirectories(UnmanagedPEFileBuilder.BuilderContext context, PEFile outputFile)

Parameters

context UnmanagedPEFileBuilder.BuilderContext

The object containing the intermediate values used during the PE file construction.

outputFile PEFile

The (incomplete) PE file that contains the sections.

CreateAuxDataSection(BuilderContext)

Creates the .sdata section containing the exports, vtable fixup tokens, and the TLS index.

protected virtual PESection? CreateAuxDataSection(UnmanagedPEFileBuilder.BuilderContext context)

Parameters

context UnmanagedPEFileBuilder.BuilderContext

The working space of the builder.

Returns

PESection

The section.

CreateAuxRDataSection(BuilderContext)

Creates an auxiliary .rdata section containing a TLS data directory, its template data and callback function table (when present in the image).

protected virtual PESection? CreateAuxRDataSection(UnmanagedPEFileBuilder.BuilderContext context)

Parameters

context UnmanagedPEFileBuilder.BuilderContext

The working space of the builder.

Returns

PESection

The new .rdata section.

CreateAuxRelocSection(BuilderContext)

Creates the base relocations section (.reloc) of the new .NET PE file.

protected virtual PESection? CreateAuxRelocSection(UnmanagedPEFileBuilder.BuilderContext context)

Parameters

context UnmanagedPEFileBuilder.BuilderContext

The working space of the builder.

Returns

PESection

The base relocations section.

CreateAuxRsrcSection(BuilderContext)

Creates the win32 resources section (.rsrc) of the new .NET PE file.

protected virtual PESection? CreateAuxRsrcSection(UnmanagedPEFileBuilder.BuilderContext context)

Parameters

context UnmanagedPEFileBuilder.BuilderContext

The working space of the builder.

Returns

PESection

The resources section.

CreateAuxTextSection(BuilderContext)

Builds up an auxiliary main text section (.auxtext) of the new .NET PE file when necessary.

protected virtual PESection? CreateAuxTextSection(UnmanagedPEFileBuilder.BuilderContext context)

Parameters

context UnmanagedPEFileBuilder.BuilderContext

The working space of the builder.

Returns

PESection

The new .text section, or null if no auxiliary text section was required.

CreateContext(PEImage)

Creates a new context for temporary storage of intermediate values during the construction of a PE image.

protected override UnmanagedPEFileBuilder.BuilderContext CreateContext(PEImage image)

Parameters

image PEImage

The image to build.

Returns

UnmanagedPEFileBuilder.BuilderContext

The context.

CreateDataDirectoryBuffers(BuilderContext)

Populates all buffers with data from the input image.

protected override void CreateDataDirectoryBuffers(UnmanagedPEFileBuilder.BuilderContext context)

Parameters

context UnmanagedPEFileBuilder.BuilderContext

The builder context.

CreateImportDirectory(BuilderContext)

Populates the import directory buffer.

protected override void CreateImportDirectory(UnmanagedPEFileBuilder.BuilderContext context)

Parameters

context UnmanagedPEFileBuilder.BuilderContext

The builder context.

CreateRelocationsDirectory(BuilderContext)

Populates the base relocations directory buffer.

protected override void CreateRelocationsDirectory(UnmanagedPEFileBuilder.BuilderContext context)

Parameters

context UnmanagedPEFileBuilder.BuilderContext

The builder context.

CreateSections(BuilderContext)

Creates the sections of the PE image.

protected override IEnumerable<PESection> CreateSections(UnmanagedPEFileBuilder.BuilderContext context)

Parameters

context UnmanagedPEFileBuilder.BuilderContext

The object containing the intermediate values used during the PE file construction.

Returns

IEnumerable<PESection>

The sections.

GetEntryPointAddress(BuilderContext, PEFile)

Gets the relative virtual address (RVA) to the entry point of the PE file.

protected override uint GetEntryPointAddress(UnmanagedPEFileBuilder.BuilderContext context, PEFile outputFile)

Parameters

context UnmanagedPEFileBuilder.BuilderContext

The object containing the intermediate values used during the PE file construction.

outputFile PEFile

The (incomplete) PE file.

Returns

uint

The relative virtual address to the entry point.