trustedboot docs

content/en/docs/Architecture/trustedboot.md

@@ -0,0 +1,82 @@
+---
+title: "Trusted Boot Architecture"
+linkTitle: "Trusted Boot"
+weight: 6
+date: 2022-11-13
+description: >
+---
+
+{{% alert title="Warning" %}}
+This section is still a work in progress and only available in Kairos v3.x releases and alphas.
+{{% /alert %}}
+
+Trusted boot is a combination of technologies that allows us to enhance the security posture of a running system. It is composed by FDE, Secure Boot and Measured Boot.
+Trusted boot is an architectural requirement of SENA (Secure Edge Native Architecture) and is a key component of Kairos.
+
+> You can read more about Trusted Boot in https://0pointer.de/blog/brave-new-trusted-boot-world.html and about SENA here: https://kairos.io/blog/2023/04/18/kairos-is-now-part-of-the-secure-edge-native-architecture-by-spectro-cloud-and-intel/
+
+By combining Secure Boot, Measured Boot and FDE we can guarantee that a system was not tampered with, and the user-data is protected by cold attacks, we refer to this combination of technologies stacked together with “Trusted Boot” or “Trusted Boot Experience”. 
+
+*FDE* stands for Full Disk Encryption. It is a security measure that encrypts the entire contents of a disk drive, including the operating system, system files, and user data. The purpose of FDE is to protect data stored on the disk from unauthorized access in the event of theft or loss of the device.
+
+*Secure Boot* is a security feature in modern computer systems that ensures only properly signed and authenticated OSes are allowed to run during the boot process. It helps prevent the loading of malicious or unauthorized code at the early stages of the system startup, thus helping in protecting the integrity of the boot process.
+
+*Measured Boot*, on the other hand, is a security mechanism that goes beyond Secure Boot. It involves creating a record, or "measurements," of each step in the boot process and storing these measurements in a specific hardware dedicated to cryptographically secure operations ( trusted platform module, or TPM) or a similar secure storage. This allows the system to verify the integrity of each component of the boot process and detect any unauthorized changes. Measured Boot provides a more comprehensive and continuous security check throughout the boot sequence.
+
+
+### UKI and USI
+
+[UKI](https://uapi-group.org/specifications/specs/unified_kernel_image/) is a specific file format tailored to achieve a tamper-proof system and encryption of user-data bound to the silicon by relying on HW capabilities. 
+
+> UKI stands for “Unified Kernel Images”. UKI files are a single, fat binary that encompasses the OS and the needed bits in order to boot the full system with a single, verified file. You can read technical details here: Brave New Trusted Boot World.
+
+Trusted Boot in Kairos works by generating UKI images from container images. The UKI file is a single, fat binary that encompasses the OS and the needed bits in order to boot the full system with a single, verified file. This file can be used for upgraes and used as usual in the lifecycle of the Kairos node.
+
+The UKI file is signed with the Secure Boot keys, and the user-data is encrypted with the PCR policies. The UKI file is then loaded by the firmware and booted directly, without any second stage or system pivoting. This is why the UKI file can grow large, and why it requires a specific firmware that supports booting large EFI files. 
+
+Due to the design choice to not boot into a second stage, this is being refered nowadays as **USI** (Unified System Image) instead of UKI, or more simply "Bootstrap Image". The benefits of using Unified system images in opposite of UKIs are that the system can be upgraded without the need of a second stage, and that the entire system is verified and signed.
+
+### Booting process
+
+![boot_1](https://github.com/kairos-io/kairos-docs/assets/2420543/9c406796-b622-4571-abd5-b8d8fed44591)
+
+The booting process of an installed system with Trusted Boot is different from a standard Kairos installation, and can be split down in 4 steps:
+
+1. The Firmware loads the `systemd-boot` bootloader from the EFI partition
+2. `systemd-boot` loads the UKI file from the EFI partition (that can be either the Active system, the passive or recovery system)
+3. The EFI system starts. The kernel and the initrd are loaded from the UKI file, and the kernel is booted with the command line specified in the UKI file. 
+4. The initrd will decrypt the user-data and mount the portions of it in the root filesystem. This includes for instance any changes to `/etc` (like adding new users and passwords), `/usr/local`, and all the mount bindpoints specified in the configuration file (see [Bind mount d ocumentation]({{%relref "/docs/advanced/customizing#bind-mounts" %}}) ). There is no second stage loaded and no system pivoting, the system is booted directly from the UKI file.
+
+### User data encryption and key generation 
+
+It is required in order to generate USI images to have a set of keys and certificates. In order to understand why those keys are required, we need to understand how the user-data is encrypted and how the system is booted.
+
+![bootingkeys](https://github.com/kairos-io/kairos-docs/assets/2420543/725745a0-0ea6-4330-bea3-e6483f53cc3f)
+
+
+The keys are used to sign the UKI file, and to generate a PCR policy keypair required later on by the system in order to decrypt the encrypted partitions. The keys and certificates are generated with the `enki` tool, that is available in the `enki` container image.
+
+### Booting system
+
+![Trusted boot](https://github.com/kairos-io/kairos-docs/assets/2420543/757870d3-3b40-46ea-9c86-13c4a545f167)
+
+There is no difference with a layout of a standard Kairos system (as explained in the [Immutable OS]({{%relref "/docs/architecture/immutable" %}}) page), however in this setup now the partitions containing data are encrypted:
+
+- [List of persistent data path overlayed and encrypted](https://github.com/kairos-io/packages/blob/528682cddf7191fb52580e7c41a33e73c1ee0001/packages/static/kairos-overlay-files/files/system/oem/00_rootfs_uki.yaml#L18) (see also [the bind mount documentation]({{%relref "/docs/advanced/customizing#bind-mounts" %}}) to customize it with your own paths).
+- `/oem` encrypted
+- `/usr/local` encrypted
+- `/etc` ephemeral
+- `/usr` read only
+- `/` immutable
+
+
+### Considerations
+
+### Security considerations
+
+TODO: Design choices (no pivot, no grub,)
+
+
+#### Booting command lines
+
+UKI file's signatures are including also the kernel command line, so any change to the kernel command line will require a new UKI file to be generated and the installer image to be rebuilt. This implies that you cannot change the booting options once the system is installed (and the system won't be able to access the encrypted data)

content/en/docs/Getting started/_index.md

@@ -8,7 +8,8 @@ description: >
 ---
 
 {{% alert title="Note" %}}
-If you prefer video format, you can also watch our [Introduction to Kairos video]({{< relref "Media#introduction-to-kairos" >}} "Media") on the [Media Section]({{< relref "Media" >}} "Media")
+- If you prefer video format, you can also watch our [Introduction to Kairos video]({{< relref "Media#introduction-to-kairos" >}} "Media") on the [Media Section]({{< relref "Media" >}} "Media")
+- If you are looking into installing Kairos with Full disk encryption, see [here]({{< relref "../installation/trustedboot" >}})
 {{% /alert %}}
 
 Ready to launch your Kubernetes cluster with ease? With Kairos, deployment is a breeze! Simply download the pre-packaged artifacts, boot up on a VM or bare metal, and let Kairos handle the rest. Whether you're a Linux or Windows user, our quickstart guide will have you up and running in no time. Kairos can build a Kubernetes cluster for you with just a few simple steps!

content/en/docs/Installation/trustedboot.md

@@ -0,0 +1,231 @@
+---
+title: "Trusted Boot Installations"
+linkTitle: "Trusted Boot"
+weight: 6
+date: 2022-11-13
+description: >
+---
+
+
+{{% alert title="Warning" %}}
+This section is still a work in progress and only available in Kairos v3.x releases and alphas.
+{{% /alert %}}
+
+"Trusted Boot" is a combination of technologies that allows us to guarantee that a system was not tampered with, and the user-data is protected by cold attacks, it is composed by FDE, Secure Boot and Measured Boot.
+
+If you want to learn more on what Trusted Boot is and how it works, see the [Trusted Boot Architecture]({{< relref "../architecture/trustedboot" >}}) page. This page describes how to enable Trusted Boot support in Kairos.
+
+## Enable Trusted Boot in Kairos
+
+Kairos supports Trusted boot by generating specific installable medium. This feature is optional and works alongside how Kairos works.
+
+## Requirements
+
+- Secure boot available in the system
+- The Hardware should have a TPM chip or fTPM enabled
+- The Hardware should be capable of booting large EFI files (>32MB)
+- Base image of the OS needs to have at least systemd 252 or newer ( for example ubuntu >=23.04 or fedora >=38 )
+
+## Usage
+
+In order to boot into UKI mode, you need to build a special ISO file with the UKI files. To build this medium you have to generate a set of keypairs first: one for the Secure boot and one for the PCR policies required to encrypt the user-data.
+
+Any change, or upgrade of the node to a new version of the OS requires those assets to be regenerated with these keypairs, including the installer ISO, and the EFI files used for upgrading. The keys are used to *sign* and *verify* the EFI files, and the PCR policies are used to *encrypt* and *decrypt* the user-data, and thus are required to be the same for the whole lifecycle of the node.
+
+The steps below will guide you into generating the installable assets, and how to re-generate the assets to upgrade the node to a new version of the OS.
+
+### Requirements
+
+- Docker
+- Git
+- A Linux machine with KVM (for testing the images locally)
+
+### Build the container image used to generate keys and installable medium
+
+```bash
+# Build the container image that will be used to generate the keys and installable medium
+git clone https://github.com/kairos-io/enki.git
+cd enki
+docker build -t enki --target tools-image .
+```
+
+### Key generation
+
+To generate the Secure boot certificates and keys run the following commands:
+
+```bash
+# Generate the keys
+docker run -v $PWD/keys:/work/keys -ti --rm enki genkey "$MY_ORG" -o /work/keys
+```
+
+{{% alert title="Warning" %}}
+It is very important to preserve the keys generated in this process in a safe place. Loosing the keys will prevent you to generate new images that can be used for upgrades.
+{{% /alert %}}
+
+### Enroll the keys in Secure Boot
+
+If your machine is in UEFI setup mode Secure Boot keys will be automatically enrolled. 
+
+If UEFI setup mode is not available, you need to enroll the keys manually in the BIOS/UEFI.
+
+This process can vary depending on the vendor, but in general you need to enter the BIOS/UEFI setup during early boot and import the keys, for an example outline you can check the steps for [HPE Hardware](https://techlibrary.hpe.com/docs/iss/proliant-gen10-uefi/GUID-E4427875-D123-4BBF-9056-342168478A02.html).
+
+A video of the process in QEMU is available [here](https://github.com/kairos-io/kairos/assets/2420543/e45f6a08-ec74-4cfd-bdf0-aeb7b23ac9bc).
+
+### Building installable medium
+
+To build the installable medium you need to run the following command:
+
+{{% alert title="Warning" %}}
+
+This method is still a work in progress.
+For now build the testing Kairos iso with:
+
+```bash
+# clone the repo
+git clone https://github.com/kairos-io/kairos
+
+# cd into the repo
+cd kairos
+
+IMAGE=quay.io/kairos/fedora:38-core-amd64-generic-v3.0.0-alpha1
+
+# build the iso with Earthly
+earthly +uki-iso --BASE_IMAGE=$IMAGE
+
+# resulting ISO is in: build/kairos-fedora-38-core-amd64-generic-v3.0.0-alpha1.uki.iso
+
+# Multiple boot options
+earthly +uki-iso --BASE_IMAGE=$IMAGE --ENKI_FLAGS="--cmdline rd.blacklist=i915"
+```
+
+{{% /alert %}}
+
+```bash
+CONTAINER_IMAGE=quay.io/kairos/fedora:38-core-amd64-generic-v3.0.0-alpha1
+docker run --rm -v $PWD/build:/result -v $PWD/keys/:/keys enki build-uki $CONTAINER_IMAGE -o /result/trustedboot.iso -k /keys
+```
+
+### Installation
+
+The installation process is performed as usual and the [Installation instructions]({{< relref "../installation" >}}) can be followed, however the difference is that user-data will be automatically encrypted (both the OEM and the persistent partition) by using the TPM chip and the Trusted Boot mechanism.
+
+### Upgrades
+
+In order to upgrade a node to a new version of the OS, you need to generate again the installable medium with the same keys used in the steps before. The process will generate an EFI file which we will pack into a container image that will be used to upgrade the node.
+
+To generate the upgrade image you need to create a naked container image containing containing the EFI files, for example:
+
+{{% alert title="Warning" %}}
+Flow not entirely tested/validated yet
+{{% /alert %}}
+
+```bash
+VERSION=v3.0.0-alpha2
+UKI=kairos-fedora-38-core-amd64-generic-v${VERSION}.efi
+UPGRADE_IMAGE=ttl.sh/kairos-uki-tests/upgrade-image
+EFI_FILE=/path/to/efi/file
+
+mkdir upgrade-image
+mkdir -p upgrade-image/loader/entries
+mkdir -p upgrade-image/EFI/kairos/
+
+mv $EFI_FILE upgrade-image/EFI/kairos/${UKI}
+
+# default @saved
+cat <<EOF > upgrade-image/loader/loader.conf
+default kairos-$VERSION.conf
+timeout 5
+console-mode max
+editor no
+EOF
+
+cat <<EOF > upgrade-image/loader/entries/kairos-$VERSION.conf
+title Kairos $VERSION
+efi /EFI/kairos/$UKI.efi
+version $VERSION
+EOF
+
+cd upgrade-image
+docker build -t $UPGRADE_IMAGE -<<DOCKER
+FROM scratch
+COPY . /
+DOCKER
+```
+
+### Testing the images locally
+
+To test the ISO file locally QEMU can be used. In order to test Secure Boot components you need an ed2k firmware with secureboot in QEMU. If you don't have QEMU locally and/or you don't have the correct dependencies you can follow the steps below that build a container image with QEMU and the needed dependencies and uses it to run the ISO file.
+
+1. Build the container image with the dependencies (note to replace disk, VM size and ISO file name):
+
+```bash
+docker build -t fedora-qemu -<<DOCKER
+FROM fedora
+RUN dnf install -y dnf-plugins-core
+RUN dnf config-manager --add-repo http://www.kraxel.org/repos/firmware.repo
+RUN dnf install -y edk2.git-ovmf-x64 qemu
+RUN dnf install -y swtpm wget
+WORKDIR /
+RUN wget https://github.com/kairos-io/kairos/raw/master/tests/assets/efivars.fd
+WORKDIR /work
+
+RUN <<EOF
+echo "#!/bin/bash -ex" >> /entrypoint.sh
+echo 'nohup swtpm socket --tpmstate dir=/tmp/ --ctrl type=unixio,path=/tmp/swtpm-sock --log level=20 --tpm2 &>/dev/null & ' >> /entrypoint.sh
+echo '[ ! -e /work/disk.img ] && qemu-img create -f qcow2 "/work/disk.img" 8G' >> /entrypoint.sh
+echo '/usr/bin/qemu-system-x86_64 -drive if=pflash,format=raw,unit=0,file="/usr/share/edk2/ovmf/OVMF_CODE.secboot.fd",readonly=on -drive if=pflash,unit=1,format=raw,file="/efivars.fd" -accel kvm -cpu host -m 8096 -drive file=/work/disk.img,if=none,index=0,media=disk,format=qcow2,id=disk1 -device virtio-blk-pci,drive=disk1,bootindex=0 -boot order=dc -vga virtio -cpu host -smp cores=4,threads=1 -machine q35,smm=on -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0 \$@' >> /entrypoint.sh
+EOF
+RUN chmod +x /entrypoint.sh
+ENTRYPOINT [ "/entrypoint.sh" ]
+DOCKER
+```
+
+2. Run the container image with the ISO file:
+
+```bash
+# console only
+docker run --privileged -v $PWD:/work -v /dev/kvm:/dev/kvm --rm -ti fedora-qemu -cdrom /work/kairos-fedora-38-core-amd64-generic-v3.0.0-alpha1.uki.iso -nographic
+
+# GTK (insecure)
+# xhost si:localuser:root # give access to root account to connect to the X server socket
+# docker run -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix --privileged -v $PWD:/work -v /dev/kvm:/dev/kvm --rm -ti fedora-qemu -cdrom /work/kairos-fedora-38-core-amd64-generic-v3.0.0-alpha1.uki.iso
+```
+
+Note: To stop the QEMU container you can use `Ctrl-a x` or `Ctrl-a c` to enter the QEMU console and then `quit` to exit.
+
+### Data Encryption
+
+The user-data will be automatically encrypted during installation, along with the OEM and the persistent partition by using the TPM chip and the Trusted Boot mechanism.
+
+#### Additional partitions
+
+Additional partitions can be encrypted and specified as part of the cloud-config used during the installation process, for example:
+
+```yaml
+install:
+  extra-partitions:
+    - name: second_partition
+      size: 100
+      fs: ext2
+      label: PARTITION_TWO
+  encrypted_partitions:
+  - PARTITION_TWO
+```
+
+A full example can be:
+```yaml
+install:
+  device: "auto" # Install to the biggest drive
+  auto: true    # Enables auto installation
+  partitions:
+    persistent:
+      size: 500 # Set persistent partition to 500MB (otherwise takes the whole disk)
+  extra-partitions:
+    - name: second_partition
+      size: 100
+      fs: ext2
+      label: PARTITION_TWO
+  encrypted_partitions:
+  - PARTITION_TWO
+```