Red Hat Enterprise Linux Diagnostics and Troubleshooting
Linux Unified Key Setup (LUKS) is a specification for block device encryption. In Red Hat Enterprise Linux 8, LUKS2 is the default LUKS encryption format. A LUKS-encrypted block device must be decrypted with a passphrase or key before the contained file systems can be mounted.
Note
The legacy LUKS1 format remains fully supported in RHEL 8 for compatibility with earlier RHEL releases.
Add entries to the /etc/crypttab and /etc/fstab files to persistently mount an encrypted device. The /etc/cryptab file must reference the device and, if used, its key file.
The system consults the
/etc/crypttabfile during booting to determine which devices to decrypt. The file lists one device per line, with space-separated fields.name /dev/<device> /path/to/keyfile
nameis the name that the device mapper creates for the decrypted device./dev/<device>is the underlying encrypted device./path/to/keyfileis the key file for decrypting the device. If the last field is blank or set to none, then the user is prompted for the decryption password during boot.
The system decrypts the device, by using the passphrase from the user or the key file, and names the device
/dev/mapper/, with the specifiednamenamein/etc/crypttab.The system mounts the file system in the decrypted mapped device, by using the relevant entry in
/etc/fstab. The entry can reference either the device mapper name or the device's UUID.# Using device mapper name /dev/mapper/name /secret ext4 defaults 1 2 # Using device UUID "2460ab6e-e869-4011-acae-31b2e8c05a3b" /another-secret ext4 defaults 1 2
Manually entering commands and passwords can decrypt LUKS-encrypted devices and mount their filesystems. When the automated persistent mounting fails, verify the file configurations and attempt to access and mount the device from the command line. Failures are caused by either an incorrect file configuration or an incorrect password or key.
An incorrect /etc/crypttab entry causes decryption issues. Entries in this file state how encrypted devices are decrypted and how they are named after decryption.
The fields in an /etc/crypttab entry are the device mapper name, the encrypted device, and the path to the key file (or blank or "none" to use a passphrase). If decryption fails, then verify the second and third fields. An incorrect encrypted device path or an incorrect key file causes a decryption failure.
If the decryption is successful, but mounting the device fails, then verify the first field. A mismatch between the specified name in /etc/crypttab and the device mapper name in /etc/fstab causes the device's file system to fail to mount. The dmsetup ls --crypt command lists the encrypted mapped devices in use.
[root@host ~]# dmsetup ls --target crypt
example-device (252, 0)Devices might fail decryption due to problems with a key or passphrase.
The LUKS passphrase is forgotten or changed to an unknown password.
The LUKS2 format offers 32 key slots for encrypted devices. If other keys or passphrases exist, then they can reset the forgotten or unknown password. To display associated keys, use the
cryptsetup luksDumpcommand.[root@host ~]#
cryptsetup luksDump /dev/vdbLUKS header information Version: 2 Epoch: 3 Metadata area: 16384 [bytes] Keyslots area: 16744448 [bytes] UUID: 1bb6e35d-c1dd-4afa-a028-ee4fe8f4c5ef Label: (no label) Subsystem: (no subsystem) Flags: (no flags) Data segments: 0: crypt offset: 16777216 [bytes] length: (whole device) cipher: aes-xts-plain64 sector: 512 [bytes] Keyslots: 0: luks2 Key: 512 bits Priority: normal Cipher: aes-xts-plain64 Cipher key: 512 bits PBKDF: argon2i Time cost: 4 Memory: 930312 Threads: 2 Salt: aa 78 ac dc 79 b7 3a 1b 77 dc 7d 7a 92 59 53 d7 1b 0d 13 94 3d ea 30 48 f8 97 db 8e fd d4 50 4a AF stripes: 4000 AF hash: sha256 Area offset:32768 [bytes] Area length:258048 [bytes] Digest ID: 0 ...output omitted...If a backup of the LUKS header exists, then restoring it can revert to a previously working passphrase.
The LUKS header is corrupted. LUKS stores a metadata header and key slots at the beginning of each encrypted device. A corrupted LUKS header can render the encrypted data inaccessible. If a known-good backup of the LUKS header exists, then restore the header from the backup.
The needed hash functions and ciphers to execute the decryption are not in the kernel. View the contents of
/proc/cryptofor a list of installed cryptographic ciphers that the kernel supports.
For commonly encountered LUKS issues, LUKS header backups can mean the difference between a simple fix and permanently unrecoverable data. You should routinely back up LUKS-encrypted device headers and practice the procedure to restore headers.
Backup LUKS headers using the cryptsetup tool with the luksHeaderBackup subcommand. Specify the backup file location with the --header-backup-file option.
[root@host ~]# cryptsetup luksHeaderBackup /path/to/encrypted/device --header-backup-file /path/to/backup/fileMake LUKS header backups before every administrative task on LUKS-encrypted devices.
If an encrypted device's LUKS header is backed up, then restore a backup to retrieve forgotten passwords or corrupted headers. Before restoring a header, always back up the existing header even if the header appears corrupted or is associated with an unknown password.
For multiple backups of an encrypted device, an administrator must identify which one to restore. Rather than restoring a header and attempting a decryption, an administrator can conduct a trial decryption with a header file.
[root@host ~]#cryptsetup luksOpenEnter passphrase for/path/to/encrypted/deviceDECRYPTED-NAME--header/path/to/backup/file/path/to/encrypted/device:
If the test succeeds, then you can restore the header with the cryptsetup command and the luksHeaderRestore subcommand.
[root@host ~]#cryptsetup luksHeaderRestoreWARNING! ======== Device/path/to/encrypted/device--header-backup-file/path/to/backup/file/path/to/encrypted/devicealready contains LUKS header. Replacing header will destroy existing keyslots. Are you sure? (Type uppercase yes):YES
References
cryptsetup(8) man page
Encrypting Block Devices Using LUKS
