# Snigdha Persistence: Disaster Recovery & Key Management Manual

Snigdha OS Decentralized — Phase 4 Engineering Documentation
SPDX-License-Identifier: GPL-3.0-or-later

# 1. Overview and Disaster Classification

This manual provides authoritative procedures for recovering encrypted persistent volumes affected by metadata corruption, filesystem errors, hardware migration, or keyslot damage.

In disk encryption engineering, failure scenarios fall into three categories:

# 2. Passphrase Loss & No-Backdoor Policy

# Keyslot Inspection

To inspect the enrolled keyslots without exposing secrets:

cryptsetup luksDump /dev/sdb2

Look for lines under Keyslots::

• An active keyslot indicates that an unlock method exists.
• If you know one working passphrase, you can enroll a new replacement passphrase immediately before retiring the old one.

# 3. Safe Passphrase Update & Keyslot Rotation

Never delete an existing keyslot until the new one has been tested and verified operational.

# Updating Passphrase via CLI

The change-passphrase command enforces an atomic enroll-verify-retire cycle:

snigdha-persistence change-passphrase

1. Prompts for your current passphrase.
2. Prompts for your new passphrase.
3. Enrolls the new passphrase into an empty keyslot.
4. Executes cryptsetup open --test-passphrase using the new passphrase.
5. Only after verification succeeds does it delete the old keyslot.

# Manual Cryptsetup Keyslot Rotation

If performing manual maintenance from a live rescue environment:

# 1. Add new passphrase
cryptsetup luksAddKey /dev/sdb2

# 2. Test the new passphrase
cryptsetup open --test-passphrase /dev/sdb2

# 3. Kill the old keyslot (e.g. keyslot 0)
cryptsetup luksKillSlot /dev/sdb2 0

# 4. LUKS2 Header Backup & Disaster Restoration

The LUKS2 header occupies the first 16 MiB of the encrypted partition. If bad flash sectors occur in this region, the entire volume will become unreadable even with the correct passphrase.

# Backing Up the Header

snigdha-persistence backup-header /mnt/external-drive/snigdha-header-backup.img

Or via raw cryptsetup:

cryptsetup luksHeaderBackup /dev/sdb2 --header-backup-file /mnt/external-drive/snigdha-header-backup.img

# Restoring the Header from Backup

# Procedure:

1. Verify the backup file:

   cryptsetup isLuks /mnt/external-drive/snigdha-header-backup.img
   cryptsetup luksDump /mnt/external-drive/snigdha-header-backup.img
   

2. Note the UUID reported by luksDump.
3. Restore the header onto the target partition:

   cryptsetup luksHeaderRestore /dev/sdb2 --header-backup-file /mnt/external-drive/snigdha-header-backup.img
   

   Type YES in capital letters when cryptsetup asks for confirmation.
4. Test unlocking the restored volume:

   cryptsetup open --test-passphrase /dev/sdb2
   

# 5. Filesystem Corruption Recovery (ext4)

When persistent storage is unlocked, the backend automatically runs e2fsck -p -f to verify filesystem integrity.

If e2fsck detects uncorrected errors (exit code 4 or higher), mount_persistence_filesystem will fail closed and refuse to mount to prevent further data corruption.

# Recovery Workflow

1. Manually open the encrypted container:

   sudo cryptsetup open /dev/sdb2 snigdha-recovery-mapping
   

2. Run an interactive filesystem check:

   sudo e2fsck -f -y /dev/mapper/snigdha-recovery-mapping
   

3. If corruption was caused by sudden power loss or unplugging without syncing, journal replay will typically repair all inconsistencies automatically.
4. Once clean, mount in read-only mode to extract critical files:

   mkdir -p /mnt/recovery
   sudo mount -o ro,nodev,nosuid /dev/mapper/snigdha-recovery-mapping /mnt/recovery
   ls -la /mnt/recovery/features/persistent-folder
   

5. Copy files to another drive, unmount, and close:

   sudo umount /mnt/recovery
   sudo cryptsetup close snigdha-recovery-mapping
   

# 6. Flash Wear-Out & Partition Corruption Safeguards

Flash memory cells have a finite write endurance. When flash cells fail, read operations may return corrupted ciphertext blocks.

# Best Practices:

1. Maintain regular offline LUKS header backups.
2. Back up critical documents from ~/Persistent to an independent external drive or encrypted remote storage.
3. Never remove the USB drive while Polybar shows  PERSIST: ACTIVE or while files are actively copying.
4. Always use Super + Shift + P -> Lock Persistent Storage before removing the drive or shutting down.