Secure Boot

Initial UEFI secure boot support is available (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:

cd vyos-build
CA_DIR="data/certificates"
SHIM_CERT_NAME="vyos-dev-2025-shim"
VYOS_KERNEL_CERT_NAME="vyos-dev-2025-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
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/"
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 MOK to the system.

First of all you will need to disable UEFI secure boot for the installation.

Disable UEFI secure boot

Proceed with the regular VyOS installation on your system, but instead of the final reboot we will enroll the MOK.

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

Disable UEFI secure boot

Select Enroll MOK

Disable UEFI secure boot

You can now view the key to be installed and continue with the Key installation

Disable UEFI secure boot
Disable UEFI secure boot

Now you will need the password previously defined

Disable UEFI secure boot

Now reboot and re-enable UEFI secure boot.

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:

vyos@vyos:~$ show secure-boot
SecureBoot enabled

vyos@vyos:~$ show log kernel | match Secure
Oct 08 19:15:41 kernel: Secure boot enabled

vyos@vyos:~$    show version
Version:          VyOS 1.5-secureboot
Release train:    current
Release flavor:   generic

Built by:         [email protected]
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

Image Update

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.

During image installation you will install your MOK into the UEFI variables to add trust to this key. After enabling secure boot support in UEFI again, you can only boot into your signed image.

It is no longer possible to boot into a CI generated rolling release as those are currently not signed by a trusted party (T861 work in progress). This also means that you need to sign all your successor builds you build on your own with the exact same key, otherwise you will see:

error: bad shim signature
error: you need to load the kernel first

Linux Kernel

In order to add an additional layer of security that can already be used in nonesecure boot images already is ephem,eral key signing of the Linux Kernel modules.

https://patchwork.kernel.org/project/linux-integrity/patch/20210218220011.67625-5-nayna@linux.ibm.com/

Whenever our CI system builds a Kernel package and the required 3rd party modules, we will generate a temporary (ephemeral) public/private key-pair that’s used for signing the modules. The public key portion is embedded into the Kernel binary to verify the loaded modules.

After the Kernel CI build completes, the generated key is discarded - meaning we can no londer sign additional modules with out key. Our Kernel configuration also contains the option CONFIG_MODULE_SIG_FORCE=y which means that we enforce all modules to be signed. If you try to load an unsigned module, it will be rejected with the following error:

insmod: ERROR: could not insert module malicious.ko: Key was rejected by service

Thos we close the door to load any malicious stuff after the image was assembled into the Kernel as module. You can of course disable this behavior on custom builds.

Troubleshoot

In most of the cases if something goes wrong you will see the following error message during system boot:

error: bad shim signature
error: you need to load the kernel first

This means that the Machine Owner Key used to sign the Kernel is not trusted by your UEFI. You need to install the MOK via install mok as stated above.