DeityGuard

Status

Does it work?

Yes, DeityGuard has now reached a reasonable state of completion and is periodically tested to be runnable on each of the four supported platforms. Of course, there’s no telling when changes to Gentoo might trip up a build. The DeityGuard project will of course do its best to provide fixes when upstream software changes.

What is it?

DeityGuard is an all-in-one builder for a secure Linux-based operating system (with some GNU in it as well). Put simply, DeityGuard is a collection of Bash scripts that coordinate building a firmware BIOS and bootloader (either Coreboot or U-Boot), the Linux operating system kernel, and a Gentoo or Buildroot operating system and applications. DeityGuard also includes various patches to existing programs, and some of its own programs written from scratch.

The resulting system uses strong cryptographic checksums to verify all the code it runs, except for the part stored in the BIOS flash memory (which is where the root of trust begins). Additionally, all of the code is compiled from source (except for the base Gentoo system – at some point, some binaries have to be trusted because you can’t just create a GCC toolchain out of thin air).

In short, DeityGuard is about achieving practical security by:

• trusting hardware as little as possible, and:
• using only software that:
  • is auditable, meaning at least availability of full source code, and:
  • is freely modifiable (or patchable), so that problems can be fixed by anyone.

Additionally, DeityGuard is meant to be as simple to use as possible (that is, without compromising its core security tenets). This goal has been achieved pretty satisfactorily – apart from the inevitable hardware muckery inherent in flashing BIOS chips, it’s now arguably simpler to get started with DeityGuard than it is to get started with Gentoo.

DeityGuard is not an end-user product and probably will never be. Some tuning will be required to get DeityGuard to do what you want to do with it. Rather than just explaining how to use DeityGuard, this guide is also intended to explain enough about the internals of DeityGuard so that you can modify it to suit your needs. But you must be prepared to make your own modifications (at least simple ones), or you won’t get much mileage out of DeityGuard. At minimum, you have to be able to modify the scripts that configure Gentoo’s portage tool to customize the list of installed software packages and their enabled features. It will help if you already have experience with Gentoo; if not, this guide also contains a primer on portage.

Which hardware platforms are supported?

Because the concept of DeityGuard is to not run any untrusted code, a platform must typically first be supported without binary blobs by the Coreboot project. This rules out most modern desktop computers and laptops. This is because both major vendors of x86_64 CPUs (Intel and AMD) now only fabricate processors that require mysterious binaries to be loaded at boot (and if you don’t load them, the chips shut down).

DeityGuard currently supports an x86_64 desktop system, an x86_64 laptop, a 32-bit ARM single-board computer, and a 32-bit ARM laptop.

• d16 desktop: Asus KGPE-D16 (actually a server motherboard, but works great in a large desktop case)
• t400 laptop: Lenovo T400
• bpi single-board computer: Banana Pi
• veysp laptop: Asus C201 Chromebook (also known as “Veyron Speedy”)

With these platforms, you can, for example, structure a computer network to contain a computing powerhouse (the d16) and multiple kiosks (t400s, bpis, veysps) that can give multiple users direct access the computing powerhouse through VNC. Additionally, DeityGuard supports finaling system configuration and flashing from either x86_64 or ARM hosts, allowing, for example, the use of a veysp laptop for administering a network.

Asus KGPE-D16

The most powerful mainboard supported by Coreboot without blobs is the Asus KGPE-D16 server mainboard, which can accept up to two Opteron 6200-series CPUs (up to 32 cores) and up to 256GiB of RAM (though only up to 192GiB is reported working in Coreboot). Virtualization is supported. It is recommended to have one of these for building new versions of DeityGuard, as building DeityGuard on the t400 laptop could take a while.

The onboard VGA is poorly supported by Linux (very slow refresh). An external NVIDIA GeForce 210 card is recommended (and supported in DeityGuard).

Can be found on eBay occasionally. Can still be bought new (as of 2017).

Lenovo T400

An aging laptop supported by Coreboot without blobs.

Can be found on eBay; no shortage of supply yet (as of 2017). Can no longer be bought new.

Banana Pi

Not actually supported by Coreboot (and doesn’t have a BIOS chip either). To avoid trusting the SD card, DeityGuard is designed to boot the Banana Pi through USB via FEL mode.

Can be found on eBay usually. Can also be bought new from https://www.tinyonesystems.com/products/banana-pi in U.S.; see also http://www.banana-pi.org/shop.html for a complete list of vendors by geographic region.

Asus C201 Chromebook

Supported by Coreboot. DeityGuard includes a patch to Coreboot that allows booting Linux directly from the BIOS chip, and without the depthcharge payload that is normally used on these systems.

Can be bought new (as of 2017).

How does DeityGuard work at runtime?

On platforms with BIOS chips (currently all platforms except bpi), the boot proceeds thusly:

• The processor’s boot sequence maps the BIOS chip into memory and begins executing Coreboot’s bootblock.

• Coreboot runs, initializing the hardware and booting a Linux kernel and initramfs that have been placed on the BIOS chip. DeityGuard compiles the Linux kernel with as many features set to modules as possible so that the kernel binary remains as small as possible. The initramfs contains modules needed to access block storage devices and wired ethernet (either the on-board ethernet or through a USB ethernet adapter on the veysp platform). The initramfs also contains a program specific to DeityGuard called the instigator.

• The instigator loads all the kernel modules on the initramfs and then scans all attached media for a stage1 archive. The stage1 archive must exactly match a secure checksum stored in the initramfs. If a valid stage1 cannot be found on an attached medium, the instigator attempts to bring up the first ethernet interface and load stage1 over the network. Control then passes to the stage1 code, which is not subject to the size restrictions of the BIOS chip.

• The stage1 code brings up the display and keyboard input and searches for a valid stage2 archive, first on disk and then over the network. If found, the stage1 code verifies that the stage2 archive is signed by public key cryptography. The user is offered to boot any valid stage2 archive found.

• The stage2 archive contains a stage3 kernel and initramfs, which are kexeced. The use of kexec allows the kernel to be upgraded without reprogramming the BIOS chip. On the veysp target, kexec does not work and DeityGuard uses a workaround involving a soft reboot.

• The stage3 initramfs presents a dialog interface allowing the user to boot into the main OS (either Gentoo or Buildroot) or carry out other management actions.

• The OS squashfs image is verified at runtime by a program specific to DeityGuard called nbd-hyperbolic. When a disk sector must be loaded, nbd-hyperbolic first tries to load it from a local cache. If the sector’s secure checksum does not match a corresponding entry in a table securely loaded from the stage3 archive, attempts are made to load the sector over HTTP using a range request; on success, the network loaded data is written back to the local cache. To improve performance, nbd-hyperbolic expands requests to a large sector size (128KiB by default). There is support in stage3 for starting nbd-hyperbolic either with an on-disk cache or with an in-memory cache - the latter case allowing operation completely without local storage.

• When the OS is loaded with an on-disk cache, stage3 also supports updating the on-disk cache with the stage1 and stage2 that archives that were discovered during the boot process in a way that allows subsequent boots to discover them from disk. This allows subsequent boots to succeed offline.

On bpi, the sole supported platform without a BIOS chip, booting happens by feeding U-Boot, the Linux kernel, and an initramfs to the board through USB FEL mode (which the bpi enters by default if no SD card is present). The OS can be loaded over the network, or it can be dropped in through the FEL link as well, enabling non-networked use cases, or network bootstrap use cases (e.g., running your LAN dhcp server or HTTP image server for OS images).

Can DeityGuard run my favorite program?

On x86_64 platforms, all user programs in a DeityGuard system come from Gentoo. Check packages.gentoo.org for the available Gentoo packages.

On ARM, most user programs in a DeityGuard system come from Buildroot. Check https://git.busybox.net/buildroot/tree/package for the available Buildroot packages. Also, DeityGuard patches Buildroot to add some additional packages.

Do the ARM parts of DeityGuard have to be built on ARM?

No. DeityGuard builds everything on an x86_64 host.

Can I try DeityGuard without building everything myself?

No. DeityGuard is supplied as sources only. The DeityGuard build scripts are capable of building a binary distribution, but the DeityGuard project has a policy of not distributing binaries in order to limit legal liability.

Ethernet?! Why isn’t wireless supported?

Basically, because it’s not secure. Also, it would take a lot of work to implement.

More information

• Download - This page lets you obtain the DeityGuard sources and pre-built binary images.

• Recipe - This page explains how to build the default configuration of DeityGuard (before you start changing everything!).

• Deploy - This page explains how to build the default configuration of DeityGuard in a reproducible and moderately secure build environment (start here!)

• Support - This page explains how to get support for DeityGuard.

• Internals - This page explains how DeityGuard works; this is what you read before you start modifying DeityGuard (or after you started but you got stuck, or after you have things working and you are curious to see if you did it correctly).

• Flashing - This page explains how to flash your system’s BIOS with DeityGuard.

• Future - This page lists various directions that DeityGuard development might be going in in the future.

• Third Idea - This page explains how to make a “data diode” on the cheap.