overhaul docs to respect current state of affairs
This commit is contained in:
parent
ba361d3db1
commit
01c292c828
95
README.md
95
README.md
|
@ -1,4 +1,4 @@
|
||||||
# Airgap #
|
# AirgapOS #
|
||||||
|
|
||||||
<https://gitlab.com/pchq/airgap>
|
<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
|
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
|
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 ##
|
## Requirements ##
|
||||||
|
|
||||||
|
@ -26,24 +39,74 @@ internet.
|
||||||
|
|
||||||
### Hardware ###
|
### 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 ##
|
## 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 ##
|
## 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 ##
|
## Development ##
|
||||||
|
|
||||||
### Boot image in qemu
|
### Build develop image
|
||||||
|
```
|
||||||
|
make
|
||||||
|
```
|
||||||
|
|
||||||
|
### Boot image in qemu
|
||||||
```
|
```
|
||||||
make vm
|
make vm
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Enter shell in build environment
|
||||||
|
```
|
||||||
|
make shell
|
||||||
|
```
|
||||||
|
|
Loading…
Reference in New Issue