How to configure encrypted storage with LUKS using exportable keys instead of passphrases

Environment

• Red Hat Enterprise Linux 7
• Red Hat Enterprise Linux 6
• Red Hat Enterprise Linux 5
• LUKS

Issue

• We need a way to have encrypted block storage using exportable keys (key files), instead of passphrases
• How to create a LUKS device that can be unlocked using a keyfile instead of a passphrase?

Resolution

See also: How to configure encrypted storage with LUKS using passphrases and How to add a passphrase, key, or keyfile to an existing LUKS device

Background:

• LUKS-formatted dm-crypt volumes have 8 key slots

• Key slots can be initialized using single-line text-only passphrases (no special [non-printable] chars like new-lines)

  • Benefit: allows for interactive input (e.g., manual human entry at boot time or on-demand) or non-interactive input (key files)

• Key slots can also be initialized using bytes from a file (i.e., a file containing ANYTHING -- even random data pulled from e.g. /dev/random)

  • Benefit: prevents memorization and interactive input; instead, the file is required to unlock device

To create a new LUKS device using a key file:

1. Prepare a key file, whether it is random data or something specific
   Examples:

   • dd if=/dev/random bs=32 count=1 of=/root/random_data_keyfile1
     OR
   • printf "Simple passphrase which can also be used interactively" >/root/plaintext_passphrase_keyfile2

   Take care to ensure the key file is hidden from and unreadable by all untrusted parties

2. Initialize a LUKS partition, setting the key-slot 0 from the new key file
   Potential containers for a "LUKS partition": /dev/sda3, /dev/sdb, /dev/VG/LV, /dev/mapper/mpath1, etc.
   From here on in this document, this will be referred to as DEV
   Examples:

   • cryptsetup luksFormat DEV /root/random_data_keyfile1
     OR
   • cryptsetup luksFormat DEV /root/plaintext_passphrase_keyfile2

3. Choose and make note of a name for the dm-device which will offer a decrypted view of DEV
   From here on in this document, this will be referred to as MAPPING
   Examples of things often used:

   • luks-DEV
     • luks-sda3
     • luks-logvol_name
     • luks-mpath1
   • luks-UUID-of-DEV
     • luks-33fbddf3-0a10-4911-aef4-77102201a938
     • luks-$(cryptsetup luksUUID /dev/sda3)
   • completely-arbitrary-name
     • sda3-unlocked
     • mpath1-decrypted
     • secret_monkeys

   Note that the full path to the decrypted view of DEV will be /dev/mapper/MAPPING -- this will be the device on which further data can be laid.

4. Next up, a choice must be made -- automatic or manual decryption?

   • Should DEV be auto-unlocked at boot time?
     If so, a new entry must be added to /etc/crypttab in the form of: "MAPPING DEV /PATH/TO/KEYFILE"

     • MAPPING is the arbitrary name chosen in step 3
     • DEV is either the path or UUID of device from step 2
     • KEYFILE¹ is of course from step 1

     Examples:

     • echo "luks-sda3 /dev/sda3 /root/random_data_keyfile1" >>/etc/crypttab
     • echo "luks-$(cryptsetup luksUUID /dev/sda3) UUID=$(cryptsetup luksUUID /dev/sda3) /root/random_data_keyfile1" >>/etc/crypttab

     Note: Device names in Linux are extremely volatile (e.g., multipath maps and VG/LV names can be renamed; SCSI dev node names like sda & sdb are non-deterministic and can be different between boots). For this reason the author must unequivocally recommended the use of device UUIDs for the second field. A LUKS device's UUID can be found with cryptsetup luksUUID DEV (as seen above) or with blkid DEV.

   • Should DEV require manual intervention to be unlocked?
     If so, nothing needs to be added to /etc/crypttab
     Instead, root (or users with sudo access) will have to execute cryptsetup luksOpen and cryptsetup luksClose commands (not to mention potentially mount and umount)
     Examples:

     • cryptsetup luksOpen DEV MAPPING --key-file KEYFILE
     • cryptsetup luksOpen /dev/sda3 sda3-unlocked --key-file /PATH/TO/KEYFILE
     • cryptsetup luksOpen UUID=$(cryptsetup luksUUID /dev/sda3) sda3-unlocked --key-file /PATH/TO/KEYFILE
     • cryptsetup luksClose MAPPING
     • cryptsetup luksClose sda3-unlocked

     If this manual intervention method is chosen, step 5 can be skipped

5. Reboot to ensure there are no problems auto-unlocking DEV at boot time
   Once the system comes up, check that DEV was unlocked using one of the following:

   • cryptsetup status MAPPING
     • (Should say "/dev/mapper/MAPPING is active.")
   • lsblk
     • (Should show MAPPING as a "crypt" device under parent DEV)
   • ls /dev/mapper/MAPPING
     • (If this file is not there, the device is not opened)

6. Use /dev/mapper/MAPPING for whatever purpose intended, e.g., put a filesystem on it, use it as the backing storage for an LVM volume group, etc.
   Examples:

   • mkfs.ext4 /dev/mapper/MAPPING
   • mkfs.xfs /dev/mapper/sda3-unlocked
   • vgcreate SOME_NEW_VG /dev/mapper/sda3-unlocked
   • vgextend SOME_EXISTING_VG /dev/mapper/sda3-unlocked

   Note: Assuming success in step 5, there are no special considerations for storing a filesystem on top of /dev/mapper/MAPPING -- simply put it in /etc/fstab as normal. Related: How to configure encrypted swap and How to extend a LUKS encrypted volume.

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.