From 15b966627a3d648c9245dd8558859013591f96ed Mon Sep 17 00:00:00 2001
From: Julian Stecklina <js@alien8.de>
Date: Thu, 24 Nov 2022 11:34:41 +0100
Subject: [PATCH] docs: add more overview information

---
 README.md | 39 +++++++++++++++++++++++++++++++++------
 1 file changed, 33 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index eb6f8af..7e45ccf 100644
--- a/README.md
+++ b/README.md
@@ -4,11 +4,23 @@
 [![made-with-rust](https://img.shields.io/badge/Made%20with-Rust-1f425f.svg)](https://www.rust-lang.org/)
 [![GitHub license](https://img.shields.io/github/license/blitz/lanzaboot.svg)](https://github.com/blitz/lanzaboote/blob/master/LICENSE)
 
-🚧🚧🚧 **This is not working yet. Come back later.*** 🚧🚧🚧
+🚧🚧🚧 **This is not working yet. Come back later.** 🚧🚧🚧
 
 This repository contains experimental tooling for Secure Boot on
 [NixOS](https://nixos.org/).
 
+## High-Level Boot Flow
+
+```mermaid
+flowchart LR
+    systemd[systemd-boot]
+	lanzaboote[lanzaboote]
+	kernel[Linux Kernel]
+	
+	systemd --> lanzaboote
+	lanzaboote --> kernel
+```
+
 ## lanzatool
 
 `lanzatool` is a Linux command line application that takes a
@@ -16,11 +28,26 @@ This repository contains experimental tooling for Secure Boot on
 installs the boot files into the UEFI
 [ESP](https://en.wikipedia.org/wiki/EFI_system_partition).
 
+
+To make systemd-boot recognize a new boot target, `lanzatool` builds a
+[UKI](https://wiki.archlinux.org/title/Unified_kernel_image) image. To
+avoid having to embed kernel and initrd, we use a custom stub
+`lanzaboote` (see below) that loads kernel and initrd from the ESP.
+
 ## lanzaboote
 
-`lanzaboote` is a UEFI application that is started by systemd-boot (or
-any other EFI boot loader) and loads a Linux kernel and initrd without
-breaking the Secure Boot chain of trust.
+`lanzaboote` is the stub that `lanzatool` uses to form an UKI. It
+loads a Linux kernel and initrd without breaking the Secure Boot chain
+of trust. Instead of rolling our own crypto, `lanzaboote` re-uses the
+signature verification that is built-in to UEFI.
 
-The information what kernel with what command line and initrd to boot
-is embedded into the `lanzaboote` by `lanzatool`.
+## Relevant Nixpkgs Work
+
+This project depends on upstream nixpkgs work:
+
+- https://github.com/NixOS/nixpkgs/pull/191665
+- https://github.com/DeterminateSystems/bootspec-secureboot/
+- https://github.com/DeterminateSystems/bootspec
+
+You can find everything integrated as PoC
+[here](https://github.com/NixOS/nixpkgs/pull/202497).