T861: secure-boot: replace install mok with mokutilmergify/bp/scutum/pr-2341

Enrolling a MOK is only needed for development with custom signed images.
Official LTS images ship officially signed binaries and boot out of the
box.

(cherry picked from commit 07df2e477ba2c6846ca5626fd5e8c2e9a96cfd3a)

1 files changed, 25 insertions, 18 deletions

diff --git a/docs/installation/secure-boot.md b/docs/installation/secure-boot.md
index 538153ff..63814c19 100644
--- a/docs/installation/secure-boot.md
+++ b/docs/installation/secure-boot.md
@@ -6,41 +6,45 @@ lastproofread: '2026-01-26'
 
 # Secure Boot
 
-Initial UEFI Secure Boot support is available ({vytask}`T861`). VyOS uses
-`shim` from Debian 12 (Bookworm), which is properly signed by the UEFI
-Secure Boot 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.
+VyOS uses `shim` from Debian 13 (trixie), which is properly signed by the
+UEFI Secure Boot key from Microsoft.
+
+:::{important}
+Enrolling a {abbr}`MOK (Machine Owner Key)` is only required for development
+purposes, when testing UEFI Secure Boot with a custom image that is not signed
+by VyOS Networks. Official LTS images contain officially signed binaries and
+run out of the box, without any key enrollment.
 :::
 
+For more information see [Microsoft UEFI Signing Requirements](
+https://techcommunity.microsoft.com/blog/hardware-dev-center/updated-microsoft-uefi-signing-requirements/1062916).
+
 To generate a custom ISO with your own secure boot keys, run the following
 commands prior to your ISO image build:
 
 ```bash
 cd vyos-build
 CA_DIR="data/certificates"
-SHIM_CERT_NAME="vyos-dev-2025-shim"
-VYOS_KERNEL_CERT_NAME="vyos-dev-2025-linux"
+CA_YEAR="$(date +%Y)"
+SHIM_CERT_NAME="vyos-dev-${CA_YEAR}-shim"
+VYOS_KERNEL_CERT_NAME="vyos-dev-${CA_YEAR}-linux"
 
 openssl req -new -x509 -newkey rsa:4096 -keyout ${CA_DIR}/${SHIM_CERT_NAME}.key -out ${CA_DIR}/${SHIM_CERT_NAME}.der \
-  -outform DER -days 36500 -subj "/CN=VyOS Networks Secure Boot CA/" -nodes
+  -outform DER -days 36500 -subj "/CN=VyOS Networks - DEVELOPMENT - Secure Boot CA/" -nodes
 openssl x509 -inform der -in ${CA_DIR}/${SHIM_CERT_NAME}.der -out ${CA_DIR}/${SHIM_CERT_NAME}.pem
 
 openssl req -newkey rsa:4096 -sha256 -nodes -keyout ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.key \
   -out ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.csr -outform PEM -days 3650 \
-  -subj "/CN=VyOS Networks Secure Boot Signer 2025 - linux/"
+  -subj "/CN=VyOS Networks - DEVELOPMENT - Secure Boot Signer - linux/"
 openssl x509 -req -in ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.csr -CA ${CA_DIR}/${SHIM_CERT_NAME}.pem \
   -CAkey ${CA_DIR}/${SHIM_CERT_NAME}.key -CAcreateserial -out ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.pem -days 3650 -sha256
 ```
 
-
 ## 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.
+As VyOS development builds have no access to the HSM stored signing key, you
+need to enroll the previously generated {abbr}`MOK (Machine Owner Key)` to
+the system.
 
 First, disable UEFI Secure Boot for the installation.
 
@@ -50,10 +54,13 @@ First, disable UEFI Secure Boot for the installation.
 
 Proceed with the standard VyOS {ref}`installation <permanent_installation>` on
 your system. Instead of the final `reboot` command, enroll the
-{abbr}`MOK (Machine Owner Key)`.
+{abbr}`MOK (Machine Owner Key)` using `mokutil`. The shim certificate generated
+above is part of the image and available as
+`/var/lib/shim-signed/mok/vyos-dev-<year>-shim.der`, where `<year>` is the year
+the certificate was generated.
 
 ```none
-vyos@vyos:~$ install mok
+vyos@vyos:~$ sudo mokutil --ignore-keyring --import /var/lib/shim-signed/mok/vyos-dev-2026-shim.der
 input password:
 input password again:
 ```
@@ -211,5 +218,5 @@ error: you need to load the kernel first
 ```
 
 This error means the Machine Owner Key used to sign the Kernel is not trusted
-by your UEFI. Install the MOK using the `install mok` command as described
+by your UEFI. Enroll the MOK using the `mokutil` command as described
 above.