LUKS2 Encryption on Shani OS — Setup, Management, and Recovery

Full-disk encryption on Shani OS is a single checkbox in the installer. If you skipped it, the correct path is to reinstall — not to attempt to encrypt an existing installation in place.

This guide covers why that is the right call, how to reinstall cleanly, and then — for users who already have an encrypted system — a complete reference for everything you can do with LUKS2: managing keyslots and passphrases, adding keyfiles, backing up the LUKS header, enrolling TPM2 auto-unlock, and recovering from worst-case scenarios.

Full reference: docs.shani.dev — LUKS.

---

If You Missed Encryption at Install: Reinstall

Encrypting an existing unencrypted Shani OS installation requires wiping the root partition entirely. There is no in-place conversion. Attempting it by hand means: backing up all data, booting from USB, repartitioning, creating a LUKS container, recreating the Btrfs subvolume layout, restoring data, regenerating UKIs, and re-enrolling TPM2. Each step is an opportunity for data loss. The Shani OS installer does all of this correctly in a few clicks.

The right approach:

Back up your home directory and any data you want to keep:

   # restic is pre-installed
   restic -r /media/external/backup init
   restic -r /media/external/backup backup ~/
   restic -r /media/external/backup backup /data/
   restic -r /media/external/backup check

Download the latest Shani OS ISO from shani.dev and write it to a USB drive
Boot from the USB and run the installer
On the disk setup screen, enable full-disk encryption — it is a single toggle
Complete installation, reboot, and restore your home directory from the backup

The installer creates the LUKS2 container with argon2id KDF, creates all Btrfs subvolumes, configures /etc/crypttab, and generates the UKIs with the correct LUKS UUID embedded. Everything is wired up correctly from the start.

After reinstalling, enroll TPM2 for passwordless unlock:

sudo gen-efi enroll-tpm2

That's it. The rest of this guide is for users who already have an encrypted system and want to manage it.

---

Why LUKS2 with argon2id

Shani OS uses LUKS2 with the argon2id key derivation function:

argon2id is memory-hard — it requires a large amount of RAM to compute, making GPU and ASIC brute-force attacks orders of magnitude more expensive than with older PBKDF2-based setups
LUKS2 supports multiple keyslots, allowing you to have a passphrase, a keyfile, and a TPM2-sealed key all active simultaneously
The passphrase you choose still matters — argon2id slows attackers down but a weak passphrase is still a weak passphrase

Default encryption parameters used by the Shani OS installer:

Cipher:      aes-xts-plain64
Key size:    512 bits
PBKDF:       argon2id
Memory cost: 1048576 KB (1 GB)
Time cost:   4 iterations
Parallelism: 4 threads

---

Checking Encryption Status

# Is the root partition encrypted?
lsblk -f | grep -E "crypt|luks"
# Should show crypto_LUKS under your root partition (e.g. nvme0n1p2)

# View the full LUKS header — version, cipher, KDF, all keyslots
sudo cryptsetup luksDump /dev/nvme0n1p2

# Confirm the active mapper device
cat /proc/mounts | grep mapper

Look for Version: 2, cipher: aes-xts-plain64, and PBKDF: argon2id. If you see pbkdf2 instead of argon2id, your KDF is significantly weaker — you can convert it:

sudo cryptsetup luksConvertKey --pbkdf argon2id /dev/nvme0n1p2

---

Managing Keyslots

LUKS2 supports up to 32 keyslots. Each keyslot holds an independent key that can decrypt the volume. You can have a primary passphrase, a backup passphrase, a keyfile, and a TPM2-sealed key all active at once.

Adding a Second Passphrase (Recovery Key)

Adding a second passphrase gives you a backup if you forget the first, or a separate passphrase for a trusted person:

sudo cryptsetup luksAddKey /dev/nvme0n1p2
# Enter any existing passphrase when prompted, then set the new one

Changing Your Passphrase

LUKS does not have a "change passphrase" operation — you add a new keyslot then remove the old one:

# Step 1: Add the new passphrase (creates a new keyslot)
sudo cryptsetup luksAddKey /dev/nvme0n1p2

# Step 2: Find the keyslot number of the old passphrase
sudo cryptsetup luksDump /dev/nvme0n1p2 | grep -A2 "Keyslot"

# Step 3: Remove the old keyslot
sudo cryptsetup luksKillSlot /dev/nvme0n1p2 <keyslot-number>
# You will be prompted to authenticate with any remaining valid key

Adding a Keyfile

Keyfiles are useful for automated unlock scenarios or as a recovery key stored securely off-device:

# Generate a strong random keyfile
sudo dd if=/dev/urandom of=/root/luks-keyfile bs=512 count=8
sudo chmod 400 /root/luks-keyfile

# Add the keyfile as an additional LUKS keyslot
sudo cryptsetup luksAddKey /dev/nvme0n1p2 /root/luks-keyfile

# Verify all keyslots
sudo cryptsetup luksDump /dev/nvme0n1p2 | grep -E "Keyslot|Token"

Store the keyfile off-device. Losing it does not lock you out as long as you still have your passphrase.

Removing a Keyslot

# Remove a specific keyslot by number
sudo cryptsetup luksKillSlot /dev/nvme0n1p2 <keyslot-number>

# Or remove by key (prompts for the key to remove)
sudo cryptsetup luksRemoveKey /dev/nvme0n1p2

Never remove all keyslots — leave at least your passphrase slot intact.

---

Backing Up the LUKS Header

The LUKS header stores all keyslots. If it gets corrupted — by a disk failure, accidental overwrite, or filesystem error — the encrypted data is permanently and completely unrecoverable. Back up the header:

sudo cryptsetup luksHeaderBackup /dev/nvme0n1p2 \
  --header-backup-file ~/luks-header-backup-$(date +%Y%m%d).img

# Store this file off-device — external drive, encrypted cloud storage
# Verify it is readable
file ~/luks-header-backup-*.img

Restoring from a header backup:

# This restores the keyslots as they were at backup time
sudo cryptsetup luksHeaderRestore /dev/nvme0n1p2 \
  --header-backup-file luks-header-backup-20260401.img

Back up the header again any time you add or remove a keyslot.

---

TPM2 Auto-Unlock

TPM2 auto-unlock seals your LUKS key into the TPM2 chip so the disk unlocks silently on boot — no passphrase prompt — as long as the boot chain is unmodified. Your passphrase always remains valid as a fallback.

Enrolling

# gen-efi handles PCR policy selection and KDF validation automatically
sudo gen-efi enroll-tpm2

You will be prompted for your LUKS passphrase. The PCR policy is chosen based on your Secure Boot state:

Secure Boot enabled: PCR 0 + PCR 7 — firmware measurements and Secure Boot certificate state
Secure Boot disabled: PCR 0 only — firmware measurements only (weaker)

After enrolling, reboot and confirm the disk unlocks silently.

After Firmware Updates

If fwupdmgr update updated your BIOS, PCR 0 changes. The TPM will not release the key, so you will be prompted for your passphrase on the next boot. This is expected behaviour.

# After booting with passphrase, clean up the stale slot and re-enroll
sudo gen-efi cleanup-tpm2
sudo gen-efi enroll-tpm2

After Secure Boot Changes

When you enable, disable, or change enrolled Secure Boot keys, PCR 7 changes. Re-enroll:

sudo gen-efi cleanup-tpm2
sudo gen-efi enroll-tpm2

Adding a TPM2 PIN (Second Factor)

For stronger protection, require a short PIN in addition to TPM2 binding. gen-efi enroll-tpm2 prompts you to opt in during enrollment. Plymouth will ask for the PIN at boot — the disk only unlocks if both the TPM measurement matches and the PIN is correct.

Verifying TPM2 State

# Confirm TPM2 enrollment is present
sudo cryptsetup luksDump /dev/nvme0n1p2 | grep systemd-tpm2

# List all keyslots and tokens
sudo cryptsetup luksDump /dev/nvme0n1p2 | grep -A5 "Token"

# List available TPM2 devices
sudo systemd-cryptenroll --tpm2-device=list

Full TPM2 reference: docs.shani.dev — TPM2 Enrollment.

---

Verifying Encryption is Working

# Confirm the partition type
lsblk -o NAME,FSTYPE,SIZE,MOUNTPOINT
# nvme0n1p2 should show crypto_LUKS

# Check the mapper device is active
ls -la /dev/mapper/shani_root

# Full header dump
sudo cryptsetup luksDump /dev/nvme0n1p2

---

Emergency Recovery

Forgotten Passphrase, No Backup Key

If you have no backup passphrase, no keyfile, and no TPM2 enrollment — the data is unrecoverable. This is the intended security guarantee of LUKS2.

Boot from the Shani OS USB, reinstall, and restore from your data backups.

Have a Backup Keyfile

# Boot from Shani OS USB
# Open the encrypted partition using the keyfile
sudo cryptsetup open /dev/nvme0n1p2 shani_root \
  --key-file /path/to/luks-keyfile

# Mount and access your data
sudo mount -o subvol=@home /dev/mapper/shani_root /mnt/home
sudo mount -o subvol=@data /dev/mapper/shani_root /mnt/data

Have a Header Backup (Corrupted Header)

# Boot from Shani OS USB
# Restore the header backup first
sudo cryptsetup luksHeaderRestore /dev/nvme0n1p2 \
  --header-backup-file luks-header-backup.img

# Then open with your passphrase as normal
sudo cryptsetup open /dev/nvme0n1p2 shani_root

TPM2 Won't Unlock (Firmware Changed)

# Boot and enter your passphrase when prompted
# Then re-enroll TPM2 with current PCR values
sudo gen-efi cleanup-tpm2
sudo gen-efi enroll-tpm2

---

Resources

Shani OS Troubleshooting Guide — when things go wrong
Shani OS FAQ — common questions answered
docs.shani.dev — LUKS — full reference
docs.shani.dev — TPM2 Enrollment — passwordless unlock setup
gen-efi and Secure Boot on Shani OS — UKI generation and TPM2
Security Without Configuration — security model overview
Telegram community — ask for help before attempting recovery procedures

---

Built in India 🇮🇳 · Immutable · Atomic · Zero Telemetry

Latest Posts