From: Simon Glass <sjg@chromium.org> Provide a function which can detect a LUKS partition. Add a test, using mmc11 Co-developed-by: Claude <noreply@anthropic.com> Signed-off-by: Simon Glass <sjg@chromium.org> --- MAINTAINERS | 1 + doc/usage/cmd/luks.rst | 1 + doc/usage/index.rst | 1 + doc/usage/luks.rst | 340 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 343 insertions(+) create mode 100644 doc/usage/luks.rst diff --git a/MAINTAINERS b/MAINTAINERS index a0374df1c4d..83f7a2ae1e9 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1295,6 +1295,7 @@ S: Maintained T: git https://concept.u-boot.org/u-boot/u-boot.git F: cmd/luks.c F: doc/usage/cmd/luks.rst +F: doc/usage/luks.rst F: drivers/block/luks.c F: include/luks.h F: include/json.h diff --git a/doc/usage/cmd/luks.rst b/doc/usage/cmd/luks.rst index 8dbcb8549c7..6c262e66200 100644 --- a/doc/usage/cmd/luks.rst +++ b/doc/usage/cmd/luks.rst @@ -248,6 +248,7 @@ if unlock failed (wrong passphrase, unsupported format, etc.). See also -------- +* :doc:`../luks` - Comprehensive LUKS feature documentation * :doc:`blkmap` - Blkmap device documentation * cryptsetup project: https://gitlab.com/cryptsetup/cryptsetup * LUKS on-disk format specifications: https://gitlab.com/cryptsetup/cryptsetup/-/wikis/home diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 2bb01211227..e8dbabfa9d2 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -11,6 +11,7 @@ Use U-Boot environment fdt_overlays fit/index + luks netconsole partitions cmdline diff --git a/doc/usage/luks.rst b/doc/usage/luks.rst new file mode 100644 index 00000000000..a87abe140db --- /dev/null +++ b/doc/usage/luks.rst @@ -0,0 +1,340 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +LUKS (Linux Unified Key Setup) +=============================== + +Overview +-------- + +U-Boot provides support for accessing LUKS-encrypted partitions through the +``luks`` command and the blkmap device infrastructure. This allows U-Boot to +unlock and read data from LUKS1-encrypted block devices. + +LUKS is a standard for disk encryption that stores encryption metadata in a +header on the encrypted device. It supports multiple key slots, allowing +different passphrases to unlock the same encrypted data. + +Currently, U-Boot supports: + +* LUKS version 1 (LUKS1) +* AES-256-CBC encryption with ESSIV (Encrypted Salt-Sector IV) mode +* Passphrase-based unlocking via PBKDF2 key derivation +* Reading ext4 and other filesystems from unlocked devices + +Supported Cipher Modes +----------------------- + +The following LUKS1 cipher configurations are supported: + +* **Cipher**: aes +* **Mode**: cbc-essiv:sha256 +* **Key sizes**: 128-bit, 192-bit, 256-bit +* **Hash**: sha256 (for PBKDF2) + +Commands +-------- + +See the :doc:`cmd/luks` for full details. + +luks detect +~~~~~~~~~~~ + +Detect whether a partition is LUKS-encrypted:: + + luks detect <interface> <dev[:part]> + +Example:: + + => luks detect mmc 0:2 + LUKS1 encrypted partition detected + +This command checks for the LUKS magic bytes and validates the header structure. + +luks info +~~~~~~~~~ + +Display information about a LUKS partition:: + + luks info <interface> <dev[:part]> + +Example:: + + => luks info mmc 0:2 + Version: 1 + Cipher name: aes + Cipher mode: cbc-essiv:sha256 + Hash spec: sha256 + Payload offset: 4096 + Key bytes: 32 + +This shows the LUKS header metadata including encryption parameters and the +offset to the encrypted data payload. + +luks unlock +~~~~~~~~~~~ + +Unlock a LUKS partition with a passphrase:: + + luks unlock <interface> <dev[:part]> <passphrase> + +Example:: + + => luks unlock mmc 0:2 mypassword + Trying to unlock LUKS partition... + Key size: 32 bytes + Trying key slot 0... + Successfully unlocked with key slot 0! + Unlocked LUKS partition as blkmap device 'luks-mmc-0:2' + Access decrypted data via: blkmap 0 + +This command: + +1. Reads the LUKS header from the specified partition +2. Derives the encryption key from the passphrase using PBKDF2 +3. Attempts to unlock each active key slot +4. Verifies the unlocked key against the master key digest +5. Creates a blkmap device that provides on-the-fly decryption + +Accessing Unlocked Data +------------------------ + +After unlocking, the decrypted data is accessible through a blkmap device. +The device number is shown in the unlock output (typically ``blkmap 0``). + +Listing Files +~~~~~~~~~~~~~ + +Use standard filesystem commands to access the unlocked device:: + + => ls blkmap 0 / + ./ + ../ + lost+found/ + 221 README.md + 17 hello.txt + subdir/ + 20 test.txt + + 3 file(s), 4 dir(s) + +Reading Files +~~~~~~~~~~~~~ + +Read file contents:: + + => cat blkmap 0 /hello.txt + Hello from LUKS! + +Loading Files to Memory +~~~~~~~~~~~~~~~~~~~~~~~~ + +Load files for further processing:: + + => ext4load blkmap 0 ${loadaddr} /boot/vmlinuz + 5242880 bytes read in 123 ms (40.6 MiB/s) + +Using with Boot Flows +~~~~~~~~~~~~~~~~~~~~~ + +LUKS-encrypted partitions can be integrated into boot flows:: + + => bootflow scan + => bootflow list + +The bootflow will detect filesystems on unlocked blkmap devices. + +Implementation Details +---------------------- + +Key Derivation +~~~~~~~~~~~~~~ + +LUKS uses PBKDF2 (Password-Based Key Derivation Function 2) to derive +encryption keys from passphrases. The process: + +1. Passphrase + salt → PBKDF2 → derived key +2. Derived key decrypts the AF-split key material +3. AF-merge combines the split key material → master key +4. Master key digest is verified against stored value + +Anti-Forensic (AF) Splitter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +LUKS uses an anti-forensic information splitter to protect key material: + +* The master key is split into 4000 stripes +* Each stripe is XORed and hashed with a counter +* All stripes must be recovered to reconstruct the key +* This makes recovery from partial key material extremely difficult + +ESSIV Mode +~~~~~~~~~~ + +ESSIV (Encrypted Salt-Sector IV) generates unique initialization vectors +for each encrypted sector: + +1. ESSIV key = SHA256(master_key) +2. For each sector: IV = AES_encrypt(sector_number, ESSIV_key) +3. Data is encrypted: ciphertext = AES-CBC-encrypt(plaintext, master_key, IV) + +This prevents watermarking attacks where identical plaintext blocks would +produce identical ciphertext blocks. + +Blkmap Device Mapping +~~~~~~~~~~~~~~~~~~~~~ + +When a LUKS partition is unlocked, U-Boot creates a blkmap device that: + +* Maps to the underlying encrypted device +* Performs on-the-fly AES-CBC decryption with ESSIV +* Presents decrypted data as a standard block device +* Supports whole-disk filesystems (no partition table required) + +The blkmap device number can be used with any U-Boot command that accepts +block device specifications. + +Creating LUKS Partitions for Testing +------------------------------------- + +Using cryptsetup on Linux:: + + # Create a 60MB file + $ dd if=/dev/zero of=test.img bs=1M count=60 + + # Format as LUKS1 + $ cryptsetup luksFormat --type luks1 \ + --cipher aes-cbc-essiv:sha256 \ + --key-size 256 \ + --hash sha256 \ + test.img + + # Open the LUKS device + $ cryptsetup open test.img testluks + + # Create filesystem + $ mkfs.ext4 /dev/mapper/testluks + + # Mount and add files + $ mount /dev/mapper/testluks /mnt + $ echo "Hello from LUKS!" > /mnt/hello.txt + $ umount /mnt + + # Close the LUKS device + $ cryptsetup close testluks + +Using Python with U-Boot Test Infrastructure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +See ``test/py/tests/fs_helper.py`` for the ``FsHelper`` class:: + + from fs_helper import FsHelper, DiskHelper + + # Create encrypted filesystem + with FsHelper(config, 'ext4', 30, 'test', + part_mb=60, + encrypt_passphrase='mypassword') as fsh: + # Add files to fsh.srcdir + with open(os.path.join(fsh.srcdir, 'hello.txt'), 'w') as f: + f.write('Hello from LUKS!\n') + + # Create encrypted filesystem + fsh.mk_fs() + +Configuration Options +--------------------- + +CONFIG_CMD_LUKS + Enable the ``luks`` command + +CONFIG_BLKMAP + Enable blkmap device support (required for LUKS unlock) + +CONFIG_AES + Enable AES encryption support + +CONFIG_SHA256 + Enable SHA-256 hashing support + +CONFIG_PBKDF2 + Enable PBKDF2 key derivation + +Limitations +----------- + +* Only LUKS1 is currently supported (LUKS2 not yet implemented) +* Only AES-CBC-ESSIV cipher mode is supported +* Only passphrase-based unlocking is supported (no key files) +* Unlocked devices are read-only (write support not yet implemented) +* Master key remains in memory after unlocking (not securely erased on exit) + +Security Considerations +----------------------- + +Passphrase Handling +~~~~~~~~~~~~~~~~~~~ + +* Passphrases are passed as command-line arguments +* They may be visible in command history +* Consider using environment variables or scripts to minimize exposure + +Memory Security +~~~~~~~~~~~~~~~ + +* Master keys are wiped from stack after use where possible +* Keys remain in blkmap device structure while device is active +* No secure memory protection or key erasure on warm reboot + +Intended Use Cases +~~~~~~~~~~~~~~~~~~ + +U-Boot's LUKS support is intended for: + +* Boot-time access to encrypted root filesystems +* Reading configuration from encrypted partitions +* Testing and development of encrypted disk support + +It is **not** a replacement for full disk encryption solutions in production +operating systems. + +Example Use Cases +----------------- + +Encrypted Root Filesystem +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Boot from an encrypted root partition:: + + => luks unlock mmc 0:2 ${rootfs_password} + => setenv bootargs root=/dev/blkmap0 rootfstype=ext4 + => ext4load blkmap 0 ${kernel_addr_r} /boot/vmlinuz + => ext4load blkmap 0 ${ramdisk_addr_r} /boot/initrd.img + => bootz ${kernel_addr_r} ${ramdisk_addr_r} ${fdt_addr_r} + +Encrypted Configuration Storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Read configuration from encrypted partition:: + + => luks unlock mmc 0:3 ${config_password} + => ext4load blkmap 0 ${loadaddr} /config/boot.conf + => env import -t ${loadaddr} ${filesize} + +Testing +------- + +See ``test/boot/luks.c`` for tests: + +* LUKS detection on encrypted and non-encrypted partitions +* LUKS header information parsing +* Successful unlocking with correct passphrase +* Rejection of incorrect passphrases +* Blkmap device creation and filesystem access + +See Also +-------- + +* :doc:`cmd/luks` - LUKS command reference +* :doc:`cmd/blkmap` - Blkmap command reference +* :doc:`blkmap` - Blkmap device documentation +* ``test/py/tests/fs_helper.py`` - Filesystem helper for creating test images +* Linux ``cryptsetup`` documentation for LUKS disk format specification -- 2.43.0