u-boot/doc/usage/cmd/luks.rst

.. 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] [-p] <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. You can use 'tkey connect' to
     select which TKey to use, otherwise it uses the first one it finds.

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.

-p
    Optional flag to treat the passphrase as a hex-encoded pre-derived master
    key, skipping the KDF (Key Derivation Function) step. This is useful when
    the master key has already been derived externally, such as from a hardware
    security module or other key management system.

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'

Unlock using a pre-derived master key (hex-encoded)::

    => luks unlock -p mmc 0:2 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
    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:`../tkey-fde` - TKey full disk encryption with hardware-backed keys
* :doc:`blkmap` - Blkmap device documentation
* :doc:`tkey` - TKey command reference
* cryptsetup project: https://gitlab.com/cryptsetup/cryptsetup
* LUKS on-disk format specifications: https://gitlab.com/cryptsetup/cryptsetup/-/wikis/home