add content and related docs for proposer role

inclusion in air gap bundle

quorum-key-management/book.toml

@@ -3,4 +3,4 @@ authors = ["Anton Livaja", "Lance R. Vick", "Ryan Heywood"]
 language = "en"
 multilingual = false
 src = "src"
-title = "Quorum Key Management (QKM)"
+title = "Quorum Vault System (QVS)"

quorum-key-management/get-commit-hash.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+COMMIT_HASH=$(git rev-parse --short HEAD)
+
+echo "Commit Hash: $COMMIT_HASH" > src/commit_hash.md
+
+# Build the mdBook
+mdbook build

quorum-key-management/src/SUMMARY.md

@@ -2,28 +2,38 @@
 * [Introduction](intro.md)
     * [Threat Model](threat-model.md)
     * [Selecting a Quorum](selecting-quorum.md)
+    * [System Roles](system-roles.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)
+    * [Verifying Signatures](verifying-signatures.md)
+    * [Tamper Evidence Methods](tamper-evidence-methods.md)
+    * [Online Machine](online-machine-provisioning.md)
 
-    * [One Time Use]()
-        * [Procure Hardware](one-time-use-hardware-procurement.md)
+    * [Fixed Location Reusable Laptop]()
+        * [Location](locations.md)
+        * [Procure Hardware](fixed-location-reusable-hardware-procurement.md)
+        * [PureBoot]()
+            * [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)
+            * [PureBoot Boot Sequence](secure-boot-sequence.md)
+
+        * [AirgapOS Setup]()
+            * [AirgapOS Setup](repeat-use-airgapos.md)
+            * [`autorun.sh` Setup](autorun-sh-setup.md)
+
+    * [One Time Use / Portable Use]()
+        * [Location](one-time-use-locations.md)
+        * [Procure Hardware](hardware-procurement-and-chain-of-custody.md)
         * [AirgapOS Setup](one-time-use-airgapos.md)
         * [Repository Setup](one-time-repository-setup.md)
         * [Selecting Locations](one-time-use-locations.md)
 
-* [Key Ceremonies]()
+* [Root Entropy Ceremonies]()
     * [Ceremony Log Template](ceremony-log-template.md)
     * [Root Entropy Ceremonies](root-entropy-ceremonies.md)
         * [Local Key Provisioning](local-key-provisioning.md)
@@ -38,6 +48,32 @@
         * [Online Artifact Storage](public-ceremony-artifact-storage.md)
         * [Physical Artifact Storage](physical-artifact-storage.md)
 
+* [Ceremonies]()
+    * [One Time Use Laptop Ceremony](one-time-use-laptop-coin-ceremony.md)
+    * [Portable Reusable Laptop Ceremony](portable-reusable-laptop-ceremony.md)
+    * [Fixed Location Reusable Laptop Ceremony](fixed-location-reusable-laptop-ceremony.md)
+
 * [Lifecycle Management]()
     * [Destroying Hardware](hardware-destruction.md)
-    * [Storage Device Management](storage-device-management.md)
+    * [Storage Device Management](storage-device-management.md)
+
+* [Generated Documents]()
+    * [Level 1]()
+    * [Level 2]()
+        * [Fixed-Location]()
+            * [Provisioner](system-roles.md)
+                * [Procure Equipment & Location](generated-documents/level-2/fixed-location/provisioner/procure-equipment-and-location.md)
+                * [Ceremony Repository](generated-documents/level-2/fixed-location/provisioner/ceremonies-repository.md)
+            * [Proposer](system-roles.md)
+                * [Propose Transaction](generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md)
+            * [Approver](system-roles.md)
+                * [Transaction Approval](generated-documents/level-2/fixed-location/approver/approve-transaction.md)
+            * [Operator](system-roles.md)
+                * [PYTH-SLN - Sign Transaction](generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md)
+    * [Level 3]()
+    * [Level 4]()
+
+* [Document Components]()
+    * [Git Commit Signing](./component-documents/git-commit-signing.md)
+    * [GUI Git Commit](./component-documents/gui-git-commit.md)
+    * [OpenPGP Setup](./component-documents/openpgp-setup.md)

quorum-key-management/src/component-documents/ceremony-repository.md

@@ -0,0 +1,38 @@
+/* ANCHOR: all */
+# Ceremony Repository
+
+// ANCHOR: content
+This repository holds data pertaining to ceremonies. The primary data consists of:
+
+* Transaction proposals
+
+* Transaction approvals
+
+* Tamper proofing evidence
+
+* Policies (such as spending rules)
+
+* Participants
+
+## Directives
+
+* MUST be private
+
+* MUST be write protected, requiring approval from at least 1 individual other than one who opened the PR for merging
+
+* MUST require signed commits
+
+## Repository Structure
+
+```
+ceremonies/
+    /<date>
+        audit_log.txt
+        tamper_evidence/
+        transactions/
+            <tx_name>.tx.json
+policies/
+    spending-policy.json
+```
+// ANCHOR_END: content
+/* ANCHOR_END: all */

quorum-key-management/src/component-documents/git-commit-signing.md

@@ -0,0 +1,35 @@
+/* ANCHOR: all */
+# Git Commit Signing
+// ANCHOR: steps
+1. Retrieve the value of your PGP key ID by using:
+
+    `gpg --list-keys`
+
+1. Set up local `.gitconfig` file with desired PGP key:
+    ```
+    [user]
+        name = <name>
+        email = <email>
+        signingKey = <pgp_key_id> 
+
+    [commit]
+        gpgsign = true
+        merge = true
+    [core]
+        editor = "code --wait"
+    ```
+
+1. Set up environment variables for using smart cards
+
+    Open the `~/.bashrc` file and add the following content at the end:
+
+    ```bash
+    if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then
+        export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
+    fi
+
+    GPG_TTY=$(tty)
+    export GPG_TTY
+    ```
+// ANCHOR_END: steps
+/* ANCHOR: all */

quorum-key-management/src/component-documents/gui-git-commit.md

@@ -0,0 +1,55 @@
+/* ANCHOR: all */
+# Committing Using Git Graphical User Interface
+
+The GitKraken tool can be used to produce commits with data.
+
+# GitKraken Guide: Create a File, Edit in VS Code, and Commit
+// ANCHOR: steps
+1. Clone the Repository
+    * Launch the GitKraken application.
+    * Clone the ceremony repository:
+        * Click on the **"Clone"** button on the left sidebar.
+        * Enter the repository URL you want to clone.
+        * Choose a local directory where you want to save the repository.
+        * Click **"Clone the repo"**.
+
+1. Create a new file
+    * **Navigate to the repository**: Make sure you are in the cloned repository in GitKraken.
+    * **Create a new file**:
+        * Right-click on the folder where you want to create the file in the left sidebar.
+        * Select **"New File"**.
+        * Name your file (e.g., `<file_name>`).
+
+1. Open the File in Visual Studio Code
+    * **Open Visual Studio Code**:
+        * Right-click on the newly created file
+        * Select **"Open in External Editor"** (this should open the file in Visual Studio Code)
+
+1. Add content to the file
+    * In Visual Studio Code, type a simple JSON blob. For example:
+     ```json
+     {
+       "name": "Sample",
+       "version": "1.0.0",
+       "description": "This is a sample JSON blob."
+     }
+     ```
+    * Save the file: Press `Ctrl + S` (or `Cmd + S` on Mac) to save the changes.
+
+1. Stage the changes
+    * **Return to GitKraken**: Go back to GitKraken.
+    * **Stage the File**:
+        * In the left sidebar, you will see the file you just created under the **"Unstaged Files"** section.
+        * Click the checkbox next to `<file_name>` to stage the file.
+
+1. Commit the Changes
+    * **Commit the Changes**:
+        * In the commit message box at the bottom, type a commit message (e.g., "Add <file_name> with sample JSON blob").
+        * Click the **"Commit changes"** button.
+
+1. Push the Changes (if needed)
+    * Push to remote repository:
+        * If you want to push your changes to the remote repository, click the **"Push"** button in the top toolbar.
+// ANCHOR_END: steps
+
+/* ANCHOR_END: all */

quorum-key-management/src/component-documents/keychain-repository.md

@@ -0,0 +1 @@
+# Keychain Repository

quorum-key-management/src/component-documents/openpgp-setup.md

@@ -0,0 +1,16 @@
+/* ANCHOR: all */
+# OpenPGP Setup
+
+Setting up a PGP key pair is necessary for a number of different aspects of QVS. The keys are a fundamental building block, and as such need to be set up in a manner that minimizes exposure risks.
+
+## Procedure
+// ANCHOR: steps
+1. Secure an airgapped machine set up with AirgapOS
+
+1. Use keyfork to generate a key and provision a card
+
+1. Encrypt the mnemonic to the generated key
+
+1. [OPTIONAL]: The operator key can be encrypted to the organization [Disaster Recovery Public Certificate](TODO).
+// ANCHOR_END: steps
+/* ANCHOR_END: all */

quorum-key-management/src/fixed-location-reusable-hardware-procurement.md

@@ -0,0 +1,40 @@
+# Procure Hardware
+- [ ] TODO update this doc so it listes a bunch of models that support pureboot, not just purism
+
+1. Select a librem 14 laptop from https://puri.sm, and ensure:
+    
+    * Memory: 8GB
+
+    * Storage: 250GB
+
+    * Power Adapter Plug: US
+
+    * Wireless: No wireless
+
+    * Firmware: PureBoot Bundle Anti-Interdiction (PureBoot Bundle Plus + Anti-interdiction services)
+
+    * Operating System: PureOS
+
+    * Warranty: 1 Year
+
+    * USB Flash Drive: No USB Flash Drive
+
+2. Purism will reach out via email and establish secure communications using PGP, so ensure that the individual who is in charge of procurement has a PGP key that's been set up securely. Purism will:
+
+    * Modify the laptop as per order specifications, in this case removing radio cards.
+
+    * Seal the screws on the bottom of the laptop using glitter of chosen color
+
+    * Take photographs of the inside of the laptop, then of the outside after it's sealed
+
+    * The photographs will be signed by Purism and encrypted to the PGP key used for communications to protect the integrity of the images
+
+    * The firmware verification hardware token can be sent to a separate location from the laptop, and will be tamper sealed using tamper proofing tape 
+        
+        * TODO: find out if we can have vacuum sealing with filler as a tamper proofing method be provided by Purism
+
+    * The laptop will be sealed in a box using tamper proofing tape
+
+3. Once the laptop is received, it should not be opened until at least 2 parties are present and principles of [chain of custody](hardware-procurement-and-chain-of-custody.md) can be upheld. The images of tamper proofing provided by Purism should be used to ensure that the hardware had not been tampered, and the hardware token to verify firmware is in tact.
+
+4. Once the hardware is properly verified to not have been tampered in transit, a [tamper evidence method](tamper-evidence-methods.md) should be applied to the laptop before it's stored.

quorum-key-management/src/fixed-location-reusable-laptop-ceremony.md

@@ -0,0 +1,69 @@
+# Fixed Location Reusable Laptop Ceremony
+
+This device is intended for use in a secure facility such as a [SCIF](TODO) which has the added assurances of protecting the environment from a wide range of side-channel attacks, as well as protection from physical attacks, and more comprehensive tamper proofing controls.
+
+The fixed location should include a work-station which makes it easy to perform the [tamper proofing](tamper-evidence-methods.md#tamper-proofing-station) procedure. This station may consist of a simple frame which holds a LED light, for consistent lightning, as well as a camera stand above it which can be used to take pictures. The camera should have an SD card that easily slides out of it so that the device doesn't leave and re-enter the room, only the SD card does.
+
+    * TODO: this is actually not necessary for the fixed location device, but it's good to have this setup in the same facility maybe for processing/setting up the one time use laptops
+
+The primary tamper proofing methods for the fixed location device are:
+
+* Heads firmware protection (TODO link to document which explains how to set up Purism)
+
+* Glitter to prevent physical access to hardware (TODO link to how to properly use glitter for tamper proofing)
+
+* On-premises audio and visual monitoring (TODO select appropriate equipment)
+
+* Physical vault (TODO find adequate vaults)
+
+## Procedure
+
+### Unsealing
+
+1. Select at least two authorized operators who will be participating in the ceremony
+
+2. Print photographs of tamper proofing of the laptop which will be used for the ceremony
+
+    * Both photos of vacuum sealed bag with filler and glitter on the bottom screws of laptop are required
+
+- [ ] TODO how is hardware token stored (for pureboot/heads)
+
+3. Make an entry into the access log, specifying the:
+
+    * Individuals involved
+
+    * Approximate time of entry
+
+4. Enter the SCIF, ensuring to lock the door behind you from the inside. The room should not be accessible from the outside during a ceremony.
+
+    * Ensure that no individual is bringing in any electronic devices. A hand-held or gate metal detector can be used for this.
+
+5. Access the laptop safe, and move the laptop, its hardware token, and polaroid to the Tamper Proofing Workstation
+
+    * Compare the polaroid and digital photographs for any differences
+
+    * Then compare the photographs to the actual object
+
+    * Check the glitter on the bottom screws of the laptop ensuring there are no scratch marks, and compare the screws to photos
+
+    * If there are any issues detected, initiate incident response
+
+6. Initiate the [Secure Boot Sequence](secure-boot-sequence.md)
+
+{{ #include secure-boot-sequence.md }}
+
+7. Use one of the [Playbooks](todo) to carry out a task
+
+#### Sealing
+
+{{ #include tamper-evidence-methods.md:vsbwf-procedure-sealing}}
+
+2. Remove the SD card from the camera and use chain of custody principles to ensure the integrity of the data
+
+3. Place the sealed laptop and signed polaroids, as well as the hardware token back in the safe
+
+4. Exit the SCIF and lock it
+
+5. Update the log with the exit time
+
+6. Upload the photos to a git repository, ensuring the commit is signed using PGP

quorum-key-management/src/generated-documents/level-2/fixed-location/approver/approve-transaction.md

@@ -0,0 +1,23 @@
+# Approver - Approve Transaction
+
+The approver is responsible for verifying a transaction proposed by a [proposer](../../../../system-roles.md).
+
+## Responsibilities
+
+* MUST verify the proposer data out of band (over a secure channel)
+
+    * Proposer data is primarily their PGP key
+
+* MUST verify the PGP signature of the data according to a policy
+
+    * TODO: specify how the policy works
+
+* MUST add their own well known PGP key signature to the data if the data is verified to be valid.
+
+    * NOTE: all transaction values must be signed as part of a single message
+
+To sign the transaction payload and produce a detached signature use:
+
+`gpg --armor --output <approver.sig> --detach-sig <filename>`
+
+Transmit the `proposer.asc` and `approver.sig` to the operator.

quorum-key-management/src/generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md

@@ -0,0 +1,114 @@
+# NOT PRODUCTION READY
+
+# Operator - Sign PYTH-SPL Transaction
+
+## Requirements
+
+* Ensure both primary operators have their [Operator Keys](../../../../../../glossary.md#operator-key)
+- [ ] TODO define guide for setting up operator keys
+
+* Both operators should print photographic evidence from digital cameras which is stored in a PGP signed repository. The photographs should be of the top and underside of the vacuum sealed object.
+
+    * The operators should verify the commit signatures of the photographs they are printing against a list of permitted PGP keys
+
+        - [ ] TODO: where do we refer to permitted PGP keys
+
+* Each operator should hash the `keychain` repository
+    - [ ] TODO define keychain repository setup
+
+    * `sha256sum keychain/`
+
+    * Write it down on a piece of paper as it will be used during the ceremony
+
+
+## Procedure
+
+1. Enter the designated location with the 3 operators and all required equipment
+
+2. Lock access to the location - there should be no inflow or outflow of people during the ceremony
+
+3. Retrieve sealed laptop and polaroid from locked storage
+
+### Unsealing Tamper Proofing
+{{ #include ../../../../../../tamper-evidence-methods.md:vsbwf-procedure-unsealing}}
+
+### Secure Boot Procedure
+0. Plug PureBoot smart card into air-gapped machine
+
+1. Plug in SD card labelled "AirgapOS"
+
+{{ #include ../../../../../../secure-boot-sequence.md:prepared}}
+
+0. Plug in SD card labelled "Trusted Keys"
+
+    * Load well known PGP keys of proposer and approver, and sign them using operator keys (NOT IMPLEMENTED)
+
+        * `gpg --import <keyfile_name>`
+
+1. Insert SD card labelled "shardfile"
+
+2. `keyfork recover shard --daemon`
+
+    * Follow on screen prompts
+
+3. As a last step, run the `icepick` command which is awaiting the transaction payload
+
+    * `icepick workflow sol-transfer` 
+
+    * Follow on screen prompts
+
+
+### Obtain Transaction Request
+
+1. Turn on online machine
+
+2. Get transaction request(s)
+
+    * TODO define means (could just be email?)
+
+3. Run `icepick workflow sol-broadcast` command
+
+    * Wait for prompt and plug in fresh SD card
+
+    * Await completion message before removing SD card
+
+    * This command will set the computer into "awaiting mode", which will broadcast the signed transaction from the SD card once it's plugged back in
+
+5. Unplug the SD card and pass it to the air-gapped machine operators
+
+### Sign Transaction
+
+1. Plug in SD card with transaction payload
+
+2. Wait for the screen to display the transaction information. (NOT IMPLEMENTED)
+
+    * In the background:
+
+        * The transaction is constructed
+
+        * Signatures of tx data are verified against well known keys which were loaded by operators into local GPG keychain and signed by operators (NOT IMPLEMENTED)
+
+3. If any issues are detected with data you will be prompted and should initiate [incident response (todo)](todo)
+
+4. Wait for the "completed" message
+
+5. Unplug and give the SD card back to the online machine operator
+
+### Broadcast Transaction
+
+* Online machine operator takes the SD card to online machine and plugs it in
+
+* The still running process from running the command to create the transaction in [Obtain Transaction Request](#obtain-transaction-request) will broadcast the transaction automatically
+
+* Await the "completed" message
+
+### Finalization
+
+* Shut down online machine
+
+* Shut down the air gapped machine
+
+#### Sealing
+
+{{ #include ../../../../../../tamper-evidence-methods.md:vsbwf-procedure-sealing}}
+

quorum-key-management/src/generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md

@@ -0,0 +1,65 @@
+# Proposer - Create Transaction Payload
+
+The proposer is a fiduciary whose responsibility is to make sound financial decisions on behalf of a business and determine where funds are moving from, where to and in which amount. The reasons for sending funds may range across settlement, exchanging, staking and more.
+
+The proposer MUST clearly define, at a minimum:
+
+* Token Name (SOL, PYTH-SPL, ETH, ETH-PYTH, BTC etc.)
+
+* FROM address
+
+* TO address
+
+* Amount
+
+* Date + Time
+
+The proposer must combine these values into a single message, which can be a simple JSON file, and sign it using a well known PGP key.
+
+## Requirements
+
+* If necessary, provision a PGP key pair to a smart card using the guied in the [Appendix: Provisioning PGP Smart Card](#provisioning-pgp-smart-card)
+
+* Ensure that the computer is configured to sign commits with the desired key. Refer to the [Appendix: Git Commit Signing Configuration](#git-commit-signing-configuration)
+
+* Clone the [Ceremonies Repository](../../../../component-documents/ceremony-repository.md) for your organization to the machine
+
+## Procedure
+
+1. Define a new file "<date:time>-<currency>.tx.json", for example "16:40-PYTH-SPL.tx.json"
+
+1. Create a new directory in the `ceremonies` repository for the date on which the ceremony for the transaction will take place if it doesn't already exist, for example `2024-01-01/`
+
+1. Collect data for the transaction being sent, and structure it according to the template below, replacing values with valid ones. The values have to come from a organization approved list of values, for each field, except for `datetime` which is just the current date and time.
+    ```json
+    {
+        "token-name": "<name>",
+        "token-amount": "<amount>",
+        "from-address": "<address>",
+        "to-address": "<address>",
+        "datetime": "<date:time>"
+    }
+    ```
+
+    Example data object:
+    ```json
+    {
+        "token-name": "PYTH-SLN",
+        "token-amount": "42",
+        "from_address": "2Z72E62atYfpatQeqPvHZMaabmuz664xq5MRWv9xM5NX",
+        "to_address": "BNQr6T2UAuEPux1fuiygM6chrT5GkHKaMWeTTaRLmR7g",
+        "datetime": "<date:time>"
+    }
+    ```
+
+{{ #include ../../../../component-documents/gui-git-commit.md:steps}}
+
+6. Notify relevant individuals that there are new transactions queued up, and that a ceremony should be scheduled. This can be automated in the future so that when a commit is made or PR opened, others are notified, for example using a incident management tool(TODO).
+
+## Appendix
+
+### Git Commit Signing Configuration
+
+{{ #include ../../../../component-documents/git-commit-signing.md:steps }}
+
+### Provisioning PGP Smart Card

quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/ceremonies-repository.md

@@ -0,0 +1,3 @@
+# Ceremonies Repository
+
+{{ #include ../../../../component-documents/ceremony-repository.md:content }}

quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/procure-equipment-and-location.md

@@ -0,0 +1,144 @@
+# Provisioner - Procure Hardware
+
+The provisioner is responsible for:
+
+* Procuring equipment
+
+* Setting up the [Facility](#facility)
+
+* Maintaining stock of supplies in the [Facility](#facility)
+
+* Minimizing hardware supply chain security risks
+
+## Directives
+
+* MUST maintain chain of custody for all hardware until after it's properly stored or where necessary tamper-proofed
+
+The different procedures are ordered in chronological preference, to improve the efficiency of setting up the system.
+
+## Facility
+
+1. Identify a location which is suitable for Level 2 ceremonies:
+
+    * SHOULD be lockable to prevent inflow and outflow of persons during ceremonies
+
+1. Procure an enclosure for locking equipment. A simple lockbox or a safe can be used. It should be at least large enough to fit several laptops, with some extra room.
+
+1. Designate the location as the facility for conducting ceremonies and update documentation and policies to reflect this
+
+## Preparing SD Cards
+
+SD cards don't require special chain of custody, but ideally should be purchased from a reputable supplier.
+
+### SD Card Models
+
+{{ #include ../../../../hardware-models.md:sd-models }}
+
+### Notes
+
+* The location should always be well stocked with freshly formatted SD cards
+
+    * There should be at least 20 microSD and 20 SD cards available for use
+
+    * Both microSD and regular SD cards should be available
+
+    * They should be formatted to `ext4` format
+
+* Usage of these SD cards:
+
+    * Transferring transaction data from online to air-gapped machine
+
+    * Storing tamper proofing evidence produced at the end of the ceremony
+
+### Procedure: formatting SD Card to `ext4`
+
+{{ #include ../../../../sd-formatting.md:steps }}
+
+## Tamper Proofing Equipment
+
+### Vacuum Sealer and roll
+{{ #include ../../../../tamper-evidence-methods.md:vsbwf-equipment}}
+
+### Colored beads
+
+{{ #include ../../../../tamper-evidence-methods.md:vsbwf-filler}}
+
+### Digital camera
+{{ #include ../../../../tamper-evidence-methods.md:digital-cameras}}
+
+### Polaroid camera
+{{ #include ../../../../tamper-evidence-methods.md:polaroid-cameras}}
+
+## AirgapOS (SD Card)
+
+An SD card with AirgapOS written to it will be required to run ceremonies.
+
+The AirgapOS SD Card once provisioned will be used in creating the [tamper proofed airgap bundle](#air-gapped-bundle)
+
+{{ #include ../../../../one-time-use-airgapos.md:steps }}
+
+### Shardfile (SD Card)
+
+There should be multiple SD cards containing the shardfile data. Shardfile data is produced during a [Root Entropy](todo) derivation ceremony.
+
+The Shardfile SD Card once provisioned will be used in creating the [tamper proofed airgap bundle](#air-gapped-bundle)
+
+* Label: "Shardfile"
+
+## Trusted Keys (SD Card)
+
+This procedure requires 2 individuals in order to witness the process and verify that the data being burned to the card is correct.
+
+The Trusted Keys SD Card once provisioned will be used in creating the [tamper proofed airgap bundle](#air-gapped-bundle)
+
+### Procedure
+
+1. Get a freshly formatted SD card 
+
+1. Plug it into a computer
+
+1. Navigate the the official Keychain repository of your organization
+
+1. Select provisioner and approver keys from the Keychain repository
+
+1. Download the desired keys along with detached signatures
+
+1. Copy the `.asc` and signature files to the SD card
+
+1. Use the `sdtool` to lock the card
+
+{{ #include ../../../../sdtool-instructions.md:steps }}
+
+1. Label the card "Trusted Keys <date>"
+
+## Computer Procurement
+
+For [Level 2](../../../../threat-model.md#level-2) security, air-gapped computers which are used for cryptographic material management and operations are required.
+
+Sealable plastic bag is required for this procedure:
+
+{{ #include ../../../../hardware-models.md:sealable-plastic-bags }}
+
+### Models
+
+{{ #include ../../../../hardware-models.md:computer-models }}
+
+### Procedure
+
+{{ #include ../../../../hardware-procurement-and-chain-of-custody.md:steps}}
+
+## Air-gapped bundle
+
+* Tamper proof together the following objects:
+    
+    * [Air-gapped machine](#computer-procurement)
+    
+    * [AirgapOS SD card](#airgapos)
+
+    * [Trusted keys SD card](#trusted-keys)
+
+    * [Shardfile SD card](#shardfile)
+
+### Procedure
+
+{{ #include ../../../../tamper-evidence-methods.md:vsbwf-procedure-sealing }}

quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/trusted-keys-repository.md

@@ -0,0 +1,2 @@
+# Trusted Keys Repository
+todo

quorum-key-management/src/glossary.md

@@ -60,6 +60,12 @@ 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.
 
+## Secure Compartmentalized Information Facility (SCIF)
+
+## [RFC2119](https://www.rfc-editor.org/rfc/rfc2119) and [RFC8174](https://www.rfc-editor.org/rfc/rfc8174)
+
+Specifications for keywords such as MUST, MUST NOT, SHOULD, SHOULD NOT, MAY etc.
+
 ## Workstation
 
 Highly secure computer which is used for sensitive operations, typically in the
@@ -133,3 +139,6 @@ importantly the Root Entropy was never exposed.
 * [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
+
+## MICE
+A mnemonic device used in counterintelligence training to remind trainees of the four general motivations that could lead someone to commit treason, become an insider threat, or collaborate with a hostile agency or organization. It stands for Money, Ideology, Compromise, and Ego.

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

@@ -0,0 +1,45 @@
+/* ANCHOR: all */
+# Hardware Models
+
+## Computers 
+
+* Laptops with chargers over ports which don't allow data transfer is preferred (non USB etc.)
+
+// ANCHOR: computer-models 
+
+* HP 13" Intel Celeron - 4GB Memory - 64GB eMMC, HP 14-dq0052dx, SKU: 6499749, UPC: 196548430192, DCS: 6.768.5321, ~USD $179.99
+    * [Illustrated Parts Catalog](https://h10032.www1.hp.com/ctg/Manual/c04501162.pdf#%5B%7B%22num%22%3A3160%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2Cnull%2C732%2Cnull%5D)
+
+* Lenovo 14" Flex 5i FHD Touchscreen 2-in-1 Laptop - Intel Core i3-1215U - 8GB Memory - Intel UHD Graphics, SKU: 6571565, ~USD $379.99
+
+* Purism Librem 14
+// ANCHOR_END: computer-models
+
+## SD Cards
+// ANCHOR: sd-models
+
+* [Kingston Industrial 8GB SD Memory Card](https://www.kingston.com/en/memory-cards/industrial-grade-sd-uhs-i-u3?capacity=8gb)
+
+* [Kingston Indsutrial 8GB microSD Memory Card](https://shop.kingston.com/products/industrial-microsd-card-memory-card?variant=40558543405248)
+
+* microSD to SD adapter
+
+    * TODO find specific products
+
+* SD Card USB Adapters
+
+    * SD card reader: https://www.kingston.com/en/memory-card-readers/mobilelite-plus-sd-reader
+
+    * microSD card reader: https://www.kingston.com/en/memory-card-readers/mobilelite-plus-microsd-reader
+
+    * Workflow station hub (may prove helpful with workflows): https://www.kingston.com/en/memory-card-readers/workflow-station-hub
+
+// ANCHOR_END: sd-models
+
+## Tamper Proofing 
+
+// ANCHOR: sealable-plastic-bags
+[Alert Security bag](https://shop.alertsecurityproducts.com/clear-alert-bank-deposit-bag-15-x-20-250cs?affiliate=ppc12&gad_source=1&gclid=CjwKCAiAgoq7BhBxEiwAVcW0LJoCVUqYI1s4RGoctHxMwtmNlwenDhgP_0x4gjB9W2e4f_7tzdJ_rxoCOwMQAvD_BwE)
+// ANCHOR_END: sealable-plastic-bags
+
+/* ANCHOR_END: all */

quorum-key-management/src/hardware-procurement-and-chain-of-custody.md

@@ -0,0 +1,28 @@
+/* ANCHOR: all */
+# Procurement & Chain of Custody
+
+## Provisioning Chain of Custody
+
+Materials and devices which are used in the context of a high assurance system need to be monitored carefully from the moment they are purchased to ensure there are no single points of failure. Going back to the assumption that participants in the system are subject to [MICE](./glossary.md#MICE) and as such may pose a threat to the system, special care has to be taken that multiple individuals are involved in the whole lifecycle of provisioning a piece of equipment.
+
+All steps of the provisioning process need to be completed under the supervision of at least 2 individuals, but benefit from having even more individuals present to increase the number of witnesses and allow individuals to take washroom breaks, eat etc.
+
+The following steps must all be completed under the continued supervision and with the involvement of all parties present. It is instrumental that there is not a single moment where the device is left unsupervised, or under the supervision of only 1 individual.
+
+## Provisioning Equipment
+// ANCHOR: steps
+1. Selecting a Purchase Location
+
+    * Select at least 4 stores which carry the type of equipment being purchased, then randomly select one using the roll of a die, or other random method. This is done in order to reduce the likelihood that a threat actor is able to plant a compromised computer in a store ahead of time.
+ 
+        * Each participant should choose 2 of the stores.
+
+2. Within the store, identify available adequate device
+
+3. Purchase the device and place it in a see-through plastic bag which will be used to transport it to a "processing location", which is ideally just a access controlled space. The bag MUST be a sealable see-through tamper evident bag. It may be necessary to remove the device from it's original packaging to fit it into the sealable bag.
+
+4. If the equipment does not have to be tamper proofed, simply deliver it to its storage location, and update the inventory repository with the serial number of the device.
+
+5. If the equipment does require tamper proofing, apply the appropriate level of tamper proofing for the security level you are performing the procurement for. 
+// ANCHOR_END:steps
+/* ANCHOR_END: all */

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

@@ -1,5 +1,7 @@
 # PureBoot Setup
 
+- [ ] TODO: fix this doc to use a different smart card for pureboot as the librem key, as the librem key doesn't have a physical switch
+
 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

quorum-key-management/src/intro.md

@@ -1,19 +1,19 @@
 # Introduction
 
-Quorum Key Management (QKM) is an open source system of playbooks and
+Quorum Vaulting System (QVS) is an open source system of playbooks and
 tooling which facilitates the creation and maintenance of highly resilient
 [quorum](glossary.md#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.
+[Distrust](https://distrust.co), with the generous support of sponsors.
 
-The basic premise of QKM is that primary cryptographic material akin to a root
+The basic premise of QVS is that primary cryptographic material akin to a root
 certificate, called [Root Entropy (RE)](glossary.md#root-entropy-re), is generated
 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.
+wallets, web certificates and more. 
+
+Currently there is a set of an opinionated set of playbooks for working with OpenPGP and blockchains is in development, and will be extended to digital certificates, FIDO secrets and more in the future.
 
 The RE is sharded using [Shamir's Secret Sharing (SSS)](glossary.md#shamirs-secret-sharing-sss)
 to a [Quorum](glossary.md#quorum) in order to protect it from single points of
@@ -23,7 +23,7 @@ access controls in order to reconstruct the secret material, namely the RE.
 
 ## Use Cases
 
-QKM can be used for a wide range of use-cases which span but are not limited
+QVS 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
@@ -42,8 +42,8 @@ a cold signing setup.
 
 ## 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
+QVS can be set up by using a set of highly opinionated playbooks which outline
+the process. The base documentation should be read in its entirety by all
 participants of the ceremony in order to ensure that the system is well
 understood by all to ensure that the integrity of the process is preserved and
 enforced.

quorum-key-management/src/locations.md

@@ -1,7 +1,7 @@
-# Location
+# Locations
 
 Locations refer to physical points in space which are used for storing
-cryptographic material  or performing actions related to the DRK lifecycle and
+cryptographic material or performing actions using the cryptographic material and
 adhere to a set of criteria which focus on achieving a high level of security -
 specifically with respect to:
 
@@ -20,11 +20,39 @@ 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.
+## Level 1
 
-## All Locations
+This level of defenses is largely focused on remote attacks, and as such does not have strict requirements about the location. 
+
+### Examples
+
+* Personal domicile
+
+* Co-working space
+
+* Regular office (non specific to QVS)
+
+### Reference Design 
+
+* SHOULD have ability to control physical access to room
+
+* SHOULD be a space that's randomly selected to minimize the likelihood of an adversary deploying equipment into the location before it's used
+
+## Level 2
+
+This level of defenses is focused on insider threats and as such requires a considerably higher standard as it needs to mitigate threats which stem from individuals who have privileged access.
+
+### Examples
+
+* Purpose specific facility for QVS
+
+* Short term rental
+
+* Hotel room 
+
+* Moving vehicle
+
+### Reference Design
 
 * MUST have physical access restrictions which require identification
 
@@ -38,21 +66,9 @@ and Ceremony Location may be one and the same.
 
 * SHOULD have anti-flood systems
 
+* SHOULD be in facilities controlled by organizations which are ideally immune to being legally subpoenaed
 
-## 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
+## Level 3 
 
 * MUST have anti-fire systems
 
@@ -66,7 +82,16 @@ standard NATO SDIP-27 Level A
     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)
+collusion unless the organization who owns the QKM system has their own facility such
+as a [SCIF](glossary.md#secure-compartmentalized-information-facility-scif).
 
-* SHOULD have seismic detectors
+## Level 4 (SCIF)
+
+* MUST not have cameras installed inside of the room
+
+* 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 have seismic detectors

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

@@ -1,3 +1,4 @@
+/* ANCHOR: all */
 # Set up AirgapOS
 
 Because without a Librem 14 there is no easy way to have a secure boot sequence,
@@ -5,25 +6,18 @@ instead the AirgapOS `.iso` image is flashed to an SD card, locked using
 `sdtool` and then verified using any machine.
 
 ## Setup Steps
+// ANCHOR: steps
+1. Build the software according to the [readme](https://git.distrust.co/public/airgap) in the repository. Use the `make reproduce` command.
 
-* Clone the latest AirgapOS version:
+2. Verify the software according to [this](verifying-signatures.md) guide
 
-    * `git clone git@distrust.co:public/airgap.git`
-
-* Build the image:
-
-    * `cd airgap && make`
-
-* Verify `sha256sum` of airgap matches hashes in `/dist`
-
-* Verify signatures on the hashes in `/dist`. The maintainer pgp keys can be found on the [Distrust contact page](https://distrust.co/contact.html) page.
-
-
-* Flash `airgap.iso` to an SD Card:
+3. 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:
+4. Use the `sdtool` to lock the SD Card:
+
+    * TODO: update this to use stagex binary
 
     * `git clone git@github.com:BertoldVdb/sdtool.git`
 
@@ -37,7 +31,16 @@ instead the AirgapOS `.iso` image is flashed to an SD card, locked using
 
         * `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:
+5. Label the SD card "AirgapOS - <version>"
+
+6. 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`
+
+7. Commit the hash of airgap to a git repo, ensuring the commit is signed
+
+// ANCHOR_END: steps
+
+/* ANCHOR_END: all */

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

@@ -1,33 +0,0 @@
-# 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 is less
-likely to specifically target the 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; if this is not possible, USB SD card reader
-should be purchased.
-
-* 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 consensus 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 Quorum 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-laptop-coin-ceremony.md

@@ -0,0 +1,7 @@
+# One Time Use Laptop Ceremony
+
+## Threat Model
+
+One time use laptops are specially prepared for using in field operation but can also be used inside of a secure facility. The primary objective of this setup is that the laptop is provisioned ahead of time, and is considered to be secure for use, but is to be destroyed afterwards.
+
+This flow is the same as [portable reusable laptop ceremony](portable-reusable-laptop-ceremony.md) except instead of tamper proofing the hardware at the end of the ceremony, it is destroyed.

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

@@ -1,19 +1,20 @@
 # Selecting Locations
 
-Secure a randomly selected location 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 an open space not near any objects and ideally on a hard surface
-such as rock to prevent hidden devices in the ground. 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.
+* MUST be selected at random right before the ceremony
+    
+* MUST have physical access control to prevent inflow and outflow of personnel during ceremony
 
-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.
+* SHOULD NOT have electronics in it as they can be used for side channel attacks
+
+* SHOULD NOT have windows to prevent exfiltration of data via light or observation of screen
+
+## Location Examples
+
+* A hotel room although it is relatively common to find spying devices in them so they are not a great choice
+
+* A moving vehicle such as car, bus, train, ferris wheel given that the operator is able to secure a space which can be locked and has no strangers in it
+
+* Open space with nobody around such as a forest, desert, large parking lot etc.
+
+
+Despite all these measures, 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. For this reason it is always highly preferred to perform cryptographic actions in a properly secured facility such as a SCIF.

quorum-key-management/src/online-machine-provisioning.md

@@ -0,0 +1,29 @@
+# Online Machine Provisioning
+
+## QubesOS
+
+QubesOS is a preferred operating system for use in high security assurance scenarios as it uses hardware based virtualization leveraging the Xen hypervisor, which gives strong isolation guarantees. This makes it trivial to create purpose specific environments, which have minimal software footprints, as well as restricted networking in order to limit ingress and egress.
+
+* [Hardware Compability](https://www.qubes-os.org/hcl/)
+
+    * It is highly preferred to use a Purism machine due to additional hardware supply chain security features such as anti-interdiction
+
+    * Commonly used alternative makes include: ThinkPads, Framework and Dell
+
+* [Installation](https://www.qubes-os.org/downloads/)
+
+    * MUST follow "verifying signatures" guide
+
+## "Power-Washed" Chromebook with ChromeOS
+
+In order to reduce surface area for attacks, we can reset a Chromebook to its factory settings, effectively wiping any malicious software that may have made its way onto the system during previous use.
+
+### "Power-Washing"
+
+1. Press and hold the Ctrl + Alt + Shift + R keys on your keyboard.
+
+2. Select the Restart option.
+
+3. A screen will appear asking you to confirm that you want to reset the device. Click Powerwash and Reset, then Continue.
+
+

quorum-key-management/src/portable-reusable-laptop-ceremony.md

@@ -0,0 +1,72 @@
+# Portable Reusable Laptop Ceremony
+
+## Security Level
+
+This process offers a Level 2 security mitigation, focusing on defending against remote adversaries and insider threats.
+
+## Requirements
+
+### Roles
+
+This setup does require the support of all [system roles](system-roles.md).
+
+* MUST use at least 1 [Proposer](system-roles.md#proposer)
+
+* MUST use at least 1 [Approver](system-roles.md#approver) different from Proposer
+
+* MUST have at least 2 [Witnesses](system-roles.md#witness)
+
+* MUST have at least 1 [Operator](system-roles.md#operator)
+
+### Location
+
+To conform to [Level 2](threat-model.md#level-2) security properties a location must be used according to the [Locations](locations.md) specification.
+
+### Equipment
+
+* Laptop procured according to [Hardware Procurement](hardware-procurement-and-chain-of-custody.md) guide
+
+* Polaroid camera + pack of polaroid film
+    - [] TODO update tamper rpoofing doc with polaroid camera models and film 
+
+* Digital camera
+    - [ ] TODO add recommendations
+
+* 10 SD cards
+    - [ ] TODO add which
+
+* [Vacuum sealer](tamper-evidence-methods.md#vacuum-sealers)
+
+* [Vacuum sealer roll](tamper-evidence-methods.md#vacuum-sealers)
+
+* Tamper evidence photographs:
+
+    * Printed digital photos
+
+    * Polaroid photos
+
+## Procedure
+
+1. The laptop and all hardware used SHOULD be kept on the person at all times
+
+    * MAY leave the laptop in a safe
+
+    * MAY (but not recommended) leave the laptop with full time supervision (such as bellhop)
+
+2. Once in a secure location - control access to the location. It is highly preferred that no individuals enter or leave the facility during the ceremony.
+
+3. Before starting the ceremony ensure that at least 1 Operator and 1 Witness are present
+
+4. Verify that the request from the Proposer is properly approved by an Approver
+
+### Unsealing
+{{ #include tamper-evidence-methods.md:vsbwf-procedure-unsealing}}
+
+### Perform Operations
+
+Follow a [playbook](TODO)
+
+
+### Sealing
+{{ #include tamper-evidence-methods.md:vsbwf-procedure-sealing}}
+

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

@@ -1,26 +1,14 @@
+/* ANCHOR: all */
 # AirgapOS Setup
+
 This section can be completed on any machine.
 
-AirgapOS has `keyfork` built into it for cryptographic operations such as key
-derivation.
+AirgapOS has `keyfork` and `icepick` built into it for cryptographic operations such as key derivation and signing
 
-1. Clone the `AirgapOS` repository locally or download it as a zip
+// ANCHOR: steps
+1. Build the software according to the [readme](https://git.distrust.co/public/airgap) in the repository.Use the `make reproduce` command.
 
-    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/`
+2. Verify the software according to [this guide](verifying-signatures.md)
 
 3. Place signed .iso on a storage device
 
@@ -43,6 +31,7 @@ The resulting iso will be located in `airgap/out/`
     ```
 
 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.
 
@@ -52,10 +41,15 @@ The resulting iso will be located in `airgap/out/`
 
     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
+5. Lock the SD card using `sdtool`
+
+6. 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
+7. 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.
+booting the ISO image to ensure it can be trusted.
+
+// ANCHOR_END: steps
+/* ANCHOR_END: all */

quorum-key-management/src/sd-formatting.md

@@ -0,0 +1,30 @@
+# SD Formatting
+// ANCHOR: steps
+1. Insert a fresh SD card into the SD card slot or connect it via a USB card reader to your computer
+
+    * microSD or standard SD card can be used
+
+2. Launch a terminal 
+
+3. List all block devices, including your SD card:
+
+    * `lsblk`
+
+4. Look for your SD card in the output of the `lsblk` command. It will typically be listed as /dev/sdX, where X is a letter (e.g., /dev/sdb, /dev/sdc). You can identify it by its size or by checking if it has a partition (like /dev/sdX1)
+
+5. Before formatting, you need to unmount the SD card. Replace /dev/sdX1 with the actual partition name you identified in the previous step:
+
+    * `sudo umount /dev/sdX1`
+
+6. Use the mkfs command to format the SD card. You can choose the file system type (e.g., vfat for FAT32, ext4, etc.). Replace /dev/sdX with the actual device name (without the partition number):
+
+    * `sudo mkfs.ext4 /dev/sdX`
+
+7. You can verify that the SD card has been formatted by running lsblk again or by checking the file system type:
+
+    * `lsblk -f`
+
+8. Once formatting is complete, you can safely remove physically or eject the SD card:
+
+    * `sudo eject /dev/sdX`
+//ANCHOR_END:steps

quorum-key-management/src/sdtool-instructions.md

@@ -0,0 +1,29 @@
+/* ANCHOR: all */
+# sdtool Usage Guide
+
+[`sdtool`](https://github.com/BertoldVdb/sdtool) is a tool for locking the contents of a SD card by means of burning a physical fuse.
+
+> It is relatively unknown that SD/MMC cards also have an electronic write protection system. Every card has two programmable flags, one for temporary write protection and one to lock the card forever. Writing these flags is not supported by most SD host devices. To remedy this, this page presents a program that allows a Linux host to configure the protection register.
+
+This tool is also available via [stagex](https://registry.hub.docker.com/r/stagex/sdtool). The binary can be exported from the image by doing the following:
+
+// ANCHOR: steps
+1. Get deterministically built binary of `sdtool` from StageX: 
+    * `docker pull stagex/sdtool`
+
+1. 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](https://codeberg.org/stagex/stagex/src/branch/main/signatures/stagex) in stagex project for latest signed hashes
+
+1. `./sdtool /dev/mmcblk permlock`
+
+1. Test that the card can't be written to:
+
+    * `dd if=out/airgap.iso of=/dev/sdb bs=1M conv=sync status=progress`
+
+// ANCHOR_END: steps
+/* ANCHOR_END: all */

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

@@ -1,5 +1,7 @@
+/* ANCHOR: all */
 # Secure Boot Sequence
 
+// ANCHOR: content
 Steps 1-12 can be skipped if the media drive with `airgap` has been verified in
 advance.
 
@@ -28,7 +30,7 @@ binary they built on their own system according to the [AirgapOS Setup Playbook]
 
 12. Once everyone is satisfied that the hash matches, the computer should be
 be restarted.
-
+// ANCHOR: prepared
 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
@@ -40,4 +42,8 @@ be restarted.
 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).
+which was noted during the [AirgapOS Setup](repeat-use-airgapos.md).
+// ANCHOR_END: prepared
+// ANCHOR_END: content
+
+/* ANCHOR_END: all */

quorum-key-management/src/side-channel-attacks.md

@@ -0,0 +1,18 @@
+# Side Channel Attacks
+
+* Acoustic (DiskFiltration, Fansmitter, Acoustic Cryptanalysis, sonic cavity resonators, etc.)
+
+* Optical (VisiSploit, xLED, eavesdropping via vibration analysis etc.)
+
+* Thermal (BitWhisper)
+
+* Electrical (Simple Power Analysis (SPA), Differential Power Analysis)
+
+* Magnetic (ODINI)
+
+* Electromagnetic (USBee)
+    * Exfiltrating data via induction of power lines, water pipes, telephone lines, coaxial cable used for televisions and internet etc.
+
+* Radio (NFCDrip, Vapor Trail, RFID, FM, Wifi, Bluetooth, GSM, SATA cable eavesdropping etc)
+
+* Steganography

quorum-key-management/src/software.md

@@ -42,3 +42,8 @@ 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.
+
+
+## [Icepick](https://git.distrust.co/public/icepick)
+
+Icepick is a framework for rapidly developing applications to perform transfer and staking cryptocurrency operations. It works synergistically with `keyfork` which derives keys which are then used by `icepick`.

quorum-key-management/src/system-roles.md

@@ -0,0 +1,35 @@
+# System Roles
+
+There are several roles which are required to properly operate the QVS system. While it is possible to have an individual perform multiple roles, typically they should only perform one role at a time. It is also recommended to have at least 2 individuals, or ideally the full quorum be used to make decisions pertaining to QVS. At least 2 individuals are required for [level 2](threat-model.md#adversary-1).
+
+To better understand why the different roles are required, refer to the [selecting a quorum](selecting-quorum.md) and [threat model](threat-model.md) sections which enumerate a number of assumptions around pertinent threats to the system as well as the use of a quorum. 
+
+## General Requirements
+
+Individuals who are selected for the roles:
+
+* MUST have background checks conducted
+
+* MUST have a clearly defined set of responsibilities
+
+* MUST be reinvestigated once a year to ensure they meet necessary standards to access restricted information
+
+## Proposer
+
+This is an individual who is a business owner or stakeholder, or a financial controller. Their role is to make fiduciary decisions which protect the financial interest of the organization and its clients. Their role is specifically to propose the movement of funds, specifying the amount, origin and destination.
+
+## Approver
+
+This is an administrative role which participates in the decision making capacity, typically as part of a quorum. Additional policies which are not for the QVS system but related decision making may be under the purview of an Approver. While there is 1 proposer per transaction, there may be an arbitrary number of Approvers, and they are required to sign proposed transactions according to a [policy](todo) which should be well defined.
+
+## Operator
+
+Trained on how the QVS(todo) system operates, with intimate knowledge of the processes which are required to maintain the integrity, confidentiality and availability (CIA triad) of the system.
+
+Operators conduct ceremonies and ensure that the controls around QVS are in tact. They verify instructions from [Approvers](#approver) and perform different actions which are part of the QVS system, ranging across hardware procurement, accessing SCIFs, preparing field kits, performing ceremonies and more.
+
+As a QVS grows, it may be prudent to create more highly specialized roles whose responsibilities are limited to a more narrow range, creating more isolation across the system, thus enforcing the principle of least privilege and separation of concerns.
+
+## Witness
+
+QVS relies of having individuals present to witness that processes which uphold the security of the system are properly followed. [Operators](#operator) make ideal witnesses as their familiarity with the QVS system allows them to detect any deviation from the processes which uphold the security of the system. While it is not required that a Witness be a trained Operator, it is highly preferred.

quorum-key-management/src/tamper-evidence-methods.md

@@ -0,0 +1,239 @@
+/* ANCHOR: all */
+
+// ANCHOR: entire-doc
+# Tamper Evidence Methods
+
+There are different methods which can be used to ensure that objects have not been tampered between uses. This is especially relevant for equipment such as laptops. Each method comes with tradeoffs, and in the context of high assurance security it is instrumental to understand the tradeoffs in order to achieve an adequate level of confidence that supplies such as computers used for high risk operations retain their integrity.
+
+There are a number of common methods which appear to provide a reasonable level of tamper evidence, but in fact do not. It is worth noting a few examples of these such as using tamper evident tape, or even glitter if done improperly. This document will focus on illustrating adequate methods, rather than enumerating ones that are inadequate.
+
+## Properties
+
+Tamper evident methods need to be:
+
+* Difficult to circumvent
+
+* Simple to set up
+
+* Simple to verify
+
+There are three reasonably secure methods which have been identified and are explored in this document that can be used in different contexts:
+
+* Vacuum sealing objects surrounded by colored filler
+
+* Glitter on screws
+
+* Heads / Pureboot for secure boot
+
+
+#### Level 1 + 2
+
+This threat level assumes fairly unsophisticated attackers, and as such, basic tamper proofing methods can be effective. These attackers would have a difficult time pursuing physical attacks such as evil maiden attacks, or covertly stealing and replacing hardware.
+
+As such one of the following combinations of tamper proofing methods MUST be used:
+
+* [Glitter on screw](#glitter-on-screws) + [pureboot/heads](#pureboot--heads)
+
+* [Vacuum sealing with filler](#vacuum-sealed-bags-with-filler)
+
+#### Level 3
+
+This level of threat actors has a more extensive range of attacks which may include physical attacks. As such additional counter measures are required to ensure that the integrity and confidentiality of information is retained. The threat modelling document contains more information about this [level](threat-model.md#level-3)
+
+* MUST combine [glitter on screws](#glitter-on-screws), [pureboot/heads](#pureboot--heads), and [vacuum sealing with filler](#vacuum-sealed-bags-with-filler)
+
+* MUST maintain 2 person [chain of custody](hardware-procurement-and-chain-of-custody.md)
+
+#### Level 4
+
+This is the highest threat level and as such requires additional controls which protect hardware. More details around the capabilities of threat actors at this level are available in the [threat modeling document](threat-model.md#level-4)
+
+* MUST use high grade tamper evident safes
+
+* MUST use physical access controls
+
+* MUST have continued surveillance of the storage location
+
+## Vacuum Sealed Bags With Filler
+// ANCHOR: vsbwf-whole
+
+One of the most reliable methods for ensuring tamper evidence relies on the randomness and difficulty of placing small objects henceforth referred to as "filler" (colored rice, lentils, confetti) in a transparent bag to encase an object which is then vacuum sealed. By placing an object in a transparent, vacuum sealable bag and surrounding it with filler, an arrangement of the filler around the object in the bag can be achieved which is difficult to reproduce. Upon sealing the object in this manner, photos can be taken to use as a reference once the object is accessed again - allowing one to verify that the arrangement of the filler has not changed.
+
+### Threat Model
+
+There are no known attacks for this type of tamper proofing method when executed properly. The main sources of risk stem from consistent and repeatable photography and comparison of photographs to ensure that any changes can be detected.
+
+If photographs are not cryptographically signed, they can also be manipulated and/or replaced which could result in the compromise of the system as well.
+
+The reason this method is effective is because unlike with many other methods that tamper proof a specific part of an object, such as applying glitter to screws which leaves device ports exposed, or using cryptographic signing to verify the hardware has not been modified, still leaving the door to physical modifications, vacuum sealing with colored filler encases the entire object in a tamper evident manner.
+
+### Adequate Filler
+
+To achieve the best level of randomness and difficulty of reproducing the arrangement of filler in a vacuum sealed bag, a variety of beads of different sizes and color should be used. They may be made of different materials as well but plastic is excellent because it doesn't change form when vacuum sealed - which can make it easier to reproduce patterns. Materials such as confetti and packing beans may be used, but because they can be flattened and retain the shape, arranging them in a given pattern is much easier. Other options like beans or lentils have less variety in color and shapes which makes it harder to detect differences.
+
+Examples of filler:
+// ANCHOR:vsbwf-filler
+* [B100B5LB – 5 Lb Mixed Craft Bead Bonanza Case](https://www.thebeadery.com/product/b100b5lb-5-lb-mixed-craft-bead-bonanza-case/)
+* [Plastic Beads - Multi Color & Size - 700ml](https://www.stockade.ca/Plastic-Beads--Multi-Colour-Size--700ml_p_8402.html)
+// ANCHOR_END:vsbwf-filler
+### Vacuum Sealers
+
+Vacuum sealer needs to be able to seal bags of sufficient size to fit a 13" laptop
+
+* [Nesco Deluxe Vacuum Sealer – VS-12P](https://www.nesco.com/product/deluxe-vacuum-sealer/)
+
+* [Anova Precision Vacuum Sealer Pro](https://anovaculinary.com/en-ca/products/anova-precision-vacuum-sealer-pro)
+
+
+Sealing bags of standard size objects which need to be protected can fit in. The bags should be perfectly see through, rather than with writing or any irregularities in the plastic which can obfuscate the view of the inside of the bag. 11" width is recommended.
+
+* [Anova Precision Vacuum Sealer Rolls (11" x 19.60')](https://anovaculinary.com/en-ca/products/anova-precision-vacuum-sealer-rolls)
+
+* [2 Vacuum Sealer Rolls (11.0" x 19.70')](https://www.nesco.com/product/2-vacuum-sealer-rolls-11-0-x-19-70/)
+
+### Additional Considerations
+
+* This strategy may be layered, for example if one chooses to apply it to a hardware token, the sealed hardware token can be placed inside of a bigger bag, along with a laptop.
+
+* A similar method can be used but with a bin filled with filler that the object is placed into. The main disadvantage here is that this type of tamper proofing is not resistant to seismic activity, air movement, or other sourced of vibration which could shift filler around.
+
+### Procedure
+// ANCHOR: vsbwf-procedure
+
+#### Requirements
+// ANCHOR: vsbwf-equipment
+* [Vacuum sealer](tamper-evidence-methods.md#vacuum-sealers)
+
+* [Vacuum plastic roll](tamper-evidence-methods.md#vacuum-sealers)
+
+* [Filler](tamper-evidence-methods.md#adequate-filler)
+// ANCHOR_END: vsbwf-equipment
+
+#### Sealing
+// ANCHOR: vsbwf-procedure-sealing
+
+1. Insert object into plastic bag
+
+2. Fill bag with enough plastic beads that all of the object is surrounded
+
+3. Use vacuum sealer to remove air from the bag until the beads are no longer able to move
+
+4. Use the [Tamper Proofing Station](tamper-evidence-methods#tamper-proofing-station) to take a photograph of both sides of the sealed object using both the digital and polaroid camera
+
+5. Take the SD card to an online connected device and commit the photographs to a repository, ensuring the commit is signed
+// ANCHOR_END: vsbwf-procedure-sealing
+
+#### Unsealing
+// ANCHOR: vsbwf-procedure-unsealing
+
+1. Retrieve photographs of the top and the bottom of the object which were taken of the sealed object
+
+3. Compare polaroid and printed photographs of digital record to the current state of the sealed object
+
+4. Compare polaroid to printed photographs of digital record
+
+2. If there is no noticeable difference, proceed with unsealing the object, otherwise initiate an [incident response process (todo)](TODO).
+
+// ANCHOR_END: vsbwf-procedure-unsealing
+
+// ANCHOR_END: vsbwf-procedure
+// ANCHOR_END: vsbwf-whole
+
+## Glitter on Screws
+
+Glitter can be used as an additional control to provide tamper evidence on specific parts of hardware such as laptop screws - in case an adversary attempts to open the laptop and introduce a malicious chip, antenna or otherwise.  While glitter allows to detect physical tampering of the hardware, it does not provide tamper evidence of the firmware and software that runs on the computer, and as such is not sufficient for adequate tamper proofing of laptops on its own.
+
+### Procedure
+
+#### Requirements
+
+* 2 or 3 different types of glitter, ideally with small and large pieces of glitter of different colors
+
+#### Sealing
+
+1. Clean the surface the glitter will be applied to
+
+2. Apply a thin layer of the first type of glitter
+
+3. Wait for it to dry
+
+4. Repeat steps 2, 3 with the different types of glitter being used
+
+5. Take a photograph of the laptop, preferably using the [tamper proofing station](tamper-evidence-methods#tamper-proofing-station)
+
+6. Ensure the SD card is in dual custody until it's uploaded to a repository, and signed by both parties (one creates a PR, the other creates a signed merge using the `git` CLI)
+
+#### Verification
+
+There is no "unsealing" procedure as the glitter used on screws, or in other similar contexts is meant as a more permanent control. As such the primary action that's performed is the verification of the integrity of the tamper proofing seal.
+
+To verify that the seal has not been tampered, compare the glitter arrangement to a photograph which had been previously signed and stored. Both operators should have a copy of the picture and use it to verify the integrity of the seal.
+
+## PureBoot / Heads
+
+This tamper proofing method is designed to protect the secure boot process of a computer. It does not protect the computer from physical tampering which can be used to ad
+
+### Procedure
+
+Refer to the [PureBoot Setup](./enable-pure-boot-restricted-boot.md) document
+
+## Tamper Proofing Station
+
+The Tamper Proofing Station is a simple structure used to make it easy to take photographs which have consistent lightning, consistent angle, and consistent distance from the object being photograph. In this manner, photographs can be taken which ensure that any differences in the sealed object can be easily detected.
+
+### Instructions
+
+To construct an appropriate Tamper Proofing Station, the simplest setup consists of:
+
+* Overhead camera mounting rig
+
+* Powerful LED light which can be attached to the mounting rig
+
+## Digital Camera
+
+* MUST have >10MP
+- [ ] TODO these cameras are specifically for level 2. this should be moved into a different section. perhaps each level can have its own hardware document
+- [ ] TODO amazon links are not ideal, more reliable and vetted hardware providers should be established
+### Models
+// ANCHOR:digital-cameras
+
+* Modern phone cameras
+
+* [Kodak PIXPRO Friendly Zoom FZ43-BK 16MP Digital Camera with 4X Optical Zoom and 2.7" LCD Screen](https://www.amazon.com/Kodak-Friendly-FZ43-BK-Digital-Optical/dp/B01CG62D00)
+    
+* [Kodak PIXPRO Friendly Zoom FZ43-BK 16MP Digital Camera with 4X Optical Zoom and 2.7" LCD Screen](https://www.amazon.com/KODAK-Friendly-FZ45-BK-Digital-Optical/dp/B0B8PDHRWY)
+
+* [Sony Cyber-Shot DSC-W800](https://www.amazon.com/Sony-DSCW800-Digital-Camera-Black/dp/B00I8BIBCW)
+// ANCHOR_END:digital-cameras
+
+## Polaroid camera
+
+* Can be attached to mounting rig
+
+### Models
+// ANCHOR: polaroid-cameras
+* [Polaroid Now+](https://www.amazon.com/Polaroid-Generation-Bluetooth-Connected-Controlled/dp/B0BVNJHMVQ)
+
+* Preferred film: [Color I-Type Film](https://www.amazon.com/Polaroid-Originals-Instant-Color-I-Type/dp/B084GXXLM7)
+// ANCHOR_END: polaroid-cameras
+
+Pick a location for the station, and attach the LED light and the camera to the overhead camera mounting rig. Set up the camera so that when it's turned on, a 14" laptop is perfectly framed without having to zoom in or out if possible.
+
+## Safe
+
+Placing objects into a safe helps improve the security of objects, and introduces an additional layer of tamper evidence.
+
+## References
+
+* [Blog About Tamper Evident Protection Methods](http://web.archive.org/web/20241130002204/https://dys2p.com/en/2021-12-tamper-evident-protection.html)
+
+* [BitBoxTep - tamper-evident packaging](http://web.archive.org/web/20240519013739/https://medium.com/shiftcrypto/an-introduction-to-bitboxtep-our-new-tamper-evident-packaging-8fa06d983c32)
+
+* [Mullvad - glitter tamper proofing](http://web.archive.org/web/20240317004315/https://mullvad.net/en/blog/how-tamper-protect-laptop-nail-polish)
+
+* [Purism anti-interdiction](http://web.archive.org/web/20241121233006/https://puri.sm/posts/anti-interdiction-services/)
+
+* [Purism Liberty phone anti-interdiction](http://web.archive.org/web/20240903104700/https://puri.sm/posts/anti-interdiction-on-the-librem-5-usa/)
+// ANCHOR_END: entire-doc
+
+/* ANCHOR_END: all */

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

@@ -1,10 +1,10 @@
 # Threat Model
 
-QKM is designed according to a high-assurance threat model which ers on the
+QVS 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
+The assumption is made that attackers who target QVS 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
@@ -18,7 +18,7 @@ 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:
+To achieve this, the QVS focuses on reducing the risk by:
 
 * Only using fully open source software and firmware to allow full verification
 of their security properties
@@ -40,6 +40,8 @@ which had radio networking cards (bluetooth, wifi etc.) removed
 
 * Leveraging tamper evident controls for components related to the system
 
+* Leveraging frequency blocking methods such as TEMPEST (Telecommunications Electronics Materials Protected from Emanating Spurious Transmissions) and soundproofing
+
 ## General Threat Model Assumptions
 
 Some additional assumptions are made to help contextualize the threat model:
@@ -60,6 +62,325 @@ Some additional assumptions are made to help contextualize the threat model:
 
 * Physical attacks are viable and likely
 
+* Side-channel attacks are viable and likely
+
+## Threat Model Levels
+
+Different threat model levels allow an organization to start benefiting from the security properties of the QVS system immediately, with a clear path to upgrading over time as resources and time become available.
+
+Each subsequent level assumes all threats and mitigations from the previous level, and introduces more sophisticated attacks and mitigations. As such, the levels should for the most part be adhered to one at a time, to ensure comprehensive defenses for all viable threats enumerated herein.
+
+## Level 1
+
+### Threat Model
+
+#### Adversary
+
+Low skilled individual targeting many organizations. This implies the adversary is not highly focused on compromising a specific organization, and relies on less sophisticated strategies.
+
+This level focuses on defending against remote adversaries.
+
+#### Attacks
+
+* Using phishing to steal data from a random set of custodian end users
+
+* Injecting malware into the system of a random set of custodian end users
+
+#### Requirements
+
+* MUST require hardware anchored login for large withdrawals
+
+* MUST require hardware anchored signature for large withdrawal requests
+
+* MUST verify withdrawal requests according to a threshold based policy
+
+#### Reference Design
+
+* Ensure all users withdrawing large sums over a short period of time are using FIDO2 or PGP capable smart cards for logging in and authorizing transactions:
+
+    * Hardware based WebAuthN/Passkey/U2F
+
+        * Android 7.0+, iOS 14+, MacOS 10.15+, Win10 1809+, ChromeOS, Yubikey 5, Nitrokey, Ledger, Trezor
+
+    * Consider software-based WebAuthN/Passkey/U2F as backup
+
+* Ensure backend systems will only approve large withdrawals if signed by known smart card.
+
+* Ensure all transaction approval keys are stored in a tamper evident append only database.
+
+    * To achieve this storage systems such as AmazonQLDB, git, Datomic etc. can be used
+
+* Ensure all key additions are authenticated with a quorum of existing keys
+
+* Consider allowing quorum of support engineer keys to enroll a new key to handle lost keys
+
+* Use hash of transaction signing request as challenge to be signed by smart-card
+
+* Blockchain signature only issued after verification a given request is signed by authorized user smart-card(s)
+
+## Level 2
+
+### Threat Model
+
+#### Adversary
+
+Adversary is a skilled and resourceful individual targeting one organization. This type of attacker uses a combination of widely used cyber weapons, OSINT, social engineering (spear phishing), exploiting vulnerabilities, MitM attacks.
+
+This level focuses on defending against insider threats.
+
+#### Attacks
+
+* Compromise one team member with privileged access
+
+* Inject code into any OSS library
+
+* Exploit any vulnerability within 24h of public knowledge
+
+### Requirements
+
+* All production access:
+
+  * MUST NOT be possible by any single engineer
+
+    * Consider a bastion that can enforce m-of-n access over ssh
+
+    * Consider hardened deployment pipeline which requires m-of-n cryptographic signatures to perform action
+
+  * MUST be via dedicated tamper evident workstation
+
+    * Consider: https://github.com/hashbang/book/blob/master/content/docs/security/Production_Engineering.md
+
+  * MUST be anchored to keys in dedicated HSMs held by each administrator
+
+    * Consider OpenPGP or PKSC#11 smart cards that support touch-approval for ssh
+
+* Any code in the transaction signing trust supply chain:
+
+  * MUST build deterministically
+
+  * MUST have extensive and frequent review
+
+  * MUST be signed in version control systems by well known author keys
+
+  * MUST be signed by separate subject matter expert after security review
+
+    * MUST hash-pin third party code at known reviewed versions
+
+  * MUST be at version with all known related security patches
+
+  * SHOULD be latest versions if security disclosures lag behind releases otherwise N-2
+
+  * MUST be built and signed (and hashes compared) by multiple parties with no management overlay
+
+    * Example: One build by IT, another by Infrastructure team managed CI/CD
+
+  * MUST be signed by well known keys signed by a common CA
+
+    * Example: OpenPGP smart cards signed under OpenPGP-CA.
+
+  * All private keys involved:
+
+    * MUST NOT ever come in contact with network accessible memory
+
+  * All execution environments MUST be able to attest what binary they run
+
+    * Examples:
+
+      * Custom Secure Boot verifies minimum signatures against CA
+
+      * Cloud enclave that can remotely attest it uses a multi-signed image
+
+        * TPM2, AWS Nitro Enclave, Google Shielded VMs etc.
+
+      * App phone stores already anchor to developer held signing keys
+
+### Reference Design
+
+* Create offline CA key(s)
+
+* Consider OpenGPG key generated on airgap using keyfork, backed up, and copies transmitted to a smart cards such as a Yubikey
+
+* CA key smart cards are stored in dual-access tamper evident locations
+
+#### User Key Management System
+
+* Enclave is created which is immutable with no ingress internet access
+
+* Enclave has random ephemeral key
+
+* Remotely attested on boot-up against multi-signed and known deterministically built system image
+
+  * Possible on many PCR based measured boot solutions based on TPM2 and Heads, AWS Nitro Enclaves, or GCP Shielded VMs
+
+* Ephemeral enclave key is signed with offline CA key(s) on verification.
+
+* Enclave has ability to validate append only database of keys
+
+* Enclave will sign new key additions/removals with ephemeral key if:
+
+  * User has no prior keys
+
+  * Key was signed with an existing key
+
+  * Key was signed with 2+ known support engineer keys
+
+#### Signing Key Generation
+
+* M-of-N key holder quorum is selected
+
+  * SHOULD be on different teams
+
+  * SHOULD live in different geographical zones to mitigate natural disaster, and war related risks
+
+  * SHOULD have their own OpenPGP smart card with pin and keys only they control
+
+* Shard keys
+
+  * SHOULD be an additional OpenPGP smart card separate from holder's personal key
+
+  * SHOULD have random PIN, encrypted to a backup shard holder
+
+  * SHOULD be stored in a neutral location only the primary and backup shard holder can access
+
+* Done in person on air-gapped laptop that has been in [dual witnessed custody](hardware-procurement-and-chain-of-custody.md) since procurement
+
+  * Has hardware anchor that can make all parties confident the OS image it is running is expected (Heads, etc)
+
+  * Has two hardware sources of entropy
+
+    * There are devices that can provide an additional source of entropy such as:
+
+      * Computer with another architecture such as RISC-V
+
+      * HSM which can export entropy
+
+      * Quantis QRNG USB
+
+      * TrueRNG
+
+  * Runs known deterministic and immutable OS image compiled by multiple parties
+
+* Key is generated and stored
+
+  * Split to m-of-n Shamir's Secret Sharing shards
+
+    * Each shard is encrypted to dedicated shard OpenPGP smart card
+
+    * Shard smart card PIN is generated randomly
+
+    * Shard smart card PIN is encrypted to personal smart cards of primary and backup holders
+
+#### Signing System
+
+* Uses an enclave which is immutable with no ingress internet access
+
+* Has enclave bound ephemeral key
+
+* Remotely attested on boot-up against multi-signed and known deterministically built system image
+
+* Will accept Shamir's Secret Sharing shards encrypted to enclave bound ephemeral key
+
+* Will restore signing key to memory when sufficient shards are submitted
+
+* Will only sign transactions if accompanied by signed request by authorized user according to a quorum specified by a policy
+
+  * Is able to validate signing request via CA key authorized user key management enclave signature
+
+* Will only sign transactions that meet predefined size and rate limits by company policy and insurance levels
+
+## Level 3
+
+### Threat Model
+
+#### Adversary
+Adversary is an organized group with significant funding. These groups consist of individuals with different skill sets and often have access to significant funds, drastically expanding their attack capabilities.
+
+This level focuses on defending against adversaries who succeeded in local compromise.
+
+#### Attacks
+
+* Compromise one data center engineer into tampering with a target system
+
+* Use a sophisticated 0 day vulnerability to compromise any one internet connected system
+
+### Requirements
+
+* MUST sign all transactions of significant value by multiple keys in separate geographical locations
+
+ * Consider well vetted open source multi signature, MPC or on-chain threshold signing software
+
+ * MUST use locations separated by hours of travel
+
+ * MUST have independent staff for separate locations
+
+ * Signing locations MUST NOT trust other locations
+
+   * Each location MUST do their own reproducible build validation
+
+   * Each location MUST do their own verifications on all large transactions
+
+## Level 4
+
+### Threat Model
+
+#### Adversary
+
+Adversary is a state actor. State actors are the best funded and most sophisticated attackers. They are the highest known threat and have the ability to execute all known attacks. Their well funded operations allow them to pursue goals over long periods of time, relying on subversion, false flags, insider threats via planting moles, compromise of hardware supply and software supply chains, the use of advanced non-commercially available cyber-warfare tools, combining many 0day vulnerabilities to construct highly effective exploit chain. This level of adversary demands the highest known standards of security, which is typically upheld only by the most sophisticated companies and the military.
+
+This level focuses on defending against adversaries who are nation states.
+
+#### Attacks
+
+* Tamper with the supply chain of any single hardware/firmware component
+
+* Quickly and covertly relocate any device to a lab environment, complete attacks within a short time period, and return the device to its original location
+
+* Use sophisticated [side channel attacks](side-channel-attacks.md) for exfiltrating data, cryptographic material being a high risk target
+
+* Non-deterministic encryption/signatures/data
+
+* Differential Fault Analysis (DFA)
+
+* Data remanence
+
+### Requirements
+
+* All signing systems:
+
+  * MUST have dual implementations of all policy enforcement and signing logic
+
+  * MUST use two or more unrelated hardware supply chains for generating cryptographic material
+
+    * Example: Rust on RISC-V Linux on an FPGA vs C on PPC Gemalto enclave
+
+  * MUST return deterministic results
+
+    * Results are only exported for chain broadcast if identical
+
+  * MUST be stored in near zero emissions vaults a single user can't open
+
+    * See: NSA TEMPEST
+
+  * MUST ensure that individuals are scanned for devices before entering the vault
+
+  * MUST only communicate with outside world via fiber optic serial terminal
+    - [ ] TODO do we even want this in the facility?
+
+  * MUST be housed in Class III bank vault or better
+
+  * MUST have constant environment deviation monitoring
+
+    * Thermal, Acoustic, Air quality, Optical
+
+  * MUST destroy key material on significant environment deviations
+
+    * TODO: methods for doing this
+
+  * MUST be accessible physically with cooperative physical access
+
+    * MAY use FF-L-2740B or better locks with dual pin enforcement
+
+    * MAY use dual biometric enforcement to get near area and disarm security
 
 ## Additional Threat Model Notes
 

quorum-key-management/src/verifying-signatures.md

@@ -0,0 +1,57 @@
+# Verifying Signatures
+
+When building and downloading software it is essential to verify signatures to ensure its integrity. It is also important to verify that the latest commit, and ideally that all commits that are being used to build from are verified to have signatures from trusted keys. This can be done using `git verify-commit HEAD` or similar. A script like below can be modified to check for trusted keys for all commits:
+
+```bash
+#!/bin/bash
+
+mapfile -t trusted_keys < trusted_keys.txt
+
+is_trusted_key() {
+    local key="$1"
+    for trusted_key in "${trusted_keys[@]}"; do
+        if [[ "$key" == "$trusted_key" ]]; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+git rev-list --all | while read commit; do
+    if git verify-commit "$commit" > /dev/null 2>&1; then
+        key_id=$(git show "$commit" | grep 'gpgsig' | awk '{print $NF}')
+        
+        if ! is_trusted_key "$key_id"; then
+            echo "$commit: Signed but NOT by a trusted key ($key_id)"
+        fi
+    else
+        echo "$commit: Not signed"
+    fi
+done
+```
+
+Verification of software depends on two primary aspects:
+
+* Ensuring that the hash of a binary matches some point of reference, for example the same binary previously built by a trusted team member, or a hash hosted alongside the software in the download location.
+
+* Ensuring that signatures alongside hashes are from trusted asymmetric keys (e.g PGP keys)
+
+In order to achieve this, one must establish that specific keys are "well known" and can be trusted - that is, that they belong to a given individual. To achieve this, the best method is to exchange keys in person, but a combination of the following methods gives even higher confidence thresholds:
+
+* Verifying the key in person
+
+* Finding a reference to a public key on the individual's personal website
+
+* Finding a reference to a public key on the individual's social media platforms
+
+* Finding a keyoxide profile for a given public key
+
+* Finding a reference to a public key on a company website
+
+* Looking up popular key servers to see if a given individual is associated with it
+
+Each point of reference allows us to build confidence that the key is indeed owned by an individual.
+
+One other consideration is how the key is protected. If possible, find out how the individual manages their key. If the key is stored on a local machine, the trust level for that key should be low. If the individual always manages their keys in airgapped environments, and on HSMs, then a higher level of trust can be ascribed - although ultimately in most cases it's impossible to verify that the individual followed a given policy around key management.
+
+One favorable method for ensuring that a key never got exposed is using built in cryptographic attestation that a key never left a TPM, such as the one offered by YubiKey. While this type of key setup has the downside of not being able to back it up, one could use a master key to sign such a key, authorizing it for use, while giving the flexibility to rotate if the hardware token is damaged or lost.