11 |
18 |
19 |
20 | Prerequisites for porting Heads
21 | ===
22 | Prerequisites:
23 | 1. coreboot port: since Heads is a coreboot payload, the board must have fully completed and actively maintained coreboot support. Any known issues should be acceptable to end users. Exceptions include the Purism and Dasharo coreboot forks, where coreboot is used from their respective forks.
24 | 2. TPM module: Measured boot and the usable security features are at the core of what Heads is about. These features depend on the TPM. Therefore, the board must have a TPM module. If it uses fTPM and you plan to neuter the Intel Management Engine (ME), the fTPM must remain functional under coreboot even after neutering ME. Otherwise, a dTPM is required for this board.
25 | 3. The final flash layout must have enough space for the Heads payload. Concretely, the size of the flash chip(s) must be at least be 12MB and the size of the BIOS region must be large enough to take the Heads payload. Usually, this means shrinking another region, the ME, and reallocating the freed space to the BIOS region. However, changing the ME blob or flash layout is not always possible as Intel Bootguard prevents booting with such modifications in most modern boards unless the board vendor chose otherwise.
26 | 4. Technical skills: the person porting the board must have basic knowledge of coreboot, Linux, Bash, Git, and Python to complete the port. While the community is committed to helping, an alternative option is a financial contribution for [consultancy services](https://osresearch.net/Consultation-Services/).
27 | 5. External programmer: an external programmer is required to flash Heads and, if necessary, to recover from a brick.
28 | 6. Users and Board-testers: There should be multiple users and testers interested in using the board, as this makes maintenance and testing easier and benefits the entire ecosystem. You may, of course, port it for yourself first and allow others to join later. However, you must commit to testing—especially after coreboot version bumps or Linux kernel updates. If testing is not done in a timely manner, the board will be moved to an "unmaintained, untested" status. This would be unfortunate, potentially a waste of time, and disappointing for everyone involved.
29 | 7. GPU: dGPUs are problematic in Heads for various reasons. While successful ports on older machines with dGPUs existed (e.g. [t530 and w530](https://github.com/linuxboot/heads/commit/a854144e2dbf14700491e3f1cb6f88e12d22197b)), security may be affected, and there is currently no clear solution for that. In case you are curious, please read a longer discussion on the Matrix coreboot channel starting with this [post](https://matrix.to/#/!EhaGFZyYcbyhdSgStq:matrix.org/$4OuJ9tPr8a_U6pwWgmjQxL0hnmpBzTATAHVl9gMvnfQ?via=matrix.org&via=tchncs.de&via=dodoid.com).
30 |
31 | The scheme depicts a port cycle.
32 | 
33 |
34 | Files needed to be created/modified are depicted on the scheme.
35 | 
36 |
37 | Prerequisites for building the ROM
38 | ===
39 | The goal is to build a ROM before the code review. `NEW_BOARD` refers to the name of your board (e.g., `t480`). It is recommended to clone the Heads GitHub repository and create a new branch:
40 | ```shell
41 | git clone https://github.com/linuxboot/heads.git
42 | git checkout -b Poc_NEW_BOARD
43 | ```
44 |
45 | modules/coreboot:
46 | ---
47 | coreboot fork that will be used should be added under `heads/modules/coreboot`. This will be the version you reference from the board config files. You should aim for building the board with an existing coreboot version, usually the main version that most boards use. If you need a different coreboot version, consider patching an existing version without breaking any other boards depending on it, of course. However, if you need to add a new coreboot fork, it should be done here. This is not ideal and not recommended, as there are already 2 different coreboot forks. It often leads to maintenance and resources burden.
48 |
49 | binary blobs:
50 | ---
51 | 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.
52 | 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.
53 |
54 | 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).
55 |
56 | 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.
57 | * 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.
58 | The blobs folder should have a script.sh which handles downloading, deactivating ME etc. It should also contain a README.md file briefly explaining the process. Hashes of the blobs should be stored either in `README.md` or in `hashes.txt file`. Furthermore, the script must ensure the integrity of the blobs it produced by comparing a SHA256 hash.
59 |
60 | NEW_BOARD.mk:
61 | ---
62 | Create a new `heads/targets/NEW_BOARD.mk` file which deals with calling blobs/script.sh*, download and extraction, and placing the blobs in correct location. This will be used by the main makefile and defines the board specific targets and dependencies, such as the binary blobs. For additional details, please see [Makefiles]({{ site.baseurl }}/Development/make-details.md).
63 |
64 | board.config:
65 | ---
66 | There should be a file `NEW_BOARD-hotp-maximized.config`, which inherits all the parameters from `NEW_BOARD-maximized.config` and adds HOTP verification. Those files should be located in the folder `heads/boards/NEW_BOARD-hotp-maximized` and `heads/boards/NEW_BOARD-maximized`, respectively. This is Heads specific configuration and should be adapted from a similar platform. The top of the board config files is also a good place to put some technical board-specific documentation, known issues etc.
67 | You should point in `NEW_BOARD-hotp-maximized` and `NEW_BOARD-maximized` to the coreboot version e.g. `export CONFIG_COREBOOT_VERSION=X.Y.Z.`- that was modified under `modules/coreboot` (see corresponding section above). Additionally, the configurations should reference the appropriate coreboot and linux configs created below:
68 | ```
69 | CONFIG_COREBOOT_CONFIG=config/coreboot-NEW_BOARD.config
70 | CONFIG_LINUX_CONFIG=config/linux-NEW_BOARD.config
71 | ```
72 | * For early testing, enabling debug mode is a good idea. However, these options should be removed before merging:
73 | ```
74 | export CONFIG_DEBUG_OUTPUT=y
75 | export CONFIG_ENABLE_FUNCTION_TRACING_OUTPUT=y
76 | ```
77 | Note: This may cause glitches where the screen output appears overwritten until an arrow key is pressed. This is normal for DEBUG mode, as the additional tracing output uses the same console as fbwhiptail. The issue will disappear once debug options are removed from the board configs.
78 | * It is important to define the correct TPM configuration (TPM 1.2 vs. TPM 2.0), ensuring they are mutually exclusive, similar to the coreboot configuration (described in coreboot config below). The selected option misses `#`:
79 | ```
80 | #TPM2 requirements
81 | export CONFIG_TPM2_TOOLS=y
82 | export CONFIG_PRIMARY_KEY_TYPE=ecc
83 | ```
84 | ```
85 | #TPM1 requirements
86 | #export CONFIG_TPM=y
87 | ```
88 | In the configuration, the binary blobs must be specified as build targets, as coreboot depends on these blobs. It is the line at the bottom of the board config `BOARD_TARGETS := NEW_BOARD`. It ensures that the main Heads makefile builds the targets specified in the `NEW_BOARD.mk` file.
89 |
90 | coreboot.config:
91 | ---
92 | You need a coreboot configuration for the new board. Ideally, this config should be adapted from the closest possible platform. You can inspect existing configurations for boards in the master branch and select one with a similar architecture, if available. Next, you can create a coreboot config by copying it from the closest platform and adapt it accordingly. You may use coreboot's `make menuconfig` for `NEW_BOARD`:
93 | ```shell
94 | cp config/coreboot-CLOSEST_PLATFORM.config config/coreboot-NEW_BOARD.config
95 | ./docker_repro.sh make coreboot.modify_and_save_oldconfig_in_place
96 | ```
97 | Note, the configuration needs to define the correct path references to all binary blobs, that are not provided by coreboot, on most architectures this includes at least `IFD`, `ME` and `GBE` (see above). The configuration file path should be: `heads/config/coreboot-NEW_BOARD.config`.
98 | * Note:
99 | TPM measured boot (```CONFIG_TPM_MEASURED_BOOT=y```) and verified boot (```CONFIG_VBOOT_LIB=y```) should be enabled. Ensure that you select CONFIG_TPM_MEASURED_BOOT and CONFIG_VBOOT_LIB in Kconfig. Furthermore, enable the TPM and pick the correct TPM version for the board.
100 | Other parameters depend on the board. It is up to you to determine the correct settings, as not all community members will have access to your board. `git diff` between `coreboot-CLOSEST_PLATFORM.config` and `coreboot-NEW_BOARD.config` may help.
101 |
102 | linux.config:
103 | ---
104 | This should be adapted from a similar board. The file path should be `heads/config/linux-NEW_BOARD.config`.
105 |
106 | CircleCI:
107 | ---
108 | Modify `heads/.circleci/config.yml` to add support for the `NEW_BOARD`. Initially, configure it to depend directly on musl-cross-make. At this stage, do not reuse caches—this simplifies debugging and ensures a clean build process.
109 | ```
110 | # NEW_BOARD is based on `X.Y.Z`. coreboot release, not sharing any buildstack from now, depend on muscl-cross cache
111 | - build:
112 | name: NEW_BOARD-hotp-maximized
113 | target: NEW_BOARD-hotp-maximized
114 | subcommand: ""
115 | requires:
116 | - x86-musl-cross-make
117 | ```
118 | CircleCI creates reproducible builds, allowing users to verify that the "flashable" roms were indeed produced by the given source code. In the development/debugging phase, it helps to ensure that you talk about the same build. It optimizes the collaboration between peers-board owners. Moreover, CI builds are significantly faster than local builds, reducing overall development time. As circleCI always builds all boards it makes it easier to find regressions early.
119 |
120 | * Optional: local builds.
121 | If you need to build locally (e.g. to ensure that some features work) pay attention to the helper functions at the end of the Makefiles. It is strongly recommended that local builders review the end of the Makefiles (including modules/*files), as these helper functions were designed to facilitate coreboot and Linux version bumps.
122 | For a completely clean build (the most radical approach), either clone the Heads repository again or remove all build artifacts using:
123 | ```bash
124 | ./docker_repro.sh BOARD=NEW_BOARD real.clean
125 | ```
126 | Building all tools needed will take a while depending on the number of cores and RAM available on your machine. For a less radical approach, run:
127 | ```shell
128 | ./docker_repro.sh BOARD=NEW_BOARD real.remove_canary_files-extract_patch_rebuild_what_changed
129 | ```
130 | Then, inject any changes into the coreboot fork canary file so that the build system refetches, repatches, and rebuilds the coreboot fork:
131 | ```shell
132 | echo "bogus" | sudo tee build/x86/coreboot-t480/.canary
133 | ```
134 | Note, patches that attempt to create files that are not expected to exist but exist will fail, showing at console what files already existed that couldn't be created. In this case, you need to remove them manually `rm -rf`, and restart the build with `./docker_repro.sh BOARD=NEW_BOARD` which will progress until each modules/* required per board config is successfully built.
135 |
136 | Testing
137 | ===
138 | For thorough testing—especially for a new board—using the following template (tasks to check) may be beneficial. Copy and paste this template into the GitHub message window when reporting test results. Mark completed tasks with an `x` inside the brackets [ ]. Replace `X.Y.Z` with the relevant information. It is recommended also to upload relevant screenshots For additional safety, you may wish to remove the metadata from these files.
139 | ```
140 | - [ ] 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
141 | - [ ] Boots successfully after the flashing:
142 | - [ ] Setting clock prompt on first reboot: ok if triggered correctly after initial flashing and CMOS battery disconnected
143 | - [ ] Clean boot detected (no keyring, nothing installed on disk): usb boot proposed and followed
144 | - [ ] Boots on usb
145 | - [ ] OS `X.Y.Z.` install and reboot
146 | - [ ] Heads functionality- no pubkey detected, but OS detected -> OEM-Factory-reset proposed. Done with `X.Y.Z.` hardwarekey e.g. nk3
147 | - [ ] On reboot after re-ownership: generate new HOTP/TOTP
148 | - [ ] wifi works based on OS `X.Y.Z.`
149 | - [ ] PR0
150 | - [ ] flashprog -p internal (not locked)
151 | - [ ] 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)
152 | - [ ] flashprog -p internal (reports locked)
153 | ```
154 |
155 | Debugging
156 | ===
157 | Future debugging from Heads: enter recovery console, with a formatted USB thumb drive (fat32/exfat/ext3/ext4) and then
158 | ```shell
159 | mount-usb --mode rw
160 | cp /tmp/debug.log /media
161 | cbmem -L > /media/coreboot_measured_boot.txt
162 | cbmem -1 > /media/coreboot_cbmem_console.txt
163 | cbmem -t > /media/coreboot_cbmem_stages_timestamps.txt
164 | umount /media
165 | ```
166 | And then provide log files in a subsequent comment. That would be really helpful if something is still wrong. Of course, this should be modified based on the problem faced.
167 |
168 | Pull Request (PR)
169 | ===
170 | Create an initial PR, with commits relative roughly to the steps above. 1 commit should correspond to 1 major bullet point. Note that Heads is all about reproducibility. Therefore, your commit messages should explain why you made the change and _how_ you got there. For instance, explain how to create a certain binary blob or better write a script that can be run by everyone.
171 |
172 | Then lets collaborate in the PR. Create a heads fork in your own repository, follow the [contribution guide](https://github.com/linuxboot/heads/blob/master/CONTRIBUTING.md) as you go, make sure you sign and sign-off commits and don't stress too much if this seems a lot. Get a PR started and we will collaborate there.
173 |
174 | Remove debugging mode:
175 | ===
176 | One of last commits should remove the debugging mode, functions tracing and use quiet mode instead.
177 |
178 | Write a flashing/disassembling guide
179 | ===
180 | Take pictures as you disassemble your board and flash the Heads ROM. You can use them later to write a guide. This will help less technical community members using the board. Your effort will improve the ecosystem.
181 | If you cannot manage to finish writing the guide but talented enough to finish the port just create an issue on the GitHub and drop pictures. We will try to find time to help.
182 | The guide is essential part of the port.
183 |
184 | Contribute to maintenance
185 | ===
186 | Refer to [Contributing on GitHub page](https://github.com/linuxboot/heads/blob/master/CONTRIBUTING.md)
187 |
188 | Heads is free as free beer.
189 | In the spirit of open-source software, free knowledge, and communal goodwill, support the Heads and the open source development [Insurgo Initiative - Open Collective](https://opencollective.com/insurgo).
190 | The supply of free beer cannot be infinite. If everyone takes without giving back, at some point, the keg runs dry, and so does the goodwill.
191 | If you enjoy free beer, contribute in some form—whether by bringing code, docs, or financial support. The cycle must be maintained to keep the ecosystem alive. No one wants to be the last guest realizing the fridge is empty and no one restocked it. Together, it is possible to keep the free beer spirit alive—open, shared, and always refreshing. Cheers!
192 |
193 | You may examine all [github PRs with the label 'port'](https://github.com/linuxboot/heads/issues?q=label%3Aport+) to gather additional information. Good luck!
194 |
--------------------------------------------------------------------------------
/Development/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Development
4 | permalink: /Development
5 | nav_order: 9
6 | has_children: yes
7 | has_toc: false
8 | ---
9 |
10 | Contributing
11 | ====
12 |
13 | * [Issues tagged with "Help Wanted"](https://github.com/osresearch/heads/labels/help%20wanted)
14 | * [Issues tagged with "Bounty"](https://github.com/osresearch/heads/labels/Bounty)
15 | * [Contributing to the Heads wiki](/Contributing-to-Heads-wiki/)
16 |
--------------------------------------------------------------------------------
/Development/make-details.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Makefile
4 | permalink: /Makefile/
5 | nav_order: 2
6 | parent: Development
7 | ---
8 |
9 | Makefile
10 | ===
11 |
12 | Helpful targets and options
13 | ---
14 |
15 | Verbose build (otherwise all log output goes into `build/x86/logs/$(submodule).log`):
16 |
17 | ```shell
18 | make V=1
19 | ```
20 |
21 | Produce just the build of a single sub-module invoking its name as the target:
22 |
23 | ```shell
24 | make gpg
25 | ```
26 |
27 | Clean a single submodule or all (?) volatile submodules:
28 |
29 | ```shell
30 | make gpg.clean
31 | make modules.clean
32 | ```
33 |
34 | Clean all volatile submodules except crosscompiler (clean build):
35 |
36 | ```shell
37 | make real.clean
38 | ```
39 |
40 | The Heads `Makefile`
41 | ===
42 |
43 | All of the organization of the Heads build is handled in the top level
44 | `Makefile` with the goal of producing a reproducible `initrd.cpio` containing
45 | the Heads runtime and kernel modules, the Head's Linux `bzImage` kernel, and
46 | the `coreboot.rom` tailored for the target platform initialization.
47 |
48 | Build configuration
49 | ---
50 |
51 | Platform configuration are stored in the `board/$BOARD.config`
52 | ([list of boards can be found here](/Install-and-Configure#supported-devices))
53 | as well as the sub-modules necessary for the system.
54 | The main difference between these use cases is the init scripts that
55 | are installed in the inird, the Linux kernel configuration and the
56 | coreboot or edk2 configuration.
57 | An example configuration is [`board/x230.config`](https://github.com/osresearch/heads/blob/master/boards/x230/x230.config)
58 |
59 | Sub-modules
60 | ---
61 |
62 | Sub-modules are defined in the `modules` directory and each one defines a
63 | dependency to be fetched, verified, configured, built and installed. The top
64 | level `Makefile` includes all of the `modules/*` files and the ones that are
65 | configured to `y` in the board's configuration will be built and installed into
66 | the initrd. Since the Heads runtime is built with a `musl-libc` cross
67 | compiler, there are frequently hacks necessary to convince the `configure`
68 | scripts or submodule Makefiles to build correctly, and since we only want the
69 | bare minimum of output for the initrd we don't use the actual `make install`
70 | target to create the ramdisk.
71 |
72 | An example submodule file is for the `cryptsetup` command, used to mount
73 | encrypted volumes from the recovery shell:
74 |
75 | ```Makefile
76 | modules-$(CONFIG_CRYPTSETUP) += cryptsetup
77 |
78 | cryptsetup_depends := util-linux popt lvm2 $(musl_dep)
79 |
80 | cryptsetup_version := 1.7.3
81 | cryptsetup_dir := cryptsetup-$(cryptsetup_version)
82 | cryptsetup_tar := cryptsetup-$(cryptsetup_version).tar.xz
83 | cryptsetup_url := https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/cryptsetup-$(cryptsetup_version).tar.xz
84 | cryptsetup_hash := af2b04e8475cf40b8d9ffd97a1acfa73aa787c890430afd89804fb544d6adc02
85 |
86 | # Use an empty prefix so that the executables will not include the
87 | # build path.
88 | cryptsetup_configure := ./configure \
89 | CC="$(heads_cc)" \
90 | --host $(MUSL_ARCH)-elf-linux \
91 | --prefix "" \
92 | --disable-gcrypt-pbkdf2 \
93 | --with-crypto_backend=kernel \
94 |
95 | # but after building, replace prefix so that they will be installed
96 | # in the correct directory.
97 | cryptsetup_target := \
98 | $(MAKE_JOBS) \
99 | && $(MAKE) \
100 | -C $(build)/$(cryptsetup_dir) \
101 | prefix="$(INSTALL)" \
102 | install
103 |
104 | cryptsetup_output := \
105 | src/.libs/cryptsetup \
106 | src/.libs/veritysetup \
107 |
108 | cryptsetup_libraries := \
109 | lib/.libs/libcryptsetup.so.4 \
110 | ```
111 |
112 | The main components that every submodule must define are:
113 |
114 | * Give itself a name and add itself to the modules list, if configured:
115 | `modules-$(CONFIG_CRYPTSETUP) += cryptsetup`
116 | * Enumerate its depdencies by their submodule names:
117 | `cryptsetup_depends := util-linux popt lvm2 $(musl_dep)`
118 | * Define a version `cryptsetup_version := 1.73`
119 | * Specify the name of the directory that the tar file will unpack into `cryptsetup_dir`
120 | * Name the tar file that will be fetched `cryptsetup_tar`
121 | * Specify the URL from which this file will be fetched `cryptsetup_url`
122 | * Provide the sha256 hash of the file to verify its correctness `cryptsetup_hash`
123 | * Define the command that will be run in the unpacked diretory to configure it
124 | after unpacking and patching (see below) `cryptsetup_configure`
125 | ** Note that we provide the compiler `CC="$(heads_cc)"` in quotes, since there
126 | might be spaces in the variable
127 | * `--host $(MUSL_ARCH)-elf-linux` is used to indicate that this is a cross compile
128 | * `--prefix` avoids writing path names into the executable
129 | * plus some additional submodule specific stuff
130 | * The target to be called by make in this directory to generate the output
131 | * The `$(MAKE_JOBS)` will have the number of parallel instances to execute
132 | * Sometimes mutliple steps are required; separate them by `&&` to ensure that
133 | they short-circuit correctly
134 | * The first one has an implicit `$(MAKE) -C $(build)/$(cryptsetup_dir)`, but
135 | the second step has to list it explicitly
136 | * Lastly a list of any executables `cryptsetup_output` or libraries
137 | `cryptsetup_libraries` that will be produced by the build, relative to the
138 | build directory.
139 | * These will be installed into `initrd/bin` and `initrd/lib`
140 | * They will be stripped
141 |
142 | If there are any patches that need to be applied, put the file in
143 | `patches/$(submodule_name)-$(submodule_version).patch` and it will be applied
144 | when the tar file is unpacked.
145 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/BootOptions.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Configuring Boot Options
4 | permalink: /BootOptions/
5 | parent: Installing and configuring
6 | nav_order: 85
7 | ---
8 |
9 |
10 | 12 | Table of contents 13 |
14 | {: .text-delta } 15 | 1. TOC 16 | {:toc} 17 |
11 |
18 |
19 |
20 |
21 | Boot config files
22 | ===
23 |
24 | A user has the option to make persistent modifications to the non-Qubes boot
25 | process by creating one or more of the following files:
26 |
27 | | file | description |
28 | | ---- | ---- |
29 | | kexec_menu.txt | contains multiple options for parameters to the kexec command|
30 | | kexec_hashes.txt | a sha256sum file from within the respective boot directory |
31 | | kexec_iso_add.txt | a sh variable to override the standard ISO kernel argument additions |
32 | | kexec_iso_remove.txt | a sh variable to override the standard ISO kernel argument removals |
33 | | kexec_default.$N.txt | specifies the default kexec parameters corresponding to the Nth menu option |
34 | | kexec_default_hashes.txt | a sha256sum file for the default entry kexec file parameters |
35 | | kexec_rollback.txt | a sha256sum of the TPM counter contents in the tmp directory |
36 | | kexec_key_devices.txt | contains a list of "device uuid" combos for all LUKS devices to unlock |
37 | | kexec_key_lvm.txt | contains the name of an LVM group to activate on boot |
38 |
39 | These can be placed in any of the following locations:
40 |
41 | | location | description |
42 | | ---- | ---- |
43 | | /boot/ | used during internal HD boot |
44 | | /media/ | used during standard USB boot |
45 | | /media/kexec_iso/$ISO_FILENAME/ | used during USB boot from a particular ISO file |
46 |
47 | These files are only used if there is an appropriate signature for them in `kexec.sig` covering all `kexec*.txt` in that location. This can be generated from the user interface from the `Update checksums and sign all files` in /boot menu option, or manually from the recovery shell by running `kexec-sign-config -p /boot/`, etc. These files are only copied by `kexec-check-config` to `/tmp/kexec/` if there is a valid signature. From there the boot routines reference only the configs in `/tmp/kexec`.
48 |
49 | Dynamic vs Persistent Boot Options
50 | ====
51 |
52 | There are two ways for heads to boot Operating systems from /boot.
53 |
54 | * Dynamic (no kexec_menu.txt)
55 | * Persistent
56 |
57 | `kexec_menu.txt` is generated from GUI menu option `Default boot` while /boot contents detached signed digest is verified as valid. If there is no persistent `kexec_menu.txt` the boot directory will be searched for grub/syslinux-like configurations and it will be generated dynamically (for any of the HD/USB/USB-ISO locations). Creating a persistent `kexec_menu.txt` can be useful to limit the options displayed or to make persistent alterations to xen or kernel params.
58 |
59 |
60 | Persistent Boot Options
61 | ----
62 |
63 | To customize the boot options and ignore the default OS boot configurations you may create a
64 | `kexec_menu.txt` which has a simple layout of a single line per boot option:
65 |
66 | ```text
67 | description 1|elf|kernel /vmlinuz... |initrd /initramfs... |append ...
68 | description 2|multiboot|kernel ... |module ... |module ...
69 | description 3|xen|kernel /xen... |module /vmlinuz... | module /initramfs...
70 | ```
71 |
72 | Here is a sample `kexec_menu.txt` derived from grub.cfg:
73 |
74 |
75 |
76 | ```text
77 | Ubuntu|elf|kernel /vmlinuz-4.8.0-58-generic|initrd /initrd.img-4.8.0-58-generic|append root=/dev/mapper/ubuntu--vg-root ro quiet splash crashkernel=384M-:128M crashkernel=384M-:128M
78 | Memory test (memtest86+, serial console 115200)|elf|kernel /memtest86+.bin|append console=ttyS0,115200n8
79 | Qubes, with Xen hypervisor|multiboot|kernel /xen-4.6.5.gz placeholder |module /vmlinuz-4.4.67-13.pvops.qubes.x86_64 placeholder root=/dev/mapper/luks-UUID ro rd.qubes.hide_all_usb|module /initramfs-4.4.67-13.pvops.qubes.x86_64.img
80 | ```
81 |
82 |
83 |
84 | ### Securing Persistent Boot Options
85 |
86 | By default, no file hash checks are made for default boot since this was done during configuration. A non-default boot will fail when the file hashes don't match the expected values.
87 |
88 | ### require hash checks
89 |
90 | If a user wishes to require that file hashes be checked for a succesful
91 | non-recovery boot, they may set the `CONFIG_BOOT_REQ_HASH=y` in their
92 | respective Heads config file (/etc/config.user).
93 |
94 | ### default boot
95 |
96 | As as convenience mechanism, a user may select a boot option to always be used
97 | in the future, assuming that the boot parameters and file hashes have not
98 | changed. This can be done by running `kexec-save-default` manually or directly
99 | from the boot menu. This works for any boot location (HD/USB/USB ISO) but does
100 | modify the respective `/boot/` or `/media/` filesystems.
101 |
102 | In the case of dynamicly derived boot options from `grub.cfg` (i.e. no persistent kexec_menu.txt) an entry index is cached so that the boot will fail when there is a change to the underlying grub parameters. This will require the user to resign/revalidate the settings. This is useful to detect changes to the primary kernel/initramfs (for example in the Qubes case when the primary entry is first).
103 |
104 | ### multiboot
105 |
106 | Note that currently, any multiboot entry is interpreted as a Xen-variant and
107 | `kexec-boot` overrides the arguments to the multiboot kernel with custom
108 | arguments. A user can manually specify `multiboot` entries to override the
109 | default behavior by creating a custom `kexec_menu.txt`.
110 |
111 | ### rollback counter
112 |
113 | If a user wishes to require that a TPM counter be set for rollback prevention,
114 | they may set the `CONFIG_BOOT_REQ_ROLLBACK=y` in their respective Heads config
115 | file. When this is true, standard boot will only succeed in these two cases:
116 |
117 | * Booting from an verified ISO
118 | * Booting from a mount point that has a valid `kexec_rollback.txt` in its
119 | parameter directory
120 |
121 | The simplest way to achieve this is to set a default boot option as this updates
122 | the rollback counter by default.
123 |
124 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/Building-Heads/general.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: General Building
4 | nav_order: 1
5 | permalink: /general-building/
6 | parent: Step 1 - Building Heads
7 | grand_parent: Installing and configuring
8 | ---
9 |
10 |
11 | 12 | Table of contents 13 |
14 | {: .text-delta } 15 | 1. TOC 16 | {:toc} 17 |
12 |
19 |
20 |
21 | Building Heads
22 | ===
23 |
24 | With the new Nix build system, building Heads has become more streamlined.
25 |
26 | Please refer to the [Building Heads](https://github.com/linuxboot/heads/blob/master/README.md#building-heads) section in the [Heads README](https://github.com/linuxboot/heads/blob/master/README.md) for updated instructions on how to build Heads using the Nix build system's produced docker image reproducibly.
27 |
28 | For more information, you can also check out the [pull request #1661](https://github.com/linuxboot/heads/pull/1661) which provides additional details and updates to the build process.
29 |
30 | Clone the tree:
31 |
32 | ```shell
33 | git clone https://github.com/osresearch/heads
34 | cd heads
35 | ```
36 |
37 | Builds of Heads should be reproducible unless issues are currently known,
38 | [see Heads milestone #1](https://github.com/osresearch/heads/milestone/1) for
39 | more detail, which means that Heads will build in the exact same way on
40 | different computers. Because of this, as a user, you can guarantee that Heads
41 | has built correctly and has not been tampered with.
42 |
43 | However, this also means that the first time you build Heads it must first build
44 | the compilers that it will use to build itself. If that seems complicated,
45 | don’t worry. The result is that the first build of Heads will take about an
46 | hour to complete. After the first build, building Heads will take less than a
47 | minute.
48 |
49 | Useful targets, stored under the `boards` directory of the git tree.
50 |
51 | Generic
52 | ---
53 |
54 | Generally, everything that is needed to flash the SPI flash of a board is a
55 | single rom generated through `make BOARD=$BOARD` commands, where $BOARD is the
56 | name of the board that can be found under `board` directory of the git
57 | downloaded tree. You can do the build verbose by doing `make BOARD=$BOARD V=1`
58 |
59 | You can also run make in debug mode to trace errors in the buildsystem while you try to improve it through `make -d BOARD=$BOARD V=1`
60 |
61 | Make Heads for another board (`XXX` should be the name of your board in ./boards and YY the number of CPUs you want to build with):
62 |
63 | ```shell
64 | ./docker_repro.sh make BOARD=XXX CPUS=YY
65 | ```
66 |
67 | The resulting rom file for a x86 board will be either `./build/x86/XXX/XXX.rom` or
68 | `./build/x86/XXX/heads-XXX-vYYYY-gZZZZZZZ.rom` (`XXX` should be the name of your board in
69 | `./boards, vYYYY the pinned Heads version and ZZZZZZ the commit id from which your build comes from`).
70 |
71 | Please continue to the corresponding flashing guide for your device.
72 |
73 | More options and detail about Heads modules under [Makefile]({{ site.baseurl }}/Makefile/)
74 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/Building-Heads/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Step 1 - Building Heads
4 | permalink: /Building/
5 | nav_order: 1
6 | parent: Installing and configuring
7 | has_children: yes
8 | ---
9 |
10 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/Building-Heads/p8z77-m_pro-tpm1.maximized.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Asus P8Z77-M Pro
4 | permalink: /p8z77-m_pro-building/
5 | nav_order: 1
6 | parent: Step 1 - Building Heads
7 | grand_parent: Installing and configuring
8 | ---
9 |
10 | ASUS P8Z77-M Pro
11 | ===
12 |
13 | This board currently supports TPMv1 modules, please note that TPM v2 module is not currently supported
14 | The following TPM modules have been tested and known to work: Asus branded TPM rev. 1.02H & Foxconn TPM Krypton rev. 1.0
15 |
16 | Please determine the [version]({{ site.baseurl }}/Prerequisites#supported-devices) you want to build (HOTP or not).
17 |
18 | 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.
19 |
20 | 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.
21 |
22 | 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.
23 |
24 | You can also [download the ROMs directly from CircleCI]({{ site.baseurl }}/Downloading)
25 |
26 | Please continue with the [flashing guide]({{ site.baseurl }}/Asus-p8z77-m_pro-flashing/)
27 |
28 | More options and detail about Heads modules under [Makefile]({{ site.baseurl }}/Makefile/)
29 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/Building-Heads/x230-maximized.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Lenovo X230 Maximized
4 | permalink: /x230-maximized-building/
5 | nav_order: 1
6 | parent: Step 1 - Building Heads
7 | grand_parent: Installing and configuring
8 | ---
9 |
10 | Lenovo X230 Maximized
11 | ====
12 |
13 | Please determine the [version]({{ site.baseurl }}/Prerequisites#supported-devices) you want to build (HOTP or not).
14 |
15 | For the Thinkpad x230 there are multiple maximized boards under `./boards`,
16 | x230-maximized, x230-hotp-maximized and usb-kb or edp-fhd variations.
17 |
18 | All those roms are externally flashable through their top and bottom rom images.
19 |
20 | As opposed to Legacy boards produced ROM images, Maximized boards produced ROMs
21 | are totally valid ROMs, including a valid Intel Flash Descriptor (IFD), Ethernet
22 | Intel Gigabit configuration flash space fiaxating MAC to DE:AD:C0:FF:EE,
23 | a valid neutered Intel ME containing only BUP+ROMP modules which liberated
24 | space is given back to the BIOS (coreboot+payload) region.
25 |
26 | x230 maximized boards need blobs to be downloaded and extracted from Lenovo prior
27 | of building the board configuration but those are managed by the board build, so see general builds instructions.
28 |
29 | Please refer to the [xx30 blobs documentation](https://github.com/osresearch/heads/blob/master/blobs/xx30/README),
30 |
31 | You can also [download the ROMs directly from CircleCI]({{ site.baseurl }}/Downloading)
32 |
33 |
34 | Please continue with the [flashing guide]({{ site.baseurl }}/x230-maximized-flashing/)
35 |
36 | More options and detail about Heads modules under [Makefile]({{ site.baseurl }}/Makefile/)
37 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/Downloading.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Step 1 - Downloading Heads
4 | nav_order: 2
5 | permalink: /Downloading
6 | parent: Installing and configuring
7 | ---
8 |
9 |
10 | 13 | Table of contents 14 |
15 | {: .text-delta } 16 | 1. TOC 17 | {:toc} 18 |
11 |
18 |
19 |
20 | Downloading Heads ROMs
21 | ===
22 |
23 | What board configuration should I choose?
24 | ---
25 | Please refer to the [devices compatibility matrix]({{ site.baseurl }}/Prerequisites#supported-devices).
26 |
27 | Downloading ROM files for initial flashing
28 | ---
29 | If you are performing an initial external flash, follow these steps to download the required ROM files and verify their integrity:
30 |
31 | 1. **Access CircleCI Builds**:
32 | - Go to the [Heads GitHub repository](https://github.com/linuxboot/heads) and click on the latest commit's green checkmark.
33 | 
34 | - This will display a list of CircleCI jobs. Locate the job corresponding to your board's name and click the "Details" link.
35 | 
36 |
37 | 2. **Navigate to Artifacts**:
38 | - On the CircleCI job page, click the "Artifacts" tab to view the output files of the build.
39 | 
40 |
41 | 3. **Download Required Files**:
42 | - Download the following files by right-clicking their links and selecting "Save Link as...":
43 | 
44 | - `*.rom` files (e.g., `top.rom` and `bottom.rom` for two SPI chip boards).
45 | - `hashes.txt` file containing the SHA256 hashes of the ROM files.
46 |
47 | 4. **Verify ROM File Integrity**:
48 | - Use `sha256sum` or an equivalent tool to compute the hash of the downloaded ROM files.
49 | - Compare the computed hash with the corresponding entry in the `hashes.txt` file to ensure the files are valid.
50 |
51 | 5. **Prepare for Flashing**:
52 | - Save the verified ROM files and `hashes.txt` to the computer or USB drive that will be used for external flashing.
53 |
54 | For more details on external flashing, refer to the [Upgrading documentation]({{ site.baseurl }}/Updating).
55 |
56 | Internal upgrading from ZIP files
57 | ---
58 | If you are upgrading an existing Heads installation, you can use the ZIP file provided in the CircleCI artifacts:
59 |
60 | 1. **Download the ZIP File**:
61 | - From the CircleCI "Artifacts" tab, download the ZIP file corresponding to your board.
62 |
63 | 2. **Transfer to Target System**:
64 | - Save the ZIP file to a USB drive and transfer it to the target system.
65 |
66 | 3. **Perform the Upgrade**:
67 | - Use the Heads GUI to upgrade the firmware by selecting the ZIP file. This method automatically verifies the ROM integrity and flashes the firmware.
68 |
69 | **Note**: Internal upgrading via ZIP files is supported for firmware versions built after [this November 2023 commit](https://github.com/linuxboot/heads/commit/6873df60c1c965ac812a49d9d245f338d8a3b128).
70 |
71 | For more details on internal upgrading, refer to the [Upgrading documentation]({{ site.baseurl }}/Updating).
72 |
73 | Caution for Rolling Releases
74 | ---
75 | Heads is a rolling release. If you do not have an external programmer, refer to the [Upgrading documentation]({{ site.baseurl }}/Updating#global-warning-no-hardware-programmer-be-cautious) for important precautions before upgrading. This includes:
76 | - Waiting for community testing and reviewing reported issues to avoid potential regressions.
77 | - Understanding the implications of `UNTESTED` and `UNMAINTAINED` labels in board names. For more details, refer to the [UNTESTED and UNMAINTAINED boards documentation](https://github.com/linuxboot/heads/blob/master/unmaintained_boards/README.md).
78 |
79 | For more details on upgrading, refer to the [Upgrading documentation]({{ site.baseurl }}/Updating).
80 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/Flashing-Guides/Clean-the-ME-firmware.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Cleaning Intel Management Engine
4 | permalink: /Clean-the-ME-firmware/
5 | nav_order: 99
6 | parent: Step 2 - Flashing Guides
7 | grand_parent: Installing and configuring
8 | ---
9 |
10 | What is the Intel Management Engine
11 | ===
12 |
13 | The Intel ME is a coprocessor, running inside your Intel CPU, which is supposed
14 | to function as a out-of-band management system for your computer.
15 | It's based on a ARC/i386 core depending of the version, can be powered even when
16 | the main CPU is off and has more privileges than the CPU itself.
17 | More info: [Intel Active Management Technology](https://en.wikipedia.org/wiki/Intel_Active_Management_Technology)
18 |
19 | How to disable/deactive most of it
20 | ===
21 |
22 | ***ALL MAXIMIZED BOARDS DO THE NEUTERING AUTOMATICALLY WHEN YOU BUILD THE BOARD. SEE GENERAL BUILDING GUIDE***
23 |
24 | The ME firmware sits on the second SPI flash chip of the x230 (the 8MB one). We
25 | cannot remove it completely, otherwise the machine will shut itself off after
26 | 30 minutes. We can, however, reduce it to the bare minimum necessary to keep it
27 | running, but without any malicious code in it (or so we hope, depending of what
28 | the ROMP and BUP modules really do...).
29 |
30 | The initial step is to upgrade the proprietary BIOS to the last upgradeable
31 | version one for each platform.
32 | As an example, for the x230, the latest upgradeable version would be
33 | [version 2.76](https://download.lenovo.com/pccbbs/mobiles/g2uj32us.iso) without
34 | [EC signature verification](https://support.lenovo.com/us/en/solutions/len-27764)
35 | . Newer firmware version [won't permit to swap a x220 keyboard on the x230](https://github.com/hamishcoleman/thinkpad-ec/pull/130)
36 | .
37 |
38 | Prepare a USB bootable disk by following
39 | [el torito instructions](https://askubuntu.com/questions/651281/write-bootable-bios-update-iso-to-usb-stick)
40 | , then boot that prepared USB disk and upgrade the prioprietary firmware to
41 | latest available version following on screen instructions. Be sure to have a
42 | fully charged battery, be connected to power source prior of attempting to
43 | upgrade, else you will have to wait for the battery to be changed.
44 |
45 | Once the proprietary firmware is updated to the latest available user ownable
46 | version, take a flash dump of the bottom SPI chip and verify that its backup is
47 | valid.
48 |
49 | Flashrom can be downloaded on most linux distribution on the external laptop
50 | that will be used to flash the cleaned rom. (`sudo dnf install flashrom` or
51 | `sudo apt-get install flashrom`.
52 |
53 | With a ch341a programmer, the command would look like the following:
54 |
55 | ```shell
56 | sudo flashrom -r ~/down.rom --programmer ch341a_spi && \
57 | sudo flashrom -v ~/down.rom --programmer ch341a_spi
58 | ```
59 |
60 | If they match, clone this repo:
61 | `https://github.com/corna/me_cleaner.git`
62 | and then run:
63 | `python ~/me_cleaner/me_cleaner.py -c flash.bin`
64 | to check if it's a valid ME firmware.
65 | The output should be like:
66 |
67 | ```text
68 | Full image detected
69 | The ME/TXE region goes from 0x3000 to 0x4ff000
70 | Found FPT header at 0x3010
71 | Found 23 partition(s)
72 | Found FTPR header: FTPR partition spans from 0x183000 to 0x24d000
73 | ME/TXE firmware version 8.1.30.1350
74 | Checking FTPR RSA signature... VALID
75 | ```
76 |
77 | If it's not, replace the reprogrammer clip and try again :)
78 |
79 | Next, unlock the descriptor and ME regions with ifdtool. We consider here that
80 | you already build Heads through `make BOARD=x230`:
81 | `~/heads/build/x86/coreboot-4.13/util/ifdtool/ifdtool -u down.rom`
82 | This produced a new unlocked rom under `down.rom.new`
83 |
84 | Next, let's strip all the nasty bits:
85 |
86 |
87 |
88 | ```shell
89 | python ~/me_cleaner/me_cleaner.py -r -t -d -S -O clean_flash.bin down.rom.new --extract-me extracted_me.rom
90 | ```
91 |
92 |
93 |
94 | Output:
95 |
96 | ```text
97 | Full image detected
98 | The ME/TXE region goes from 0x3000 to 0x4ff000
99 | Found FPT header at 0x3010
100 | Found 23 partition(s)
101 | Found FTPR header: FTPR partition spans from 0x183000 to 0x24d000
102 | ME/TXE firmware version 8.1.30.1350
103 | Removing extra partitions...
104 | Removing extra partition entries in FPT...
105 | Removing EFFS presence flag...
106 | Removing ME/TXE R/W access to the other flash regions...
107 | Correcting checksum (0x7b)...
108 | Reading FTPR modules list...
109 | UPDATE (LZMA , 0x1cf4f2 - 0x1cf6b0): removed
110 | ROMP (Huffman, fragmented data ): NOT removed, essential
111 | BUP (Huffman, fragmented data ): NOT removed, essential
112 | KERNEL (Huffman, fragmented data ): removed
113 | POLICY (Huffman, fragmented data ): removed
114 | HOSTCOMM (LZMA , 0x1cf6b0 - 0x1d648b): removed
115 | RSA (LZMA , 0x1d648b - 0x1db6e0): removed
116 | CLS (LZMA , 0x1db6e0 - 0x1e0e71): removed
117 | TDT (LZMA , 0x1e0e71 - 0x1e7556): removed
118 | FTCS (Huffman, fragmented data ): removed
119 | ClsPriv (LZMA , 0x1e7556 - 0x1e7937): removed
120 | SESSMGR (LZMA , 0x1e7937 - 0x1f6240): removed
121 | Relocating FTPR from 0xd00 - 0xcad00 to 0xd00 - 0xcad00...
122 | Adjusting FPT entry...
123 | Adjusting LUT start offset...
124 | Adjusting Huffman start offset...
125 | Adjusting chunks offsets...
126 | Moving data...
127 | The ME minimum size should be 98304 bytes (0x18000 bytes)
128 | The ME region can be reduced up to:
129 | 00003000:0001afff me
130 | Setting the AltMeDisable bit in PCHSTRP10 to disable Intel ME...
131 | Removing ME/TXE R/W access to the other flash regions...
132 | Extracting and truncating the ME image to "extracted_me.rom"...
133 | Checking the FTPR RSA signature of the extracted ME image... VALID
134 | Checking the FTPR RSA signature... VALID
135 | Done! Good luck!
136 | ```
137 |
138 | After that, you got your new, cleaned up version of the ME firmware inside
139 | clean_flash.bin
140 | Flash it back on the SPI:
141 |
142 | `sudo flashrom -w clean_flash.bin --programmer ch341a_spi`
143 |
144 | You're now good to go :)
145 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/Flashing-Guides/T420-maximized.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Lenovo T420 Maximized
4 | permalink: /T420-maximized-flashing/
5 | nav_order: 1
6 | parent: Step 2 - Flashing Guides
7 | grand_parent: Installing and configuring
8 | ---
9 |
10 | Lenovo T420 (Maximized)
11 | ===
12 |
13 | [T420 Hardware Maintenance Manual](https://download.lenovo.com/pccbbs/mobiles_pdf/t420_and_t420i_ug_en.pdf)
14 |
15 | The thinkpad T420 has only one SPI flash chip that hold the BIOS, ME, etc. It is located under the palm rest. Similarly to the T430, to access this chip complete disassembly is required. It is a straightforward process and takes approximately 30 minutes. For this follow the T430/x230 guide.
16 |
17 | [Here](https://www.coreboot.org/Board:lenovo/t420) is the location of the chip. At some models the location of the dot where the red wire from programmer should go may be misleading. The dot you need is just black.
18 |
19 | 
20 |
21 | You should then follow through with [configuring keys]({{ site.baseurl }}/Configuring-Keys/).
22 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/Flashing-Guides/T430-maximized.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Lenovo T430 Maximized
4 | permalink: /T430-maximized-flashing/
5 | nav_order: 1
6 | parent: Step 2 - Flashing Guides
7 | grand_parent: Installing and configuring
8 | ---
9 |
10 | Lenovo T430 (Maximized)
11 | ===
12 |
13 | [T430 Hardware Maintenance Manual](https://download.lenovo.com/ibmdl/pub/pc/pccbbs/mobiles_pdf/t430_t430i_hmm_en_0b48304_04.pdf)
14 |
15 | 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.
16 |
17 | First remove the battery and the cable powering your device.
18 |
19 | 
20 |
21 | Removing these screws will allow you to remove the keyboard and palm rest.
22 |
23 | 
24 |
25 | First, slightly shift the keyboard towards the screen.
26 |
27 | 
28 | The keyboard is connected to the motherboard by a ribbon cable which easily
29 | detaches from the motherboard.
30 |
31 | 
32 |
33 | Remove these screws in order to remove the palm-rest.
34 |
35 | 
36 |
37 | The palm-rest is removed. Removing these screws will allow you to further detach the screen and the CPU cooler.
38 |
39 | 
40 |
41 | The screen and CPU with left speaker are removed.
42 |
43 | 
44 |
45 | Flip the board and remove these screws too. This should allow you to get rid of the aluminium part to access the SPI flash chips.
46 |
47 | 
48 |
49 | Flip the board again. The SPI flash chips are located under this plastic.
50 |
51 | 
52 |
53 | Left chip corresponds to the "bottom" flash chip (8192 kb) and right corresponds to the "top" (4096 kb) chip, respectively. The top chip is 4MB and contains the BIOS and reset vector. The bottom chip is 8MB and has the [Intel Management Engine (ME)](https://www.flashrom.org/ME) firmware, plus the flash descriptor. To be on the safe side, you may want to disconnect CMOS battery before next steps.
54 |
55 | 
56 |
57 |
58 | 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.
59 |
60 |
61 | 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.
62 |
63 | 
64 |
65 | 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.
66 |
67 | 
68 |
69 | Use flashrom to check the chip that you are connected to:
70 |
71 | ```shell
72 | sudo flashrom -p ch341a_spi
73 | ```
74 |
75 |
76 | Here is my output.
77 |
78 | 
79 |
80 | Find the chip and read from it twice (For me the SPI flash chip is `YYY`):
81 |
82 | ```shell
83 | sudo flashrom -r ~/top.bin --programmer ch341a_spi -c YYY && \
84 | sudo flashrom -v ~/top.bin --programmer ch341a_spi -c YYY
85 | ```
86 |
87 | If the files differ then try reconnecting your programmer to the SPI flash chip
88 | and make sure your flashrom software is up to date.
89 |
90 |
91 | If they are the same then write `t430-maximized-top.rom` to the SPI flash chip:
92 |
93 | ```shell
94 | sudo flashrom -p ch341a_spi -c YYY -w ~/heads/build/x86/t430-maximized/t430-maximized-top.rom
95 | ```
96 |
97 | While everything goes well you should see the blue LED on the programmer.
98 |
99 | 
100 |
101 |
102 | Here is a successful attempt.
103 |
104 | 
105 |
106 |
107 | Try to read the name on the bottom SPI flash chip. Then, connect the clip and
108 | ch341a programmer to the bottom SPI flash chip.
109 |
110 | 
111 |
112 | Use flashrom to check the chip that you are connected to:
113 |
114 | ```shell
115 | sudo flashrom -p ch341a_spi
116 | ```
117 |
118 | Here is my output.
119 |
120 | 
121 |
122 | Find the chip and read from the chip twice (For me the SPI flash chip is `ZZZ`):
123 |
124 | ```shell
125 | sudo flashrom -r ~/bottom.bin --programmer ch341a_spi -c ZZZ && \
126 | sudo flashrom -v ~/bottom.bin --programmer ch341a_spi -c ZZZ
127 | ```
128 |
129 | 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:
130 | ```shell
131 | sudo flashrom -p ch341a_spi -c ZZZ -w ~/heads/build/x86/t430-maximized/t430-maximized-bottom.rom
132 | ```
133 |
134 | If all goes well, you should see the keyboard LED flash, and within a second Heads will boot in its GUI.
135 |
136 | 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.
137 |
138 | You should then follow through with [configuring keys]({{ site.baseurl }}/Configuring-Keys/).
139 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/Flashing-Guides/T480-maximized.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Lenovo T480 Maximized
4 | permalink: /T480-maximized-flashing/
5 | nav_order: 1
6 | parent: Step 2 - Flashing Guides
7 | grand_parent: Installing and configuring
8 | ---
9 |
10 | Lenovo T480 (Maximized)
11 | ===
12 |
13 | [T480 Hardware Maintenance Manual](https://download.lenovo.com/pccbbs/mobiles_pdf/t480_hmm_en.pdf)
14 |
15 | Accessing and flashing the BIOS chip on a T-series machine has never been easier. The process is straightforward and takes approximately 10 minutes.
16 |
17 | The ThinkPad T480 has two SPI flash chips important for the port. The first chip holds the BIOS, ME, etc., while the second holds the Thunderbolt firmware. To access these chips, you only need to remove the back panel, which is secured by six screws.
18 |
19 | For whole procedure you will need:
20 | - A Phillips screwdriver +1 (PH1), which is standard for most laptop screws.
21 | - An assembled Raspberry Pi or CH341A SPI programmer. You should use a CH341A revision 1.6 or later (e.g., 1.6, 1.7, etc.) because these versions have a properly implemented and enforced voltage regulator, ensuring stable 3.3V operation (3.3V is important!) (e.g. [Modified CH341A SPI programmer](https://novacustom.com/product/modded-ch341a-bios-firmware-programmer-3v/) by Novacustom) or [open-source Tigard tool](https://github.com/tigard-tools/tigard). Using Raspberry Pi pico is described in the [Libreboot flash guide](https://libreboot.org/docs/install/spi.html).
22 | - Other laptop/PC with a Linux-based OS installed.
23 | - Optional: A plastic guitar pick or an old credit card to help detach the bottom case from the clips holding it in place. Otherwise, it can be difficult to remove, increasing the risk of breaking the tabs or the top part of the bottom case above the battery connector.
24 |
25 | There is still debate over which programmer and software should be used (flashprog vs. flashrom). Before following this guide, make sure you read [README.md](https://github.com/linuxboot/heads/tree/master/blobs/xx80/README.md) and the related information.
26 |
27 | Some ThinkPad T480 units on the used market are affected by an Intel bug in the Thunderbolt firmware. In short, the flash chip becomes full, causing Thunderbolt fast charging to stop working, though slow charging still functions. This issue can also affect the USB-C port. For convenience, Heads provides a fixed and padded Thunderbolt firmware that resolves the "charging problem" if your laptop is affected. Board testers did not encounter this issue, and it is unlikely to occur if your laptop was in use for more than 12 months before flashing. If you do experience the "charging bug," it is possible to fix it with external flashing. Also, the update is possible prior flashing heads using [fwupd from a Linux distribution](https://www.reddit.com/r/thinkpad/comments/12tf6xv/psa_t480_thunderbolt_controller_v23_is_now_on/?rdt=44850)
28 |
29 | 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.
30 |
31 | ## Flashing Heads
32 |
33 | First, remove the battery 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.
34 |
35 | 
36 |
37 | The back panel and the battery are removed. Important, ensure that all batteries, including the CMOS battery, are disconnected. Arrows indicate the direction you should pull the connectors. Pull the plastic part, not the wires, as the wires are thin and can be damaged.
38 |
39 | 
40 |
41 | The top-right chip corresponds to the Thunderbolt SPI flash chip (1 MB). The chip located in the middle of the board corresponds to the BIOS (16 MB) chip, respectively.
42 |
43 | The chip located in the middle of the board contains the [Intel Management Engine (ME)](https://www.flashrom.org/ME) firmware.
44 |
45 | 
46 |
47 | 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 board rom for this board and verify its hash value.
48 |
49 | Try to read the name of the SPI flash chip. The dot on the chip helps to identify the correct clip orientation.
50 |
51 | 
52 |
53 | First, connect the clip of the CH341A programmer to the chip. Next, connect the programmer to the USB port of your other Linux-based computer with flashrom installed. In my setup, the red wire should be where the dot is (the dot indicates pin 1). Here, please also see the flashing guide for the T430.
54 |
55 | Use flashrom to check the chip you are connected to:
56 |
57 | ```shell
58 | sudo flashrom -p ch341a_spi
59 | ```
60 |
61 | Here is my output.
62 |
63 | 
64 |
65 | Read from the chip twice (where the name of the flash chip is `YYY`):
66 |
67 | ```shell
68 | sudo flashrom -r ~/t480_original_bios.bin --programmer ch341a_spi -c YYY
69 | ```
70 |
71 | First output can be seen here.
72 | 
73 |
74 | ```shell
75 | sudo flashrom -r ~/t480_original_bios_1.bin --programmer ch341a_spi -c YYY
76 | ```
77 | Second output can be seen here.
78 | 
79 |
80 | Make sure that the dump matches the chip content. If this is the case, the output of the following command will state `Verifying flash... VERIFIED`
81 |
82 | ```shell
83 | sudo flashrom -v ~/t480_original_bios.bin --programmer ch341a_spi -c YYY
84 | ```
85 | Make sure that files do not differ.
86 |
87 | ```shell
88 | sha256sum t480_original_bios.bin
89 | sha256sum t480_original_bios_1.bin
90 | ```
91 |
92 | My dumps were the same.
93 | 
94 |
95 | Alternative comparison is bit-by-bit. If the files are the same, there should be no output of this command. Otherwise, you will see a bit-by-bit difference between the files.
96 |
97 | ```shell
98 | diff <(hexdump -C t480_original_bios.bin) <(hexdump -C t480_original_bios_1.bin)
99 | ```
100 |
101 | If the files differ or the chip content does not match the dump, try reconnecting your programmer to the SPI flash chip and make sure your flashrom/flashprog software is up-to-date.
102 |
103 |
104 | If they are the same, then write `T480-hotp-maximized.rom` to the SPI flash chip:
105 |
106 | ```shell
107 | sudo flashrom -p ch341a_spi -c YYY -w ~/heads/build/x86/T480-hotp-maximized/T480-hotp-maximized.rom
108 | ```
109 |
110 | Here is a successful attempt. Be patient, it may take a while.
111 | 
112 |
113 | If all goes, well you can connect the battery, press the power button and you should see the keyboard LED flash. After that, Heads will boot into its GUI.
114 |
115 | Two reboots are sometimes needed after flashing. Force a power off by holding the power button for 10 seconds. Since the memory training data was wiped by the content of the fully flashed ROM, this is normal.
116 |
117 | You should then follow through with [configuring keys]({{ site.baseurl }}/Configuring-Keys/).
118 |
119 | ## Flash Thunderbolt firmware
120 | Important, ensure that power supply and all batteries, including the CMOS battery, are disconnected. After connecting the clip to the Thunderbolt chip as shown in the figure above read from the chip, making sure the connection is stable. The procedure is similar to the flashing Heads on the SPI chip. Therefore, comments are skipped.
121 |
122 | ```shell
123 | sudo flashrom -r ~/t480_original_tb.bin --programmer ch341a_spi -c YYY
124 | ```
125 |
126 | ```shell
127 | sudo flashrom -r ~/t480_original_tb_1.bin --programmer ch341a_spi -c YYY
128 | ```
129 |
130 | ```shell
131 | sudo flashrom -v ~/t480_original_tb.bin --programmer ch341a_spi -c YYY
132 | ```
133 |
134 | ```shell
135 | sha256sum t480_original_tb.bin
136 | sha256sum t480_original_tb_1.bin
137 | ```
138 |
139 | ```shell
140 | diff <(hexdump -C t480_original_tb.bin) <(hexdump -C t480_original_tb_1.bin)
141 | ```
142 |
143 | Flash the padded Thunderbolt firmware. The firmware file tb.bin is located in the blobs folder after you build the Heads locally, or in the CircleCI artifacts.
144 |
145 | ```shell
146 | sudo flashrom -p ch341a_spi -c YYY -w ~/tb.bin
147 | ```
148 | Done.
149 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/Flashing-Guides/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Step 2 - Flashing Guides
4 | permalink: /Flashing-guides
5 | nav_order: 2
6 | parent: Installing and configuring
7 | has_children: yes
8 | ---
9 |
10 | - [The internal flashing commands for Purism devices can be found here](https://docs.puri.sm/PureBoot/Heads/User_Manual.html#flash-the-compiled-heads-rom-to-your-hardware)
11 | - External x230/t430 flashing can be found through Nitrokey, which supports x230/t430 sells, at
12 |
13 | - [Video showing how to properly connect a SOIC "Pamona" clip once motherboard SPI chips accessible](https://user-images.githubusercontent.com/827570/203147231-4791a1f1-bb9b-4373-9b4c-309bb3611c8b.mp4)
14 |
15 | - [Video showing how to automatize SPI chip detection upon correct SOIC clip connection](https://user-images.githubusercontent.com/827570/203147643-528e9828-2666-4bd6-900f-3b915a11f633.mp4)
16 |
17 | TODO: Add WSON
18 | TODO: Add guides for total disassembly as community effort
19 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/Flashing-Guides/x230-maximized.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Lenovo X230 Maximized
4 | permalink: /x230-maximized-flashing/
5 | nav_order: 1
6 | parent: Step 2 - Flashing Guides
7 | grand_parent: Installing and configuring
8 | ---
9 |
10 | Lenovo X230 (Maximized) (applies to all 4mb+8mb SPI chips maximized boards)
11 | ===
12 |
13 | [X230 Hardware Maintenance Manual](https://web.archive.org/web/20201112030049/https://thinkpads.com/support/hmm/hmm_pdf/x230_x230i_hmm_en_0b48666_01.pdf)
14 | [X230 Tablet Hardware Maintenance Manual](https://web.archive.org/web/20130908100917/http://download.lenovo.com/pccbbs/mobiles_pdf/0b48730.pdf)
15 |
16 | 
17 |
18 | First remove the battery or cable powering your device. The Thinkpad x230 has
19 | two SPI flash chips that hold the BIOS, ME, etc. and are located under the
20 | palm rest. To access these chips, first remove the indicated screws on the back
21 | of the laptop.
22 |
23 | 
24 |
25 | Removing these screws will allow you to remove the keyboard and palm rest.
26 |
27 | 
28 |
29 | The keyboard is connected to the motherboard by a ribbon cable which easily
30 | detaches from the motherboard. (The keyboard only needs to be removed so that
31 | the palm rest can be removed. After removing the palm rest, you can put the
32 | keyboard back.)
33 |
34 | The palm rest is also connected to the motherboard, but there is a little latch
35 | holding its ribbon cable. After undoing that latch, the palm rest should be
36 | fairly easy to remove.
37 |
38 | Pull up the black plastic on the bottom right of the palm rest to reveal the two
39 | SPI flash chips.
40 |
41 | 
42 |
43 | The top chip is 4MB and contains the BIOS and reset vector. The bottom chip is
44 | 8MB and has the [Intel Management Engine (ME)](https://www.flashrom.org/ME)
45 | firmware, plus the flash descriptor.
46 |
47 | Based on [the work done here](https://github.com/osresearch/heads/issues/716),
48 | the chips should be one 4M and one 8M of the following:
49 |
50 | |Vendor|Device| size|
51 | |---|---|---|
52 | |Eon | EN25QH32 | 4M|
53 | |Eon| EN25QH64 | 8M|
54 | |Macronix|MX25L3206E - MX25L3206E/MX25L3208E|4M|
55 | |Macronix|MX25L6405,MX25L6405D, MX25L6406E/MX25L6408E, MX25L6436E/MX25L6445E/MX25L6465E/MX25L6473E/MX25L6473F, MX25L6495F|8M|
56 | |Micron/Numonyx/ST|N25Q032..1E, N25Q032..3E|4M|
57 | |Micron/Numonyx/ST|N25Q064..1E, N25Q064..3E|8M|
58 | |Winbond | W25Q32.V, W25Q32.W | 4M|
59 | |Winbond | W25Q64.V, W25Q32.W | 8M|
60 |
61 | First [download]({{ site.baseurl }}/Downloading) / [build]({{ site.baseurl }}/x230-maximized-building/) the maximized board roms (top and bottom) for this board and verify their hashes.
62 |
63 |
64 | Try to read the name on the top SPI flash chip. Then, connect the clip and
65 | ch341a programmer to the top SPI flash chip. Use flashrom to check the chip
66 | that you are connected to:
67 |
68 | ```shell
69 | sudo flashrom -p ch341a_spi
70 | ```
71 |
72 | Find the chip and read from it twice (For me the SPI flash chip is `YYY`):
73 |
74 | ```shell
75 | sudo flashrom -r ~/top.bin --programmer ch341a_spi -c YYY && \
76 | sudo flashrom -v ~/top.bin --programmer ch341a_spi -c YYY
77 | ```
78 |
79 | If the files differ then try reconnecting your programmer to the SPI flash chip
80 | and make sure your flashrom software is up to date.
81 |
82 | If they are the same then write `x230-maximized-top.rom` to the SPI flash chip:
83 |
84 | ```shell
85 | sudo flashrom -p ch341a_spi -c “YYY” -w ~/heads/build/x86/x230-maximized/x230-maximized-top.rom
86 | ```
87 |
88 | Try to read the name on the bottom SPI flash chip. Then, connect the clip and
89 | ch341a programmer to the bottom SPI flash chip. Use flashrom to check the chip
90 | that you are connected to:
91 |
92 | ```shell
93 | sudo flashrom -p ch341a_spi
94 | ```
95 |
96 | Find the chip and read from the chip twice (For me the SPI flash chip is `ZZZ`):
97 |
98 | ```shell
99 | sudo flashrom -r ~/bottom.bin --programmer ch341a_spi -c ZZZ && \
100 | sudo flashrom -v ~/bottom.bin --programmer ch341a_spi -c ZZZ
101 | ```
102 |
103 | The 8M bottom chip contains the ME firmware. It is neutralized in maximized version.
104 | You can flash it specifying the same chip you found under ZZZ:
105 | ```shell
106 | sudo flashrom -p ch341a_spi -c “ZZZ” -w ~/heads/build/x86/x230-maximized/x230-maximized-bottom.rom
107 | ```
108 |
109 |
110 | If all goes well, you should see the keyboard LED flash, and within a second Heads will boot
111 | in its GUI.
112 |
113 | Two reboots are sometimes needed after flash. Force power off by holding the power button for
114 | 10 seconds. Since the memory training data was wiped by the content of the full flashed ROM,
115 | this is normal.
116 |
117 | You should then follow through with [configuring keys]({{ site.baseurl }}/Configuring-Keys/).
118 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/GPG.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: GPG Generation
4 | permalink: /GPG
5 | nav_order: 11
6 | nav_exclude: true
7 | ---
8 |
9 | Generating a new card
10 | ===
11 |
12 | ```shell
13 | diamond:~/clean/heads: gpg --card-edit --homedir ./initrd/.gnupg
14 |
15 | gpg: detected reader `Yubico Yubikey NEO OTP+CCID 00 00'
16 | Application ID ...: D2760001240102000006053147090000
17 | Version ..........: 2.0
18 | Manufacturer .....: unknown
19 | Serial number ....: 05314709
20 | Name of cardholder: [not set]
21 | Language prefs ...: [not set]
22 | Sex ..............: unspecified
23 | URL of public key : [not set]
24 | Login data .......: [not set]
25 | Signature PIN ....: forced
26 | Key attributes ...: 2048R 2048R 2048R
27 | Max. PIN lengths .: 127 127 127
28 | PIN retry counter : 3 3 3
29 | Signature counter : 0
30 | Signature key ....: [none]
31 | Encryption key....: [none]
32 | Authentication key: [none]
33 | General key info..: [none]
34 |
35 | gpg/card> admin
36 | Admin commands are allowed
37 |
38 | gpg/card> generate
39 | Make off-card backup of encryption key? (Y/n) n
40 |
41 | Please note that the factory settings of the PINs are
42 | PIN = `123456' Admin PIN = `12345678'
43 | You should change them using the command --change-pin
44 |
45 | gpg: 3 Admin PIN attempts remaining before card is permanently locked
46 |
47 | Please enter the Admin PIN
48 |
49 | Please enter the PIN
50 | Please specify how long the key should be valid.
51 | 0 = key does not expire
52 | 12 | Table of contents 13 |
14 | {: .text-delta } 15 | 1. TOC 16 | {:toc} 17 |
11 |
18 |
19 |
20 | Prerequisites for Heads
21 | ===
22 |
23 | Required equipment
24 | ---
25 |
26 | To install Heads on a physical device, you will need:
27 |
28 | * Supported motherboard or laptop ([see below](#supported-devices))
29 | * A heads compatible USB security dongle ([see below](#usb-security-dongles-aka-security-token-aka-smartcard))
30 | * A heads compatible storage device for your public GPG key (USB flash drive)
31 |
32 | If your device requires external flashing ([see below](#supported-devices)),
33 | you will also need:
34 |
35 | * [SPI Programmer](https://trmm.net/SPI_flash): green pcb ch341a programmer or raspberry
36 | pi or bus pirate (green ch341a is recommended for new users and can be found almost
37 | [anywhere with preassembled clip as a kit](https://www.amazon.com/s?k=ch341a+programmer).
38 | * [Beware that black ch341a are known to not provide 3.3V as most NOR chips requires and should me manually fixed. If you intend to use a ch341a for initial flashing and occasional unbricking, this is perfectly fine without modification. Otherwise, you should look into other programmers or do the fix yourself. A lot of people suggest against using ch341a unless modified.](https://libreboot.org/docs/install/spi.html#do-not-use-ch341a)
39 | * Wires and a clip SOIC8 to connect your programmer of choice to the board’s
40 | SPI flash chip(s).
41 | * The [Pomona 5250](https://www.pomonaelectronics.com/products/test-clips/soic-clip-8-pin)
42 | is suggested as it is high quality and easier to make contact with the pins.
43 | * A second computer to flash from (Try to use a recommended operating system:
44 | Qubes or Debian 9 or Fedora 30)
45 |
46 | Supported devices
47 | ---
48 |
49 | **Please see the current [heads source](https://github.com/osresearch/heads/tree/master/boards) for up-to-date supported board configurations.**
50 |
51 | *Note* repeatedly untested boards from willing to test board owners were moved to [unmaintained_boards directory and aren't built by CircleCI anymore](https://github.com/linuxboot/heads/tree/master/unmaintained_boards)
52 |
53 | If *you have an external programmer* and *are techsavvy enough to bring their support back yourself*, read the [Community page](/community/) and reach out. I will gladly assist in your quest :)
54 |
55 | USB Security Dongles (aka security token aka smartcard)
56 | ---
57 |
58 | *NOTE* - Heads does **NOT** support FIDO2 or U2F authentication. Be careful when
59 | purchasing to buy a compatible key.
60 |
61 | *NOTE* - HOTP remote attestation is supported from Librem/NovaCustom/Nitropad platforms by default,
62 | Otherwise HOTP is explicitely supported by board configurations having `hotp` in their [board names](/Prerequisites#supported-devices).
63 |
64 | *NOTE* - The NitroKey 3 comes in three sizes: USB A, A-mini and C. Nk3a mini (USB A-mini) is the one most shipped with novacustom and nitropads.
65 | - ThinkPads have USB A ports, not C. After that, it's users preferences for the form factor desired.
66 |
67 | |Manufacture|Model line|TOTP|HOTP|
68 | |--|--|:--:|:--:|
69 | |Yubico|[YubiKey 5 Series](https://www.yubico.com/products/yubikey-5-overview/)|X||
70 | |Nitrokey|[Nitrokey Pro 2](https://www.nitrokey.com/products/nitrokeys#comparison)|X|X|
71 | |Nitrokey|[Nitrokey Storage 2](https://www.nitrokey.com/products/nitrokeys#comparison)|X|X|
72 | |Nitrokey|[Nitrokey 3](https://www.nitrokey.com/products/nitrokeys#comparison)|X|X|
73 | |Purism|[Librem Key](https://puri.sm/products/librem-key/)|X|X|
74 |
75 | Legacy vs Maximized boards
76 | ===
77 | Some history first on the historical x230-flash and x230 boards that initially created the Heads project.
78 |
79 | Heads was initially developped on the x230 board (first xx30 board supported).
80 |
81 | At that time, ME cleaning/neutering was not a thing. Then me_cleaner facilitated the task.
82 | [The X230 board, as all xx30 family boards do not have a single SPI flash, but two.
83 | 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)
84 |
85 | 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.
86 |
87 | 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.
88 |
89 | 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.
90 |
91 | *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.*
92 |
93 | 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.
94 |
95 | 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
96 |
97 | Current Legacy boards
98 | ---
99 | 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.
100 |
101 | 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.
102 |
103 | 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.
104 |
105 | 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.
106 |
107 | Current Maximized boards
108 | ---
109 | 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
110 | 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.
111 |
112 | 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.
113 |
114 | Legacy to Maximized boards upgrade path
115 | ---
116 | It is possible to upgrade from Legacy to Maximized boards under certain conditions.
117 |
118 | *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.
119 |
120 | 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.
121 |
122 | If coming from Skulls or Heads Legacy board configurations while having unlocked IFD initially, you can flash from the recovery shell manually.
123 | [**IF UNSURE, PLEASE VERIFY FIRST**](/Updating#verify-upgradeability-paths-of-the-firmware)
124 |
125 | 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:
126 | ```
127 | mount-usb
128 | flashrom -p internal -w /media/PathToMaximizedRom.rom
129 | ```
130 | 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.
131 |
132 | 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.
133 |
134 | 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.
135 |
136 | Emulated devices
137 | ===
138 |
139 | For further information, see [Emulating Heads](/Emulating-Heads/)
140 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/RecoveryShell.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Heads Recovery Shell
4 | permalink: /RecoveryShell/
5 | nav_order: 90
6 | has_children: false
7 | has_toc: false
8 | parent: Installing and configuring
9 | ---
10 |
11 | Heads Recovery Shell
12 | ====
13 |
14 | The recovery shell is a command line environment where heads and *nix utilities may be accessed (see [modules](https://github.com/osresearch/heads/tree/master/modules)) This document is a work in progress.
15 |
16 | Overview
17 | ---
18 |
19 | The recovery shell is running a Linux kernel and shell based on busybox. The environment comes from the initrd image flashed into the BIOS with the Linux kernel. i.e. Heads
20 |
21 | The shell can be used to troubleshoot Heads. The security dongle paired with Heads may be needed to effectively use this environment.
22 |
23 |
24 | Access
25 | ----
26 |
27 | The recovery shell may be accessed using two different methods.
28 |
29 | 1. at power-on repeatedly press 'r' before the GUI loads
30 | 2. select the recovery shell menu in the Heads GUI
31 |
32 | These two different methods of access will result in some different settings.
33 |
34 |
35 | Limitations
36 | ----
37 |
38 | The recovery shell wipes secrets--normally used for security checks--that were [computed](/Keys/#tpm-pcrs) from the BIOS, kernel modules loaded, etc. This will limit sealing/unsealing functions (Disk Unlock Key creation, TOTP/HOTP sealing) from the recovery shell environment. To seal/unseal secrets, the same measurements needs to be calculated, which would be different depending of the kernel modules loaded and if going in/out of the recovery shell, which invalidates per design the TPM measurements to not release secrets.
39 |
40 | To seal/unseal secrets, use the GUI environment.
41 |
42 |
43 | Boot Process
44 | ----
45 |
46 | To troubleshoot you should understand the processes used to configure and boot Heads after flashing it into the BIOS.
47 |
48 | ### configuration
49 |
50 | * First Boot Checks
51 | * set default boot and flash BIOS (again)
52 | * Reset the TPM
53 | * sign files in /boot
54 | * reset htop/totp
55 |
56 | ### boot
57 |
58 | * mount default boot
59 | * check signatures
60 | * check hotp
61 | * menus and user interaction
62 | * boot kernel
63 |
64 |
65 | Troubleshoot the boot process
66 | ----
67 |
68 | ### manual boot
69 |
70 | If you want or need to manually boot a Linux system you must specify a kernel, initrd, and root file system. Use the kexec-boot utility. In this example 'foo' is a description that normally comes from other parts of Heads configurations. It can be anything. The root filesystem must be the correct one used in the target Linux installation.
71 |
72 | This example may work for you by changing only the root= setting. Normally, there are symlinks in the boot partition using these file names. Of course you need to adjust if your target system uses a different convention for specifying these files.
73 |
74 | kexec-boot -b /boot -e ‘foo|elf|kernel /vmlinuz|initrd /initrd.img|append root=/dev/whatever’
75 |
76 |
77 | ### sign files
78 |
79 | Content in /boot is hashed and recorded in a file. The hashes are signed using the security dongle paired with Heads. These hashes are verified on boot using the public key corresponding to the security dongle.
80 |
81 | mount /dev/sdaX /boot
82 | kexec-sign-config -p /boot
83 |
84 | ### hotp and totp
85 |
86 | Will not work in recovery shell due to missing secrets. See [Limitations](#limitations).
87 |
88 |
89 | Upgrading Heads
90 | ----
91 |
92 | The Heads [upgrade process](/Updating) may be performed from the recovery shell.
--------------------------------------------------------------------------------
/Installing-and-Configuring/Upgrading.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Upgrading Heads
4 | permalink: /Updating
5 | nav_order: 99
6 | parent: Installing and configuring
7 | ---
8 |
9 |
10 | 12 | Table of contents 13 |
14 | {: .text-delta } 15 | 1. TOC 16 | {:toc} 17 |
11 |
18 |
19 |
20 |
21 | 
22 |
23 |
24 | Upgrading Heads
25 | ===
26 |
27 | The first time you install Heads, you'll need [some SPI programmer]({{ site.baseurl }}/Prerequisites#required-equipment)
28 | to replace the existing vendor firmware. This process involves **initial external flashing** using `.rom` files.
29 |
30 | For subsequent upgrades, you can use the Heads GUI to perform **internal upgrading** using `.zip` files. This method is supported for firmware versions built after [this November 2023 commit](https://github.com/linuxboot/heads/commit/6873df60c1c965ac812a49d9d245f338d8a3b128).
31 |
32 | ---
33 |
34 | Global Warning: No Hardware Programmer? Be Cautious!
35 | ---
36 | Heads is a rolling release. If you do not have an external programmer to recover from potential issues, exercise caution when upgrading. Follow these guidelines:
37 |
38 | 1. **Wait Before Upgrading**:
39 | - Wait a day or two after a new commit is merged, especially if it involves coreboot or kernel updates. This allows time for potential regressions to be identified and resolved.
40 |
41 | 2. **Check Reported Issues**:
42 | - Review the [most recently reported issues](https://github.com/linuxboot/heads/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) to ensure no critical problems have been reported for your platform.
43 |
44 | 3. **Verify Community Testing**:
45 | - Confirm that other users with the same platform have successfully tested the changes. Heads relies on community testing to validate updates across supported devices.
46 |
47 | 4. **Understand the Risks**:
48 | - Major updates, such as coreboot or kernel version bumps, require extensive testing. Untested platforms may experience regressions or even bricking.
49 |
50 | 5. **Pay Attention to Board Labels**:
51 | - Boards labeled as `UNTESTED` or `UNMAINTAINED` in their names indicate limited or no support. These labels mean exactly what they state:
52 | - **UNTESTED**: The board has not been tested and may not function as expected.
53 | - **UNMAINTAINED**: The board is no longer actively supported or maintained.
54 | - For additional details, refer to the [UNTESTED and UNMAINTAINED boards documentation](https://github.com/linuxboot/heads/blob/master/unmaintained_boards/README.md).
55 |
56 | By following these precautions, you can minimize the risk of encountering issues during an upgrade. If in doubt, wait for additional feedback from the community or consider using an external programmer for recovery.
57 |
58 | ---
59 |
60 | Initial External Flashing
61 | ---
62 | If you are installing Heads for the first time, you will need to perform an external flash using `.rom` files. Refer to the [Downloading documentation]({{ site.baseurl }}/Downloading) for detailed instructions on:
63 | - Downloading `.rom` files and `hashes.txt`.
64 | - Verifying file integrity.
65 | - Preparing for external flashing.
66 |
67 | **Note**: This process is only required for the initial installation of Heads.
68 |
69 | ---
70 |
71 | Internal Upgrading Using ZIP Files
72 | ---
73 | If Heads is already installed on your device, you can upgrade the firmware internally using a `.zip` file. This method is simpler and does not require an external programmer.
74 |
75 | 1. **Prepare the ZIP File**:
76 | - Download the `.zip` file for your board from the CircleCI "Artifacts" tab (refer to the [Downloading documentation]({{ site.baseurl }}/Downloading)).
77 |
78 | 2. **Transfer to Target System**:
79 | - Save the `.zip` file to a USB drive and insert it into the target system.
80 |
81 | 3. **Upgrade via Heads GUI**:
82 | - Boot into the Heads GUI.
83 | - Navigate to `Options -> Flash/Update BIOS`.
84 | - Select the `.zip` file from the USB drive. The system will automatically verify the ROM integrity and flash the firmware.
85 |
86 | **Note**: Internal upgrading via `.zip` files is supported for firmware versions built after [this November 2023 commit](https://github.com/linuxboot/heads/commit/6873df60c1c965ac812a49d9d245f338d8a3b128).
87 |
88 | ---
89 |
90 | Caution for Rolling Releases
91 | ---
92 | Heads is a rolling release. If you do not have an external programmer, wait a few days after a new commit before upgrading to ensure no regressions are reported. Check the [most recently reported issues](https://github.com/linuxboot/heads/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) and confirm that other users have tested the changes on your platform.
93 |
94 | ---
95 |
96 | Reflashing the Same Firmware
97 | ---
98 | If you need to validate the current firmware integrity against the last flashed firmware image stored on a USB thumb drive, follow these steps to back up the current ROM and ensure no changes occur during the process:
99 |
100 | 1. **Back Up the Current ROM**:
101 | - Insert a USB thumb drive and mount it in read-write mode:
102 | ```shell
103 | mount-usb --mode rw
104 | ```
105 | - Back up the current ROM to the USB drive:
106 | ```shell
107 | ${CONFIG_FLASH_OPTIONS} -r /media/backup.rom
108 | ```
109 | - Remount the USB drive in read-only mode for safety:
110 | ```shell
111 | mount -o remount,ro /media
112 | ```
113 |
114 | 2. **Reflash the Same Firmware**:
115 | - Use the Heads Flashing GUI (for zip file downloaded) or the following command to reflash the same firmware image from Heads Recovery shell:
116 | ```shell
117 | ${CONFIG_FLASH_OPTIONS} -w /media/same_rom_image_previously_flashed.rom
118 | ```
119 | - The process should report **no changes** to the SPI flash.
120 |
121 | **Note on `CONFIG_FLASH_OPTIONS`**:
122 | - The `CONFIG_FLASH_OPTIONS` variable specifies the board-specific flash options to ensure proper handling of SPI regions during flashing. These options are defined in the board's configuration file.
123 | - Boards may specify different SPI regions to flash. For example:
124 | - The `novacustom-v540tu` board preserves the `GBE` (Gigabit Ethernet) region, ensuring the manufacturing MAC address remains intact.
125 | - The `x230-hotp-maximized` board overwrites the entire SPI flash, including the `GBE` region, replacing it with a generic configuration.
126 | - To inspect the flash options for your board, use the `env` command in the recovery shell:
127 | ```shell
128 | env
129 | ```
130 | This will display all environment variables, including `CONFIG_FLASH_OPTIONS`, as defined for your board.
131 |
132 | **Tip**: Advanced users can review the board-specific configuration files under the Heads repository (`boards/12 | Table of contents 13 |
14 | {: .text-delta } 15 | 1. TOC 16 | {:toc} 17 |
11 |
18 |
19 |
20 | ## No OS installed
21 |
22 | If starting with a blank hard drive, Heads will detect it and propose to boot
23 | from USB alongside other options:
24 | 
25 |
26 | You can also set a different boot device, or go into Recovery shell and
27 | partition with `fdisk`.
28 |
29 | Installing an OS by booting from USB is probably the best option. Note here
30 | again that for OSes that provide detached signatures (iso.asc or iso.sig)
31 | alongside their ISO download option, this is the preferred Heads installation
32 | method, since Heads can validate both integrity and authenticity against
33 | distribution public key, fused (and measured) in the firmware.
34 |
35 | If there are other OSes providing detached signatures alongside their ISOs,
36 | please open an issue so we can add it.
37 |
38 | ### No public key found in ROM
39 | 
40 |
41 | You can either add a backuped gpg public key matching an already provisioned
42 | USB Security dongle (see below on adding public key) or generate the keys,
43 | alongside setting all security components in one go with the `OEM Factory
44 | Reset/Re-Ownership` option.
45 |
46 | #### OEM Factory Reset/Re-Ownership
47 | Once you have installed the OS, you will need to take ownership of the
48 | different security components under Heads. The easiest way is through `OEM
49 | Factory Reset/Re-Ownership` option.
50 |
51 | The wizard will prompt you to use default configuration options.
52 | **It is strongly advised to refuse the defaults, and answer the questionnaire thoroughtly.
53 | This only happens once, and will permit you to reencrypt encrypted containers and provision
54 | properly to your use case the different security components of your system before use.**
55 |
56 | **Note that the passphrases you will type will be echoed back to you. You need
57 | to accomplish this step in a safe environment**
58 |
59 | **_EFF Diceware passphrases are recommended_**
60 | You can generate those on a separate device from the following recommended
61 | sites:
62 | - [https://www.rempe.us/diceware/#eff](https://www.rempe.us/diceware/#eff)
63 | Explains why those are important as opposed to passwords
64 | - [https://diceware.dmuth.org/](https://diceware.dmuth.org/) Explains as well
65 | - [https://romeljacinto.github.io/diceware/](https://romeljacinto.github.io/diceware/)
66 | Minimalist, first letter capitalizer, customizes word separator.
67 |
68 | The Secrets involved under Heads are the following (and their recommended
69 | lengths):
70 |
71 | - Disk Recovery Key passphrase (6 words. _Do not forget this one_)
72 | - This passphrase is required to setup a TPM Disk Unlock Key passphrase.
73 | - This passphrase is required to access encrypted data from any computer
74 | - This passphrase is required to "unsafe boot", where the installed OS will
75 | prompt for it.
76 | - TPM Ownership passphrase (2 words.)
77 | - Used to set ownership on the TPM.
78 | - GPG Admin PIN (2 words. _Locks Admin out after 3 bad attempts in a row. DO
79 | NOT FORGET_)
80 | - This passphrase is requested to do management tasks on the USB Security
81 | dongle
82 | - Under Heads, it is to seal measurements under HOTP
83 | - It will be needed in case the GPG User PIN was locked
84 | - GPG User PIN (2 words. _Locks user out after 3 bad attempts in a row. DO NOT
85 | FORGET_)
86 | - Used to sign/encrypt content
87 | - Used to do anything linked to user interaction with the USB Security
88 | dongle.
89 | - GPG prompts for this passphrase when signing hashes under Heads
90 | - TPM Disk Unlock Key passphrase (3 words, asked to boot default boot option)
91 | - Requires GPG User PIN and Disk Recovery Key passphrase to setup
92 |
93 | ##### Process
94 | This will go first briefly over a survey, asking you if you want to:
95 |
96 | - Re-encrypt the LUKS encrypted container (Say yes here if you didn't install
97 | the OS yourself)
98 | - As explained on screen, anyone having a LUKS header backup could restore it
99 | and decrypt with past corresponding passphrase. Changing passphrase without
100 | reencrypting doesn't change the encryption key.
101 | - Change the Disk Recovery Key passphrase (Say yes here if you didn't install
102 | the OS yourself)
103 | - You should have also said yes above.
104 | - Define a single shared passphrase across all security components (not
105 | recommended)
106 | - This option is used by some OEMs to provision initial secrets. Passphrases
107 | should be different
108 | - Define individual passphrases for each security components (recommended: y)
109 | - This is the preferred option
110 | - Set custom under information for the GnuPG key (recommended: y)
111 | - If you desire to use the USB Security dongle to encrypt/sign content linked
112 | to a public identity that identity needs to be provisioned in a way that it
113 | will be searchable if you ever decide to upload the resulting public key to
114 | gpg key search engines.
115 |
116 | Note that the Comment section is used to differentiate the resulting public
117 | key from other public keys that would be linked with the same Real Name and
118 | E-Mail address, and should be distinguishable from the Comment. A good
119 | Comment example is: "USB Security dongle".
120 |
121 | The process then enforces user's selected choices.
122 |
123 | At the end, the wizard outputs on screen the `Provisioned Security Components
124 | Secrets` This is the last chance you have to note provisioned secrets correctly
125 | until you know them by heart. That piece of paper's content is precious, and
126 | should be safeguarded accordingly.
127 |
128 | At the end, the wizard outputs on screen the `Provisioned Security Components
129 | Secrets` This is the last chance you have to note provisioned secrets correctly
130 | until you know them by heart. A Qr code containing the same information is also
131 | provided: please scan it.
132 |
133 | #### Adding your PGP key
134 |
135 | If you already have a provisioned USB Security dongle and its associated public
136 | key, then follow these steps to inject the public key into Heads. Otherwise,
137 | you should probably follow `OEM Factory Reset/Re-Ownership` above.
138 |
139 | 
140 |
141 | Heads uses your own GPG key to sign updates and as a result it needs the key
142 | stored in the ROM image before flashing the full Heads ROM.
143 |
144 | Ensure your USB security dongle and the USB drive with your key are still
145 | inserted. Select "Add a GPG key to the running BIOS" to enter the GPG
146 | Management menu, then "Add a GPG key to the running BIOS + reflash". Follow the
147 | steps and your GPG key will be added to the Heads rom.
148 |
149 | Once `flashrom` is complete, reboot and now you should now be back in the Heads
150 | runtime. It should display a message that it is unable to unseal TOTP.
151 |
152 | ## Configuring the TPM
153 | google authenticator or [FreeOTP+](https://f-droid.org/en/packages/org.liberty.android.freeotpplus/)
154 | application and use to validate that the firmware (bootblock, ram/rom stages,
155 | Linux payload and user config injected files are un-altered.
156 |
157 | If you have the HOTP version of the firmware, this is also where Heads will ask
158 | you for your GPG Admin PIN to seal the secret inside of a HOTP compatible USB
159 | Security dongle.
160 |
161 | On the next boot, the current TOTP will be computed and you can compare this
162 | one-time-password against the value that your phone generates.
163 |
164 | TPM Disk Encryption Key (TPM Disk Unlock Key)
165 | ---
166 |
167 | The LUKS Disk Recovery Key stored under LUKS header at OS install is derived
168 | from its user passphrase, which is expanded via the LUKS expansion algorithm to
169 | increase the time needed to brute force it. For extra protection it is possible
170 | to store an additional LUKS key in the TPM so that it will only be released to
171 | unlock the LUKS container if the PCRs match (firmware measurements, kernel
172 | modules loaded, no recovery shell access) from Heads when selecting a boot
173 | option.
174 |
175 | If you want to use the TPM to seal a secret used to unlock your LUKS volumes:
176 | Go to boot options, show OS boot options and select a new default boot option:
177 | 
178 |
179 | Select make default:
180 | 
181 |
182 | Answer the prompts properly:
183 | 
184 |
185 | This will prompt you for your Disk Recovery Key passphrase, a new TPM Disk
186 | unlock passphrase and confirm and finally ask you to enter your GPG User PIN to
187 | sign the new default boot option before rebooting.
188 |
189 | Reboot and you will be prompted for your boot password when that device is used
190 | to boot in the future:
191 | 
192 | 
193 |
194 | The key file cannot persist on disk anywhere, since it would allow an adversary
195 | to decrypt the drive. Instead it is necessary to unseal/decrypt the key from
196 | the TPM and then bundle the key file into a RAM copy of Qubes' dom0 initrd on
197 | each boot. The initramfs format allows concatenated cpio files, so it is easy
198 | for the Heads firmware to inject files into the Qubes startup script.
199 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Installing and configuring
4 | permalink: /Install-and-Configure
5 | nav_order: 40
6 | has_children: yes
7 | has_toc: false
8 | ---
9 |
10 |
11 | Installing and configuring Heads
12 | ===
13 |
14 |
15 | Prerequisites
16 | ----
17 |
18 | Heads is supported on a limited set of hardware (laptop and security dongle). First, check the [Prerequisites](/Prerequisites) page for details.
19 |
20 |
21 | Downloading
22 | ----
23 | You can [download ROMs](/Downloading) directly from CircleCI for most of the boards configurations supported.
24 |
25 | Building
26 | ----
27 |
28 | If you are [building heads](/Building) check the build guides. See below if you are using heads releases from this project.
29 |
30 |
31 | Flashing Guides
32 | ----
33 |
34 | The steps for [Flashing-Guides](/Flashing-guides) on your system may vary based on the hardware in use.
35 |
36 |
37 | Secrets and Security
38 | ----
39 |
40 | There are many secret pins, passphrases, and keys used in heads. These are described in [Configuring Keys](/Configuring-Keys/).
41 |
42 |
43 | Operating Systems
44 | ----
45 |
46 | We assume you want to run something other than heads on your system. The installation procedure could vary greatly depending on which distro you choose, which version of that distro, and if you are encrypting various partitions. See [Operating System](/InstallingOS/) for help.
47 |
48 |
49 | Recovery Shell
50 | ----
51 |
52 | There is a [Recovery Shell](/RecoveryShell/) built into the heads environment which may be used for troubleshooting.
53 |
--------------------------------------------------------------------------------
/Installing-and-Configuring/install-os.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Step 4 - Installing Qubes and other OSes
4 | permalink: /InstallingOS/
5 | nav_order: 8
6 | parent: Installing and configuring
7 | ---
8 |
9 |
10 | 12 | Table of contents 13 |
14 | {: .text-delta } 15 | 1. TOC 16 | {:toc} 17 |
11 |
18 |
19 |
20 | Generic OS Installation
21 | ===
22 |
23 | Insert OS installation media into one of the USB3 ports (blue on Thinkpads).
24 | [For certain OSes](https://github.com/osresearch/heads/tree/master/initrd/etc/distro/keys),
25 | Heads boot process supports standard OS ISO bootable media (where the USB drive
26 | contains the ISO installation media alongside of its detached signature). For
27 | other OS, you will need to create USB installation media with using `dd` or
28 | `unetbootin` etc.).
29 |
30 | For supported OSes, on a EXT3/EXT4/ExFat formatted partition on USB drive, you
31 | can put the ISO image along with a trusted detached signature in the root
32 | directory:
33 | ```shell
34 | /Qubes-R4.0-x86_64.iso
35 | /Qubes-R4.0-x86_64.iso.asc
36 | /tails-amd64-3.7.iso
37 | /tails-amd64-3.7.iso.sig
38 | ```
39 |
40 | - Some distros will require additional options to boot directly from ISO. See
41 | [Boot config files](/BootOptions) for more information.
42 | - Boot from USB by Boot menu options, or by calling `usb-scan` from the recovery
43 | shell.
44 | - Select the install boot option for your distro of choice and work through
45 | the standard OS installation procedures (including setting up LUKS disk
46 | encryption if desired)
47 | - Reboot and your new boot option should be available through boot options: show
48 | boot options.
49 |
50 | Each ISO file is verified for integrity and authenticity before booting so that
51 | you can be sure Live distros and installation media are not tampered with or
52 | corrupted, so this route is preferred when available. You can also sign the ISO
53 | with your own key **from Heads Recovery Shell menu option (Options-> Exit to
54 | recovery shell)** :
55 |
56 | ```shell
57 | mount-usb --mode rw #Loads USB controller kernel modules, scan for partitions,
58 | ask which one to mount under /media
59 | cd /media # Change directory to /media to do the detach-sign operation
60 | gpg --detach-sign