appender

Documentation

Overview

Package appender is a tiny pure-Go appender for sections to a PE32/PE32+ image. It is the equivalent of `objcopy --add-section`, restricted to the case that matters for UEFI Unified Kernel Images: appending new sections at the end of the file, leaving every existing section's RVA, file offset and data untouched.

The package only depends on the standard library and is intentionally small so it can be vendored or audited in one sitting. It is the companion to github.com/go-coff/peln/linker; together they cover the two PE assembly modes the cloud-boot toolchain needs (append sections to an existing PE, vs. link .o files into a fresh PE).

References:

• Microsoft PE/COFF specification rev 11+
• systemd-stub PE annex

Limitations:

• Section names are limited to 8 bytes (PE truncates longer names via a string table that this package does not write).
• SizeOfHeaders is not grown, so the input PE must reserve enough header padding to hold the added section-header entries. The systemd UEFI stubs (`linux{x64,aa64,riscv64}.efi.stub`) all reserve plenty.
• The Optional Header CheckSum field is zeroed; UEFI does not enforce it and recomputing requires the full PE checksum algorithm. Tools that need a valid checksum (e.g. Secure Boot signers) should run their own pass afterwards.

Index

• Constants
• func Append(stub []byte, sections []Section) ([]byte, error)
• type Section

Constants

const (
	SCN_CNT_INITIALIZED_DATA uint32 = 0x00000040
	SCN_MEM_READ             uint32 = 0x40000000
	SCN_MEM_WRITE            uint32 = 0x80000000
	SCN_MEM_EXECUTE          uint32 = 0x20000000

	// DefaultCharacteristics is the set of flags objcopy applies to a
	// `--add-section` of an arbitrary binary blob: read-only initialised data.
	DefaultCharacteristics = SCN_CNT_INITIALIZED_DATA | SCN_MEM_READ
)

IMAGE_SCN_* characteristics.

Functions

func Append

func Append(stub []byte, sections []Section) ([]byte, error)

Append takes a PE32 / PE32+ binary `stub` and returns a new image with `sections` appended after the last existing section. Existing section data is preserved byte-for-byte; only NumberOfSections, SizeOfImage and the new section-table entries are written. The PE CheckSum field is zeroed.

Returns an error if the section table cannot grow inside SizeOfHeaders, or if any input field is malformed.

Types

type Section

type Section struct {
	Name            string // up to 8 bytes; longer names are rejected
	Data            []byte
	Characteristics uint32 // see SCN_* constants; DefaultCharacteristics is fine
}

Section describes one new section to append.