🔒 Two-Layer LUKS Vault with Shamir Keys

Paranoid-grade secure storage setup featuring Shamir's Secret Sharing (2-of-3) key splitting and a hidden, deniable two-layer LUKS partition layout.

Designed for Arch Linux and modern Unix-like systems

Architecture • Directory Structure • Key Features • Threat Model • Quick Start • Support

---

📸 Architecture

  Vault Drive (SSD / HDD / USB)
  ┌───────────────────────────────┬──────────────────────────────────────────┐
  │  p1: LUKS2 + ext4 (Layer 1)  │  p2: raw (Layer 2, no FS header)        │
  │  ─────────────────────────   │  ─────────────────────────────────────  │
  │  Key: Shamir master key       │  Detached header: stored in p1/.hdr/vol2.img
  │  Visible from outside: UUID   │  Visible from outside: solid urandom     │
  │  Content: regular files       │  Key: separate password (no USB sticks)  │
  │            + hidden header    │  Content: secret data                    │
  └───────────────────────────────┴──────────────────────────────────────────┘

  3× USB keys with Shamir shares (generated via forge-keys.sh)
  Any 2 of 3 keys → Shamir combine → master key → unlocks Layer 1 (p1)
  p2 without header (stored inside p1) = indistinguishable from random noise

---

📂 Directory Structure

This repository contains all the necessary utilities, scripts, and documentation to deploy, configure, and mount a two-layer encrypted system. Here is a description of the files in the repository:

🛠️ Shell Scripts

• CreateKeys/forge-keys.sh
  An interactive tool to manage 2-of-3 key splits. It generates a 512-bit master key, splits it into 3 parts via ssss-split, formats target USB drives (creating a standard partition and a RAW partition), writes key shares using wear-leveled floating offsets, and generates an encrypted GPG backup.
• OpenManually/vault-open.sh
  A script to manually mount and open the vaults. It detects connected Shamir USB drives by their PARTUUID, extracts the shares, reconstructs the master key in memory using ssss-combine, unlocks Layer 1, extracts the detached header, and prompts you to unlock the hidden Layer 2 partition.

📚 Documentation & Setup Guides

• LUKS-Manual-Setup.md
  A complete, step-by-step instruction guide to manually partition and format the Two-Layer Vault drive, prepare the detached headers, and test the mounting configuration.
• LUKS-AUTO-Unlock/Shamirs-LUKS.md
  A detailed guide on setting up automated system/root partition unlocking at boot time. Includes configurations for initramfs hooks, mkinitcpio configurations, and kernel-level BusyBox integration.
• CreateKeys/README.md
  A guide on using the key forge tool (forge-keys.sh) to generate shares, rotate keys, inspect partitions, install dependencies, and manage backups.

---

✨ Key Features

• 🔑 Shamir (2-of-3) Splitting: Your master encryption key is split into three shares. Any two shares are sufficient to open Layer 1. The theft of a single USB drive reveals no information about the key.
• 🕵️ Plausible Deniability: Layer 2 does not have a LUKS superblock on the disk (using a detached header). Without the detached header (which resides in Layer 1), Layer 2 is cryptographically indistinguishable from random noise (/dev/urandom).
• 🔄 Wear-Leveled Key Placement: The key forge script writes key shares at dynamic, floating offsets on the RAW partitions of the USB drives to prevent hardware wear on flash sectors.
• 🛡️ GPG Backup: Creates a secure, symmetric AES-256 GPG-encrypted offline backup of the master key.
• ⚡ Early Boot Hooks: Fully integrated early-boot scripts for Arch Linux mkinitcpio to unlock the main boot/root drive seamlessly.

---

🛡️ Threat Model & Security

Threat	Security Defense
Seizure of Vault Drive	Drive cannot be opened without at least 2 of the 3 USB keys.
Seizure of a Single USB Key	Individual keys contain only one share; Shamir scheme guarantees 0% key leakage.
Coerced Disclosure of Layer 2	Since the header for Layer 2 is detached and stored in Layer 1, the Layer 2 partition appears as random block noise.
Forensics on Layer 2	No LUKS signature exists on the device, ensuring plausible deniability.
Forensics on Layer 1	Hardened with LUKS2 + Argon2id + 512-bit master key.

---

🚀 Quick Start

1. Prepare USB Keys: Follow the Key Forge Guide to generate keys and write shares to your USB drives:

   sudo ./CreateKeys/forge-keys.sh setup

2. Configure Vault Drive: Follow the LUKS Manual Setup Guide to partition the drive, format Layer 1 and Layer 2, and configure the detached header.
3. Mounting the Vault: Run the manual open script:

   sudo ./OpenManually/vault-open.sh

4. Boot Autounlock: If you want to use this setup to unlock your root system partition at boot time, follow the Automatic Boot Hook Guide.

---

🤝 Contributing & Support

• Bug Reports & Feature Requests: Open an Issue.
• Discussions: Join our Discussions to ask questions.
• Contributing Guide: Review CONTRIBUTING.md for style and security rules.
• Support the Project: See SUPPORT.md for sponsorship and cryptocurrency donation details.

---

📄 License

MIT — see LICENSE.

---

Made with ❤️ for the open-source security community