From: Simon Glass <simon.glass@canonical.com> Add comprehensive documentation for TKey-based full disk encryption: - doc/usage/tkey-fde.rst: Main documentation covering the TKey FDE workflow, key derivation process, U-Boot integration, the tkey-fde-key.py script usage, creating test images, troubleshooting, and security considerations - Add cross-references from related documentation pages including blkmap, bootflow, luks, and tkey command references - Update luks.rst with a section on hardware-backed key derivation Co-developed-by: Claude <noreply@anthropic.com> Signed-off-by: Simon Glass <simon.glass@canonical.com> --- doc/usage/blkmap.rst | 24 ++ doc/usage/cmd/blkmap.rst | 2 + doc/usage/cmd/bootflow.rst | 25 ++ doc/usage/cmd/luks.rst | 2 + doc/usage/cmd/tkey.rst | 2 + doc/usage/index.rst | 1 + doc/usage/luks.rst | 19 +- doc/usage/tkey-fde.rst | 585 +++++++++++++++++++++++++++++++++++++ 8 files changed, 656 insertions(+), 4 deletions(-) create mode 100644 doc/usage/tkey-fde.rst diff --git a/doc/usage/blkmap.rst b/doc/usage/blkmap.rst index e9b3cfeaaa1..b6d3fae7aff 100644 --- a/doc/usage/blkmap.rst +++ b/doc/usage/blkmap.rst @@ -110,7 +110,31 @@ Now we can access the filesystem: blkmap get sq dev devnum load blkmap ${devnum} ${loadaddr} /etc/version + +Example: Accessing LUKS-encrypted partitions +--------------------------------------------- + +When LUKS-encrypted partitions are unlocked, U-Boot automatically creates +blkmap devices that provide on-the-fly decryption. This allows transparent +access to encrypted filesystems. + +For example, after unlocking a LUKS partition:: + + luks unlock mmc 0:2 mypassword + +A blkmap device is created (e.g., ``blkmap 0``) that can be used like any +other block device:: + + ls blkmap 0 / + load blkmap 0 ${kernel_addr_r} /boot/vmlinuz + +For more information on LUKS encryption, including hardware-backed key +derivation with TKey devices, see :doc:`luks` and :doc:`tkey-fde`. + + See also -------- * :doc:`/usage/cmd/blkmap` +* :doc:`luks` - LUKS encryption support +* :doc:`tkey-fde` - TKey full disk encryption diff --git a/doc/usage/cmd/blkmap.rst b/doc/usage/cmd/blkmap.rst index aaa4cd403c0..564898abd6c 100644 --- a/doc/usage/cmd/blkmap.rst +++ b/doc/usage/cmd/blkmap.rst @@ -321,3 +321,5 @@ See Also -------- * :doc:`../blkmap` - Blkmap device documentation and examples +* :doc:`../luks` - LUKS encryption support (uses blkmap for decrypted access) +* :doc:`../tkey-fde` - TKey full disk encryption diff --git a/doc/usage/cmd/bootflow.rst b/doc/usage/cmd/bootflow.rst index 938e5c79903..4082aa3c198 100644 --- a/doc/usage/cmd/bootflow.rst +++ b/doc/usage/cmd/bootflow.rst @@ -751,4 +751,29 @@ else 1. For other subcommands, the return value $? is always 0 (true). +Encrypted Partitions +-------------------- + +Bootflow scanning automatically detects and handles LUKS-encrypted partitions. +When an encrypted partition is detected during scanning, U-Boot will: + +1. Detect the LUKS encryption and display an indicator in the bootflow list +2. Prompt the user for a password when attempting to boot +3. Attempt to unlock the partition using the provided password +4. If a TKey device is present, use hardware-backed key derivation for enhanced + security + +For detailed information on LUKS encryption and TKey-based full disk encryption, +see :doc:`../luks` and :doc:`../tkey-fde`. + + +See also +-------- + +* :doc:`../luks` - LUKS encryption support +* :doc:`../tkey-fde` - TKey full disk encryption +* :doc:`bootdev` - Boot device documentation +* :doc:`/develop/bootstd/index` - Standard boot documentation + + .. BootflowStates_: diff --git a/doc/usage/cmd/luks.rst b/doc/usage/cmd/luks.rst index 1a9cba875ce..15a87ea12cd 100644 --- a/doc/usage/cmd/luks.rst +++ b/doc/usage/cmd/luks.rst @@ -307,6 +307,8 @@ See also -------- * :doc:`../luks` - Comprehensive LUKS feature documentation +* :doc:`../tkey-fde` - TKey full disk encryption with hardware-backed keys * :doc:`blkmap` - Blkmap device documentation +* :doc:`tkey` - TKey command reference * cryptsetup project: https://gitlab.com/cryptsetup/cryptsetup * LUKS on-disk format specifications: https://gitlab.com/cryptsetup/cryptsetup/-/wikis/home diff --git a/doc/usage/cmd/tkey.rst b/doc/usage/cmd/tkey.rst index b7d138f7307..56da02f4b5c 100644 --- a/doc/usage/cmd/tkey.rst +++ b/doc/usage/cmd/tkey.rst @@ -260,4 +260,6 @@ requires a TKey driver to be configured (USB or serial). See also -------- +* :doc:`../tkey-fde` - TKey full disk encryption guide +* :doc:`luks` - LUKS command reference * `Tillitis TKey documentation <https://tillitis.se/>`_ diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 8913c0a4f9b..bee7884a066 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -12,6 +12,7 @@ Use U-Boot fdt_overlays fit/index luks + tkey-fde netconsole partitions cmdline diff --git a/doc/usage/luks.rst b/doc/usage/luks.rst index db8558ffb56..36d66081dc1 100644 --- a/doc/usage/luks.rst +++ b/doc/usage/luks.rst @@ -422,8 +422,7 @@ See ``test/py/tests/fs_helper.py`` for the ``FsHelper`` class: # Create LUKS2 encrypted filesystem with Argon2id with FsHelper(config, 'ext4', 30, 'test', - part_mb=60, - encrypt_passphrase='mypassword', + part_mb=60, passphrase='mypassword', luks_kdf='argon2id') as fsh: # Add files to fsh.srcdir with open(os.path.join(fsh.srcdir, 'hello.txt'), 'w') as f: @@ -434,8 +433,7 @@ See ``test/py/tests/fs_helper.py`` for the ``FsHelper`` class: # Create LUKS1 encrypted filesystem with FsHelper(config, 'ext4', 30, 'test', - part_mb=60, - encrypt_passphrase='mypassword', + part_mb=60, passphrase='mypassword', luks_version=1) as fsh: # Add files to fsh.srcdir with open(os.path.join(fsh.srcdir, 'hello.txt'), 'w') as f: @@ -472,6 +470,16 @@ CONFIG_SHA512 CONFIG_ARGON2 Enable Argon2 key derivation support (optional, for modern LUKS2) +Hardware-Backed Key Derivation +------------------------------- + +For enhanced security, LUKS partitions can be unlocked using hardware security +tokens like the Tillitis TKey. Instead of relying solely on a password, the +encryption key is derived from both the password and the device's unique +hardware identifier. + +See :doc:`tkey-fde` for complete details on using TKey for full disk encryption. + Limitations ----------- @@ -551,8 +559,11 @@ See ``test/boot/luks.c`` for tests: See Also -------- +* :doc:`tkey-fde` - TKey full disk encryption documentation * :doc:`cmd/luks` - LUKS command reference * :doc:`cmd/blkmap` - Blkmap command reference +* :doc:`cmd/tkey` - TKey command reference * :doc:`blkmap` - Blkmap device documentation * ``test/py/tests/fs_helper.py`` - Filesystem helper for creating test images +* ``scripts/tkey_fde_key.py`` - TKey key derivation tool * Linux ``cryptsetup`` documentation for LUKS disk format specification diff --git a/doc/usage/tkey-fde.rst b/doc/usage/tkey-fde.rst new file mode 100644 index 00000000000..3452dc79540 --- /dev/null +++ b/doc/usage/tkey-fde.rst @@ -0,0 +1,585 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +TKey Full Disk Encryption +========================== + +Overview +-------- + +U-Boot supports using `Tillitis TKey <https://tillitis.se/>`_ hardware-security +tokens to unlock LUKS-encrypted partitions. This provides hardware-backed +full-disk encryption (FDE) where the encryption key is derived from two pieces +of information: + +* A user password/passphrase (USS - User Supplied Secret) +* The TKey's internal Unique Device Identifier (UDI) + +The same password on the same TKey always produces the same encryption key, +making it suitable for unlocking encrypted root filesystems at boot time. + +Note: Despite its name, FDE generally refers to the encryption of a single +partition on a disk, rather than an entire disk. + +**Key Features:** + +* Hardware-backed key derivation using TKey security token +* Compatible with standard LUKS1 and LUKS2 encrypted partitions +* Automatic unlock during boot flow detection +* Test infrastructure for creating encrypted disk images +* Python tools for key generation and disk encryption + +How It Works +------------ + +TKey Key Derivation Process +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The TKey derives encryption keys through this process: + +1. **Load Signer App**: The TKey firmware loads the signer application with + your password (USS) +2. **Generate Key Pair**: The signer app combines the USS with the device's UDI + to generate an Ed25519 key pair +3. **Derive Disk Key**: The public key is hashed with SHA-256 to produce a + 32-byte encryption key +4. **Decrypt Partition**: The key is used to unlock the LUKS-encrypted + partition + +This means: + +* The same password always produces the same key (deterministic) +* Different passwords produce completely different keys +* The physical TKey device is required (UDI is device-specific) +* No key material is stored on disk - only derived when needed + + +U-Boot Integration +~~~~~~~~~~~~~~~~~~ + +When U-Boot detects a LUKS-encrypted partition during bootflow booting: + +1. Prompts the user for their password +2. Detects if a TKey device is present +3. Loads the TKey signer app with the password +4. Derives the encryption key from the TKey +5. Attempts to unlock the LUKS partition +6. Creates a blkmap device for accessing decrypted data +7. Continues with normal boot process + + +Tools and Workflow +------------------ + +The ``scripts/tkey_fde_key.py`` Script +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This Python script handles TKey key derivation and disk encryption operations. + +**Basic Usage - Generate a key:** + +:: + + # Generate key interactively (prompts for password) + $ ./scripts/tkey_fde_key.py + + # Generate key from password file + $ echo "mypassword" > passfile + $ ./scripts/tkey_fde_key.py -p passfile -o diskkey.bin --binary + + # Generate key from stdin + $ echo "mypassword" | ./scripts/tkey_fde_key.py -p - --binary + +**Encrypting a Disk Image:** + +:: + + # Create a disk image + $ dd if=/dev/zero of=rootfs.img bs=1M count=1000 + + # Encrypt the entire disk with LUKS + $ ./scripts/tkey_fde_key.py -e rootfs.img -p passfile + + # Encrypt a specific partition + $ ./scripts/tkey_fde_key.py -e disk.img -P 2 -p passfile + +**Opening an Encrypted Disk:** + +:: + + # Open encrypted disk (creates /dev/mapper/tkey-disk) + $ ./scripts/tkey_fde_key.py -O rootfs.img -p passfile + + # Mount the decrypted filesystem + $ sudo mount /dev/mapper/tkey-disk /mnt + + # When done, unmount and close + $ sudo umount /mnt + $ sudo cryptsetup close tkey-disk + +**Advanced Options:** + +:: + + # Save both encrypted disk and backup key file + $ ./scripts/tkey_fde_key.py -e disk.img -p passfile -o backup.key + + # Use verbose output to see what's happening + $ ./scripts/tkey_fde_key.py -e disk.img -p passfile --verbose + + # Use debug mode for troubleshooting + $ ./scripts/tkey_fde_key.py --debug -e disk.img -p passfile + + +Creating Test Images +-------------------- + +Test Disk Images +~~~~~~~~~~~~~~~~ + +The U-Boot test infrastructure creates several LUKS-encrypted test images: + +* ``mmc11.img`` - LUKS1 encrypted Ubuntu image +* ``mmc12.img`` - LUKS2 encrypted Ubuntu image with Argon2id KDF +* ``mmc13.img`` - LUKS2 encrypted Ubuntu image for TKey testing +* ``mmc14.img`` - LUKS2 encrypted image with pre-derived master key + +By default, ``mmc13.img`` is encrypted with a key derived from the TKey +emulator's deterministic public key. This allows testing without physical +hardware. + +Using override.bin for Physical TKey Testing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To test with a physical TKey device instead of the emulator, create an +``override.bin`` file containing the TKey-derived disk key: + +:: + + # Generate override.bin from your physical TKey with password "test" + $ echo "test" | ./scripts/tkey_fde_key.py -p - -o override.bin --binary + + # Regenerate test images with your TKey's key + $ ./test/py/test.py -B sandbox --build-dir /tmp/b/sandbox \ + --build -k test_ut_dm_init_bootstd + + # Test unlocking mmc13 with your physical TKey + $ /tmp/b/sandbox/u-boot -T -c \ + "tkey connect sandbox_tkey; sb devon mmc13; luks unlock -t mmc d:2 test" + +When ``override.bin`` exists in the source directory, the test infrastructure +uses it instead of the emulator's key to encrypt ``mmc13.img``. This allows +you to test the full TKey unlock flow with real hardware. + +To switch back to emulator testing, simply remove the override file: + +:: + + $ rm override.bin + $ ./test/py/test.py -B sandbox --build-dir /tmp/b/sandbox \ + --build -k test_ut_dm_init_bootstd + +Using the Python Test Infrastructure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The test infrastructure in ``test/py/tests/test_ut.py`` handles TKey key +generation automatically: + +:: + + def test_ut_dm_init_bootstd(u_boot_config, u_boot_log): + """Initialize data for bootflow tests with TKey encryption""" + + # Check for override key file (for physical TKey testing) + override_keyfile = os.path.join(u_boot_config.source_dir, 'override.bin') + if os.path.exists(override_keyfile): + keyfile = override_keyfile + u_boot_log.action(f'Using override TKey key: {keyfile}') + else: + # Generate key matching TKey emulator's deterministic pubkey + pubkey = bytes([0x50 + (i & 0xf) for i in range(32)]) + disk_key = hashlib.sha256(pubkey.hex().encode()).digest() + keyfile = os.path.join(u_boot_config.persistent_data_dir, + 'tkey_emul.key') + with open(keyfile, 'wb') as f: + f.write(disk_key) + + # Create LUKS2 encrypted image for TKey testing + setup_ubuntu_image(u_boot_config, u_boot_log, 13, 'mmc', + use_fde=2, luks_kdf='argon2id', + encrypt_keyfile=keyfile) + +**Helper Class Usage:** + +See ``test/py/tests/fs_helper.py`` for the ``FsHelper`` class: + +:: + + from fs_helper import FsHelper, DiskHelper + + # Create LUKS2 encrypted filesystem with TKey key file + with FsHelper(config, 'ext4', 30, 'test', + part_mb=60, + encrypt_keyfile='/path/to/tkey-derived-key.bin') as fsh: + fsh.setup() + # Add files to fsh.srcdir + with open(os.path.join(fsh.srcdir, 'hello.txt'), 'w') as f: + f.write('Hello from TKey FDE!\n') + + # Create encrypted filesystem + fsh.mk_fs() + +Step-by-Step Workflow +---------------------- + +Complete Example: Testing TKey FDE with mmc13 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**1. Create Test Disk Images** + +Run the test infrastructure to create encrypted images: + +:: + + $ ./test/py/test.py -B sandbox --build-dir /tmp/b/sandbox \ + --build -k test_ut_dm_init_bootstd + +This creates ``mmc13.img`` (LUKS2 with Argon2id) encrypted with the TKey +emulator's key. + +**2. Test Unlocking with TKey Emulator** + +Run U-Boot sandbox and test the unlock process with the emulator: + +:: + + $ /tmp/b/sandbox/u-boot -T -c \ + "tkey connect tkey-emul; sb devon mmc13; luks unlock -t mmc d:2 test" + +**Expected Output:** + +:: + + Connected to TKey device + Device 'mmc13' enabled + Unlocking LUKS2 partition... + Using TKey for disk encryption key + Loading TKey signer app (6d78 bytes) with USS... + TKey public key: 50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f + 50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f + TKey disk key derived successfully + TKey derived disk key: e9 b0 59 92 68 ff 8b 08 3e f8 0d bd 04 be 20 7c + e9 a1 9a 60 a8 88 cc b3 fe 93 71 0a 0a 70 a3 4e + Unlocked LUKS partition as blkmap device 'luks-mmc-d:2' + +**3. Test with Physical TKey** + +To test with a real TKey device: + +:: + + # Generate override.bin from your physical TKey with password "test" + $ echo "test" | ./scripts/tkey_fde_key.py -p - -o override.bin --binary -f -v + Reading password from stdin... + Password length: 4, repr: 'test' + TKey detected via USB enumeration + ... + Ed25519 public key (hex): df4faa680d9fd79079cc572c1f84fb3fa59ab904dad652e90a22e5b672a67eb1 + Derived disk key (hex): 1546bdaf99e9ed9867d83ae69062c9da3202a617584a35ee4ae38672ec775a7f + Key saved to override.bin + + # Regenerate mmc13.img with your TKey's key + $ ./test/py/test.py -B sandbox --build-dir /tmp/b/sandbox \ + --build -k test_ut_dm_init_bootstd + + # Test unlocking with physical TKey (ensure TKey is plugged in) + $ /tmp/b/sandbox/u-boot -T -c "sb devon mmc13; luks unlock -t mmc d:2 test" -P + +**Expected Output with Physical TKey:** + +:: + + Device 'mmc13' enabled + Unlocking LUKS2 partition... + Using TKey for disk encryption key + Loading TKey signer app (6d78 bytes) with USS... + TKey public key: df 4f aa 68 0d 9f d7 90 79 cc 57 2c 1f 84 fb 3f + a5 9a b9 04 da d6 52 e9 0a 22 e5 b6 72 a6 7e b1 + TKey disk key derived successfully + TKey derived disk key: 15 46 bd af 99 e9 ed 98 67 d8 3a e6 90 62 c9 da + 32 02 a6 17 58 4a 35 ee 4a e3 86 72 ec 77 5a 7f + Unlocked LUKS partition as blkmap device 'luks-mmc-d:2' + +**4. Verify Encryption** + +You can verify the disk is encrypted by checking with cryptsetup: + +:: + + # Extract partition 2 from the disk image + $ dd if=mmc13.img bs=512 skip=38912 count=122880 of=mmc13_part2.img + + # Check LUKS header + $ cryptsetup luksDump mmc13_part2.img + LUKS header information + Version: 2 + ... + + # Test unlock with the TKey emulator key (when no override.bin exists) + # First generate the emulator's key + $ python3 -c " + import hashlib + pubkey = bytes([0x50 + (i & 0xf) for i in range(32)]) + key = hashlib.sha256(pubkey.hex().encode()).digest() + open('emul.key', 'wb').write(key) + " + $ sudo cryptsetup open mmc13_part2.img test-luks --key-file=emul.key + $ ls /dev/mapper/test-luks + /dev/mapper/test-luks + $ sudo cryptsetup close test-luks + +Troubleshooting +--------------- + +Key Mismatch Errors +~~~~~~~~~~~~~~~~~~~ + +**Problem:** U-Boot shows "Failed to unlock LUKS partition" + +:: + + LUKS1: Keyslot 0 failed with error -13 + Failed to unlock LUKS1 with binary passphrase (err=-2) + Failed to unlock LUKS partition (err=-13: Permission denied) + +**Cause:** The disk was encrypted with a different key than U-Boot is deriving. + +**Solutions:** + +1. **Verify you're using the correct password:** Make sure you enter the same + password in U-Boot that was used to generate the key file. + +2. **Regenerate the key and verify it matches:** + + :: + + # Generate key again with same password + $ ./scripts/tkey_fde_key.py -p mykey.txt -o test-key.bin --binary + + # Compare with original + $ diff mykey test-key.bin + + # If different, TKey may have been in different state + +3. **Recreate disk images with the correct key:** If U-Boot consistently + derives a different key than what was used for encryption, capture the key + U-Boot derives and use that to encrypt the disk: + + :: + + # Run U-Boot and note the "Binary pass" hex values from debug output + # Then recreate the key file with those values + $ python3 << 'EOF' + key_hex = "10f1132e6c27e6e8...d29b6b8a" # from U-Boot output + with open('mykey', 'wb') as f: + f.write(bytes.fromhex(key_hex)) + EOF + + # Recreate disk images with this key + $ rm mmc11.img mmc12.img + $ ./test/py/test.py -B sandbox --build-dir /tmp/b/sandbox \ + -k test_ut_dm_init_bootstd + +TKey Not Detected +~~~~~~~~~~~~~~~~~ + +**Problem:** U-Boot doesn't detect the TKey device + +**Solutions:** + +* Ensure TKey is plugged in before starting U-Boot +* Check USB device is accessible: ``ls /dev/ttyACM*`` +* Try replugging the TKey device +* For sandbox, ensure ``sandbox,device-path`` is set correctly in device tree + +TKey App Already Loaded +~~~~~~~~~~~~~~~~~~~~~~~~ + +**Problem:** TKey is in app mode instead of firmware mode + +**Solution:** Remove and reinsert the TKey. The device must be in firmware mode +to load the signer app. + +Configuration +------------- + +Kconfig Options +~~~~~~~~~~~~~~~ + +To enable TKey FDE support in U-Boot: + +:: + + CONFIG_CMD_TKEY=y # TKey command + CONFIG_TKEY_DRIVER=y # TKey device driver + CONFIG_CMD_LUKS=y # LUKS command + CONFIG_BLK_LUKS=y # LUKS block device support + CONFIG_BLKMAP=y # Block device mapping + CONFIG_BOOTCTL=y # Boot control with unlock support + CONFIG_BOOTCTL_LOGIC=y # Boot control unlock logic + CONFIG_ARGON2=y # For LUKS2 Argon2id support (optional) + +Device Tree Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~ + +For sandbox testing, the TKey is configured in ``arch/sandbox/dts/test.dts``: + +:: + + tkey { + compatible = "sandbox,tkey"; + sandbox,device-path = "/dev/ttyACM0"; + }; + +For real hardware, configure the USB serial device path appropriately. + +Security Considerations +----------------------- + +Key Storage +~~~~~~~~~~~ + +* The TKey-derived key should **never be stored permanently** on disk +* Only temporary key files (like ``mykey``) used during testing should exist +* In production, keys should be derived fresh each boot from TKey + password +* The ``mykey`` file is for **testing only** and should be kept secure + +Password Security +~~~~~~~~~~~~~~~~~ + +* Use a strong password (at least 16 characters recommended) +* Different passwords produce completely different encryption keys +* The TKey's UDI adds additional entropy to the key derivation +* Consider using a hardware security token for additional protection + +Hardware Security +~~~~~~~~~~~~~~~~~ + +* Physical access to the TKey is required to derive keys +* The TKey's UDI is unique per device - keys cannot be derived without it +* If the TKey is lost, encrypted data cannot be recovered +* Consider keeping a backup TKey or traditional key recovery mechanism + +Memory Security +~~~~~~~~~~~~~~~ + +* Keys are held in memory while the device is unlocked +* Memory is not securely erased on warm reboot +* This is acceptable for boot-time use but not for long-term key storage + + +Comparison with Traditional LUKS +--------------------------------- + +**Traditional LUKS (Password Only):** + +* Encryption key derived only from password +* Vulnerable to offline password cracking attacks +* No hardware requirement - same password works anywhere + +**TKey-Enhanced LUKS:** + +* Encryption key derived from password + TKey UDI +* Requires physical TKey device to derive key +* Resistant to offline password cracking (attacker needs both password and + TKey) +* Same password + same TKey always produces same key +* Different TKey devices produce different keys even with same password + +Example Use Case: Secure Boot +------------------------------ + +A typical secure boot workflow with TKey FDE: + +1. **System Powers On** + + * U-Boot starts and scans for boot devices + * Finds LUKS-encrypted root partition + +2. **User Authentication** + + * U-Boot prompts user for password + * User inserts TKey device + * User enters password + +3. **Key Derivation** + + * U-Boot loads TKey signer app with password + * TKey derives encryption key from password + UDI + * Returns 32-byte encryption key to U-Boot + +4. **Partition Unlock** + + * U-Boot attempts to unlock LUKS partition + * If successful, creates blkmap device + * Encrypted data is accessible as standard block device + +5. **Boot Continues** + + * U-Boot loads kernel from unlocked partition + * System boots into encrypted root filesystem + +Testing +------- + +Unit Tests +~~~~~~~~~~ + +Run the bootctl TKey unlock tests: + +:: + + $ ./test/py/test.py -B sandbox --build-dir /tmp/b/sandbox \ + -k bootctl_logic_tkey + + +Manual Testing +~~~~~~~~~~~~~~ + +Test mmc13 with the TKey emulator: + +:: + + # 1. Build sandbox and create test images + $ crosfw sandbox -L + $ ./test/py/test.py -B sandbox --build-dir /tmp/b/sandbox \ + --build -k test_ut_dm_init_bootstd + + # 2. Test unlocking mmc13 with TKey emulator + $ /tmp/b/sandbox/u-boot -T -c \ + "tkey connect tkey-emul; sb devon mmc13; luks unlock -t mmc d:2 test" + +Test mmc13 with a physical TKey: + +:: + + # 1. Generate override.bin with your TKey and password "test" + $ echo "test" | ./scripts/tkey_fde_key.py -p - -o override.bin --binary + + # 2. Regenerate test images + $ ./test/py/test.py -B sandbox --build-dir /tmp/b/sandbox \ + --build -k test_ut_dm_init_bootstd + + # 3. Test unlocking with physical TKey + $ /tmp/b/sandbox/u-boot -T -c \ + "tkey connect sandbox_tkey; sb devon mmc13; luks unlock -t mmc d:2 test" + +See Also +-------- + +* :doc:`luks` - LUKS encryption documentation +* :doc:`cmd/luks` - LUKS command reference +* :doc:`cmd/tkey` - TKey command reference +* :doc:`cmd/blkmap` - Blkmap device mapping +* ``scripts/tkey_fde_key.py`` - TKey key derivation tool +* ``test/py/tests/fs_helper.py`` - Filesystem test helpers +* `Tillitis TKey Documentation <https://tillitis.se/>`_ -- 2.43.0