UEFI Secure Boot
This article aims to describe and clarify everything surrounding UEFI Secure Boot, and the support MassOS has for it.
Note that secure boot is only relevant to and supported on UEFI - if your system boots in Legacy BIOS mode, none of this article applies to you, and you can safely ignore it. Unless you want to read it anyway for curiosity and/or learning purposes - in which case, go right ahead!
Secure boot is a technology supported by most modern UEFI firmwares, which allows the system to verify, on boot-up, whether or not an installed operating system or bootloader is allowed to start up. It does this by containing a database of "trusted" secure boot signatures - if the system attempts to boot any .efi binary on the system which is not signed by a secure boot key whose signature is included in this database, then the system will refuse to boot, and most likely give a full screen error message on startup, reading something along the lines of SECURE BOOT VIOLATION.
By default, all UEFI firmwares of machines that ship (or shipped) with Windows 8 or newer pre-installed, will be configured with secure boot enabled by default, and the system's secure boot database will only contain the certificates for Microsoft's official signing keys. These keys are used to sign Windows, and a few commercially-supported GNU/Linux distributions, such as Ubuntu and Fedora.
Historically, secure boot support in MassOS had many limitations, however as of build experimental-20251221, almost all of the flaws have been ironed out, and secure boot is now fairly seamless, with minimal intervention / additional steps required by users. Nonetheless, some manual steps are still required. This document exists to clarify those steps, as well as to provide some ethical discussion around UEFI secure boot. The main sections you will want to read are the following:
- Importing the MassOS secure boot certificate (required read if you want to boot MassOS under UEFI secure boot).
- Signing custom kernel modules (required read if you install any out-of-tree kernel modules on MassOS under UEFI secure boot).
If you do not need or want secure boot enabled at all, this section describes how to disable it. If you instead want to use MassOS with secure boot ENABLED, then please disregard this section, and skip ahead to Importing the MassOS secure boot certificate.
By far the easiest course of action to allow MassOS, or any other non-Microsoft-signed operating system, to boot successfully, is to simply disable secure boot outright. This is the recommended approach in most cases, but there are a few specific situations where it may not be possible. This includes, but is not limited to, the following:
- You are dual-booting with Windows and some Windows program requires secure boot to be enabled.
- For example, the Vanguard anti-cheat system, which is used by various online video games including Valorant, will refuse to run if secure boot is not enabled.
- Obviously you could just make the decision to not play a proprietary video game which uses a borderline-malware kernel-level anti-cheat system, and this would be the easiest course of action, but who are we to try and dictate what software you can or can't use, and what games you can or can't play, on an operating system completely unrelated to MassOS?
- For example, the Vanguard anti-cheat system, which is used by various online video games including Valorant, will refuse to run if secure boot is not enabled.
- You are dual-booting with Windows, and need to use some Windows system features which refuse to work without secure boot.
- For example, Windows Device Encryption, which is an alternative to Bitlocker on Home (non-Pro) editions of Windows, for enabling encryption of data. But unlike Bitlocker, it requires secure boot to be enabled.
- A few systems have UEFI firmwares which secure boot cannot be disabled on. This is extremely uncommon these days, but some older models of laptop from the Microsoft Surface and Lenovo Thinkpad lineups (for example), were known to be this way.
- Modders often found ways to bypass this, e.g., by developing and flashing custom firmwares (such as Coreboot) onto the locked-down machine. But this obviously comes with the risk of bricking the machine, especially if the only possible method of flashing is by manually using a programmer device connected to the physical BIOS chip on the mainboard itself.
If none of the above situations apply to you, read on for instructions on how to disable secure boot. Otherwise, skip ahead to the following section of the article.
NOTE: It is a common misconception that Microsoft's system requirements for Windows 11 require secure boot to be enabled. Secure boot needs to be supported on the system, but it does NOT need to be enabled, for the system to meet the Windows 11 system requirements. However, as mentioned above, Microsoft may block certain features under Windows if secure boot is not enabled, such as Windows Device Encryption.
Note that this guide is not exhaustive. Every single system's firmware settings will differ in some way, and may place the options relating to secure boot in different places, or under different submenus. This guide provides example images for a few systems with widely-used firmware interfaces.
-
Enter the firmware settings. This is normally done by pressing ESC, DEL, or one of the function keys while the system starts up. You should consult the manual of your device or motherboard to confirm. Alternatively, you can try every possible key until you find one which works. Alternatively, if you are using Windows, open the start menu, and press the Restart button/icon from the start menu while holding down the Shift key. This will restart into a blue menu, and you can select Advanced Options, then UEFI Firmware Settings, to enter the firmware setup. Likewise, if you are using a Linux system, you can type the command
systemctl reboot --firmware-setup, which will immediately restart the system and enter the UEFI firmware settings automatically. You will know once you are inside the firmware setup, as it should list some information about your system, including about the system's CPU, RAM, Motherboard and BIOS, and there should be menus you can interact with (either tabs at the top of the screen, or options on the screen). Some firmwares allow you to navigate with a mouse, others only using a keyboard, so keep this in mind when navigating through the firmware settings. -
Find the secure boot option, which may be under the Security tab or the Boot tab.
-
Set the secure boot option to DISABLED.
-
Save and exit the firmware settings.
You should now be able to boot the MassOS Live CD without any issues.
If you've decided to keep secure boot enabled, you will need to import the MassOS secure boot certificate into your firmware before you can boot MassOS (this applies to both the Live CD, and the system once it's fully installed - but the import process only needs to be done once).
Note that if you are using a custom build instead of an official one published by the MassOS developers, then it will be signed with that custom builder's keys instead of the official MassOS keys. But the import process does not change. It is also possible to import multiple keys, if necessary, but whether or not you need to depends on whether or not you are using an official build, a custom build, or both.
Regardless of whether the build is official or custom, the secure boot certificate files will be embedded in the MassOS ISO's bootable section, which will expose itself as a regular volume from the firmware settings. As such, you only need to ensure you have written the ISO to a USB flash drive, as described in Installing MassOS, and you can then proceed with the importing process as described below.
NOTE: If you instead want to import the certificates ahead of time, before creating the bootable USB, then you will need to copy them onto a normal USB flash drive which is formatted to either FAT or FAT32. For the official MassOS keys, you can obtain them from https://dmassey.net/files/massos-secureboot-certs as a ZIP file. Simply extract the contents of the ZIP file onto the flash drive. For custom keys, you will need to approach the custom builder to see if they provide their keys outside of the custom build itself. If not, you may be forced to use the method above of importing them from the bootable USB. Alternatively, they may be extracted from the ISO image itself, under the secureboot/ directory.
NOTE: The previous defacto method was to import the MassOS secure boot certificate directly into your UEFI's Authorized Signatures database. Starting with MassOS experimental-20251018, this is no longer needed, and a much simpler process of importing into the MokList can be used instead. This is because MassOS has switched to using a Microsoft-signed shim, and switched to a newer version of GRUB which fully supports utilizing shim for all verification. If you still, however, wish to use the other method (which is much more complicated and not even permitted by all firmwares), it is shown below, in the section titled Alternative method for importing the certificate.
Firstly, boot up the MassOS installation media on your USB flash drive, as described in Installing MassOS. This will cause the following screen to appear, reporting a supposed "Security Violation". Do NOT be alarmed by this - it is normal/expected at this stage:
Select "OK", and then press any key during the countdown to run MokManager:
Use the arrow keys to navigate down to Enroll key from disk, and press enter to select it:
Select the drive/volume labelled MASSOS_EFI. This is the bootable section of the MassOS installation media. If it appears multiple times, select the topmost entry which matches this name:
Select the file named ENROLLME.cer:
If desired, you can select View Key 0 to verify the certificate you are about to import is correct:
The text displayed should show the name of the certificate that signed the MassOS build. For official MassOS builds, the current key is MassOS Project Official SB Signing 2025, and its serial number and fingerprint are shown in the image below:
Press any key to go back to the previous screen, and then select Continue:
Select Yes to confirm enrollment of the key:
Select Reboot and then boot up the MassOS installation media again. It should now succeed and no longer show a security violation error screen. This is all you need to do - you are now good to go:
NOTE: This method is more complicated and no longer needed in most cases. The guide is left here for informational purposes only. Please follow the above method instead, if possible.
NOTE: The UEFI firmwares on some systems (particularly entry-level laptops and the like) do not expose options for importing or otherwise managing secure boot databases. Please try to follow the guide below, hopefully it works for you. It is not known to be possible to use userspace tools such as KeyTool.efi or efi-updatevar, unless you take control of the entire secure boot envrionment (which, again, is complicated and outside the scope of this guide), as it requires Authorized Signatures to be signed by the firmware's KEK (but importing directly from the firmware interface, as described below, does not). Your mileage may vary. If you are unable to complete the process below, please visit DanielMYT's secureboot-scripts repository, which aims to document the process of taking full control of secure boot, as well as providing scripts to make it easier to do so. There is also a pinned issue on this repository containing an extremely simple guide for taking control of secure boot.
This guide will demonstrate how to import the MassOS secure boot certificate into your UEFI firmware's Authorized Signatures (db) list itself. Doing this allows you to boot any EFI executable signed by the MassOS secure boot key, without needing to use Shim, and therefore without needing SBAT metadata embedded in the EFI binary. As previously mentioned, it is an advanced process, and is only needed in rare circumstances - so is only recommended if you know you need this.
You first need to head into your firmware settings and locate the secure boot related options. Please see the How to disable secure boot section above for information about this (obviously only the information specific to entering the firmware settings and locating the secure boot options - not disabling secure boot, since you don't want to do that).
Once you are in the firmware, head to the security tab. You may first need to access the "Advanced Options" - often by pressing the F2 or DEL key (but this may differ between firmware interfaces). Your firmware may look slightly different to the one below (including possibly having a graphical interface instead of the TUI-based environment you see in these images), but functionally it should be very similar, so these instructions should still apply.
If "Secure Boot" appears as one of the options, select it.
It should descend into the submenu showed in the image below. First, you need to ensure Secure Boot is ENABLED, and enable it if it isn't. Then, you need to set the Secure Boot Mode to CUSTOM, so as to allow you to import custom certificates. Finally, enter the Key Management submenu. All three of these steps are demonstrated in the image below.
Navigate down to the Authorized Signatures (db) option, and then select it.
Choose Append (NOT Update).
You will be asked whether or not to load the factory default. Select NO. Do not worry, as this will not overwrite or erase the existing certificates (e.g., Microsoft ones).
You will be shown a list of devices. If the bootable USB is the only flash drive connected to the system, there should be no other options to confuse you (you can ignore SATA, NVMe, and related options which correspond to internal drives). If instead you decided to manually put the certificate files on a USB flash drive, it should also appear here. Select the drive now.
Select the <secureboot> directory (this may not be needed if you instead extracted the files to a custom USB flash drive and put them in the top-level directory).
Select ONLY the db.auth file, which is the signed list of authorized signatures for the MassOS secure boot certificate. All the other files are not needed in this context.
If you are asked what the Input File Format is, select Authenticated Variable.
Now confirm the import by selecting YES when asked to update db with content from db.auth.
A small box with the word Success should be displayed. This indicates that the import was successful.
Now, before restarting your system, you can proceed to verify the import was successful, as described in the following section.
Select Authorized Signatures (db) again. But this time, select Details, to view the list of authorized secure boot signatures registered in the firmware.
As shown in the following image, the list should display all the Microsoft-related ones which are built into the firmware to begin with, and the MassOS key should be shown alongside them (as well as, of course, any other keys you may have previously imported).
The name of the certificate should match what you expect to see. For the official MassOS key, it is MassOS Project Official SB Signing 2025. But a custom key used to sign an unofficial build will have a different name (which ideally should be descriptive, i.e., contain the real name or perhaps pseudonym of the person who compiled the custom build - check with the custom builder if you are at all in doubt).
NOTE: If you, at any point in the future, want to remove the imported MassOS secure boot certificate(s) from your firmware, and reset the key database to the default, then you can do this with the Restore Factory Keys option.
You can now head back to the main menu of the firmware settings, and proceed to save and exit. This is important, since your changes may not otherwise be saved.
But with all this done, you should now be able to boot MassOS with secure boot enabled! Good luck.
NOTE: Please update to MassOS build experimental-20251221 or newer, if you are currently on an older version. It fixes a critical issue regarding the use of MOKs.
An important part of UEFI secure boot is that is should enforce hardening features within the operating system too. One such hardening feature in MassOS is the use of kernel lockdown, which mandates that all kernel modules that want to load on the system must be signed by a key that the kernel trusts. For first-party modules built into MassOS, this is not a concern, as they are already signed by the main MassOS secure boot key which was previously enrolled in an earlier section of this document. However, the issue arises when you as the user want/need to build and install third-party kernel modules which are not included by default. In order for those to be signed, a MOK (Machine Owner Key) must be used.
On installation of MassOS, a MOK is automatically generated for you for that machine, designed for the purpose discussed above. However, you must import it into the firmware so it will be trusted by the kernel. Run the following command to do this:
sudo mokutil --import /var/lib/shim-signed/mok/MOK.der
You will be prompted to enter a password. You can type anything you want here, as it is only used once, to confirm the MOK import, later. We therefore DON'T recommend entering a long or complicated password.
After the command completes, restart your system. You will automatically boot into MokManager; press any key at the main screen to ensure you run MokManager instead of continuing the boot as normal.
Select Enroll MOK.
Select View Key.
Confirm that the key name appears as Auto-generated MOK for MassOS [...]. The date displayed for you will correspond to when you installed MassOS. The fingerprint and ID numbers will differ from those shown in this example image.
Select Continue.
Select Yes.
Enter the password you created when you ran the mokutil --import command above. It will not be displayed in the clear as you type it.
The import process is now complete. Select Reboot, and you will boot back into MassOS.
The rest of this section provides examples of situations under which you may install third party kernel modules, and whether or not manual signing with your MOK is necessary.
Any kernel modules you install using DKMS should automatically get signed by your MOK. You can check this by inspecting the file /etc/dkms/framework.conf, which should contain the following lines:
mok_signing_key=/var/lib/shim-signed/mok/MOK.priv
mok_certificate=/var/lib/shim-signed/mok/MOK.der
No intervention by you should be required.
When you install VirtualBox using the .run installer you download from the VirtualBox website, it will automatically compile its kernel modules and sign them using your MOK. No intervention by you should be required. If the installer reports that a successful installation, then you are good to go. If there is a problem, it will tell you that building/signing the modules was unsuccessful.
If you ever need to rebuild the VirtualBox host modules, without reinstalling the entirety of VirtualBox, you can do so using the following command:
sudo vboxconfig
When you install VMware using the .bundle installer for Linux, it will unfortunately not sign its host modules using your MOK. You will therefore have to do it manually. Run the following two commands (they will not produce any output):
sudo kmodsign sha512 /var/lib/shim-signed/mok/MOK.{priv,der} /usr/lib/modules/$(uname -r)/misc/vmmon.ko
sudo kmodsign sha512 /var/lib/shim-signed/mok/MOK.{priv,der} /usr/lib/modules/$(uname -r)/misc/vmnet.ko
Now restart your system, and you should be good to go. If ever the VMware modules get rebuilt, e.g., after a MassOS upgrade which installs a newer kernel, then you may need to run the above commands again.
The above commands used for the VMware modules can be adapted for signing any loose module which is not auto-managed by DKMS. Simply replace the module's path (e.g. misc/vmmon.ko) with your module's path.
You can check if a module is signed by running the command sudo modinfo <module-name>, for example:
sudo modinfo vmmon
It should contain lines similar to the following (exact values will differ from what is shown in this example):
sig_id: PKCS#7
signer: Auto-generated MOK for MassOS on 2025-12-21
sig_key: 72:AE:AF:9A:80:A1:67:D3:32:3E:73:8E:93:D7:BF:BA:89:AF:6C:28
sig_hashalgo: sha512
If those lines are absent then the module is not (yet) signed.
The rest of this article, in this section, is dedicated to answering some frequently asked questions about secure boot on MassOS, and explain the rationales behind the decisions taken by the MassOS developers in the MassOS implementation of secure boot support.
Shim is a "preloader" application that allows EFI binaries to run even when they are signed by keys not imported into the UEFI firmware database itself. Instead, secure boot certificates can be imported into Shim's own internal database of trusted keys (known as Machine Owner Keys, or MokList). This works because the build of Shim itself should be signed by Microsoft - whose keys are trusted by almost all UEFI firmwares by default - and then Shim has control over second-stage verification itself. As the two methods shown above demonstrate, importing a certificate into MokList for Shim is much easier than importing a certificate into the UEFI firmware directly (which, on some firmwares, may not even be possible at all). Therefore, the MassOS developers now prefer this by default. Historically, this wasn't a feature-complete solution, because the GRUB bootloader (used as the main bootloader in MassOS) would only support using Shim for validation of booting Linux kernels, despite the fact that it supports chainloading other EFI executables. Therefore, GRUB would have to fall back to the UEFI firmware trust database for validation of chainloaded executables, and wouldn't support keys in the MokList. However, recent updates to GRUB, which are present in the latest versions MassOS, have now added support for using Shim verification on chainloaded EFI binaries too, by use of the "shim_loader" protocol. This enables Shim to be used universally.
However, use of Shim has some considerations. The main one being Shim's requirements for validation of MOK-signed EFI binaries. Shim requires all such binaries to have valid SBAT (Secure Boot Advanced Targetting) metadata. This metadata must be embedded in the EFI binary itself and cannot be validated from an external file. The goal of SBAT is to provide more controllable revocations for older versions of bootloaders and EFI applications which have security vulnerabilities. Without this mechanism, the only way to block vulnerable applications would be through the UEFI firmware's internal revocation list - known as the dbx - which only contains a list of hashes of particular revoked binaries. When MOKs exist, and users can sign and load anything they want, the dbx itself is therefore insufficient for this purpose. A full description of the SBAT system can be found in its official documentation, and the current SBAT revocations can be found here. If you wish to not rely on SBAT data, then you will have to instead load the EFI binary directly from the firmware, instead of through Shim, and this requires the secure boot certificate to be imported into the firmware directly, instead of the MokList, which is demonstrated above in the Alternative method for importing the certificate section. However, as mentioned in that section, this should be unnecessary in most cases, so only use the alternative import method if you know you need it.
The Shim situation is further discussed in the section below, titled Are there legal implications?.
All possible legal implications of MassOS's implementation of secure boot have been carefully considered and evaluated. Where necessary, we have taken steps to ensure no free software licenses, including the strict GPL version 3, have been or will be violated. This section also covers some of the ethical concerns users may have of how the whole situation regarding Shim and secure boot works in MassOS.
Microsoft themselves will refuse to sign any bootloader or application that is licensed under the GPL version 3. This is for borderline arbitrary reasons, and is widely regarded to be a misunderstanding on their part, and/or intentional gaslighting of users, about what version 3 of the GPL actually requires. Contrary to Microsoft's belief, and what Microsoft wants users to believe, signing a GPL3-licensed application would NOT require Microsoft to reveal their private signing keys. However, due to this situation (which, again, is a misunderstanding and misinterpretation of what the GPL3 actually requires), Microsoft will refuse to sign the GRUB 2 bootloader (the default bootloader used by many distributions including MassOS), as it is GPL3-licensed. Just so conveniently, however, Shim (which is primarily developed by RedHat) uses a permissive BSD license, which Microsoft will sign, but at the cost that this does not protect the freedom of users as much as GPL3 (or even GPL2) would - and let's not forget all it really does is chainload a GPL3 signed GRUB anyway.
Nonetheless, MassOS uses a prebuilt Microsoft-signed Shim binary which comes from Ubuntu - and therefore does not trust MassOS's keys out of the box in the same way it trusts Canonical's keys for Ubuntu - and therefore, users of MassOS have to go through the fairly straightforward process (described above) of enrolling the MassOS certificate into MokList, for Shim to trust it. Given that the shim review board actively recommends use of shim from an existing distro, instead of going through the process of getting your own Shim build signed, clearly this is not legally questionable. And if you consider it to be ethically questionable (with regards to free software), then hopefully by reading this you already have an idea of WHO you should be directing your criticism towards (and spoiler - it's not us - we'd love a world without mega corporations gatekeeping the principle of "security"). As described in our MassOS and Free Software article, we aim to provide the best experience for our users to be able to use MassOS - and in this case, it involves providing a way for our users to be able to use MassOS without needing to disable secure boot and without needing to go through dozens of hurdles to be able to use MassOS with secure boot.
With the Shim situation aside, we can now discuss MassOS builds themselves, which are signed by the secure boot key of whoever built them. Official MassOS builds produced by the developers of MassOS are signed by the official MassOS key. This key is kept private for obvious reasons, and is not made available for custom builders. However, the MassOS source repository contains a script (generate-sb-keys.sh), which will generate a secure boot key set for any custom builder who doesn't already have one. The secure boot key files will then be placed in a location that the MassOS build system uses to know which keys to use to sign the binaries in the build with. This means that the only difference between official MassOS builds and "unofficial" user-created ones, will be a different signing key. But, as described above, the process for importing the certificate into the is exactly the same, regardless of whether it's the official MassOS key, or the key of the person who made the custom build. Custom builds are in no way inferior to official ones in this regard - there are no functional limitations imposed by a build being signed by a third party builder's key instead of the MassOS developers' official key. The mechanism above all else serves a way to guarantee authorship - you can look at the certificate of the key that signed the build, and then know who the build was produced by.