updates

content/en/docs/Architecture/trustedboot.md

@@ -0,0 +1,32 @@
+---
+title: "Trusted Boot Architecture"
+linkTitle: "Trusted Boot"
+weight: 6
+date: 2022-11-13
+description: >
+---
+
+
+*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.
+
+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”. 
+
+> 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/
+
+
+
+### Considerations
+
+
+### Security considerations
+
+TODO: Design choices (no pivot, no grub, etc)
+
+
+#### 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

@@ -9,7 +9,7 @@ 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 are looking into installing Kairos with Full disk encryption, see [here]({{< relref "../reference/trustedboot" >}})
+- 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,198 @@
+---
+title: "Trusted Boot Installations"
+linkTitle: "Trusted Boot"
+weight: 6
+date: 2022-11-13
+description: >
+---
+
+"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 special installable medium, and we boot into what we call “UKI-mode”. [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. This feature is optional and works alongside how Kairos works.
+
+> 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.
+
+## 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)
+
+## 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 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 "Kairos" -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:
+
+```bash
+CONTAINER_IMAGE=quay.io/kairos/fedora:38-core-amd64-generic-v3.0.0-alpha
+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:
+
+```bash
+VERSION=2.5.0-1-g21e04f76.uki
+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:
+
+```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=raw,id=disk1 -device virtio-blk-pci,drive=disk1,bootindex=0 -boot menu=on -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-v2.5.0-1-g21e04f76.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-v2.5.0-1-g21e04f76.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
+```