From: Simon Glass <simon.glass@canonical.com> Add documentation for the new LUKSv2 feature and update LUKSv1 to mention the more common algorithm. Update the tests to use LUKSv2 for mmc12 Co-developed-by: Claude <noreply@anthropic.com> Signed-off-by: Simon Glass <simon.glass@canonical.com> --- doc/usage/cmd/luks.rst | 42 ++++-- doc/usage/luks.rst | 300 +++++++++++++++++++++++++++++++++++------ test/boot/luks.c | 29 ++++ 3 files changed, 318 insertions(+), 53 deletions(-) diff --git a/doc/usage/cmd/luks.rst b/doc/usage/cmd/luks.rst index 6c262e66200..3c8576dc8a1 100644 --- a/doc/usage/cmd/luks.rst +++ b/doc/usage/cmd/luks.rst @@ -57,7 +57,7 @@ For LUKS1 partitions, the following information is displayed: * Version number * Cipher name (encryption algorithm) -* Cipher mode (e.g., xts-plain64) +* Cipher mode (e.g., cbc-essiv:sha256) * Hash specification (e.g., sha256) * Payload offset (in sectors) * Key bytes (key size) @@ -88,24 +88,35 @@ dev[:part] luks unlock ~~~~~~~~~~~ -Unlock a LUKS1 encrypted partition using a passphrase. This command: +Unlock a LUKS encrypted partition using a passphrase. This command: -1. Verifies the partition is LUKS1 encrypted -2. Derives the encryption key using PBKDF2 with the provided passphrase -3. Attempts to unlock each active key slot -4. Verifies the master key against the stored digest -5. Creates a blkmap device providing on-the-fly decryption +1. Verifies the partition is LUKS encrypted (LUKS1 or LUKS2) +2. Parses LUKS2 JSON metadata (if LUKS2) using FDT conversion +3. Derives the encryption key using PBKDF2 or Argon2id with the provided + passphrase +4. Attempts to unlock each active key slot +5. Verifies the master key against the stored digest +6. Creates a blkmap device providing on-the-fly decryption After successful unlock, the decrypted data is accessible through a blkmap device (typically ``blkmap 0``). Standard U-Boot filesystem commands can then be used to access files on the unlocked partition. -**Currently only LUKS1 is supported for unlocking. LUKS2 unlock is not yet -implemented.** +**Supported LUKS versions:** -Supported cipher modes: +* LUKS1 (fully supported) +* LUKS2 (fully supported with PBKDF2 and Argon2id key derivation) -* aes-cbc-essiv:sha256 (AES in CBC mode with ESSIV) +**Supported cipher modes:** + +* **LUKS1**: aes-cbc-essiv:sha256 (AES in CBC mode with ESSIV) +* **LUKS2**: aes-cbc-essiv:sha256 and aes-xts-plain64 (AES-XTS, modern default) + +**Supported key derivation functions:** + +* **PBKDF2**: Traditional password-based key derivation (LUKS1 and LUKS2) +* **Argon2id**: Memory-hard KDF resistant to GPU attacks (LUKS2 only, requires + CONFIG_ARGON2) interface The storage interface type (e.g., mmc, usb, scsi) @@ -165,7 +176,7 @@ Display LUKS header information for a LUKS2 partition:: "0": { "type": "crypt", "offset": "16777216", - "encryption": "aes-xts-plain64", + "encryption": "aes-cbc-essiv:sha256", ... } }, @@ -232,9 +243,16 @@ For LUKS unlock functionality, additional options are required:: CONFIG_BLK_LUKS=y CONFIG_CMD_LUKS=y CONFIG_BLKMAP=y # For blkmap device support + CONFIG_JSON=y # For LUKS2 JSON metadata parsing (auto-selected by + # CONFIG_BLK_LUKS) CONFIG_AES=y # For AES encryption CONFIG_SHA256=y # For SHA-256 hashing CONFIG_PBKDF2=y # For PBKDF2 key derivation + CONFIG_MBEDTLS_LIB=y # For AES-XTS and mbedTLS crypto (LUKS2) + +For Argon2id support (modern LUKS2 KDF):: + + CONFIG_ARGON2=y # Argon2 password hashing (adds ~50KB to binary) Return value ------------ diff --git a/doc/usage/luks.rst b/doc/usage/luks.rst index 24be8d1ea81..db8558ffb56 100644 --- a/doc/usage/luks.rst +++ b/doc/usage/luks.rst @@ -1,14 +1,14 @@ .. 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. +unlock and read data from LUKS1 and LUKS2-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 @@ -17,19 +17,34 @@ different passphrases to unlock the same encrypted data. Currently, U-Boot supports: * LUKS version 1 (LUKS1) +* LUKS version 2 (LUKS2) with PBKDF2 and Argon2 key derivation * AES-256-CBC encryption with ESSIV (Encrypted Salt-Sector IV) mode -* Passphrase-based unlocking via PBKDF2 key derivation +* AES-256-XTS encryption (modern default for LUKS2) +* Passphrase-based unlocking via PBKDF2 or Argon2id key derivation * Reading ext4 and other filesystems from unlocked devices Supported Cipher Modes ------------------------ +---------------------- -The following LUKS1 cipher configurations are supported: +The following cipher configurations are supported: + +**LUKS1:** * **Cipher**: aes * **Mode**: cbc-essiv:sha256 * **Key sizes**: 128-bit, 192-bit, 256-bit -* **Hash**: sha256 (for PBKDF2) +* **KDF**: PBKDF2 with SHA256 + +**LUKS2:** + +* **Cipher**: aes +* **Mode**: cbc-essiv:sha256 or xts-plain64 +* **Key sizes**: 128-bit, 192-bit, 256-bit (CBC); 256-bit, 512-bit (XTS) +* **KDF**: PBKDF2 with SHA256, or Argon2id +* **Hash**: sha256, sha512 (for PBKDF2 and digests) + +XTS mode is the modern default for LUKS2 and provides better security properties +than CBC-ESSIV for disk encryption. Commands -------- @@ -39,11 +54,15 @@ See the :doc:`cmd/luks` for full details. luks detect ~~~~~~~~~~~ -Detect whether a partition is LUKS-encrypted:: +Detect whether a partition is LUKS-encrypted: + +:: luks detect <interface> <dev[:part]> -Example:: +Example: + +:: => luks detect mmc 0:2 LUKS1 encrypted partition detected @@ -53,11 +72,15 @@ This command checks for the LUKS magic bytes and validates the header structure. luks info ~~~~~~~~~ -Display information about a LUKS partition:: +Display information about a LUKS partition: + +:: luks info <interface> <dev[:part]> -Example:: +Example: + +:: => luks info mmc 0:2 Version: 1 @@ -73,11 +96,15 @@ offset to the encrypted data payload. luks unlock ~~~~~~~~~~~ -Unlock a LUKS partition with a passphrase:: +Unlock a LUKS partition with a passphrase: + +:: luks unlock <interface> <dev[:part]> <passphrase> -Example:: +Example: + +:: => luks unlock mmc 0:2 mypassword Trying to unlock LUKS partition... @@ -96,15 +123,17 @@ This command: 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``). +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:: +Use standard filesystem commands to access the unlocked device: + +:: => ls blkmap 0 / ./ @@ -120,15 +149,19 @@ Use standard filesystem commands to access the unlocked device:: Reading Files ~~~~~~~~~~~~~ -Read file contents:: +Read file contents: + +:: => cat blkmap 0 /hello.txt Hello from LUKS! Loading Files to Memory -~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~ + +Load files for further processing: -Load files for further processing:: +:: => ext4load blkmap 0 ${loadaddr} /boot/vmlinuz 5242880 bytes read in 123 ms (40.6 MiB/s) @@ -136,7 +169,9 @@ Load files for further processing:: Using with Boot Flows ~~~~~~~~~~~~~~~~~~~~~ -LUKS-encrypted partitions can be integrated into boot flows:: +LUKS-encrypted partitions can be integrated into boot flows: + +:: => bootflow scan => bootflow list @@ -149,16 +184,41 @@ Implementation Details Key Derivation ~~~~~~~~~~~~~~ -LUKS uses PBKDF2 (Password-Based Key Derivation Function 2) to derive -encryption keys from passphrases. The process: +LUKS supports two key derivation functions: + +**PBKDF2 (Password-Based Key Derivation Function 2)** + +Used by LUKS1 and LUKS2. 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 +PBKDF2 applies HMAC-SHA256 iteratively (typically 100,000+ iterations) to make +brute-force attacks computationally expensive. + +**Argon2id (Modern KDF for LUKS2)** + +Argon2id is the winner of the Password Hashing Competition and provides better +resistance to GPU-based cracking attacks. The process: + +1. Passphrase + salt → Argon2id(time, memory, parallelism) → 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 + +Argon2id parameters: + +* **time**: Number of iterations through memory +* **memory**: Amount of memory used in KiB (e.g., 1048576 = 1GB) +* **parallelism**: Number of parallel threads/lanes + +Argon2id is memory-hard, making it resistant to ASIC and GPU attacks while +remaining fast on CPUs. + Anti-Forensic (AF) Splitter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ LUKS uses an anti-forensic information splitter to protect key material: @@ -170,8 +230,8 @@ LUKS uses an anti-forensic information splitter to protect key material: ESSIV Mode ~~~~~~~~~~ -ESSIV (Encrypted Salt-Sector IV) generates unique initialization vectors -for each encrypted sector: +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) @@ -180,23 +240,86 @@ for each encrypted sector: This prevents watermarking attacks where identical plaintext blocks would produce identical ciphertext blocks. +XTS Mode +~~~~~~~~ + +XTS (XEX-based tweaked-codebook mode with ciphertext stealing) is the modern +standard for disk encryption and the default for LUKS2. It provides several +advantages over CBC-ESSIV: + +1. **Tweakable block cipher**: Each 512-byte sector uses the sector number as a + tweak +2. **No IV dependency**: Eliminates the need for ESSIV key derivation +3. **Parallel encryption**: Sectors can be encrypted/decrypted independently +4. **Better security**: Resistant to manipulation attacks on ciphertext + +XTS operation: + +1. Uses two AES keys (concatenated): 256-bit key → two 128-bit keys, or 512-bit + key → two 256-bit keys +2. For each 512-byte sector: + + * Data unit (tweak) = sector number in little-endian format + * Plaintext is encrypted using AES-XTS with the data unit + +3. Each 16-byte block within the sector uses a different tweak value derived + from the sector number + +XTS is specified in IEEE P1619 and is widely used in modern disk encryption. + +LUKS2 JSON Metadata Parsing +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +LUKS2 stores its metadata in JSON format within the header. This is handled as +follows: + +1. **JSON to FDT Conversion**: The JSON metadata is converted to a Flattened + Device Tree (FDT) format using ``json_to_fdt()`` +2. **ofnode Navigation**: ofnode API is used to access the tree structure +3. **Type-Safe Property Reading**: Properties are read using + ``ofnode_read_string()`` and ``ofnode_read_u32()`` for type safety + +This approach provides several advantages: + +* **Robust Parsing**: Uses U-Boot's well-tested FDT/ofnode infrastructure +* **Type Safety**: Explicit type checking for all properties +* **Maintainability**: Clear code structure with proper node navigation +* **No String Searching**: Eliminates fragile string-based parsing + +Example navigation path for reading a keyslot's KDF type: + +:: + + root → keyslots → "0" → kdf → type + +The implementation properly handles LUKS2's mixed data types: + +* JSON numbers (iterations, time, memory) are stored as 32-bit integers +* JSON string-encoded numbers (offset, size) are parsed from strings +* JSON strings (type, hash, salt) are read directly + 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 +* Performs on-the-fly decryption (AES-CBC-ESSIV for LUKS1, AES-XTS for LUKS2) * 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. +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 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +**LUKS1 with CBC-ESSIV (legacy):** -Using cryptsetup on Linux:: +:: # Create a 60MB file $ dd if=/dev/zero of=test.img bs=1M count=60 @@ -222,14 +345,71 @@ Using cryptsetup on Linux:: # Close the LUKS device $ cryptsetup close testluks +**LUKS2 with XTS and PBKDF2 (modern default):** + +:: + + # Create a 60MB file + $ dd if=/dev/zero of=test.img bs=1M count=60 + + # Format as LUKS2 with XTS + $ cryptsetup luksFormat --type luks2 \ + --cipher aes-xts-plain64 \ + --key-size 512 \ + --hash sha256 \ + --pbkdf pbkdf2 \ + test.img + + # Open, create filesystem, and add files (same as LUKS1) + $ cryptsetup open test.img testluks + $ mkfs.ext4 /dev/mapper/testluks + $ mount /dev/mapper/testluks /mnt + $ echo "Hello from LUKS2!" > /mnt/hello.txt + $ umount /mnt + $ cryptsetup close testluks + +**LUKS2 with XTS and Argon2id (maximum security):** + +:: + + # Create a 60MB file + $ dd if=/dev/zero of=test.img bs=1M count=60 + + # Format as LUKS2 with XTS and Argon2id + $ cryptsetup luksFormat --type luks2 \ + --cipher aes-xts-plain64 \ + --key-size 512 \ + --hash sha256 \ + --pbkdf argon2id \ + --pbkdf-memory 65536 \ + --pbkdf-parallel 4 \ + --iter-time 2000 \ + test.img + + # Open, create filesystem, and add files (same as above) + $ cryptsetup open test.img testluks + $ mkfs.ext4 /dev/mapper/testluks + $ mount /dev/mapper/testluks /mnt + $ echo "Hello from LUKS2 with Argon2!" > /mnt/hello.txt + $ umount /mnt + $ cryptsetup close testluks + +Note: Argon2 parameters: + +* ``--pbkdf-memory``: Memory in KiB (65536 = 64MB) +* ``--pbkdf-parallel``: Number of parallel threads +* ``--iter-time``: Target time in milliseconds for KDF + Using Python with U-Boot Test Infrastructure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +See ``test/py/tests/fs_helper.py`` for the ``FsHelper`` class: -See ``test/py/tests/fs_helper.py`` for the ``FsHelper`` class:: +:: from fs_helper import FsHelper, DiskHelper - # Create encrypted filesystem + # Create LUKS2 encrypted filesystem with PBKDF2 (default) with FsHelper(config, 'ext4', 30, 'test', part_mb=60, passphrase='mypassword') as fsh: @@ -240,32 +420,66 @@ See ``test/py/tests/fs_helper.py`` for the ``FsHelper`` class:: # Create encrypted filesystem fsh.mk_fs() + # Create LUKS2 encrypted filesystem with Argon2id + with FsHelper(config, 'ext4', 30, 'test', + part_mb=60, + encrypt_passphrase='mypassword', + luks_kdf='argon2id') as fsh: + # Add files to fsh.srcdir + with open(os.path.join(fsh.srcdir, 'hello.txt'), 'w') as f: + f.write('Hello from LUKS with Argon2!\n') + + # Create encrypted filesystem + fsh.mk_fs() + + # Create LUKS1 encrypted filesystem + with FsHelper(config, 'ext4', 30, 'test', + part_mb=60, + encrypt_passphrase='mypassword', + luks_version=1) as fsh: + # Add files to fsh.srcdir + with open(os.path.join(fsh.srcdir, 'hello.txt'), 'w') as f: + f.write('Hello from LUKS1!\n') + + # Create encrypted filesystem + fsh.mk_fs() + Configuration Options --------------------- CONFIG_CMD_LUKS Enable the ``luks`` command +CONFIG_BLK_LUKS + Enable LUKS block device support + CONFIG_BLKMAP Enable blkmap device support (required for LUKS unlock) -CONFIG_AES - Enable AES encryption support +CONFIG_JSON + Enable JSON parsing support (automatically selected by CONFIG_BLK_LUKS for + LUKS2 metadata parsing) + +CONFIG_MBEDTLS_LIB + Enable mbedTLS library for AES-XTS and key derivation CONFIG_SHA256 Enable SHA-256 hashing support -CONFIG_PBKDF2 - Enable PBKDF2 key derivation +CONFIG_SHA512 + Enable SHA-512 hashing support (optional, for LUKS2) + +CONFIG_ARGON2 + Enable Argon2 key derivation support (optional, for modern LUKS2) 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) +* Argon2 support requires CONFIG_ARGON2 to be enabled (adds ~50KB to binary) +* Large Argon2 memory requirements may not be suitable for all embedded systems Security Considerations ----------------------- @@ -302,7 +516,9 @@ Example Use Cases Encrypted Root Filesystem ~~~~~~~~~~~~~~~~~~~~~~~~~ -Boot from an encrypted root partition:: +Boot from an encrypted root partition: + +:: => luks unlock mmc 0:2 ${rootfs_password} => setenv bootargs root=/dev/blkmap0 rootfstype=ext4 @@ -313,7 +529,9 @@ Boot from an encrypted root partition:: Encrypted Configuration Storage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Read configuration from encrypted partition:: +Read configuration from encrypted partition: + +:: => luks unlock mmc 0:3 ${config_password} => ext4load blkmap 0 ${loadaddr} /config/boot.conf diff --git a/test/boot/luks.c b/test/boot/luks.c index afa8c9f172e..4ee6081a790 100644 --- a/test/boot/luks.c +++ b/test/boot/luks.c @@ -229,6 +229,7 @@ static int bootstd_test_luks_unlock(struct unit_test_state *uts) /* Test unlocking partition 2 with correct passphrase */ ut_assertok(run_command("luks unlock mmc b:2 test", 0)); + ut_assert_nextline("Unlocking LUKS1 partition..."); ut_assert_nextline("Unlocked LUKS partition as blkmap device 'luks-mmc-b:2'"); ut_assert_console_end(); @@ -239,3 +240,31 @@ static int bootstd_test_luks_unlock(struct unit_test_state *uts) return 0; } BOOTSTD_TEST(bootstd_test_luks_unlock, UTF_DM | UTF_SCAN_FDT | UTF_CONSOLE); + +/* Test LUKS2 unlock command with LUKS2 encrypted partition */ +static int bootstd_test_luks2_unlock(struct unit_test_state *uts) +{ + struct udevice *mmc; + + ut_assertok(setup_mmc12(uts, &mmc)); + + /* Test that unlock command exists and handles errors properly */ + /* Should fail because partition 1 is not LUKS */ + ut_asserteq(1, run_command("luks unlock mmc c:1 test", 0)); + ut_assert_nextline("Not a LUKS partition"); + ut_assert_console_end(); + + /* Test unlocking partition 2 with correct passphrase */ + ut_assertok(run_command("luks unlock mmc c:2 test", 0)); + ut_assert_nextline("Unlocking LUKS2 partition..."); + ut_assert_nextline("Unlocked LUKS partition as blkmap device 'luks-mmc-c:2'"); + ut_assert_console_end(); + + /* Test unlocking with wrong passphrase */ + ut_asserteq(1, run_command("luks unlock mmc c:2 wrongpass", 0)); + ut_assert_nextline("Unlocking LUKS2 partition..."); + ut_assert_skip_to_line("Failed to unlock LUKS partition (err -13: Permission denied)"); + + return 0; +} +BOOTSTD_TEST(bootstd_test_luks2_unlock, UTF_DM | UTF_SCAN_FDT | UTF_CONSOLE); -- 2.43.0