|
1 | | -# Below this note is the standard Heads README |
2 | | -I am working to port heads to the Lenovo ThinkPad x280 |
3 | | - |
4 | | - |
5 | | -> [!WARNING] |
6 | | -> The heads port should be done. I need to do some checks: |
7 | | -Unticked first one because I have no idea if this is reproducible via circleci I have not tested circleci |
8 | | -- [ ] Successful external flash link to circleci: https://X.Y.Z. from commit `X.Y.Z.` using external programmer model `X.Y.Z.` on `X.Y.Z.` Voltage mode |
9 | | -- [X] Boots successfully after the flashing: |
10 | | -- [X] Setting clock prompt on first reboot: ok if triggered correctly after initial flashing and CMOS battery disconnected |
11 | | -- [X] Clean boot detected (no keyring, nothing installed on disk): usb boot proposed and followed |
12 | | -- [X] Boots on usb |
13 | | -- [X] OS `X.Y.Z.` install and reboot |
14 | | -- [~] Heads functionality- no pubkey detected, but OS detected -> OEM-Factory-reset proposed. Done with `X.Y.Z.` hardwarekey e.g. nk3 TOTP works I do not have HOTP dongle |
15 | | -- [X] On reboot after re-ownership: generate new HOTP/TOTP |
16 | | -- [X] wifi works based on OS `X.Y.Z.` |
17 | | -- [X] PR0 coreboot upstream includes this without patch |
18 | | - - [X] flashprog -p internal (not locked) |
19 | | - - [X] lock_chip (locks the platform with PR0, if PR0 patch applied in fork or under `patches/coreboot-X.Y.Z.` and coreboot config contain proper preparation of the platform) |
20 | | - - [X] flashprog -p internal (reports locked) |
21 | | - |
22 | | - |
23 | | -but we are at the point where the fact that I have never used heads before is the bigger issue. I unfortunately do NOT have a HOTP dongle/ NitroKey, so I can only test TOTP for now. |
24 | | -Sorry for taking so long, I spent the last month or two being really busy with other things. |
25 | | - |
26 | | - |
27 | | - |
28 | | -# Notes while I am working on this |
29 | | - |
30 | | -Attempted heads with AlguienSasaki's commits. Did not work. |
31 | | - |
32 | | -Heads now only beeps at you once, and does not reboot constantly. We do not know if this is better or worse but it is different. <- with hindsight, this appears to be better |
33 | | - |
34 | | -I will set up QEMU for logs. |
35 | | - |
36 | | -Long hiatus, moved across the country. WILL BE BACK SORRY FOR IMMENSE DELAY. |
37 | | - |
38 | | -I am not sure if I can actually begin work on this yet, but I did have time to set up QEMU! |
39 | | -QEMU tells me it gets past Cache As RAM and loops 193-196 CPU instructions. Probably a register? To be honest this is a BIT out of my league BUT it does actually boot, which is more than I thought it was doing. Technically a regression since CoreBoot just supports the X280 and I have made it not. I might need a responsible adult. |
40 | | - |
41 | | -It still just beeps at me like I owe it money and I have to remove Remote TPM for it to even build, otherwise the kernel is too big I have some fundamental issues with this config. |
42 | | -Every single time I get keyboard backlight, no screen, Six beeps, and then nothing. It just hangs a while. It eerily resembles the QEMU behaviour of trying to do something, going red, and then hanging a while and it still will not tell me what the beeps are. |
43 | | - |
44 | | -QEMU will be emulating a generic intel CPU, so I can't guarantee too much with this one. I need to know what the beeps mean. |
45 | | - |
46 | | -I believe it is failing at RAM initialisation. build/x86/coreboot-25.09/src/mainboard/lenovo/sklkbl_thinkpad/variants/ also did not end up generating a new variant. The X280 has soldered RAM, the T480 does not. |
47 | | - |
48 | | -raminit fsp bad me I dont know please stop beeping |
49 | | - |
50 | | -it might be the blobs oh no why I gave the x280 its own /variants/ and went around the FSP and XIP stuff just for this not IME/IFD |
51 | | - |
52 | | -the charging LED, f4/microphone LED, and Power button LED are now in a state of permanent blinking. |
53 | | -Ok so beeping means FSP issues from coreboot. Blinking means... |
54 | | -coreboot--TIMELESS--LESSTIME--Heads- Thu Jan 01 00:00:00 UTC 1970 x86_32 bootblock starting (log level: 7)... <- also 1970 epoch not ideal |
55 | | -CBFS: Found 'fallback/romstage' @0x67dc0 size 0x11a58 in mcache @0xfef0568c |
56 | | -CBFS: Found 'bootblock' @0xdedfc0 size 0xd000 in mcache @0xfef05b44 |
57 | | -TPM: Digest of `CBFS: bootblock` to PCR 2 logged |
58 | | -TPM: Digest of `CBFS: fallback/romstage` to PCR 2 logged |
59 | | -BS: bootblock times (exec / console): total (unknown) / 2 ms |
60 | | -coreboot--TIMELESS--LESSTIME--Heads- Thu Jan 01 00:00:00 UTC 1970 x86_32 romstage starting (log level: 7)... |
61 | | -CBFS ERROR: 'fspm.bin' allocation failure |
62 | | -FSPM not available or failed to load! |
63 | | -This isnt heads. I now need to figure out why on earth fspm is not working |
64 | | - |
65 | | -I used different version of coreboot along with a minimal version of the kernel config IT IS ALIVE |
66 | | - |
67 | | -I am now bringing everything in slowly. I do not have a HOTP dongle yet, so unfortunately I cannot test it. I also cannot test on other X280 devices since the other one I had has been given a funeral |
68 | | - |
69 | | -<img width="1600" height="900" alt="image" src="https://github.com/user-attachments/assets/c374731d-187b-4011-8781-b1acf19d3dbf" /> |
70 | | - |
71 | | - |
72 | | -# Heads: the other side of TAILS |
73 | | - |
74 | | - |
75 | | - |
76 | | -Heads is a configuration for laptops and servers that tries to bring |
77 | | -more security to commodity hardware. Among its goals are: |
78 | | - |
79 | | -* Use free software on the boot path |
80 | | -* Move the root of trust into hardware (or at least the ROM bootblock) |
81 | | -* Measure and attest to the state of the firmware |
82 | | -* Measure and verify all filesystems |
83 | | - |
84 | | - |
85 | | - |
86 | | -NOTE: It is a work in progress and not yet ready for non-technical users. |
87 | | -If you're interested in contributing, please get in touch. |
88 | | -Installation requires disassembly of your laptop or server, |
89 | | -external SPI flash programmers, possible risk of destruction and |
90 | | -significant frustration. |
91 | | - |
92 | | -More information is available in [the 33C3 presentation of building "Slightly more secure systems"](https://trmm.net/Heads_33c3). |
93 | | - |
94 | | -## Documentation |
95 | | - |
96 | | -The `doc/` directory contains technical reference documentation for the |
97 | | -Heads codebase. Start here: |
98 | | - |
99 | | -| Document | What it covers | |
100 | | -| --- | --- | |
101 | | -| [doc/architecture.md](doc/architecture.md) | Component overview: coreboot, Linux payload, initrd, build system, configuration layers | |
102 | | -| [doc/security-model.md](doc/security-model.md) | Trust hierarchy, measured boot, TOTP/HOTP attestation, GPG boot signing, LUKS DUK, fail-closed design | |
103 | | -| [doc/boot-process.md](doc/boot-process.md) | Step-by-step boot flow: /init → gui-init → kexec-select-boot → OS handoff | |
104 | | -| [doc/tpm.md](doc/tpm.md) | PCR assignments, sealing policies, SRTM chain, board-specific TPM variations, developer config reference | |
105 | | -| [doc/ux-patterns.md](doc/ux-patterns.md) | GUI/UX conventions: whiptail wrappers, integrity report, error flows | |
106 | | -| [doc/config.md](doc/config.md) | Board and user configuration system | |
107 | | -| [doc/docker.md](doc/docker.md) | Reproducible build workflow using Docker | |
108 | | -| [doc/circleci.md](doc/circleci.md) | CircleCI pipeline layout, workspace flow, and cache behavior | |
109 | | -| [doc/qemu.md](doc/qemu.md) | QEMU board targets for development and testing | |
110 | | -| [doc/wp-notes.md](doc/wp-notes.md) | Flash write-protection status per board | |
111 | | -| [doc/BOARDS_AND_TESTERS.md](doc/BOARDS_AND_TESTERS.md) | Supported boards and their maintainers/testers | |
112 | | -| [doc/prerequisites.md](doc/prerequisites.md) | USB security dongles (HOTP/TPMTOTP), OS requirements, flashing methods | |
113 | | -| [doc/faq.md](doc/faq.md) | Common questions: UEFI vs coreboot, TPM, LUKS, threat models | |
114 | | -| [doc/keys.md](doc/keys.md) | All keys and secrets: TPM owner, GPG PINs, Disk Recovery Key, LUKS DUK | |
115 | | -| [doc/development.md](doc/development.md) | Commit conventions, coding standards, testing checklist | |
116 | | -| [doc/build-freshness.md](doc/build-freshness.md) | Debugging stale builds: initrd.cpio.xz composition, verification | |
117 | | - |
118 | | -For user-facing documentation and guides, see [Heads-wiki](https://osresearch.net). |
119 | | - |
120 | | -## Contributing |
121 | | - |
122 | | -We welcome contributions to the Heads project! Before contributing, please read our [Contributing Guidelines](CONTRIBUTING.md) for information on how to get started, submit issues, and propose changes. |
123 | | - |
124 | | -## Building Heads |
125 | | - |
126 | | -Heads builds inside a versioned Docker image. The supported and tested workflow uses the |
127 | | -provided Docker wrappers — no host-side QEMU or swtpm installation is needed. |
128 | | - |
129 | | -**Quick start** (requires [Docker CE](https://docs.docker.com/engine/install/)): |
130 | | - |
131 | | -```bash |
132 | | -./docker_repro.sh make BOARD=x230-hotp-maximized |
133 | | -./docker_repro.sh make BOARD=qemu-coreboot-fbwhiptail-tpm2 run |
134 | | -``` |
135 | | - |
136 | | -**No hardware required for testing** — Docker provides the full build stack |
137 | | -and QEMU runtime with software TPM (swtpm) and the bundled `canokey-qemu` |
138 | | -virtual OpenPGP smartcard. Build and test entirely in software before flashing real hardware. |
139 | | - |
140 | | -Build targets are the directory names under `boards/`. For the current set of |
141 | | -tested and maintained targets, see [doc/BOARDS_AND_TESTERS.md](doc/BOARDS_AND_TESTERS.md). |
142 | | - |
143 | | -For full details — wrapper scripts, Nix local dev, reproducibility verification, and |
144 | | -maintainer workflow — see **[doc/docker.md](doc/docker.md)**. |
145 | | - |
146 | | -For CI cache/workspace behavior and the CircleCI job graph, see |
147 | | -**[doc/circleci.md](doc/circleci.md)**. |
148 | | - |
149 | | -For QEMU board testing see **[doc/qemu.md](doc/qemu.md)**. |
150 | | - |
151 | | -For troubleshooting build issues see **[doc/faq.md](doc/faq.md)** and |
152 | | -**[doc/build-freshness.md](doc/build-freshness.md)**. |
153 | | - |
154 | | -## General notes on reproducible builds |
155 | | - |
156 | | -In order to build reproducible firmware images, Heads builds a specific |
157 | | -version of gcc and uses it to compile the Linux kernel and various tools |
158 | | -that go into the initrd. Unfortunately this means the first step is a |
159 | | -little slow since it will clone the `musl-cross-make` tree and build gcc... |
160 | | - |
161 | | -Once that is done, the top level `Makefile` will handle most of the |
162 | | -remaining details -- it downloads the various packages, verifies the |
163 | | -hashes, applies Heads specific patches, configures and builds them |
164 | | -with the cross compiler, and then copies the necessary parts into |
165 | | -the `initrd` directory. |
166 | | - |
167 | | -There are still dependencies on the build system's coreutils in |
168 | | -`/bin` and `/usr/bin/`, but any problems should be detectable if you |
169 | | -end up with a different hash than the official builds. |
170 | | - |
171 | | -## Key components |
172 | | - |
173 | | -Heads builds a curated set of packages (from `modules/`). Key components |
174 | | -enabled by most board configs include: |
175 | | - |
176 | | -* [musl-cross-make](https://github.com/richfelker/musl-cross-make) — cross-compiler toolchain |
177 | | -* [coreboot](https://www.coreboot.org/) — minimal firmware replacing vendor BIOS/UEFI |
178 | | -* [Linux](https://kernel.org) — minimal kernel payload (no built-in initrd; boots with external initrd such as `initrd.cpio.xz`) |
179 | | -* [busybox](https://busybox.net/) — core utilities |
180 | | -* [kexec](https://wiki.archlinux.org/index.php/kexec) — Linux kernel executor (loads kernels from boot partition, USB, network) |
181 | | -* [tpmtotp](https://github.com/osresearch/tpmtotp) — TPM-based TOTP/HOTP one-time password generator |
182 | | -* [cryptsetup](https://gitlab.com/cryptsetup/cryptsetup) — LUKS disk encryption |
183 | | - |
184 | | -The full build also includes: lvm2, tpm2-tools, flashrom/flashprog, dropbear (SSH), |
185 | | -fbwhiptail (GUI), qrencode, and many others. See individual `modules/*` files and |
186 | | -board configs for the complete picture. |
187 | | - |
188 | | -We also recommend installing [Qubes OS](https://www.qubes-os.org/), |
189 | | -although there Heads can `kexec` into any Linux or |
190 | | -[multiboot](https://www.gnu.org/software/grub/manual/multiboot/multiboot.html) |
191 | | -kernel. |
192 | | - |
193 | | -### Notes |
194 | | - |
195 | | -* Building coreboot's cross compilers can take a while. Luckily this is only done once. |
196 | | -* Builds are finally reproducible! The [reproduciblebuilds tag](https://github.com/osresearch/heads/issues?q=is%3Aopen+is%3Aissue+milestone%3Areproduciblebuilds) tracks any regressions. |
197 | | -* Current tested and maintained boards are tracked in [doc/BOARDS_AND_TESTERS.md](doc/BOARDS_AND_TESTERS.md). Board targets themselves live under `boards/`. |
198 | | -* Xen does not work in QEMU. Signing, HOTP, and TOTP do work; see below. |
199 | | -* Blob requirements are board- or board-family-specific. Check the relevant documentation under `blobs/` for the target you are building. |
200 | | -* Purism boards use Purism-managed coreboot blob paths from the Purism fork (for example `3rdparty/purism-blobs/...` via `CONFIG_IFD_BIN_PATH` and `CONFIG_ME_BIN_PATH` in `config/coreboot-librem_*.config`). Heads should not maintain those vendor blob payloads. Runtime firmware notes for Librem blob jail are in [blobs/librem_jail/README](blobs/librem_jail/README). |
201 | | -* Lenovo xx20 boards such as X220 and X230 use the shared xx20 blob flow documented in [blobs/xx20/readme.md](blobs/xx20/readme.md). X220-specific notes are in [blobs/x220/readme.md](blobs/x220/readme.md). |
202 | | -* Other boards can source blobs from board-family directories under `blobs/` (for example xx20/xx30/xx80, t420, t440p, w541) or from fork-specific paths configured in coreboot configs (for example Dasharo boards using `3rdparty/dasharo-blobs/...`). Vendor blob payloads remain maintained by their upstream vendors/forks. |
203 | | -* T480 and T480s blob requirements are documented in [blobs/xx80/README.md](blobs/xx80/README.md). Other families have their own docs under `blobs/`, for example `t420/`, `t440p/`, and `w541/`. |
204 | | - |
205 | | -### QEMU |
206 | | - |
207 | | -OS booting can be tested in QEMU using a software TPM. HOTP can be tested by forwarding a USB token from the host to the guest. |
208 | | - |
209 | | -For more information and setup instructions, refer to the [qemu documentation](doc/qemu.md). |
210 | | - |
211 | | -### coreboot console messages |
212 | | - |
213 | | -The coreboot console messages are stored in the CBMEM region |
214 | | -and can be read by the Linux payload with the `cbmem --console | less` |
215 | | -command. There is lots of interesting data about the state of the |
216 | | -system. |
| 1 | +Ignore this branch pls |
0 commit comments