# Snigdha OS Decentralized — Verified Immutable Root Filesystem (dm-verity)

# 1. Rationale & Threat Model

Secure Boot alone only guarantees that the UEFI firmware executed an authentic bootloader and kernel. It does not protect the files stored in the root filesystem image on the installation medium against offline tampering or storage corruption.

If an attacker modifies a binary on the USB drive (e.g., patching /usr/bin/sudo or /usr/lib/libcrypto.so inside airootfs.erofs), a kernel booted with Secure Boot would ordinarily mount the tampered image without knowing that the filesystem was altered.

Snigdha OS Decentralized eliminates this vulnerability by enforcing dm-verity (Device Mapper Verity) on the immutable root filesystem.

---

# 2. Cryptographic Architecture

dm-verity uses a Merkle tree (a tree of cryptographic hashes) to verify block-level integrity transparently as blocks are read from storage into memory:

                  +------------------------+
                  |  Authenticated Root    | <--- Embedded in signed UKI
                  |        Hash            |      kernel command line
                  +------------------------+
                               |
               +---------------+---------------+
               |                               |
       +---------------+               +---------------+
       |  Level 2 Hash |               |  Level 2 Hash |
       +---------------+               +---------------+
               |                               |
        +------+------+                 +------+------+
        |             |                 |             |
   +---------+   +---------+       +---------+   +---------+
   | L1 Hash |   | L1 Hash |       | L1 Hash |   | L1 Hash |
   +---------+   +---------+       +---------+   +---------+
        |             |                 |             |
   +---------+   +---------+       +---------+   +---------+
   | Data B0 |   | Data B1 |       | Data B2 |   | Data B3 | <--- airootfs.erofs
   +---------+   +---------+       +---------+   +---------+

# Verification Parameters

• Data Block Size: 4096 bytes (matches standard Linux page size)
• Hash Block Size: 4096 bytes
• Hash Algorithm: SHA-256
• Cryptographic Salt: Unique 256-bit hexadecimal string generated per build
• Hash Tree Location: snigdha/x86_64/airootfs.verity
• Data Image: snigdha/x86_64/airootfs.erofs

---

# 3. Initramfs Integration & Amnesia Handshake

The verification is executed during early boot by the snigdha_trust_verity initcpio hook:

1. Parameter Discovery:

   • The kernel starts executing the signed UKI.
   • The hook extracts snigdha_verity.roothash and snigdha_verity.salt directly from the authenticated /proc/cmdline.
   • Crucial Invariant: The root hash is never loaded from an unsigned configuration file on disk. It is cryptographically anchored inside the signed PE UKI binary.

2. Block Device Mapping:

   • A read-only loop device is attached to airootfs.erofs (data_dev).
   • A read-only loop device is attached to airootfs.verity (hash_dev).

3. dm-verity Activation:

   • veritysetup open "${data_dev}" airootfs_verity "${hash_dev}" "${roothash}" --data-block-size=4096 --hash-block-size=4096 --salt="${salt}" --restart-on-corruption
   • The kernel creates /dev/mapper/airootfs_verity.

4. OverlayFS Integration:

   • /dev/mapper/airootfs_verity is mounted read-only at /run/archiso/airootfs.
   • Snigdha Amnesia creates its volatile tmpfs overlay on top of /run/archiso/airootfs:
     • lowerdir: /run/archiso/airootfs (cryptographically authenticated block device)
     • upperdir: /run/archiso/cowspace/persistent_.../upperdir (volatile RAM)
     • workdir: /run/archiso/cowspace/persistent_.../workdir (volatile RAM)

5. Telemetry & Audit:

   • The hook writes /run/snigdha/boot-integrity.json, recording the verified root hash, mapper target, and status (VERIFIED).
   • Snigdha Security Center reads this telemetry to confirm boot security posture.

---

# 4. Failure Modes & Fail-Closed Enforcement

If any data block in airootfs.erofs or any hash in airootfs.verity fails verification:

• The Linux device-mapper layer generates an EIO (I/O error) or restarts immediately (--restart-on-corruption).
• The snigdha_trust_verity initcpio hook halts boot progression.
• An explicit error banner is displayed on the console.
• Telemetry is recorded with verity_status: FAILED.
• Fail-Closed Rule: The system will never silently fall back to mounting an unverified filesystem as trusted.

---

# 5. Scope & Verification Boundaries

dm-verity provides block-level mathematical authentication for the contents of airootfs.erofs.

However, administrators and auditors must recognize the precise verification boundary:

• Protected by dm-verity: The entire immutable operating system image (/usr, /etc, /lib, /bin, desktop environment, isolation policies, and preinstalled privacy applications).
• Outside dm-verity Scope:
  • The boot medium's partition table and unverified bootloader config files (mitigated by direct UKI boot).
  • Mutable files created in RAM during the live amnesic session (protected by kernel memory mitigation and Amnesia shutdown hooks).
  • Optional encrypted persistent volumes (protected by LUKS2, Argon2id, and dm-crypt).