#!/usr/bin/perl # # PBCDEDIT - Copyright 2019 Marc A. Lehmann # # SPDX-License-Identifier: GPL-3.0-or-later # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program. If not, see . # use 5.016; # numerous features need 5.14, __SUB__ needs 5.16 our $VERSION = '1.5'; our $JSON_VERSION = 3; # the version of the json objects generated by this program our $CHANGELOG = <,element,path' \ set '{default}' osdevice 'locate=,element,path' =head1 DESCRIPTION This program allows you to create, read and modify Boot Configuration Data (BCD) stores used by Windows Vista and newer versions of Windows. At this point, it is in relatively early stages of development and has received little to no real-world testing. Compared to other BCD editing programs it offers the following unique features: =over =item Can create BCD hives from scratch Practically all other BCD editing programs force you to copy existing BCD stores, which might or might not be copyrighted by Microsoft. =item Does not rely on Windows As the "portable" in the name implies, this program does not rely on C or other windows programs or libraries, it works on any system that supports at least perl version 5.16. =item Decodes and encodes BCD device elements PBCDEDIT can concisely decode and encode BCD device element contents. This is pretty unique, and offers a lot of potential that can't be realised with C or any programs relying on it. =item Minimal files BCD files written by PBCDEDIT are always "minimal", that is, they don't contain unused data areas and therefore don't contain old and potentially sensitive data. =back The target audience for this program is professionals and tinkerers who are ready to invest time into learning how it works. It is not an easy program to use and requires patience and a good understanding of BCD stores. =head1 SUBCOMMANDS PBCDEDIT expects a subcommand as first argument that tells it what to do. The following subcommands exist: =over =item C Displays the whole manual page (this document). =item C This outputs the PBCDEDIT version, the JSON schema version it uses and the full log of changes. =item C F Reads a BCD data store and writes a JSON representation of it to standard output. The format of the data is explained later in this document. Example: read a BCD store, modify it with an external program, write it again. pbcdedit export BCD | modify-json-somehow | pbcdedit import BCD =item C F The reverse of C: Reads a JSON representation of a BCD data store from standard input, and creates or replaces the given BCD data store. =item C F I Load a BCD data store, apply some instructions to it, and save it again. See the section L, below, for more info. =item C F I Same as C, above, except it doesn't save the data store again. Can be useful to extract some data from it. =item C F I Same as C, above, except it creates a new data store from scratch if needed. An existing store will be emptied completely. =item C [C<--json>] On a GNU/Linux system, you can get a list of partition device descriptors using this command - the external C command is required, as well as a mounted C file system. The output will be a list of all partitions in the system and C descriptors for GPT and both C and C descriptors for MBR partitions. With C<--json> it will print similar information as C, but with extra C and C attributes. =item C F Tries to find the BCD device element for the given device, which currently must be a a partition of some kind. Prints the C descriptor as a result, or nothing. Exit status will be true on success, and false on failure. Like C, above, this likely only works on GNU/Linux systems. Example: print the partition descriptor of tghe partition with label DATA. $ pbcdedit bcd-device /dev/disk/by-label/DATA partition=,harddisk,mbr,47cbc08a,213579202560 =item C F Like above, but uses a C descriptor instead. =item C [C<--json>] Outputs two tables: a table listing all type aliases with their hex BCD element ID, and all object name aliases with their GUID and default type (if any). With C<--json> it prints similar information as a JSON object, for easier parsing. =item C [C<--json>] Outputs a table of known element aliases with their hex ID and the format type. With C<--json> it prints similar information as a JSON object, for easier parsing. =item C F This has nothing to do with BCD stores, but simply exposes PCBEDIT's internal registry hive reader - it takes a registry hive file as argument and outputs a JSON representation of it to standard output. Hive versions 1.2 till 1.6 are supported. =item C F The reverse of C: reads a JSON representation of a registry hive from standard input and creates or replaces the registry hive file given as argument. The written hive will always be in a slightly modified version 1.3 format. It's not the format windows would generate, but it should be understood by any conformant hive reader. Note that the representation chosen by PBCDEDIT currently throws away classname data (often used for feeble attempts at hiding stuff by Microsoft) and security descriptors, so if you write anything other than a BCD hive you will most likely destroy it. =back =head1 BCD STORE REPRESENTATION FORMAT A BCD data store is represented as a JSON object with one special key, C, and one key per BCD object. That is, each BCD object becomes one key-value pair in the object, and an additional key called C contains meta information. Here is an abridged example of a real BCD store: { "meta" : { "version" : 1 }, "{7ae02178-821d-11e7-8813-1c872c5f5ab0}" : { "type" : "application::osloader", "description" : "Windows 10", "device" : "partition=,harddisk,gpt,9742e468-9206-48a0-b4e4-c4e9745a356a,3ce6aceb-e90c-4fd2-9fba-47cab15f6faf", "osdevice" : "partition=,harddisk,gpt,9742e468-9206-48a0-b4e4-c4e9745a356a,3ce6aceb-e90c-4fd2-9fba-47cab15f6faf", "path" : "\\Windows\\system32\\winload.exe", "systemroot" : "\\Windows" }, "{bootloadersettings}" : { "inherit" : "{globalsettings} {hypervisorsettings}" }, "{bootmgr}" : { "description" : "Windows Boot Manager", "device" : "partition=,harddisk,mbr,ff3ba63b,1048576", "displayorder" : "{7ae02178-821d-11e7-8813-1c872c5f5ab0}", "inherit" : "{globalsettings}", "displaybootmenu" : 0, "timeout" : 30 }, "{globalsettings}" : { "inherit" : "{dbgsettings} {emssettings} {badmemory}" }, "{hypervisorsettings}" : { "hypervisorbaudrate" : 115200, "hypervisordebugport" : 1, "hypervisordebugtype" : 0 }, # ... } =head2 Minimal BCD to boot windows Experimentally I found the following BCD is the minimum required to successfully boot any post-XP version of Windows (assuming suitable C and C values, of course, and assuming a BIOS boot - for UEFI, you should use F instead of F): { "{bootmgr}" : { "default" : "{45b547a7-8ca6-4417-9eb0-a257b61f35b4}" }, "{45b547a7-8ca6-4417-9eb0-a257b61f35b1}" : { "type" : "application::osloader", "description" : "Windows Boot", "device" : "legacypartition=,harddisk,mbr,47cbc08a,1", "osdevice" : "legacypartition=,harddisk,mbr,47cbc08a,1", "path" : "\\Windows\\system32\\winload.exe", "systemroot" : "\\Windows" }, } Note that minimal doesn't mean recommended - Windows itself will add stuff to this during or after boot, and you might or might not run into issues when installing updates as it might not be able to find the F. This is how you would create a minimal hive with PBCDEDIT from within GNU/Linux, assuming F is the windows partition, using a random GUID for the osloader and using C instead of C: osldr="{$(uuidgen)}" part=$(pbcdedit bcd-device /dev/sdc3) pbcdedit create minimal.bcd \ set '{bootmgr}' default "$osldr" \ set "$osldr" type application::osloader \ set "$osldr" description 'Windows Boot' \ set "$osldr" device "$part" \ set "$osldr" osdevice "$part" \ set "$osldr" path '\Windows\system32\winload.exe' \ set "$osldr" systemroot '\Windows' =head2 The C key The C key is not stored in the BCD data store but is used only by PBCDEDIT. It is always generated when exporting, and importing will be refused when it exists and the version stored inside doesn't match the JSON schema version of PBCDEDIT. This ensures that different and incompatible versions of PBCDEDIT will not read and misinterpret each others data. =head2 The object keys Every other key is a BCD object. There is usually a BCD object for the boot manager, one for every boot option and a few others that store common settings inherited by these. Each BCD object is represented by a GUID wrapped in curly braces. These are usually random GUIDs used only to distinguish BCD objects from each other. When adding a new boot option, you can simply generate a new GUID. Some of these GUIDs are fixed well known GUIDs which PBCDEDIT will decode into human-readable strings such as C<{globalsettings}>, which is the same as C<{7ea2e1ac-2e61-4728-aaa3-896d9d0a9f0e}>. Each BCD object has an associated type. For example, C for objects loading Windows via F, C for real mode applications and so on. The type of a object is stored in the pseudo BCD element C (see next section). Some well-known objects have a default type. If an object type matches its default type, then the C element will be omitted. Similarly, if the C element is missing and the BCD object has a default type, the default type will be used when writing a BCD store. Running F will give you a list of object types, well-known object aliases and their default types. If different string keys in a JSON BCD store map to the same BCD object then a random one will "win" and the others will be discarded. To avoid this, you should always use the "canonical" name of a BCD object, which is the human-readable form (if it exists). =head2 The object values - BCD elements The value of each BCD object entry consists of key-value pairs called BCD elements. BCD elements are identified by a 32 bit number, but to make things simpler PBCDEDIT will replace these with well-known strings such as C, C or C. When PBCDEDIT does not know the BCD element, it will use C, where C is the 8-digit hex number of the BCD element. For example, C would be C. You can get a list of all BCD elements known to PBCDEDIT by running F. What was said about duplicate keys mapping to the same object is true for elements as well, so, again, you should always use the canonical name, which is the human readable alias, if known. =head3 BCD element types Each BCD element has a type such as I or I. This type determines how the value is interpreted, and most of them are pretty easy to explain: =over =item string This is simply a unicode string. For example, the C and C elements both are of this type, one storing a human-readable name for this boot option, the other a file path to the windows root directory: "description" : "Windows 10", "systemroot" : "\\Windows", =item boolean Almost as simple are booleans, which represent I/I, I/I and similar values. In the JSON form, true is represented by the number C<1>, and false is represented by the number C<0>. Other values will be accepted, but PBCDEDIT doesn't guarantee how these are interpreted. For example, C is a boolean that decides whether to enable the C boot menu. In the example BCD store above, this is disabled: "displaybootmenu" : 0, =item integer Again, very simple, this is a 64 bit integer. It can be either specified as a decimal number, as a hex number (by prefixing it with C<0x>) or as a binary number (prefix C<0b>). For example, the boot C is an integer, specifying the automatic boot delay in seconds: "timeout" : 30, =item integer list This is a list of 64 bit integers separated by whitespace. It is not used much, so here is a somewhat artificial and untested example of using C to specify a certain custom, eh, action to be executed when pressing C at boot: "customactions" : "0x1000044000001 0x54000001", =item guid This represents a single GUID value wrapped in curly braces. It is used a lot to refer from one BCD object to other one. For example, The C<{bootmgr}> object might refer to a resume boot option using C: "default" : "{7ae02178-821d-11e7-8813-1c872c5f5ab0}", Human readable aliases are used and allowed. =item guid list Similar to the GUID type, this represents a list of such GUIDs, separated by whitespace from each other. For example, many BCD objects can I elements from other BCD objects by specifying the GUIDs of those other objects in a GUID list called surprisingly called C: "inherit" : "{dbgsettings} {emssettings} {badmemory}", This example also shows how human readable aliases can be used. =item device This type is why I write I are easy to explain earlier: This type is the pinnacle of Microsoft-typical hacks layered on top of other hacks. Understanding this type took more time than writing all the rest of PBCDEDIT, and because it is so complex, this type has its own subsection below. =back =head3 The BCD "device" element type Device elements specify, well, devices. They are used for such diverse purposes such as finding a TFTP network boot image, serial ports or VMBUS devices, but most commonly they are used to specify the disk (harddisk, cdrom, ramdisk, vhd...) to boot from. The device element is kind of a mini-language in its own which is much more versatile then the limited windows interface to it - BCDEDIT - reveals. While some information can be found on the BCD store and the windows registry, there is pretty much no public information about the device element, so almost everything known about it had to be researched first in the process of writing this script, and consequently, support for BCD device elements is partial only. On the other hand, the expressive power of PBCDEDIT in specifying devices is much greater than BCDEDIT and therefore more can be done with it. The downside is that BCD device elements are much more complicated than what you might think from reading the BCDEDIT documentation. In other words, simple things are complicated, and complicated things are possible. Anyway, the general syntax of device elements is an optional GUID, followed by a device type, optionally followed by hexadecimal flags in angle brackets, optionally followed by C<=> and a comma-separated list of arguments, some of which can be (and often are) in turn devices again. [{GUID}]type[][=arg,arg...] Here are some examples: boot {b097d29f-bc00-11e9-8a9a-525400123456}block=file,,\EFI locate=,element,systemroot partition=,harddisk,mbr,47cbc08a,1048576 partition=,harddisk,gpt,9742e468-9206-48a0-b4e4-c4e9745a356a,76d39e5f-ad1b-407e-9c05-c81eb83b57dd block<1>=ramdisk,,harddisk,mbr,47cbc08a,68720525312>,0,0,0,\Recovery\b097d29e-bc00-11e9-8a9a-525400123456\Winre.wim block=file,,harddisk,gpt,9742e468-9206-48a0-b4e4-c4e9745a356a,ee3a393a-f0de-4057-9946-88584245ed48>,\ binary=050000000000000048000000000000000000000000000000000000000000000000000000000000000 I hope you are suitably impressed. I was, too, when I realized decoding these binary blobs is not as easy as I had assumed. The optional prefixed GUID seems to refer to a device BCD object, which can be used to specify more device-specific BCD elements (for example C and C). The flags after the type are omitted when they are C<0>. The only known flag is C<1>, which seems to indicate that the parent device is invalid. I don't claim to fully understand it, but it seems to indicate that the boot manager has to search the device itself. Why the device is specified in the first place escapes me, but a lot of this device stuff seems to be badly hacked together... The types understood and used by PBCDEDIT are as follows (keep in mind that not of all the following is necessarily supported in PBCDEDIT): =over =item CI This type isn't actually a real BCD element type, but a fallback for those cases where PBCDEDIT can't perfectly decode a device element (except for the leading GUID, which it can always decode). In such cases, it will convert the device into this type with a hexdump of the element data. =item C This is another special type - sometimes, a device is all zero-filled, which is not valid. This can mark the absence of a device or something PBCDEDIT does not understand, so it decodes it into this special "all zero" type called C. It's most commonly found in devices that can use an optional parent device, when no parent device is used. =item C Another type without parameters, this refers to the device that was booted from (nowadays typically the EFI system partition). =item CI,I This specifies a VMBUS device with the given interface type and interface instance, both of which are "naked" (no curly braces) GUIDs. Made-up example (couldn't find a single example on the web): vmbus=c376c1c3-d276-48d2-90a9-c04748072c60,12345678-a234-b234-c234-d2345678abcd =item C>,I,I,I,I This designates a specific partition on a block device. I is an optional parent device on which to search on, and is often C. Note that the angle brackets around I are part of the syntax. I is one of C, C, C, C, C or C, where the first three should be self-explaining, C is usually used to locate a file to be used as a disk image, and C is used to treat files as virtual harddisks, i.e. F and F files. The I is either C, C or C, the latter being used for devices without partitions, such as cdroms, where the "partition" is usually the whole device. The I identifies the disk or device using a unique signature, and the same is true for the I. How these are interpreted depends on the I: =over =item C The C is the 32 bit disk signature stored at offset 0x1b8 in the MBR, interpreted as a 32 bit unsigned little endian integer and written as hex number. That is, the bytes C<01 02 03 04> would become C<04030201>. Diskpart (using the C command) and the C command typically found on GNU/Linux systems (using e.g. C) can display the I. The I is the byte offset(!) of the partition counting from the beginning of the MBR. Example, use the partition on the harddisk with I C<47cbc08a> starting at sector C<2048> (= 1048576 / 512). partition=,harddisk,mbr,47cbc08a,1048576 =item C The I is the disk GUID/disk identifier GUID from the partition table (as displayed e.g. by F), and the I is the partition unique GUID (displayed using e.g. the F F command). Example: use the partition C<76d39e5f-ad1b-407e-9c05-c81eb83b57dd> on GPT disk C<9742e468-9206-48a0-b4e4-c4e9745a356a>. partition=,harddisk,gpt,9742e468-9206-48a0-b4e4-c4e9745a356a,76d39e5f-ad1b-407e-9c05-c81eb83b57dd =item C Instead of I and I, this type only accepts a decimal disk number and signifies the whole disk. BCDEDIT cannot display the resulting device, and I am doubtful whether it has a useful effect. =back =item C>,I,I,I,I This is exactly the same as the C type, except for a tiny detail: instead of using the partition start offset, this type uses the partition number for MBR disks. Behaviour other partition types should be the same. The partition number starts at C<1> and skips unused partition, so if there are two primary partitions and another partition inside the extended partition, the primary partitions are number C<1> and C<2> and the partition inside the extended partition is number C<3>, regardless of any gaps. =item C>,I,I This device description will make the bootloader search for a partition with a given path. The I device is the device to search on (angle brackets are still part of the syntax!) If it is C, then C will search all disks it can find. I is either C or C, and merely distinguishes between two different ways to specify the path to search for: C uses an element ID (either as hex or as name) as I and C uses a relative path as I. Example: find any partition which has the F path in the root. locate=,path,\magicfile.xxx Example: find any partition which has the path specified in the C element (typically F<\Windows>). locate=,element,systemroot =item CI,I Last not least, the most complex type, C, which... specifies block devices (which could be inside a F file for example). I is one of C, C, C, C, C or C - the same as for C. The remaining arguments change depending on the I: =over =item C,>,I Interprets the I device (typically a partition) as a filesystem and specifies a file path inside. =item C,> Pretty much just changes the interpretation of I, which is usually a disk image (C) to be a F or F file. =item C,>,I,I,I,I Interprets the I device as RAM disk, using the (decimal) base address, byte size and byte offset inside a file specified by I. The numbers are usually all C<0> because they can be extracted from the RAM disk image or other parameters. This is most commonly used to boot C images. =item C,I Refers to a removable drive identified by a number. BCDEDIT cannot display the resulting device, and it is not clear what effect it will have. =item C,I Pretty much the same as C but for CD-ROMs. =item anything else Probably not yet implemented. Tell me of your needs... =back =back =head4 Examples This concludes the syntax overview for device elements, but probably leaves many questions open. I can't help with most of them, as I also have many questions, but I can walk you through some actual examples using more complex aspects. =over =item C<< locate=,path,\disk.vhdx>,\disk.vhdx>>,element,path >> Just like with C declarations, you best treat device descriptors as instructions to find your device and work your way from the inside out: locate=,path,\disk.vhdx First, the innermost device descriptor searches all partitions on the system for a file called F<\disk.vhdx>: block=file,,\disk.vhdx Next, this takes the device locate has found and finds a file called F<\disk.vhdx> on it. This is the same file locate was using, but that is only because we find the device using the same path as finding the disk image, so this is purely incidental, although quite common. Next, this file will be opened as a virtual disk: block=vhd, And finally, inside this disk, another C will look for a partition with a path as specified in the C element, which most likely will be F<\Windows\system32\winload.exe>: locate=,element,path As a result, this will boot the first Windows it finds on the first F disk image it can find anywhere. =item C<< locate=,harddisk,mbr,47cbc08a,242643632128>,\win10.vhdx>>,element,path >> Pretty much the same as the previous case, but with a bit of variance. First, look for a specific partition on an MBR-partitioned disk: partition=,harddisk,mbr,47cbc08a,242643632128 Then open the file F<\win10.vhdx> on that partition: block=file,,\win10.vhdx Then, again, the file is opened as a virtual disk image: block=vhd, And again the windows loader (or whatever is in C) will be searched: locate=,element,path =item C<< {b097d2b2-bc00-11e9-8a9a-525400123456}block<1>=ramdisk,,harddisk,mbr,47cbc08a,242643632128>,0,0,0,\boot.wim >> This is quite different. First, it starts with a GUID. This GUID belongs to a BCD object of type C, which has additional parameters: "{b097d2b2-bc00-11e9-8a9a-525400123456}" : { "type" : "device", "description" : "sdi file for ramdisk", "ramdisksdidevice" : "partition=,harddisk,mbr,47cbc08a,1048576", "ramdisksdipath" : "\boot.sdi" }, I will not go into many details, but this specifies a (presumably empty) template ramdisk image (F<\boot.sdi>) that is used to initialize the ramdisk. The F<\boot.wim> file is then extracted into it. As you can also see, this F<.sdi> file resides on a different C. Continuing, as always, from the inside out, first this device descriptor finds a specific partition: partition=,harddisk,mbr,47cbc08a,242643632128 And then specifies a C image on this partition: block<1>=ramdisk,,0,0,0,\boot.wim I don't know what the purpose of the C<< <1> >> flag value is, but it seems to be always there on this kind of entry. If you have some good examples to add here, feel free to mail me. =back =head1 EDITING BCD STORES The C and C subcommands allow you to read a BCD data store and modify it or extract data from it. This is done by executing a series of "editing instructions" which are explained here. =over =item C I