https://wiki.archlinux.org/api.php?action=feedcontributions&user=Calcium&feedformat=atomArchWiki - User contributions [en]2024-03-29T09:20:41ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=WirePlumber&diff=747504WirePlumber2022-09-19T09:51:06Z<p>Calcium: Update wpctl keyboard volume control</p>
<hr />
<div>[[Category:Multimedia]]<br />
[[ja:WirePlumber]]<br />
[[ru:WirePlumber]]<br />
{{Related articles start}}<br />
{{Related|PipeWire}}<br />
{{Related articles end}}<br />
<br />
[https://pipewire.pages.freedesktop.org/wireplumber WirePlumber] is a powerful session and policy manager for [[PipeWire]]. Based on a modular design, with Lua plugins that implement the actual management functionality, it is highly configurable and extendable.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|wireplumber}} package. It will conflict with other PipeWire Session Managers and make sure they are uninstalled.<br />
<br />
WirePlumber uses [[systemd/User]] for management of the server.<br />
<br />
Optionally, install {{Pkg|wireplumber-docs}} to review the documentation.<br />
<br />
== Configuration ==<br />
<br />
=== Configuration file layout ===<br />
<br />
[https://pipewire.pages.freedesktop.org/wireplumber/configuration.html WirePlumber's configuration] is comprised of global PipeWire-flavored JSON objects such as {{ic|context}} and {{ic|alsa_monitor}} that are modified to change its behavior. The configuration files are read from {{ic|~/.config/wireplumber/}} (user configuration), {{ic|/etc/wireplumber/}} (global configuration), and then {{ic|/usr/share/wireplumber/}} (stock configuration).<br />
<br />
WirePlumber starts by reading the [https://pipewire.pages.freedesktop.org/wireplumber/configuration/main.html main configuration file]. This is a JSON-like file that sets up the PipeWire context, [https://docs.pipewire.org/page_spa_plugins.html SPA plugins], modules, and components. Among these components is the [[Wikipedia:Lua (programming language)|Lua]] scripting engine, which is used to dynamically modify the global objects.<br />
<br />
There are different main configuration files that ship with the package:<br />
<br />
* The single-instance configuration file, at {{ic|/usr/share/wireplumber/wireplumber.conf}}. This is the default configuration, which includes the functionality of all the other configurations within one process.<br />
** See the [https://pipewire.pages.freedesktop.org/wireplumber/configuration/main.html documentation for the "context" object] used in all of the main configuration files.<br />
* The main configuration file, at {{ic|/usr/share/wireplumber/main.conf}}. This loads the modules and components necessary for the WirePlumber core, and loads [https://pipewire.pages.freedesktop.org/wireplumber/configuration/config_lua.html Lua configuration files] from {{ic|''config-dir''/main.lua.d/}}. [https://pipewire.pages.freedesktop.org/wireplumber/configuration/config_lua.html]<br />
** See the documentation for the [https://pipewire.pages.freedesktop.org/wireplumber/configuration/alsa.html ALSA objects] and [https://pipewire.pages.freedesktop.org/wireplumber/configuration/access.html "access" objects].<br />
* The [[Bluetooth]] configuration file, at {{ic|/usr/share/wireplumber/bluetooth.conf}}. This is suitable for a WirePlumber process that is handling Bluetooth connectivity for the core process. This loads Lua files from {{ic|''config-dir''/bluetooth.lua.d/}}.<br />
** See the [https://pipewire.pages.freedesktop.org/wireplumber/configuration/bluetooth.html documentation for the Bluetooth object].<br />
* The ''policy'' configuration file, at {{ic|/usr/share/wireplumber/policy.conf}}. This encapsulates policy functionality, which is how WirePlumber makes decisions about moving and making changes to nodes. This loads Lua files from {{ic|''config-dir''/policy.lua.d/}}<br />
** See the [https://pipewire.pages.freedesktop.org/wireplumber/configuration/policy.html documentation for the policy-related objects].<br />
<br />
The Lua configuration files in the {{ic|lua.d}} directories also load Lua scripts from {{ic|''config_dir''/scripts/}}. These scripts implement some of the logic/functionality of Pipewire, and could also be worth modifying under certain circumstances.<br />
<br />
=== Modifying the configuration ===<br />
<br />
The recommended way to configure WirePlumber is to add a Lua script to the appropriate {{ic|lua.d}} directory within {{ic|/etc/wireplumber}} or {{ic|~/.config/wireplumber}}. Some things to consider are:<br />
<br />
* If there is an existing script you want to override, copy it from {{ic|/usr/share/wireplumber}} to the destination while keeping its name the same. Configuration files with the same name but in a lower priority location will be ignored. [https://pipewire.pages.freedesktop.org/wireplumber/configuration/locations.html#location-of-configuration-files]<br />
* Otherwise, if you are adding a new script, you should start it with a number bigger than 50 (e.g. {{ic|51-my-config.lua}}), as the default configuration is mostly done at or below 50 in the alphanumeric ordering.<br />
** Note that WirePlumber performs [https://pipewire.pages.freedesktop.org/wireplumber/configuration/config_lua.html#multi-path-merging multi-path merging], meaning that a lower numbered stock config will run before your new script, as alphanumeric ordering takes precedence over directory priorities.<br />
* The directory you choose should be consistent with what the stock configuration does, but it doesn't strictly matter unless you are [https://pipewire.pages.freedesktop.org/wireplumber/configuration/multi_instance.html using multiple instances].<br />
* ALSA properties for Bluetooth devices ''must'' be configured in {{ic|bluetooth.lua.d/}}. An ALSA property for a Bluetooth device set in {{ic|main.lua.d/}} is ''not'' applied.<br />
<br />
=== Obtain interface name for rules matching ===<br />
<br />
In the Lua scripts, you need to specify {{ic|matches}} rules with a property from [https://docs.pipewire.org/page_objects_design.html PipeWire objects] of the target interface you want to configure.<br />
<br />
Use the command {{ic|wpctl status}} to show all objects managed by WirePlumber. Find the {{ic|''ID''}} of you desired interface.<br />
<br />
Consider following example output:<br />
{{hc|$ wpctl status|output=<br />
PipeWire 'pipewire-0' [0.3.56, user@hostname, cookie:1163266174]<br />
└─ Clients:<br />
32. pipewire-pulse [0.3.56, user@hostname, pid:895]<br />
33. WirePlumber [0.3.56, user@hostname, pid:894]<br />
...<br />
Audio<br />
├─ Devices:<br />
│ 42. HD Audio Controller [alsa]<br />
│ 105. USB PnP Audio Device [alsa]<br />
│ <br />
├─ Sinks:<br />
│ * '''48'''. HD Audio Controller Analog Stereo [vol: 0.50]<br />
│ 53. EasyEffects Sink [vol: 1.00]<br />
│ <br />
├─ ...<br />
│ <br />
├─ Sources:<br />
│ 54. EasyEffects Source [vol: 1.00]<br />
│ * 101. USB PnP Audio Device Mono [vol: 0.74]<br />
│ <br />
└─ ...<br />
<br />
Video<br />
└─ ...<br />
<br />
Settings<br />
└─ Default Configured Node Names:<br />
0. Audio/Sink alsa_output.pci-0000_08_00.4.analog-stereo<br />
1. Audio/Source alsa_input.usb-0c76_USB_PnP_Audio_Device-00.mono-fallback}}<br />
<br />
the {{ic|''ID''}} of desired interface: {{ic|HD Audio Controller Analog Stereo}} is {{ic|48}}.<br />
<br />
Then use command {{ic|wpctl inspect ''ID''}} to view object detail, listed all properties in that object:<br />
<br />
{{hc|$ wpctl inspect 48|output=<br />
id 48, type PipeWire:Interface:Node<br />
...<br />
* client.id = "34"<br />
device.api = "alsa"<br />
device.class = "sound"<br />
* device.id = "42"<br />
device.profile.description = "Analog Stereo"<br />
device.profile.name = "analog-stereo"<br />
* factory.id = "18"<br />
factory.mode = "merge"<br />
factory.name = "api.alsa.pcm.sink"<br />
library.name = "audioconvert/libspa-audioconvert"<br />
* media.class = "Audio/Sink"<br />
* node.description = "HD Audio Controller Analog Stereo"<br />
...<br />
* node.name = "alsa_output.pci-0000_08_00.4.analog-stereo"<br />
* node.nick = "ALC1220 Analog"<br />
...<br />
* object.path = "alsa:pcm:1:front:1:playback"<br />
* object.serial = "49"<br />
...<br />
}}<br />
<br />
Choose {{ic|device.name}} or {{ic|node.name}} or {{ic|node.nick}} property, to use with the {{ic|matches}} rules in the Lua configuration script.<br />
<br />
Avoid using {{ic|device.id}}, it is dynamic and changes often.<br />
<br />
{{Note|<br />
* {{ic|wpctl inspect}} outputs the object type on the first line, i.e. {{ic|type PipeWire:Interface:Node}} means that the object type is {{ic|Node}}.<br />
* {{ic|Node}} objects are sinks or sources in the PipeWire graph, and {{ic|Device}} objects correspond to the ALSA card.<br />
* You can determine the {{ic|Endpoint}} class of this object from the {{ic|media.class}} property.<br />
* Since WirePlumber v0.4.9, ALSA nodes use the PCM name to populate {{ic|node.nick}}, which is useful at least on HDA cards using UCM, where all outputs (analog, HDMI, etc.) are exposed as {{ic|Node}} on a single profile.<br />
}}<br />
<br />
{{Tip|<br />
* The command {{ic|pw-top}} shows the PipeWire {{ic|Device}} and {{ic|Node}} currently in use.<br />
* Results from {{ic|wpctl inspect ''ID''}} are the same as the properties field from the {{ic|pw-cli dump ''ID''}} command.<br />
}}<br />
<br />
=== Changing a device/node property ===<br />
<br />
To change a device or node property, such as its description or nick, you must create a Lua script and add it into {{ic|/etc/wireplumber/}} or {{ic|~/.config/wireplumber}} under the proper path and name.<br />
<br />
For instance, to change the description of an ALSA node, you would create a file such as:<br />
{{hc|head=/etc/wireplumber/main.lua.d/51-device-rename.lua (or ~/.config/wireplumber/main.lua.d/51-device-rename.lua)|output=rule = {<br />
matches = {<br />
{<br />
{ "node.name", "equals", "alsa_output.pci-0000_00_1f.3.output_analog-stereo" },<br />
},<br />
},<br />
apply_properties = {<br />
["node.description"] = "Laptop",<br />
},<br />
}<br />
<br />
table.insert(alsa_monitor.rules, rule)}}<br />
<br />
If instead you wish to change something on a Bluetooth node or device, you could create a file such as:<br />
{{hc|head=/etc/wireplumber/bluetooth.lua.d/51-device-rename.lua (or ~/.config/wireplumber/bluetooth.lua.d/51-device-rename.lua)|output=rule = {<br />
matches = {<br />
{<br />
{ "node.name", "equals", "bluez_output.02_11_45_A0_B3_27.a2dp-sink" },<br />
},<br />
},<br />
apply_properties = {<br />
["node.nick"] = "Headphones",<br />
},<br />
}<br />
<br />
table.insert(bluez_monitor.rules, rule)}}<br />
<br />
The properties that you can change as well as the matching rules to select devices or nodes are documented at [https://pipewire.pages.freedesktop.org/wireplumber/configuration/alsa.html ALSA configuration] and [https://pipewire.pages.freedesktop.org/wireplumber/configuration/bluetooth.html Bluetooth configuration].<br />
<br />
=== Disable a device/node ===<br />
<br />
Since WirePlumber v0.4.7, users could now disable any devices or nodes by property {{ic|device.disabled}} or {{ic|node.disabled}}<br />
<br />
{{hc|head=/etc/wireplumber/main.lua.d/51-alsa-disable.lua (or ~/.config/wireplumber/main.lua.d/51-alsa-disable.lua)|output=rule = {<br />
matches = {<br />
{<br />
{ "device.name", "equals", "alsa_card.pci-0000_08_00.4" },<br />
},<br />
},<br />
apply_properties = {<br />
["device.disabled"] = true,<br />
},<br />
}<br />
<br />
table.insert(alsa_monitor.rules,rule)}}<br />
<br />
For the name of {{ic|alsa_card.*}} in your system, see [[#Obtain interface name for rules matching]]<br />
<br />
{{Note|Common use-case, for example, is to disable NVIDIA's HDMI audio output.}}<br />
<br />
=== Simultaneous output to multiple sinks on the same sound card ===<br />
<br />
Create a copy of {{ic|/usr/share/alsa-card-profile/mixer/profile-sets/default.conf}} so that changes persist across updates. Here we define a profile joining the two default mappings for Analog and HDMI.<br />
<br />
{{hc|/usr/share/alsa-card-profile/mixer/profile-sets/multiple.conf|2=<br />
[General]<br />
auto-profiles = no<br />
<br />
[Mapping analog-stereo]<br />
device-strings = front:%f<br />
channel-map = left,right<br />
paths-output = analog-output analog-output-lineout analog-output-speaker analog-output-headphones analog-output-headphones-2<br />
paths-input = analog-input-front-mic analog-input-rear-mic analog-input-internal-mic analog-input-dock-mic analog-input analog-input-mic analog-input-linein analog-input-aux analog-input-video analog-input-tvtuner analog-input-fm analog-input-mic-line analog-input-headphone-mic analog-input-headset-mic<br />
priority = 15<br />
<br />
[Mapping hdmi-stereo]<br />
description = Digital Stereo (HDMI)<br />
device-strings = hdmi:%f<br />
paths-output = hdmi-output-0<br />
channel-map = left,right<br />
priority = 9<br />
direction = output<br />
<br />
[Profile multiple]<br />
description = Analog Stereo Duplex + Digital Stereo (HDMI) Output<br />
output-mappings = analog-stereo hdmi-stereo<br />
input-mappings = analog-stereo<br />
}}<br />
<br />
Now we configure Wireplumber to use the new card-profile for matching devices. For identifying information see [[#Obtain interface name for rules matching]]. We apply the configuration systemwide by creating a Lua script such as the following:<br />
<br />
{{hc|/etc/wireplumber/main.lua.d/51-alsa-custom.lua (or ~/.config/wireplumber/main.lua.d/51-alsa-custom.lua)|2=<br />
rule = {<br />
matches = {<br />
{<br />
{ "device.nick", "matches", "HDA Intel PCH" },<br />
},<br />
},<br />
apply_properties = {<br />
["api.alsa.use-acp"] = true,<br />
["api.acp.auto-profile"] = false,<br />
["api.acp.auto-port"] = false,<br />
["device.profile-set"] = "multiple.conf",<br />
["device.profile"] = "multiple",<br />
},<br />
}<br />
table.insert(alsa_monitor.rules,rule)<br />
}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Keyboard volume control ===<br />
<br />
See [[Keyboard shortcuts#Xorg]] to bind the following commands to your volume keys: {{ic|XF86AudioRaiseVolume}}, {{ic|XF86AudioLowerVolume}}, {{ic|XF86AudioMute}} and {{ic|XF86AudioMicMute}}.<br />
<br />
To raise the volume:<br />
<br />
$ wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+<br />
<br />
To lower the volume:<br />
<br />
$ wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-<br />
<br />
To mute/unmute the volume:<br />
<br />
$ wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle<br />
<br />
To mute/unmute the microphone:<br />
<br />
$ wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle<br />
<br />
{{Tip|To use sinks or sources other than the default ones, run {{ic|wpctl status}} to list all available sinks, and use sink or source numbers in place of {{ic|@DEFAULT_AUDIO_SINK@}} or {{ic|_SOURCE@}}.}}<br />
<br />
=== Show volume level ===<br />
<br />
To get the volume level and mute status of the default sink:<br />
<br />
$ wpctl get-volume @DEFAULT_AUDIO_SINK@<br />
<br />
{{Note|This only shows the mute status when the sink is muted.}}<br />
<br />
== See also ==<br />
<br />
* [https://pipewire.pages.freedesktop.org/wireplumber/ Documentation] — Official documentation<br />
* [https://www.collabora.com/news-and-blog/blog/2020/05/07/wireplumber-the-pipewire-session-manager/ WirePlumber, the PipeWire session manager] — Blog post by George Kiagiadakis (Collabora) from May 2020, detailing how WirePlumber works</div>Calciumhttps://wiki.archlinux.org/index.php?title=Unified_Extensible_Firmware_Interface/Secure_Boot&diff=740589Unified Extensible Firmware Interface/Secure Boot2022-08-08T07:54:46Z<p>Calcium: sbctl: Add details about signing files</p>
<hr />
<div>[[Category:Boot process]]<br />
[[ja:セキュアブート]]<br />
[[zh-hans:Unified Extensible Firmware Interface (简体中文)/Secure Boot]]<br />
{{Related articles start}}<br />
{{Related|Arch boot process}}<br />
{{Related|Unified Extensible Firmware Interface}}<br />
{{Related|Security}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Unified_Extensible_Firmware_Interface#Secure_boot|Secure Boot]] is a security feature found in the [[UEFI]] standard, designed to add a layer of protection to the [[Arch boot process|pre-boot process]]: by maintaining a cryptographically signed list of binaries authorized or forbidden to run at boot, it helps in improving the confidence that the machine core boot components (boot manager, kernel, initramfs) have not been tampered with.<br />
<br />
As such it can be seen as a continuation or complement to the efforts in [[Security|securing]] one's computing environment, reducing the attack surface that other software security solutions such as [[dm-crypt/Encrypting an entire system|system encryption]] cannot easily [[Dm-crypt/Encrypting an entire system#Encrypted boot partition (GRUB)|cover]], while being totally distinct and not dependent on them. Secure Boot just stands on its own as a component of current security practices, with its own set of pros and [[wikipedia:Unified_Extensible_Firmware_Interface#Secure_Boot_2|cons]].<br />
<br />
{{Note|For a deeper overview about Secure Boot in Linux, see [https://www.rodsbooks.com/efi-bootloaders/secureboot.html Rodsbooks' Secure Boot] article and [[#See also|other online resources]]. This article focuses on how to set up Secure Boot in Arch Linux.}}<br />
<br />
== Checking Secure Boot status ==<br />
<br />
=== Before booting the OS ===<br />
<br />
At this point, one has to look at the firmware setup. If the machine was booted and is running, in most cases it will have to be rebooted. <br />
<br />
You may access the firmware configuration by pressing a special key during the boot process. The key to use depends on the firmware. It is usually one of {{ic|Esc}}, {{ic|F2}}, {{ic|Del}} or possibly another {{ic|F''n''}} key. Sometimes the right key is displayed for a short while at the beginning of the boot process. The motherboard manual usually records it. You might want to press the key, and keep pressing it, immediately following powering on the machine, even before the screen actually displays anything.<br />
<br />
After entering the firmware setup, be careful not to change any settings without prior intention. Usually there are navigation instructions, and short help for the settings, at the bottom of each setup screen. The setup itself might be composed of several pages. You will have to navigate to the correct place. The interesting setting might be simply denoted by secure boot, which can be set on or off.<br />
<br />
=== After booting the OS ===<br />
<br />
An easy way to check Secure Boot status on systems using [[systemd]] is to use [[systemd-boot]]:<br />
<br />
{{Note|There is no need to be using systemd-boot as your boot manager for this command to work, it is more akin to the others *ctl systemd utilities (localectl, timedatectl...) and will not touch your configuration.}}<br />
<br />
{{bc|$ bootctl status<br />
System:<br />
Firmware: UEFI 2.70 (American Megatrends 5.15)<br />
Secure Boot: enabled<br />
Setup Mode: user<br />
Boot into FW: supported<br />
...}}<br />
<br />
Here we see that Secure Boot is enabled and enforced; other values are {{ic|disabled}} for Secure Boot and {{ic|setup}} for Setup Mode[https://github.com/systemd/systemd/issues/8154#issue-296106251].<br />
<br />
{{Accuracy|This command might display more than five digits even though secure boot is enabled.}}<br />
<br />
Another way to check whether the machine was booted with Secure Boot is to use this command:<br />
<br />
$ od --address-radix=n --format=u1 /sys/firmware/efi/efivars/SecureBoot*<br />
<br />
If Secure Boot is enabled, this command returns {{ic|1}} as the final integer in a list of five, for example:<br />
<br />
6 0 0 0 1<br />
<br />
Note, however, that the kernel may be unaware of Secure Boot (even if it is enabled in the firmware) if an insufficiently capable boot loader is used. This can be verified by checking the kernel messages shortly after the system starts up:<br />
<br />
{{hc|# dmesg {{!}} grep -i secure|<br />
[ 0.013442] Secure boot disabled<br />
[ 0.013442] Secure boot could not be determined<br />
}}<br />
<br />
The kernel messages will otherwise read {{ic|Secure boot enabled}}.<br />
<br />
== Booting an installation medium ==<br />
<br />
{{Note|The official installation image does not support Secure Boot ({{Bug|53864}}). To successfully boot the installation medium you will need to [[#Disabling Secure Boot|disable Secure Boot]].}}<br />
<br />
Secure Boot support was initially added in {{ic|archlinux-2013.07.01-dual.iso}} and later removed in {{ic|archlinux-2016.06.01-dual.iso}}. At that time ''prebootloader'' was replaced with {{pkg|efitools}}, even though the latter uses unsigned EFI binaries. There has been no support for Secure Boot in the official installation medium ever since.<br />
<br />
[https://gitlab.archlinux.org/tpowa/archboot/-/wikis/Archboot-Homepage Archboot] images provide a way to use secure boot on installation media.<br />
<br />
=== Disabling Secure Boot ===<br />
<br />
The Secure Boot feature can be disabled via the UEFI firmware interface. How to access the firmware configuration is described in [[#Before booting the OS]].<br />
<br />
If using a hotkey did not work and you can boot Windows, you can force a reboot into the firmware configuration in the following way (for Windows 10): ''Settings > Update & Security > Recovery > Advanced startup (Restart now) > Troubleshoot > Advanced options > UEFI Firmware settings > restart''.<br />
<br />
Note that some motherboards (this is the case in a Packard Bell laptop) only allow to disable secure boot if you have set an administrator password (that can be removed afterwards). See also [https://www.rodsbooks.com/efi-bootloaders/secureboot.html#disable Rod Smith's Disabling Secure Boot].<br />
<br />
=== Remastering the installation image ===<br />
<br />
{{Expansion|Add explicit instructions.}}<br />
<br />
One might want to [[Remastering the Install ISO|remaster the Install ISO]] in a way described by previous topics of this article. For example, the signed EFI applications {{ic|PreLoader.efi}} and {{ic|HashTool.efi}} from [[#PreLoader]] can be adopted to here. Another option would be to borrow the {{ic|BOOTx64.EFI}} (shim) and {{ic|grubx64.efi}} from installation media of another GNU+Linux distribution that supports Secure Boot and modify the GRUB configuration to one's needs. In this case, the authentication chain of Secure Boot in said distribution's installation media should end to the {{ic|grubx64.efi}} ( [https://www.linux-magazine.com/index.php/layout/set/print/Issues/2014/164/The-State-of-Secure-Boot/(tagid)/154 for example Ubuntu]) so that GRUB would boot the unsigned kernel and initramfs from archiso. Note that up to this point, the article assumed one can access the [[ESP]] of the machine. But when installing a machine that never had an OS before, there is no ESP present. You should explore other articles, for example [[Unified Extensible Firmware Interface#Create UEFI bootable USB from ISO]], to learn how this situation should be handled.<br />
<br />
== Implementing Secure Boot ==<br />
<br />
There are certain conditions making for an ideal setup of ''Secure boot'':<br />
<br />
# UEFI considered mostly trusted (despite having some well known [[Wikipedia:Unified_Extensible_Firmware_Interface#Criticism|criticisms]] and vulnerabilities[https://www.uefi.org/sites/default/files/resources/UEFI%20Firmware%20-%20Security%20Concerns%20and%20Best%20Practices.pdf]) and necessarily [[#Protecting Secure Boot|protected by a strong password]]<br />
# Default manufacturer/third party keys are not in use, as they have been shown to weaken the security model of Secure Boot by a great margin[https://habr.com/ru/post/446238/]<br />
# UEFI directly loads a user-signed [[EFISTUB]] combined kernel image (no boot manager), including microcode (if applicable) and initramfs so as to maintain throughout the boot process the chain of trust established by Secure Boot and reduce the attack surface<br />
# Use of [[dm-crypt/Encrypting an entire system|full drive encryption]], so that the tools and files involved in the kernel image creation and signing process cannot be accessed and tampered with by someone having physical access to the machine.<br />
# Some further improvements may be obtained by using a [[TPM]], although tooling and support makes this harder to implement.<br />
<br />
A simple and fully self-reliant setup is described in [[#Using your own keys]], while [[#Using a signed boot loader]] makes use of intermediate tools signed by a third-party.<br />
<br />
=== Using your own keys ===<br />
<br />
{{Warning|Replacing the platform keys with your own can end up bricking hardware on some machines, including laptops, making it impossible to get into the UEFI/BIOS settings to rectify the situation. This is due to the fact that some device (e.g GPU) firmware ([[Wikipedia:OpROM|OpROMs]]), that get executed during boot, are signed using [[#Microsoft Windows|Microsoft's key]].}}<br />
<br />
Secure Boot implementations use these keys:<br />
<br />
; Platform Key (PK): Top-level key.<br />
; Key Exchange Key (KEK): Keys used to sign Signatures Database and Forbidden Signatures Database updates.<br />
; Signature Database (db): Contains keys and/or hashes of allowed EFI binaries.<br />
; Forbidden Signatures Database (dbx): Contains keys and/or hashes of denylisted EFI binaries.<br />
<br />
See [https://blog.hansenpartnership.com/the-meaning-of-all-the-uefi-keys/ The Meaning of all the UEFI Keys] for a more detailed explanation.<br />
<br />
To use Secure Boot you need at least '''PK''', '''KEK''' and '''db''' keys. While you can add multiple KEK, db and dbx certificates, only one Platform Key is allowed.<br />
<br />
Once Secure Boot is in "User Mode" keys can only be updated by signing the update (using ''sign-efi-sig-list'') with a higher level key. Platform key can be signed by itself.<br />
<br />
==== Using sbctl ====<br />
{{Pkg|sbctl}} is a user-friendly way of setting up secure boot and signing files.<br />
<br />
{{Note|sbctl doesn't work with all hardware. How well it will work depends on the manufacturer.}}<br />
<br />
===== Creating and enrolling keys =====<br />
Before starting, go to your BIOS settings and turn off secure boot. This is different for each device.<br />
<br />
Once you log back in, check the secure boot status:<br />
$ sbctl status<br />
You should see that sbctl isn't installed and secure boot is disabled.<br />
<br />
Then create your custom secure boot keys:<br />
# sbctl create-keys<br />
<br />
Enroll your keys, with Microsoft's keys, to the EFI:<br />
# sbctl enroll-keys -m<br />
<br />
{{Warning|Some firmware is signed and verified with Microsoft's keys when secure boot is enabled. Not validating devices could brick them. To enroll your keys without enrolling Microsoft's, run: {{ic|# sbctl enroll-keys}}. Only do this if you know what you're doing.}}<br />
<br />
Check the secure boot status again:<br />
$ sbctl status<br />
<br />
sbctl should be installed now, but secure boot won't work until the boot files have been signed with the keys you just created.<br />
<br />
===== Signing =====<br />
<br />
Check what files need to be signed for secure boot to work:<br />
# sbctl verify<br />
<br />
Now sign all the unsigned files.<br />
Usually the [[kernel]] and the [[bootloader]] need to be signed, for example:<br />
# sbctl sign -s /boot/vmlinuz-linux<br />
# sbctl sign -s /boot/EFI/BOOT/BOOTX64.EFI<br />
The files that need to be signed will depend on your system's layout, kernel and bootloader.<br />
<br />
Now you're done! Reboot your system and turn secure boot back on in the BIOS settings.<br />
If the bootloader and OS load, secure boot should be working. Check with:<br />
$ sbctl status<br />
<br />
===== Automatic signing with the pacman hook =====<br />
sbctl comes with a [[pacman hook]] that automatically signs all new files whenever the [[Kernel|Linux kernel]], [[systemd]] or the [[bootloader]] is updated.<br />
<br />
==== Install efitools ====<br />
<br />
Nearly all of the following sections require you to [[install]] the {{Pkg|efitools}} package.<br />
<br />
==== Backing up current variables ====<br />
<br />
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.<br />
<br />
Run the following commands to backup all four of the principal Secure Boot variables:<br />
<br />
$ efi-readvar -v PK -o old_PK.esl<br />
$ efi-readvar -v KEK -o old_KEK.esl<br />
$ efi-readvar -v db -o old_db.esl<br />
$ efi-readvar -v dbx -o old_dbx.esl<br />
<br />
If you perform these commands on a new computer or motherboard, the variables you extract will most likely be the ones provided by Microsoft.<br />
<br />
==== Creating keys ====<br />
<br />
===== Manual process =====<br />
<br />
To generate keys, perform the following steps.<br />
<br />
You will need private keys and certificates in multiple formats:<br />
<br />
; ''.key'': PEM format '''private''' keys for EFI binary and EFI signature list signing.<br />
; ''.crt'': PEM format certificates for {{man|1|sbsign}}, {{man|1|sbvarsign}} and {{man|1|sign-efi-sig-list}}.<br />
; ''.cer'': DER format certificates for firmware.<br />
; ''.esl'': Certificates in an EFI Signature List for {{man|1|sbvarsign}}, {{man|1|efi-updatevar}}, ''KeyTool'' and firmware.<br />
; ''.auth'': Certificates in an EFI Signature List with an authentication header (i.e. a signed certificate update file) for {{man|1|efi-updatevar}}, ''sbkeysync'', ''KeyTool'' and firmware.<br />
<br />
Create a [[Wikipedia:Globally unique identifier|GUID]] for owner identification:<br />
<br />
$ uuidgen --random > GUID.txt<br />
<br />
Platform key:<br />
<br />
$ openssl req -newkey rsa:4096 -nodes -keyout PK.key -new -x509 -sha256 -days ''3650'' -subj "/CN=''my Platform Key''/" -out PK.crt<br />
$ openssl x509 -outform DER -in PK.crt -out PK.cer<br />
$ cert-to-efi-sig-list -g "$(< GUID.txt)" PK.crt PK.esl<br />
$ sign-efi-sig-list -g "$(< GUID.txt)" -k PK.key -c PK.crt PK PK.esl PK.auth<br />
<br />
Sign an empty file to allow removing Platform Key when in "User Mode":<br />
<br />
$ sign-efi-sig-list -g "$(< GUID.txt)" -c PK.crt -k PK.key PK /dev/null rm_PK.auth<br />
<br />
Key Exchange Key:<br />
<br />
$ openssl req -newkey rsa:4096 -nodes -keyout KEK.key -new -x509 -sha256 -days ''3650'' -subj "/CN=''my Key Exchange Key''/" -out KEK.crt<br />
$ openssl x509 -outform DER -in KEK.crt -out KEK.cer<br />
$ cert-to-efi-sig-list -g "$(< GUID.txt)" KEK.crt KEK.esl<br />
$ sign-efi-sig-list -g "$(< GUID.txt)" -k PK.key -c PK.crt KEK KEK.esl KEK.auth<br />
<br />
Signature Database key:<br />
<br />
$ openssl req -newkey rsa:4096 -nodes -keyout db.key -new -x509 -sha256 -days ''3650'' -subj "/CN=''my Signature Database key''/" -out db.crt<br />
$ openssl x509 -outform DER -in db.crt -out db.cer<br />
$ cert-to-efi-sig-list -g "$(< GUID.txt)" db.crt db.esl<br />
$ sign-efi-sig-list -g "$(< GUID.txt)" -k KEK.key -c KEK.crt db db.esl db.auth<br />
<br />
===== Helper scripts =====<br />
<br />
A helper/convenience script is offered by the author of the reference page on this topic[https://www.rodsbooks.com/efi-bootloaders/controlling-sb.html#creatingkeys] (requires [[python]]). A mildly edited version is also packaged as {{AUR|sbkeys}}.<br />
<br />
In order to use it, simply create a folder in a secure location (e.g. {{ic|/etc/efi-keys/}} if later use of {{AUR|sbupdate-git}} to automate unified kernel image creation and signing is planned) and run it:<br />
<br />
# mkdir /etc/efi-keys<br />
# cd !$<br />
# curl -L -O https://www.rodsbooks.com/efi-bootloaders/mkkeys.sh<br />
# chmod +x mkkeys.sh<br />
# ./mkkeys.sh<br />
<Enter a Common Name to embed in the keys, e.g. "Secure Boot"><br />
<br />
This will produce the required files in different formats.<br />
<br />
===== Updating keys =====<br />
<br />
Once Secure Boot is in "User Mode" any changes to KEK, db and dbx need to be signed with a higher level key.<br />
<br />
For example, if you wanted to replace your db key with a new one:<br />
<br />
# [[#Creating keys|Create the new key]],<br />
# Convert it to EFI Signature List,<br />
# Sign the EFI Signature List,<br />
# Enroll the signed certificate update file.<br />
<br />
$ cert-to-efi-sig-list -g "$(< GUID.txt)" ''new_db''.crt ''new_db''.esl<br />
$ sign-efi-sig-list -g "$(< GUID.txt)" -k KEK.key -c KEK.crt db ''new_db''.esl ''new_db''.auth<br />
<br />
If instead of replacing your db key, you want to '''add''' another one to the Signature Database, you need to use the option {{ic|-a}} (see {{man|1|sign-efi-sig-list}}):<br />
<br />
$ sign-efi-sig-list '''-a''' -g "$(< GUID.txt)" -k KEK.key -c KEK.crt db ''new_db''.esl ''new_db''.auth<br />
<br />
When {{ic|''new_db''.auth}} is created, [[#Enrolling keys in firmware|enroll it]].<br />
<br />
==== Signing EFI binaries ====<br />
<br />
When ''Secure Boot'' is active (i.e. in "User Mode"), only signed EFI binaries (e.g. applications, [[Unified Extensible Firmware Interface#UEFI drivers|drivers]], [[unified kernel image]]s) can be launched.<br />
<br />
===== Manually with sbsigntools =====<br />
<br />
Install {{Pkg|sbsigntools}} to sign EFI binaries with {{man|1|sbsign}}.<br />
<br />
{{Tip|<br />
* To check if a binary is signed and list its signatures use {{ic|sbverify --list ''/path/to/binary''}}.<br />
* The [[rEFInd]] boot manager's {{ic|refind-install}} script can sign rEFInd EFI binaries and copy them together with the db certificates to the ESP. See [[rEFInd#Using your own keys]] for instructions.<br />
}}<br />
<br />
{{Note|If running ''sbsign'' without {{ic|--output}} the resulting file will be {{ic|''filename''.signed}}. See {{man|1|sbsign}} for more information.}}<br />
<br />
To sign your kernel and boot manager use ''sbsign'', e.g.:<br />
<br />
# sbsign --key db.key --cert db.crt --output /boot/vmlinuz-linux /boot/vmlinuz-linux<br />
# sbsign --key db.key --cert db.crt --output ''esp''/EFI/BOOT/BOOTx64.EFI ''esp''/EFI/BOOT/BOOTx64.EFI<br />
<br />
{{Warning|Signing kernel only will not protect the initramfs from tampering. See [[Unified kernel image]] to know how to produce a combined image that you can then manually sign with ''sbsign''.}}<br />
<br />
===== Signing the kernel with a pacman hook =====<br />
<br />
You can also use mkinitcpio's [[pacman hook]] to sign the kernel on install and updates.<br />
<br />
Copy {{ic|/usr/share/libalpm/hooks/90-mkinitcpio-install.hook}} to {{ic|/etc/pacman.d/hooks/90-mkinitcpio-install.hook}} and {{ic|/usr/share/libalpm/scripts/mkinitcpio-install}} to {{ic|/usr/local/share/libalpm/scripts/mkinitcpio-install}}.<br />
<br />
In {{ic|/etc/pacman.d/hooks/90-mkinitcpio-install.hook}}, replace:<br />
<br />
Exec = /usr/share/libalpm/scripts/mkinitcpio-install<br />
<br />
with:<br />
<br />
Exec = /usr/local/share/libalpm/scripts/mkinitcpio-install<br />
<br />
In {{ic|/usr/local/share/libalpm/scripts/mkinitcpio-install}}, replace:<br />
<br />
install -Dm644 "${line}" "/boot/vmlinuz-${pkgbase}"<br />
<br />
with:<br />
<br />
sbsign --key ''/path/to/''db.key --cert ''/path/to/''db.crt --output "/boot/vmlinuz-${pkgbase}" "${line}"<br />
<br />
If you are using systemd-boot, there is a [[Systemd-boot#Automatic update|dedicated pacman hook]] doing this task semi-automatically.<br />
<br />
===== Fully automated unified kernel generation and signing with sbupdate =====<br />
<br />
[https://github.com/andreyv/sbupdate sbupdate] is a tool made specifically to automate unified kernel image generation and signing on Arch Linux. It handles installation, removal and updates of kernels through [[pacman hooks]].<br />
<br />
Install {{AUR|sbupdate-git}} and configure it following the instructions given on the project's homepage.[https://github.com/andreyv/sbupdate#sbupdate]<br />
<br />
{{Tip|If using [[systemd-boot]], set {{ic|1=OUT_DIR="EFI/Linux"}} to get your signed kernel images directly recognized without needing configuration. See {{man|7|systemd-boot|FILES}} and [[Systemd-boot#Adding loaders]].}}<br />
<br />
Once configured, simply run {{ic|sbupdate}} as root for first-time image generation.<br />
<br />
{{Note|''sbupdate'' output often contains errors such as {{ic|warning: data remaining[26413568 vs 26423180]: gaps between PE/COFF sections?}}. Those are harmless and can be safely ignored.[https://github.com/andreyv/sbupdate/issues/30]}}<br />
<br />
==== Putting firmware in "Setup Mode" ====<br />
<br />
Secure Boot is in Setup Mode when the Platform Key is removed. To put firmware in Setup Mode, enter firmware setup utility and find an option to delete or clear certificates. How to enter the setup utility is described in [[#Before booting the OS]].<br />
<br />
==== Enrolling keys in firmware ====<br />
<br />
Use one of the following methods to enroll '''db''', '''KEK''' and '''PK''' certificates.<br />
<br />
{{Tip|As the '''dbx''' (forbidden signatures db) is empty, it can be safely left out in the following instructions.}}<br />
<br />
{{Warning|Enrolling Platform Key sets Secure Boot in "User Mode", leaving "Setup Mode", so it should be enrolled last in sequence.}}<br />
<br />
===== Using sbkeysync =====<br />
<br />
Install {{Pkg|sbsigntools}}. Create a directory {{ic|/etc/secureboot/keys}} with the following directory structure -<br />
<br />
/etc/secureboot/keys<br />
├── db<br />
├── dbx<br />
├── KEK<br />
└── PK<br />
<br />
For example using:<br />
<br />
# mkdir -p /etc/secureboot/keys/{db,dbx,KEK,PK}<br />
<br />
Then copy each of the ''.auth'' files that were generated earlier into their respective locations (for example, {{ic|PK.auth}} into {{ic|/etc/secureboot/keys/PK}} and so on).<br />
<br />
If you want to verify the changes {{ic|sbkeysync}} will make to the system's UEFI keystore, use:<br />
<br />
# sbkeysync --pk --dry-run --verbose<br />
<br />
Finally, use {{ic|sbkeysync}} to enroll your keys.<br />
<br />
# sbkeysync --verbose<br />
# sbkeysync --verbose --pk<br />
<br />
{{Tip|<br />
*If {{ic|sbkeysync}} returns write errors, first run {{ic|1=chattr -i /sys/firmware/efi/efivars/{PK,KEK,db}*}} prior to issuing commands with {{ic|sbkeysync}} to temporarily change file attributes, enabling writing of the EFI keys within the {{ic|efivars}} directory. See {{man|1|chattr}}.<br />
* If you get a {{ic|permission denied}} error for {{ic|PK.auth}}, you can enroll it with command {{ic|efi-updatevar -f /etc/secureboot/keys/PK/PK.auth PK}}.}}<br />
<br />
On next boot the UEFI should be back in User Mode and enforcing Secure Boot policy.<br />
<br />
===== Using firmware setup utility =====<br />
<br />
Copy all {{ic|*.cer}}, {{ic|*.esl}}, {{ic|*.auth}} files '''EXCEPT OF {{ic|noPK.auth}}''' files to a [[FAT]] formatted file system (you can use [[EFI system partition]]). <br />
<br />
{{Warning|'''Don't copy the {{ic|noPK.auth}} file to the [[EFI system partition]] (ESP) of your PC!''' If you do this, and someone e.g. steals your PC, this person can delete the personal Platform Key in the UEFI Secure Boot firmware again, turn on "Setup Mode" on your PC again and replace your Secure Boot Keys (PK, KEK, db, dbx) with his or her own Platform Key, thereby defeating the whole purpose of UEFI Secure Boot. Only you should be able to replace the Platform Key, so only you should have access to the {{ic|noPK.auth}} file. Therefore keep the {{ic|noPK.auth}} file in a safe place where only you have access to. A safe place for the noPK.auth file are: <br />
* an '''external USB stick with an [[EFI system partition]]''' when using {{ic|KeyTool}}. Unfortunately, {{ic|KeyTool}} can only read files from unencrypted storage. <br />
* [[Data-at-rest encryption|encrypted storage on your PC]] when using {{ic|sbkeysync}}. <br />
The [[EFI system partition]] of your PC must not be encrypted according to the UEFI specifications and can be mounted and read on another PC (if your PC is stolen and if the hard drive is taken out and connected to another PC). Copying the {{ic|noPK.auth}} file to the ESP of your PC and deleting it afterwards is also not advisable, because deleted files on the FAT32 [[EFI system partition]] [[File recovery#TestDisk and PhotoRec|can be recovered with tools like PhotoRec]].}}<br />
<br />
Launch firmware setup utility and enroll '''db''', '''KEK''' and '''PK''' certificates.<br />
Firmwares have various different interfaces, see [https://www.rodsbooks.com/efi-bootloaders/controlling-sb.html#setuputil Replacing Keys Using Your Firmware's Setup Utility] for example how to enroll keys.<br />
<br />
If the used tool supports it prefer using ''.auth'' and ''.esl'' over ''.cer''.<br />
<br />
===== Using KeyTool =====<br />
<br />
{{ic|KeyTool.efi}} is in {{Pkg|efitools}} package, copy it to ESP. To use it after enrolling keys, sign it with {{ic|sbsign}}.<br />
<br />
# sbsign --key db.key --cert db.crt --output ''esp''/KeyTool-signed.efi /usr/share/efitools/efi/KeyTool.efi<br />
<br />
Launch {{ic|KeyTool-signed.efi}} using firmware setup utility, boot loader or [[Unified Extensible Firmware Interface#UEFI Shell|UEFI Shell]] and enroll keys.<br />
<br />
See [https://www.rodsbooks.com/efi-bootloaders/controlling-sb.html#keytool Replacing Keys Using KeyTool] for explanation of KeyTool menu options.<br />
<br />
==== Dual booting with other operating systems ====<br />
<br />
===== Microsoft Windows =====<br />
<br />
{{Expansion|Is it possible to boot Windows by signing its bootloader with a [[#Creating keys|custom key]]?|section=Booting Windows with custom bootloader signature}}<br />
/<br />
It is usually '''not''' possible to boot Windows by signing its bootloader ({{ic|EFI/Microsoft/Boot/bootmgfw.efi}}) with a [[#Creating keys|custom, personal key]] with Secure Boot Mode enabled, without enrolling the "Microsoft Windows Production PCA 2011" key in the UEFI Secure Boot variables: <br />
* if {{ic|bootmgfw.efi}} contains a signature '''both''' from the "Microsoft Windows Production PCA 2011" '''and''' from your own Secure Boot DB key (so '''two signatures'''), then UEFI firmware implementations like ''INSYDE Corp. 4096.01 (UEFI Version 2.31, Version F.70, Release Date: 07/18/2016, BIOS Revision 15.112, Firmware Revision: 29.66)'' will not launch {{ic|bootmgfw.efi}} and will throw a security violation error ('''{{ic|Selected boot image did not authenticate. Press ENTER to continue.}}'''): UEFI firmware implementation like this can probably only read the '''first''' signature - not the '''second''' one. Only the certificate for the second signature is enrolled in the UEFI Secure Boot variables, so the Secure Boot verification fails. <br />
* if the "Microsoft Windows Production PCA 2011" signature from the {{ic|bootmgfw.efi}} file is stripped/removed, and only a signature from your own Secure Boot DB key is added to the file, then UEFI will launch the file - but Windows will launch a recovery/repair environment: Windows complains that the Windows installation is broken (because the "Microsoft Windows Production PCA 2011" signature on {{ic|bootmgfw.efi}} file is missing). <br />
<br />
So to [[dual boot with Windows]], ...<br />
* you either have to add the hash of {{ic|bootmgfw.efi}} to the list of allowed hashes in the {{ic|DB}} variable; and you have to update the {{ic|DB}} variable every time a Windows Update changes {{ic|bootmgfw.efi}}. This is very tedious, error-prone and not supported by Microsoft; and for example Bitlocker will not work properly anymore with this setup (Bitlocker will ask for your recovery password every time to decrypt your Windows partition). <br />
* or you have to add Microsoft's certificates to the UEFI Secure Boot variables [https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/windows-secure-boot-key-creation-and-management-guidance#14-signature-databases-db-and-dbx Microsoft has two {{ic|DB}} certificates and one {{ic|KEK}} certificate]:<br />
** The [https://www.microsoft.com/pkiops/certs/MicWinProPCA2011_2011-10-19.crt "Microsoft Windows Production PCA 2011"] certificate must be included in the {{ic|DB}} variable in order to allow the Windows Operating System to load. <br />
** The [https://www.microsoft.com/pkiops/certs/MicCorUEFCA2011_2011-06-27.crt "Microsoft Corporation UEFI CA 2011"] certificate should be included in the {{ic|DB}} variable in order to use third-party binaries like UEFI drivers, option ROMs, {{Pkg|shim}}, etc.<br />
** The [https://www.microsoft.com/pkiops/certs/MicCorKEKCA2011_2011-06-24.crt "Microsoft Corporation KEK CA 2011"] certificate should be included in the {{ic|KEK}} variable, in order to "enable revocation of bad images by updating the {{ic|DBX}} and potentially for updating {{ic|DB}} to prepare for newer Windows signed images". However, Windows will also boot without the "Microsoft Corporation KEK CA 2011" certificate. <br />
<br />
Create EFI Signature Lists from Microsoft's DER format {{ic|DB}} certificates using Microsoft's GUID ({{ic|77fa9abd-0359-4d32-bd60-28f4e78f784b}}) and combine them in one file for simplicity:<br />
<br />
$ sbsiglist --owner 77fa9abd-0359-4d32-bd60-28f4e78f784b --type x509 --output MS_Win_db.esl MicWinProPCA2011_2011-10-19.crt<br />
$ sbsiglist --owner 77fa9abd-0359-4d32-bd60-28f4e78f784b --type x509 --output MS_UEFI_db.esl MicCorUEFCA2011_2011-06-27.crt<br />
$ cat MS_Win_db.esl MS_UEFI_db.esl > MS_db.esl<br />
<br />
Optional (for strict conformity with Microsoft UEFI Secure Boot requirements): Create an EFI Signature List from Microsoft's DER format {{ic|KEK}} certificate using Microsoft's GUID ({{ic|77fa9abd-0359-4d32-bd60-28f4e78f784b}}): <br />
$ sbsiglist --owner 77fa9abd-0359-4d32-bd60-28f4e78f784b --type x509 --output MS_Win_KEK.esl MicCorKEKCA2011_2011-06-24.crt <br />
<br />
Sign a {{ic|DB}} variable update with your {{ic|KEK}}. Use {{ic|sign-efi-sig-list}} with option {{ic|-a}} to '''add''' not replace a {{ic|DB}} certificate:<br />
$ sign-efi-sig-list -a -g 77fa9abd-0359-4d32-bd60-28f4e78f784b -k KEK.key -c KEK.crt db MS_db.esl add_MS_db.auth<br />
<br />
<br />
Optional (for strict conformity with Microsoft UEFI Secure Boot requirements): Sign a {{ic|KEK}} variable update with your {{ic|PK}}. Use {{ic|sign-efi-sig-list}} with option {{ic|-a}} to '''add''' not replace a {{ic|KEK}} certificate: <br />
$ sign-efi-sig-list -a -g 77fa9abd-0359-4d32-bd60-28f4e78f784b -k PK.key -c PK.crt KEK MS_Win_KEK.esl add_MS_Win_KEK.auth <br />
<br />
<br />
<br />
Follow [[#Enrolling keys in firmware]] to enroll {{ic|add_MS_db.auth}} and for strict conformity with Microsoft UEFI Secure Boot requirements {{ic|add_MS_Win_KEK.auth}} into the UEFI Secure Boot Database variables.<br />
<br />
=== Using a signed boot loader ===<br />
<br />
Using a signed boot loader means using a boot loader signed with Microsoft's key. There are two known signed boot loaders: PreLoader and shim. Their purpose is to chainload other EFI binaries (usually [[boot loader]]s). Since Microsoft would never sign a boot loader that automatically launches any unsigned binary, PreLoader and shim use an allowlist called Machine Owner Key list, abbreviated MokList. If the SHA256 hash of the binary (Preloader and shim) or key the binary is signed with (shim) is in the MokList they execute it, if not they launch a key management utility which allows enrolling the hash or key.<br />
<br />
==== PreLoader ====<br />
<br />
When run, PreLoader tries to launch {{ic|loader.efi}}. If the hash of {{ic|loader.efi}} is not in MokList, PreLoader will launch {{ic|HashTool.efi}}. In HashTool you must enroll the hash of the EFI binaries you want to launch, that means your [[boot loader]] ({{ic|loader.efi}}) and kernel.<br />
<br />
{{Note|Each time you update any of the binaries (e.g. boot loader or kernel) you will need to enroll their new hash.}}<br />
<br />
{{Tip|The [[rEFInd]] boot manager's {{ic|refind-install}} script can copy the rEFInd and PreLoader EFI binaries to the ESP. See [[rEFInd#Using PreLoader]] for instructions.}}<br />
<br />
===== Set up PreLoader =====<br />
<br />
{{Note|{{ic|PreLoader.efi}} and {{ic|HashTool.efi}} in {{Pkg|efitools}} package are not signed, so their usefulness is limited. You can get a signed {{ic|PreLoader.efi}} and {{ic|HashTool.efi}} from {{AUR|preloader-signed}} or [https://blog.hansenpartnership.com/linux-foundation-secure-boot-system-released/ download them manually].}}<br />
<br />
[[Install]] {{AUR|preloader-signed}} and copy {{ic|PreLoader.efi}} and {{ic|HashTool.efi}} to the [[boot loader]] directory; for [[systemd-boot]] use:<br />
<br />
# cp /usr/share/preloader-signed/{PreLoader,HashTool}.efi ''esp''/EFI/systemd<br />
<br />
Now copy over the boot loader binary and rename it to {{ic|loader.efi}}; for [[systemd-boot]] use:<br />
<br />
# cp ''esp''/EFI/systemd/systemd-bootx64.efi ''esp''/EFI/systemd/loader.efi<br />
<br />
Finally, create a new NVRAM entry to boot {{ic|PreLoader.efi}}:<br />
<br />
# efibootmgr --verbose --disk /dev/sd'''''X''''' --part '''''Y''''' --create --label "PreLoader" --loader /EFI/systemd/PreLoader.efi<br />
<br />
Replace {{ic|''X''}} with the drive letter and replace {{ic|''Y''}} with the partition number of the [[EFI system partition]].<br />
<br />
This entry should be added to the list as the first to boot; check with the {{ic|efibootmgr}} command and adjust the boot-order if necessary.<br />
<br />
====== Fallback ======<br />
<br />
If there are problems booting the custom NVRAM entry, copy {{ic|HashTool.efi}} and {{ic|loader.efi}} to the default loader location booted automatically by UEFI systems:<br />
<br />
# cp /usr/share/preloader-signed/HashTool.efi ''esp''/EFI/BOOT/<br />
# cp ''esp''/EFI/systemd/systemd-bootx64.efi ''esp''/EFI/BOOT/loader.efi<br />
<br />
Copy over {{ic|PreLoader.efi}} and rename it:<br />
<br />
# cp /usr/share/preloader-signed/PreLoader.efi ''esp''/EFI/BOOT/BOOTx64.EFI<br />
<br />
For particularly intransigent UEFI implementations, copy {{ic|PreLoader.efi}} to the default loader location used by Windows systems:<br />
<br />
# mkdir -p ''esp''/EFI/Microsoft/Boot<br />
# cp /usr/share/preloader-signed/PreLoader.efi ''esp''/EFI/Microsoft/Boot/bootmgfw.efi<br />
<br />
{{Note|If dual-booting with Windows, backup the original {{ic|bootmgfw.efi}} first as replacing it may cause problems with Windows updates.}}<br />
<br />
As before, copy {{ic|HashTool.efi}} and {{ic|loader.efi}} to {{ic|''esp''/EFI/Microsoft/Boot/}}.<br />
<br />
When the system starts with Secure Boot enabled, follow the steps above to enroll {{ic|loader.efi}} and {{ic|/vmlinuz-linux}} (or whichever kernel image is being used).<br />
<br />
===== How to use while booting? =====<br />
<br />
A message will show up that says {{ic|Failed to Start loader... I will now execute HashTool.}} To use HashTool for enrolling the hash of {{ic|loader.efi}} and {{ic|vmlinuz.efi}}, follow these steps. These steps assume titles for a remastered archiso installation media. The exact titles you will get depends on your boot loader setup.<br />
<br />
* Select ''OK''<br />
* In the HashTool main menu, select ''Enroll Hash'', choose {{ic|\loader.efi}} and confirm with ''Yes''. Again, select ''Enroll Hash'' and {{ic|archiso}} to enter the archiso directory, then select {{ic|vmlinuz.efi}} and confirm with ''Yes''. Then choose ''Exit'' to return to the boot device selection menu.<br />
* In the boot device selection menu choose ''Arch Linux archiso x86_64 UEFI CD''<br />
<br />
===== Remove PreLoader =====<br />
<br />
{{Note|Since you are going to remove stuff, is a good idea to backup it.}}<br />
<br />
[[Uninstall]] {{AUR|preloader-signed}} and simply remove the copied files and revert configuration; for [[systemd-boot]] use:<br />
<br />
# rm ''esp''/EFI/systemd/{PreLoader,HashTool}.efi<br />
# rm ''esp''/EFI/systemd/loader.efi<br />
# efibootmgr --verbose --bootnum ''N'' --delete-bootnum<br />
# bootctl update<br />
<br />
Where {{ic|''N''}} is the NVRAM boot entry created for booting {{ic|PreLoader.efi}}.<br />
Check with the ''efibootmgr'' command and adjust the boot-order if necessary.<br />
<br />
{{Note|The above commands cover the easiest case; if you have created, copied, renamed or edited further files probably you have to handle with them, too. If PreLoader was your operational boot entry, you obviously also need to [[#Disabling Secure Boot]].}}<br />
<br />
===== Delete enrolled hash =====<br />
<br />
Every entry of hashes enrolled in the MOK database eats up a little piece of space of NVRAM. You may want to delete useless hashes to free the space and to prevent outdated programs from booting.<br />
<br />
[[Install]] {{Pkg|efitools}} and copy {{ic|KeyTool.efi}}:<br />
<br />
# cp /usr/share/efitools/efi/KeyTool.efi ''esp''/EFI/systemd/KeyTool.efi<br />
<br />
Manage to boot to Preloader and you will see the KeyTool entry. You can then edit hashes in the MOK database.<br />
<br />
==== shim ====<br />
<br />
{{Expansion|Testing needed.|section=shim}}<br />
<br />
When run, shim tries to launch {{ic|grubx64.efi}}. If MokList does not contain the hash of {{ic|grubx64.efi}} or the key it is signed with, shim will launch MokManager ({{ic|mmx64.efi}}). In MokManager you must enroll the hash of the EFI binaries you want to launch (your [[boot loader]] ({{ic|grubx64.efi}}) and kernel) or enroll the key they are signed with.<br />
<br />
{{Note|<br />
* If you use [[#shim with hash]], each time you update any of the binaries (e.g. boot loader or kernel) you will need to enroll their new hash.<br />
* Since version 15.3, shim will not launch EFI binaries without a valid {{ic|.sbat}} section. Run {{ic|objdump -j .sbat -s ''/path/to/binary.efi''}} to verify if an EFI binary has it. See the [https://github.com/rhboot/shim/blob/main/SBAT.md SBAT documentation] for details.<br />
* It might be worth mentioning that if you are not actually interested in the security brought by Secure Boot and are only enabling it to meet the requirements posed by Windows 11, you may want to consider disabling the validation process in shim with {{ic|mokutil --disable-validation}}. In that case you will not need to sign grub (sbat probably still needed) or the kernel images and at the same time be able to boot Windows with {{ic|chainloader}} in grub.<br />
}}<br />
<br />
===== Set up shim =====<br />
<br />
{{Tip|The [[rEFInd]] boot manager's {{ic|refind-install}} script can sign rEFInd EFI binaries and copy them along with shim and the MOK certificates to the ESP. See [[rEFInd#Using shim]] for instructions.}}<br />
<br />
[[Install]] {{AUR|shim-signed}}.<br />
<br />
Rename your current [[boot loader]] to {{ic|grubx64.efi}}<br />
<br />
# mv ''esp''/EFI/BOOT/BOOTx64.EFI ''esp''/EFI/BOOT/grubx64.efi<br />
<br />
Copy ''shim'' and ''MokManager'' to your boot loader directory on ESP; use previous filename of your boot loader as as the filename for {{ic|shimx64.efi}}:<br />
<br />
{{Note|<br />
* Make sure you do NOT copy fbx64.efi (which is under the same directory) unless you actually have a valid bootx64.csv to use. Otherwise shim will NOT execute grubx64.efi but will appear to fail to work and just reset the machine.<br />
}}<br />
<br />
# cp /usr/share/shim-signed/shimx64.efi ''esp''/EFI/BOOT/BOOTx64.EFI<br />
# cp /usr/share/shim-signed/mmx64.efi ''esp''/EFI/BOOT/<br />
<br />
Finally, create a new NVRAM entry to boot {{ic|BOOTx64.EFI}}:<br />
<br />
# efibootmgr --verbose --disk /dev/sd'''''X''''' --part '''''Y''''' --create --label "Shim" --loader /EFI/BOOT/BOOTx64.EFI<br />
<br />
''shim'' can authenticate binaries by Machine Owner Key or hash stored in MokList.<br />
<br />
; Machine Owner Key (MOK): A key that a user generates and uses to sign EFI binaries.<br />
; hash: A SHA256 hash of an EFI binary.<br />
<br />
Using hash is simpler, but each time you update your boot loader or kernel you will need to add their hashes in MokManager. With MOK you only need to add the key once, but you will have to sign the boot loader and kernel each time it updates.<br />
<br />
====== shim with hash ======<br />
<br />
If ''shim'' does not find the SHA256 hash of {{ic|grubx64.efi}} in MokList it will launch MokManager ({{ic|mmx64.efi}}).<br />
<br />
In ''MokManager'' select ''Enroll hash from disk'', find {{ic|grubx64.efi}} and add it to MokList. Repeat the steps and add your kernel {{ic|vmlinuz-linux}}. When done select ''Continue boot'' and your boot loader will launch and it will be capable launching the kernel.<br />
<br />
====== shim with key ======<br />
<br />
Install {{Pkg|sbsigntools}}.<br />
<br />
You will need:<br />
<br />
; ''.key'': PEM format '''private''' key for EFI binary signing.<br />
; ''.crt'': PEM format certificate for ''sbsign''.<br />
; ''.cer'': DER format certificate for ''MokManager''.<br />
<br />
Create a Machine Owner Key:<br />
<br />
$ openssl req -newkey rsa:4096 -nodes -keyout MOK.key -new -x509 -sha256 -days ''3650'' -subj "/CN=''my Machine Owner Key''/" -out MOK.crt<br />
$ openssl x509 -outform DER -in MOK.crt -out MOK.cer<br />
<br />
Sign your boot loader (named {{ic|grubx64.efi}}) and kernel:<br />
<br />
# sbsign --key MOK.key --cert MOK.crt --output /boot/vmlinuz-linux /boot/vmlinuz-linux<br />
# sbsign --key MOK.key --cert MOK.crt --output ''esp''/EFI/BOOT/grubx64.efi ''esp''/EFI/BOOT/grubx64.efi<br />
<br />
You will need to do this each time they are updated. You can automate the kernel signing with a [[pacman hook]], e.g.:<br />
<br />
{{hc|/etc/pacman.d/hooks/999-sign_kernel_for_secureboot.hook|2=<br />
[Trigger]<br />
Operation = Install<br />
Operation = Upgrade<br />
Type = Package<br />
Target = linux<br />
Target = linux-lts<br />
Target = linux-hardened<br />
Target = linux-zen<br />
<br />
[Action]<br />
Description = Signing kernel with Machine Owner Key for Secure Boot<br />
When = PostTransaction<br />
Exec = /usr/bin/find /boot/ -maxdepth 1 -name 'vmlinuz-*' -exec /usr/bin/sh -c 'if ! /usr/bin/sbverify --list {} 2>/dev/null {{!}} /usr/bin/grep -q "signature certificates"; then /usr/bin/sbsign --key MOK.key --cert MOK.crt --output {} {}; fi' ;<br />
Depends = sbsigntools<br />
Depends = findutils<br />
Depends = grep<br />
}}<br />
<br />
Copy {{ic|MOK.cer}} to a [[FAT]] formatted file system (you can use [[EFI system partition]]).<br />
<br />
Reboot and enable Secure Boot. If ''shim'' does not find the certificate {{ic|grubx64.efi}} is signed with in MokList it will launch MokManager ({{ic|mmx64.efi}}).<br />
<br />
In ''MokManager'' select ''Enroll key from disk'', find {{ic|MOK.cer}} and add it to MokList. When done select ''Continue boot'' and your boot loader will launch and it will be capable launching any binary signed with your Machine Owner Key.<br />
<br />
====== Shim with key and GRUB ======<br />
<br />
Complete the previous section first.<br />
<br />
Reinstall GRUB using {{ic|/usr/share/grub/sbat.csv}} with the {{ic|TPM}} module enabled and sign it:<br />
<br />
# grub-install --target=x86_64-efi --efi-directory=''esp'' --modules="tpm" --sbat /usr/share/grub/sbat.csv<br />
# sbsign --key MOK.key --cert MOK.crt --output ''esp''/EFI/GRUB/grubx64.efi ''esp''/EFI/GRUB/grubx64.efi<br />
# cp ''esp''/GRUB/grubx64.efi ''esp''/boot/grubx64.efi<br />
<br />
Reboot, select the key in ''MokManager'', and secureboot should be working.<br />
<br />
===== Remove shim =====<br />
<br />
[[Uninstall]] {{AUR|shim-signed}}, remove the copied ''shim'' and ''MokManager'' files and rename back your boot loader.<br />
<br />
== Protecting Secure Boot ==<br />
<br />
The only way to prevent anyone with physical access to disable Secure Boot is to protect the firmware settings with a password.<br />
<br />
Most UEFI firmwares provide such a feature, usually listed under the "Security" section in the firmware settings.<br />
<br />
== See also ==<br />
<br />
* [https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/ Understanding the UEFI Secure Boot Chain] by tianocore<br />
* [[Wikipedia:Unified Extensible Firmware Interface#Secure boot]]<br />
* [https://www.rodsbooks.com/efi-bootloaders/secureboot.html Dealing with Secure Boot] by Rod Smith<br />
* [https://www.rodsbooks.com/efi-bootloaders/controlling-sb.html Controlling Secure Boot] by Rod Smith<br />
* [https://mjg59.dreamwidth.org/5850.html UEFI secure booting (part 2)] by Matthew Garrett<br />
* [https://blog.hansenpartnership.com/uefi-secure-boot/ UEFI Secure Boot] by James Bottomley<br />
* [https://git.kernel.org/cgit/linux/kernel/git/jejb/efitools.git/tree/README efitools README]<br />
* [https://www.fsf.org/campaigns/secure-boot-vs-restricted-boot Will your computer's "Secure Boot" turn out to be "Restricted Boot"?] — Free Software Foundation<br />
* [https://www.fsf.org/campaigns/secure-boot-vs-restricted-boot/statement/campaigns/secure-boot-vs-restricted-boot/whitepaper-web Free Software Foundation recommendations for free operating system distributions considering Secure Boot]<br />
* [https://web.archive.org/web/20150928202110/https://firmware.intel.com/messages/219 Intel's UEFI Secure Boot Tutorial]<br />
* [http://dreamhack.it/linux/2015/12/03/secure-boot-signed-modules-and-signed-elf-binaries.html Secure Boot, Signed Modules and Signed ELF Binaries]<br />
* National Security Agency docs: [https://www.nsa.gov/Portals/70/documents/what-we-do/cybersecurity/professional-resources/ctr-uefi-defensive-practices-guidance.pdf UEFI Defensive Practices Guidance] and unclassified [https://media.defense.gov/2020/Sep/15/2002497594/-1/-1/0/CTR-UEFI-SECURE-BOOT-CUSTOMIZATION-20200915.PDF/CTR-UEFI-SECURE-BOOT-CUSTOMIZATION-20200915.PDF UEFI Secure Boot customization]<br />
* [http://jk.ozlabs.org/docs/sbkeysync-maintaing-uefi-key-databases/ sbkeysync & maintaining uefi key databases] by Jeremy Kerr<br />
* [https://nwildner.com/posts/2020-07-04-secure-your-boot-process/ Secure your boot process: UEFI + Secureboot + EFISTUB + Luks2 + lvm + Arch Linux] (2020-07)<br />
* [https://security.stackexchange.com/questions/29122/how-is-hibernation-supported-on-machines-with-uefi-secure-boot How is hibernation supported, on machines with UEFI Secure Boot?] (Security StackExchange)<br />
* [http://0pointer.net/blog/authenticated-boot-and-disk-encryption-on-linux.html Authenticated Boot and Disk Encryption on Linux] by Lennart Poettering (2021-09-23)</div>Calciumhttps://wiki.archlinux.org/index.php?title=Unified_Extensible_Firmware_Interface/Secure_Boot&diff=740587Unified Extensible Firmware Interface/Secure Boot2022-08-08T07:40:18Z<p>Calcium: Add sbctl instructions</p>
<hr />
<div>[[Category:Boot process]]<br />
[[ja:セキュアブート]]<br />
[[zh-hans:Unified Extensible Firmware Interface (简体中文)/Secure Boot]]<br />
{{Related articles start}}<br />
{{Related|Arch boot process}}<br />
{{Related|Unified Extensible Firmware Interface}}<br />
{{Related|Security}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Unified_Extensible_Firmware_Interface#Secure_boot|Secure Boot]] is a security feature found in the [[UEFI]] standard, designed to add a layer of protection to the [[Arch boot process|pre-boot process]]: by maintaining a cryptographically signed list of binaries authorized or forbidden to run at boot, it helps in improving the confidence that the machine core boot components (boot manager, kernel, initramfs) have not been tampered with.<br />
<br />
As such it can be seen as a continuation or complement to the efforts in [[Security|securing]] one's computing environment, reducing the attack surface that other software security solutions such as [[dm-crypt/Encrypting an entire system|system encryption]] cannot easily [[Dm-crypt/Encrypting an entire system#Encrypted boot partition (GRUB)|cover]], while being totally distinct and not dependent on them. Secure Boot just stands on its own as a component of current security practices, with its own set of pros and [[wikipedia:Unified_Extensible_Firmware_Interface#Secure_Boot_2|cons]].<br />
<br />
{{Note|For a deeper overview about Secure Boot in Linux, see [https://www.rodsbooks.com/efi-bootloaders/secureboot.html Rodsbooks' Secure Boot] article and [[#See also|other online resources]]. This article focuses on how to set up Secure Boot in Arch Linux.}}<br />
<br />
== Checking Secure Boot status ==<br />
<br />
=== Before booting the OS ===<br />
<br />
At this point, one has to look at the firmware setup. If the machine was booted and is running, in most cases it will have to be rebooted. <br />
<br />
You may access the firmware configuration by pressing a special key during the boot process. The key to use depends on the firmware. It is usually one of {{ic|Esc}}, {{ic|F2}}, {{ic|Del}} or possibly another {{ic|F''n''}} key. Sometimes the right key is displayed for a short while at the beginning of the boot process. The motherboard manual usually records it. You might want to press the key, and keep pressing it, immediately following powering on the machine, even before the screen actually displays anything.<br />
<br />
After entering the firmware setup, be careful not to change any settings without prior intention. Usually there are navigation instructions, and short help for the settings, at the bottom of each setup screen. The setup itself might be composed of several pages. You will have to navigate to the correct place. The interesting setting might be simply denoted by secure boot, which can be set on or off.<br />
<br />
=== After booting the OS ===<br />
<br />
An easy way to check Secure Boot status on systems using [[systemd]] is to use [[systemd-boot]]:<br />
<br />
{{Note|There is no need to be using systemd-boot as your boot manager for this command to work, it is more akin to the others *ctl systemd utilities (localectl, timedatectl...) and will not touch your configuration.}}<br />
<br />
{{bc|$ bootctl status<br />
System:<br />
Firmware: UEFI 2.70 (American Megatrends 5.15)<br />
Secure Boot: enabled<br />
Setup Mode: user<br />
Boot into FW: supported<br />
...}}<br />
<br />
Here we see that Secure Boot is enabled and enforced; other values are {{ic|disabled}} for Secure Boot and {{ic|setup}} for Setup Mode[https://github.com/systemd/systemd/issues/8154#issue-296106251].<br />
<br />
{{Accuracy|This command might display more than five digits even though secure boot is enabled.}}<br />
<br />
Another way to check whether the machine was booted with Secure Boot is to use this command:<br />
<br />
$ od --address-radix=n --format=u1 /sys/firmware/efi/efivars/SecureBoot*<br />
<br />
If Secure Boot is enabled, this command returns {{ic|1}} as the final integer in a list of five, for example:<br />
<br />
6 0 0 0 1<br />
<br />
Note, however, that the kernel may be unaware of Secure Boot (even if it is enabled in the firmware) if an insufficiently capable boot loader is used. This can be verified by checking the kernel messages shortly after the system starts up:<br />
<br />
{{hc|# dmesg {{!}} grep -i secure|<br />
[ 0.013442] Secure boot disabled<br />
[ 0.013442] Secure boot could not be determined<br />
}}<br />
<br />
The kernel messages will otherwise read {{ic|Secure boot enabled}}.<br />
<br />
== Booting an installation medium ==<br />
<br />
{{Note|The official installation image does not support Secure Boot ({{Bug|53864}}). To successfully boot the installation medium you will need to [[#Disabling Secure Boot|disable Secure Boot]].}}<br />
<br />
Secure Boot support was initially added in {{ic|archlinux-2013.07.01-dual.iso}} and later removed in {{ic|archlinux-2016.06.01-dual.iso}}. At that time ''prebootloader'' was replaced with {{pkg|efitools}}, even though the latter uses unsigned EFI binaries. There has been no support for Secure Boot in the official installation medium ever since.<br />
<br />
[https://gitlab.archlinux.org/tpowa/archboot/-/wikis/Archboot-Homepage Archboot] images provide a way to use secure boot on installation media.<br />
<br />
=== Disabling Secure Boot ===<br />
<br />
The Secure Boot feature can be disabled via the UEFI firmware interface. How to access the firmware configuration is described in [[#Before booting the OS]].<br />
<br />
If using a hotkey did not work and you can boot Windows, you can force a reboot into the firmware configuration in the following way (for Windows 10): ''Settings > Update & Security > Recovery > Advanced startup (Restart now) > Troubleshoot > Advanced options > UEFI Firmware settings > restart''.<br />
<br />
Note that some motherboards (this is the case in a Packard Bell laptop) only allow to disable secure boot if you have set an administrator password (that can be removed afterwards). See also [https://www.rodsbooks.com/efi-bootloaders/secureboot.html#disable Rod Smith's Disabling Secure Boot].<br />
<br />
=== Remastering the installation image ===<br />
<br />
{{Expansion|Add explicit instructions.}}<br />
<br />
One might want to [[Remastering the Install ISO|remaster the Install ISO]] in a way described by previous topics of this article. For example, the signed EFI applications {{ic|PreLoader.efi}} and {{ic|HashTool.efi}} from [[#PreLoader]] can be adopted to here. Another option would be to borrow the {{ic|BOOTx64.EFI}} (shim) and {{ic|grubx64.efi}} from installation media of another GNU+Linux distribution that supports Secure Boot and modify the GRUB configuration to one's needs. In this case, the authentication chain of Secure Boot in said distribution's installation media should end to the {{ic|grubx64.efi}} ( [https://www.linux-magazine.com/index.php/layout/set/print/Issues/2014/164/The-State-of-Secure-Boot/(tagid)/154 for example Ubuntu]) so that GRUB would boot the unsigned kernel and initramfs from archiso. Note that up to this point, the article assumed one can access the [[ESP]] of the machine. But when installing a machine that never had an OS before, there is no ESP present. You should explore other articles, for example [[Unified Extensible Firmware Interface#Create UEFI bootable USB from ISO]], to learn how this situation should be handled.<br />
<br />
== Implementing Secure Boot ==<br />
<br />
There are certain conditions making for an ideal setup of ''Secure boot'':<br />
<br />
# UEFI considered mostly trusted (despite having some well known [[Wikipedia:Unified_Extensible_Firmware_Interface#Criticism|criticisms]] and vulnerabilities[https://www.uefi.org/sites/default/files/resources/UEFI%20Firmware%20-%20Security%20Concerns%20and%20Best%20Practices.pdf]) and necessarily [[#Protecting Secure Boot|protected by a strong password]]<br />
# Default manufacturer/third party keys are not in use, as they have been shown to weaken the security model of Secure Boot by a great margin[https://habr.com/ru/post/446238/]<br />
# UEFI directly loads a user-signed [[EFISTUB]] combined kernel image (no boot manager), including microcode (if applicable) and initramfs so as to maintain throughout the boot process the chain of trust established by Secure Boot and reduce the attack surface<br />
# Use of [[dm-crypt/Encrypting an entire system|full drive encryption]], so that the tools and files involved in the kernel image creation and signing process cannot be accessed and tampered with by someone having physical access to the machine.<br />
# Some further improvements may be obtained by using a [[TPM]], although tooling and support makes this harder to implement.<br />
<br />
A simple and fully self-reliant setup is described in [[#Using your own keys]], while [[#Using a signed boot loader]] makes use of intermediate tools signed by a third-party.<br />
<br />
=== Using your own keys ===<br />
<br />
{{Warning|Replacing the platform keys with your own can end up bricking hardware on some machines, including laptops, making it impossible to get into the UEFI/BIOS settings to rectify the situation. This is due to the fact that some device (e.g GPU) firmware ([[Wikipedia:OpROM|OpROMs]]), that get executed during boot, are signed using [[#Microsoft Windows|Microsoft's key]].}}<br />
<br />
Secure Boot implementations use these keys:<br />
<br />
; Platform Key (PK): Top-level key.<br />
; Key Exchange Key (KEK): Keys used to sign Signatures Database and Forbidden Signatures Database updates.<br />
; Signature Database (db): Contains keys and/or hashes of allowed EFI binaries.<br />
; Forbidden Signatures Database (dbx): Contains keys and/or hashes of denylisted EFI binaries.<br />
<br />
See [https://blog.hansenpartnership.com/the-meaning-of-all-the-uefi-keys/ The Meaning of all the UEFI Keys] for a more detailed explanation.<br />
<br />
To use Secure Boot you need at least '''PK''', '''KEK''' and '''db''' keys. While you can add multiple KEK, db and dbx certificates, only one Platform Key is allowed.<br />
<br />
Once Secure Boot is in "User Mode" keys can only be updated by signing the update (using ''sign-efi-sig-list'') with a higher level key. Platform key can be signed by itself.<br />
<br />
==== Using sbctl ====<br />
{{Pkg|sbctl}} is a user-friendly way of setting up secure boot and signing files.<br />
<br />
{{Note|sbctl doesn't work with all hardware. How well it will work depends on the manufacturer.}}<br />
<br />
===== Creating and enrolling keys =====<br />
Before starting, go to your BIOS settings and turn off secure boot. This is different for each device.<br />
<br />
Once you log back in, check the secure boot status:<br />
$ sbctl status<br />
You should see that sbctl isn't installed and secure boot is disabled.<br />
<br />
Then create your custom secure boot keys:<br />
# sbctl create-keys<br />
<br />
Enroll your keys, with Microsoft's keys, to the EFI:<br />
# sbctl enroll-keys -m<br />
<br />
{{Warning|Some firmware is signed and verified with Microsoft's keys when secure boot is enabled. Not validating devices could brick them. To enroll your keys without enrolling Microsoft's, run: {{ic|# sbctl enroll-keys}}. Only do this if you know what you're doing.}}<br />
<br />
Check the secure boot status again:<br />
$ sbctl status<br />
<br />
sbctl should be installed now, but secure boot won't work until the boot files have been signed with the keys you just created.<br />
<br />
===== Signing =====<br />
<br />
Check what files need to be signed for secure boot to work:<br />
# sbctl verify<br />
<br />
Now sign all the unsigned files, for example:<br />
# sbctl sign -s /boot/EFI/BOOT/BOOTX64.EFI<br />
What files will need signing depends on the boot partition's layout and the [[bootloader]].<br />
<br />
Now you're done! Reboot your system and turn secure boot back on in the BIOS settings.<br />
If the bootloader and OS load, secure boot should be working. Check with:<br />
$ sbctl status<br />
<br />
===== Automatic signing with the pacman hook =====<br />
sbctl comes with a [[pacman hook]] that automatically signs all new files whenever the [[Kernel|Linux kernel]], [[systemd]] or the [[bootloader]] is updated.<br />
<br />
==== Install efitools ====<br />
<br />
Nearly all of the following sections require you to [[install]] the {{Pkg|efitools}} package.<br />
<br />
==== Backing up current variables ====<br />
<br />
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.<br />
<br />
Run the following commands to backup all four of the principal Secure Boot variables:<br />
<br />
$ efi-readvar -v PK -o old_PK.esl<br />
$ efi-readvar -v KEK -o old_KEK.esl<br />
$ efi-readvar -v db -o old_db.esl<br />
$ efi-readvar -v dbx -o old_dbx.esl<br />
<br />
If you perform these commands on a new computer or motherboard, the variables you extract will most likely be the ones provided by Microsoft.<br />
<br />
==== Creating keys ====<br />
<br />
===== Manual process =====<br />
<br />
To generate keys, perform the following steps.<br />
<br />
You will need private keys and certificates in multiple formats:<br />
<br />
; ''.key'': PEM format '''private''' keys for EFI binary and EFI signature list signing.<br />
; ''.crt'': PEM format certificates for {{man|1|sbsign}}, {{man|1|sbvarsign}} and {{man|1|sign-efi-sig-list}}.<br />
; ''.cer'': DER format certificates for firmware.<br />
; ''.esl'': Certificates in an EFI Signature List for {{man|1|sbvarsign}}, {{man|1|efi-updatevar}}, ''KeyTool'' and firmware.<br />
; ''.auth'': Certificates in an EFI Signature List with an authentication header (i.e. a signed certificate update file) for {{man|1|efi-updatevar}}, ''sbkeysync'', ''KeyTool'' and firmware.<br />
<br />
Create a [[Wikipedia:Globally unique identifier|GUID]] for owner identification:<br />
<br />
$ uuidgen --random > GUID.txt<br />
<br />
Platform key:<br />
<br />
$ openssl req -newkey rsa:4096 -nodes -keyout PK.key -new -x509 -sha256 -days ''3650'' -subj "/CN=''my Platform Key''/" -out PK.crt<br />
$ openssl x509 -outform DER -in PK.crt -out PK.cer<br />
$ cert-to-efi-sig-list -g "$(< GUID.txt)" PK.crt PK.esl<br />
$ sign-efi-sig-list -g "$(< GUID.txt)" -k PK.key -c PK.crt PK PK.esl PK.auth<br />
<br />
Sign an empty file to allow removing Platform Key when in "User Mode":<br />
<br />
$ sign-efi-sig-list -g "$(< GUID.txt)" -c PK.crt -k PK.key PK /dev/null rm_PK.auth<br />
<br />
Key Exchange Key:<br />
<br />
$ openssl req -newkey rsa:4096 -nodes -keyout KEK.key -new -x509 -sha256 -days ''3650'' -subj "/CN=''my Key Exchange Key''/" -out KEK.crt<br />
$ openssl x509 -outform DER -in KEK.crt -out KEK.cer<br />
$ cert-to-efi-sig-list -g "$(< GUID.txt)" KEK.crt KEK.esl<br />
$ sign-efi-sig-list -g "$(< GUID.txt)" -k PK.key -c PK.crt KEK KEK.esl KEK.auth<br />
<br />
Signature Database key:<br />
<br />
$ openssl req -newkey rsa:4096 -nodes -keyout db.key -new -x509 -sha256 -days ''3650'' -subj "/CN=''my Signature Database key''/" -out db.crt<br />
$ openssl x509 -outform DER -in db.crt -out db.cer<br />
$ cert-to-efi-sig-list -g "$(< GUID.txt)" db.crt db.esl<br />
$ sign-efi-sig-list -g "$(< GUID.txt)" -k KEK.key -c KEK.crt db db.esl db.auth<br />
<br />
===== Helper scripts =====<br />
<br />
A helper/convenience script is offered by the author of the reference page on this topic[https://www.rodsbooks.com/efi-bootloaders/controlling-sb.html#creatingkeys] (requires [[python]]). A mildly edited version is also packaged as {{AUR|sbkeys}}.<br />
<br />
In order to use it, simply create a folder in a secure location (e.g. {{ic|/etc/efi-keys/}} if later use of {{AUR|sbupdate-git}} to automate unified kernel image creation and signing is planned) and run it:<br />
<br />
# mkdir /etc/efi-keys<br />
# cd !$<br />
# curl -L -O https://www.rodsbooks.com/efi-bootloaders/mkkeys.sh<br />
# chmod +x mkkeys.sh<br />
# ./mkkeys.sh<br />
<Enter a Common Name to embed in the keys, e.g. "Secure Boot"><br />
<br />
This will produce the required files in different formats.<br />
<br />
===== Updating keys =====<br />
<br />
Once Secure Boot is in "User Mode" any changes to KEK, db and dbx need to be signed with a higher level key.<br />
<br />
For example, if you wanted to replace your db key with a new one:<br />
<br />
# [[#Creating keys|Create the new key]],<br />
# Convert it to EFI Signature List,<br />
# Sign the EFI Signature List,<br />
# Enroll the signed certificate update file.<br />
<br />
$ cert-to-efi-sig-list -g "$(< GUID.txt)" ''new_db''.crt ''new_db''.esl<br />
$ sign-efi-sig-list -g "$(< GUID.txt)" -k KEK.key -c KEK.crt db ''new_db''.esl ''new_db''.auth<br />
<br />
If instead of replacing your db key, you want to '''add''' another one to the Signature Database, you need to use the option {{ic|-a}} (see {{man|1|sign-efi-sig-list}}):<br />
<br />
$ sign-efi-sig-list '''-a''' -g "$(< GUID.txt)" -k KEK.key -c KEK.crt db ''new_db''.esl ''new_db''.auth<br />
<br />
When {{ic|''new_db''.auth}} is created, [[#Enrolling keys in firmware|enroll it]].<br />
<br />
==== Signing EFI binaries ====<br />
<br />
When ''Secure Boot'' is active (i.e. in "User Mode"), only signed EFI binaries (e.g. applications, [[Unified Extensible Firmware Interface#UEFI drivers|drivers]], [[unified kernel image]]s) can be launched.<br />
<br />
===== Manually with sbsigntools =====<br />
<br />
Install {{Pkg|sbsigntools}} to sign EFI binaries with {{man|1|sbsign}}.<br />
<br />
{{Tip|<br />
* To check if a binary is signed and list its signatures use {{ic|sbverify --list ''/path/to/binary''}}.<br />
* The [[rEFInd]] boot manager's {{ic|refind-install}} script can sign rEFInd EFI binaries and copy them together with the db certificates to the ESP. See [[rEFInd#Using your own keys]] for instructions.<br />
}}<br />
<br />
{{Note|If running ''sbsign'' without {{ic|--output}} the resulting file will be {{ic|''filename''.signed}}. See {{man|1|sbsign}} for more information.}}<br />
<br />
To sign your kernel and boot manager use ''sbsign'', e.g.:<br />
<br />
# sbsign --key db.key --cert db.crt --output /boot/vmlinuz-linux /boot/vmlinuz-linux<br />
# sbsign --key db.key --cert db.crt --output ''esp''/EFI/BOOT/BOOTx64.EFI ''esp''/EFI/BOOT/BOOTx64.EFI<br />
<br />
{{Warning|Signing kernel only will not protect the initramfs from tampering. See [[Unified kernel image]] to know how to produce a combined image that you can then manually sign with ''sbsign''.}}<br />
<br />
===== Signing the kernel with a pacman hook =====<br />
<br />
You can also use mkinitcpio's [[pacman hook]] to sign the kernel on install and updates.<br />
<br />
Copy {{ic|/usr/share/libalpm/hooks/90-mkinitcpio-install.hook}} to {{ic|/etc/pacman.d/hooks/90-mkinitcpio-install.hook}} and {{ic|/usr/share/libalpm/scripts/mkinitcpio-install}} to {{ic|/usr/local/share/libalpm/scripts/mkinitcpio-install}}.<br />
<br />
In {{ic|/etc/pacman.d/hooks/90-mkinitcpio-install.hook}}, replace:<br />
<br />
Exec = /usr/share/libalpm/scripts/mkinitcpio-install<br />
<br />
with:<br />
<br />
Exec = /usr/local/share/libalpm/scripts/mkinitcpio-install<br />
<br />
In {{ic|/usr/local/share/libalpm/scripts/mkinitcpio-install}}, replace:<br />
<br />
install -Dm644 "${line}" "/boot/vmlinuz-${pkgbase}"<br />
<br />
with:<br />
<br />
sbsign --key ''/path/to/''db.key --cert ''/path/to/''db.crt --output "/boot/vmlinuz-${pkgbase}" "${line}"<br />
<br />
If you are using systemd-boot, there is a [[Systemd-boot#Automatic update|dedicated pacman hook]] doing this task semi-automatically.<br />
<br />
===== Fully automated unified kernel generation and signing with sbupdate =====<br />
<br />
[https://github.com/andreyv/sbupdate sbupdate] is a tool made specifically to automate unified kernel image generation and signing on Arch Linux. It handles installation, removal and updates of kernels through [[pacman hooks]].<br />
<br />
Install {{AUR|sbupdate-git}} and configure it following the instructions given on the project's homepage.[https://github.com/andreyv/sbupdate#sbupdate]<br />
<br />
{{Tip|If using [[systemd-boot]], set {{ic|1=OUT_DIR="EFI/Linux"}} to get your signed kernel images directly recognized without needing configuration. See {{man|7|systemd-boot|FILES}} and [[Systemd-boot#Adding loaders]].}}<br />
<br />
Once configured, simply run {{ic|sbupdate}} as root for first-time image generation.<br />
<br />
{{Note|''sbupdate'' output often contains errors such as {{ic|warning: data remaining[26413568 vs 26423180]: gaps between PE/COFF sections?}}. Those are harmless and can be safely ignored.[https://github.com/andreyv/sbupdate/issues/30]}}<br />
<br />
==== Putting firmware in "Setup Mode" ====<br />
<br />
Secure Boot is in Setup Mode when the Platform Key is removed. To put firmware in Setup Mode, enter firmware setup utility and find an option to delete or clear certificates. How to enter the setup utility is described in [[#Before booting the OS]].<br />
<br />
==== Enrolling keys in firmware ====<br />
<br />
Use one of the following methods to enroll '''db''', '''KEK''' and '''PK''' certificates.<br />
<br />
{{Tip|As the '''dbx''' (forbidden signatures db) is empty, it can be safely left out in the following instructions.}}<br />
<br />
{{Warning|Enrolling Platform Key sets Secure Boot in "User Mode", leaving "Setup Mode", so it should be enrolled last in sequence.}}<br />
<br />
===== Using sbkeysync =====<br />
<br />
Install {{Pkg|sbsigntools}}. Create a directory {{ic|/etc/secureboot/keys}} with the following directory structure -<br />
<br />
/etc/secureboot/keys<br />
├── db<br />
├── dbx<br />
├── KEK<br />
└── PK<br />
<br />
For example using:<br />
<br />
# mkdir -p /etc/secureboot/keys/{db,dbx,KEK,PK}<br />
<br />
Then copy each of the ''.auth'' files that were generated earlier into their respective locations (for example, {{ic|PK.auth}} into {{ic|/etc/secureboot/keys/PK}} and so on).<br />
<br />
If you want to verify the changes {{ic|sbkeysync}} will make to the system's UEFI keystore, use:<br />
<br />
# sbkeysync --pk --dry-run --verbose<br />
<br />
Finally, use {{ic|sbkeysync}} to enroll your keys.<br />
<br />
# sbkeysync --verbose<br />
# sbkeysync --verbose --pk<br />
<br />
{{Tip|<br />
*If {{ic|sbkeysync}} returns write errors, first run {{ic|1=chattr -i /sys/firmware/efi/efivars/{PK,KEK,db}*}} prior to issuing commands with {{ic|sbkeysync}} to temporarily change file attributes, enabling writing of the EFI keys within the {{ic|efivars}} directory. See {{man|1|chattr}}.<br />
* If you get a {{ic|permission denied}} error for {{ic|PK.auth}}, you can enroll it with command {{ic|efi-updatevar -f /etc/secureboot/keys/PK/PK.auth PK}}.}}<br />
<br />
On next boot the UEFI should be back in User Mode and enforcing Secure Boot policy.<br />
<br />
===== Using firmware setup utility =====<br />
<br />
Copy all {{ic|*.cer}}, {{ic|*.esl}}, {{ic|*.auth}} files '''EXCEPT OF {{ic|noPK.auth}}''' files to a [[FAT]] formatted file system (you can use [[EFI system partition]]). <br />
<br />
{{Warning|'''Don't copy the {{ic|noPK.auth}} file to the [[EFI system partition]] (ESP) of your PC!''' If you do this, and someone e.g. steals your PC, this person can delete the personal Platform Key in the UEFI Secure Boot firmware again, turn on "Setup Mode" on your PC again and replace your Secure Boot Keys (PK, KEK, db, dbx) with his or her own Platform Key, thereby defeating the whole purpose of UEFI Secure Boot. Only you should be able to replace the Platform Key, so only you should have access to the {{ic|noPK.auth}} file. Therefore keep the {{ic|noPK.auth}} file in a safe place where only you have access to. A safe place for the noPK.auth file are: <br />
* an '''external USB stick with an [[EFI system partition]]''' when using {{ic|KeyTool}}. Unfortunately, {{ic|KeyTool}} can only read files from unencrypted storage. <br />
* [[Data-at-rest encryption|encrypted storage on your PC]] when using {{ic|sbkeysync}}. <br />
The [[EFI system partition]] of your PC must not be encrypted according to the UEFI specifications and can be mounted and read on another PC (if your PC is stolen and if the hard drive is taken out and connected to another PC). Copying the {{ic|noPK.auth}} file to the ESP of your PC and deleting it afterwards is also not advisable, because deleted files on the FAT32 [[EFI system partition]] [[File recovery#TestDisk and PhotoRec|can be recovered with tools like PhotoRec]].}}<br />
<br />
Launch firmware setup utility and enroll '''db''', '''KEK''' and '''PK''' certificates.<br />
Firmwares have various different interfaces, see [https://www.rodsbooks.com/efi-bootloaders/controlling-sb.html#setuputil Replacing Keys Using Your Firmware's Setup Utility] for example how to enroll keys.<br />
<br />
If the used tool supports it prefer using ''.auth'' and ''.esl'' over ''.cer''.<br />
<br />
===== Using KeyTool =====<br />
<br />
{{ic|KeyTool.efi}} is in {{Pkg|efitools}} package, copy it to ESP. To use it after enrolling keys, sign it with {{ic|sbsign}}.<br />
<br />
# sbsign --key db.key --cert db.crt --output ''esp''/KeyTool-signed.efi /usr/share/efitools/efi/KeyTool.efi<br />
<br />
Launch {{ic|KeyTool-signed.efi}} using firmware setup utility, boot loader or [[Unified Extensible Firmware Interface#UEFI Shell|UEFI Shell]] and enroll keys.<br />
<br />
See [https://www.rodsbooks.com/efi-bootloaders/controlling-sb.html#keytool Replacing Keys Using KeyTool] for explanation of KeyTool menu options.<br />
<br />
==== Dual booting with other operating systems ====<br />
<br />
===== Microsoft Windows =====<br />
<br />
{{Expansion|Is it possible to boot Windows by signing its bootloader with a [[#Creating keys|custom key]]?|section=Booting Windows with custom bootloader signature}}<br />
/<br />
It is usually '''not''' possible to boot Windows by signing its bootloader ({{ic|EFI/Microsoft/Boot/bootmgfw.efi}}) with a [[#Creating keys|custom, personal key]] with Secure Boot Mode enabled, without enrolling the "Microsoft Windows Production PCA 2011" key in the UEFI Secure Boot variables: <br />
* if {{ic|bootmgfw.efi}} contains a signature '''both''' from the "Microsoft Windows Production PCA 2011" '''and''' from your own Secure Boot DB key (so '''two signatures'''), then UEFI firmware implementations like ''INSYDE Corp. 4096.01 (UEFI Version 2.31, Version F.70, Release Date: 07/18/2016, BIOS Revision 15.112, Firmware Revision: 29.66)'' will not launch {{ic|bootmgfw.efi}} and will throw a security violation error ('''{{ic|Selected boot image did not authenticate. Press ENTER to continue.}}'''): UEFI firmware implementation like this can probably only read the '''first''' signature - not the '''second''' one. Only the certificate for the second signature is enrolled in the UEFI Secure Boot variables, so the Secure Boot verification fails. <br />
* if the "Microsoft Windows Production PCA 2011" signature from the {{ic|bootmgfw.efi}} file is stripped/removed, and only a signature from your own Secure Boot DB key is added to the file, then UEFI will launch the file - but Windows will launch a recovery/repair environment: Windows complains that the Windows installation is broken (because the "Microsoft Windows Production PCA 2011" signature on {{ic|bootmgfw.efi}} file is missing). <br />
<br />
So to [[dual boot with Windows]], ...<br />
* you either have to add the hash of {{ic|bootmgfw.efi}} to the list of allowed hashes in the {{ic|DB}} variable; and you have to update the {{ic|DB}} variable every time a Windows Update changes {{ic|bootmgfw.efi}}. This is very tedious, error-prone and not supported by Microsoft; and for example Bitlocker will not work properly anymore with this setup (Bitlocker will ask for your recovery password every time to decrypt your Windows partition). <br />
* or you have to add Microsoft's certificates to the UEFI Secure Boot variables [https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/windows-secure-boot-key-creation-and-management-guidance#14-signature-databases-db-and-dbx Microsoft has two {{ic|DB}} certificates and one {{ic|KEK}} certificate]:<br />
** The [https://www.microsoft.com/pkiops/certs/MicWinProPCA2011_2011-10-19.crt "Microsoft Windows Production PCA 2011"] certificate must be included in the {{ic|DB}} variable in order to allow the Windows Operating System to load. <br />
** The [https://www.microsoft.com/pkiops/certs/MicCorUEFCA2011_2011-06-27.crt "Microsoft Corporation UEFI CA 2011"] certificate should be included in the {{ic|DB}} variable in order to use third-party binaries like UEFI drivers, option ROMs, {{Pkg|shim}}, etc.<br />
** The [https://www.microsoft.com/pkiops/certs/MicCorKEKCA2011_2011-06-24.crt "Microsoft Corporation KEK CA 2011"] certificate should be included in the {{ic|KEK}} variable, in order to "enable revocation of bad images by updating the {{ic|DBX}} and potentially for updating {{ic|DB}} to prepare for newer Windows signed images". However, Windows will also boot without the "Microsoft Corporation KEK CA 2011" certificate. <br />
<br />
Create EFI Signature Lists from Microsoft's DER format {{ic|DB}} certificates using Microsoft's GUID ({{ic|77fa9abd-0359-4d32-bd60-28f4e78f784b}}) and combine them in one file for simplicity:<br />
<br />
$ sbsiglist --owner 77fa9abd-0359-4d32-bd60-28f4e78f784b --type x509 --output MS_Win_db.esl MicWinProPCA2011_2011-10-19.crt<br />
$ sbsiglist --owner 77fa9abd-0359-4d32-bd60-28f4e78f784b --type x509 --output MS_UEFI_db.esl MicCorUEFCA2011_2011-06-27.crt<br />
$ cat MS_Win_db.esl MS_UEFI_db.esl > MS_db.esl<br />
<br />
Optional (for strict conformity with Microsoft UEFI Secure Boot requirements): Create an EFI Signature List from Microsoft's DER format {{ic|KEK}} certificate using Microsoft's GUID ({{ic|77fa9abd-0359-4d32-bd60-28f4e78f784b}}): <br />
$ sbsiglist --owner 77fa9abd-0359-4d32-bd60-28f4e78f784b --type x509 --output MS_Win_KEK.esl MicCorKEKCA2011_2011-06-24.crt <br />
<br />
Sign a {{ic|DB}} variable update with your {{ic|KEK}}. Use {{ic|sign-efi-sig-list}} with option {{ic|-a}} to '''add''' not replace a {{ic|DB}} certificate:<br />
$ sign-efi-sig-list -a -g 77fa9abd-0359-4d32-bd60-28f4e78f784b -k KEK.key -c KEK.crt db MS_db.esl add_MS_db.auth<br />
<br />
<br />
Optional (for strict conformity with Microsoft UEFI Secure Boot requirements): Sign a {{ic|KEK}} variable update with your {{ic|PK}}. Use {{ic|sign-efi-sig-list}} with option {{ic|-a}} to '''add''' not replace a {{ic|KEK}} certificate: <br />
$ sign-efi-sig-list -a -g 77fa9abd-0359-4d32-bd60-28f4e78f784b -k PK.key -c PK.crt KEK MS_Win_KEK.esl add_MS_Win_KEK.auth <br />
<br />
<br />
<br />
Follow [[#Enrolling keys in firmware]] to enroll {{ic|add_MS_db.auth}} and for strict conformity with Microsoft UEFI Secure Boot requirements {{ic|add_MS_Win_KEK.auth}} into the UEFI Secure Boot Database variables.<br />
<br />
=== Using a signed boot loader ===<br />
<br />
Using a signed boot loader means using a boot loader signed with Microsoft's key. There are two known signed boot loaders: PreLoader and shim. Their purpose is to chainload other EFI binaries (usually [[boot loader]]s). Since Microsoft would never sign a boot loader that automatically launches any unsigned binary, PreLoader and shim use an allowlist called Machine Owner Key list, abbreviated MokList. If the SHA256 hash of the binary (Preloader and shim) or key the binary is signed with (shim) is in the MokList they execute it, if not they launch a key management utility which allows enrolling the hash or key.<br />
<br />
==== PreLoader ====<br />
<br />
When run, PreLoader tries to launch {{ic|loader.efi}}. If the hash of {{ic|loader.efi}} is not in MokList, PreLoader will launch {{ic|HashTool.efi}}. In HashTool you must enroll the hash of the EFI binaries you want to launch, that means your [[boot loader]] ({{ic|loader.efi}}) and kernel.<br />
<br />
{{Note|Each time you update any of the binaries (e.g. boot loader or kernel) you will need to enroll their new hash.}}<br />
<br />
{{Tip|The [[rEFInd]] boot manager's {{ic|refind-install}} script can copy the rEFInd and PreLoader EFI binaries to the ESP. See [[rEFInd#Using PreLoader]] for instructions.}}<br />
<br />
===== Set up PreLoader =====<br />
<br />
{{Note|{{ic|PreLoader.efi}} and {{ic|HashTool.efi}} in {{Pkg|efitools}} package are not signed, so their usefulness is limited. You can get a signed {{ic|PreLoader.efi}} and {{ic|HashTool.efi}} from {{AUR|preloader-signed}} or [https://blog.hansenpartnership.com/linux-foundation-secure-boot-system-released/ download them manually].}}<br />
<br />
[[Install]] {{AUR|preloader-signed}} and copy {{ic|PreLoader.efi}} and {{ic|HashTool.efi}} to the [[boot loader]] directory; for [[systemd-boot]] use:<br />
<br />
# cp /usr/share/preloader-signed/{PreLoader,HashTool}.efi ''esp''/EFI/systemd<br />
<br />
Now copy over the boot loader binary and rename it to {{ic|loader.efi}}; for [[systemd-boot]] use:<br />
<br />
# cp ''esp''/EFI/systemd/systemd-bootx64.efi ''esp''/EFI/systemd/loader.efi<br />
<br />
Finally, create a new NVRAM entry to boot {{ic|PreLoader.efi}}:<br />
<br />
# efibootmgr --verbose --disk /dev/sd'''''X''''' --part '''''Y''''' --create --label "PreLoader" --loader /EFI/systemd/PreLoader.efi<br />
<br />
Replace {{ic|''X''}} with the drive letter and replace {{ic|''Y''}} with the partition number of the [[EFI system partition]].<br />
<br />
This entry should be added to the list as the first to boot; check with the {{ic|efibootmgr}} command and adjust the boot-order if necessary.<br />
<br />
====== Fallback ======<br />
<br />
If there are problems booting the custom NVRAM entry, copy {{ic|HashTool.efi}} and {{ic|loader.efi}} to the default loader location booted automatically by UEFI systems:<br />
<br />
# cp /usr/share/preloader-signed/HashTool.efi ''esp''/EFI/BOOT/<br />
# cp ''esp''/EFI/systemd/systemd-bootx64.efi ''esp''/EFI/BOOT/loader.efi<br />
<br />
Copy over {{ic|PreLoader.efi}} and rename it:<br />
<br />
# cp /usr/share/preloader-signed/PreLoader.efi ''esp''/EFI/BOOT/BOOTx64.EFI<br />
<br />
For particularly intransigent UEFI implementations, copy {{ic|PreLoader.efi}} to the default loader location used by Windows systems:<br />
<br />
# mkdir -p ''esp''/EFI/Microsoft/Boot<br />
# cp /usr/share/preloader-signed/PreLoader.efi ''esp''/EFI/Microsoft/Boot/bootmgfw.efi<br />
<br />
{{Note|If dual-booting with Windows, backup the original {{ic|bootmgfw.efi}} first as replacing it may cause problems with Windows updates.}}<br />
<br />
As before, copy {{ic|HashTool.efi}} and {{ic|loader.efi}} to {{ic|''esp''/EFI/Microsoft/Boot/}}.<br />
<br />
When the system starts with Secure Boot enabled, follow the steps above to enroll {{ic|loader.efi}} and {{ic|/vmlinuz-linux}} (or whichever kernel image is being used).<br />
<br />
===== How to use while booting? =====<br />
<br />
A message will show up that says {{ic|Failed to Start loader... I will now execute HashTool.}} To use HashTool for enrolling the hash of {{ic|loader.efi}} and {{ic|vmlinuz.efi}}, follow these steps. These steps assume titles for a remastered archiso installation media. The exact titles you will get depends on your boot loader setup.<br />
<br />
* Select ''OK''<br />
* In the HashTool main menu, select ''Enroll Hash'', choose {{ic|\loader.efi}} and confirm with ''Yes''. Again, select ''Enroll Hash'' and {{ic|archiso}} to enter the archiso directory, then select {{ic|vmlinuz.efi}} and confirm with ''Yes''. Then choose ''Exit'' to return to the boot device selection menu.<br />
* In the boot device selection menu choose ''Arch Linux archiso x86_64 UEFI CD''<br />
<br />
===== Remove PreLoader =====<br />
<br />
{{Note|Since you are going to remove stuff, is a good idea to backup it.}}<br />
<br />
[[Uninstall]] {{AUR|preloader-signed}} and simply remove the copied files and revert configuration; for [[systemd-boot]] use:<br />
<br />
# rm ''esp''/EFI/systemd/{PreLoader,HashTool}.efi<br />
# rm ''esp''/EFI/systemd/loader.efi<br />
# efibootmgr --verbose --bootnum ''N'' --delete-bootnum<br />
# bootctl update<br />
<br />
Where {{ic|''N''}} is the NVRAM boot entry created for booting {{ic|PreLoader.efi}}.<br />
Check with the ''efibootmgr'' command and adjust the boot-order if necessary.<br />
<br />
{{Note|The above commands cover the easiest case; if you have created, copied, renamed or edited further files probably you have to handle with them, too. If PreLoader was your operational boot entry, you obviously also need to [[#Disabling Secure Boot]].}}<br />
<br />
===== Delete enrolled hash =====<br />
<br />
Every entry of hashes enrolled in the MOK database eats up a little piece of space of NVRAM. You may want to delete useless hashes to free the space and to prevent outdated programs from booting.<br />
<br />
[[Install]] {{Pkg|efitools}} and copy {{ic|KeyTool.efi}}:<br />
<br />
# cp /usr/share/efitools/efi/KeyTool.efi ''esp''/EFI/systemd/KeyTool.efi<br />
<br />
Manage to boot to Preloader and you will see the KeyTool entry. You can then edit hashes in the MOK database.<br />
<br />
==== shim ====<br />
<br />
{{Expansion|Testing needed.|section=shim}}<br />
<br />
When run, shim tries to launch {{ic|grubx64.efi}}. If MokList does not contain the hash of {{ic|grubx64.efi}} or the key it is signed with, shim will launch MokManager ({{ic|mmx64.efi}}). In MokManager you must enroll the hash of the EFI binaries you want to launch (your [[boot loader]] ({{ic|grubx64.efi}}) and kernel) or enroll the key they are signed with.<br />
<br />
{{Note|<br />
* If you use [[#shim with hash]], each time you update any of the binaries (e.g. boot loader or kernel) you will need to enroll their new hash.<br />
* Since version 15.3, shim will not launch EFI binaries without a valid {{ic|.sbat}} section. Run {{ic|objdump -j .sbat -s ''/path/to/binary.efi''}} to verify if an EFI binary has it. See the [https://github.com/rhboot/shim/blob/main/SBAT.md SBAT documentation] for details.<br />
* It might be worth mentioning that if you are not actually interested in the security brought by Secure Boot and are only enabling it to meet the requirements posed by Windows 11, you may want to consider disabling the validation process in shim with {{ic|mokutil --disable-validation}}. In that case you will not need to sign grub (sbat probably still needed) or the kernel images and at the same time be able to boot Windows with {{ic|chainloader}} in grub.<br />
}}<br />
<br />
===== Set up shim =====<br />
<br />
{{Tip|The [[rEFInd]] boot manager's {{ic|refind-install}} script can sign rEFInd EFI binaries and copy them along with shim and the MOK certificates to the ESP. See [[rEFInd#Using shim]] for instructions.}}<br />
<br />
[[Install]] {{AUR|shim-signed}}.<br />
<br />
Rename your current [[boot loader]] to {{ic|grubx64.efi}}<br />
<br />
# mv ''esp''/EFI/BOOT/BOOTx64.EFI ''esp''/EFI/BOOT/grubx64.efi<br />
<br />
Copy ''shim'' and ''MokManager'' to your boot loader directory on ESP; use previous filename of your boot loader as as the filename for {{ic|shimx64.efi}}:<br />
<br />
{{Note|<br />
* Make sure you do NOT copy fbx64.efi (which is under the same directory) unless you actually have a valid bootx64.csv to use. Otherwise shim will NOT execute grubx64.efi but will appear to fail to work and just reset the machine.<br />
}}<br />
<br />
# cp /usr/share/shim-signed/shimx64.efi ''esp''/EFI/BOOT/BOOTx64.EFI<br />
# cp /usr/share/shim-signed/mmx64.efi ''esp''/EFI/BOOT/<br />
<br />
Finally, create a new NVRAM entry to boot {{ic|BOOTx64.EFI}}:<br />
<br />
# efibootmgr --verbose --disk /dev/sd'''''X''''' --part '''''Y''''' --create --label "Shim" --loader /EFI/BOOT/BOOTx64.EFI<br />
<br />
''shim'' can authenticate binaries by Machine Owner Key or hash stored in MokList.<br />
<br />
; Machine Owner Key (MOK): A key that a user generates and uses to sign EFI binaries.<br />
; hash: A SHA256 hash of an EFI binary.<br />
<br />
Using hash is simpler, but each time you update your boot loader or kernel you will need to add their hashes in MokManager. With MOK you only need to add the key once, but you will have to sign the boot loader and kernel each time it updates.<br />
<br />
====== shim with hash ======<br />
<br />
If ''shim'' does not find the SHA256 hash of {{ic|grubx64.efi}} in MokList it will launch MokManager ({{ic|mmx64.efi}}).<br />
<br />
In ''MokManager'' select ''Enroll hash from disk'', find {{ic|grubx64.efi}} and add it to MokList. Repeat the steps and add your kernel {{ic|vmlinuz-linux}}. When done select ''Continue boot'' and your boot loader will launch and it will be capable launching the kernel.<br />
<br />
====== shim with key ======<br />
<br />
Install {{Pkg|sbsigntools}}.<br />
<br />
You will need:<br />
<br />
; ''.key'': PEM format '''private''' key for EFI binary signing.<br />
; ''.crt'': PEM format certificate for ''sbsign''.<br />
; ''.cer'': DER format certificate for ''MokManager''.<br />
<br />
Create a Machine Owner Key:<br />
<br />
$ openssl req -newkey rsa:4096 -nodes -keyout MOK.key -new -x509 -sha256 -days ''3650'' -subj "/CN=''my Machine Owner Key''/" -out MOK.crt<br />
$ openssl x509 -outform DER -in MOK.crt -out MOK.cer<br />
<br />
Sign your boot loader (named {{ic|grubx64.efi}}) and kernel:<br />
<br />
# sbsign --key MOK.key --cert MOK.crt --output /boot/vmlinuz-linux /boot/vmlinuz-linux<br />
# sbsign --key MOK.key --cert MOK.crt --output ''esp''/EFI/BOOT/grubx64.efi ''esp''/EFI/BOOT/grubx64.efi<br />
<br />
You will need to do this each time they are updated. You can automate the kernel signing with a [[pacman hook]], e.g.:<br />
<br />
{{hc|/etc/pacman.d/hooks/999-sign_kernel_for_secureboot.hook|2=<br />
[Trigger]<br />
Operation = Install<br />
Operation = Upgrade<br />
Type = Package<br />
Target = linux<br />
Target = linux-lts<br />
Target = linux-hardened<br />
Target = linux-zen<br />
<br />
[Action]<br />
Description = Signing kernel with Machine Owner Key for Secure Boot<br />
When = PostTransaction<br />
Exec = /usr/bin/find /boot/ -maxdepth 1 -name 'vmlinuz-*' -exec /usr/bin/sh -c 'if ! /usr/bin/sbverify --list {} 2>/dev/null {{!}} /usr/bin/grep -q "signature certificates"; then /usr/bin/sbsign --key MOK.key --cert MOK.crt --output {} {}; fi' ;<br />
Depends = sbsigntools<br />
Depends = findutils<br />
Depends = grep<br />
}}<br />
<br />
Copy {{ic|MOK.cer}} to a [[FAT]] formatted file system (you can use [[EFI system partition]]).<br />
<br />
Reboot and enable Secure Boot. If ''shim'' does not find the certificate {{ic|grubx64.efi}} is signed with in MokList it will launch MokManager ({{ic|mmx64.efi}}).<br />
<br />
In ''MokManager'' select ''Enroll key from disk'', find {{ic|MOK.cer}} and add it to MokList. When done select ''Continue boot'' and your boot loader will launch and it will be capable launching any binary signed with your Machine Owner Key.<br />
<br />
====== Shim with key and GRUB ======<br />
<br />
Complete the previous section first.<br />
<br />
Reinstall GRUB using {{ic|/usr/share/grub/sbat.csv}} with the {{ic|TPM}} module enabled and sign it:<br />
<br />
# grub-install --target=x86_64-efi --efi-directory=''esp'' --modules="tpm" --sbat /usr/share/grub/sbat.csv<br />
# sbsign --key MOK.key --cert MOK.crt --output ''esp''/EFI/GRUB/grubx64.efi ''esp''/EFI/GRUB/grubx64.efi<br />
# cp ''esp''/GRUB/grubx64.efi ''esp''/boot/grubx64.efi<br />
<br />
Reboot, select the key in ''MokManager'', and secureboot should be working.<br />
<br />
===== Remove shim =====<br />
<br />
[[Uninstall]] {{AUR|shim-signed}}, remove the copied ''shim'' and ''MokManager'' files and rename back your boot loader.<br />
<br />
== Protecting Secure Boot ==<br />
<br />
The only way to prevent anyone with physical access to disable Secure Boot is to protect the firmware settings with a password.<br />
<br />
Most UEFI firmwares provide such a feature, usually listed under the "Security" section in the firmware settings.<br />
<br />
== See also ==<br />
<br />
* [https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/ Understanding the UEFI Secure Boot Chain] by tianocore<br />
* [[Wikipedia:Unified Extensible Firmware Interface#Secure boot]]<br />
* [https://www.rodsbooks.com/efi-bootloaders/secureboot.html Dealing with Secure Boot] by Rod Smith<br />
* [https://www.rodsbooks.com/efi-bootloaders/controlling-sb.html Controlling Secure Boot] by Rod Smith<br />
* [https://mjg59.dreamwidth.org/5850.html UEFI secure booting (part 2)] by Matthew Garrett<br />
* [https://blog.hansenpartnership.com/uefi-secure-boot/ UEFI Secure Boot] by James Bottomley<br />
* [https://git.kernel.org/cgit/linux/kernel/git/jejb/efitools.git/tree/README efitools README]<br />
* [https://www.fsf.org/campaigns/secure-boot-vs-restricted-boot Will your computer's "Secure Boot" turn out to be "Restricted Boot"?] — Free Software Foundation<br />
* [https://www.fsf.org/campaigns/secure-boot-vs-restricted-boot/statement/campaigns/secure-boot-vs-restricted-boot/whitepaper-web Free Software Foundation recommendations for free operating system distributions considering Secure Boot]<br />
* [https://web.archive.org/web/20150928202110/https://firmware.intel.com/messages/219 Intel's UEFI Secure Boot Tutorial]<br />
* [http://dreamhack.it/linux/2015/12/03/secure-boot-signed-modules-and-signed-elf-binaries.html Secure Boot, Signed Modules and Signed ELF Binaries]<br />
* National Security Agency docs: [https://www.nsa.gov/Portals/70/documents/what-we-do/cybersecurity/professional-resources/ctr-uefi-defensive-practices-guidance.pdf UEFI Defensive Practices Guidance] and unclassified [https://media.defense.gov/2020/Sep/15/2002497594/-1/-1/0/CTR-UEFI-SECURE-BOOT-CUSTOMIZATION-20200915.PDF/CTR-UEFI-SECURE-BOOT-CUSTOMIZATION-20200915.PDF UEFI Secure Boot customization]<br />
* [http://jk.ozlabs.org/docs/sbkeysync-maintaing-uefi-key-databases/ sbkeysync & maintaining uefi key databases] by Jeremy Kerr<br />
* [https://nwildner.com/posts/2020-07-04-secure-your-boot-process/ Secure your boot process: UEFI + Secureboot + EFISTUB + Luks2 + lvm + Arch Linux] (2020-07)<br />
* [https://security.stackexchange.com/questions/29122/how-is-hibernation-supported-on-machines-with-uefi-secure-boot How is hibernation supported, on machines with UEFI Secure Boot?] (Security StackExchange)<br />
* [http://0pointer.net/blog/authenticated-boot-and-disk-encryption-on-linux.html Authenticated Boot and Disk Encryption on Linux] by Lennart Poettering (2021-09-23)</div>Calciumhttps://wiki.archlinux.org/index.php?title=WirePlumber&diff=739773WirePlumber2022-08-02T09:19:26Z<p>Calcium: Added wpctl commands to get and set volume</p>
<hr />
<div>[[Category:Multimedia]]<br />
[[ja:WirePlumber]]<br />
[[ru:WirePlumber]]<br />
{{Related articles start}}<br />
{{Related|PipeWire}}<br />
{{Related articles end}}<br />
<br />
[https://pipewire.pages.freedesktop.org/wireplumber WirePlumber] is a powerful session and policy manager for [[PipeWire]]. Based on a modular design, with Lua plugins that implement the actual management functionality, it is highly configurable and extendable.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|wireplumber}} package. It will conflict with other PipeWire Session Managers and make sure they are uninstalled.<br />
<br />
WirePlumber uses [[systemd/User]] for management of the server.<br />
<br />
Optionally, install {{Pkg|wireplumber-docs}} to review the documentation.<br />
<br />
== Configuration ==<br />
<br />
WirePlumber's modular design confers lots of flexibility when it comes to swapping the implementation of a specific functionality without having to re-implement the rest of it. Detailed information can be found at the [https://pipewire.pages.freedesktop.org/wireplumber/configuration.html official documentation].<br />
<br />
Below we add examples of simple configurations.<br />
<br />
=== Obtain interface name for rules matching ===<br />
<br />
In WirePlumber's Lua scripts, you need to specify {{ic|matches}} rules with [https://docs.pipewire.org/page_objects_design.html PipeWire objects] of the target interface you want to configure.<br />
<br />
Use the commands {{ic|pw-cli list-objects}} and {{ic|pw-cli dump}} to show all available objects in the system.<br />
<br />
Object {{ic|Node}} are sinks or sources in the PipeWire graph. They correspond to the ALSA {{ic|Device}}.<br />
<br />
To filter what type to show, add the {{ic|list-objects}} option with one of {{ic|<nowiki>[Device|Node]</nowiki>}}. For example:<br />
<br />
{{hc|$ pw-cli list-objects Device|output=<br />
...<br />
id 37, type PipeWire:Interface:Device/3<br />
object.serial = "264"<br />
factory.id = "14"<br />
client.id = "49"<br />
device.api = "alsa"<br />
device.description = "Starship/Matisse HD Audio Controller"<br />
device.name = "alsa_card.pci-0000_08_00.4"<br />
device.nick = "HD-Audio Generic"<br />
media.class = "Audio/Device"<br />
...<br />
}}<br />
<br />
Object type filtering also applies to the {{ic|pw-cli dump}} command.<br />
<br />
If you are looking for specific class of the endpoint (ex. “Audio/Sink”), see the {{ic|media.class}} property.<br />
<br />
In most cases, when configuring ALSA the property you need is either {{ic|device.name}} or {{ic|node.name}}.<br />
<br />
{{Tip|The command {{ic|pw-top}} show a list of {{ic|Node}} currently in use.}}<br />
<br />
=== Changing a device/node property ===<br />
<br />
To change a device or node property, such as its description or nick, you must create a Lua script and add it into {{ic|~/.config/wireplumber}} under the proper path and name.<br />
<br />
For instance, to change the description of an ALSA node, you would create a file such as {{ic|~/.config/wireplumber/main.lua.d/51-alsa-rename.lua}} with the following content:<br />
{{hc|head=51-alsa-rename.lua|output=rule = {<br />
matches = {<br />
{<br />
{ "node.name", "equals", "alsa_output.pci-0000_00_1f.3.output_analog-stereo" },<br />
},<br />
},<br />
apply_properties = {<br />
["node.description"] = "Laptop",<br />
},<br />
}<br />
<br />
table.insert(alsa_monitor.rules,rule)}}<br />
<br />
If instead you wish to change something on a Bluetooth node or device, you could create {{ic|~/.config/wireplumber/bluetooth.lua.d/51-rename.lua}} with a content such as:<br />
{{hc|head=51-rename.lua|output=rule = {<br />
matches = {<br />
{<br />
{ "node.name", "equals", "bluez_output.02_11_45_A0_B3_27.a2dp-sink" },<br />
},<br />
},<br />
apply_properties = {<br />
["node.nick"] = "Headphones",<br />
},<br />
}<br />
<br />
table.insert(bluez_monitor.rules,rule)}}<br />
<br />
The Lua scripts' filenames and locations are thus devised in a way that allows [https://pipewire.pages.freedesktop.org/wireplumber/configuration/config_lua.html#multi-path-merging WirePlumber's Multi-path merging] to run them just after the default configuration files (e.g. {{ic|/usr/share/wireplumber/main.lua.d/50-alsa-config.lua}}) but before the file that loads and enables the devices (e.g. {{ic|/usr/share/wireplumber/main.lua.d/90-enable-all.lua}}).<br />
<br />
The properties that you can change as well as the matching rules to select devices or nodes are documented at [https://pipewire.pages.freedesktop.org/wireplumber/configuration/alsa.html ALSA configuration] and [https://pipewire.pages.freedesktop.org/wireplumber/configuration/bluetooth.html Bluetooth configuration].<br />
<br />
=== Disable a device/node ===<br />
<br />
Since WirePlumber v0.4.7, users could now disable any devices or nodes by property {{ic|device.disabled}} or {{ic|node.disabled}}<br />
<br />
{{hc|head=~/.config/wireplumber/main.lua.d/51-alsa-disable.lua|output=rule = {<br />
matches = {<br />
{<br />
{ "device.name", "equals", "alsa_card.pci-0000_08_00.4" },<br />
},<br />
},<br />
apply_properties = {<br />
["device.disabled"] = true,<br />
},<br />
}<br />
<br />
table.insert(alsa_monitor.rules,rule)}}<br />
<br />
For the name of {{ic|alsa_card.*}} in your system, see [[#Obtain interface name for rules matching]]<br />
<br />
{{Note|Common use-case, for example, is to disable NVIDIA's HDMI audio output.}}<br />
<br />
=== Simultaneous output to multiple sinks on the same sound card ===<br />
<br />
Create a copy of {{ic|/usr/share/alsa-card-profile/mixer/profile-sets/default.conf}} so that changes persist across updates. Here we define a profile joining the two default mappings for Analog and HDMI.<br />
<br />
{{hc|/usr/share/alsa-card-profile/mixer/profile-sets/multiple.conf|2=<br />
[General]<br />
auto-profiles = no<br />
<br />
[Mapping analog-stereo]<br />
device-strings = front:%f<br />
channel-map = left,right<br />
paths-output = analog-output analog-output-lineout analog-output-speaker analog-output-headphones analog-output-headphones-2<br />
paths-input = analog-input-front-mic analog-input-rear-mic analog-input-internal-mic analog-input-dock-mic analog-input analog-input-mic analog-input-linein analog-input-aux analog-input-video analog-input-tvtuner analog-input-fm analog-input-mic-line analog-input-headphone-mic analog-input-headset-mic<br />
priority = 15<br />
<br />
[Mapping hdmi-stereo]<br />
description = Digital Stereo (HDMI)<br />
device-strings = hdmi:%f<br />
paths-output = hdmi-output-0<br />
channel-map = left,right<br />
priority = 9<br />
direction = output<br />
<br />
[Profile multiple]<br />
description = Analog Stereo Duplex + Digital Stereo (HDMI) Output<br />
output-mappings = analog-stereo hdmi-stereo<br />
input-mappings = analog-stereo<br />
}}<br />
<br />
Now we configure Wireplumber to use the new card-profile for matching devices. For identifying information see [[#Obtain interface name for rules matching]]. We apply the configuration systemwide by creating a Lua script in the new directory {{ic|# mkdir -p /etc/wireplumber/main.lua.d}} with a number prefixed filename starting after {{ic|50-alsa-config.lua}}:<br />
<br />
{{hc|/etc/wireplumber/main.lua.d/51-alsa-custom.lua|2=<br />
rule = {<br />
matches = {<br />
{<br />
{ "device.nick", "matches", "HDA Intel PCH" },<br />
},<br />
},<br />
apply_properties = {<br />
["api.alsa.use-acp"] = true,<br />
["api.acp.auto-profile"] = false,<br />
["api.acp.auto-port"] = false,<br />
["device.profile-set"] = "multiple.conf",<br />
["device.profile"] = "multiple",<br />
},<br />
}<br />
table.insert(alsa_monitor.rules,rule)<br />
}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Keyboard volume control ===<br />
<br />
See [[Keyboard shortcuts#Xorg]] to bind the following commands to your volume keys: {{ic|XF86AudioRaiseVolume}}, {{ic|XF86AudioLowerVolume}} and {{ic|XF86AudioMute}}.<br />
<br />
To raise the volume:<br />
$ wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+<br />
<br />
To lower the volume:<br />
<br />
$ wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-<br />
<br />
To mute/unmute the volume:<br />
<br />
$ wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle<br />
<br />
To mute/unmute the microphone:<br />
<br />
$ wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle<br />
<br />
{{Tip|<br />
* To use sinks or sources other than the default ones, run {{ic|wpctl status}} to list all available sinks, and use sink or source numbers in place of {{ic|@DEFAULT_AUDIO_SINK@}} or {{ic|_SOURCE@}}.<br />
}}<br />
<br />
=== Show volume level ===<br />
<br />
To get the volume level and mute status of the default sink:<br />
$ wpctl get-volume @DEFAULT_AUDIO_SINK@<br />
<br />
{{Note|This only shows the mute status when the sink is muted.}}<br />
<br />
== See also ==<br />
<br />
* [https://pipewire.pages.freedesktop.org/wireplumber/ Documentation] — Official documentation<br />
* [https://www.collabora.com/news-and-blog/blog/2020/05/07/wireplumber-the-pipewire-session-manager/ WirePlumber, the PipeWire session manager] — Blog post by George Kiagiadakis (Collabora) from May 2020, detailing how WirePlumber works</div>Calcium