🔒 TKey Integration: Unlocking Encrypted Disks

A new series in Concept introduces the complete logic and UI enhancements required to use a TKey to unlock an encrypted disk (like a LUKS partition) before booting an operating system.

1. The TKey Unlock Flow

The TKey unlock process is complex because it involves iterative communication with the external hardware and handling scenarios like the TKey being in the wrong mode:

• State Machine: The series implements a simple state machine (using enum unlock_state) to manage the entire TKey process. This allows the UI to remain responsive while waiting for user input, TKey removal, TKey insertion, or the app loading process .
• App Loading: The user’s passphrase is used as the User-Supplied Secret (USS) to load a signing app onto the TKey. This is done incrementally (tkey_load_next) on each UI poll to prevent the UI from freezing.
• Key Derivation: Once the app is loaded, the TKey’s public key is used to derive the disk encryption key (via SHA256 hashing), which is then used to unlock the LUKS partition.

2. UI and UX Enhancements

The user interface has been significantly upgraded to support this secure flow:

• Visual Indicators: The series adds a lock image which appears next to any encrypted OS entry in the Bootctl UI, providing immediate visual feedback.
• Passphrase Prompt: A dedicated textline object is provided for the user to enter their passphrase/USS. The series ensures this text renders as asterisks (by setting the SCENEOF_PASSWORD flag) for security.
• User Messaging: The UI is enhanced to display dynamic messages to the user:
  • “Unlocking…” or “Preparing TKey… 50%” (progress updates during app load).
  • Error messages like “Incorrect passphrase.”
  • Hardware prompts like “Please remove TKey” or “Please insert TKey.”
• Autonomy: The series provides functions (bc_ui_show_pass, bc_ui_get_pass, etc.) to allow the core logic to control the visibility and content of the passphrase and message fields.

3. Stability and Testing

• LUKS2 Support: The logic is updated to ensure compatibility with LUKS2 partitions, which is crucial for modern Linux distributions.
• TKey Correction: A fix is included in the TKey driver logic to correctly handle the position and use of the USS hash during app loading.
• Test Environment: The series enables the Bootctl tests and includes configuration to use a TKey emulator within the Sandbox environment, ensuring the new TKey logic remains functional in the future.
• luks command enhancement: The luks unlock command gains a new -p flag, allowing a pre-derived master key to be passed, which is useful for testing or integration with external key management systems.

This series moves U-Boot’s Bootctl from simple boot selection toward a feature-rich, hardware-backed security manager, making it a viable candidate for handling encrypted system boots.