.. SPDX-License-Identifier: GPL-2.0+: .. index:: single: luks (command) luks command ============ Synopsis -------- :: luks detect luks info luks unlock [-t] 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