Development Resources

This page is dedicated to those who wish to either help develop HalogenOS, or host their own build infrastructure to distribute modified versions of HalogenOS.

Build System

HalogenOS images are built and signed using a Docker container and a build script. The Docker container provides the necessary Gentoo tooling (emerge, Portage, profiles, compilers, libraries, etc) to compile all the system's binaries. The script contains all the commands necessary to copy over relevant config files, compile all the needed binaries, and create a system partition image.

Installation

Currently, there is no "installer" for HalogenOS. Installation must be performed manually from a Linux live USB:

A 512mb EFI boot partition must be created.
The kernel UKI and the A/B boot manager must be placed in this partition.
A system image must be installed in the disk immediately following the EFI partition.
The system EFI must have Secure Boot enabled and set to Setup Mode.

Upon reboot, the first system slot (Slot A) will generate its own verity partition, Slot B's system and verity partitions, and the root partition. It will also generate Secure Boot Keys and sign all EFI binaries, effectively relocking the system's firmware security mechanisms by exiting Setup Mode. For full security, the system BIOS password must be set. Once Secure Boot is finalized, the root partition's password will be bound to the TPM.

Eventually, this project will include an installation script that could be used from an Arch Linux or Alpine Linux minimal ISO.

Security

Public-key cryptography is used to ensure that system images are not tampered with in transit, and to increase assurance that kernel modules are authorized to run on the system. The image distribution key must be consistent across releases, or else the system will be unable to update to any other version. Kernel keys should preferably remain the same across versions, but kernel modules must include their kernel target versions to ensure incorrect versions cannot be loaded.

Cryptographic private keys or symmetrical keys cannot, and should not, ever be present in installation images. Signing keys are required to be password-protected, and should also be stored in an encrypted directory or disk. The usage of the Docker secrets API ensures that keys and passwords are never copied out of their original locations. Symmetric encryption keys are always generated dynamically and protected by TPM.