@@ -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
@@ -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
@@ -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_:
@@ -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
@@ -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/>`_
@@ -12,6 +12,7 @@ Use U-Boot
fdt_overlays
fit/index
luks
+ tkey-fde
netconsole
partitions
cmdline
@@ -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
new file mode 100644
@@ -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/>`_