UEFI Secure Boot

2026-03-30T19:23:06Z

Coolreader18: Add note on osslsigncode

This page documents the procedure to enable [[UEFI]] Secure Boot after Alpine Linux is installed. To install Alpine Linux, secure boot needs to be disabled in [[UEFI]] firmware.

== Mounting ESP ==

Prepare mount point for UEFI partition (ESP) at {{path|/boot/efi}}: {{cmd|# install -d -m 000 /boot/efi}}

Add the following line to {{path|/etc/fstab}} as follows: {{Cat|/etc/fstab|...
UUID{{=}}<first-partition-uuid> /boot/efi vfat rw,noatime,fmask{{=}}0022,dmask{{=}}0022,codepage{{=}}437,iocharset{{=}}ascii,shortname{{=}}mixed,utf8,errors{{=}}remount-ro 0 2}}

Mount it: {{cmd|# mount /boot/efi}}

== Generating own UEFI keys ==

Install package {{pkg|efi-mkkeys}}: {{cmd|# apk add efi-mkkeys}}

Before creating new keys and modifying EFI variables, it is advisable to backup the current variables, so that they may be restored in case of error:

{{cmd|# mkdir -p /etc/uefi-keys/vendor
# cd /etc/uefi-keys/vendor
# for i in PK KEK db dbx; do efi-readvar -v $i -o $i.esl; done }}

Generate your self-signed PK, KEK and db key, including .esl and .auth files: {{cmd|# efi-mkkeys -s "Your Name" -o /etc/uefi-keys}}

Now you can uninstall {{pkg|efi-mkkeys}} if you want: {{cmd|# apk del efi-mkkeys}}

== Generating Unified Kernel Image ==

Install package {{pkg|secureboot-hook}}, {{pkg|systemd-efistub}} (Alpine v3.22+) or {{pkg|gummiboot-efistub}} (prior v3.22), and {{pkg|efibootmgr}}:

{{cmd|# apk add secureboot-hook systemd-efistub efibootmgr}}

{{Note|From Alpine Linux v3.22, {{pkg|gummiboot-efistub}} doesn’t work. {{pkg|systemd-efistub}} only provides EFI stub binaries, and it doesn’t depend on any systemd components.}}

Adjust parameter <code>cmdline</code> in {{path|/etc/kernel-hooks.d/secureboot.conf}}. It should '''not''' contain an <code>initrd=</code> parameter! Example of a valid <code>cmdline</code>:

<pre>cmdline="root=UUID=<uuid-of-your-root-fs> modules=ext4"</pre>

Run kernel hooks: {{cmd|# apk fix kernel-hooks}}

Disable {{pkg|mkinitfs}} trigger: {{cmd|# echo 'disable_trigger{{=}}yes' >> /etc/mkinitfs/mkinitfs.conf}}

Add boot entry: {{cmd|# efibootmgr --disk <dev> --part 1 --create --label 'Alpine Linux' --load /Alpine/linux-lts.efi --verbose}}

Note: This procedure only needs to be done once; after that the Unified Kernel Image will be generated automatically every time the kernel is upgraded.

== Enrolling UEFI keys ==

Copy all *.esl, *.auth files from {{path|/etc/uefi-keys}} to a FAT formatted file system (you can use EFI system partition).

Launch firmware setup utility and enrol db, KEK and PK certificates (in this order!). Firmwares have various different interfaces; the following steps for ThinkPad T14s are just an example.

# Reboot system and enter ThinkPad Setup (F1).
# Go to '''Security''' > '''Secure Boot'''
# Change '''Secure Boot''' to '''Enabled'''
# '''Reset to Setup Mode'''
# Go to '''Key Management'''
# '''Authorized Signature Database (DB)'''
#* '''Enroll DB''' > select your Flash Drive > select '''db.auth'''
#* '''Delete DB''' > delete Microsoft certificates (optional)
# '''Key Exchange Key (KEK)'''
#* '''Enroll KEK''' > select your Flash Drive > select '''KEK.auth'''
#* '''Delete KEK''' > delete Microsoft certificates (optional)
# '''Platform Key (PK)''' > '''Enroll PK''' > select your Flash Drive > select '''PK.auth''' (this MUST be the last!)
# Go to top, '''Restart''' > '''Exit Saving Changes'''

Some devices, such as HP Pavilion laptops, cannot enroll keys through the interface. Instead, you must follow the following steps (steps 1-5 and 9-12 may vary depending on the computer, they are for HP Pavilion laptops as an example):
# Reboot system and enter HP Bios Setup Utility (F10).
# Go to '''System Configuration'''
# Change '''Secure Boot''' to '''Disabled'''
# Select '''Clear All Secure Boot Keys'''
# Press F10 to save settings
# Reboot system and enter Alpine Linux
# Enable the [[Repositories|Community Repository]]
# Run the following commands:
{{cmd|# apk update
# apk add sbctl
# sbctl create-keys
# sbctl sign /boot/efi/Alpine/linux-lts.efi
# sbctl enroll-keys -m }}
# <li value="9"> Reboot system and enter HP Bios Setup Utility (F10).
# Go to '''System Configuration'''
# Change '''Secure Boot''' to '''Enabled'''
# Press F10 to save settings

Note: If you needed to use sbctl, you will have to run <code>sbctl sign /boot/efi/Alpine/linux-lts.efi</code> every time you upgrade the kernel. You should '''not''' need to disable secure boot, so long as you sign the new Unified Kernel Image before you reboot.

== Troubleshooting ==

In some cases on some older motherboards, the firmware will reject UEFI executables signed by sbsign. In that case, [https://github.com/mtrojnar/osslsigncode osslsigncode] may work instead.<sup>[https://superuser.com/a/1560609]</sup>

== See also ==

* [[Initramfs init]]
* <code>mkinitfs-bootparam(7)</code>

* [https://wiki.gentoo.org/wiki/User:Sakaki/Sakaki%27s_EFI_Install_Guide/Configuring_Secure_Boot Sakaki's EFI Install Guide/Configuring Secure Boot - Gentoo Wiki]
* [https://wiki.archlinux.org/title/Unified_Extensible_Firmware_Interface/Secure_Boot Unified Extensible Firmware Interface/Secure Boot - ArchWiki]
* [https://github.com/jirutka/efi-mkuki efi-mkuki: EFI Unified Kernel Image Maker] (used by the {{pkg|secureboot-hook}} package)

[[Category:Booting]] [[Category:UEFI]]

Alpine Linux - User contributions [en]

UEFI Secure Boot