refactor the provisioner document

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/generated-documents/level-2/fixed-location/provisioner/procure-hardware.md

@@ -4,33 +4,44 @@ The provisioner is responsible for:
 
 * Procuring equipment
 
-* Setting up the Location
+* Setting up the [Facility]()
 
-* Maintaining stock of supplies in the [Location]()
+* Maintaining stock of supplies in the [Facility]()
 
 * Minimizing hardware supply chain security risks
 
-* Ensuring availability of necessary equipment
-
 ## Directives
 
-* MUST maintain chain of custody for all hardware until after it's properly tamper-proofed
+* MUST maintain chain of custody for all hardware until after it's properly stored or where necessary tamper-proofed
 
 - [ ] do we need to tamper proof usb equipment?
     * no because we verify hashes of data on the ceremony machines
 
-## Laptops
+---
+Order of things:
+- [x] set up facility
+- [x] preparing sd card
+- [x] prepare airgapos
+- [x] procure computer
+- [ ] prepare trusted keys card
+- [ ] prepare shardfile
+- [ ] tamper proof computer and cards
 
+---
 
+The different procedures are ordered in chronological preference, to improve the efficiency of setting up the system.
 
-* [Purism Librem 14](../../../../hardware.md#air-gapped-computer)
+## Facility
 
-* ChromeBook or a computer capable of running QubesOS according to [this guide](../../../../online-machine-provisioning.md)
+1. Identify a location which is suitable for Level 2 ceremonies:
 
-## Provisioning AirgapOS
+    * SHOULD be lockable to prevent inflow and outflow of persons during ceremonies
 
-Provision AirgapOS using [this guide](../../../../one-time-use-airgapos.md)
+    * SHOULD have locker for equipment
 
+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
 
 ## Tamper Proofing Equipment
 
@@ -46,54 +57,50 @@ This guide contains specific equipment models: [guide](../../../../tamper-eviden
 
 * Polaroid camera
 
-## Other Equipment
+## AirgapOS
 
-* SD cards
+{{ #include ../../../../one-time-use-airgapos.md:steps }}
 
-    * [Kingston Industrial 8GB SD Memory Card](https://www.kingston.com/en/memory-cards/industrial-grade-sd-uhs-i-u3?capacity=8gb)
+## Computer Procurement
 
-    * [Kingston Indsutrial 8GB microSD Memory Card](https://shop.kingston.com/products/industrial-microsd-card-memory-card?variant=40558543405248)
+For [Level 2](../../../../threat-model.md#level-2) security, air-gapped computers which are used for cryptographic material management and operations are required.
 
-* microSD to SD adapter
+### Models
 
-    * TODO find specific products
+{{ #include ../../../../hardware-models.md:computer-models }}
 
-* SD Card USB Adapter
+### Procedure
 
-    * SD card reader: https://www.kingston.com/en/memory-card-readers/mobilelite-plus-sd-reader
+1. Follow the [chain of custody procurement procedure](../../../../hardware-procurement-and-chain-of-custody.md)
 
-    * microSD card reader: https://www.kingston.com/en/memory-card-readers/mobilelite-plus-microsd-reader
+1. Apply [vaccum sealing with filler](../../../../tamper-evidence-methods.md#vacuum-sealed-bags-with-filler) tamper proofing.
-
-    * Workflow station hub (may prove helpful with workflows): https://www.kingston.com/en/memory-card-readers/workflow-station-hub
-
-* PureBoot smart card (TODO)
-
-* [Online machine](../../../../../../online-machine-provisioning.md) used for fetching transaction data
 
 ## Preparing SD Cards
 
-### Freshly Formatted Cards
+### 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
 
-        * It is the provisioner's responsibility to keep track of the number of ceremonies and replenish stock as needed
-
     * Both microSD and regular SD cards should be available
 
     * They should be formatted to `ext4` format
 
-    - [ ] consider renaming location ot vault/facility
-
-- [ ] TODO find a way to format many cards at once
-
 * 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 }}
+
 ### Shardfile 
 
 There should be multiple SD cards containing the shardfile data. Shardfile data is produced during a [Root Entropy](todo) derivation ceremony.
@@ -102,31 +109,42 @@ There should be multiple SD cards containing the shardfile data. Shardfile data
 
 * This should be write-locked and stored in tamper proofing along with air-gapped machine
 
-### Trusted Keys
+## Trusted Keys
 
-* Label: Trusted Keys
+### Procedure
 
-* 1 SD card with "trusted keys" for proposers and approvers, both signed by each operator using their operator key
+This procedure requires 2 individuals in order to witness the process.
 
-* This should be write-locked and stored in tamper proofing along with air-gapped machine
+1. Get a freshly formatted SD card 
 
-### AirgapOS
+1. Plug it into a computer
 
-* Label: "AirgapOS <version>"
+1. Navigate the the official Keychain repository of your organization
 
-* This should be write-locked and stored in tamper proofing along with air-gapped machine
+1. Select provisioner and approver keys from the Keychain repository
 
-## Preparing The Location
+1. Export the keys using `gpg --armor --export <key_id> > <key_id:individual_name>.asc`
 
-### Locker / Safe
+    * Repeat step for all needed keys
 
-* establish a means of locking up equipment
+1. Copy the `.asc` files to the SD card
 
-### Air-gapped bundle
+1. Use the `sdtool` to lock the card
 
-* tamper proof together: Apply [vacuum sealing + filler tamper proofing](../../../../tamper-evidence-methods.md#vacuum-sealed-bags-with-filler) to the laptop and the AirgapOS SD card
+{{ #include ../../../../sdtool-instructions.md:steps }}
-    * air-gapped machine
-    * airgapos sd card
 
+1. Label the card "Trusted Keys <date>"
 
+## Air-gapped bundle
 
+* Tamper proof together the following objects:
+    
+    * [Air-gapped machine](#computer-procurement)
+    
+    * [AirgapOS SD card](#airgapos)
+
+    * [Trusted keys SD card](#trusted-keys)
+
+### Procedure
+
+{{ #include ../../../../tamper-evidence-methods.md:vsbwf-procedure-sealing }}

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

@@ -2,7 +2,10 @@
 # Hardware Models
 
 ## Computers 
-// ANCHOR: models 
+
+* 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)
@@ -10,6 +13,36 @@
 * 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: models
+// 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 
+
+* Sealable See-Through 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: all */

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

@@ -4,7 +4,7 @@
 
 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, purchase food and take breaks.
+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.
 
@@ -12,28 +12,18 @@ The following steps must all be completed under the continued supervision and wi
 
 1. Selecting a Purchase Location
 
-    Select at least 3 stores which carry the type of equipment being purchased, then randomly select one using the roll of a die, or other random method.
+    * 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.
  
-    This is done in order to reduce the likelihood that a threat actor is able to plant a compromised computer in a store.
+        * Each participant should choose 2 of the stores.
 
-2. Within the store, identify available adequate laptops from the list of [tested hardware](#tested-hardware-airgapos-compatibility). Alternatively bring an SD card with AirgapOS, and test booting to it on the device on the store floor before purchasing it.
+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.
+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. At the processing location, one of the individuals is responsible for observing while the other opens the back of the laptop and removes:
+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.
 
-* Radio cards (wifi, bluetooth)
+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. 
-
-* Storage drive
-
-* Speakers
-
-* Microphone
-
-Each laptop model is laid out slightly differently so use an online reference and/or read the names of the components which are found in the laptop to determine which parts to remove.
-
-5. Apply a [tamper proofing](./tamper-evidence-methods.md) method to the device depending on the [device designation](TODO)
 
 ## Tested Hardware (AirgapOS Compatibility)
 
-{{ #include hardware-models.md:models }}
+{{ #include hardware-models.md:computer-models }}

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,16 +6,16 @@ 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.
 
-* Build the software according to the [readme](https://git.distrust.co/public/airgap) in the repository. Use the `make reproduce` command.
+2. Verify the software according to [this](verifying-signatures.md) guide
 
-* Verify the software according to [this](verifying-signatures.md) guide
+3. Flash `airgap.iso` to an SD Card:
-
-* 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
 
@@ -30,12 +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`
 
-* Label the SD card "AirgapOS - <version>"
+5. Label the SD card "AirgapOS - <version>"
 
-* Verify that the hash of `airgap.iso` matches what's flashed on the SD card:
+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`
 
-* Commit the hash of airgap to a git repo, ensuring the commit is signed
+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/repeat-use-airgapos.md

@@ -1,10 +1,11 @@
+/* ANCHOR: all */
 # AirgapOS Setup
 
 This section can be completed on any machine.
 
-AirgapOS has `keyfork` and `icepick` built into it for cryptographic operations such as key
+AirgapOS has `keyfork` and `icepick` built into it for cryptographic operations such as key derivation and signing
-derivation and signing
 
+// ANCHOR: steps
 1. Build the software according to the [readme](https://git.distrust.co/public/airgap) in the repository.Use the `make reproduce` command.
 
 2. Verify the software according to [this guide](verifying-signatures.md)
@@ -42,10 +43,13 @@ derivation and signing
 
 5. Lock the SD card using `sdtool`
 
-5. Make sure to note the `sha256sum` hash of the `airgap.iso` and write it
+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.
+
+// 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,31 @@
+/* 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
+* Get deterministically built binary of `sdtool` from StageX: 
+  * `docker pull stagex/sdtool`
+
+* Extracting binary:
+  * Run docker container: `docker run -p 4000:80 --name sdtool stagex/sdtool`
+    * This will error out the first time, run the command again and then you will get an error that's different that looks like this: `docker: Error response from daemon: Conflict. The container name "/sdtool" is already in use by container "679a52775dfce91f66d8894925449242eacbf4b0aeccaf2effe2c5e213e60a6b". You have to remove (or rename) that container to be able to reuse that name.`. Copy the container ID from the error message and use it in the next command
+    * This issue occurs because of bin/sh missing in the image so we can't run the container properly
+    * 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
+
+* `./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`
+
+// ANCHOR_END: steps
+/* ANCHOR_END: all */