moonregf

    纯 MoonBit 实现的 Windows 注册表 hive(REGF)读取与写入库,不依赖 Windows API

    windows
    registry
    regf
    hive
    parser
    forensics
    Download zip
    Author
    Version
    0.3.0
    License
    Apache-2.0
    Last updated
    5 days ago
    Downloads
    46

    #moonregf

    纯 MoonBit 实现的 Windows 注册表 hive 文件(REGF 二进制格式)读取与写入库:不依赖 Windows API、C 库或 FFI。

    Windows 把 NTUSER.DAT、SYSTEM、SOFTWARE 等配置单元以 REGF 格式存盘。本项目在纯 MoonBit 中读写该格式, 让工具链在 Windows 之外(Linux CI、wasm-gc、浏览器)也能读取与生成 hive,并把 .reg 文本导入成 hive。

    #安装

    moon add Xcsa-ee/moonregf

    moon.pkg 中导入:

    import { "Xcsa-ee/moonregf", }

    #读取

    match @moonregf.parse_header(bytes) { Ok(header) => println(header.file_name) Err(error) => println(error.message()) }

    遍历键树、读取键值:

    for entry in @moonregf.walk_key_tree(bytes, header.root_cell_offset, 3) { println(entry.path) } match @moonregf.list_values(bytes, key) { Ok(values) => for value in values { println(value.name + " = " + value.data_type.label()) } Err(error) => println(error.message()) }

    想先看清楚这些字节长什么样,见 docs/byte-walkthrough.md:一个 8 KiB hive 的 base block、hbin 头与根 cell 的真实十六进制,逐字段对照偏移。

    #写入

    let builder = @moonregf.HiveBuilder::new() let software = builder.add_key(0, "Software") builder.set_string(software, "Install", "Hello") builder.set_dword(software, "Count", 42) match builder.build() { Ok(bytes) => println(bytes.length()) Err(error) => println(error.message()) }

    #.reg 导入

    match @moonregf.parse_reg_bytes(raw) { Ok(file) => match file.to_builder() { Ok(builder) => builder.build() Err(error) => println(error.message()) } Err(error) => println(error.message()) }

    命令行:

    moon run cmd/main -- <path-to-NTUSER.DAT> moon run cmd/main -- <path-to-NTUSER.DAT> --values moon run cmd/main -- <path-to-NTUSER.DAT> --security moon run cmd/main -- --build demo.hive moon run cmd/main -- --import-reg backup.reg rebuilt.hive moon run cmd/main -- --export-reg rebuilt.hive out.reg HKEY_CURRENT_USER moon run cmd/main -- --replay-log dirty.hive dirty.hive.LOG1 clean.hive moon run cmd/main -- --rebuild in.hive out.hive

    #读一个真实 hive 的可复现路径

    登录会话里 %USERPROFILE%\NTUSER.DAT 正被系统独占,直接读会失败:

    I/O error: Failed to read file C:\Users\<你>\NTUSER.DAT: 另一个程序正在使用此文件,进程无法访问。 (os error 32)

    先取一份可读的 hive,任选其一:reg save HKCU\Software software.hive /y(需备份权限,非管理员会报 A required privilege is not held by the client);从离线镜像或卷影副本复制;或读他人导出的 .reg、用构造器生成的 hive。

    不依赖任何外部文件的最小演示(第一条会在当前目录生成 demo.hive):

    moon run cmd/main -- --build demo.hive moon run cmd/main -- demo.hive moon run cmd/main -- demo.hive --values

    在 C:\Users\Default\NTUSER.DAT(262,144 B)上实测:walk_key_tree(data, header.root_cell_offset, 64) 全深度遍历得 634 个键,list_values 汇总 1,065 个值;同一份 hive 用 regipy 6.5.0 逐条比对,路径与值名的对称差为 0(2026-11-08,在全新工程 moon add Xcsa-ee/moonregf@0.2.0 内运行;CLI 默认只列 depth 3 的键)。

    #修改已有 hive

    HiveEditor 把 hive 读进内存,改完再写回,并保留原有元数据:

    let editor = @moonregf.HiveEditor::open(raw) if let Some(key) = editor.find("ROOT/Software/Vendor") { editor.set_dword(key, "Count", 7) let _ = editor.delete_value(key, "Install") let added = editor.add_key(key, "Inner") editor.set_string(added, "Note", "added") } let bytes = editor.build()

    保真的字段:nk 的写入时间戳、访问位与标志位,类名,sk 安全描述符,以及 base block 的文件名与序列号。

    重建是一次全量重写:空闲空间与已删除记录不会保留下来,所以 --rebuild 默认用 open_strict, 一旦加载时丢掉过记录就拒绝写出;确需写出时加 --force,它会先打印丢掉了多少值与子键列表。 写入器按 4096 字节分箱:每个 bin 自带 32 字节 hbin 头,bin 尾部补空闲 cell,单个 cell 放不进当前 bin 时它会独占一个按需扩大的 bin。写出的多 bin hive 与 Windows 自己的布局同形。 在本机 NTUSER.DAT 上做过往返验证:634 键 / 1,065 值在重建后与原文件一致(regipy 双向计数相同),属主、属组与 ACL 标志不变。

    #示例

    examples/basic 在内存里构造一个 hive,再读回并打印每个键与值,不需要任何输入文件:

    moon run examples/basic

    #演示视频

    docs/demo.mp4 用真实命令演示:两个后端的门禁与测试、解析本机 hive、遍历键树、值导出并与独立解析器对拍、生成 hive 后由独立解析器读回、.reg 往返、事务日志重放。

    #参考与来源

    实现依据、关键判断与对拍方式见 DESIGN.md。格式按公开说明实现,未移植上游源码;reg.exe 与 regipy 只在本机作为独立解析器对拍,不进入仓库、不作为运行依赖。

    #记录支持矩阵

    按 REGF 的结构逐项列出读写状态。写不了的地方返回明确错误,不静默截断或丢弃。

    结构读取写入说明
    base block是是校验和按前 508 字节逐 u32 异或重算
    hbin / cell是是cell 长度含 4 字节头,按 8 字节对齐
    nk 键节点是是读取支持压缩与 UTF-16 名称;写入按名称自动选压缩或 UTF-16LE
    lf / lh / li是是按子键数与名称编码自动选择,也可显式指定
    ri 根索引是是子键超过 500 个时自动生成,每片 500 项
    vk 值记录是是类型码 1 / 2 / 3 / 4 / 7 / 11 已映射
    内联数据是是数据不超过 4 字节时直接存在 vk 里
    big data(db)是是读取按段拼接;写入按 16344 字节分段
    del(已删除键)是不适用--orphans 扫出未被活动键树引用的 nk 与 del 记录
    sk 安全描述符是是解析属主与属组 SID、ACL 是否存在;写入按给定描述符生成 sk 记录
    .reg 文本是是导入支持 REGEDIT4 与 version 5.00;导出固定 version 5.00
    .reg 删除段否否遇到 [-key] 返回 UnsupportedDelete
    HvLE 事务日志是否只解析 8.1 及更新版本;写入与生成日志不在范围内

    #持续集成

    .github/workflows/regf.yml 拆成三个作业,红了能一眼看出是哪一层出问题:

    1. 字节布局:moon fmt --check + moon check --target wasm-gc --deny-warn,再 moon build。
    2. 解析器测试:wasm-gc 与 js 两个后端的矩阵,各自跑 moon test --deny-warn。
    3. 写出的 hive 必须能被读回:先用 --build 生成 hive,再用本库自己的 CLI 读回,断言键数 3、值数 3、校验和存在; 再把 examples/sample.reg 导入成 hive 并导出回文本,断言 dword:0000002a、hex(2) 与嵌套键都在。

    #格式版本与互操作

    读取端接受 base block 声明的 1.3 / 1.5 / 1.6 三个版本(HiveHeader::version_supported),其余版本仍可解析但会报告为不受支持。 本机 NTUSER.DAT 是 1.5;把同一份夹具的版本字段改成 1.3 与 1.6 后,本库与 regipy 都能读出相同的键树,也能经 --rebuild 写回。

    事务日志按序列号次序合并:先应用较旧的一份,再应用较新的一份;比 hive 次序列号旧的日志不动作。 在真实 NTUSER.DAT.LOG1 上验证过两种情形:干净 hive 应用 0 条且字节不变,降次序列号后应用 1 条并与独立实现逐字节一致。

    #已知限制

    • .reg 导入不支持 [-key] 删除段,遇到时返回 UnsupportedDelete。
    • 事务日志只解析 Windows 8.1 及更新版本的 HvLE 格式;更早的 512 字节头格式返回 UnsupportedLogVersion。
    • .reg 导出输出 UTF-8 文本;导入端支持 UTF-16LE 与 UTF-8 两种输入。

    #数据与隐私

    hive 通常含用户名、路径、产品密钥等信息,属于个人数据。因此:

    • 库本身不发网络请求,不写日志文件,不读取文件路径之外的上下文。
    • CLI 只把解析结果打印到标准输出,不缓存、不上传。
    • 仓库的忽略规则默认挡住 .hive、.LOG1、.LOG2、.reg,只有 examples/*.reg 例外;对拍用的真实 hive 一律留在仓库外。

    #开发与提交约定

    提交标题按改动所在的层加方括号前缀(hdr / cell / nk / lf / vk / big / log / reg / build / cli / ci / docs / repo), 夹具再生步骤与本地门禁命令写在 CONTRIBUTING.md。

    #许可

    Apache-2.0,见 LICENSE。

    Ace

    pub(all) struct Ace {
    ace_type : AceType
    flags : Int
    mask : UInt
    sid : String
    }

    One parsed access control entry.

    AceType

    pub(all) enum AceType {
    AccessAllowed
    AccessDenied
    SystemAudit
    SystemAlarm
    AccessAllowedObject
    AccessDeniedObject
    SystemAuditObject
    SystemAlarmObject
    Unknown(Int)
    }

    How one access control entry grants, denies or audits access.

    AceType::label

    fn AceType::label(self : AceType) -> String

    Human readable label of an ACE type.

    BuildValue

    type BuildValue

    A value waiting to be written into a hive.

    EditableKey

    pub(all) struct EditableKey {
    name : String
    parent : Int
    children : Array[Int]
    values : Array[EditableValue]
    high : UInt
    low : UInt
    access : UInt
    flags : UInt
    class_bytes : Bytes
    security : Bytes
    }

    One key inside an editable tree, carrying the metadata the writer needs to reproduce the original key bit for bit.

    EditableValue

    pub(all) struct EditableValue {
    name : String
    data_type : HiveValueType
    data : Bytes
    }

    One value inside an editable tree.

    HiveBuilder

    pub struct HiveBuilder {
    names : Array[String]
    parents : Array[Int]
    children : Array[Array[Int]]
    values : Array[Array[BuildValue]]
    kinds : Array[Int]
    securities : Array[Bytes]
    highs : Array[UInt]
    lows : Array[UInt]
    access : Array[UInt]
    extras : Array[UInt]
    classes : Array[Bytes]
    file_name : String
    sequence : Int
    stamp_low : Int
    stamp_high : Int
    }

    A tree of keys and values that build() turns into a REGF hive.

    Nodes are addressed by index; node 0 is the root key.

    HiveBuilder::add_key

    fn HiveBuilder::add_key(self : HiveBuilder, parent : Int, name : String) -> Int

    Adds a child key under parent and returns its index.

    HiveBuilder::build

    fn HiveBuilder::build(self : HiveBuilder) -> Result[Bytes, RegfError]

    Serializes the tree into a REGF hive file.

    The layout is the one Windows uses: a 4096-byte base block, then one or more hive bins whose cells carry the nk, vk and lf records. Key names must be ASCII and a value payload must fit in one data cell (16344 bytes).

    HiveBuilder::child_index

    fn HiveBuilder::child_index(self : HiveBuilder, parent : Int, name : String) -> Int?

    Index of the child of parent whose name matches exactly, if any.

    HiveBuilder::key_count

    fn HiveBuilder::key_count(self : HiveBuilder) -> Int

    Number of keys in the tree.

    HiveBuilder::new

    Creates a builder holding a single root key called ROOT.

    HiveBuilder::new_named

    fn HiveBuilder::new_named(root_name : String) -> HiveBuilder

    Creates a builder whose root key uses root_name.

    HiveBuilder::set_class_name

    fn HiveBuilder::set_class_name(self : HiveBuilder, key_index : Int, bytes : Bytes) -> Unit

    Attaches a class name to a key. The bytes are stored as is, in UTF-16LE.

    HiveBuilder::set_dword

    fn HiveBuilder::set_dword(self : HiveBuilder, key_index : Int, name : String, value : Int) -> Unit

    Stores a REG_DWORD value.

    HiveBuilder::set_file_name

    fn HiveBuilder::set_file_name(self : HiveBuilder, text : String) -> Unit

    Overrides the file name written into the base block.

    HiveBuilder::set_header_metadata

    fn HiveBuilder::set_header_metadata(self : HiveBuilder, sequence : Int, stamp_low : Int, stamp_high : Int) -> Unit

    Overrides the sequence numbers and the write timestamp of the base block.

    HiveBuilder::set_index_kind

    fn HiveBuilder::set_index_kind(self : HiveBuilder, key_index : Int, kind : IndexKind) -> Unit

    Forces the index kind of one key instead of letting build() choose.

    HiveBuilder::set_key_metadata

    fn HiveBuilder::set_key_metadata(self : HiveBuilder, key_index : Int, high : UInt, low : UInt, access : UInt, extra_flags : UInt) -> Unit

    Copies the metadata of an existing key: the two halves of its last write timestamp, its access bits and any nk flag bit the caller wants kept.

    HiveBuilder::set_security

    fn HiveBuilder::set_security(self : HiveBuilder, key_index : Int, descriptor : Bytes) -> Unit

    Attaches a self-relative security descriptor to a key.

    The bytes become the payload of an sk record. Pass the output of security_descriptor_with_owner_group() when only an owner and a group are needed.

    HiveBuilder::set_string

    fn HiveBuilder::set_string(self : HiveBuilder, key_index : Int, name : String, text : String) -> Unit

    Stores a REG_SZ value holding text.

    HiveBuilder::set_value

    fn HiveBuilder::set_value(self : HiveBuilder, key_index : Int, name : String, data_type : HiveValueType, data : Bytes) -> Unit

    Stores one value under the key at key_index.

    HiveCell

    pub(all) struct HiveCell {
    offset : UInt
    payload_size : Int
    allocated : Bool
    }

    A cell inside the hive bins region.

    A cell starts with a signed 32-bit size that covers the size field itself: negative sizes mark allocated cells, positive sizes mark free cells.

    HiveEditor

    pub struct HiveEditor {
    keys : Array[EditableKey]
    file_name : String
    sequence : Int
    stamp_low : Int
    stamp_high : Int
    skipped_values : Int
    skipped_subkey_lists : Int
    }

    A hive loaded into memory so that it can be modified and written back.

    HiveEditor::add_key

    fn HiveEditor::add_key(self : HiveEditor, parent : Int, name : String) -> Int

    Adds a child key and returns its index.

    HiveEditor::build

    fn HiveEditor::build(self : HiveEditor) -> Result[Bytes, RegfError]

    Writes the edited tree back into hive bytes.

    HiveEditor::delete_key

    fn HiveEditor::delete_key(self : HiveEditor, index : Int) -> Bool

    Removes a key together with everything below it.

    HiveEditor::delete_value

    fn HiveEditor::delete_value(self : HiveEditor, key : Int, name : String) -> Bool

    Removes a value by name, reporting whether it existed.

    HiveEditor::find

    fn HiveEditor::find(self : HiveEditor, path : String) -> Int?

    Finds a key by a path such as ROOT/Software/Vendor.

    HiveEditor::is_lossless

    fn HiveEditor::is_lossless(self : HiveEditor) -> Bool

    True when nothing had to be skipped, so a rebuild keeps every record.

    HiveEditor::key_count

    fn HiveEditor::key_count(self : HiveEditor) -> Int

    Number of keys in the tree.

    HiveEditor::key_name

    fn HiveEditor::key_name(self : HiveEditor, index : Int) -> String

    Name of the key at index.

    HiveEditor::open

    fn HiveEditor::open(bytes : Bytes) -> Result[HiveEditor, RegfError]

    Loads every key, value and metadata field of a hive into memory.

    Records that cannot be parsed are counted, not dropped silently: read skipped_values() and skipped_subkey_lists(), or call open_strict().

    HiveEditor::open_strict

    fn HiveEditor::open_strict(bytes : Bytes) -> Result[HiveEditor, RegfError]

    Loads a hive but refuses one that a rebuild would write back incomplete.

    HiveEditor::set_dword

    fn HiveEditor::set_dword(self : HiveEditor, key : Int, name : String, value : Int) -> Unit

    Stores a REG_DWORD value.

    HiveEditor::set_string

    fn HiveEditor::set_string(self : HiveEditor, key : Int, name : String, text : String) -> Unit

    Stores a REG_SZ value holding text as UTF-16LE with a terminating NUL.

    HiveEditor::set_value

    fn HiveEditor::set_value(self : HiveEditor, key : Int, name : String, data_type : HiveValueType, data : Bytes) -> Unit

    Replaces a value by name, or appends it when the name is new.

    HiveEditor::skipped_subkey_lists

    fn HiveEditor::skipped_subkey_lists(self : HiveEditor) -> Int

    Number of subkey records that could not be parsed while loading.

    HiveEditor::skipped_values

    fn HiveEditor::skipped_values(self : HiveEditor) -> Int

    Number of values that could not be parsed while the hive was loaded.

    HiveEditor::to_builder

    fn HiveEditor::to_builder(self : HiveEditor) -> HiveBuilder

    Builds a writer that reproduces this tree, including its metadata.

    HiveFileType

    pub(all) enum HiveFileType {
    Primary
    Log
    External
    Unknown(UInt)
    }

    Kind of file recorded in the base block.

    HiveFileType::label

    fn HiveFileType::label(self : HiveFileType) -> String

    Short label for a hive file type.

    HiveHeader

    pub(all) struct HiveHeader {
    primary_sequence : UInt
    secondary_sequence : UInt
    last_written_high : UInt
    last_written_low : UInt
    major_version : UInt
    minor_version : UInt
    file_type : HiveFileType
    file_format : UInt
    root_cell_offset : UInt
    hive_bins_data_size : UInt
    clustering_factor : UInt
    file_name : String
    checksum : UInt
    }

    Parsed REGF base block (the 4096 bytes at the start of a hive file).

    HiveHeader::version_supported

    fn HiveHeader::version_supported(self : HiveHeader) -> Bool

    True when the base block declares a major.minor this library reads.

    Windows has shipped 1.3, 1.5 and 1.6; the record layouts this library understands are the ones those versions use.

    HiveKeyEntry

    pub(all) struct HiveKeyEntry {
    path : String
    offset : UInt
    subkey_count : Int
    value_count : Int
    }

    One entry of a flattened key tree.

    HiveKeyNode

    pub(all) struct HiveKeyNode {
    offset : UInt
    flags : UInt
    last_written_high : UInt
    last_written_low : UInt
    access_bits : UInt
    parent_offset : UInt
    subkey_count : UInt
    volatile_subkey_count : UInt
    subkey_list_offset : UInt
    volatile_subkey_list_offset : UInt
    value_count : UInt
    value_list_offset : UInt
    security_offset : UInt
    class_name_offset : UInt
    name_length : UInt
    class_name_length : UInt
    name : String
    }

    A key node (nk) record: one registry key and the offsets of its children.

    HiveSubkeyList

    pub(all) struct HiveSubkeyList {
    offset : UInt
    kind : SubkeyListKind
    count : Int
    key_offsets : Array[UInt]
    }

    A subkey list record: the direct children of one key.

    For root index (ri) records the child offsets of the nested lists are flattened, so key_offsets always holds key node offsets in stored order.

    HiveValue

    pub(all) struct HiveValue {
    offset : UInt
    name : String
    data_type : HiveValueType
    data_size : UInt
    data_offset : UInt
    inline_data : Bool
    data : Bytes
    }

    A registry value (vk record) together with its resolved data.

    inline_data is true when the four bytes of data_offset hold the data itself, which Windows does for payloads of at most four bytes.

    HiveValue::as_multi_string

    fn HiveValue::as_multi_string(self : HiveValue) -> Array[String]?

    Splits the data of a REG_MULTI_SZ value into its NUL separated entries.

    HiveValue::as_string

    fn HiveValue::as_string(self : HiveValue) -> String?

    Decodes the data of a string typed value; the trailing NUL is dropped.

    HiveValue::as_u32

    fn HiveValue::as_u32(self : HiveValue) -> UInt?

    Interprets the data as a 32-bit integer when it holds at least four bytes.

    HiveValueType

    pub(all) enum HiveValueType {
    Nil
    Sz
    ExpandSz
    Binary
    Dword
    DwordBigEndian
    Link
    MultiSz
    ResourceList
    FullResourceDescriptor
    ResourceRequirementsList
    Qword
    Unknown(UInt)
    }

    Kind of data stored in a registry value.

    HiveValueType::from_code

    fn HiveValueType::from_code(code : UInt) -> HiveValueType

    Maps the numeric type code stored in a vk record to a value type.

    HiveValueType::label

    fn HiveValueType::label(self : HiveValueType) -> String

    Registry type name such as REG_SZ, as used by regedit and .reg files.

    IndexKind

    pub(all) enum IndexKind {
    Auto
    FastLeaf
    HashLeaf
    IndexLeaf
    RootIndex
    }

    How the writer serializes a key subkey index.

    LogEntry

    pub(all) struct LogEntry {
    sequence : UInt
    bins_data_size : UInt
    size : Int
    pages : Array[LogPageRef]
    data : Bytes
    }

    One transaction log entry: dirty page references plus their bytes.

    LogFile

    pub(all) struct LogFile {
    primary_sequence : UInt
    secondary_sequence : UInt
    entries : Array[LogEntry]
    }

    A parsed transaction log file.

    LogFile::entry_count

    fn LogFile::entry_count(self : LogFile) -> Int

    Number of entries in the log.

    LogFile::page_count

    fn LogFile::page_count(self : LogFile) -> Int

    Total number of dirty pages across every entry.

    LogPageRef

    pub(all) struct LogPageRef {
    offset : UInt
    size : Int
    }

    One dirty page reference inside a log entry.

    LogReplay

    pub(all) struct LogReplay {
    bytes : Bytes
    applied : Int
    final_sequence : UInt
    }

    Outcome of replaying a log onto a hive.

    OrphanRecord

    pub(all) struct OrphanRecord {
    offset : Int
    signature : String
    name : String
    deleted : Bool
    }

    One record found inside the bins that the live key tree cannot reach.

    RegFile

    pub(all) struct RegFile {
    sections : Array[RegSection]
    }

    A parsed .reg document.

    RegFile::section_count

    fn RegFile::section_count(self : RegFile) -> Int

    Number of sections in the document.

    RegFile::to_builder

    fn RegFile::to_builder(self : RegFile) -> Result[HiveBuilder, RegfError]

    Builds a hive from the document.

    The first path segment of each section (the predefined root such as HKEY_CURRENT_USER) is dropped, so the remaining path hangs off the hive root key. Delete sections are reported instead of being dropped silently.

    RegFile::value_count

    fn RegFile::value_count(self : RegFile) -> Int

    Number of values across all sections.

    RegSection

    pub(all) struct RegSection {
    path : String
    delete : Bool
    values : Array[RegValue]
    }

    One [path] section of a .reg file.

    RegValue

    pub(all) struct RegValue {
    name : String
    data_type : HiveValueType
    data : Bytes
    }

    One value read from a .reg file.

    RegfError

    pub(all) enum RegfError {
    TooShort(Int)
    BadSignature(String)
    BadChecksum(UInt, UInt)
    BadCellOffset(Int)
    BadCellSize(Int)
    BadKeyNode(Int)
    BadSubkeyList(Int)
    BadValue(Int)
    BadValueData(Int)
    UnsupportedName(Int)
    ValueTooLarge(Int)
    BadRegFile(String)
    UnsupportedDelete(String)
    NotALogFile(UInt)
    UnsupportedLogVersion(UInt)
    BadLogEntry(Int)
    BadLogPage(Int)
    BadSecurityDescriptor(String)
    LossyHive(Int, Int)
    }

    Errors reported while parsing, building or replaying a REGF hive file.

    RegfError::message

    fn RegfError::message(self : RegfError) -> String

    Human readable message for an error value.

    SecurityDescriptor

    pub(all) struct SecurityDescriptor {
    revision : Int
    control : Int
    owner : String
    group : String
    has_sacl : Bool
    has_dacl : Bool
    dacl : Array[Ace]
    }

    A parsed self-relative security descriptor.

    SubkeyListKind

    pub(all) enum SubkeyListKind {
    FastLeaf
    HashLeaf
    IndexLeaf
    RootIndex
    Unknown(String)
    }

    Kind of subkey list record stored in a hive.

    SubkeyListKind::label

    fn SubkeyListKind::label(self : SubkeyListKind) -> String

    Short label for a subkey list kind.

    apply_log

    fn apply_log(hive : Bytes, log : Bytes) -> Result[Bytes, RegfError]

    Replays a log and returns only the patched hive bytes.

    decode_single_byte

    fn decode_single_byte(bytes : Bytes, offset : Int, count : Int) -> String

    Decodes count single-byte characters starting at byte offset.

    REGF stores compressed key names as one byte per character. Bytes are decoded as UTF-8 with replacement so ASCII names round-trip exactly and stray high bytes stay readable.

    decode_utf16le

    fn decode_utf16le(bytes : Bytes, offset : Int, unit_count : Int) -> String

    Decodes unit_count UTF-16LE code units starting at byte offset.

    Decoding stops at the first NUL code unit, matching how REGF stores the fixed-width base block file name. Unpaired surrogates become U+FFFD so the result is always valid UTF-8.

    describe_security

    fn describe_security(bytes : Bytes, key : HiveKeyNode) -> Result[SecurityDescriptor, RegfError]

    Reads the sk record a key points at and parses its descriptor.

    encode_utf16le

    fn encode_utf16le(text : String) -> Bytes

    Encodes text as UTF-16LE code units.

    export_reg_text

    fn export_reg_text(bytes : Bytes, root_path : String) -> Result[String, RegfError]

    Renders a hive as .reg text.

    Every section path is root_path followed by the key path below the hive root key, so a hive whose root holds Environment renders as [HKEY_CURRENT_USER\Environment] when root_path is HKEY_CURRENT_USER.

    list_subkeys

    fn list_subkeys(bytes : Bytes, key : HiveKeyNode) -> Result[Array[HiveKeyNode], RegfError]

    Reads the direct children of a key.

    This is the strict view: any unreadable child record fails the whole call.

    list_values

    fn list_values(bytes : Bytes, key : HiveKeyNode) -> Result[Array[HiveValue], RegfError]

    Reads the values of a key in stored order.

    This is the strict view: any unreadable value fails the whole call.

    parse_acl

    fn parse_acl(bytes : Bytes, offset : Int) -> Result[Array[Ace], RegfError]

    Parses the ACL stored at offset: revision, size, entry count, then the entries. Object entries carry one or two GUIDs before their SID, which the object flags announce; anything that does not fit stops the walk instead of inventing an entry.

    parse_header

    fn parse_header(bytes : Bytes) -> Result[HiveHeader, RegfError]

    Parses the base block of a hive file.

    parse_key_node

    fn parse_key_node(bytes : Bytes, offset : UInt) -> Result[HiveKeyNode, RegfError]

    Parses the key node stored in the cell at offset.

    parse_log

    fn parse_log(bytes : Bytes) -> Result[LogFile, RegfError]

    Parses a transaction log file.

    Windows 8.1 and newer write a REGF base block with file type 6 followed by HvLE entries on 512-byte boundaries; the parser only accepts that layout and reports older formats as UnsupportedLogVersion instead of guessing.

    parse_reg_bytes

    fn parse_reg_bytes(raw : Bytes) -> Result[RegFile, RegfError]

    Parses .reg text from raw file bytes, honouring UTF-16LE and UTF-8 byte order marks.

    parse_reg_file

    fn parse_reg_file(text : String) -> Result[RegFile, RegfError]

    Parses .reg text into sections and values.

    parse_security_descriptor

    fn parse_security_descriptor(bytes : Bytes, offset : Int) -> Result[SecurityDescriptor, RegfError]

    Parses the self-relative security descriptor stored at offset.

    parse_value

    fn parse_value(bytes : Bytes, offset : UInt) -> Result[HiveValue, RegfError]

    Parses the value record stored in the cell at offset and resolves its data.

    read_cell

    fn read_cell(bytes : Bytes, offset : UInt) -> Result[HiveCell, RegfError]

    Reads the cell header at offset, which is relative to the bins region.

    read_subkey_list

    fn read_subkey_list(bytes : Bytes, offset : UInt) -> Result[HiveSubkeyList, RegfError]

    Reads the subkey list stored at offset, expanding nested ri records.

    read_u16_le

    fn read_u16_le(bytes : Bytes, offset : Int) -> UInt

    Reads a little-endian 16-bit unsigned integer at offset.

    The caller must guarantee that offset + 2 is within bounds.

    read_u32_le

    fn read_u32_le(bytes : Bytes, offset : Int) -> UInt

    Reads a little-endian 32-bit unsigned integer at offset.

    The caller must guarantee that offset + 4 is within bounds.

    read_value_list

    fn read_value_list(bytes : Bytes, offset : UInt) -> Result[Array[UInt], RegfError]

    Reads the value list stored in the cell at offset.

    A value list cell is a plain array of 32-bit vk offsets; it carries no signature of its own.

    replay_log

    fn replay_log(hive : Bytes, log : Bytes) -> Result[LogReplay, RegfError]

    Replays a transaction log onto a copy of a hive.

    Entries are applied in stored order and only when their sequence is newer than the secondary sequence of the hive, so replaying a stale log leaves the hive untouched. Dirty page offsets are relative to the hive bins data, and the base block sequence numbers plus checksum are rewritten after the last applied entry.

    scan_orphan_records

    fn scan_orphan_records(bytes : Bytes) -> Result[Array[OrphanRecord], RegfError]

    Walks every allocated cell and reports the nk and del records that the live tree does not reach.

    Cells are walked from the first cell after each bin header: a bin starts with a 32 byte hbin header, so the very first 32 bytes of every 4096 byte bin are skipped instead of being read as a cell size.

    security_bytes_of

    fn security_bytes_of(bytes : Bytes, key : HiveKeyNode) -> Bytes

    Returns the raw self-relative descriptor a key points at, or empty bytes.

    security_descriptor_with_owner_group

    fn security_descriptor_with_owner_group(owner : String, group : String) -> Result[Bytes, RegfError]

    Builds a self-relative descriptor that only carries an owner and a group.

    sid_from_string

    fn sid_from_string(text : String) -> Result[Bytes, RegfError]

    Turns a SID string such as S-1-5-18 into its binary form.

    The binary form is one revision byte, one sub authority count byte, a six byte big-endian identifier authority and the sub authorities as u32 LE.

    sid_to_string

    fn sid_to_string(bytes : Bytes, offset : Int) -> String

    Renders the binary SID at offset as S-1-5-... form.

    value_offsets

    fn value_offsets(bytes : Bytes, key : HiveKeyNode) -> Result[Array[UInt], RegfError]

    Reads the vk offsets listed by a key, without parsing the values.

    The lenient counterpart of list_values: callers that must survive hives referencing volatile or freed cells can parse each offset on their own.

    walk_key_tree

    fn walk_key_tree(bytes : Bytes, root_offset : UInt, max_depth : Int) -> Array[HiveKeyEntry]

    Walks the key tree rooted at root_offset, descending max_depth levels.

    The lenient view used for offline hives: children whose records cannot be parsed are skipped, because hives can reference volatile or freed cells that are absent from the file on disk.