airgap/README.md

AirgapOS

https://git.distrust.co/public/airgap

About

A full-source-bootstrapped, deterministic, minimal, immutable, and offline, workstation linux distribution designed for creating and managing secrets offline.

Built for those of us that want to be -really- sure our most important secrets are managed in a clean environment with an "air gap" between us and the internet with high integrity on the supply chain of the firmware and OS used.

Uses

• Generate PGP keychain
• Store/Restore gpg keychain to security token such as a Yubikey or Nitrokey
• Signing cryptocurrency transactions
• Generate/backup BIP39 universal cryptocurrency wallet seed
• Store/Restore BIP39 seed to a hardware wallet such as a Trezor or Ledger

Features

• Deterministic iso generation for multi-party code->binary verification
• Small footprint (< 100MB)
• Immutable and Diskless: runs from initramfs
• Network support and most drivers removed to minimize exfiltration vectors

Requirements

Software

• docker 26+

Hardware

• x86_64 PC or laptop
  • linuxboot/heads firmware supported and recommended for multi-use machine
    • Allows for signed builds, and verification of signed sd card payloads
  • Ensure any Wifi/Disk/Bluetooth/Audio devices are disabled/removed
• Blank flash drive
• Blank SD card

Build

Update git submodules

git submodule update --init --recursive

Build a new release

make release

Reproduce an existing release

make attest

Sign an existing release

make sign

Provisioning

1. Write airgap.iso to CD-ROM or SD Card a. dd if=out/airgap.iso of=/dev/sda bs=1M conv=sync status=progress b. cdrecord out/airgap.iso

2. Verify media still produces expected hash

sha256sum out/airgap.iso
head -c $(stat -c '%s' airgap.iso) /dev/sda | sha256sum

Setup

Assumes target is running Pureboot or Coreboot/heads

1. Boot to shell: Options -> Recovery Shell
2. Mount SD card

   mount-usb
   mount -o remount,rw /media
   

3. Insert chosen GPG Smartcard device
4. Initialize smartcard

   gpg --card-status
   

5. Sign target iso

   cd /media
   gpg --armor --detach-sign airgap.iso
   

6. Unmount

   cd
   umount /media
   sync
   

7. Reboot

Usage

1. Insert remote attestation device
2. Power on, and verify successful remote attestation
3. Boot to airgap via: Options -> Boot Options -> USB Boot

Development

Build develop image

make

Boot image in qemu

make vm

Enter shell in build environment

make shell

Writing to SD Card

1. Flash airgap.iso to an SD Card:

   • Use lsblk to find device name

   • dd if=out/airgap.iso of=/dev/<your_device> bs=4M status=progress conv=fsync

2. Use the sdtool to lock the SD Card:

   a. Get deterministically built binary of sdtool from StageX:

   • docker pull stagex/sdtool:latest

   b. Extracting binary:

   • Run docker container: docker create -p 4000:80 --name sdtool stagex/sdtool
     • Copy image to tar: docker export <container_id> -o sdtool.tar
     • Extract binary from tar: mkdir -p sdtool-dir | tar -xvf sdtool.tar -C sdtool-dir | cp sdtool-dir/usr/bin/sdtool ./sdtool
     • You can verify the container hash:
       • To get container hash: docker inspect --format='{{json .RepoDigests}}' stagex/sdtool
       • Check the signatures dir in stagex project for latest signed hashes

   c. Permanently lock the card:

   • ./sdtool /dev/mmcblk permlock

   d. Test that the card can't be written to:

   • dd if=out/airgap.iso of=/dev/sdb bs=1M status=progress conv=fsync

3. Verify that the hash of airgap.iso matches what's flashed on the SD card:

   • head -c $(stat -c '%s' out/airgap.iso) /dev/<your_device> | sha256sum

   • sha256sum out/airgap.iso

Hardware Compatibility

Tested Models

• Purism Librem 14

• HP 13" Intel Celeron - 4GB Memory - 64GB eMMC, HP 14-dq0052dx, SKU: 6499749, UPC: 196548430192, DCS: 6.768.5321, ~USD $179.99

• Lenovo 14" Flex 5i FHD Touchscreen 2-in-1 Laptop - Intel Core i3-1215U - 8GB Memory - Intel UHD Graphics, SKU: 6571565, ~USD $379.99

Disabling Secure Boot

AirgapOS can't be booted using secure boot. Therefore it has to be disabled. Alternative systems like Heads may be used.

Instructions to Disable Secure Boot in BIOS

1. Restart your computer

2. Enter BIOS/UEFI Setup:

   • As your computer starts up, press the appropriate key to enter the BIOS/UEFI setup. Common keys include:
     • F2 (Dell, Acer, Lenovo)
     • Delete (ASUS, MSI)
     • F10 (HP)
     • Esc (Some systems)
   • You may see a prompt on the screen indicating which key to press

3. Navigate to the Secure Boot Option:

   • Once in the BIOS/UEFI setup, use the arrow keys to navigate through the menus. Look for a tab or section labeled "Boot," "Security," or "Authentication."
   • The exact location of the Secure Boot option can vary, so you may need to explore a bit

4. Locate Secure Boot:

   • Find the Secure Boot option within the selected menu. It may be listed as "Secure Boot Control" or simply "Secure Boot."

5. Disable Secure Boot:

   • Select the Secure Boot option and change its setting to Disabled. This is usually done by pressing Enter and then selecting Disabled from the options.

6. Save Changes and Exit:

   • After disabling Secure Boot, navigate to the Exit tab or section.
   • Choose the option to Save Changes and Exit. Confirm any prompts that appear to save your changes.

7. Reboot Your Computer:

   • Your computer will restart. Secure Boot should now be disabled.