Heads-threat-model: per-board GPIO TPM reset protection table; uniformise 20 board flashing guide pages

About/Heads-threat-model.md

@@ -144,6 +144,15 @@ Additionally, since my ROM image is very size constrained, Heads didn't want to
  from 5MB to 180KB.  The source is available from [github.com/osresearch/tpmtotp](https://github.com/osresearch/tpmtotp)
  and has since been merged into the Heads project.
 
+**Note on TPMTOTP attestation and GPIO reset attacks:** On Intel platforms where
+coreboot does not lock the PCH GPIO pad configuration, an attacker with OS-level
+code execution can reset the TPM and forge PCR measurements, bypassing TPMTOTP
+and HOTP attestation. The TPM Disk Unlock Key with passphrase is not affected.
+See the [Per-Board Protection Status](#per-board-protection-status) section below
+for which boards are affected, and
+[TPM GPIO Reset Vulnerability](https://github.com/linuxboot/heads/blob/master/doc/TPM_GPIO_Reset_Vulnerability.md)
+for technical details.
+
 The UEFI firmware itself is also of great concern: is a very large code base and
  most system firmwares are built from closed-source forks of the edk2 tree. This
  presents a problem for trusted systems since it is not possible to knows what
@@ -506,6 +515,57 @@ Heads is not designed for "Cover" or "Concealment"
  competitor, but there is no "NSA proof toolkit" that can stop a nation state
  from making you have a very bad day.
 
+Per-Board Protection Status
+===
+
+The TPM GPIO reset vulnerability
+([upstream coreboot bug #576](https://ticket.coreboot.org/issues/576))
+affects TPMTOTP evil maid detection and HOTP USB security dongle authentication
+on platforms where coreboot does not lock the PCH GPIO pad configuration.
+The TPM Disk Unlock Key with passphrase is **not affected** on any platform.
+
+{: .note }
+Heads itself is **not** vulnerable — the fix must come from coreboot.
+See the [technical document](https://github.com/linuxboot/heads/blob/master/doc/TPM_GPIO_Reset_Vulnerability.md)
+for details.
+
+| Board | Evil Maid detection<br>(TPMTOTP attestation) | Disk encryption<br>(TPM DUK + passphrase) | USB Security Dongle<br>(HOTP authentication) |
+|---|---|---|---|
+| **Pre-Skylake laptops** (xx20/30/4x): T420, T430, T440p, W530, W541, X220, X230 | ✅ Protected | ✅ Protected | ✅ Protected |
+| **Desktop boards**: Optiplex 7010/9010, HP Z220 CMT | ✅ Protected | ✅ Protected | ✅ Protected |
+| **T480, T480s** (8th Gen Kaby Lake) | ❌ Not protected<br>[TPM GPIO reset bypass](https://mkukri.xyz/2024/06/01/tpm-gpio-fail.html) | ✅ Protected | ❌ Not protected |
+| **Librem 14, Librem 11** (Purism) | ❌ Not protected | ✅ Protected | ❌ Not protected |
+| **Librem 13v2/v4, 15v3/v4** (Purism) | ❌ Not protected | ✅ Protected | ❌ Not protected |
+| **Librem L1UM v2, Mini v1/v2** (Purism) | ❌ Not protected | ✅ Protected | ❌ Not protected |
+| **Librem L1UM v1** (Broadwell) | ✅ Protected | ✅ Protected | ✅ Protected |
+| **NovaCustom NV4x, NitroPad NS50** (12th Gen Alder Lake) | ❌ Not protected | ✅ Protected | ❌ Not protected |
+| **NovaCustom V54/V56, NitroPad V54/V56** (Meteor Lake) | ✅ Protected | ✅ Protected | ✅ Protected |
+| **MSI Z690-A, Z790-P** (12th-13th Gen) | ❌ Not protected | ✅ Protected | ❌ Not protected |
+| **KGPE-D16** (AMD) | ✅ Protected | ✅ Protected | ✅ Protected |
+| **Talos II** (Power9) | ✅ Protected | ✅ Protected | ✅ Protected |
+
+✅ Protected — Heads' protection against this attack is intact on this board.
+
+❌ Not protected — the TPM GPIO reset vulnerability bypasses Heads' TPMTOTP
+  and HOTP attestation on this board. An attacker with OS-level code execution
+  could reset the TPM and forge PCR measurements to extract the shared secret.
+
+{: .note }
+TPM Disk Unlock Key (DUK) with passphrase is **not affected** on any board.
+The DUK requires a user passphrase to unseal, which a GPIO reset cannot bypass.
+
+### What this means for your threat model
+
+- If you rely on Heads for **evil maid detection** (checking the TOTP code
+  before entering your disk password), choose a board marked ✅ in the
+  first column.
+- If you need **USB security dongle authentication** (HOTP), choose a board
+  marked ✅ in the last column.
+- **Disk encryption** (TPM DUK with passphrase) is protected on all boards.
+
+For the current per-board technical status and fork verification details, see the
+[Heads board testers list](https://github.com/linuxboot/heads/blob/master/doc/BOARDS_AND_TESTERS.md).
+
 Binary blobs, microcode updates and transient execution vulnerabilities
 ===
 With the disclosure of the Spectre and Meltdown vulnerabilities in January 2018, it became apparent that most processors manufactured since the late 1990s can potentially be compromised by attacks made possible because of [transient execution CPU vulnerabilities](https://en.wikipedia.org/wiki/Transient_execution_CPU_vulnerability). Modern CPUs utilize speculative execution in order to increase performance. A branch misprediction may leave observable side effects that may reveal private data to attackers using a timing attack. Future not-yet-identified vulnerabilities of this kind is likely. For users of Qubes OS, this class of vulnerabilities can additionally compromise the enforced isolation of virtual machines, and it is prudent to take the risks associated with these vulnerabilities into account when deciding on a platform on which to run Heads and Qubes OS.

Installing-and-Configuring/Flashing-Guides/T420-maximized.md

@@ -26,4 +26,11 @@ The thinkpad T420 has only one SPI flash chip that holds the BIOS, ME, etc. It i
 
 **Note**: See the [SPI Programmer Best Practices]({{ site.baseurl }}/SPI-Programmer-Best-Practices/) for programmer recommendations (Tigard recommended; CH347F preferred budget option; CH341A rev1.6+ acceptable with a physical selector).
 
+## TPM GPIO Reset Vulnerability — Not Affected
+
+This platform (Sandy Bridge / Intel 2nd Gen) is **not affected** by the
+[TPM GPIO reset vulnerability](https://mkukri.xyz/2024/06/01/tpm-gpio-fail.html).
+On pre-Skylake PCHs, the PLTRST# signal connected to the TPM reset line is a
+dedicated pin that cannot be reprogrammed to GPIO mode by software.
+
 You should then follow through with [configuring keys]({{ site.baseurl }}/Configuring-Keys/).

Installing-and-Configuring/Flashing-Guides/T430-maximized.md

@@ -2,23 +2,26 @@
 layout: default
 title: Lenovo T430 Maximized
 permalink: /T430-maximized-flashing/
-nav_order: 3
+nav_order: 1
 parent: Step 2 - Flashing Guides
 grand_parent: Installing and configuring
 ---
 
 Lenovo T430 (Maximized)
 ===
 
-## ⚠️ Safety First
+[T430 Hardware Maintenance Manual](https://download.lenovo.com/ibmdl/pub/pc/pccbbs/mobiles_pdf/t430_t430i_hmm_en_0b48304_04.pdf)  
 
-**Before starting, please read our [SPI Programmer Best Practices guide]({{ site.baseurl }}/SPI-Programmer-Best-Practices/) for essential safety information and programmer recommendations.**
+## TPM GPIO Reset Vulnerability — Not Affected
 
-[T430 Hardware Maintenance Manual](https://download.lenovo.com/ibmdl/pub/pc/pccbbs/mobiles_pdf/t430_t430i_hmm_en_0b48304_04.pdf)  
+This platform (Ivy Bridge / Intel 3rd Gen) is **not affected** by the
+[TPM GPIO reset vulnerability](https://mkukri.xyz/2024/06/01/tpm-gpio-fail.html).
+On pre-Skylake PCHs, the PLTRST# signal connected to the TPM reset line is a
+dedicated pin that cannot be reprogrammed to GPIO mode by software.
 
-Similarly to the x230, the thinkpad T430 has two SPI flash chips that hold the BIOS, ME, etc. They are located under the palm rest. To access these chips, complete disassembly is required. It is a straightforward process and takes approximately 30 minutes. For this you will need: some screwdrivers, thermal paste (since the CPU cooler needs to be removed too), a recommended SPI programmer (see our [Best Practices guide]({{ site.baseurl }}/SPI-Programmer-Best-Practices/)), and another laptop/PC with Ubuntu installed. Other linux based OS should be fine too. 
+Similarly to the x230, the thinkpad T430 has two SPI flash chips that hold the BIOS, ME, etc. They are located under the palm rest. To access these chips, complete disassembly is required. It is a straightforward process and takes approximately 30 minutes. For this you will need: some screwdrivers, thermal paste (since the CPU cooler needs to be removed too), an assembled ch341a SPI programmer (e.g. [Modified ch341a SPI programmer](https://novacustom.com/product/modded-ch341a-bios-firmware-programmer-3v/) by Novacustom) and a other laptop/PC with Ubuntu installed. Other linux based OS should be fine too. 
 
-**Critical**: Remove all batteries (including CMOS) AND disconnect the AC adapter before starting.
+First remove the battery and the cable powering your device.
 
 ![Keyboard tilted up]({{ site.baseurl }}/images/t430/1_1_back_view_removed_battery.jpg)
 
@@ -61,37 +64,31 @@ Left chip corresponds to the "bottom" flash chip (8192 kb) and right corresponds
 
 First [download]({{ site.baseurl }}/Downloading)  or build (please see [general building]({{ site.baseurl }}/{{ site.baseurl }}/x230-maximized-building/) / [building x230]({{ site.baseurl }}/x230-maximized-building/))  the maximized board roms (top and bottom) for this board and verify their hashes.
 
-**Note:** If you need to reflash or customize the EC firmware while still on proprietary platform firmware, refer to the **EC firmware & customizations** section in the [Prerequisites]({{ site.baseurl }}/Prerequisites) for guidance on performing EC updates and customizations from vendor firmware prior to the initial Heads flash.
-
 
 Try to read the name on the top SPI flash chip. I was unable to do that. The dots on the chip help to identify the correct clip orientation. 
 
 ![SPI flash chips closed view]({{ site.baseurl }}/images/t430/11_spi_chips_closed_view.jpg)
 
- Then, connect the clip and SPI programmer to the "top" (4096 kb) SPI flash chip. In my set up, the red wire should be where the dot is.
-
-**Note**: See the [SPI Programmer Best Practices]({{ site.baseurl }}/SPI-Programmer-Best-Practices/) for programmer recommendations (Tigard recommended; CH347F preferred budget option; CH341A rev1.6+ acceptable with a physical selector). The commands below use `[programmer]` as a placeholder; see the SPI Programmer Best Practices guide for example commands for specific programmers.
+ Then, connect the clip and ch341a programmer to the "top" (4096 kb) SPI flash chip. In my set up, the red wire should be where the dot is.
 
 ![Flashing 4 mb chip]({{ site.baseurl }}/images/t430/12_flash_4mb_spi_chip.jpg)
 
  Use flashrom to check the chip that you are connected to:
 
 ```shell
-sudo flashrom --programmer [programmer]
+sudo flashrom -p ch341a_spi
 ```
 
 
  Here is my output.
 
 ![output top 4 mb chip]({{ site.baseurl }}/images/t430/13_ubuntu_output_4mb.jpg)
 
-Find the chip and create a backup and verify it (For me the SPI flash chip is `YYY`):
+Find the chip and read from it twice (For me the SPI flash chip is `YYY`):
 
 ```shell
-sudo flashrom --programmer [programmer] --read ~/top.bin --chip YYY
-# Quick sanity check: inspect the start of the dump for obvious garbage
-hexdump -C ~/top.bin | head -20
-sudo flashrom --programmer [programmer] --verify ~/top.bin --chip YYY
+sudo flashrom -r ~/top.bin --programmer ch341a_spi -c YYY && \
+    sudo flashrom -v ~/top.bin --programmer ch341a_spi -c YYY
 ```
 
 If the files differ then try reconnecting your programmer to the SPI flash chip
@@ -101,7 +98,7 @@ If the files differ then try reconnecting your programmer to the SPI flash chip
 If they are the same then write `t430-maximized-top.rom` to the SPI flash chip:
 
 ```shell
-sudo flashrom --programmer [programmer] --chip YYY --write ~/heads/build/x86/t430-maximized/t430-maximized-top.rom
+sudo flashrom -p ch341a_spi -c YYY -w ~/heads/build/x86/t430-maximized/t430-maximized-top.rom
 ```
 
  While everything goes well you should see the blue LED on the programmer.
@@ -115,37 +112,32 @@ sudo flashrom --programmer [programmer] --chip YYY --write ~/heads/build/x86/t43
 
 
 Try to read the name on the bottom SPI flash chip. Then, connect the clip and
- SPI programmer to the bottom SPI flash chip. 
+ ch341a programmer to the bottom SPI flash chip. 
 
 ![flashing bottom 8 mb chip]({{ site.baseurl }}/images/t430/16_flash_8mb_chip.jpg)
 
  Use flashrom to check the chip that you are connected to:
 
 ```shell
-sudo flashrom --programmer [programmer]
+sudo flashrom -p ch341a_spi
 ```
 
 Here is my output.
 
 ![output bottom 8 mb chip]({{ site.baseurl }}/images/t430/17_ubuntu_output_8mb.jpg)
 
-Find the chip and create a backup and verify it (For me the SPI flash chip is `ZZZ`):
+Find the chip and read from the chip twice (For me the SPI flash chip is `ZZZ`):
 
 ```shell
-sudo flashrom --programmer [programmer] --read ~/bottom.bin --chip ZZZ
-# Quick sanity check: inspect the start of the dump for obvious garbage
-hexdump -C ~/bottom.bin | head -20
-sudo flashrom --programmer [programmer] --verify ~/bottom.bin --chip ZZZ
+sudo flashrom -r ~/bottom.bin --programmer ch341a_spi -c ZZZ && \
+    sudo flashrom -v ~/bottom.bin --programmer ch341a_spi -c ZZZ
 ```
 
 The 8M bottom chip contains the ME firmware.  It is neutralized in maximized version. You can flash it specifying the same chip you found under ZZZ:
 ```shell
-sudo flashrom --programmer [programmer] --chip ZZZ --write ~/heads/build/x86/t430-maximized/t430-maximized-bottom.rom
+sudo flashrom -p ch341a_spi -c ZZZ -w ~/heads/build/x86/t430-maximized/t430-maximized-bottom.rom
 ```
 
-**Note about GBE:** The T430 contains a GBE region (board MACs) inside the Intel Firmware Descriptor (IFD). **Always back up the full chip before the initial flash** and inspect the dump (for example, `hexdump -C ~/bottom-backup.bin | head -20`).
-
-If you need to preserve a board's MAC/GBE, the reliable approach is to create a custom GBE during the Heads build (see the `boards/<boardname>` configuration in linuxboot/heads). For details on preserving board-specific regions, consult the SPI Programmer Best Practices guide and the board's build documentation, and refer to issue #120 for community discussion.
 If all goes well, you should see the keyboard LED flash, and within a second Heads will boot in its GUI. 
 
 Two reboots are sometimes needed after flash. Force power off by holding the power button for 10 seconds. Since the memory training data was wiped by the content of the full flashed ROM, this is normal.

Installing-and-Configuring/Flashing-Guides/T480-maximized.md

@@ -36,6 +36,31 @@ Some ThinkPad T480 units on the used market are affected by an Intel bug in the
 
 Please note that as of March 2025, Thunderbolt data transfer is not supported upstream by [coreboot](https://review.coreboot.org/c/coreboot/+/83274). However, video output through Thunderbolt and charging still work. This means only the USB-C charging port can be used for data transfer.
 
+## TPM GPIO Reset Vulnerability (upstream coreboot bug)
+
+Heads relies on [coreboot](https://coreboot.org/) for low-level platform initialization, including GPIO pad configuration. Many Intel platforms are affected by a coreboot bug where the PCH GPIO lock bits are not set before booting the OS. This allows an attacker with code execution (e.g., a malicious OS or dual-boot environment) to assert the TPM's PLTRST# signal via PCH GPIO register access and clear PCRs without a physical reboot — enabling forged measurements and TPM secret extraction. Details: [TPM GPIO fail (mkukri.xyz)](https://mkukri.xyz/2024/06/01/tpm-gpio-fail.html).
+
+The fix must come from coreboot. GPIO lock support varies by SoC generation in coreboot upstream:
+
+| Platform generation | Coreboot GPIO lock status |
+|---|---|
+| Sandy/Ivy/Haswell/Broadwell (2nd-5th Gen) | Not vulnerable: PLTRST# is a dedicated PCH pin, cannot be reprogrammed to GPIO |
+| Skylake through Tiger Lake (6th-11th Gen) — **this platform** | Not functional: common GPIO block exists but lock method is not selected in Kconfig, and pad lock register offsets are missing from GPIO community definitions (some added in 26.06 but still non-functional without Kconfig selection) |
+| Alder Lake / Raptor Lake (12th-13th Gen) | Functional: `SOC_INTEL_COMMON_BLOCK_GPIO_LOCK_USING_SBI` selected, pad lock offsets defined |
+| Meteor Lake and newer (Core Ultra Series 1+) | Functional: `SOC_INTEL_COMMON_BLOCK_GPIO_LOCK_USING_PCR` selected, pad lock offsets defined |
+
+Note: coreboot 26.06 added `pad_cfg_lock_offset` to Skylake GPIO communities ([merged patch](https://review.coreboot.org/c/coreboot/+/90884)), but the lock remains non-functional without the Kconfig selection ([open patch](https://review.coreboot.org/c/coreboot/+/90885) — tested and does not work on real hardware). The T480 boards use coreboot 25.09 which lacks even the offset definitions.
+
+Further progress on Skylake-era platforms likely requires Intel NDA documentation. Tracked at [coreboot ticket #576](https://ticket.coreboot.org/issues/576) and [coreboot patch series](https://review.coreboot.org/q/topic:%22intel_gpio_lock%22).
+
+**Impact on Heads:**
+
+- **TPM Disk Unlock Key (DUK) with passphrase**: Not affected. Heads requires a passphrase to unseal the disk key, which this attack cannot bypass.
+- **TPMTOTP remote attestation**: Affected. A GPIO reset preserves NVRAM; the sealed TOTP/HOTP secret at index 0x4d47 (no passphrase required) can be unsealed after replaying PCR extends. The attacker obtains the shared secret and can produce valid TOTP/HOTP codes indefinitely.
+- **HOTP sealed secrets without a passphrase**: Affected.
+
+See the [Heads threat model]({{ site.baseurl }}/Heads-threat-model/) for more context. The board configuration file (`boards/EOL_t480-*/EOL_t480-*.config`) contains additional notes.
+
 ## Flashing Heads
 
 First, remove the batteries and disconnect the power cable from your device. Removing the screws will allow you to remove the back panel. A guitar pick or an old credit card can be helpful for detaching the panel.