USB Key Forge is a bash script for creating distributed encrypted storage with a paranoid level of protection.
It generates a random 512-bit master key, splits it into 3 parts (using Shamir's Secret Sharing algorithm), and hides it in cryptographic noise on three physical media drives (USB flash drives or SD cards). To access your data, any two of the three physical keys are always required.
Each of the three drives is partitioned exactly in half into two volumes:
- Partition 1 (LUKS2 + ext4): An encrypted "vault" for your files.
- Partition 2 (RAW + urandom): An ocean of random digital noise, inside of which (at random offsets) your key "shard" (Share) is hidden.
To prevent forensic detection and hardware wear on specific flash sectors, forge-keys.sh implements a floating layout inside the RAW partition (p2):
- Baseline Noise: The entire
p2partition is filled with cryptographically secure random noise (/dev/urandom) during setup. - Key Fragment Splitting (5 Chunks): The Shamir share string is divided into 5 chunks of 256 bytes each.
- Dynamic Offsets: These 5 chunks are written at randomized, sector-aligned (4096-byte) offsets.
- The Index Block: To locate the chunks during decryption, a fixed 512-byte Index Block is written at a hardcoded offset (
IDX_OFFSET = 8192bytes from the start ofp2). It contains 5 big-endian 64-bit pointers to the dynamic positions of the 5 chunks. The rest of the Index Block is padded with random noise to blend in. - Guard Zones: The script enforces a 128 KiB minimum gap (guard zones) between the index block and any chunk, as well as between the chunks themselves, to prevent data collision.
- Wear Leveling & Rotation: When running
rotate, the script generates new random offsets, copies the key chunks there, updates the Index Block, and overwrites the old chunk locations with fresh random noise.
A single drive on its own is completely useless. The passphrase is never stored in plain text anywhere and exists in the computer's RAM only at the moment of decryption, after which it is immediately destroyed.
Insert three USB flash drives/SD cards one by one when prompted by the script. WARNING: All data on them will be permanently deleted!
sudo chmod +x forge-keys.sh
sudo ./forge-keys.sh setupEach of the three forged USB drives contains an encrypted filesystem partition (p1) that is secured using the master key. This means the USB keys themselves double as secure portable storage vaults.
To decrypt and open the encrypted p1 storage on one of the USB keys, you must connect both that drive (holding your files) and any second key drive (to reconstruct the master key).
Connect the target storage drive (e.g., /dev/mmcblk0) and any second key drive (e.g., /dev/sda), then run the open command:
# Syntax: open <key_device_1> <key_device_2> <target_partition_p1> <volume_name>
sudo ./forge-keys.sh open /dev/mmcblk0 /dev/sda /dev/mmcblk0p1 my_vaultIf everything is correct, the script will reconstruct the key and open the disk at /dev/mapper/my_vault.
Create a directory (if it does not exist) and mount the opened disk there:
sudo mkdir -p /mnt/vault
sudo mount /dev/mapper/my_vault /mnt/vault
# IMPORTANT: On the first run, change ownership to your user, otherwise you won't be able to write anything:
sudo chown -R $USER:$USER /mnt/vaultNow you can open /mnt/vault in your file manager, copy, and delete files.
When you are finished, always close the container before removing the USB drives:
# 1. Unmount the filesystem
sudo umount /mnt/vault
# 2. Lock the vault (erasing the key from kernel memory)
sudo cryptsetup luksClose my_vaultOnly after this can the USB drives be physically disconnected from the computer.
The script contains safe tools for checking key health without the risk of damaging data.
Use this command to ensure that two specific keys can successfully reconstruct the master passphrase. This command operates in read-only mode.
sudo ./forge-keys.sh verifyThe script will prompt you to select two devices, reconstruct the key, and verify it against the LUKS header (without actually mounting anything).
Shows the physical layout of key fragments inside the RAW partition of the drive and checks for any overlapping data or conflicts.
# Replace sdX with your USB drive, e.g., sda
sudo ./forge-keys.sh inspect /dev/sdXFlash memory has a limited write cycle count for the same cells. Additionally, moving key shares is useful for cryptographic deniability.
The rotate command takes the key fragments on a specific drive, generates new random addresses for them in the RAW partition, copies the data, and overwrites the old locations with random noise.
# Recommended to run periodically (every few months)
sudo ./forge-keys.sh rotate /dev/sdXIf you lose 2 out of the 3 physical drives, data recovery will be impossible. To protect against this, a backup mechanism is provided.
During initial setup (setup), the script will offer to encrypt the master key with a password. A file named ukf-master-key-backup.gpg will be created (AES-256 encryption).
Be sure to save this file in a safe place (cloud storage, email, another hard drive).
If the keys are lost, you can use the backup file to recreate 3 new USB drives that will match your old data vaults.
# The script will automatically search for the ukf-master-key-backup.gpg file in the current directory:
sudo ./forge-keys.sh restore
# Or specify the file path manually:
sudo ./forge-keys.sh restore /path/to/your/backup_file.gpgThe system will ask you to enter the password created during backup, and will then partition the new USB drives.
The script will attempt to install them automatically on its first run:
cryptsetup— for creating and opening LUKS containers.ssss— Shamir's Secret Sharing Scheme implementation (ssss-split, ssss-combine).gnupg(gpg) — for AES-256 symmetric backup encryption.parted,xxd,util-linux,coreutils.