regedit

README

go-regedit

Pure-Go editing of Windows registry hive files. Point it at a SYSTEM or SOFTWARE hive on disk and it can read and patch values directly in the binary format, no hivex, no cgo, no Windows required. The main use case is servicing offline images: the Windows install you are modifying is not running, its hives are just files.

The API is small. ApplyDWordPatches and ReadDWord handle the common case of flipping and verifying REG_DWORD values. WriteKey adds whole keys with typed values, growing the hive when it runs out of room. ParseRegExport turns a .reg export into a key tree you can replay with WriteKey, which is handy for copying a service definition from a reference machine. There are also BCD helpers (SetHypervisorLaunchType, ClearWinPEFlag and friends), since a BCD store is just another hive.

This library is part of the Windows tooling behind devcell. Hive editing is the kind of thing you want tested against the real consumer: the test suite includes fixtures from actual hives and an opt-in check that loads a patched hive on a live Windows machine. No v1 yet, so pin a version.

go get github.com/devcell-sh/go-regedit

Documentation

Index

• Constants
• func ApplyDWordPatches(hivePath string, patches []DWordPatch) error
• func ClearWinPEFlag(bcdPath string) error
• func ParseRegExport(r io.Reader) (map[string]*Key, error)
• func ReadDWord(hivePath, keyPath, valueName string) (uint32, error)
• func SetBCDBooleanElement(bcdPath, objectGUID, elementCode string, value bool) error
• func SetBCDIntegerElement(bcdPath, objectGUID, elementCode string, value uint64) error
• func SetHypervisorLaunchType(bcdPath string, mode uint64) error
• func WriteKey(hivePath, keyPath string, spec *Key) error
• type DWordPatch
• type Key
  • func ReadServiceKey(hivePath, keyPath string) (*Key, error)
• type Value
  • func (v Value) DWord() uint32
  • func (v Value) String() string
  • func (v Value) Strings() []string

Constants

const (
	// WinPELoaderGUID is the well-known identifier of the Windows PE boot
	// loader entry ({7619dcc9-fafe-11d9-b411-000476eba25f}) present in the
	// BCD store on Windows installation media.
	WinPELoaderGUID = "{7619dcc9-fafe-11d9-b411-000476eba25f}"

	// ElementHypervisorLaunchType selects whether winload starts the
	// hypervisor (BcdOSLoaderInteger_HypervisorLaunchType).
	ElementHypervisorLaunchType = "250000f0"

	// ElementWinPE is BcdOSLoaderBoolean_WinPE. When set to 1, winload
	// treats the boot as a WinPE session and skips subsystems that a
	// preinstallation environment does not need, including the hypervisor
	// launch path. Clearing it to 0 lets winload enter EL2 normally.
	ElementWinPE = "26000022"
)

A BCD store is a registry hive whose boot entries live under Objects\{guid}\Elements\<code>, each element holding its payload in a value named "Element".

const (
	HypervisorLaunchOff  uint64 = 0
	HypervisorLaunchAuto uint64 = 1
)

Hypervisor launch modes for ElementHypervisorLaunchType.

const (
	TypeNone             uint32 = 0
	TypeString           uint32 = 1  // REG_SZ
	TypeExpandString     uint32 = 2  // REG_EXPAND_SZ
	TypeBinary           uint32 = 3  // REG_BINARY
	TypeDWord            uint32 = 4  // REG_DWORD (little-endian)
	TypeDWordBigEndian   uint32 = 5  // REG_DWORD_BIG_ENDIAN
	TypeLink             uint32 = 6  // REG_LINK
	TypeMultiString      uint32 = 7  // REG_MULTI_SZ
	TypeResourceList     uint32 = 8  // REG_RESOURCE_LIST
	TypeFullResourceDesc uint32 = 9  // REG_FULL_RESOURCE_DESCRIPTOR
	TypeResourceReqList  uint32 = 10 // REG_RESOURCE_REQUIREMENTS_LIST
	TypeQWord            uint32 = 11 // REG_QWORD
)

Registry value types, as stored in a vk cell's type field.

Functions

func ApplyDWordPatches

func ApplyDWordPatches(hivePath string, patches []DWordPatch) error

ApplyDWordPatches opens a Windows registry hive file, navigates to each patch's key/value, and overwrites the DWORD data in place. The hive file is modified on disk.

Only REG_DWORD values that already exist can be patched — the function returns an error if a key, value, or non-DWORD type is encountered.

func ClearWinPEFlag

func ClearWinPEFlag(bcdPath string) error

ClearWinPEFlag sets BcdOSLoaderBoolean_WinPE to 0 on the WinPE loader entry. Stock WinPE media has this set to 1, which causes winload to skip the hypervisor launch path even when hypervisorlaunchtype=Auto.

func ParseRegExport

func ParseRegExport(r io.Reader) (map[string]*Key, error)

ParseRegExport reads a "Windows Registry Editor Version 5.00" export and returns the top-level keys it defines, indexed by hive-relative path (the HKEY_LOCAL_MACHINE\ prefix stripped). Subkeys of an exported key are nested under it rather than returned separately, so a whole service subtree arrives as one Key ready to hand to WriteKey.

This is the transplant's source of truth: install.wim's own SYSTEM hive only holds services that ship enabled, while the rest are created when the optional feature is turned on. An export from a reference machine with the feature enabled carries all of them.

func ReadDWord

func ReadDWord(hivePath, keyPath, valueName string) (uint32, error)

ReadDWord reads a single REG_DWORD value from a Windows registry hive file without modifying it. Returns the value or an error if the key, value, or hive is invalid.

func SetBCDBooleanElement

func SetBCDBooleanElement(bcdPath, objectGUID, elementCode string, value bool) error

SetBCDBooleanElement writes a 1-byte boolean element into a BCD object.

func SetBCDIntegerElement

func SetBCDIntegerElement(bcdPath, objectGUID, elementCode string, value uint64) error

SetBCDIntegerElement writes an 8-byte little-endian integer element into a BCD object, creating the element key if needed.

func SetHypervisorLaunchType

func SetHypervisorLaunchType(bcdPath string, mode uint64) error

SetHypervisorLaunchType writes hypervisorlaunchtype into a BCD store's WinPE loader entry, creating the element when the media does not carry one — stock Windows media never does.

This has to happen while the boot media is staged on the host: WinPE runs from a ramdisk and cannot open the BCD store it booted from.

func WriteKey

func WriteKey(hivePath, keyPath string, spec *Key) error

WriteKey creates or updates a key (and its subkey tree) in a hive file. keyPath is relative to the hive root using backslash separators; every component but the last must already exist.

Values in spec are written over any existing values of the same name; values already in the hive but absent from spec are left alone. New cells are appended in fresh hbins rather than reusing free space, which keeps allocation trivially correct at the cost of some file growth.

Types

type DWordPatch

type DWordPatch struct {
	// KeyPath is the registry key path relative to the hive root,
	// using backslash separators (e.g. `ControlSet001\Services\hvservice`).
	KeyPath string
	// ValueName is the value entry to modify (e.g. "Start").
	ValueName string
	// Value is the new DWORD value.
	Value uint32
	// Optional silently skips this patch when the key or value does
	// not exist instead of returning an error.
	Optional bool
}

DWordPatch describes a single DWORD value to overwrite in a Windows registry hive file. The key must already exist — this package modifies existing values in place rather than creating new keys or values.

type Key

type Key struct {
	Name    string
	Values  map[string]Value
	Subkeys map[string]*Key
}

Key is a registry key read out of a hive: its values and, recursively, its subkeys. Names are the hive's own casing; lookups are case-sensitive, matching the exact spelling Windows stores.

func ReadServiceKey

func ReadServiceKey(hivePath, keyPath string) (*Key, error)

ReadServiceKey reads a key and its entire subtree from a hive file without modifying it. keyPath is relative to the hive root using backslash separators (e.g. `ControlSet001\Services\vmbus`).

type Value

type Value struct {
	Type uint32
	Data []byte
}

Value is a single registry value: its type tag and raw data exactly as stored in the hive. Decoding helpers interpret Data by type; callers cloning values into another hive should copy Type and Data verbatim.

func (Value) DWord

func (v Value) DWord() uint32

DWord decodes REG_DWORD data. Other types, or truncated data, yield 0.

func (Value) String

func (v Value) String() string

String decodes REG_SZ / REG_EXPAND_SZ / REG_LINK data (UTF-16LE) and trims the trailing NUL. Other types yield an empty string.

func (Value) Strings

func (v Value) Strings() []string

Strings decodes REG_MULTI_SZ data into its entries, dropping the empty terminator. Other types yield nil.