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.

Although MassOS supports secure boot, the nature of how secure boot is designed makes it an imperfect solution which is not at all seamless. Here are a few limitations and/or considerations of using secure boot with MassOS:

• MassOS can only be signed using custom keys that are not included in UEFI firmwares by default, and therefore need to be manually imported by the user (it is not possible or feasible for MassOS to support being signed by Microsoft's official keys).
• Only the kernel, kernel modules, and bootloader(s) that are included as part of the MassOS system will be signed. Anything else will not be, and therefore may be unusable (unless signed with a separate key created by the user of the system which they ALSO import into their firmware - since signing with the same keys as used for the MassOS build is not possible for security reasons, unless the builder and end-user are the same person). This includes custom kernels and even custom out-of-tree kernel modules (such as the ones required by VMware and VirtualBox, as well as other software - or simply custom drivers which you build and install onto your system using the Dynamic Kernel Module System (DKMS)).
• The GRUB bootloader cannot use any custom themes when secure boot is enabled. This is because the secure boot policy only permits GRUB to load fonts and other resources which are built-in to its own binary - it cannot load any such assets from real disks. Therefore, you must have secure boot disabled if you want to use a custom theme (including the distro-massos theme that is included by default on a MassOS system).

With this in mind, you may ask "Why does MassOS support secure boot in the first place?". And the answer to that is to provide a workaround for people who can't or don't want to disable secure boot. The section below, entitled Why might you not be able to disable secure boot?, contains several reasons why you may not be able to disable secure boot. But by all means disable it if these don't apply to you - as this will make your experience with MassOS less complicated and more seamless.

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?
• 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.

1. 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.

2. Find the secure boot option, which may be under the Security tab or the Boot tab.

3. Set the secure boot option to DISABLED.

4. 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). Please be aware that this guide only demonstrates how to import the MassOS certificate into an existing secure boot environment as an authorized signature. This is sufficient for booting MassOS and its signed binaries on a secure boot enabled system, but it does not "take control" of the entire secure boot environment (which may still be managed by Microsoft or the device's OEM), like some other guides on the internet suggest. If you want to go down this route, take a look at DanielMYT's secureboot-scripts repository, which both documents the process, and provides scripts to assist with doing so.

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: It appears that 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.

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 F7 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: The key with the name Official MassOS Secure Boot Key (Daniel Massey) was an official key used to sign early testing builds, but it is no longer used. We recommend removing it if you previously added it.

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.

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 companion bootloader (or "preloader") that allows self-signed EFI binaries to run using user-managed Machine Owner Keys (MOKs), without needing to import secure boot signing keys directly into the firmware (they will instead be stored in Shim's local database). This clearly makes it a more appealing option for end-users, as users can import certificates into the shim database using the MokManager utility, instead of needing to dig into the UEFI firmware. Unfortunately, shim itself needs to be signed too, and that would need a key trusted by the UEFI firmware settings to import a certificate.

Under normal circumstances, you would expect it to be possible to bypass shim entirely, and just run the bootloader (e.g., GRUB) directly, as it is signed and the keys it is signed by is imported into the firmware directly. However, GRUB's internal verification logic relies on shim, and GRUB will refuse to load anything on a secure boot system if shim is not present - therefore, it must be used.

The "conventional" way to use shim, and indeed the method employed by Ubuntu, Fedora, and some other commercially-backed distributions, is to have shim itself signed by Microsoft's keys - allowing it to load on any secure-boot-enabled system. This allows everything else to be signed exclusively using MOK keys imported into shim's internal database (or a vendored key that shim was compiled to trust out of the box). Unfortunately, the process of getting signed by Microsoft is not straightforward, especially for small independent distributions like MassOS. Furthermore, it raises some ethical questions with regards to free software - as Microsoft imposes restrictions on anything they sign (legally preventing a distro like MassOS from just yoinking the signed shim from Ubuntu or Fedora, for example). For this reason, the MassOS developers have made the decision to have shim compiled as part of the MassOS build system, and signed only by the MassOS secure boot key (or whichever key the MassOS build as a whole is signed by). However, this shim (compiled by MassOS) IS configured to trust the same signing key out of the box - meaning that there will be no need to also import the MassOS key into MokManager - you can just import the key into your firmware directly, using the process described above, and you'll be good to go. You can pretend shim doesn't exist!

shim is also less straightforward to use than directly booting a signed binary trusted by certificates in the firmware, as it mandates the use of SBAT data which must be embedded into the signed binary (cannot be in a separate file). Unfortunately, the SBAT data system can be complicated to understand. So avoid it (and shim) if at all possible! However, you can note that GRUB ONLY uses shim for loading Linux kernels (from Linux boot entries). Any EFI executables chainloaded from GRUB using the chainloader command, such as Windows Boot Manager, and any other EFI executable, will use the standard inbuilt verification process of the firmware, not shim.

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.

Most of the concern comes from the idea of having Microsoft sign a free software bootloader such as shim. Anything signed by Microsoft has restrictions placed upon how it can be used and redistributed, so as to maintain the integrity of Microsoft's signing keys, and the secure boot trust chain as a whole. These restrictions would include, for example, forbidding another distribution, like MassOS, from yoinking the signed shim binaries from Ubuntu, and distributing them in official MassOS builds. But, as described above, MassOS has not done this. MassOS signs everything with its own keys. And there are no restrictions on distributing binaries signed by us (or custom builders who have used their own keys for their unofficial MassOS builds).

As for people who want to build MassOS themselves, the process is just as easy. Although they, for obvious reasons, cannot use the MassOS signing keys (as these are kept private), the MassOS source repository contains a script (generate-sb-keys.sh), which automatically generates a secure-boot key (and its certificate files) for you. The secure boot key/cert 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, and therefore, the MassOS system is not artifically restricted in a way that the license of the GPL version 3 would forbid.