2022-06-22 20:47:05 +00:00
2016-08-03 03:29:46 +00:00
2016-07-25 13:06:36 +00:00
Heads: the other side of TAILS
===
2018-02-05 22:25:51 +00:00
Heads is a configuration for laptops and servers that tries to bring
more security to commodity hardware. Among its goals are:
2016-07-25 13:06:36 +00:00
* Use free software on the boot path
2016-08-03 03:29:46 +00:00
* Move the root of trust into hardware (or at least the ROM bootblock)
2016-07-25 13:06:36 +00:00
* Measure and attest to the state of the firmware
* Measure and verify all filesystems
2016-12-26 21:29:36 +00:00
2016-08-03 03:29:46 +00:00
2017-01-29 21:44:23 +00:00
NOTE: It is a work in progress and not yet ready for non-technical users.
2016-08-03 03:29:46 +00:00
If you're interested in contributing, please get in touch.
Installation requires disassembly of your laptop or server,
external SPI flash programmers, possible risk of destruction and
significant frustration.
2016-07-25 14:08:53 +00:00
2016-12-26 21:29:36 +00:00
More information is available in [the 33C3 presentation of building "Slightly more secure systems" ](https://trmm.net/Heads_33c3 ).
2019-05-21 17:23:59 +00:00
Documentation
===
2023-02-07 16:42:35 +00:00
Please refer to [Heads-wiki ](https://web.archive.org/web/20230203072945/https://osresearch.net/ ) for your Heads' documentation needs.
2019-05-21 17:23:59 +00:00
2016-08-06 22:45:56 +00:00
2016-08-14 16:57:54 +00:00
Building heads
===
2020-03-09 18:21:46 +00:00
`make BOARD=board_name` where board_name is the name of the board directory under `./boards` directory.
2016-08-14 16:57:54 +00:00
2017-01-29 21:44:23 +00:00
In order to build reproducible firmware images, Heads builds a specific
version of gcc and uses it to compile the Linux kernel and various tools
that go into the initrd. Unfortunately this means the first step is a
2020-03-09 18:21:46 +00:00
little slow since it will clone the `musl-cross-make` tree and build gcc...
2017-01-29 21:44:23 +00:00
Once that is done, the top level `Makefile` will handle most of the
remaining details -- it downloads the various packages, verifies the
hashes, applies Heads specific patches, configures and builds them
with the cross compiler, and then copies the necessary parts into
the `initrd` directory.
There are still dependencies on the build system's coreutils in
`/bin` and `/usr/bin/` , but any problems should be detectable if you
end up with a different hash than the official builds.
The various components that are downloaded are in the `./modules`
directory and include:
* [musl-libc ](https://www.musl-libc.org/ )
* [busybox ](https://busybox.net/ )
* [kexec ](https://wiki.archlinux.org/index.php/kexec )
* [mbedtls ](https://tls.mbed.org/ )
* [tpmtotp ](https://trmm.net/Tpmtotp )
2017-03-06 12:59:06 +00:00
* [coreboot ](https://www.coreboot.org/ )
2017-01-29 21:44:23 +00:00
* [cryptsetup ](https://gitlab.com/cryptsetup/cryptsetup )
* [lvm2 ](https://sourceware.org/lvm2/ )
* [gnupg ](https://www.gnupg.org/ )
* [Linux kernel ](https://kernel.org )
We also recommend installing [Qubes OS ](https://www.qubes-os.org/ ),
2019-05-21 17:23:59 +00:00
although there Heads can `kexec` into any Linux or
2017-01-29 21:44:23 +00:00
[multiboot ](https://www.gnu.org/software/grub/manual/multiboot/multiboot.html )
kernel.
2016-08-14 16:57:54 +00:00
Notes:
2016-08-06 22:45:56 +00:00
---
2016-08-14 16:57:54 +00:00
* Building coreboot's cross compilers can take a while. Luckily this is only done once.
2017-01-29 21:44:23 +00:00
* Builds are finally reproducible! The [reproduciblebuilds tag ](https://github.com/osresearch/heads/issues?q=is%3Aopen+is%3Aissue+milestone%3Areproduciblebuilds ) tracks any regressions.
2020-03-09 18:21:46 +00:00
* Currently only tested in QEMU, the Thinkpad x230, Librem series and the Chell Chromebook.
2022-07-11 01:20:29 +00:00
** Xen does not work in QEMU. Signing, HOTP, and TOTP do work; see below.
2017-04-21 19:12:54 +00:00
* Building for the Lenovo X220 requires binary blobs to be placed in the blobs/x220/ folder.
2018-03-12 17:56:11 +00:00
See the readme.md file in that folder
* Building for the Librem 13 v2/v3 or Librem 15 v3/v4 requires binary blobs to be placed in
the blobs/librem_skl folder. See the readme.md file in that folder
2016-08-06 22:45:56 +00:00
2022-07-11 01:20:29 +00:00
QEMU:
---
OS booting can be tested in QEMU using a software TPM. HOTP can be tested by forwarding a USB token from the host to the guest.
For more information and setup instructions, refer to the [qemu-coreboot-fbwhiptail-tpm1-hotp documentation ](boards/qemu-coreboot-fbwhiptail-tpm1-hotp/qemu-coreboot-fbwhiptail-tpm1-hotp.md ).
2016-12-13 17:02:35 +00:00
coreboot console messages
2016-08-14 16:57:54 +00:00
---
2016-12-13 17:02:35 +00:00
The coreboot console messages are stored in the CBMEM region
2016-08-14 16:57:54 +00:00
and can be read by the Linux payload with the `cbmem --console | less`
command. There is lots of interesting data about the state of the
system.
