Framework Laptop 16 - UEFI Keyboard FN-lock driver

This UEFI app/driver runs as soon as USB devices are enumerated and sends a HID command to the keyboard module so that the F2/F12 hotkeys are always functional, even if the FN-lock is off (mediakeys active).

Running

Framework Laptop 16 BIOS will ship with this app embedded.

To run a modified version, build it, as below, or download a release binary.

Preparing the keyboard

Since v0.2.2 the keyboard firmware has support for the hotkey mode.

For easier debugging, there's a special release that also changes the RGB backlight when hotkey mode is enabled/disabled to red/white.

Running the executable

It can be started on the shell, just by starting the executable.

# Run QEMU
make run

# And then in the UEFI Shell
# Check devices
Shell> fs0:uefi_hotkey_app.efi lsusb

# Lock hotkeys
Shell> fs0:uefi_hotkey_app.efi lock
# Unlock keys for regular usage again
Shell> fs0:uefi_hotkey_app.efi unlock

Building

Pre-requisites:

• Rustup (MSRV: 1.61)

Build:

# Build debug version
> make
-rwxrwxr-x 2 zoid zoid 695K May  2 11:48 target/x86_64-unknown-uefi/debug/uefi_hotkey_app.efi

# Build release version
> make release
-rwxrwxr-x 2 zoid zoid 426K May  2 11:49 target/x86_64-unknown-uefi/release/uefi_hotkey_app.efi

# Copy executable to UEFI System Partition (ESP)
cp target/x86_64-unknown-uefi/debug/uefi_hotkey_app /boot/efi

# Make sure to also put a UEFI shell at /boot/efi/EFI/BOOT/BOOTX64.efi
# Or put it somewhere else on the ESP and add a bootloader entry for it

• List all USB devices (version)
• List all USB devices (lsusb)
• List keyboards (lsqmk)
• Show keyboard lock status (status)
• Lock keyboard hotkeys (lock)
• Unlock keyboard hotkeys (unlock)

Current Limitations

• Only works with one Framework 16 Keyboard attached
• Hook to ExitBootServices does not work - doesn't turn the mode off
• Hook to ExitBootServices makes the OS that loads crash

Security Design

This sections explains the design of this project. It should serve as guidance for future changes. Any changes that change the security related design, should be carefully evaluated.

To limit how bugs in this application affect boot-time and overall system security, this app/driver is constrained to a very limited purpose and does not have many touchpoints with anything else.

Security boundaries:

• does not read/write to/from disk
• does not interact with the network
• does not leave anything in memory after it exits
• does not access (read/write) UEFI variables
• does not execute any UEFI drivers/executables
• does interact with USB devices

It has one purpose: tell the USB keyboard when system is in UEFI so that hotkeys can be realiably detected, regardless of user configuration.