Merge remote-tracking branch 'origin/feat/quorum-kms'

quorum-key-management/.gitignore

@@ -0,0 +1 @@
+book/

quorum-key-management/README.md

@@ -0,0 +1,15 @@
+# Quorum Key Management (QKM)
+
+Quorum Key Management (QKM) is an open source system of playbooks and tooling which
+facilitates the creation and maintenance of highly resilient Quorum-based Key
+Management Systems based on a strict threat model which can be used for a
+variety of different cryptographic algorithms.
+
+## Usage
+
+In order to read the `mdbook` run the following commands:
+
+```
+cargo install mdbook
+mdbook serve
+```

quorum-key-management/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Anton Livaja", "Lance R. Vick", "Ryan Heywood"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Quorum Key Management (QKM)"

quorum-key-management/src/SUMMARY.md

@@ -0,0 +1,43 @@
+# Summary
+* [Introduction](intro.md)
+    * [Threat Model](threat-model.md)
+    * [Selecting a Quorum](selecting-quorum.md)
+    * [Software](software.md)
+    * [Hardware](hardware.md)
+    * [Glossary](glossary.md)
+
+* [Preparations]()
+    * [Repeat Use]()
+        * [Flash PureBoot to Librem](flash-pureboot-firmware.md)
+        * [Initialize PureBoot Smart Card](initialize-pureboot-smart-card.md)
+        * [Change Smart Card PINs](setting-smart-card-pins.md)
+        * [PureBoot Restricted Boot](enable-pure-boot-restricted-boot.md)
+        * [AirgapOS Setup](repeat-use-airgapos.md)
+        * [`autorun.sh` Setup](autorun-sh-setup.md)
+        * [Secure Boot Sequence](secure-boot-sequence.md)
+        * [Selecting Locations](locations.md)
+
+    * [One Time Use]()
+        * [Procure Hardware](one-time-use-hardware-procurement.md)
+        * [AirgapOS Setup](one-time-use-airgapos.md)
+        * [Repository Setup](one-time-repository-setup.md)
+        * [Selecting Locations](one-time-use-locations.md)
+
+* [Key Ceremonies]()
+    * [Ceremony Log Template](ceremony-log-template.md)
+    * [Root Entropy Ceremonies](root-entropy-ceremonies.md)
+        * [Local Key Provisioning](local-key-provisioning.md)
+        * [Hybrid Key Provisioning](hybrid-key-provisioning.md)
+        * [Remote Key Provisioning](remote-key-provisioning.md)
+
+    * [Additional Key Ceremonies]()
+        * [Operator Key Provisioning](operator-key-provisioning.md)
+        * [Location Key Provisioning](location-key-provisioning.md)
+
+    * [Post Ceremony]()
+        * [Online Artifact Storage](public-ceremony-artifact-storage.md)
+        * [Physical Artifact Storage](physical-artifact-storage.md)
+
+* [Lifecycle Management]()
+    * [Destroying Hardware](hardware-destruction.md)
+    * [Storage Device Management](storage-device-management.md)

quorum-key-management/src/autorun-sh-setup.md

@@ -0,0 +1,44 @@
+# `autorun.sh` Setup
+
+This document describes how `autorun.sh`, a file that AirgapOS automatically
+boots and runs should be set up.
+
+This setup can be done on any machine.
+
+1. Create a file called `autorun.sh` that has the following contents:
+
+    You may accomplish this by doing the following:
+
+    * In your Terminal use this command:
+    `vi autorun.sh`
+    * Once you are in the editor press "i" to enter "insert mode"
+    * Type in the contents, replacing <N> and <M> with your chosen threshold
+    numbers according to your [Quorum](selecting-quorum.md):
+    ```sh
+    #!/bin/sh
+    keyfork wizard generate-shard-secret --threshold <M> --max <N> --output shards.pgp
+    ```
+    * Press "esc"
+    * Press ":"
+    * Press "x"
+    * Press Enter
+
+2. Hash the file
+    The file should be hashed by using the following command:
+
+    ```sh
+    sha256sum autorun.sh
+    ```
+    Make note of the hash on a piece of paper
+
+3. Copy the file to the Storage Device which contains AirgapOS.
+
+    a. If you don't have a Storage Device set up with AirgapOS use [this guide](repeat-use-airgapos.md)
+to do so.
+
+    b. Mount the AirgapOS Storage Device using [this guide](storage-device-management.md#mounting-a-storage-device)
+
+    c. Copy the `autorun.sh` file to the Storage Device
+
+4. Make note of this hash on a piece of paper or print it as you will need it to
+verify the file during Ceremonies.

quorum-key-management/src/ceremony-log-template.md

@@ -0,0 +1,62 @@
+# Ceremony Log Template
+
+This template is to be used during the ceremony in order to keep track of events
+that take place during the Key Derivation Ceremony.
+
+Capture as much information as possible - more data is always better than less,
+this means being specific about the exact location, full names of participants,
+exact models of equipment used etc.
+
+## Date
+
+```
+2024-08-03
+```
+
+## Individuals Present
+Individuals may be Operators or Witnesses. Include the individual's full legal
+name
+
+```
+Max Rockatansky - Witness
+Paul Atreides - Operator
+```
+
+## Location
+Specify exact location, including details such as the floor, room etc.
+
+```
+12 Grimmauld Place, Islington, London
+2nd floor, first room on the left when coming up the stairs
+```
+
+## Equipment
+
+### Type of Laptop Used
+
+```
+Purism Librem 14
+```
+
+### Type of SD Card Used
+
+```
+SD Card: Kingston SDCIT2/8GBSP
+```
+
+## Software
+Specify the exact version / commit
+
+```
+AirgapOS: https://git.distrust.co/public/airgap/commit/df223e6deb2833a8160c836f435ee01f7b776e87
+```
+
+## Chronological Timeline
+Ensure to capture as much details as possible, even if it seems trivial.
+
+* 2024-01-01:0900: The team assembles at the airport and selects the location
+from a pre-made list of potential locations
+* 2024-01-01:1030: The team arrives at location and inspects the premises for
+cameras and ensures that the location criteria are adhered to
+* 2024-01-01:1440: The hardware is set up and the software and firmware are
+verified

quorum-key-management/src/enable-pure-boot-restricted-boot.md

@@ -0,0 +1,8 @@
+# Enable PureBoot Restricted Boot
+
+With PureBoot Restricted Boot, you can lock down your boot firmware to only boot
+trusted, signed executables both on a local disk and USB, so you control the
+keys.
+
+In order to enable Restricted Boot, the user may follow the Purism guide found
+[here](https://docs.puri.sm/PureBoot/Restricted.html).

quorum-key-management/src/flash-pureboot-firmware.md

@@ -0,0 +1,36 @@
+# Flash Pureboot Firmware
+
+The version required for being able to complete all steps for setting up the
+Ceremony Machine using a Librem 14:
+* https://source.puri.sm/firmware/releases/-/blob/PureBoot-Release-24-L14JackDetect-1/librem_14/pureboot-librem_14-Release-24-L14JackDetect-1.rom.gz?ref_type=heads
+
+If another type of hardware is used you may have to try different versions of
+the PureBoot firmware as some have issues with the `/etc/gui_functions` and `/etc/functions` which are used during the [Secure Boot Sequence](secure-boot-sequence.md)
+
+## Steps
+
+1. Download the [.rom](https://source.puri.sm/firmware/releases/-/blob/PureBoot-Release-24-L14JackDetect-1/librem_14/pureboot-librem_14-Release-24-L14JackDetect-1.rom.gz?ref_type=heads) file
+
+2. Put the `.rom` file on a Storage Device
+
+3. Plug the Storage Device with the `.rom` file into the Librem 14
+
+4. During boot, press *any* key when prompted
+
+5. Select "Options -->", press Enter
+
+6. Select "Flash/Update the BIOS -->", press Enter
+
+7. Select "Flash the firmware with a new ROM, retain settings"
+
+8. "You will need to insert a USB drive containing your BIOS image (*.rom...)
+    After you select this file, this program will reflash your BIOS.
+    Do you want to proceed?"
+
+    * Select "Yes", Press Enter
+
+9. Select the `.rom` file and press Enter
+
+10. Do you wish to proceed?
+
+    * Select "Yes", Press Enter

quorum-key-management/src/flashing-iso.md

@@ -0,0 +1,21 @@
+4. Flash ISO Image to a Storage Device
+
+    a. Select a new Storage Device which can be overwritten entirely
+
+    b. Find the name of the Storage Device using [this guide](storage-device-management.md#finding-a-storage-device-name)
+
+    d. Use the `dd` utility in the Terminal to flash AirgapOS to it. You will need
+    to replace `<your_storage_device>` with the name of your device.
+
+    ```bash
+    sudo dd bs=4M if=~/airgap/dist/airgap.iso of=/dev/<your_thumb_drive> status=progress
+    ```
+
+    In the example, the name of the device is `sda` so the complete command would look like this:
+
+    ```bash
+    sudo dd bs=4M if=~/airgap/dist/airgap.iso of=/dev/sda status=progress
+    ```
+
+    Once this step is complete, you have successfully set up a Storage Device
+    with AirgapOS.

quorum-key-management/src/glossary.md

@@ -0,0 +1,108 @@
+# Glossary
+
+## Ciphertext
+In cryptography, ciphertext is the result of encryption performed on plaintext
+using an algorithm, called a cipher.
+
+## Quorum Key Management (QKM)
+A set of highly specified processes and tooling used for setting up a highly
+resilient quorum-based key management system.
+
+## Operator
+An individual who manages an [Operator Key](#operator-key) which is used for
+protecting the passphrase of a Location key and participates in different
+aspects of the lifecycle management of the QKM system.
+
+## Operator Key
+An asymmetric key used for protecting the passphrase of a Location key
+
+## Quorum
+The chosen M of N threshold used to achieve "quorum", which is a type of
+agreement or consensus between a group of individuals. In the context of
+Shamir's Secret Sharing, it refers to the minimum number of shards required to
+reassemble the [Root Entropy](#root-entripy-re).
+
+#### Wrench Factor
+How many people are required to be put under duress (via smacking them with a
+wrench repeatedly or otherwise to get access to their Shard) before the Disaster
+Recover Key is compromised.
+
+#### Bus Factor
+How many members of the Quorum can meet an untimely demise without irretrievably
+locking access to the Distrust Quroum system.
+
+## Root Entropy (RE)
+The main entropy/randomness which is used for hierarchical deterministic key
+derivation of a variety of cryptographic algorithms.
+
+## Shard
+Crytpographic shard created using Shamir's Secret Sharing algorithm.
+
+## Shamir's Secret Sharing (SSS)
+An algorithm used to split cryptographic material into shards which can be
+used to reassemble a secret. The shards can be combined according to a threshold
+which is set at the time of initial sharding, expressed as M of N, or in other
+words M shards of the total N shards in existence are required to reveal the
+secret.
+
+## Workstation
+Highly secure computer which is used for sensitive operations, typically in the
+context of [Production Engineering](TODO).
+
+#### Minimum
+In order to set up a Workstation, as part of a [Production Engineering](TODO) setup,
+a separate computer only used for carrying out sensitive operations should be used.
+
+#### Recommended
+Setting up a computer with QubesOS is recommended as it makes it easy to create
+purpose built environments with minimal surface area for attacks, on the OS, and
+networking level.
+
+## Air-Gapped
+Hardware which has no access to radio frequency or cable based networking
+capabilities in order to reduce area for surface attacks. Typically Air-Gapped
+computers are laptops which are never connected to the internet or any other
+networks, and have had their radio frequency hardware permanently disabled or
+ideally removed.
+
+## Key Derivation Ceremony
+Highly specified process which is used to secure derivation of cryptographic
+material, with a focus on ensuring no single party has access to the Disaster
+Recovery Key. The ceremony includes witnesses who can help attest to the fact
+that the ceremony was executed properly, as well as instructions on hardware,
+software and location that should be used. Each step of the ceremony is
+carefully planned, and executed accordingly.
+
+## Location Key
+Is a asymmetric key pair which is used for encrypting shards which are used to
+re-assemble the Root Entropy. Location Keys are stored in [Locations](locations.md)
+which adhere to a strict set of criteria to maximize their security. The location
+smart card passphrase is encrypted to a Operator Key in order to secure access
+to it.
+
+## M of N
+M is the minimum number of shards required to reassemble the secret, and N is the
+total number of shards that exist. The minimum recommended threshold is 2-of-3.
+
+## Organization
+An organization which owns the QKM and is responsible for funding the setup and
+maintenance. The organization is also responsible for ensuring that the
+[Warehouse](#warehouse) is properly maintained in order to ensure that the
+ciphertext blobs associated with the system are redundantly stored and
+protected.
+
+## Witness
+An individual who attests the ceremony was performed according to specification
+in order to have additional assurances the cryptographic material, most
+importantly the Root Entropy was never exposed.
+
+## Warehouse
+* Online storage for encrypted data replicated across multiple providers
+* All data in DR Warehouse can only be decrypted by the DR Key
+* Tolerate loss of any single provider by duplicating data to all of them
+* Storage backends can be any combination of the following:
+    * S3 Compatible object stores:
+        * AWS, Google Cloud, DigitalOcean, Azure, etc.
+* [Version Control Systems](software.md#version-control-system-vcs):
+* We tolerate a loss of all but one DR storage backend
+* A minimum of three storage backends should be maintained

quorum-key-management/src/hardware-destruction.md

@@ -0,0 +1,19 @@
+# Destroying Hardware
+
+Destroying hardware should be done by using a combination of:
+
+* Degaussing
+
+* Burning
+
+* Shredding
+
+All three methods should be used because of the efficacy of using electron
+microscopy to read data from storage drives which have not been completely
+destroyed.
+
+Drilling through the storage drive, a common hardware destruction method, is not
+considered to be secure.
+
+In the best case scenario, the hardware should be melted in a foundry, as this
+makes it impossible to retrieve any data by any means.

quorum-key-management/src/hardware.md

@@ -0,0 +1,98 @@
+# Hardware
+
+This page describes different equipment which is required, and makes opinionated
+recommendations as well as alternatives. One may improve the overall security
+of their system by using a variety of hardware in order to benefit from their
+diversity, by reducing the likelihood that all hardware has suffered the same
+kind of hardware supply chain compromise, has the same vulnerability present, or
+has the same type of hardware failure issue.
+
+Based on the decided upon [Quorum](selecting-quorum.md), the amount of equipment
+required to set up a [QKM](glossary.md#quroum-kms-QKM) will
+vary. In order to figure out what equipment is required, decide on a Quorum,
+which is expressed as "N of M". Once you know your M, the required equipment list
+is the following:
+
+* M x 4 Smart Cards
+
+    * It is recommended to use two Smart Cards for storing each key pair
+
+    * Ideally two different types of hardware are used in order to reduce the
+    risk of simultaneous failure
+
+    * At least 1 Smart Card is required for each Operator Key and 1 Smart Card
+    for each Location Key
+
+    * The number of Operator Keys is M, and the number of Location Keys is also
+    M, hence the minimum of 2 x M Smart Cards, with the recommendation of using
+    two smart cards for each, resulting in 4 x M Smart Cards
+
+* 2 + X Storage Devices
+
+    * 1 Storage Device for [AirgapOS](repeat-use-airgapos.md)
+
+    * 1 Storage Device for storing [Public Ceremony Artifacts](public-ceremony-artifact-storage.md)
+
+    * X, or *any* number of additional Storage Devices to duplicate the data, a
+    good measure would be to have at least 3 Storage Devices for the ceremony
+
+* Librem 14 Laptop
+
+    * Get as many laptops as desired to satisfy your operational needs
+
+    * For each Librem 14, get a Librem Smart Card used for [PureBoot](initialize-pureboot-smart-card.md)
+
+## Smart Cards
+
+Smart Cards are primarily used for storing OpenPGP cryptographic keys which are
+used as a building block for security controls. These smart cards hold OpenPGP
+keys which are derived in secure environments.
+
+There are two primary requirements for smart cards:
+
+* FIPS 140-2
+
+* Support for Ed25519 OpenPGP
+
+* Touch for enacting operations
+
+Some options include:
+
+* NitroKey 3 - because of its open source approach which helps improve the
+overall security of the products
+
+* YubiKey 5 - because of the widespread use and battle-tested reliability
+
+* Librem Key - because of the manufacturer's approach to hardware supply chain
+security and verifiable software
+
+## Air-Gapped Computer
+[Air-Gapped](glossary.md#Air-Gapped) computers are used for the lifecycle management
+of cryptographic material that is part of QKM.
+
+The primary hardware recommendation for a Air-Gapped Computer is the [Librem 14](https://puri.sm/products/librem-14/), manufactured by [Purism](puri.sm). Purism specializes in reducing hardware and
+firmware security risks, especially via their [Anti-Interdiction Service](https://puri.sm/posts/anti-interdiction-services/) and [PureBoot](https://docs.puri.sm/PureBoot.html)
+and as such is an excellent choice for hardware which high integrity assurance is
+required for.
+
+#### Alternative
+
+An alternative approach is to use an off-the-shelf computer that is randomly
+selected right before the ceremony, removing the radio cards from it, using it
+to conduct a Ceremony, and then destroying the laptop using sufficiently
+adequate method to ensure that no data forensics can be used to recover the data
+from the drive, or memory. This can be achieved by using a combination of
+incineration, degaussing, shredding and drilling. Special care should be taken
+to completely destroy all components of the computer that are able to store data,
+even if it's only in ephemeral form as some forensic methods all extraction of
+data from components with "temporary memory".
+
+Three letter agencies are known to collect and exploit physical destroyed drives,
+as data can still be extracted from them using methods such as electron
+microscopy, therefore a combination of degaussing, shredding and burning should
+be used, and the remaining debris should be spread out across multiple disposal
+locations.
+
+## Storage Device
+Can be an SD Card or USB Drive but should be procured from a vendor with
+a good reputation, and ideally hardware of industrial grade should be prioritized.

quorum-key-management/src/hybrid-key-provisioning.md

@@ -0,0 +1,77 @@
+# Hybrid Key Provisioning
+
+This document contains instructions on how Operators collaborate to set up
+QKM where the Operator Keys and Location Keys were generated before this
+ceremony and only the PGP Public Certificates of the Location keys are brought
+to the ceremony which are used to shard the Root Entropy. This is useful
+when conducting the ceremony in a lower trust environment, and where not all
+aspects of the ceremony can be controlled to the desired degree.
+
+## Steps
+
+1. Prior to the ceremony, set up a git repository with relevant artifacts in it,
+and create Ceremony Notes according to [this](one-time-repository-setup.md)
+guide.
+
+2. Ensure there are additional witnesses for the ceremony, outside of the
+operators to assist in monitoring and verifying the integrity of the process.
+
+    * Designate at least 1 individual to keep notes on the ceremony based
+    on the [Ceremony Log Template](ceremony-log-template.md)
+
+3. Ensure that no participants have brought digital devices other than ones
+necessary for the ceremony. A faraday bag may be used to hold any such devices
+for the duration of the ceremony.
+
+4. Procure a laptop and SD cards (3) from a randomly selected store and
+ensure at least 2 people are in line of sight of all the hardware until the
+ceremony is executed. It may be worthwhile to try booting from the SD card at
+the store. Dell laptops tend to support booting from SD cards while Lenovo
+don't. More notes on selecting hardware can be found [here](one-time-use-hardware-procurement.md)
+
+5. Secure a [Location](one-time-use-locations.md)
+
+6. Each member needs to bring their:
+
+    * Ceremony Notes
+
+    * Ceremony SD Card
+
+    * Airgap SD Card (only 1 member needs to bring this - set up according to
+    [One Time Use / AirgapOS Setup](one-time-use-airgapos.md)).
+
+7. Verify the SD card by either:
+
+    * Booting a separate AirgapOS to the machine used for the ceremony in order
+    to verify the SD card is not writeable and the hash matches using the steps
+    from the [One Time Use/ AirgapOS Setup](one-time-use-airgapos.md) guide.
+
+        OR
+
+    * Mounting the SD card to a separate machine and verifying it's not
+    writeable  and verify the hash matches using steps from the [One Time Use/AirgapOS Setup](one-time-use-airgapos.md) guide.
+
+    * NOTE: It is essential that the SD card remain in line of sight from the
+    moment it is verified to the moment is is used.
+
+8. Plug in and boot from Airgap SD card:
+
+    * Boot from internal SD card reader or USB device reader
+
+    * Verify the `sha256sum ceremony.sh` hash matches each of the Operator's
+    "Ceremony Notes"
+
+9. Button mash to ensure adequate entropy on the OS
+
+10. Set the system time as it has to be after the PGP
+public certificates were created, and before they expire:
+
+    * `date -s "YYYY-MM-DD HH:MM:SS"`
+
+10. Run `ceremony.sh`
+
+11. Back up the `shardfile`, and `pub.asc` to 3 separate SD cards,
+one for each operator
+
+12. Destroy the computer according to [Hardware Destruction](hardware-destruction.md)
+guide.

quorum-key-management/src/initialize-pureboot-smart-card.md

@@ -0,0 +1,151 @@
+# PureBoot Setup
+
+This guide walks the user through setting up a machine which relies on
+[PureBoot](https://source.puri.sm/firmware/pureboot) to verify the authenticity
+of the .iso image which is being booted, as well to ensure that firmware of the
+machine has not been tampered with between uses.
+
+This guide assumes the use of a Purism machine, with a Librem Key.
+
+## Requirements
+
+* 1 Storage Device
+
+* 1 Librem Smart Card
+
+* 1 Librem 14 Computer with [PureBoot firmware installed](flash-pureboot-firmware.md).
+
+## Notes
+
+After you complete this setup, the Librem Smart Card will be provisioned with a
+new GPG key pair, which will be used for signing the BIOS, as well as any `.iso`
+images which will be booted using the [Restricted Boot](https://docs.puri.sm/PureBoot/Restricted.html)
+mode.
+
+At the end of this guide you will have:
+
+* 1 Librem Smart Card
+
+    * With a newly generated GPG key pair
+
+    * With a newly generated HOTP secret
+
+* 1 storage device with the public key of the newly generated GPG key
+
+    * This GPG key will be used to sign `.iso` files booted on the machine
+
+## Steps
+
+1. Plug in the Librem Smart Card into the machine
+
+2. Turn on the machine
+
+3. Wait for the prompt that says "Automatic boot in 5 seconds unless interrupted
+by keypress..."
+
+    * Press *any* key
+
+4. Select "Options -->"
+
+    * Press Enter
+
+5. Select "GPG Options" -->
+
+    * Press Enter
+
+6. Select "Generate GPG keys manually on a Librem Key"
+
+    * Press Enter
+
+7. Please Confirm that your GPG card is inserted [Y/n/]
+
+    * Input "Y", press Enter
+
+8. $ gpg/card>
+
+    * Input `admin`, press Enter
+
+9. $ gpg/card>
+
+    * Inpuut `generate`, press Enter
+
+10. Make off-card backup of encryption key (Y/n):
+
+    * Input "n", Press Enter
+
+11. Replace existing keys? (y/n):
+
+    * Input "y", press Enter
+
+12. PIN: <user pin> (default is 123456)
+
+    * Input `user_pin`, press Enter
+
+13. Key is valid for? (0):
+
+    * Press Enter
+
+14. Key does not expire at all. Is this correct? (y/N):
+
+    * Input "y", press Enter
+
+15. Real name: <name>
+
+    * Note: You must supply at least one of the "Real name", "Email address"
+        or "Comment"
+    * Input one of the values, and press Enter
+
+16. Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit?
+
+    * Input "O", press Enter
+
+17. Admin PIN: <admin pin> (default is 12345678)
+
+    * Input `admin_pin`, press Enter
+
+18. After step q, the generation of the key will take some time then you will
+see a prompt:
+    ```
+    gpg: key<ID> market as ultimately trusted
+    gpg: directory '//.gnupg/openpgp-revocs.d' created
+    gpg: recovation certificate stored as '//.gnupg/openpgp-revocs.d/<ID>.rev'
+    public and secret key created and signed
+    ```
+
+19. $ gpg/card>
+
+    * Input "quit", press Enter
+
+20. "Would you like to copy the GPG public key you generated to a USB disk?
+       You may need it, if you want to use it outside of Heads later.
+       The file will show up as <ID>.asc"
+
+    * Ensure a USB drive is connected
+
+    * Select "Yes", press Enter
+
+21. "Would you like to add the GPG public key you generated to the BIOS?
+        This makes it a trusted key used to sign files in /boot"
+
+    * Select "Yes", press Enter
+
+22. "Would you like to update the checksum and sign all of the files in /boot?
+        You will need your GPG key to continue and this will modify your disk
+        Otherwise the system will reboot immediately."
+
+    * Select "Yes", press Enter
+
+23. Please confirm that your GPG card is inserted [Y/n]:
+
+    * Input "Y", press Enter
+
+24. After the computer reboots you will be faced with an error:
+    "ERROR: PureBoot couldn't generate the TOTP code."
+
+    * Select "Generate new HOTP/TOTP secret", press Enter
+
+25. "This will erase your old secret and replace it with a new one! Do you want
+to proceed?"
+
+    * Select "Yes", press Enter
+

quorum-key-management/src/intro.md

@@ -0,0 +1,69 @@
+# Introduction
+
+Quorum Key Management (QKM) is an open source system of playbooks and
+tooling which facilitates the creation and maintenance of highly resilient
+Quorum-based Key Management Systems based on a strict [threat model](threat-model.md)
+which can be used for a variety of different cryptographic algorithms. The
+system was designed and developed by [Distrust](https://distrust.co), with the
+generous support of the following sponsors: TODO.
+
+The basic premise of QKM is that primary cryptographic material akin to a root
+certificate, called Root Entropy, is derived during a secure key derivation
+ceremony, and then used to derive chosen cryptographic material via different
+algorithms such as PGP keys, digital asset wallets, web certificates and more.
+The system was designed with extensibility in mind.
+
+The Root Entropy is sharded using [Shamir's Secret Sharing](glossary.md#shamirs-secret-sharing-sss) to a [Quorum](glossary.md#quorum) in order to
+protect it from single points of failure, requiring cooperation of multiple
+individuals - a quorum, and use of cryptographic material stored in separate
+physical locations with significant access controls in order to reconstruct the
+secret material, namely the Root Entropy.
+
+## Use Cases
+
+QKM can be used for a wide range of use-cases which span but are not limited
+to:
+
+* Deriving a PGP key pair whose public key can be used as a "one-way deposit
+box" - for example a company can back up keys for their digital asset wallets by
+encrypting them to the public key and storing the encrypted ciphertext blobs on
+multiple cloud storage platforms, or on offline hard drives for redundancy.
+
+* Deriving PGP keys for multiple individual users in a deterministic manner.
+
+* Deriving wallets for digital assets using BIP-0032 style derivation as part of
+a cold signing setup.
+
+* Decrypting data in a secure, quorum protected, air-gapped environment.
+
+* Generating digital certificates
+
+## Playbooks
+
+QKM can be set up by using a set of highly opinionated playbooks which outline
+the process. The documentation should be read in its entirety by all
+participants in the ceremony in order to ensure that the system is well
+understood by all in order to ensure that the integrity of the process is
+preserved and enforced by all participants.
+
+## Directives
+
+The documentation provides directives in order to specify the importance of
+adhering to parts of the specification as follows to achieve high levels of
+security:
+
+* **MUST** - not adhering to this will result in significant deterioration of
+security properties of the system
+
+* **SHOULD** - is recommended and may impact the security of the system
+depending on the context
+
+* **MAY** - is typically a design decision with no significant impact to the
+overall security of the system
+
+## Method
+
+The reader is encouraged to read through the entire body of documents which
+should not take more than 30 minutes. If any parts are unclear, they may contact
+Distrust for clarification, which is welcomed as it will aid improving the
+documentation.

quorum-key-management/src/local-key-provisioning.md

@@ -0,0 +1,53 @@
+# Local Key Provisioning
+
+This document contains instructions on how Operators collaborate to set up
+QKM which requires an N-of-M quorum to be reconstituted. The encrypted shards
+which result from this ceremony are stored in separate physical
+[Locations](locations.md) which contain [Location Keys](glossary.md#location-key)
+to which shards are encrypted, and whose passphrases are protected using
+[Operator Keys](glossary#operator-key).
+
+
+### Requirements
+
+* [Smart Card](hardware.md#smart-cards): whatever number of smart
+cards you would like to have seeded for each Operator, usually 2 per Operator is
+recommended - one NitroKey 3 and 1 YubiKey Series 5.
+
+* [Storage Devices](hardware.md#storage-device): as many storage
+devices as you would like for backing up [Public Ceremony Artifacts](public-ceremony-artifact-storage.md)
+
+* Storage Device loaded with
+	* [airgap.iso](repeat-use-airgapos.md)
+	* [airgap.iso.asc](repeat-use-airgapos.md)
+	* [autorun.sh](autorun-sh-setup.md)
+
+* All participants need Ceremony Notes which contain a record of which they
+verified and wrote down themselves:
+	* The SHA256 hash of airgap.iso
+	* The SHA256 hash of autorun.sh
+
+### Steps
+
+1. Bring the Ceremony Machine and [Quorum Team](quorum-team.md) into the
+established [Location](locations.md)
+
+2. Ensure that no participants have brought digital devices other than ones
+necessary for the ceremony. A faraday bag may be used to hold any such devices
+for the duration of the ceremony.
+
+3. Plug in a new Storage Device
+
+4. Boot your Ceremony Machine using [Secure Boot Sequence](secure-boot-sequence.md)
+
+5. As prompted plug in new Smart Cards
+
+6. Once the ceremony is complete, make as many copies of the Storage Device
+from Step 3 as desired.
+
+7. Follow the [Physical Artifact Storage](physical-artifact-storage.md) guide
+ for storage of the Operator Smart Cards and Location Smart Cards
+
+8. Follow the [Public Ceremony Artifacts Storage](public-ceremony-artifact-storage.md)
+guide for all public artifacts produced during the ceremony
+

quorum-key-management/src/location-key-provisioning.md

@@ -0,0 +1,119 @@
+# Location Key Provisioning
+
+## Description
+This ceremony is for generating Location Keys. Location Keys are typically
+stored in vaults as prescribed in the [Secure Storage Guidelines](secure-storage-guidelines.md).
+Location Keys are keypairs to which the Root Entropy of a QKM is sharded. The
+keypairs are stored exclusively on Smart Cards, and the PINs which protect the
+Smart Cards are encrypted to Operator Keys.
+
+## Requirements
+* Smart Card(s): whatever number of smart cards you would like to have seeded
+for each Operator, usually 2 per Operator is recommended - one NitroKey 3 and
+1 YubiKey Series 5.
+
+* [Storage Devices](equipment.md#storage-device): as many storage devices as you
+would like for backing up [Public Ceremony Artifacts](public-ceremony-artifact-storage.md)
+
+## Steps
+
+1. Bring the Ceremony Machine and [Quorum Team](quorum-team.md) into the
+established [Location](locations.md)
+
+2. Boot your Ceremony Machine using [Secure Boot Sequence](secure-boot-sequence.md)
+or the [One Time Use Airgap-OS](one-time-use-airgapos.md)
+
+3. Provision new key in the selected secure environment
+
+    * Set system time to date greater than operator key creation but less than
+    operator key expiry
+
+        * `date -s "YYYY-MM-DD HH:MM:SS"`
+
+    * Load your personal PGP certificate which will be used as the Operator
+    Key in to the local keyring
+
+        * `gpg --import /media/<operator_key_id>`
+
+    * Generate the mnemonic:
+
+        * `keyfork mnemonic generate --size 256 > mnemonic.txt`
+
+    * Write the mnemonic on a small piece of paper as you will need to enter the
+    words in the next step. After entering the words, set the piece of paper
+    on fire (that's why it should be small enough - to make burning it easy)
+
+    * In a new terminal window start `keyfork` daemon with the mnemonic:
+
+        * `export KEYFORKD_SOCKET_PATH=/tmp/keyforkd.socket`
+
+        * `keyfork recover mnemonic`
+
+        * ctrl + z
+
+        * `bg`
+
+    * Derive PGP keypair:
+
+        * `keyfork derive openpgp "Location Key: Distrust Disaster Recovery" > location.priv.asc`
+
+    * Provision two YubiKey:
+
+        * To get the `smart_card_id`: `oct list`
+
+        * `oct admin --card <smart_card_id> import location.priv.asc`
+
+        *  `keyfork mnemonic generate --size 256 | awk '{ print $1, $2, $3, $4, $5 }' > smart-card-pin.txt`
+
+        * `cat smart-card-pin.txt`
+
+        * `oct pin --card <smart_card_id> set-user`
+
+            * Enter the <smart_card_pin>
+
+        * `oct pin --card <smart_card_id> set-admin`
+
+            * Enter the <smart_card_pin>
+
+    * Import PGP key into keyring
+
+        * `gpg --import location.priv.asc`
+
+    * Encrypt and back up the `mnemonic.txt`
+
+        * `gpg -er <operator_key_id> mnemonic.txt`
+
+        * `cp mnemonic.txt.gpg /media`
+
+    * Encrypt and back up the `smart-card-pin`
+
+        * `gpg -er <operator_key_id> smart-card-pin.txt`
+
+        * `cp smart-card-pin.txt.gpg /media`
+
+    * Export and back up `location.pub.asc`
+
+        * `gpg --armor --export <location_key_id> > location.pub.asc`
+
+        * `cp location.pub.asc /media`
+
+    * Duplicate all backup files to a second SD card:
+
+        * `mnemonic.txt.gpg`, `smart-card-pin.gpg`, `location.pub.asc`
+
+    * Copy the `location.pub.asc` to the SD card that was used to bring over
+    the operator key. This will be used to bring the public key to the Hybrid
+    Ceremony Later on:
+
+        * `cp location.pub.asc /media`
+
+    * For posterity, delete all the generated assets before shutting down
+    computer:
+
+        * `rm -rf *`
+
+4. Follow the [Physical Artifact Storage](physical-artifact-storage.md) guide
+ for storage of the Operator Smart Cards and Location Smart Cards
+
+5. Follow the [Public Ceremony Artifacts Storage](public-ceremony-artifact-storage.md)
+guide for all public artifacts produced during the ceremony

quorum-key-management/src/locations.md

@@ -0,0 +1,72 @@
+# Location
+
+Locations refer to physical points in space which are used for storing
+cryptographic material  or performing actions related to the DRK lifecycle and
+adhere to a set of criteria which focus on achieving a high level of security -
+specifically with respect to:
+
+* Protecting access to devices which store cryptographic material
+
+* Mitigating the risk stemming from natural disaster and other black swan events
+such as civil unrest or war.
+
+* Reducing the risk of exposing cryptographic material, for example via
+side-channel attacks
+
+There are three sub-types of Locations, one which is used for performing
+any actions related to the management of the cryptographic material life-cycle
+and is referred to as the Management Location, one for long term secure
+storage of cryptographic material such as Smart Cards which are used to decrypt
+[Shards](glossary.md#shard), referred to as a Storage Location, and a location
+for Ceremonies, known as the Ceremony Location.
+
+The Storage Location has a shorter list of requirements while the Management
+and Ceremony locations have a number of additional requirements. The Management
+and Ceremony Location may be one and the same.
+
+## All Locations
+
+* MUST have physical access restrictions which require identification
+
+* MUST have the ability to require more than 1 person to gain access
+
+    * This control can be both physical, for example in vaults which require 2
+    keys for access AND/OR process level, where the personnel of the facility
+    may verify the identity of one or more individuals
+
+* SHOULD have anti-fire systems
+
+* SHOULD have anti-flood systems
+
+
+## Management & Ceremony Locations
+
+* MUST not have cameras installed
+
+* MUST not have windows with direct line of sight to monitors
+
+* MUST have all walls protected with EM shielding which adheres to the TEMPEST
+standard NATO SDIP-27 Level A
+
+* SHOULD be organizations which are ideally immune to being legally subpoenaed
+
+* SHOULD NOT be susceptible to being subpoenaed
+
+## Storage Location
+
+* MUST have anti-fire systems
+
+* MUST have anti-flood systems
+
+* MUST have 24/7 security monitoring
+
+* MUST be in different geographic locations
+
+    * This ensures that natural disasters are not likely to impact multiple
+    locations simultaneously
+
+* SHOULD be facilities owned by different organizations to reduce the risk of
+collusion unless the organization who owns the DRK has their own facility such
+as a SCIF (Secure Compartmentalized Information Facility)
+
+* SHOULD have seismic detectors

quorum-key-management/src/one-time-repository-setup.md

@@ -0,0 +1,54 @@
+# Repository Setup
+
+Before the one time ceremony, a git repository should be set up which contains
+several items which will be relevant to the ceremony. Namely the following:
+
+* PGP public certificates of the Location Keys which will be used for the
+ceremony. The key ids of these certificates will be verified during the
+ceremony.
+
+* `ceremony.sh` a script which imports the PGP public certificates of the
+location keys, and displays their ids so that Operators can verify that they are
+the correct ones. This script will also execute the appropriate `keyfork`
+command with a desired threshold:
+    ```
+    #!/bin/sh
+
+    script_dir="$(dirname "$(realpath "$0")")"
+
+    read -p "Provide the absoute path to PGP certificates which will be used for the ceremony: " directory_path
+
+    if [ ! -d "$directory_path" ]; then
+        echo "Directory does not exist. Please enter a valid directory path."
+        exit 1
+    fi
+
+    for file in "$directory_path"/*; do
+    if [ -f "$file" ]; then
+        echo "Processing file: $file"
+        gpg --import --import-options import-show $file
+    fi
+    done
+
+    read -p "Do the PGP key IDs match what you expect? (y/n): " matches_expectation
+
+    if [ $matches_expectation != "y" ]; then
+    echo "Ceasing ceremony as PGP key IDs don't match"
+    exit 1
+    fi
+
+    keyfork wizard bottoms-up --threshold 2 --output-cert /media/cert --output-shardfile /media/shardfile --user-id "Distrust Key Ceremony" public-certificates/
+    ```
+
+* The `airgap.iso` which is to be used during the ceremony
+
+* Each operator should produce Ceremony Notes which contain:
+
+    * `sha256sum` of `airgap.iso`
+
+    * The AirgapOS commit and date for the version that was used
+
+    * `sha256sum` of `ceremony.sh`
+
+    * Key ID of each PGP Public Certificate located in `public-certificates`
+    in the ceremony repository

quorum-key-management/src/one-time-use-airgapos.md

@@ -0,0 +1,38 @@
+# Set up AirgapOS
+
+Because without a Librem 14 there is no easy way to have a secure boot sequence,
+instead the AirgapOS `.iso` image is flashed to an SD card, locked using
+`sdtool` and then verified using any machine.
+
+## Setup Steps
+
+* Clone the latest AirgapOS version:
+
+    * `git clone git@distrust.co:public/airgap.git`
+
+* Build the image:
+
+    * `cd airgap && make`
+
+* Flash `airgap.iso` to an SD Card:
+
+    * `dd if=out/airgap.iso of=/dev/<your_device> bs=4M status=progress oflag=direct`
+
+* Use the `sdtool` to lock the SD Card:
+
+    * `git clone git@github.com:BertoldVdb/sdtool.git`
+
+    * `cd sdtool`
+
+    * `make`
+
+    * `./sdtool /dev/mmcblk permlock`
+
+    * Test that the card can't be written to:
+
+        * `dd if=out/airgap.iso of=/dev/sdb bs=1M conv=sync status=progress`
+
+* Verify that the hash of `airgap.iso` matches what's flashed on the SD card:
+
+    * `head -c $(stat -c '%s' out/airgap.iso) /dev/sdb | sha256sum`
+    * `sha256sum out/airgap.iso`

quorum-key-management/src/one-time-use-hardware-procurement.md

@@ -0,0 +1,33 @@
+# Procure Hardware
+
+* Procure a laptop, and SD cards from a randomly selected store. A randomly
+selected store is used in order to reduce the possibility of a malicious actor
+having time to plant compromised hardware at the store, and/or make arrangements
+by coercing store staff to sell compromised hardware to the quroum team. Of
+course, there still may be hardware that's compromised being sold, but not
+specifically targeting the specific quorum group.
+
+* Ensure at least 2 people are in line of sight of access to all of the
+equipment, for example a bag carried in hand, until the ceremony is executed.
+This is done in order to eliminate the possibility of the equipment being
+swapped for compromised hardware.
+
+* The laptop should ideally support booting from an SD card and have a built in
+micro or standard SD card reader built in; if this is not possible, you will
+also need to purchase a USB SD card reader.
+
+* Dell laptops tend to have support for booting from SD cards so they are a
+good option.
+
+* The store and laptop model should be selected on the spot via consensu of at
+least 2 members of the Quorum. This is done for several reasons:
+
+    * To ensure that no time is given to a malicious actor to deploy
+    compromised hardware to the store
+
+    * To reduce likelihood that arrangements can be made by a malicious actor
+    for the store to sell compromised hardware to the Quroum team
+
+* Note that a secondary computer, or secondary SD card with bootable OS will be
+required in order to be able to verify the flashed AirgapOS SD card right before
+the ceremony.

quorum-key-management/src/one-time-use-locations.md

@@ -0,0 +1,18 @@
+# Selecting Locations
+
+Secure a location that is randomly selected that has a private space with EM
+shielding, or no electronics in at least a 10 m radius. A moving vehicle (eg.
+car, bus, train, ferris wheel) is also a viable alternative. Additionally, the
+ceremony may be conducted in an open outdoor space, such as a forest, or a
+desert, at a location that is not near any human made buildings. The point of
+narrowing the location selection to these spaces is that it makes it hard for a
+malicious actor to prepare for the ceremony and deploy equipment for
+side-channel attacks - with the intent of stealing the cryptographic material
+which is produced or managed during key ceremonies.
+
+The location should be selected immediately before the ceremony in order to
+eliminate the possibility of a malicious actor having time to infiltrate and
+compromise the space ahead of the ceremony. The location may be compromised
+anyways, as a malicious actor may have done so with another target in mind, or a
+more broad campaign, for example in the case for three letter agencies may plant
+cameras and microphones in hotels for intel gathering.

quorum-key-management/src/operator-key-provisioning.md

@@ -0,0 +1,44 @@
+# Operator Key Provisioning
+
+## Description
+This guide can be used for provisioning Operator key pairs, and the output of
+the ceremony is a set of the following for each Operator:
+* Smart Card(s) seeded with PGP keys
+* Storage Device with a backup of:
+    * PGP key pair public key
+
+## Requirements
+* Smart Card(s): whatever number of smart cards you would like to have seeded
+for each Operator, usually 2 per Operator is recommended - one NitroKey 3 and
+1 YubiKey Series 5.
+
+* [Storage Devices](hardware.md#storage-device): as many storage devices as you
+would like for backing up [Public Ceremony Artifacts](public-ceremony-artifact-storage.md)
+
+## Playbook
+
+### Steps
+This playbook allows the setup of any number of Operator Keys. For each Operator,
+the steps that follow need to be repeated.
+
+1. Bring the Ceremony Machine and [Quorum](selecting-quorum.md) team into the
+established [Location](locations.md)
+
+2. Boot your Ceremony Machine using [Secure Boot Sequence](secure-boot-sequence.md)
+
+3. Plug in a new Storage Device
+
+4. Run `keyfork wizard operator` TODO: this command is not part of `keyfork` yet
+
+5. As prompted plug in new Smart Cards
+
+6. Once the ceremony is complete, make as many copies of the Storage Device
+from Step 3 as desired.
+
+7. Follow the [Physical Artifact Storage](physical-artifact-storage.md) guide
+ for storage of the Operator Smart Cards and Location Smart Cards
+
+8. Follow the [Online Artifacts Storage](public-ceremony-artifact-storage.md)
+guide for all public artifacts produced during the ceremony
+
+

quorum-key-management/src/physical-artifact-storage.md

@@ -0,0 +1,44 @@
+# Physical Artifact Storage
+
+QKM requires that some of the hardware containing cryptographic material be
+securely stored in physical locations. The two primary cases where physical
+storage is necessary are the storage of Location Key Smart Cards, and Operator
+Key Smart Cards. These Smart Cards are necessary to successfully execute a
+ceremony.
+
+There are two primary physical artifacts which need to be stored properly:
+
+* Operator Smart Cards
+
+* Location Smart Cards
+
+## Operator Smart Cards
+
+These cards should be stored by Operators in personal vaults using a high
+quality hidden safe, or in a vaulting facility such as a bank vault, or a
+private vaulting provider.
+
+## Location Smart Cards
+
+These cards should only be stored in secure vaults which meet the criteria
+outlined for Storage Locations in the [Location](locations.md) document.
+
+## Additional Criteria
+
+* MUST apply glitter nail polish to screws/seams of hardware casing, and take
+photographs. It's best to use nail polish where the glitter is of different
+sizes and colors.
+
+* MAY put the hardware in a vacuum sealed bag with confetti, and take
+photographs.
+
+* MUST place smart cards in a tamper proof bag, whose picture is taken upon
+sealing, and stored along with other [Public Ceremony Artifacts](public-ceremony-artifact-storage.md)
+
+* SHOULD provision all GPG keys to at least two smart cards, ideally made
+by different manufacturers in order to decrease the likelihood that they both
+simultaneously experience a hardware failure.
+
+* SHOULD place the smart cards in anti-static bags
+
+* SHOULD place the smart cards in a faraday bag

quorum-key-management/src/public-ceremony-artifact-storage.md

@@ -0,0 +1,35 @@
+# Redundant Storage of Ceremony Artifacts
+
+Ceremony Artifacts consist of data which is not sensitive in nature, but
+essential to ongoing operation of a QKM.
+
+The primary artifacts which are produced during the ceremony are:
+
+* PGP Key Certificates
+
+* Shard Files
+
+* Pin Files
+
+* Pictures of tamper proof measures such as tamper proof bags, glitter applied
+to bags, or hardware, such as screws on the bottoms of laptops etc. Pictures
+should be cryptographically signed to prevent tampering.
+
+## Key Principles
+
+* MUST verify that all Public Artifacts generated during the Ceremonies are
+present in the Ceremony Artifacts bundle.
+
+* MUST store all Ceremony Artifacts in at least 2 different cloud storage
+systems. Some options are:
+
+    * AWS S3
+
+    * Google Cloud Platform Storage
+
+    * Azure Storage
+
+    * GitHub
+
+* The data SHOULD have proper access controls, and only be accessible to
+authorized personnel who are part of the organization.

quorum-key-management/src/quorum-team.md

@@ -0,0 +1,40 @@
+# Quorum Team
+
+The Quorum Team is a team of individuals who are selected to perform different
+roles related to a QKM. Some of the Quorum Team members have ongoing roles,
+while others may participate in a partial manner.
+
+Depending on the type of actions performed, some or all of the members of the
+Quorum may be required to participate. For example, it is recommended that there
+is at least 1 witness for all sensitive actions, but having 3 witnesses during
+the primary Key Derivation Ceremony can give better assurances that the most
+crucial part of the ceremony was properly conducted.
+
+The roles which are required for the Quorum Team are the following:
+
+## Operator
+Operators are individuals who protect [Smart Cards](equipment.md) which
+store a [GPG Key Certificate](glossary.md#gpg-certificate), which is used
+for encrypting information, such as the [Location Key](glossary.md#location-key)
+PINs as well as other [Ceremony Artifacts](reduntant-storage-of-ceremony-artifacts.md).
+They are also individuals who participate in Ceremonies in order to Reconstitute
+the key and perform actions with it.
+
+## Controller
+Controllers are an additional optional role which can be used to protect access
+to the physical locations which hold the Location Keys. Some vaulting solutions
+allow for requiring more than 1 individual in order to access a vault. Multiple
+Controllers may be used to protect access to physical locations - according to
+risk appetite.
+
+## Witness
+Witnesses are individuals who are familiar with the QKM specification, and can
+ensure that the different aspects of the system are set up correctly, and
+processes carried out as they should be. The main objective of the witnesses is
+to monitor and attest that processes such as the ceremonies are done according
+to the strictly prescribed rules.
+
+## Courier
+This role can be fulfilled by members of the Quorum Team and their main role is
+getting materials to their designated locations - the main task being getting
+the Location Keys securely to their physical location.

quorum-key-management/src/remote-key-provisioning.md

@@ -0,0 +1,3 @@
+# Remote Key Provisioning
+
+TODO

quorum-key-management/src/repeat-use-airgapos.md

@@ -0,0 +1,61 @@
+# AirgapOS Setup
+This section can be completed on any machine.
+
+AirgapOS has `keyfork` built into it for cryptographic operations such as key
+derivation.
+
+1. Clone the `AirgapOS` repository locally or download it as a zip
+
+    To clone use the following command in the terminal:
+    ```
+    cd ~
+    git clone git@distrust.co:public/airgap.git
+    ```
+
+    To download as a ZIP from https://git.distrust.co/public/airgap:
+    ![Downloading AirgapOS as ZIP](img/download-airgap-os.png)
+
+2. Navigate into the `airgap` repository locally, and build the iso image.
+    ```
+    cd ~/airgap
+    make reproduce
+    ```
+The resulting iso will be located in `airgap/out/`
+
+3. Place signed .iso on a storage device
+
+    a. Import the public key for the PureBoot Smart Card from [Initialize PureBoot Smart Card](initialize-pureboot-smart-card.md) guide.
+    ```
+    gpg --import <ID>.asc
+    ```
+
+    b. Get the GPG key ID using the command:
+    ```
+    gpg --list-keys
+    ```
+    It should look something like `6B61ECD76088748C70590D55E90A401336C8AAA9`
+
+    c. Sign the `airgap.iso` image using the "PureBoot Smart Card", which is
+    set up in [Initalize PureBoot Smart Card](initialize-pureboot-smart-card.md)
+    guide.
+    ```
+    gpg --detach-sign --armor --default-key <ID> airgap.iso
+    ```
+
+4. Copy `airgap.iso` and detached signature to a storage device
+    a. Select a new Storage Device which has no other files on it and plug it
+    into the machine that has the `airgap.iso` file and the detached GPG signature.
+
+    b. Find the name of the Storage Device using [this guide](storage-device-management.md#finding-a-storage-device-name)
+
+    d. Use the `mount` command to mount the drive
+
+    e. Copy both the `airgap.iso` and detached signature to the drive.
+
+5. Make sure to note the `sha256sum` hash of the `airgap.iso` and write it
+down on a piece of paper.
+
+6. Multiple members of your team should build the `airgap.iso` image
+independently and use `sha256sum airgap.iso` in order to hash it, then record
+the value for later use. This value will be checked during Ceremonies before
+booting the ISO image to ensure it can be trusted.

quorum-key-management/src/root-entropy-ceremonies.md

@@ -0,0 +1,14 @@
+# Root Entropy Ceremonies
+
+There are 3 primary types of [Root Entropy](glossary.md#root-entropy-re)
+derivation ceremonies:
+
+* "Local": where all cryptographic material, including the Operator Keys,
+Location Keys, and the Root Entropy are all generated during a single in-person
+ceremony
+
+* "Hybrid": where the Operator Keys and Location Keys are generated separately
+prior to the in-person ceremony where the Root Entropy is generated
+
+* "Remote": where all cryptographic material is generated in a decentralized
+manner, remotely.

quorum-key-management/src/secure-boot-sequence.md

@@ -0,0 +1,40 @@
+# Secure Boot Sequence
+
+1. Plug in the [PureBoot Smart Card](initialize-pureboot-smart-card.md)
+
+2. Plug in [AirgapOS Storage Device](repeat-use-airgapos.md)
+
+3. Turn on the machine
+
+4. Press space when the message "Automatic boot in 5 seconds unless interrupted by keypress..."
+
+5. Once in the PureBoot Boot Menu, navigate to "Options -->" and press Enter
+
+6. Navigate to "Exit to recovery shell" and press enter
+
+7. Use the command `source /etc/gui_functions` to load gui functions
+
+8. Use the command `mount_usb` to mount the Storage Device which contains `airgap.iso` and the detached GPG signature.
+
+9. Type `sha256sum /media/airgap.iso.asc`
+
+10. Verify the hash that appears using whatever number of witnesses the Quroum
+agreed are necessary for witnessing key parts of the Ceremony. Each witness
+should bring their own piece of paper with the hash written out based on the
+binary they built on their own system according to the [AirgapOS Setup Playbook](repeat-use-airgapos.md).
+
+12. Once everyone is satisfied that the hash matches, the computer should be
+be restarted.
+
+13. Press space when the message "Automatic boot in 5 seconds unless interrupted by keypress..."
+
+14. Once in the PureBoot Boot Menu, navigate to "Options -->" and press Enter
+
+15. Navigate to "Boot Options -->" and press enter
+
+16. Navigate to "USB boot" and press enter
+
+17. Ensure that `/media/airgap.iso` is selected and press Enter
+
+18. Once booted, verify the version of the software matches the AirgapOS Hash
+which was noted during the [AirgapOS Setup](repeat-use-airgapos.md).

quorum-key-management/src/selecting-quorum.md

@@ -0,0 +1,38 @@
+# Selecting a Quorum
+
+The backbone of the Distrust Quroum system is a Quorum which is used to
+reconstitute or re-assemble cryptographic material, and approve actions.
+Quorum is a general term referring to a system which requires the collaboration
+of multiple individuals in order to achieve something, and it is based on a
+Threshold which determines how many Members of a Quorum there are in total, and
+the Quorum, which is how Members are required to reach consensus.
+
+The following is a simple Quorum example. Let's assume there are 3 trusted
+individuals who will be part of Quorum and at least 2 of the Members of the
+Quorum should be required to reach consensus. In that case the chosen Quorum
+would be "2 of 3" - in other words, 2 of the total of 3 are required to achieve
+consensus. These numbers may be adjusted in order to optimize risk tolerance
+along two axis:
+
+* Tolerating loss of X members aka "Bus Factor"
+
+* Tolerating duress of Y members aka "Wrench Factor"
+
+In a "2 of 3" Quorum, the **Bus Factor** is 1 as we can only afford to lose 1
+member of the Quorum before the ability to reach consensus is lost permanently.
+For that same Quorum, the **Wrench Factor** is 2, as an adversary has to use
+their wrench on two different Quorum Members to force them to give them access
+to their shards before the system is compromised (this is an over-simplification
+as there are additional security controls in place such as the physical
+locations which hold Location Keys, and as such the Wrench Factor is hardened).
+
+It is recommended to use a "2 of 3" Threshold at a minimum, but many organizations
+may choose to go with more resilient Threshold such as "3 of 5", "2 of 6", or
+"5 of 7", depending on considerations pertaining to:
+
+* Availability requirements
+
+* Bus Factor requirements
+
+* Wrench Factor requirements
+

quorum-key-management/src/setting-smart-card-pins.md

@@ -0,0 +1,38 @@
+# Setting Smart Card Pins
+
+In order to protect unauthorized use of smart cards, we can leverage PINs.
+
+There are two pins with different levels of authorization for making changes
+to the smart card:
+
+* User PIN
+
+* Admin PIN
+
+Both PINs support alphanumeric characters and typically need to be at least 6
+characters long.
+
+For Operator Keys it is recommended to use the default PINs, while for Location
+Keys, PINs are generated by the `keyfork` utility and have high entropy.
+
+## Guide
+
+To set the smart card pins you may use the `gpg` utility.
+
+1. Plug the smart card into a computer which has the `gpg` utility intalled
+2. Use the command `gpg --edit-card` to enter edit mode
+3. gpg/card>
+    * Input `admin`, press Enter
+4. Your selection?
+    * Input 1, press Enter
+5. Please enter the PIN:
+    * Enter old PIN (default is 123456), press Enter
+6. New PIN:
+    * Enter the new PIN, press Enter
+7. Repeat this PIN:
+    * Enter the new PIN, press Enter
+
+8. For the Admin PIN, the steps are the same, except in step 4, input "3", then
+press Enter.
+
+9. Once done, shut down the computer

quorum-key-management/src/software.md

@@ -0,0 +1,38 @@
+# Software
+This page outlines the software used for setting up a QKM. All software used in
+the setup is open source and audited by security firms in order to ensure their
+security. Furthermore, all software is built in a deterministic manner and
+reproduced by multiple individuals on diverse hardware to minimize the risks
+associated with supply chain attacks.
+
+To achieve this, [StageX](https://codeberg.org/stagex/stagex)
+is used - a toolchain for building software using a fully bootstrapped compiler,
+which itself is built deterministically, and multi-reproduced.
+## [AirgapOS](https://git.distrust.co/public/airgap)
+
+AirgapOS is an operating system built for those that want to be -really- sure
+that sensitive cryptographic material is managed in a clean environment with an
+"air gap" between the machine and the internet with high integrity on the supply
+chain of the firmware and OS used. This OS is hardened and specifically designed
+as an appliance for working with cryptographic material.
+
+The software was developed by [Distrust](https://distrust.co) and has undergone
+an [audit](https://git.distrust.co/public/airgap/src/branch/main/audits) by
+Cure53 with no significant vulnerabilities found and has since then undergone
+additional hardening.
+
+The [AirgapOS Setup](repeat-use-airgapos.md) guides the user through verifying and
+setting up AirgapOS on a bootable disk to use as part of the [Key Derivation
+Ceremony](glossary.md#key-derivation-ceremony)
+
+## [Keyfork](https://git.distrust.co/public/keyfork)
+
+Keyfork is an opinionated and modular toolchain for generating and managing a
+wide range of cryptographic keys offline and on Smart Cards from a shared
+BIP-0039 mnemonic phrase. BIP-0039 phrases are used to calculate a BIP-0032
+seed, which is used for hierarchical deterministic key derivation.
+
+This software is the backbone for all cryptographic actions performed as part
+of QKM. It was developed by [Distrust](https://distrust.co) and is included
+with AirgapOS and has been audited by two firms, NCC and Cure53 with no
+significant vulnerabilities found.

quorum-key-management/src/storage-device-management.md

@@ -0,0 +1,53 @@
+# Storage Device Management
+
+In order to interact with a USB device on a Linux system it first has to be
+`mounted`. In order to mount a USB device, one must first identify the device
+name, and then use the `mount` command.
+
+## Finding a Storage Device Name
+USB devices are assigned names when they are connected to a Linux operating
+system. The first storage device is assigned the name `sda` (storage device a),
+the second `sdb`, the third `sdc` and so on.
+
+One may use the `lsblk` to list the detected storage devices for a system, which
+will output something like this:
+```
+NAME    MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
+xvda    202:0    1    50G  0 disk
+├─xvda1 202:1    1   200M  0 part
+├─xvda2 202:2    1     2M  0 part
+└─xvda3 202:3    1  49.8G  0 part /
+xvdb    202:16   1   1.9T  0 disk /rw
+xvdc    202:32   1    10G  0 disk
+├─xvdc1 202:33   1     1G  0 part [SWAP]
+└─xvdc3 202:35   1     9G  0 part
+xvdd    202:48   1 526.8M  1 disk
+```
+
+Then after plugging in the Storage Device run `lsblk` and look for what's
+different. In this example, the newly detected storage device is `sdb`:
+```
+NAME    MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
+sdb       8:16   1  14.5G  0 disk
+xvda    202:0    1    50G  0 disk
+├─xvda1 202:1    1   200M  0 part
+├─xvda2 202:2    1     2M  0 part
+└─xvda3 202:3    1  49.8G  0 part /
+xvdb    202:16   1   1.9T  0 disk /rw
+xvdc    202:32   1    10G  0 disk
+├─xvdc1 202:33   1     1G  0 part [SWAP]
+└─xvdc3 202:35   1     9G  0 part
+xvdd    202:48   1 526.8M  1 disk
+```
+
+## Mounting a Storage Device
+In order to mount a device, first ensure that the directory you will mount to
+exists by running:
+
+```sh
+mkdir -p /media/usb
+```
+
+Then run the following command to mount the storage device:
+```sh
+sudo mount /dev/<usb_device_name> /media/usb

quorum-key-management/src/threat-model.md

@@ -0,0 +1,81 @@
+# Threat Model
+
+QKM is designed according to a high-assurance threat model which ers on the
+side of making exaggerated, rather than conservative assumptions in order to
+build a resilient system.
+
+The assumption is made that attackers who target QKM are extremely
+sophisticated, well funded and patient attackers, and as such, the full arsenal
+of attacks is on the table. This means that the attacker can purchase and
+weaponize multiple 0day vulnerabilities, execute physical attacks or deploy
+moles, target different supply chains of hardware, firmware and software used,
+and generally attack the system using an array of known and unknown attacks.
+
+One of the guiding principles in the design is the elimination of Single Points
+of Failure (SPOFs), and relies on a number of different control mechanisms which
+help reduce risk of any one individual being able to compromise the system,
+whether it's maintainers of software used in the system, the firmware that's
+used, or the individuals or locations that hold secret material which is the
+backbone of the system.
+
+To achieve this, the QKM focuses on reducing the risk by:
+
+* Only using fully open source software and firmware to allow full verification
+of their security
+
+* Creating custom purpose specific tooling which eliminates dependencies in
+order to reduce supply chain attacks, and adds desirable security properties
+
+* Using a fully bootstrapped and deterministically built compiler for building
+all software that's used
+
+* Building all of the software and firmware deterministically
+
+* Using computers which either have a hard switch for disabling networking or
+which had radio networking cards (bluetooth, wifi etc.) removed
+
+* Leveraging smart cards (personal HSMs) to protect cryptographic material
+
+* Leveraging sharding in order to physically separate cryptographic material
+
+* Leveraging tamper evident controls to protect hardware
+
+## General Threat Model Assumptions
+
+Some additional assumptions are made to help contextualize the threat model:
+
+* All screens are visible to an adversary
+
+* All keyboards are logging to an adversary
+
+* Any firmware/boot-loaders not verified on every boot are compromised
+
+* Any host OS with network access is compromised
+
+* Any guest OS used for any purpose other than prod access is compromised
+
+* At least one member of the PRODUCTION team is always compromised
+
+* At least one maintainer of third party used in the system is compromised
+
+* Physical attacks are viable and likely
+
+
+## Additional Threat Model Notes
+
+### Smart Cards
+
+The Operator Smart Card uses the default PIN because it is meant to be something
+a user "has", rather than "knows". On the other hand, the Location Smart Card
+is protected by a complex PIN, which can only be decrypted using the PGP keys
+stored on the Operator Smart Card. This is done in order to protect the access
+to the Location key by anyone except the Operator, but also to allow for adding
+controls which require more than one individual to access a Location Smart Card.
+In this way, there is an additional "quorum" which needs to be achieved to
+access the Location key - more on this in the [Location](locations.md) section.
+
+The Smart Cards are used as they are an HSM (Hardware Security Module) which
+provides excellent protection for the cryptographic material stored on it, and
+they are portable, which makes them suitable for creating systems where the
+cards are in separate physical locations, and need to be brought together in
+order to re-assemble secret material.