Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
secureboot [2023/10/25 22:58] – removed - external edit (Unknown date) 127.0.0.1secureboot [2023/11/12 04:39] (current) – [TPM] formatting + grammar atari
Line 1: Line 1:
 +====== Secure Boot ======
 +
 +For Batocera **v39** and higher on x86_64 systems, streamlined support for Secure Boot is present. This makes it easier to boot Batocera on PCs which have poor secure boot key management in the native UEFI BIOS. The process detailed below will install Batocera's security certificate into the machine's "Machine Owner Keys" (MOK) into the PC's UEFI variable store. This will allow the machine to execute Batocera's bootloader, which has been digitally signed with Batocera's certificate, even when Secure Boot is enabled in the BIOS.
 +
 +<WRAP center round alert>
 +Modifying Secure Boot and related settings may trip a "tamper switch" (Platform Configuration Register, PCR) in the system's Trusted Platform Module (TPM).  Once the switch has been tripped, it cannot be reset without providing a recovery key. If BitLocker Disk Encryption is enabled, Windows will detect the tampering and will ask for the BitLocker recovery key before allowing Windows to boot.
 +
 +If the system is managed by someone else (such as your employer), recovery may require assistance from an authorized system administrator. Act responsibly, and only install Batocera on systems you own and manage.
 +</WRAP>
 +
 +Before proceeding, make a copy of the required BitLocker recovery keys. Documentation on locating the keys can be found at https://support.microsoft.com/en-us/windows/where-to-look-for-your-bitlocker-recovery-key-fd2b3501-a4b9-61e9-f5e6-2a545ad77b3e
 +
 +Technical references:
 +
 +https://learn.microsoft.com/en-us/windows/security/hardware-security/tpm/switch-pcr-banks-on-tpm-2-0-devices
 +
 +https://www.dell.com/support/kbdoc/en-us/000124361/bitlocker-is-prompting-for-a-recovery-key-and-you-cannot-locate-the-key
 +
 +<WRAP center round info>
 +For Batocera **v38** and lower, the keys must be enrolled by the BIOS itself (if available, otherwise [[:troubleshooting#boot_issues|just use legacy/CSM boot]]). This usually can be done from the security options of the BIOS. Search for an option which allows you to "Add keys", "Generate keys from EFI file" or "Enroll Efi image". The file to be selected, if asked, is ''EFI/boot/bootx64.efi''.\\ {{:bios_security_efi_keys_options.jpeg?400|Photo of a motherboard BIOS showing security options, "Enroll Efi Image" is visible.}}
 +
 +This method can be used instead of using the MOK management tool as explained below. Batocera **v38** and lower does not have the MOK management tool installed.
 +</WRAP>
 +
 +====== Prerequisites ======
 +
 +  * The system must be an Intel/AMD system that supports booting in 64-bit UEFI mode, with the standard Microsoft signing key certificates.
 +  * Secure Boot must be enabled during the setup process. If offered the option to select the mode of Secure Boot to use, the "Standard" mode is recommended. Other modes are untested.
 +  * The UEFI BIOS firmware must support booting from the desired installation media type, and it must be possible to select which drive to boot while using UEFI.
 +  * A keyboard is required to navigate the MOK management procedure detailed below.
 +
 +As some of this configuration is vendor-specific, consult the manual for the machine before getting started.
 +
 +====== Preparation ======
 +
 +[[:install_batocera|Flash Batocera]] on a drive, or upgrade an existing installation to **v38** or higher. Attach the drive to your computer.
 +
 +====== Configuration Steps ======
 +
 +Power on the computer and enter its BIOS setup or boot manager. Set the UEFI boot to the drive Batocera is installed on. The details of how to do this vary by manufacturer.  On some systems there is a "boot manager" accessible by a keystroke at boot; on others the "boot order" bust be configured with the Batocera drive set first. Tom's Hardware has a good guide on [[https://www.tomshardware.com/reviews/bios-keys-to-access-your-firmware,5732.html|How to Enter the BIOS on Any PC]]. For my demonstration run on my Dell laptop, I pressed ''[F12]'' at startup to enter the boot menu, used the arrow keys to navigate to the USB media, and hit ''[ENTER]'' to boot.
 +
 +{{:secure_boot_x64_-_1_-_select_thumb_drive_efi_to_boot.png?direct&600|}}
 +
 +A blue screen will appear with a message **Error Verification Failed (0x1A) Security Violation**.  Hit ''[ENTER]'' on the keyboard to continue.
 +
 +{{:secure_boot_x64_-_2_-_error_verification_failed_0x1a_security_violation_-_screenshot_2023-10-20_121355.png?direct&720|}}
 +
 +On the **Shim UEFI key management** screen, hit any key before the ten-second timer expires.
 +
 +{{:secure_boot_x64_-_3_-_shim_uefi_key_management_-_press_any_key_to_perform_mok_management_-_screenshot_2023-10-20_121617.png?direct&720|}}
 +
 +On the **Perform MOK management** screen, use the arrow keys to navigate to **Enroll key from disk**, and hit ''[ENTER]''.
 +
 +{{:secure_boot_x64_-_4_-_perform_mok_management_-_enroll_key_from_disk_-_screenshot_2023-10-20_121730.png?direct&720|}}
 +
 +On the **Select Key** screen, navigate to the **BATOCERA** partition and hit ''[ENTER]''.
 +
 +{{:secure_boot_x64_-_5_-_select_key_-_batocera_-_screenshot_2023-10-20_122153.png?direct&720|}}
 +
 +On the second **Select Key** screen, navigate to the **ENROLL_THIS_KEY_IN_MOKMANAGER_batocera.cer** certificate file, and hit ''[ENTER]''.
 +
 +{{:secure_boot_x64_-_6_-_select_key_-_enroll_this_key_in_mokmanager_batocera.cer_-_screenshot_2023-10-20_122352.png?direct&720|}}
 +
 +On the **Enroll MOK** screen, navigate to the **Continue** menu item, and hit ''[ENTER]''.
 +
 +{{:secure_boot_x64_-_7_-_enroll_mok_-_continue_-_screenshot_2023-10-20_122618.png?direct&720|}}
 +
 +On the **Enroll the key(s)?** screen, navigate to the **Yes** menu item, and hit ''[ENTER]''.
 +
 +{{:secure_boot_x64_-_8_-_enroll_the_key_s_-_yes_-_screenshot_2023-10-20_122730.png?direct&720|}}
 +
 +On the second **Perform MOK management** screen, hit ''[ENTER]'' to reboot the system.
 +
 +{{:secure_boot_x64_-_9_-_perform_mok_management_-_reboot_-_screenshot_2023-10-20_122839.png?direct&720|}}
 +
 +The system will reboot.  If the system's TPM is enabled, proceed to the next section, otherwise it should automatically launch Batocera with Secure Boot enabled.
 +
 +If other operating system disks are attached to the system, they can be selected for boot from your firmware's boot menu.  The ''efibootmgr'' command-line utility in Batocera can also be used to adjust boot order, or to perform a one-time "boot-next" to another UEFI OS. (FIXME this commentary needs to move elsewhere)
 +
 +====== TPM ======
 +
 +Batocera's Secure Boot support requires some interaction between the bootloader and the system's hardware Trusted Platform Module (TPM), //even on systems where Secure Boot is not enabled//.
 +
 +If the system's TPM is enabled, the first time you boot into the newer Batocera versions, and after completing the Secure Boot MOK management setup (if Secure Boot is enabled), a **Boot Option Restoration** screen with a countdown will be displayed. If no action is taken, the system will reboot repeatedly into this screen.
 +
 +{{ :tpm_1_boot_option_restoration.jpg?direct&600 |}}
 +
 +Using a keyboard, press any key to move on to the next screen.
 +
 +On the **Boot Options Restored** screen, use the arrow keys to select **Always continue boot** and press ''[Enter]''. The system will then boot into Batocera.
 +
 +{{ :tpm_2_boot_option_restored.jpg?direct&600 |}}
 +
 +It will be necessary to perform this setup only once, as long as the correct option is selected.
 +
 +====== Upgrading and Downgrading with Secure Boot ======
 +
 +It is safe to upgrade to later Batocera versions while Secure Boot is enabled. Downgrading to **v39** or higher is also safe. If the newly upgraded/downgraded version was signed with a different signing key certificate which is not already enrolled, the MOK enrollment process may be reappear. It is possible to avoid this by disabling Secure Boot validation in the shim.
 +
 +If Batocera is downgraded to **v38** or lower, the system may fail to boot in Secure Boot mode from the bootloaders installed by those versions. On systems where Secure Boot can be disabled, disabling it should allow the system to boot again. It is recommended to disable Secure Boot //before// such a downgrade.
 +
 +<WRAP center round info 100%>
 +After the downgrade, the Secure Boot capable bootloader referenced in the ''Batocera'' EFI bootloader entry may allow the earlier versions to boot with Secure Boot enabled.  Whether this works or not will depend on the system's specific UEFI BIOS behaviors.
 +</WRAP>
 +
 +
 +===== Disabling Secure Boot validation in the shim =====
 +
 +Once Secure Boot is set up and working, it is possible to leave Secure Boot enabled in the system, while disabling Secure Boot verification in the shim.  This is optional, and is riskier than the normal setup allowing only signed bootloader components to run.
 +
 +To disable Secure Boot verification, [[:access_the_batocera_via_ssh|SSH into Batocera]] and run the following:
 +
 +<code>
 +mokutil --disable-validation
 +</code>
 +
 +To re-enable Secure Boot verification:
 +
 +<code>
 +mokutil --enable-validation
 +</code>
 +
 +The ''mokutil'' command will request a (one-time) password. It is strongly recommended that you use the password ''12345678'' as the password for the validation state change, reasons for which will be explained below.
 +
 +Reboot the system, and the MOK Manager will ask to allow changing the verification state. It will then request a few random characters of the password by specifying the position number of the desired character. For example, if it asks for character #2, type ''2'' and press ''[ENTER]''. Repeat the process until the MOK manager is satisfied, then select the reboot option to restart the system with the new validation state.