Unlocking Modern Storage: U-Boot Adds LUKSv2 Support

written by Simon Glass | 14 November 2025

We’re excited to announce that U-Boot concept has merged support for unlocking LUKSv2 encrypted partitions! This is a significant enhancement to U-Boot’s security capabilities, allowing it to handle the encryption standard used today by most current Linux distributions.

This 16-patch series (and a small follow-up) bring U-Boot up to speed with modern disk encryption, building on the existing luks unlock command.

Why LUKSv2?

While LUKSv1 was added initially, it was with the intention of taking this next step. LUKSv2 is the modern standard, offering superior security. The two key features U-Boot now supports from LUKSv2 are:

  1. Argon2id Key Derivation: LUKSv2 defaults to using Argon2id, the winner of the Password Hashing Competition. Unlike LUKSv1’s PBKDF2, Argon2id is a memory-hard function designed to be highly resistant to brute-force attacks using GPUs and ASICs. This series introduces the Argon2 library to U-Boot to handle this.
  2. XTS Cipher Mode: Support for the AES-XTS cipher mode (via mbedtls) has been added. XTS is the modern standard for disk encryption, providing stronger security guarantees than the older CBC mode.

The Implementation: A JSON-to-FDT Converter

One of the most interesting challenges in this series was handling the LUKSv2 metadata format. Unlike LUKSv1’s binary header, LUKSv2 stores its complex, hierarchical metadata as a JSON object.

As noted in the cover letter:

“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.”

This is the core of the new implementation. Instead of writing a new, complex JSON parser from scratch, a new function, json_to_fdt(), was created. This function parses the JSON text and converts it on-the-fly into a Flattened Device Tree (FDT) blob in memory.

From there, the LUKSv2 code can use U-Boot’s familiar and robust ofnode API (ofnode_find_subnode(), ofnode_read_string(), etc.) to navigate the metadata and retrieve keyslots, digests, and segment information. This approach is not only more reliable but also fits better within the existing U-Boot architecture.

How It Works

For the command interface, not much has changed. The existing luks unlock command just grows some new features:

  • It automatically detects whether the partition is LUKSv1 or LUKSv2.
  • If it’s LUKSv2, it will parse the JSON metadata.
  • If the keyslot uses Argon2id, it will use the new Argon2 library to derive the key.
  • If the partition uses XTS, it will use the newly enabled mbedtls functions to decrypt it.

Once unlocked, the encrypted partition is mapped as a blkmap device (e.g., blkmap 0), which you can then read from using standard commands like ext4load, fatload, or ls.

This work, along with the necessary documentation and test updates, makes U-Boot ready to boot from modern, secure, full-disk-encrypted systems.