Skip to content

Commit f66e0df

Browse files
tlauriontlaurion
authored
Merge pull request #71 from jtmoree-github-com/docs-refresh2
docs refresh without OS pages
2 parents bea96f2 + df780e8 commit f66e0df

File tree

8 files changed

+335
-194
lines changed

8 files changed

+335
-194
lines changed

‎About/Keys.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ The owner of the machine generates a GPG key pair as part of installing Heads.
147147
Ideally the private key does not live on the machine, but instead is in a
148148
Yubikey or other USB Security dongle.
149149

150-
TODO: Can this be used in the disk decryption process?
150+
The security dongle may be used in the disk decryption process. Some of the [Linux distros](https://docs.puri.sm/Librem_Key/Getting_Started/User_Manual.html#decrypt-luks-encrypted-drives-with-librem-key) have incorporated this using /etc/crypttab with a keyscript option.
151151

152152
An attacker who controls this private key can replace executables in `/boot` and
153153
if they also control the disk encryption key they can tamper with files in a

‎Installing-and-Configuring/BootOptions.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
layout: default
3+
title: Configuring Boot Options
4+
permalink: /BootOptions/
5+
parent: Installing and configuring
6+
nav_order: 85
7+
---
8+
9+
<!-- markdownlint-disable MD033 -->
10+
<details open markdown="block">
11+
<summary>
12+
Table of contents
13+
</summary>
14+
{: .text-delta }
15+
1. TOC
16+
{:toc}
17+
</details>
18+
<!-- markdownlint-enable MD033 -->
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+
<!-- markdownlint-disable MD013 -->
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+
<!-- markdownlint-enable MD013 -->
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+

‎Installing-and-Configuring/Prerequisites.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
layout: default
3+
title: Prerequisites for Heads
4+
permalink: /Prerequisites
5+
nav_order: 1
6+
parent: Installing and configuring
7+
---
8+
9+
Prerequisites for Heads
10+
===
11+
12+
Required equipment
13+
---
14+
15+
To install Heads on a physical device, you will need:
16+
17+
* Supported motherboard or laptop ([see below](#supported-devices))
18+
* A heads compatible USB security dongle ([see below](#USB Security Dongles))
19+
* A heads compatible storage device for your public GPG key (USB flash drive)
20+
21+
If your device requires external flashing ([see below](#supported-devices)),
22+
you will also need:
23+
24+
* [SPI Programmer](https://trmm.net/SPI_flash): ch341a programmer or raspberry
25+
pi or bus pirate (ch341a is recommended for new users and can be found almost
26+
[anywhere](https://www.amazon.com/s?k=ch341a+programmer).
27+
* Wires and a clip SOIC8 to connect your programmer of choice to the board’s
28+
SPI flash chip(s).
29+
* The [Pomona 5250](https://www.pomonaelectronics.com/products/test-clips/soic-clip-8-pin)
30+
is suggested as it is high quality and easier to make contact with the pins.
31+
* A second computer to flash from (Try to use a recommended operating system:
32+
Qubes or Debian 9 or Fedora 30)
33+
34+
Supported devices
35+
---
36+
37+
Please see the current [heads source](https://github.com/osresearch/heads/tree/master/boards) for supported devices.
38+
39+
|Device| Board name|Firmware base|Requires external flashing| ME should be cleaned|Notes|
40+
|--|--|--|:--:|:--:|--|
41+
|Asus KGPE-D16|`kgpe-d16`|coreboot|X|||
42+
|Dell R630|`r630`|linuxboot||X||
43+
|Intel S2600wf|`s2600wf`|linuxboot||X||
44+
|Lenovo Thinkpad T420|`t420`|coreboot|X|X||
45+
|Lenovo Thinkpad T430|`t430-flash`|coreboot|X|X|initial flashed image|
46+
|Lenovo Thinkpad T430|`t430`|coreboot|X|X||
47+
|Lenovo Thinkpad X220|`x220`|coreboot|X|X||
48+
|Lenovo Thinkpad X230|`x230-flash`|coreboot|X|X|initial flashed image|
49+
|Lenovo Thinkpad X230|`x230-hotp-verification`|coreboot|X|X|with hotp verification|
50+
|Lenovo Thinkpad X230|`x230`|coreboot|X|X||
51+
|Open Compute Project Leopard node|`leopard`|linuxboot|||
52+
|Open Compute Project TiogaPass node|`tioga`|linuxboot||||
53+
|Open Compute Project Winterfell node|`winterfell`|linuxboot||||
54+
|Purism Librem 13 v2|`librem_13v2`|coreboot||||
55+
|Purism Librem 13 v4|`librem_13v4`|coreboot||||
56+
|Purism Librem 15 v3|`librem_15v3`|coreboot||||
57+
|Purism Librem 15 v4|`librem_15v4`|coreboot||||
58+
|Purism Librem Mini|`librem_mini`|coreboot||||
59+
60+
Emulated devices
61+
---
62+
63+
For further information, see [Emulating Heads](/Emulating-Heads/)
64+
65+
|Device| Board name| Firmware base|
66+
|--|--|--|--|
67+
|QEMU development image|`qemu-coreboot-fbwhiptail`|coreboot|
68+
|QEMU development image|`qemu-coreboot`|coreboot|
69+
|QEMU development image|`qemu-linuxboot`|linuxboot|
70+
71+
USB Security Dongles (aka security token aka smartcard)
72+
---
73+
74+
*NOTE* - Heads does **NOT** support FIDO2 or U2F authentication. Be careful when
75+
purchasing to buy a compatible key.
76+
77+
*NOTE* - HOTP is currently only supported with Librem devices and the ThinkPad
78+
x230 rom with HOTP support
79+
80+
|Manufacture|Model line|TOTP|HOTP|
81+
|--|--|:--:|:--:|
82+
|Yubico|[YubiKey 5 Series](https://www.yubico.com/products/yubikey-5-overview/)|X||
83+
|Nitrokey|[Nitrokey Pro 2](https://www.nitrokey.com/#comparison)|X|X|
84+
|Nitrokey|[Nitrokey Storage 2](https://www.nitrokey.com/#comparison)|X|X|
85+
|Purism|[Librem Key](https://puri.sm/products/librem-key/)|X|X|

‎Installing-and-Configuring/RecoveryShell.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
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‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -24,14 +24,19 @@ encryption key. Be sure you have your TPM owner's password and your
2424
disk encryption recovery key or passphrase available since, by design,
2525
the disk key is not accessible to the recovery shell.
2626

27+
If you flash the same firmware and you keep settings, your TOTP will be valid, HOTP also, and Disk Unlock Key passphrase will still boot your system. In doubt, you can consequently reflash your firmware.
28+
29+
The Disk Recovery Key is the key used at OS installation for the encrypted root partition (passphrase placed in LUKS keyslot 0).
30+
31+
2732
Recovery shell
2833
---
2934

3035
![Recovery shell]({{ site.baseurl }}/images/Recovery_shell.jpg)
3136

3237
If the flash protection bits are set correctly it is not possible to
3338
rewrite the firmware from the normal OS. You'll need to reboot
34-
to the Heads recovery shell (hit `r` after the TPM TOTP prompt).
39+
to the Heads [recovery shell](/RecoveryShell/). Repeatedly press 'r' on boot or choose 'Recovery Shell' in the heads GUI.
3540

3641
Internal Flashing
3742
---
@@ -156,11 +161,3 @@ sealtotp.sh
156161

157162
This needs the TPM owner password to be able to define the NVRAM space.
158163
(todo: [issue #151](https://github.com/osresearch/heads/issues/151)).
159-
160-
Resealing the disk encryption keys
161-
---
162-
163-
When you get to the standard boot menu and after you verify the TOTP, select 'm'
164-
to go to the full boot menu. Select the option you want (usually the first),
165-
make it the default by hitting 'd' and also say 'y' when asked to reseal the
166-
disk keys.

‎Installing-and-Configuring/configuring-keys.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@ Select "Add a GPG key to the running BIOS" to enter the GPG Management menu. If
4040

4141
![GPG Management menu]({{ site.baseurl }}/images/gpg_management.jpg)
4242

43-
Insert your USB security dongle and USB drive into the device, then chose
44-
"Generate GPG keys manually on a USB security token".
43+
Insert your USB security dongle and USB drive into the device, then choose
44+
"Generate GPG keys manually on a USB security token[dongle]".
4545

4646
When at the GPG prompt, go into "Admin" mode and generate a new key inside the
4747
USB security dongle:

0 commit comments

Comments
 (0)