wip for end-to-end generated docs

quorum-key-management/src/SUMMARY.md

@@ -55,3 +55,19 @@
 * [Lifecycle Management]()
     * [Destroying Hardware](hardware-destruction.md)
     * [Storage Device Management](storage-device-management.md)
+
+* [Generated Documents]()
+    * [Level 1]()
+    * [Level 2]()
+        * [Fixed-Location]()
+            * [Provisioner](system-roles.md)
+                * [Hardware](generated-documents/level-2/fixed-location/provisioner/procure-hardware.md)
+                * [Location]()
+            * [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]()

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,148 @@
+# NOT PRODUCTION READY
+
+# Operator - Sign PYTH-SPL Transaction
+
+Solana blockchain has a time sensitive aspect associated to validity of standard transactions. The `blockhash` which is used as part of a transaction expires in 60-90 seconds. This introduces operational challenges to signing a transaction offline. As a result, this ceremony requires 3 operators, rather than the typical 2. It is essential for the operators to collaborate to quickly get the transaction data from the online computer to the offline, sign it, then get it back to the online machine before the `blockhash` validity period expires.
+
+The online machine operator is only to operate the online machine, and not touch the offline machine, and the air-gapped machine operators should not touch the online machine. The operators must focus on their machine and their part of the process.
+
+Typically, the online machine and the additional operator are not necessary as there is no time sensitivity to the transaction as only some blockchains have the requirement of using a `blockhash` from a previous block as part of a new valid transaction.
+
+## Requirements
+
+* 3 Operators
+
+    * 2 primary operators will be operating the offline machine
+
+        * Ensure both primary operators have their [Operator Keys](../../../../../../glossary.md#operator-key)
+
+    * An additional operator is necessary for fetching and providing the transaction data and the latest SOL `blockhash` from a online computer and transmitting using an SD card to the 2 primary operators conducting the main ceremony
+
+* Photographic tamper proofing evidence
+
+    * 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
+
+* Ensure location has [tamper proofing tools](../../../../../../tamper-evidence-methods.md#vacuum-sealed-bags-with-filler)
+
+    * Vacuum sealer
+
+    * Vacuum roll
+
+    * Colored beads
+
+* 4 SD cards (2 fresh, formatted as ext4, and 2 cards with prepared data)
+
+    * 1 SD card for transferring transaction data from online to air-gapped machine
+
+    * 1 SD card for storing tamper proofing evidence produced at the end of the ceremony
+
+    * 1 SD card which has the shardfile and "trusted keys" for proposers and approvers, both signed by each operator using their operator key (TODO)
+
+        * This should be write-locked and stored in tamper proofing along with air-gapped machine
+
+            * TODO refactor for this to be alongside airgapped machine
+
+    * 1 SD card with AirgapOS
+
+* Digital camera (TODO selection)
+
+* [Online machine](../../../../../../online-machine-provisioning.md) used for fetching transaction data
+
+## 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
+
+{{ #include ../../../../../../secure-boot-sequence.md:content}}
+
+0. Load well known PGP keys of proposer and approver, and sign them using operator keys (NOT IMPLEMENTED)
+
+1. Insert SD card with shardfile
+
+2. `keyfork recover shard --daemon`
+
+3. Await prompt and plug in first Operator Key
+
+4. Tap the key (may have to tap multiple times)
+
+5. Await prompt and plug in second Operator Key
+
+6. Tap the key
+
+7. Run `keyfork
+
+8. As a last step, run the `icepick` command which is awaiting the transaction payload
+
+    * TODO add command
+
+### 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-get-blockhash-and-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. Use `icepick` to generate the transaction payload:
+
+    * `icepick workflow sol-transfer-token`
+
+        * Wait for SD card prompt and plug in SD card with signed 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,28 @@
+# 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, BTC etc.)
+
+* FROM address
+
+* TO address
+
+* Amount
+
+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.
+
+```json
+{
+    "from-address": "<address>",
+    "to-address": "<address>",
+    "token-name": "<name>",
+    "token-amount": "<amount>"
+}
+```
+
+To sign use the command:
+
+`gpg --clearsign <filename>`

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

@@ -0,0 +1,27 @@
+# Provisioner - Procure Hardware
+
+The provisioner is responsible for procuring equipment. Their main focus is:
+
+* Minimizing hardware supply chain security risks
+
+* Ensuring availability of necessary equipment
+
+## Laptops
+
+### Air-Gapped Machine
+
+[Guide](../../../../hardware.md#air-gapped-computer)
+
+### Online Machine
+
+[Guide](../../../../online-machine-provisioning.md)
+
+## Tamper Proofing Equipment
+
+[Guide](../../../../tamper-evidence-methods.md#vacuum-sealed-bags-with-filler)
+
+* Vacuum Sealer
+
+* Vacuum sealer roll
+
+* Colored beads

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/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.
 
@@ -41,3 +43,6 @@ be restarted.
 
 18. Once booted, verify the version of the software matches the AirgapOS Hash
 which was noted during the [AirgapOS Setup](repeat-use-airgapos.md).
+// ANCHOR_END: content
+
+/* ANCHOR_END: all */

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

@@ -124,11 +124,14 @@ Sealing bags of standard size objects which need to be protected can fit in. The
 #### Unsealing
 // ANCHOR: vsbwf-procedure-unsealing
 
-1. Retrieve photographs which were taken of the sealed object and print them out, one copy for each operator
+1. Retrieve photographs of the top and the bottom of the object which were taken of the sealed object
 
-2. Use the photographs and compare them to the sealed object, ensuring the arrangement of the filler in the sealed bag is the same on both sides of the 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).
 
-3. If there is no noticeable difference, proceed with unsealing the object, otherwise initiate an incident response process.
 // ANCHOR_END: vsbwf-procedure-unsealing
 
 // ANCHOR_END: vsbwf-procedure
@@ -156,6 +159,8 @@ Glitter can be used as an additional control to provide tamper evidence on speci
 
 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.