diff --git a/About/Historical-Legacy-Migration.md b/About/Historical-Legacy-Migration.md new file mode 100644 index 0000000..f90ed0e --- /dev/null +++ b/About/Historical-Legacy-Migration.md @@ -0,0 +1,108 @@ +--- +layout: default +title: Historical Legacy Migration +permalink: /Historical-Legacy-Migration +nav_order: 99 +parent: About +--- + + +
+ + Table of contents + + {: .text-delta } +1. TOC +{:toc} +
+ + +Historical Legacy Migration +=== + +**Note**: This page contains historical reference information and applies only to users upgrading from very old Heads firmware (pre-2024). All new installations should use current board configurations available from the [Prerequisites](/Prerequisites) page. + +**Warning**: Migration from pre-2024 firmware requires careful attention. Legacy boards were [officially deprecated in October 2024](https://github.com/linuxboot/heads/pull/1803). Use maximum caution when upgrading from very old firmware, as improper steps may result in a bricked device. + +Historical Background +--- + +Originally, Heads supported two types of board configurations: + +- **Legacy boards**: Produced incomplete ROM images that required specific flashing procedures and only worked with locked IFD/ME regions +- **Maximized boards**: Produced complete ROM images with neutered/deactivated ME and unlocked IFD, allowing full internal flashing + +Legacy boards were [officially deprecated in October 2024](https://github.com/linuxboot/heads/pull/1803), and all current boards now use the approach that was previously called "maximized." + +Identifying Very Old Firmware +--- + +If you are running very old Heads firmware: + +1. Boot into the Heads main menu +2. Check if the main screen title includes "Maximized" in the board name + - If it does NOT include "Maximized," you may be on very old firmware + - Examples of old firmware: `x220-legacy`, `x220`, `t430`, `x230-hotp` (without "Maximized") + - Current firmware: All board names are standardized and use modern architecture + +Migration Steps +--- + +1. Refer to the [Downloading documentation](/Downloading) for current board configurations +2. Follow the [upgrade verification steps](/Updating#verify-upgradeability-paths-of-the-firmware) in the Upgrading documentation +3. Ensure you have proper recovery equipment before proceeding + +**Important for Nitrokey Customers**: +If you are using a NitroPad X230 or T430 with firmware version **1.2 or earlier**, contact [Nitrokey support](https://support.nitrokey.com/) for their flashing service. See this [support thread](https://support.nitrokey.com/t/nitropad-t430-firmware-update-brick/3777/2) for details. + +Technical Details (Historical) +--- + +The historical approach involved: + +- **ME neutering/deactivation**: For older Intel platforms (up to Ivy Bridge), reducing the Intel Management Engine to only essential components (BUP and ROMP for xx30 family, BUP only for xx20). For newer platforms, ME is deactivated using HAP bits or other methods +- **IFD unlocking**: Allowing the Intel Flash Descriptor regions to be modified +- **Space optimization**: Reclaiming freed ME space for the BIOS region (expanding from ~7MB to ~11.5MB on x230 family) + +This approach is now standard for all Heads boards, adapted to each platform's capabilities. + +Legacy Board Details (Historical Reference) +--- + +### Legacy Board Types (Deprecated) + +**xx30-flash**: 4MB ROM images to be flashed internally through 1vyrain or Skulls. Unlocking IFD and cleaning/neutering ME still highly recommended prior of doing initial flash. 1vyrain deactivates ME internally. But if one leaves 1vyrain and chooses another ROM, 1vyrain applied hacks to deactivate ME will not be applied anymore. Note that Skulls permits to unlock IFD as an option prior of initial flash. So if it was not applied at that step, then the end user can only upgrade to Legacy boards produced ROMs in the future, the IFD and ME not being flashable internally and requiring an external flash to go with Maximized boards. + +**xx30**: Baked 12MB ROM images to be flashed internally through xxxx-flash flashed ROMs. Those ROMs can only be internally flashed from/to legacy boards configuration. Flashing a legacy ROM from a Maximized ROM will result in a brick, since Maximized boards produced ROMs will flash the whole combined opaque 12MB ROM internally, overwriting IFD, ME and GBE with empty content. Resulting into a brick. + +**xx20**: Those ports (t420 and x220 at time of writing) landed on Heads later in time and were historically produced by making required blobs available by applying scripts on SPI backups to extract required blobs. Consequently, those boards do not suffer from feature reduction as of now; they always took for granted that ME was neutered and IFD was unlocked. They still only flash internally the BIOS region, which was maximized to take advantage of 7.5MB available SPI space for BIOS region, while not reflashing the whole SPI. + +**xxxx-hotp-verification**: Legacy, reduced versions of their HOTP maximized counterpart. At the time of writing this, those board configuration will normally loose dropbear support, while xx30 versions will not have FBWhiptail anymore. That means that there is no framebuffer enforced graphical interface under Heads with background color cues notifying the end user of warning (yellow) or errors (red) contextual, graphical menus. + +Legacy to Maximized Upgrade Path (Historical) +--- + +It was possible to upgrade from Legacy to Maximized boards under certain conditions: + +- **If you come from 1vyrain, this was impossible**. 1vyrain does not unlock neither IFD nor ME regions of the SPI. Consequently, flashing internally anything else then Legacy boards produced ROMs would result in a brick. + +- **If coming from Skulls**, if and only optional unlocking step has been followed, you could upgrade internally through a manual flash tool call (`flashprog` on newer firmware or `flashrom` on older firmware), just like if you were coming from Heads Legacy boards while having followed the me_cleaning page instructions prior of initial flash. + +- **If coming from Skulls or Heads Legacy board configurations** while having unlocked IFD initially, you could flash from the recovery shell manually. + +### Manual Upgrade Process (Historical) + +Having a full xxxx-hotp-maximized or xxxx-maximized board config produced ROM available on a USB stick, alongside with your USB Security dongle's matching exported public key, the process was: + +``` +mount-usb +flashprog -p internal -w /media/PathToMaximizedRom.rom +``` + +**Note**: Use `flashprog` on newer Heads firmware (2025+) or `flashrom` on older firmware versions, depending on what is available in your Heads system. + +On next reboot, Heads would guide you into factory resetting your USB Security dongle or import your previously generated public key matching your USB Security dongle's private key. + +It would then regenerate a TOTP/HOTP secret and sign /boot content. You would then have to define a new default boot and optionally renew/change your Disk Unlock Key to be released to to OS to unlock your encrypted OS installation to move forward. + +In the case nothing was found installed on your disk, Heads would propose you to boot from USB to install a new Operating System, prior of being able to do the above steps prior of booting into your system. \ No newline at end of file diff --git a/Development/Porting.md b/Development/Porting.md index 42122cb..5b317b4 100644 --- a/Development/Porting.md +++ b/Development/Porting.md @@ -51,7 +51,7 @@ binary blobs: Check the coreboot configuration for the ported board. This will indicate which binary blobs are required and where they are expected to be located. Heads expects architecture-/board-specific scripts under `blobs/*` which do the magic, called by the main makefile that handles everything in Heads. These scripts must create reproducible binary blobs when invoked. The blobs should be placed in the `blobs/NEW_BOARD/`. Make sure the coreboot config file references the correct path for each blob and the blobs are added to `.gitignore` so that they are not accidentally committed to git. Generally, three binary blobs are required: Management Engine (ME), Intel Flash Descriptor Region (IFD), and Gigabit Ethernet (GBE). The IFD and GBE can be extracted from a donor board using coreboot’s ifdtool. For more details, refer to the [upstream documentation](https://doc.coreboot.org/util/ifdtool/layout.html). On some boards it may be necessary to provide more blobs to coreboot, for instance an MRC blob for RAM initialization if coreboot cannot distribute the blob itself for legal reasons. -Please note, if the ME is neutered, the IFD, coreboot CBFS region, and ME neutering space should be adjusted accordingly. Rationale: the ME region defined under IFD must fit. With the IFD ME region reduced, the BIOS region can grow with the freed ME space. With the BIOS region augmented, the CBFS region of the coreboot configuration must be increased to fit the ["maximized" space](https://osresearch.net/Prerequisites#legacy-vs-maximized-boards). +Please note, if the ME is neutered, the IFD, coreboot CBFS region, and ME neutering space should be adjusted accordingly. Rationale: the ME region defined under IFD must fit. With the IFD ME region reduced, the BIOS region can grow with the freed ME space. With the BIOS region augmented, the CBFS region of the coreboot configuration must be increased to fit the optimized space (all current Heads boards use this approach). Please note the GBE MAC address should be forged to: `00:DE:AD:C0:FF:EE MAC`. It can be done with [nvmutil](https://libreboot.org/docs/install/nvmutil.html). Due to licensing restrictions, the ME firmware cannot be uploaded to the GitHub. However, scripts can be used to build it locally and within CircleCI (a gray area legally, but still possible). GBE and IFD blobs can be uploaded directly to GitHub. Please explain how they were obtained in the commit message. * Note: When calling scripts in Nix-based environments, Python must be invoked explicitly, as Nix does not allow executing Python scripts directly from files. One can use last clean example for t480: `python ./finalimage.py` will work and just `./finalimage.py` will not work. diff --git a/Installing-and-Configuring/Building-Heads/p8z77-m_pro-tpm1.maximized.md b/Installing-and-Configuring/Building-Heads/p8z77-m_pro-tpm1.maximized.md index a9cbdaa..4b64ccd 100644 --- a/Installing-and-Configuring/Building-Heads/p8z77-m_pro-tpm1.maximized.md +++ b/Installing-and-Configuring/Building-Heads/p8z77-m_pro-tpm1.maximized.md @@ -17,7 +17,7 @@ Please determine the [version]({{ site.baseurl }}/Prerequisites#supported-device For the ASUS P8Z77-M Pro there are multiple maximized boards under `./boards`, p8z77-m_pro-tpm1-maximized and p8z77-m_pro-tpm1-maximized-hotp. -As opposed to Legacy boards produced ROM images, Maximized boards produced ROMs are totally valid ROMs, including a valid Intel Flash Descriptor (IFD), Ethernet, a valid neutered Intel ME containing only BUP+ROMP modules which liberated space is given back to the BIOS (coreboot+payload) region. The IFD also has the VSCC table remove in these boards](https://github.com/corna/me_cleaner/issues/80) which prevents the ME having an instruction of what model of flash chip to write to. +Current Heads boards produce totally valid ROM images, including a valid Intel Flash Descriptor (IFD), Ethernet, a valid neutered Intel ME containing only BUP+ROMP modules which liberated space is given back to the BIOS (coreboot+payload) region. The IFD also has the VSCC table removed in these boards](https://github.com/corna/me_cleaner/issues/80) which prevents the ME having an instruction of what model of flash chip to write to. These boards have a script in the 'blobs/p8z77-m_pro' folder which will automatically download a factory rom and perform the necassary modifications and extraction. diff --git a/Installing-and-Configuring/Building-Heads/x230-maximized.md b/Installing-and-Configuring/Building-Heads/x230-maximized.md index cab50a4..a961202 100644 --- a/Installing-and-Configuring/Building-Heads/x230-maximized.md +++ b/Installing-and-Configuring/Building-Heads/x230-maximized.md @@ -17,9 +17,8 @@ For the Thinkpad x230 there are multiple maximized boards under `./boards`, All those roms are externally flashable through their top and bottom rom images. -As opposed to Legacy boards produced ROM images, Maximized boards produced ROMs - are totally valid ROMs, including a valid Intel Flash Descriptor (IFD), Ethernet - Intel Gigabit configuration flash space fiaxating MAC to DE:AD:C0:FF:EE, +Current Heads x230 boards produce totally valid ROM images, including a valid Intel Flash Descriptor (IFD), Ethernet + Intel Gigabit configuration flash space fixing MAC to DE:AD:C0:FF:EE, a valid neutered Intel ME containing only BUP+ROMP modules which liberated space is given back to the BIOS (coreboot+payload) region. diff --git a/Installing-and-Configuring/Prerequisites.md b/Installing-and-Configuring/Prerequisites.md index 8cf085c..f1c4af6 100644 --- a/Installing-and-Configuring/Prerequisites.md +++ b/Installing-and-Configuring/Prerequisites.md @@ -74,66 +74,12 @@ USB Security Dongles (aka security token aka smartcard) *NOTE* - If you prefer not to use USB security dongles or want simplified security procedures, see the [Purism Boot Modes](/PurismBootModes) documentation for information about Basic and Restricted boot modes that provide different security/usability trade-offs. -Legacy vs Maximized boards +Board Architecture Overview === -Some history first on the historical x230-flash and x230 boards that initially created the Heads project. -Heads was initially developped on the x230 board (first xx30 board supported). +**Note**: All current Heads boards use a modern architecture where the Intel Management Engine (ME) is deactivated and the Intel Flash Descriptor (IFD) is unlocked. On older Intel platforms (up to Ivy Bridge/3rd gen), the ME can be neutered (most modules removed), while on newer platforms (Skylake and later), the ME is deactivated using HAP bits or other methods. The historical distinction between "Legacy" and "Maximized" boards is no longer relevant as of 2024, since all supported boards now use the approach that was previously called "maximized." -At that time, ME cleaning/neutering was not a thing. Then me_cleaner facilitated the task. -[The X230 board, as all xx30 family boards do not have a single SPI flash, but two. -On the bottom SPI flash chip lies the Intel Flash Descriptor (IFD), Intel Management Enging (ME), Intel Gigabit Configuration (GBE) and some BIOS available space spanning from 4MB chip. On the top SPI flash is the original BIOS region which spans to BIOS region on the 8MB chip.](https://doc.coreboot.org/mainboard/lenovo/Ivy_Bridge_series.html?highlight=t430#flash-layout) - -Original work done on Heads without ME cleaning led to the creation of a two phase flashing of the board. It required an original external flashing of the x230-flash ROM to the 4MB top chip, which permitted to boot into a minimal BIOS recovery shell from which the x230 board 12MB ROM could be internally flashed through flashrom and Linux, fitting into the 4MB SPI flash from x230-flash ROM. Booting into x230-flash launches a recovery shell which made possible to flash only the BIOS region from the x230 created ROM. This ROM image is incomplete, and flashing the whole 12MB image would create a brick. A script made available through x230-flash was taking care of only flashing the BIOS region defined under untouched IFD region, which permitted to flash the 7MB defined BIOS region inside of the IFD descriptor, without touching ME, GBE or the IFD itself. - -Then me_cleaner came to life, which permitted to clean ME in different ways. me_cleaner project grew mature, and eventually permitted, for xx20 and xx30 families, to not only clean ME, but neuter it. Neutering here means that not only ME was asked to deactivate itself, but most of the modules inside of it could be removed. For the xx20 family, it eventually meant that only Platform Bring UP (BUP) was required for the computer to maintain its functions, while for the xx30, BUP and ROM byPass (ROMP) are necessary. This also meant that the space used by the ME kernel and libraries being deleted could be reused for other purposes. But that space being freed could never be took for granted. Unless the IFD descriptor was modified to reduce ME region to match freed space, coreboot CBFS region maximized to match freed ME available space. Doing so permitted the BIOS region (coreboot + Heads) to jump from a 7MB available BIOS region in IFD descriptor to 11.5MB on the x230 and the whole xx30 family boards. But no board configuration permitted to take advantage of that for numerous reasons, most of which being legal matters, with blobs being non redistributable. - -The consequence of that is the appearance of Maximized boards the multiple xx20 and xx30 boards now lying under Heads repository, and the complexity for newcomers to build and use Heads for the first time. - -*In short, legacy boards will produce ROMs that are incomplete by themselves; they do not contain a valid IFD descriptor and require internal and manual flashrom program invocation with proper parameters from a script to inform flashrom to use the actual IFD defined BIOS region and flash that area only. Otherwise a non-booting system would result. A brick.* - -The maximized boards were created to produce fully valid and complete images for those boards. Blobs download/cleaning scripts were created for xx20 and xx30 platforms, which download ME blobs from the manufacturer, remove all the nasty bits reducing ME used space to the minimal and put resulting blob where it is needed from coreboot configuration to be integrated in the final produced ROM. A valid IFD descriptor is provided under the blob directory to match reduced ME size, giving the freed space to the BIOS region. A generated GBE blob is also provided in tree, required to have a functional e1000e ethernet interface, with an important limitation to be known from Heads users: the MAC address of maximized boards is fixed to DE:AD:C0:FF:EE. That is not so important for the majority of us connecting through wifi nowadays. But if a lot of Heads machines are living on the same LAN, or if privacy is needed through Ethernet connection, NetworkManager or other manual configuration will need to be applied to randomize/fixate Ethernet MAC address to desired value prior of connecting to a network. - -Legacy boards advocates that unlocking IFD regions and ME could permit ME to be modified. While it is true, the non-removable parts of ME (BUP and/or ROMP) are signed together and verified per ME coproocessor prior of permitting the platform to boot. Consequently, removing the nasty parts of ME and providing an unlocked IFD and baked GBE was the chosen path for *Maximized* boards. It is still possible for advanced users to decide to relock the IFD regions prior of flashing maximized boards, while this path would be manual and complexify future internal upgrades. Actually provided Maximized boards take into consideration that the whole SPI flash chip is internally flashable, which would result in flashrom complaining on next internal upgrades. It is still also possible for advanced users to override Heads internally kept configuration to replace the *FLASHROM_OPTIONS* statement to specify manually the IFD defined specific sections to flash : `--ifd --image bios --image ME` etc - -Current Legacy boards ---- -xx30-flash: 4MB ROM images to be flashed internally through 1vyrain or Skulls. Unlocking IFD and cleaning/neutering ME still highly recommended prior of doing initial flash. 1vyrain deactivates ME internally. But if one leaves 1vyrain and chooses another ROM, 1vyrain applied hacks to deactivate ME will not be applied anymore. Note that Skulls permits to unlock IFD as an option prior of initial flash. So if it was not applied at that step, then the end user can only upgrade to Legacy boards produced ROMs in the future, the IFD and ME not being flashable internally and requiring an external flash to go with Maximized boards. - -xx30: Baked 12MB ROM images to be flashed internally through xxxx-flash flashed ROMs. Those ROMs can only be internally flashed from/to legacy boards configuration. Flashing a legacy ROM from a Maximized ROM will result in a brick, since Maximized boards produced ROMs will flash the whole combined opaque 12MB ROM internally, overwriting IFD, ME and GBE with empty content. Resulting into a brick. - -xx20: Those ports (t420 and x220 at time of writing) landed on Heads later in time and were historically produced by making required blobs available by applying scripts on SPI backups to extract required blobs. Consequently, those boards do not suffer from feature reduction as of now; they always took for granted that ME was neutered and IFD was unlocked. They still only flash internally the BIOS region, which was maximized to take advantage of 7.5MB available SPI space for BIOS region, while not reflashing the whole SPI. - -xxxx-hotp-verification: Legacy, reduced versions of their HOTP maximized counterpart. At the time of writing this, those board configuration will normally loose dropbear support, while xx30 versions will not have FBWhiptail anymore. That means that there is no framebuffer enforced graphical interface under Heads with background color cues notifying the end user of warning (yellow) or errors (red) contextual, graphical menus. - -Current Maximized boards ---- -xx30-maximized: Those board configuration produce 3 ROM images: One full 12MB image containing reduced ME, maximized IFD BIOS region and GBE to be flashed internally, and two splitted out ROM images from the full image named bottom (8MB) and top images (4MB), aimed to be externally flashed to their physical SPI counterparts -If built locally, the builder has the option of extracting blobs from a backup image which will put GBE, ME and IFD binaries at the right location in the blobs directory which will be included into coreboot created full ROM image, including Heads payload. There is a risk that ME will be bigger/smaller since backuped blobs might be of sifferent size. In the case ME is bigger then expected, there is a chance that the flashed system will result in a brick. This is why [Cleaning ME instructions in this website](/Clean-the-ME-firmware/) strongly advises into upgrading to Lenovo 2.76 version of the firmware prior of backuping the bottom SPI ROM, unlocking IFD and clean that specific version of proprietary firmware. This is also why it is suggested to only backup your GBE to keep your MAC address for Ethernet and use the download script under blobs/xx30 to download and neuter verified version of Lenovo ME downloaded straight from their website. Those do not enforce HOTP firmware verification (see hotp-maximized counterparts) against supported USB Security dongles and rely solely on TOTP to manually verify firmware integrity prior of each boot, that is: launching OTP application on smartphone to manually verify that the TOTP codes generated on both screens of smartphone and laptop matches from smartphone generated and scanned Qr code after first boot of Heads new firmware. - -xxxx-hotp-maximized: Those board configurations are the same as prior maximized board configuration, but produce ROM images enforcing TOTP+HOTP for firmware verification on supported, already bought and received prior of flashing USB Security dongles to be bounded with Heads. - -Legacy to Maximized boards upgrade path ---- -It is possible to upgrade from Legacy to Maximized boards under certain conditions. - -*If you come from 1vyrain, this is impossible*. 1vyrain does not unlock neither IFD nor ME regions of the SPI. Consequently, flashing internally anything else then Legacy boards produced ROMs will result in a brick. - -If coming from Skulls, *if and only optional unlocking step has been followed*, you can upgrade internally through a manual flashrom call, just like if you were coming from Heads Legacy boards while having followed the me_cleaning page instructions prior of initial flash. - -If coming from Skulls or Heads Legacy board configurations while having unlocked IFD initially, you can flash from the recovery shell manually. -[**IF UNSURE, PLEASE VERIFY FIRST**](/Updating#verify-upgradeability-paths-of-the-firmware) - -Having a full xxxx-hotp-maximized or xxxx-maximized board config produced ROM available on a USB stick, alongside with your USB Security dongle's matching exported public key, do the following: -``` -mount-usb -flashrom -p internal -w /media/PathToMaximizedRom.rom -``` -On next reboot, Heads will guide you into factory resetting your USB Security dongle or import your previously generated public key matching your USB Security dongle's private key. - -It will then regenerate a TOTP/HOTP secret and sign /boot content. You will then have to define a new default boot and optionally renew/change your Disk Unlock Key to be released to to OS to unlock your encrypted OS installation to move forward. - -In the case nothing is found installed on your disk, Heads will propose you to boot from USB to install a new Operating System, prior of being able to do the above steps prior of booting into your system. +For users upgrading from very old firmware (pre-2024), see the [Historical Legacy Migration](/Historical-Legacy-Migration) page. Emulated devices === diff --git a/Installing-and-Configuring/Upgrading.md b/Installing-and-Configuring/Upgrading.md index b86f608..90b4f78 100644 --- a/Installing-and-Configuring/Upgrading.md +++ b/Installing-and-Configuring/Upgrading.md @@ -133,23 +133,12 @@ If you need to validate the current firmware integrity against the last flashed --- -Migrating from Legacy to Maximized Firmware +Historical: Migrating from Very Old Firmware --- -**Warning**: Migration from Legacy to Maximized builds is now considered a legacy process. Legacy builds were officially deprecated in [October 2024](https://github.com/linuxboot/heads/pull/1803), while Maximized builds have been promoted since [December 2020](https://github.com/linuxboot/heads/pull/703). Use maximum caution when upgrading internally to Maximized builds, as improper steps may result in a bricked device. -### How to Identify Legacy vs Maximized Builds -To determine whether you are using a Legacy or Maximized build: -1. Boot into the Heads main menu. -2. Check the main screen title: - - If the build is **Maximized**, the label will explicitly include the word "Maximized." - - Example: `x230-hotp-maximized` - - If the label does not include "Maximized," you are using a Legacy build. - - Example: `x220-legacy`, `x220`, `t430`, `x230-hotp` (no "Maximized" in the board name). +**Note**: If you are upgrading from very old Heads firmware that predates the 2024 standardization, please refer to the [Historical Legacy Migration](/Historical-Legacy-Migration) page for detailed information and migration steps. -For migration instructions, refer to the [Downloading documentation]({{ site.baseurl }}/Downloading) and ensure you follow both the upgradability validation and integrity validation steps before flashing. - -**Important Note for Nitrokey Customers**: -If you are using a NitroPad X230 or T430 with firmware version **1.2 or earlier**, you should contact [Nitrokey support](https://support.nitrokey.com/) to get their flashing service. For more details, refer to this [Nitrokey support thread](https://support.nitrokey.com/t/nitropad-t430-firmware-update-brick/3777/2). +All current Heads boards use modern architecture, and new installations should use current board configurations. --- @@ -167,39 +156,44 @@ For more details on re-owning, refer to the relevant sections above. Verify Upgradeability Paths of the Firmware ==== First, verify the [supported platforms]({{ site.baseurl }}/Prerequisites#supported-devices). -If you have a *ThinkPad (xx30/xx20 flavors), proceed with caution.* -*Also select the HOTP variant if you own a [Heads-supported USB Security dongle]({{ site.baseurl }}/Prerequisites#usb-security-dongles-aka-security-token-aka-smartcard) for visual remote attestation.* -Review whether the Intel Firmware Descriptor (IFD) and Intel Management Engine (ME) were unlocked from the [Recovery Shell]({{ site.baseurl }}/RecoveryShell) before proceeding. +**For ThinkPad users (xx30/xx20 families)**: If you are upgrading from very old firmware that predates 2024, proceed with extra caution and ensure you have recovery equipment available. + +*Select the HOTP variant if you own a [Heads-supported USB Security dongle]({{ site.baseurl }}/Prerequisites#usb-security-dongles-aka-security-token-aka-smartcard) for visual remote attestation.* + +Review whether the Intel Firmware Descriptor (IFD) and Intel Management Engine (ME) regions are unlocked from the [Recovery Shell]({{ site.baseurl }}/RecoveryShell): ```shell -flashrom -p internal +flashprog -p internal ``` -The two following situations must apply, which will define what to do next. +**Note**: On older Heads firmware (pre-2025), use `flashrom -p internal` if `flashprog` is not available. Newer firmware versions use `flashprog` as the flash tool. + +The output will show whether you can upgrade internally or need external flashing. -Unlocked IFD and ME +Unlocked IFD and ME (Modern Firmware) ---- -This is the expected output if the initial external flashing of the firmware unlocked IFD and ME regions: +This is the expected output for modern Heads firmware with unlocked IFD and ME regions: ![CanBeFlashedToMaximizedRom](https://user-images.githubusercontent.com/827570/167728631-85a5ca9e-48f6-4d4f-8544-532fa75bf5d3.jpeg) -- This means you can internally migrate from Legacy boards (xxxx-hotp/xxxx boards ROM) to their Maximized boards counterpart (xxx-hotp-maximized/xxxx-maximized boards ROM). - - If you are presently on a Legacy board (If Heads boot screen is not showing Maximized): - - You will have to manually call flashrom from the Recovery Console: - - `mount-usb` - - `flashrom -p internal -w /media/heads-hotp-maximized-version-gcommit.rom` - - ![InternalUpgradeToMaximizedROM](https://user-images.githubusercontent.com/827570/167729694-6ff8da60-986a-4ec3-9b2d-4fa94e42d3fa.jpeg) -- If you are already running a Maximized board ROM, you can safely upgrade through Heads GUI keeping your current settings. - -Locked IFD and ME + +- **Current firmware**: You can safely upgrade through the Heads GUI using `.zip` files +- **Very old firmware**: If upgrading from pre-2024 firmware, you may need to manually flash: + - `mount-usb` + - `flashprog -p internal -w /media/heads-current-version-gcommit.rom` (or `flashrom` on older firmware) + - ![InternalUpgradeToMaximizedROM](https://user-images.githubusercontent.com/827570/167729694-6ff8da60-986a-4ec3-9b2d-4fa94e42d3fa.jpeg) + +Locked IFD and ME (Very Old Firmware) ---- -Otherwise, initial external flashing of the firmware didn't unlock the IFD/ME regions: +If you see this output, your firmware has locked IFD/ME regions: ![CantBeInternallyUpgradeToMaximizedROM](https://user-images.githubusercontent.com/827570/167728658-731362da-a676-4610-becb-ff94f2ff48b1.jpeg) -- This means you will have to: - - Externally reflash Maximized board ROM - - xx30: xx30-*maximized-top.rom(4Mb) and xx30-*maximized-bottom.rom(8Mb) ROMs - - xx20: xx20-*-maximized.rom (8Mb ROM) -Legacy board variants were [officially deprecated in October 2024 per this PR](https://github.com/linuxboot/heads/pull/1803). +- This indicates very old firmware that requires external flashing +- You will need to externally reflash using current board ROM files: + - xx30 family: Use the appropriate `.rom` files (typically split into 4MB + 8MB images) + - xx20 family: Use the appropriate single `.rom` file +- **Warning**: External flashing is required - internal flashing will not work + +**Historical Note**: Legacy board variants were [officially deprecated in October 2024](https://github.com/linuxboot/heads/pull/1803). All current boards use modern architecture. --- diff --git a/Installing-and-Configuring/configuring-keys.md b/Installing-and-Configuring/configuring-keys.md index 8fb7ae7..8b40164 100644 --- a/Installing-and-Configuring/configuring-keys.md +++ b/Installing-and-Configuring/configuring-keys.md @@ -146,7 +146,7 @@ inserted. Select "Add a GPG key to the running BIOS" to enter the GPG Management menu, then "Add a GPG key to the running BIOS + reflash". Follow the steps and your GPG key will be added to the Heads rom. -Once `flashrom` is complete, reboot and now you should now be back in the Heads +Once the flash tool (`flashprog` on newer firmware or `flashrom` on older firmware) is complete, reboot and now you should now be back in the Heads runtime. It should display a message that it is unable to unseal TOTP. ## Configuring the TPM