mathom — air-gapped PGP signing

Why

The key everything rests on shouldn't live online

In Thurin, your identity is anchored by a PGP key you control. That key signs your attestations, your releases, your statements. If it leaks, the whole identity is forfeit.

So the master key should never touch a networked machine. mathom builds a dedicated offline one: pull the wifi card, pull the drive, boot from a USB stick, and you have a machine that generates and holds your master key with no way to reach a network and no way to page secrets to disk.

Data crosses the gap by QR code, in and out, photographed by a webcam. No cable, no shared disk, no electrical path ever exists between the online world and the key. The security property is the hardware you removed. Everything the software does is defense in depth on top of that.

What it is

A readable diff, not a new system to trust

mathom is a hardened overlay on drduh/YubiKey-Guide, the canonical, community-tested guide for offline YubiKey and PGP work. You inherit its proven key-generation workflow and its guide baked into the image. mathom adds exactly the pieces that make it a one-way vault, and nothing more.

QR-first transport

Everything moves in and out as QR codes, chunked and checksummed. Optical only, so no electrical path between the online machine and the vault ever exists.

Encrypted container

Your keys live in a LUKS-encrypted file on an SD card, backed up with one command. One file to keep in the safe, one to store apart.

No network, enforced

The radio comes out. On top of that, the kernel-derived driver blacklist and disabled network services mean there is nothing left to bring an interface up.

Session discipline

Clock enforcement (GPG stamps time into keys), no suspend, lid-close to power off, no auto-mounting. Rarely opened, verifiable each time.

First question

Will it work on the laptop you own?

It depends on one thing: can the radio come out? Be honest about which tier you land on, because the claim you can defend is genuinely different for each. Older business laptops (ThinkPad T/X, Dell Latitude, HP EliteBook) usually keep the wifi card in a removable socket, which is the only route to tier 1.

Tier	What you did	What you can honestly claim
1	WLAN card physically removed	No network interface exists.
2	Antennas disconnected, kernel built without radio drivers, module loading locked	No network interface can be brought up.
3	Generated driver blacklist only	No network interface is configured.

Run vault-survey on a candidate machine for a provisional read, but software cannot see solder. The definitive test is a screwdriver.

How to build one

From an old laptop to a working vault

Start to finish, this is an afternoon. You need an x86_64 Linux machine with Nix to build the image, a spare laptop to become the vault, a USB stick, and an SD card. The full guide, threat model, and hardware notes live in the repo.

1

Pick the right laptop

You want a machine where the wifi card and the storage drive both come out. Removable storage is a free win: with no drive, no swap is possible, so key material can never be paged to disk. Old business laptops are ideal and cheap.

2

Build the ISO

On your everyday Linux machine, build the image from the pinned flake. Building it yourself is the point: you are not trusting a download.

nix build github:thurinlabs/mathom#iso

3

Write it to a USB stick

Flash the ISO to the stick that will boot the vault.

sudo dd if=result/iso/*.iso of=/dev/sdX bs=4M status=progress conv=fsync

Check the device name twice. That is the command that eats the wrong disk.

4

Open the case: pull the radio and the drive

Follow an iFixit teardown for your model. Disconnect the internal battery first, then lift the two antenna leads off the wifi card, unscrew it, and slide it out. Take the storage drive out too. Neither goes back. Bluetooth usually rides on the same module, so it leaves with it.

5

Boot and verify

Boot the USB stick and confirm the machine is what you think it is: no network hardware, loopback only, no internal disk.

vault-verify

6

Set the clock, then generate your key

Set the time first, always. GPG bakes the creation timestamp into the key and it feeds the fingerprint permanently. Then unlock the encrypted container and generate your master key, following the guide baked into the image.

vault-clock                 # set the time first
vault-open /dev/mmcblk0     # unlock the encrypted container
export GNUPGHOME=/persist/gnupg

7

Move work across the gap by QR

To sign something, render it as QR codes on your online machine, scan them in, read what you are about to sign, sign it, and send the signature back out the same way.

qr-in                       # scan a payload in through the webcam
# inspect it, then sign it
qr-out signature.asc        # display it as QR to photograph

8

Close, power off, back up

Lock the container, power off (never suspend), and copy the encrypted vault to a second card, on this machine only. Then tape the short job list inside the lid and put it away until next time.

vault-close && poweroff
vault-backup /dev/mmcblk0   # copy to the backup card, here

This is the shape of it. The full build guide covers hardware selection, the tier-2 kernel route when the radio is soldered, media choices, key-generation notes, and the printable session card. Read it before trusting the machine with a real key.

Honest limits

What the air gap does not buy you

An air gap is one strong property, not a magic one. Knowing the edges is part of using it well.

Not protection from a malicious USB device. That is why provisioning happens once, and only cards cross afterward.
Not protection from a compromised source. That is why you build the ISO yourself instead of downloading it.
Not protection from approving something you didn't read. The camera authenticates nothing. Decode and read every payload before you sign it. That step is the trust boundary.
Not protection from physical access. That is why the container is LUKS-encrypted and lives in a safe.
Not protection from evil-maid firmware attacks. That needs measured boot, which most salvaged hardware won't give you. Say so plainly.

The realistic failure mode isn't an exotic attack. It's building the vault, using it twice, then "just this once" plugging in a USB stick from your daily machine. Decide up front which jobs justify the ritual, keep the list short, and tape it inside the lid.

Build your own

Open source, MIT licensed. The overlay is the entire diff, and it is meant to be read.

View on GitHub Read the build guide

The key-generation workflow, the guide, and the Nix integration are drduh/YubiKey-Guide, which is actively maintained and excellent. mathom is a readable diff on top of it.