overhaul docs to respect current state of affairs

README.md

@@ -1,4 +1,4 @@
-# Airgap #
+# AirgapOS #
 
 <https://gitlab.com/pchq/airgap>
 
@@ -8,15 +8,28 @@ A live buildroot based distribution designed for 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.
+internet with high integrity on the supply chain of the firmware and OS used.
 
-## Use Cases ##
+## Uses ##
+ * Generate GPG 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
 
-- Generate GPG keychain
+## Features ##
-- Store/Restore gpg keychain to security token such as a Yubikey or Nitrokey
+ * Builds Coreboot-heads firmware for all supported devices for measured boot
-- Signing cryptocurrency transactions
+ * Determinsitic rom/iso generation for multi-party code->binary verification
-- Generate/backup BIP39 universal cryptocurrency wallet seed
+ * Small footprint (< 100MB)
-- Store/Restore BIP39 seed to a hardware wallet such as a Trezor or Ledger
+ * Immutable and Diskless: runs from initramfs
+ * Network support and most drivers removed to minimize exfiltration vectors
+
+## Supported Devices ##
+
+  | Device      | TPM Model      | TPM Version | Remote Attestation  |
+  |-------------|:--------------:|:-----------:|:-------------------:|
+  | Librem13v4  | Infineon 9465  | 1.2         | HOTP via Nitrokey   |
+  | Librem15v4  | Infineon 9456  | 1.2         | HOTP via Nitrokey   |
 
 ## Requirements ##
 
@@ -26,24 +39,74 @@ internet.
 
 ### Hardware ###
 
-* Any x86_64 laptop known to support Linux should work.
+* Supported PC already running coreboot-heads
-* Ideally use a coreboot compatible machine with Heads for secure boot
+  * Ensure any Wifi/Disk/Bluetooth/Audio devices are removed
-* Ensure any Wifi/Bluetooth/Audio devices are removed
+* Supported remote attestation key (Librem Key, Nitrokey, etc)
+* Supported GPG smartcard device (Yubikey, Ledger, Trezor, Librem Key, etc)
+* Blank flash drive
+* Blank SD card
+
 
 ## Build ##
 
+1. Reproduce existing release, or build fresh if never released:
+
     ```
-make all
+    make VERSION=1.0.0rc1
     ```
 
+2. Compares hashes of newly built iso/rom files with in-tree hashes.txt
+
+    ```
+    make VERSION=1.0.0rc1 verify
+    ```
+
+
 ## Install ##
 
-TBD
+1. Place contents of release/$VERSION folder on SD card
+2. Boot machine to Heads -> Options -> Flash/Update BIOS
+3. Flash firmware via "Flash the firmware with new ROM, erase settings"
+4. Insert external Remote attestation key and signing key when prompted
+6. Reboot and verify successful remote attestation
+7. Boot to shell: Options -> Recovery Shell
+8. Mount SD card
+9. Insert chosen GPG Smartcard device
+10. Sign target iso ```gpg --armor --detach-sign airgap*.iso```
+11. 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
+
+
+## Release ##
+
+1. Verify then make detached signature of given release build with:
+
+    ```
+    make VERSION=1.0.0rc1 verify sign
+    ```
+
+2. Commit signatures.
+
 
 ## Development ##
 
-### Boot image in qemu
+### Build develop image
+```
+make
+```
 
+### Boot image in qemu
 ```
 make vm
 ```
+
+### Enter shell in build environment
+```
+make shell
+```