U-Boot

.. SPDX-License-Identifier: GPL-2.0+:

.. index::
   single: luks (command)

luks command
============

Synopsis
--------

::

    luks detect <interface> <dev[:part]>
    luks info <interface> <dev[:part]>
    luks unlock [-t] <interface> <dev[:part]> <passphrase>

Description
-----------

The *luks* command provides an interface to detect, inspect, and unlock LUKS
(Linux Unified Key Setup) encrypted partitions. LUKS is a disk encryption
specification used for full disk encryption on Linux systems.

This command supports:

* Detection of LUKS encrypted partitions (LUKS1 and LUKS2)
* Display of LUKS header information
* Unlocking LUKS1 partitions with passphrase-based authentication
* Access to decrypted data via blkmap devices

The LUKS format uses a distinctive header containing:

* Magic bytes: "LUKS" followed by 0xBA 0xBE
* Version information (16-bit big-endian)
* Encryption metadata (cipher, mode, hash specification)

luks detect
~~~~~~~~~~~

Detect whether a specified partition is LUKS encrypted and report its version.

interface
    The storage interface type (e.g., mmc, usb, scsi)

dev[:part]
    The device number and optional partition number. If partition is omitted,
    defaults to the whole device.

luks info
~~~~~~~~~

Display detailed header information for a LUKS encrypted partition. This
subcommand reads the LUKS header and displays format-specific metadata.

For LUKS1 partitions, the following information is displayed:

* Version number
* Cipher name (encryption algorithm)
* Cipher mode (e.g., cbc-essiv:sha256)
* Hash specification (e.g., sha256)
* Payload offset (in sectors)
* Key bytes (key size)

For LUKS2 partitions, the following information is displayed:

* Version number
* Header size (in bytes)
* Sequence ID (metadata update counter)
* UUID (partition identifier)
* Label (optional partition label)
* Checksum algorithm
* Full JSON metadata containing:

  - keyslots: Encryption key slot information including KDF parameters
  - tokens: Optional token metadata
  - segments: Encrypted data segment descriptions
  - digests: Master key digest information
  - config: Configuration parameters

interface
    The storage interface type (e.g., mmc, usb, scsi)

dev[:part]
    The device number and optional partition number. If partition is omitted,
    defaults to the whole device.

luks unlock
~~~~~~~~~~~

Unlock a LUKS encrypted partition using a passphrase or TKey hardware token.
This command:

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:

   - **Without -t**: Uses PBKDF2 or Argon2id with the provided passphrase
   - **With -t**: Uses TKey hardware token with passphrase as USS (User-Supplied
     Secret) to derive a disk encryption key

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.

**Supported LUKS versions:**

* LUKS1 (fully supported)
* LUKS2 (fully supported with PBKDF2 and Argon2id key derivation)

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

-t
    Optional flag to use TKey hardware security token. When specified, the
    passphrase is used as the USS (User-Supplied Secret) to derive a disk
    encryption key from the TKey's public key.

interface
    The storage interface type (e.g., mmc, usb, scsi)

dev[:part]
    The device number and optional partition number

passphrase
    The passphrase to unlock the LUKS partition. When using -t flag, this is
    used as the USS for TKey key derivation. Note that the passphrase is
    passed as a command-line argument and may be visible in command history.
    Consider using environment variables to minimize exposure.

The unlocked data remains accessible until U-Boot exits or the blkmap device
is explicitly destroyed.

Examples
--------

Check if MMC device 0 partition 2 is LUKS encrypted::

    => luks detect mmc 0:2
    LUKS2 encrypted partition detected

Check a USB device partition::

    => luks detect usb 0:1
    Not a LUKS partition (error -2: No such file or directory)

Display LUKS header information for a LUKS2 partition::

    => luks info mmc 0:2
    Version:        2
    Header size:    16384 bytes
    Sequence ID:    3
    UUID:           7640da3a-d0a2-4238-9813-4714e7f62203
    Label:
    Checksum alg:   sha256

    JSON metadata (12288 bytes):
    {
      "keyslots": {
        "0": {
          "type": "luks2",
          "key_size": 64,
          "kdf": {
            "type": "argon2id",
            "time": 6,
            "memory": 1048576,
            "cpus": 4,
            ...
          },
          ...
        }
      },
      "tokens": {},
      "segments": {
        "0": {
          "type": "crypt",
          "offset": "16777216",
          "encryption": "aes-cbc-essiv:sha256",
          ...
        }
      },
      "digests": { ... },
      "config": { ... }
    }

Display LUKS header information for a LUKS1 partition::

    => luks info mmc 1:1
    Version:        1
    Cipher name:    aes
    Cipher mode:    cbc-essiv:sha256
    Hash spec:      sha256
    Payload offset: 4096 sectors
    Key bytes:      32

Unlock a LUKS1 partition and access files::

    => 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

    => ls blkmap 0 /
                ./
                ../
                lost+found/
          221   README.md
           17   hello.txt
                subdir/
           20   test.txt

    3 file(s), 4 dir(s)

    => cat blkmap 0 /hello.txt
    Hello from LUKS!

Unlock and load a kernel from encrypted partition::

    => luks unlock mmc 0:2 ${rootfs_password}
    Successfully unlocked with key slot 0!

    => ext4load blkmap 0 ${kernel_addr_r} /boot/vmlinuz
    5242880 bytes read in 123 ms (40.6 MiB/s)

    => bootz ${kernel_addr_r} - ${fdt_addr_r}

Unlock using TKey hardware token::

    => luks unlock -t mmc 0:2 mypassword
    Using TKey for disk encryption key
    Loading TKey signer app (7168 bytes) with USS...
    TKey public key: 3a b2 c4 ... (32 bytes)
    TKey disk key derived successfully
    Unlocking LUKS2 partition...
    Successfully unlocked with key slot 0!
    Unlocked LUKS partition as blkmap device 'luks-mmc-0:2'

Configuration
-------------

The luks command is available when CONFIG_CMD_LUKS is enabled.

For LUKS detection and info commands::

    CONFIG_BLK_LUKS=y
    CONFIG_CMD_LUKS=y

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)

For TKey hardware token support (requires -t flag)::

    CONFIG_TKEY=y        # TKey hardware security token support

Return value
------------

For *detect* and *info*: The return value $? is 0 (true) on success, 1 (false)
on failure.

For *unlock*: The return value $? is 0 (true) if unlock succeeded, 1 (false)
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