luks: Update docs and tests for LUKSv2

Add documentation for the new LUKSv2 feature and update LUKSv1 to mention the more common algorithm. Update the tests to use LUKSv2 for mmc12 Series-to: concept Series-cc: heinrich Cover-letter: luks: Provide support for LUKSv2 Modern systems mostly use LUKSv2 as it is more secure that v1. This series provides an implementation of this feature, making use of the existing 'luks unlock' command. One interesting part of this series is a converter from JSON to FDT, so that U-Boot's existing ofnode interface can be used to access the hierarchical data in JSON text. This obviously results in quite a bit of new code, but it is more robust than trying to parse the text directly using strstr(), etc. The choice of JSON for LUKS was presumably made with larger code bases in mind, rather than a firmware implementation. END Co-developed-by: Claude <noreply@anthropic.com> Signed-off-by: Simon Glass <simon.glass@canonical.com> Series-links: 1:58
2025-11-11 03:40:19 -07:00
parent 407b729bad
commit 505a3e3af8
3 changed files with 319 additions and 54 deletions
--- 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
 ------------
--- 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::
+Using cryptsetup on Linux
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**LUKS1 with CBC-ESSIV (legacy):**
+
+::

    # 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

-Using Python with U-Boot Test Infrastructure
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**LUKS2 with XTS and PBKDF2 (modern default):**

-See ``test/py/tests/fs_helper.py`` for the ``FsHelper`` class::
+::
+
+    # 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:
+
+::

    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
--- 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);