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:

Verifies the partition is LUKS encrypted (LUKS1 or LUKS2)
Parses LUKS2 JSON metadata (if LUKS2) using FDT conversion
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.
Attempts to unlock each active key slot
Verifies the master key against the stored digest
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.).