5e381f02ee
Add a -t option to the 'luks unlock' command to allow a TKey to be used to unlock a disk. The password is used as the user-supplied secret (USS) in this case. Series-to: concept Cover-letter: luks: Integrate support for a TKey This series illustrates how to use a Tillitis TKey to unlock an encrypted disk. This has the advantage that the key depends on a physical key in the user's posession as well as the usual passphrase. The TKey handles the key derivation, so this series includes logic to skip that step when a TKey is used. The 'luks unlock' command provides a -t flag to use a TKey. It also provides a small pytest fix to ease conflicts with Labgrid integration. END Co-developed-by: Claude <noreply@anthropic.com> Signed-off-by: Simon Glass <simon.glass@canonical.com> Series-links: 1:63
299 lines
8.3 KiB
ReStructuredText
299 lines
8.3 KiB
ReStructuredText
.. 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
|