BTRFS Encryption Authentication

TL;DR

Yes, BTRFS can provide authentication on an encrypted disk using keyslots and PAM (Pluggable Authentication Modules). This allows you to unlock your encrypted volume with a password or other authentication method instead of just a key file. It’s more secure than relying solely on a key file.

Setting up BTRFS Encryption Authentication

1. Prerequisites: You need a working BTRFS filesystem already encrypted. This guide assumes you have that set up and can mount it with a keyfile.
   • Ensure you have the btrfs-progs package installed.
   • You’ll also need PAM configured, which is standard on most Linux distributions.
2. Create a Keyslot: A keyslot stores the encryption key securely.

   sudo btrfs key unlock -K <keyfile_path> -s <keyslot_number> /mount/point

   Replace <keyfile_path> with the path to your existing encryption key file and <keyslot_number> with a number (e.g., 1, 2, etc.). Choose a number you’ll remember.

3. Configure PAM: This is where you tell the system how to authenticate before unlocking the volume.
   • Edit the PAM configuration file for your authentication method (usually /etc/pam.d/login or /etc/pam.d/system-auth). Back up this file first!
   • Add a line similar to the following:

     auth    required pam_btrfs.so keyslot=<keyslot_number> subvolume=/mount/point

     Replace <keyslot_number> with the same number you used in step 2 and /mount/point with your mount point.

4. Modify fstab: Update your /etc/fstab entry to use keyslots instead of a keyfile.

   UUID=<your_uuid> /mount/point btrfs defaults,subvol=@,noatime,compress=zstd,keyslot=<keyslot_number>,user_xattr 0 0

   Replace <your_uuid> with the UUID of your BTRFS partition (find it using blkid), and <keyslot_number> with the keyslot number.

5. Test the Configuration: Reboot your system or try unmounting and remounting the volume.
   1. You should be prompted for authentication (password, etc.) before the volume is unlocked.
   2. If it fails, check your PAM configuration file carefully for errors. Look at /var/log/auth.log or similar logs for clues.
6. Multiple Keyslots (Optional): You can create multiple keyslots and configure different authentication methods for each.
   • Repeat steps 2 and 3 for each additional keyslot.
   • In your PAM configuration, you can specify multiple pam_btrfs.so lines with different keyslot numbers to allow any of them to unlock the volume.

Important Considerations

• Security: While using PAM improves security over a simple keyfile, it’s still crucial to protect your system from malware and unauthorized access.
• Key Management: Keep track of your keyslot numbers! Losing them means losing access to your data.
• Backups: Always have backups of your important data, regardless of the encryption method used.
• systemd-cryptsetup integration: BTRFS encryption with PAM is often best integrated with systemd-cryptsetup for more robust management and automatic unlocking during boot (this guide doesn’t cover that).