Add initial secure boot documentation

1 files changed, 116 insertions, 0 deletions

diff --git a/docs/installation/secure-boot.rst b/docs/installation/secure-boot.rst
new file mode 100644
index 00000000..07fdfbf4
--- /dev/null
+++ b/docs/installation/secure-boot.rst
@@ -0,0 +1,116 @@
+.. _secure_boot:
+
+###########
+Secure Boot
+###########
+
+Initial UEFI secure boot support is available (:vytask:`T861`). We utilize
+``shim`` from Debian 12 (Bookworm) which is properly signed by the UEFI
+SecureBoot key from Microsoft.
+
+.. note:: There is yet no signed version of ``shim`` for VyOS, thus we
+   provide no signed image for secure boot yet. If you are interested in
+   secure boot you can build an image on your own.
+
+To generate a custom ISO with your own secure boot keys, run the following
+commands prior to your ISO image build:
+
+.. code-block:: bash
+
+  cd vyos-build
+  openssl req -new -x509 -newkey rsa:4096 \
+    -keyout data/live-build-config/includes.chroot/var/lib/shim-signed/mok/MOK.key \
+    -outform DER -out MOK.der -days 36500 -subj "/CN=MyMOK/" -nodes
+  openssl x509 -inform der \
+    -in data/live-build-config/includes.chroot/var/lib/shim-signed/mok/MOK.der \
+    -out MOK.pem
+
+************
+Installation
+************
+
+As our version of ``shim`` is not signed by Microsoft we need to enroll the
+previously generated :abbr:`MOK (Machine Owner Key)` to the system.
+
+First of all you will need to disable UEFI secure boot for the installation.
+
+.. figure:: /_static/images/uefi_secureboot_01.png
+   :alt: Disable UEFI secure boot
+
+Proceed with the regular VyOS :ref:`installation <permanent_installation>` on
+your system, but instead of the final ``reboot`` we will enroll the
+:abbr:`MOK (Machine Owner Key)`.
+
+.. code-block:: none
+
+  vyos@vyos:~$ install mok
+  input password:
+  input password again:
+
+The requested ``input password`` can be user chosen and is only needed after
+rebooting the system into MOK Manager to permanently install the keys.
+
+With the next reboot, MOK Manager will automatically launch
+
+.. figure:: /_static/images/uefi_secureboot_02.png
+   :alt: Disable UEFI secure boot
+
+Select ``Enroll MOK``
+
+.. figure:: /_static/images/uefi_secureboot_03.png
+   :alt: Disable UEFI secure boot
+
+You can now view the key to be installed and ``continue`` with the Key installation
+
+.. figure:: /_static/images/uefi_secureboot_04.png
+   :alt: Disable UEFI secure boot
+
+.. figure:: /_static/images/uefi_secureboot_05.png
+   :alt: Disable UEFI secure boot
+
+Now you will need the password previously defined
+
+.. figure:: /_static/images/uefi_secureboot_06.png
+   :alt: Disable UEFI secure boot
+
+Now reboot and re-enable UEFI secure boot.
+
+.. figure:: /_static/images/uefi_secureboot_07.png
+   :alt: Disable UEFI secure boot
+
+VyOS will now launch in UEFI secure boot mode. This can be double-checked by running
+either one of the commands:
+
+.. code-block:: none
+
+  vyos@vyos:~$ show secure-boot
+  SecureBoot enabled
+
+.. code-block:: none
+
+   vyos@vyos:~$ show log kernel | match Secure
+   Oct 08 19:15:41 kernel: Secure boot enabled
+
+.. code-block:: none
+
+    vyos@vyos:~$    show version
+    Version:          VyOS 1.5-secureboot
+    Release train:    current
+    Release flavor:   generic
+
+    Built by:         autobuild@vyos.net
+    Built on:         Tue 08 Oct 2024 18:00 UTC
+    Build UUID:       5702ca38-e6f4-470f-b89e-ffc29baee474
+    Build commit ID:  9eb61d3b6cf426
+
+    Architecture:     x86_64
+    Boot via:         installed image
+    System type:      KVM guest
+    Secure Boot:      enabled   <-- UEFI secure boot indicator
+
+    Hardware vendor:  QEMU
+    Hardware model:   Standard PC (i440FX + PIIX, 1996)
+    Hardware S/N:
+    Hardware UUID:    1f6e7f5c-fb52-4c33-96c9-782fbea36436
+
+    Copyright:        VyOS maintainers and contributors