🔑 Full Circle: Completing TKey Hardware-Backed LUKS Unlock

This final series in Concept closes out the complete implementation of TKey hardware-backed full disk encryption (FDE) in U-Boot.

The previous series established the core logic and UI flow. This final work wraps up the effort by providing end-to-end testing, a useful Python tool for key management on the host, along with documentation, making the feature ready for real-world secure-boot environments.

🛠️ The Final Pieces of the Puzzle

This series of 7 patches focuses on robust testing, external utility, and documentation.

1. Host-Side Key Management Tool

The core of this series is the new script, scripts/tkey_fde_key.py.

• Key Derivation: This script allows users on their host machine to use a physical TKey and a passphrase to derive the exact same disk encryption key that U-Boot derives at boot time.
• Disk Operations: It is an all-in-one utility that can then use the derived key to:
  • Encrypt a disk image (or partition) with LUKS.
  • Open/Unlock an already encrypted disk image for host access.
  • This capability is essential for creating encrypted root filesystems that U-Boot can later unlock using the TKey.

2. Comprehensive Testing & Infrastructure

To ensure this complex hardware-backed flow is reliable, the test infrastructure has been significantly upgraded:

• Full TKey Unlock Test: A major test, bootctl_logic_tkey, validates the entire TKey unlock state machine: passphrase entry, handling TKey removal and re-insertion prompts, app loading, key derivation, and final LUKS partition unlock.
• New Test Devices: The series adds two new disk images to the sandbox:
  • mmc13: A LUKS2-encrypted disk designed specifically for TKey-based unlock.
  • mmc14: A LUKS2-encrypted disk for testing the pre-derived master key path (via the -p flag in luks unlock), ensuring maximum flexibility.
• Keyfile Support: The Python filesystem helper is updated to support key files (instead of only passphrases) and the ability to specify a raw master key. This allows the automated tests to encrypt disks using the deterministic key generated by the TKey emulator.

3. Complete Documentation

The final piece is the doc/usage/tkey-fde.rst guide, which ties the entire workflow together.

• Workflow Explained: This new documentation covers the entire TKey FDE workflow, from how the key is derived from the User-Supplied Secret (USS) and the TKey’s Unique Device Identifier (UDI), to using the tkey_fde_key.py script and configuring U-Boot.
• Physical TKey Testing: It includes a guide on how to use a real TKey for testing by generating an override.bin key, allowing developers to switch seamlessly between the emulator and physical hardware.

What’s next?

This work has been an interesting expedition into LUKS and hardware-backed security. While it is complete from the U-Boot side, there are a few loose ends which could be looked at in future. For example, it would be useful to communicate the unlock key to Linux’s the ramdisk environment, so it doesn’t need to do another unlock (and prompt the user) on startup.

In any case, U-Boot now includes a complete, robust, and well-documented solution for hardware-backed full disk encryption, a significant step forward in the area of security.