airgap/README.md

131 lines
2.6 KiB
Markdown
Raw Normal View History

# AirgapOS #
2020-06-15 18:04:50 +00:00
2024-06-27 07:35:06 +00:00
<https://git.distrust.co/public/airgap>
2020-06-15 18:04:50 +00:00
## About ##
2024-06-27 07:35:06 +00:00
A full-source-bootstrapped, deterministic, minimal, immutable, and offline,
workstation linux distribution designed for creating and managing secrets
offline.
2020-06-15 18:04:50 +00:00
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.
2020-06-15 18:04:50 +00:00
## Uses ##
2024-06-27 07:35:06 +00:00
* 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
2020-06-15 18:04:50 +00:00
## Features ##
2024-03-28 23:55:28 +00:00
* 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
2020-06-15 18:04:50 +00:00
## Requirements ##
### Software ###
2024-06-27 07:35:06 +00:00
* docker 26+
2020-06-15 18:04:50 +00:00
### Hardware ###
2024-06-27 07:35:06 +00:00
* 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
2020-06-15 18:04:50 +00:00
## Build ##
2024-03-28 15:38:56 +00:00
### Update git submodules
```
git submodule update --init --recursive
```
2022-12-26 09:22:00 +00:00
### Build a new release
2024-03-28 15:38:56 +00:00
```
make release
```
2022-12-26 09:22:00 +00:00
### Reproduce an existing release
2024-03-28 15:38:56 +00:00
```
make attest
```
2022-12-26 09:22:00 +00:00
### Sign an existing release
2024-03-28 15:38:56 +00:00
```
make sign
```
2020-06-15 18:04:50 +00:00
## 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
2020-06-15 18:04:50 +00:00
## Development ##
### Build develop image
```
make
```
2020-06-15 18:04:50 +00:00
### Boot image in qemu
2020-06-15 18:04:50 +00:00
```
make vm
```
### Enter shell in build environment
```
make shell
```