From 98c7efef540b3f081542e12d668223bc194a6502 Mon Sep 17 00:00:00 2001 From: Anton Livaja Date: Sun, 23 Feb 2025 10:08:08 -0500 Subject: [PATCH] reduce number of steps in docs --- quorum-vault-system/src/SUMMARY.md | 14 +++-- .../src/component-documents/git-basics.md | 33 +++------- .../git-repository-initialization.md | 6 -- .../tamper-evidence-methods.md | 2 +- .../approver/approve-transaction.md | 44 +++++-------- .../operator/coins/sol/generate-address.md | 34 ++++------ .../operator/namespace-entropy-ceremony.md | 20 ++---- .../operator/quorum-entropy-ceremony.md | 24 +++---- .../level-2/fixed-location/procurer/index.md | 10 ++- .../procurer/procure-facility.md | 10 --- .../procurer/procure-hardware.md | 4 ++ .../proposer/create-transaction-payload.md | 63 +++++++------------ .../provisioner/provision-computer.md | 10 +-- .../provisioner/provision-sd-card.md | 0 14 files changed, 98 insertions(+), 176 deletions(-) delete mode 100644 quorum-vault-system/src/generated-documents/level-2/fixed-location/provisioner/provision-sd-card.md diff --git a/quorum-vault-system/src/SUMMARY.md b/quorum-vault-system/src/SUMMARY.md index 0e1c931..932523a 100644 --- a/quorum-vault-system/src/SUMMARY.md +++ b/quorum-vault-system/src/SUMMARY.md @@ -29,10 +29,12 @@ * [Transaction Approval](generated-documents/level-2/fixed-location/approver/approve-transaction.md) * [Operator](generated-documents/level-2/fixed-location/operator/index.md) * [Quorum Entropy Ceremony](generated-documents/level-2/fixed-location/operator/quorum-entropy-ceremony.md) - * [Namespace Entropy Ceremony](generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md) * [Ceremony SD Card Provisioning](generated-documents/level-2/fixed-location/operator/ceremony-sd-card-provisioning.md) - * [SOL - Transfer Token](generated-documents/level-2/fixed-location/operator/coins/sol/transfer-token.md) - * [SOL - Generate Address](generated-documents/level-2/fixed-location/operator/coins/sol/generate-address.md) - * [Decrypt Namespace Secret](generated-documents/level-2/fixed-location/operator/decrypt-namespace-secret.md) - * [Encrypt Wallet To Namespace PGP Key](generated-documents/level-2/fixed-location/operator/encrypt-wallet-to-namespace-key.md) - * [Export Namespace Mnemonic](generated-documents/level-2/fixed-location/operator/export-namespace-mnemonic.md) + * [Namespace Operations]() + * [Namespace Entropy Ceremony](generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md) + * [Decrypt Namespace Secret](generated-documents/level-2/fixed-location/operator/decrypt-namespace-secret.md) + * [Encrypt Wallet To Namespace PGP Key](generated-documents/level-2/fixed-location/operator/encrypt-wallet-to-namespace-key.md) + * [Export Namespace Mnemonic](generated-documents/level-2/fixed-location/operator/export-namespace-mnemonic.md) + * [Coins - SOL]() + * [SOL - Generate Address](generated-documents/level-2/fixed-location/operator/coins/sol/generate-address.md) + * [SOL - Transfer Token](generated-documents/level-2/fixed-location/operator/coins/sol/transfer-token.md) diff --git a/quorum-vault-system/src/component-documents/git-basics.md b/quorum-vault-system/src/component-documents/git-basics.md index 367d24a..c7fef55 100644 --- a/quorum-vault-system/src/component-documents/git-basics.md +++ b/quorum-vault-system/src/component-documents/git-basics.md @@ -4,30 +4,15 @@ 1. {{ #include finding-device-name.md:content }} -1. Copy files into designated location in a repository: +1. If the `~/vaults/` repository already exists, ensure it doesn't have any changes that haven't been committed, then remove it using `sudo rm -rf ~/vaults` before re-running the previous step - * e.g `cp -r /media/vaults ~/vaults/` - - * If the `~/vaults/` repository already exists, ensure it doesn't have any changes that haven't been committed, then remove it using `sudo rm -rf ~/vaults` before re-running the previous step - -1. Change directory to `vaults` - - * `cd ~/vaults` - -1. Add all files to git stage: - - * `git add .` - -1. Review what files are staged: - - * `git status` - -1. Create a signed commit: - - * `git commit -m -S ""` - -1. Push the changes to the branch you are on: - - * `git push origin HEAD` +1. Copy the repository with updated files to an online machine, sign, commit and push to the `vaults` repository: + ``` + $ cp -r /media/vaults ~/vaults/ + $ cd ~/vaults + $ git add . + $ git commit -m -S "" + $ git push origin HEAD + ``` // ANCHOR_END: content /* ANCHOR_END: all */ \ No newline at end of file diff --git a/quorum-vault-system/src/component-documents/git-repository-initialization.md b/quorum-vault-system/src/component-documents/git-repository-initialization.md index b36ad03..e017a50 100644 --- a/quorum-vault-system/src/component-documents/git-repository-initialization.md +++ b/quorum-vault-system/src/component-documents/git-repository-initialization.md @@ -11,12 +11,6 @@ Git is used because it permits cryptographic singing of commits using PGP, as we 1. Set appropriate permissions to limit who can write to the repository. - * `main` branch should be write protected so that merges to that branch can only be done if at least 2 approvals are present - - * The organization may choose to require more approvals based on risk tolerance and operational capacity - - * The merges should be done via CLI signed commits - * Require that all commits are signed using well known PGP keys 1. Optionally set up a chron job that periodically pulls the data from the repository as a backup. diff --git a/quorum-vault-system/src/component-documents/tamper-evidence-methods.md b/quorum-vault-system/src/component-documents/tamper-evidence-methods.md index 7d0ccde..8d6dd92 100644 --- a/quorum-vault-system/src/component-documents/tamper-evidence-methods.md +++ b/quorum-vault-system/src/component-documents/tamper-evidence-methods.md @@ -116,7 +116,7 @@ Sealing bags of standard size objects which need to be protected can fit in. The 1. Insert object(s) into plastic bag -1. Fill bag with enough plastic beads that all of the object is surrounded +1. Fill bag with enough plastic beads that most of the object is surrounded 1. Use vacuum sealer to remove air from the bag until the beads are no longer able to move diff --git a/quorum-vault-system/src/generated-documents/level-2/fixed-location/approver/approve-transaction.md b/quorum-vault-system/src/generated-documents/level-2/fixed-location/approver/approve-transaction.md index 5779ed7..443361f 100644 --- a/quorum-vault-system/src/generated-documents/level-2/fixed-location/approver/approve-transaction.md +++ b/quorum-vault-system/src/generated-documents/level-2/fixed-location/approver/approve-transaction.md @@ -46,14 +46,11 @@ The approver is responsible for verifying a transaction proposed by a [proposer] 1. {{ #include ../../../../component-documents/finding-device-name.md:content }} -1. Copy the git repo locally from the Ceremony SD card - - * `cp -r /media/vaults /root/vaults` - -1. Change directory to vaults - - * `cd /root/vaults` - +1. Copy the git repo locally from the Ceremony SD card and change into it + ``` + $ cp -r /media/vaults /root/vaults + $ cd /root/vaults + ``` 1. Plug in the Operator smart card 1. Verify the existing signatures and add your own signature: @@ -72,26 +69,17 @@ The approver is responsible for verifying a transaction proposed by a [proposer] 1. {{ #include ../../../../component-documents/finding-device-name.md:content }} -1. Copy the updated repository locally: - - * `cp -r /media/vaults ~/` - -1. Change into locally copied directory - - * `cd ~/vaults` - -1. Stage the modified file: - - * `git add /ceremonies//payloads/*` - -1. Create a signed git commit: - - * `git commit -S -m "add payload signature for payload_.json"` - -1. Push the latest commit to the repository - - * `git push origin main` - +1. Copy the updated repository locally and change into it: + ``` + $ cp -r /media/vaults ~/ + $ cd ~/vaults + ``` +1. Stage, sign, commit and push changes to the ceremonies repository: + ``` + $ git add /ceremonies//payloads/* + $ git commit -S -m "add payload signature for payload_.json" + $ git push origin main + ``` 1. Tamper proof the AirgapOS and Air-gapped laptop {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}} diff --git a/quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/coins/sol/generate-address.md b/quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/coins/sol/generate-address.md index 85cabc1..5a3dafe 100644 --- a/quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/coins/sol/generate-address.md +++ b/quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/coins/sol/generate-address.md @@ -36,13 +36,11 @@ 1. Retrieve Ceremony SD card from High Visibility Storage and plug it into the air-gapped machine -1. Copy the `vaults` repository to the machine - - * `cp -r /media/vaults /root/` - -1. Change directory to `vaults`: - - * `cd /root/vaults` +1. Copy the `vaults` repository to the machine and switch to it + ``` + $ cp -r /media/vaults /root/ + $ cd /root/vaults + ``` 1. Start Keyfork using the relevant Shardfile: @@ -158,22 +156,12 @@ * Once the airdrop is done, nonce account will be created -1. Add all files to git stage: - - * `git add .` - -1. Review what files are staged: - - * `git status` - -1. Create a signed commit: - - * `git commit -m -S ""` - -1. Push the changes to the branch you are on: - - * `git push origin HEAD` - +1. Stage, commit, sign and push the changes: + ``` + $ git add . + $ git commit -m -S "" + $ git push origin HEAD + ``` ### Sealing 1. Gather all the original items that were in the air-gapped bundle: diff --git a/quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md b/quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md index 8a981d1..02babe1 100644 --- a/quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md +++ b/quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md @@ -32,20 +32,12 @@ This is a ceremony for generating and sharding entropy to a set of existing Quor 1. Plug in the Ceremony SD card - 1. Back up the `shardfile.asc` - - * `cp shardfile.asc /media/vaults//` - - 1. TODO - NOT IMPLEMENTED: - - * Back up the root OpenPGP certificate - - * `cp encryption_certificate.asc /media/vaults//` - - 1. Copy the contents of Ceremony SD card to machine - - * `cp -r /media/vaults /root/` - +1. Back up the files + ``` + $ cp shardfile.asc /media/vaults// + TODO (NOT IMPLEMENTED): $ cp encryption_certificate.asc /media/vaults// + $ cp -r /media/vaults /root/ + ``` 1. To create additional backups of the updated `vaults` repository, plug in SD cards one at a time and use following steps to back up ceremony artifacts 1. Plug in fresh SD card diff --git a/quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/quorum-entropy-ceremony.md b/quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/quorum-entropy-ceremony.md index 8d5e34e..09eb6bc 100644 --- a/quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/quorum-entropy-ceremony.md +++ b/quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/quorum-entropy-ceremony.md @@ -35,23 +35,13 @@ This is a ceremony for generating entropy which is used to derive Quorum PGP key 1. Plug in the Ceremony SD card - 1. Back up the `shardfile.asc` - - * `cp shardfile.asc /media/vaults//` - - 1. Back up the `keyring.asc` - - * `cp keyring.asc /media/vaults//` - - 1. TODO - NOT IMPLEMENTED: - - * Back up the root OpenPGP certificate - - * `cp encryption_cert.asc /media/vaults//` - - 1. Copy the contents of Ceremony SD card to machine - - * `cp -r /media/vaults /root/` +1. Back up the files + ``` + $ cp shardfile.asc /media/vaults// + $ cp keyring.asc /media/vaults// + TODO (NOT IMPLEMENTED): $ cp encryption_cert.asc /media/vaults// + $ cp -r /media/vaults /root/ + ``` 1. To create additional backups of the updated `vaults` repository, plug in SD cards one at a time and use following steps to back up ceremony artifacts diff --git a/quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/index.md b/quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/index.md index 360807f..09bb1bc 100644 --- a/quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/index.md +++ b/quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/index.md @@ -12,8 +12,6 @@ The procurer is responsible for: * Ensuring equipment is properly tamper proofed -* Maintaining stock of supplies in the inventory - * Minimizing hardware supply chain security risks ## Order of Operations @@ -28,4 +26,10 @@ The procurer is responsible for: 1. Procuring [hardware](./procure-hardware.md) -1. Procuring [SD cards](./procure-sd-card-pack.md) \ No newline at end of file + * Laptops + + * SD cards + + * SD card USB adapters + + * Smart cards diff --git a/quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/procure-facility.md b/quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/procure-facility.md index ace56d3..4345ee1 100644 --- a/quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/procure-facility.md +++ b/quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/procure-facility.md @@ -7,13 +7,3 @@ 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 - -## Maintenance - -* The facility should always be well stocked with SD cards - -* 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 \ No newline at end of file diff --git a/quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/procure-hardware.md b/quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/procure-hardware.md index 59f757e..01e6317 100644 --- a/quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/procure-hardware.md +++ b/quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/procure-hardware.md @@ -14,6 +14,10 @@ ## Procedure: Online Procurement +1. Select a well known and reputable supplier. Establishing a relationship with a hardware supplier that has a reputation for privacy, supply chain security is preferred. + +2. Order the supplies to a registered mailbox, to prevent exposing your organization's location + ## Tamper Proofing All hardware: diff --git a/quorum-vault-system/src/generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md b/quorum-vault-system/src/generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md index 1e73465..d39fed9 100644 --- a/quorum-vault-system/src/generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md +++ b/quorum-vault-system/src/generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md @@ -38,14 +38,11 @@ The proposer must combine these values into a JSON file, such as: 1. Turn on online machine -1. Clone the repository if it's not available locally: - - * `git clone ` - -1. Pull the latest changes from the `ceremonies` repository - - * `git pull origin main` - +1. Clone the `vaults` repository if it's not available locally and get the latest changes: + ``` + $ git clone + $ git pull origin main + ``` 1. Unseal the SD Card Pack {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing}} @@ -66,19 +63,15 @@ The proposer must combine these values into a JSON file, such as: 1. Insert the AirgapOS SD card into the airgapped machine and turn it on -1. Once booted, unplug the AirgapOS SD card +1. Once booted, unplug the AirgapOS SD card and place it in High Visibility Storage 1. Plug in the Ceremony SD card - -1. Copy the git repo locally from the Ceremony SD card - - * `cp -r /media/vaults /root` - -1. Change into the vaults directory: - - * `cd /root/vaults` - +1. Copy the git repo locally from the Ceremony SD card and change to it + ``` + $ cp -r /media/vaults /root + $ cd /root/vaults + ``` 1. Create a new payloads directory in the `vaults` repository for the date on which the ceremony for the transaction will take place if it doesn't already exist * `mkdir -p /ceremonies//payloads` @@ -101,31 +94,21 @@ The proposer must combine these values into a JSON file, such as: * `cp -r /root/vaults /media` -1. Unplug the SD card from the air-gapped machine - -1. Plug in the SD card into the online machine +1. Transfer the SD card from the air-gapped machine to the online machine 1. {{ #include ../../../../component-documents/finding-device-name.md:content }} -1. Copy the updated repository locally: - - * `cp -r /media/vaults ~/` - -1. Change into locally copied directory - - * `cd ~/vaults` - -1. Stage the modified file: - - * `git add /ceremonies//payloads/*` - -1. Create a signed git commit: - - * `git commit -S -m "add payload signature for payload_.json"` - -1. Push the latest commit to the repository - - * `git push origin main` +1. Copy the updated repository locally and switch to it: + ``` + $ cp -r /media/vaults ~/ + $ cd ~/vaults + ``` +1. Stage, sign, commit and push the changes to the ceremonies repository: + ``` + $ git add /ceremonies//payloads/* + $ git commit -S -m "add payload signature for payload_.json" + $ git push origin main + ``` 1. 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. diff --git a/quorum-vault-system/src/generated-documents/level-2/fixed-location/provisioner/provision-computer.md b/quorum-vault-system/src/generated-documents/level-2/fixed-location/provisioner/provision-computer.md index 9ef275f..f83362b 100644 --- a/quorum-vault-system/src/generated-documents/level-2/fixed-location/provisioner/provision-computer.md +++ b/quorum-vault-system/src/generated-documents/level-2/fixed-location/provisioner/provision-computer.md @@ -10,14 +10,16 @@ ## Procedure +1. Unseal a tamper proofed laptop + {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing }} -1. Follow a given model manual to remove all radio cards, storage drive, speakers, and microphone using standard industry laptop repair tactics +1. Remove all radio cards, storage drive, speakers, and microphone using standard industry laptop repair tactics {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing }} -1. Apply a new label which indicates the laptop has been provisioned +1. Apply a new label which indicates the laptop has been provisioned (include date, and any other desired metadata such as a unique ID (e.g Laptop #4)) -1. Return the provisioned laptop to inventory +1. Place the provisioned laptop in inventory -1. Update inventory to reflect that this hardware has ben provisioned \ No newline at end of file +1. Update inventory to reflect that this hardware has been provisioned, and including the metadata in the `description.txt` for that item according to the [inventory repository structure](../procurer/create-inventory-repository.md) \ No newline at end of file diff --git a/quorum-vault-system/src/generated-documents/level-2/fixed-location/provisioner/provision-sd-card.md b/quorum-vault-system/src/generated-documents/level-2/fixed-location/provisioner/provision-sd-card.md deleted file mode 100644 index e69de29..0000000